portfolio-hub/docs/sdlc/implementation/imp-001_2026-04-15_cli-bot-token-lifecycle-cli.implementation.md

0. 문서 상태

• 상태: confirmed
• 승인자: 고진환
• 승인 시각: 2026-04-15

1. Implementation 개요

• 입력 Design: dsn-001
• 목적: CLI bot 토큰 발급/삭제 기능을 설계 기준에 따라 작은 구현 단위로 분해하고, Verification 단계에 즉시 전달 가능한 검증 근거를 준비한다.
• 이번 구현 우선순위 작업:
  • 1순위: P-002 만기 정책 및 권한 가드 구현
  • 2순위: P-003 토큰 출력 마스킹 및 감사 로그 구현
  • 3순위: P-001 CLI bot 토큰 발급/삭제 명령 추가

2. 이번 구현 범위

In Scope

• bot token issue, bot token revoke CLI 명령 추가 및 help 노출
• --ttl-days/--no-expiry 입력 검증(상호배타, 값 범위)과 서비스 계층 정책 재검증
• 기본 TTL 365일 정책 반영 및 비관리자 무기한 토큰 금지
• issue/revoke 결과의 마스킹 출력 처리 및 감사 로그 기록 경로 구현
• revoke 확인 프롬프트/--force 분기와 표준 출력(table/json) 정합성 반영
• 정상/예외 테스트 및 문서 동기화 반영

Out of Scope

• bot token list/rotate 등 신규 명령 확장
• 감사 로그 저장소 아키텍처 재설계(외부 로그 파이프라인 교체 포함)
• API 채널의 대규모 인터페이스 재정의

3. 작업 단위 분해

Impl ID	작업명	연결 설계/AC	변경 유형	우선순위	상태
I-001	bot 토큰 CLI 그룹/서브커맨드 골격 추가	P-001 AC-1	코드(명령 라우팅)	High	완료
I-002	issue 입력 옵션 검증(상호배타/범위)	P-002 AC-3	코드(입력 검증)	High	완료
I-003	만기 정책 서비스 재검증 및 기본 TTL 365일 적용	P-002 AC-1, AC-2	코드(도메인/서비스)	High	완료
I-004	issue/revoke 서비스 호출 및 결과 DTO 정규화	P-001 AC-2, AC-3	코드(서비스 통합)	High	완료
I-005	토큰 출력 마스킹 정책 적용(원문 1회 출력 후 차단)	P-003 AC-1, AC-3	코드(출력/보안)	High	완료
I-006	감사 로그 이벤트 기록 및 실패 분기 처리	P-003 AC-2	코드(로깅/오류 처리)	Medium	완료
I-007	revoke UX 가드(확인 프롬프트, --force, 오류 메시지)	P-004 AC-1, AC-2	코드(UX/CLI)	Medium	완료
I-008	테스트/문서 동기화 및 근거 번들 준비	P-005 AC-1/AC-2	테스트+문서	High	완료

4. 파일 변경 계획

Impl ID	대상 파일	변경 목적	변경 종류(생성/수정)	상태
I-001	app/cli/main.py	bot 그룹 등록 및 커맨드 엔트리 연결	수정	완료
I-001	app/cli/commands/bot_tokens.py	token issue/revoke 커맨드 골격 정의	생성	완료
I-002	app/cli/commands/bot_tokens.py	--ttl-days/--no-expiry 검증 로직 추가	수정	완료
I-003	app/services/auth_service.py	만기 정책 재검증, 기본 TTL/권한 정책 강제	수정	완료
I-003	app/domain/services.py	정책 객체 정규화 규칙 보완(필요 시)	수정	완료
I-004	app/services/auth_service.py	issue/revoke 결과 DTO 필드 정규화	수정	완료
I-004	app/schemas/auth.py	응답 스키마(token_id/expires_at/revoked) 정렬	수정	완료
I-005	app/cli/core/output.py	table/json 출력 시 마스킹 렌더링 추가	수정	완료
I-006	app/core/security.py	감사 로그 payload 표준화 및 민감정보 필터링	수정	완료
I-006	app/repositories/postgres.py	감사 로그 쓰기 경로(트랜잭션 연계) 보강	수정	완료
I-007	app/cli/commands/bot_tokens.py	revoke 확인 프롬프트, --force 분기, 사용자 지침 메시지	수정	완료
I-008	tests/test_cli.py	bot token help/성공/취소 흐름 테스트 추가	수정	완료
I-008	tests/test_auth.py	정책 검증(관리자/비관리자/no-expiry) 테스트 추가	수정	완료
I-008	tests/test_app.py	출력 마스킹 및 보안 회귀 시나리오 보강	수정	완료
I-008	README.md	CLI 사용 예시 및 정책 제약 문서화	수정	완료
I-008	docs/technical/auth-and-token-lifecycle.md	토큰 수명주기/감사 로그 동작 반영	수정	완료

