# 0. 문서 상태
- 상태: draft
- 승인자: 고진환
- 승인 시각: {{CONFIRM: 승인 후 기재}}

# 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 단계 전달 체크
- [x] 구현 범위가 설계 문서와 연결됨
- [x] 작업 단위별 검증 방법이 정의됨
- [x] 영향 파일과 의존성 점검 결과가 기록됨
- [x] Verification에 전달할 실행/검증 근거가 정의됨
- [ ] 최종 승인
  - {{CONFIRM: Implementation 초안 승인 여부를 확인하라}}

# 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. 사용자 결정 필요 항목 요약
## {{CONFIRM}} (2건)
- 승인 후 기재 (위치: #0)
- Implementation 초안 승인 여부를 확인하라. (위치: #7)

## {{DATA}}
- 현재 미해결 플레이스홀더 없음