5. 테스트/검증 계획

Impl ID	검증 방법	성공 기준	근거
I-001	CLI help 테스트	bot token issue/revoke가 help에 노출된다	tests/test_cli.py
I-002	옵션 조합 예외 테스트	--ttl-days와 --no-expiry 동시 입력 시 실패한다	tests/test_auth.py
I-003	권한/기본값 테스트	기본 TTL 365일, 비관리자 --no-expiry 차단	tests/test_auth.py
I-004	성공 경로 통합 테스트	issue 응답에 token_id/expires_at/revoked가 존재한다	tests/test_cli.py
I-005	출력 스냅샷/회귀 테스트	재출력/로그에 raw token이 노출되지 않는다	tests/test_app.py
I-006	감사 로그 실패 분기 테스트	issue는 롤백 실패 처리, revoke는 폐기 유지+경고를 만족한다	tests/test_auth.py
I-007	UX 동작 테스트	revoke 시 확인 프롬프트, --force 시 생략, 취소는 code 0	tests/test_cli.py
I-008	회귀+문서 동기화 확인	변경 경로 테스트 통과 및 문서 업데이트 반영	테스트 실행 로그 + 변경 문서 diff

6. 영향도 및 의존성 점검

항목	영향 내용	대응 방안
코드	CLI 진입점, 인증 서비스, 출력/로깅 경로가 동시에 변경되어 회귀 범위가 넓다	단위+통합 테스트를 분리 실행하고 민감정보 노출 회귀 테스트를 추가한다
문서	CLI 사용법과 토큰 수명주기 운영 규칙이 불일치할 수 있다	README/기술문서를 같은 변경 세트에서 동기 갱신한다
설정/의존성	로그 sink/DB 쓰기 실패 시 issue/revoke 실패 정책이 다르므로 운영 혼선 위험이 있다	실패 분기 정책을 테스트로 고정하고 운영 경고 기준을 문서에 명시한다

7. Verification 단계 전달 체크

• 구현 범위가 설계 문서와 연결됨
• 작업 단위별 검증 방법이 정의됨
• 영향 파일과 의존성 점검 결과가 기록됨
• Verification에 전달할 실행/검증 근거가 정의됨
• 최종 승인

8. 파일 처리 결과

• 생성 경로: app/cli/commands/bot_tokens.py
• 생성 경로: app/cli/core/output.py
• 수정 경로: app/cli/main.py
• 수정 경로: app/services/auth_service.py
• 수정 경로: app/domain/services.py
• 수정 경로: app/schemas/auth.py
• 수정 경로: app/core/security.py
• 수정 경로: app/repositories/postgres.py
• 수정 경로: tests/test_cli.py
• 수정 경로: tests/test_auth.py
• 수정 경로: tests/test_app.py
• 수정 경로: README.md
• 수정 경로: docs/technical/auth-and-token-lifecycle.md
• 수정 경로: docs/sdlc/implementation/imp-001_2026-04-15_cli-bot-token-lifecycle-cli.implementation.md

9. 사용자 결정 필요 항목 요약

현재 미해결 플레이스홀더 없음