sdlc 정리

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/1_discovery.md

@@ -0,0 +1,109 @@
+# 0. 문서 상태
+- 상태: confirmed
+- 승인자: Justin
+- 승인 시각: 2026-04-14
+
+# 1. 계획 상태 요약
+- Discovery 문서 현황: 본 문서가 첫 Discovery 초안이다.
+- Planning 점수 파일 현황: docs/sdlc/planning/planning-backlog-scores.out.csv (존재하지 않음)
+- 해석: CLI에서 봇 토큰 발급/삭제를 지원하기 위한 요구사항 정의가 우선이며, Planning 단계에서 만기 정책과 우선순위 점수화를 확정해야 한다.
+
+# 2. 요구사항 판정 결과 (완전 중복/유사/신규 + 근거)
+- 판정: 신규
+- 근거
+  - docs/sdlc/discovery/ 경로에 기존 Discovery 문서가 없어 완전 중복/유사 판정을 수행할 대상이 없다.
+  - 현재 저장소의 CLI는 user/portfolio/strategy 중심이며, bot 토큰 발급/삭제를 직접 수행하는 CLI 커맨드가 없다.
+
+# 3. 문제점의 요약
+- 현재 상태
+  - 인증 API는 봇/봇 토큰 기능을 제공하지만, 운영자가 CLI만으로 봇 토큰 발급/삭제를 실행할 수 없다.
+  - 자동화 스크립트에서 API 직접 호출 의존이 발생해 운영 절차 일관성이 낮다.
+- 기대 상태
+  - CLI에서 특정 사용자(또는 사용자 소유 봇)에 대해 봇 토큰 발급/삭제를 일관된 명령으로 처리할 수 있어야 한다.
+  - 토큰 만기 설정 정책은 선택 입력으로 하되, 미입력 시 기본 TTL 365일을 적용하고 운영상 필요 시 `--no-expiry` 옵션으로 무기한 발급을 허용해야 한다.
+- 이해관계자
+  - 운영자(관리자 권한 사용자): 봇 토큰 발급/폐기의 실행 주체.
+  - 자동화/배포 담당자: 스크립트 기반 토큰 라이프사이클 관리 필요.
+  - 보안/승인 책임자: 토큰 만기 정책과 최소 권한 정책 승인 필요.
+- 제약사항
+  - 기존 권한 모델(admin/read/trade-write) 및 auth 서비스 계약과 호환되어야 한다.
+  - 기존 CLI UX 패턴(확인 프롬프트, --force, 출력 포맷 table/json)을 유지해야 한다.
+  - 저장소의 문서 동기화 규칙에 따라 API/CLI 계약 변경 시 기술 문서 업데이트가 필요하다.
+
+# 4. 이번에 만들 기능 1개
+- CLI에서 봇 토큰 발급/삭제 기능을 제공하고, 토큰 만기 정책(필수/기본값)을 명시적으로 처리한다.
+
+# 5. 요구사항 목록
+## 기능 요구사항
+- FR-1: 관리자는 CLI에서 봇 토큰을 발급할 수 있어야 한다 (대상 bot 식별자 지정 필수).
+- FR-2: 관리자는 CLI에서 봇 토큰을 삭제(폐기)할 수 있어야 한다 (대상 token 식별자 지정 필수).
+- FR-3: 발급 시 만기 정책을 입력 또는 기본값으로 처리해야 하며, 기본값은 365일 TTL이고 명시적 `--no-expiry` 지정 시에만 무기한 발급을 허용해야 한다.
+- FR-4: 발급/삭제 명령은 기존 쓰기 명령과 동일하게 확인 프롬프트를 제공하고, --force 시 프롬프트를 생략해야 한다.
+- FR-5: 명령 결과는 기존 CLI 포맷 정책(table/json)으로 출력되어야 하며, token_id, expires_at, revoked 상태를 포함해야 한다.
+
+## 비기능 요구사항
+- NFR-1: 보안 - 토큰 원문은 발급 시 1회만 노출하고, 이후 조회/출력 시 앞 6자/뒤 4자만 노출하는 마스킹 정책을 따른다.
+- NFR-2: 감사추적 - 발급/삭제 행위에 대해 실행자, 대상 bot_id, 시각, 결과를 로그로 남겨야 한다.
+- NFR-3: 사용성 - 기존 CLI 하위 명령 체계와 일관된 help 텍스트/옵션명을 유지해야 한다.
+- NFR-4: 신뢰성 - 잘못된 bot_id/token_id 입력 시 비정상 종료 대신 명확한 오류 메시지와 종료 코드를 제공해야 한다.
+
+## 범위 경계
+- In Scope
+  - CLI에 bot 토큰 발급/삭제 명령 추가.
+  - 만기 입력 옵션 및 기본 TTL 연동.
+  - 확인 프롬프트/--force/출력 포맷 일관화.
+  - 관련 기술 문서(API/CLI 계약) 업데이트.
+- Out of Scope
+  - 토큰 암호화 저장 구조 전면 재설계.
+  - 다중 사용자 셀프서비스 포털 UI 제공.
+  - 외부 IAM 연동(OAuth/OIDC 등) 추가.
+
+# 6. 리스크/가정 목록
+## 리스크
+- R-1 (High): 만기 정책이 모호하면 무기한 토큰 발급으로 보안 리스크가 커질 수 있다.
+  - 완화 방안: 기본 TTL 상한을 365일로 강제하고, 무기한 발급은 명시적 `--no-expiry` 옵션과 관리자 권한에서만 허용하며 감사 로그를 남긴다.
+- R-2 (Medium): CLI 명령 체계 확장 시 기존 명령 네이밍과 충돌하여 운영자가 오사용할 수 있다.
+  - 완화 방안: 기존 command group 패턴에 맞춰 bot 하위 명령을 도입하고 --help 예시를 README에 추가한다.
+- R-3 (Medium): 토큰 출력 정책이 미정이면 로그/스크린샷을 통한 민감정보 유출 가능성이 있다.
+  - 완화 방안: 발급 직후 1회 노출 정책과 마스킹 정책을 적용하고 운영 가이드에 비노출 원칙을 명시한다.
+
+## 가정
+- A-1: 봇/봇토큰 관련 API 및 서비스 계층은 이미 존재하며 CLI는 이를 호출하는 어댑터 역할로 구현 가능하다.
+- A-2: 운영 환경에서 bot 토큰 발급/폐기 실행 권한은 admin으로 제한된다.
+
+# 7. 초기 성공 기준
+- S-1: 관리자가 CLI로 bot 토큰 발급/삭제를 수행할 수 있다.
+- S-2: 만기 정책(필수 또는 기본 TTL)이 문서와 구현에서 일치한다.
+- S-3: 발급/삭제 명령의 정상/예외 경로 검증 증거가 Verification에 제출된다.
+
+## 측정 방식 및 데이터 출처
+- S-1 측정 방식: 통합 테스트 또는 수동 E2E 시나리오에서 발급 후 토큰 사용 가능, 삭제 후 사용 불가 확인 / 데이터 출처: CLI 실행 로그, API 응답 로그.
+- S-2 측정 방식: 만기 입력 유무별 테스트 케이스 통과 여부 확인 / 데이터 출처: 테스트 리포트, 설정값(.env) 및 문서 diff.
+- S-3 측정 방식: 정상 1건 + 예외 1건 이상 테스트 증적 첨부 여부 확인 / 데이터 출처: pytest 결과, Verification 문서.
+
+# 8. Planning으로 넘기기 전 확인 체크
+- Planning 시작 시점은 보류.
+- [x] 범위(In Scope/Out of Scope) 확정
+  - 기준: 본 문서 #5 범위 경계에 포함/제외 항목이 명시되어 있다.
+- [x] 성공 지표의 측정 방식/데이터 출처 확정
+  - 운영 지표 수집 채널: "운영자는 CLI 실행 결과를 터미널 출력으로 직접 확인하며, 별도 중앙 로그/대시보드는 없음. 추후 자동화/감사 필요 시 /var/log/portfoliohub/cli.log에 기록 예정."
+- [x] High 영향 플레이스홀더 우선순위 및 해소 책임자 지정
+  - 기준: [x] 미해결 High 영향 플레이스홀더 없음
+- [x] 승인자 확정
+  - 기준: 승인자가 Justin으로 명시되어 있다.
+
+# 9. 파일 처리 결과 (생성/미생성 경로)
+- 처리 결과: 신규 생성
+- 생성 경로: docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.discovery.md
+- 재검토: Planning 이전에 운영 지표 수집 채널 확정 필요
+- 참조 문서: 없음
+
+# 10. 사용자 결정 필요 항목 요약
+## {{DECIDE}}
+- 없음
+
+## {{CONFIRM}}
+- 승인 시각 기재.
+
+## {{DATA}}
+- 없음

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/2_planning.md

@@ -0,0 +1,98 @@
+# 0. 문서 상태
+- 상태: confirmed
+- 승인자: Justin
+- 승인 시각: 2026-04-14
+
+# 1. Planning 개요
+- 입력 Discovery: dcy-001
+- 목적: CLI에서 bot 토큰 발급/삭제 기능을 우선순위 기반 작업으로 분해하고 Design 단계 전달 가능한 AC를 확정한다.
+- 우선순위 방법: WSJF
+- 점수 스케일: Business Value/Time Criticality/RR-OE/Job Size 모두 1~10
+
+# 2. 이번 반복 범위 경계
+## In Scope
+- CLI `bot` 하위 명령에 토큰 발급/삭제 기능 추가
+- 만기 정책 반영(기본 TTL 365일, `--no-expiry` 옵션 처리)
+- 토큰 출력 마스킹(앞 6자/뒤 4자) 및 감사 로그 반영
+- 확인 프롬프트/`--force`/출력 포맷(`table`/`json`) 일관화
+- 테스트(정상/예외) 및 기술 문서 동기화
+
+## Out of Scope
+- 토큰 저장 구조 전면 재설계
+- UI/포털 제공
+- 외부 IAM(OAuth/OIDC) 연동
+
+## 운영/보안 정책
+- 운영 정책: 터미널 접근은 오직 관리자만 접근 가능하며 일반 유저는 터미널 사용이 불가하다. 따라서 CLI 사용은 관리자 행위로 간주하며, 관리자만 터미널 접근 및 CLI 실행 권한을 가진다.
+- 보안 정책: `--no-expiry` 옵션은 관리자 전용 운영 정책 하에서만 허용된다.
+
+# 3. 백로그 작업 분해
+| Item ID | Work Item | 연결 요구사항 | 연결 리스크 | 담당 |
+|---|---|---|---|---|
+| P-002 | 만기 정책 및 권한 가드 구현 (`--no-expiry`, TTL 기본 365일, 관리자 전용 정책) | FR-3, NFR-4 | R-1 | Builder |
+| P-003 | 토큰 출력 마스킹 및 감사 로그 구현 | NFR-1, NFR-2 | R-1, R-3 | Builder |
+| P-001 | CLI bot 토큰 발급/삭제 명령 추가 | FR-1, FR-2, FR-4, FR-5 | R-2 | Builder |
+| P-004 | CLI UX 정합성 보강(확인 프롬프트, `--force`, 오류 메시지) | FR-4, NFR-3, NFR-4 | R-2 | Builder |
+| P-005 | 테스트/문서 동기화(README, API/CLI 계약) | S-1, S-2, S-3 | R-2, R-3 | Builder |
+
+# 4. 점수표 (WSJF)
+| Item ID | Work Item | Business Value | Time Criticality | RR/OE | Job Size | WSJF Score | selected_score | Priority |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| P-002 | 만기 정책 및 권한 가드 구현 | 9 | 10 | 9 | 4 | 7.00 | 7.00 | 1 |
+| P-003 | 토큰 출력 마스킹 및 감사 로그 구현 | 8 | 8 | 10 | 4 | 6.50 | 6.50 | 2 |
+| P-001 | CLI bot 토큰 발급/삭제 명령 추가 | 10 | 9 | 8 | 5 | 5.40 | 5.40 | 3 |
+| P-004 | CLI UX 정합성 보강 | 7 | 7 | 7 | 4 | 5.25 | 5.25 | 4 |
+| P-005 | 테스트/문서 동기화 | 7 | 6 | 8 | 5 | 4.20 | 4.20 | 5 |
+
+계산식: WSJF = (Business Value + Time Criticality + RR/OE) / Job Size
+
+## 점수 근거 메모
+- P-002: 무기한 발급 오남용 리스크(R-1)를 직접 줄이는 핵심 정책 구현이라 TC/RR-OE를 높게 반영했다.
+- P-003: 민감정보 노출 리스크(R-3)와 감사추적 요구(NFR-2)를 직접 완화하므로 RR/OE를 최상위로 반영했다.
+- P-001: 기능 핵심(발급/삭제)이지만 정책/보안 가드 선행 필요성이 있어 우선순위를 3으로 배치했다.
+- P-004: 운영 UX 일관성 확보에 필요하나 기능/보안 블로커 대비 사업가치는 상대적으로 낮아 후순위다.
+- P-005: 품질 게이트 통과 및 문서 동기화 필수이나 구현 선행 항목 의존이 있어 마지막 순위로 배치했다.
+
+# 5. 작업별 수용 기준 (AC)
+## P-002 AC
+- AC-1: 토큰 발급 명령에서 만기 미입력 시 기본 TTL 365일이 적용된다.
+- AC-2: `--no-expiry` 옵션은 관리자 전용 CLI 운영 정책에서만 허용되며, 정책 비적합 실행에서는 명확한 오류 코드/메시지를 반환한다.
+- AC-3: 만기 관련 옵션 조합이 잘못된 경우(예: TTL과 no-expiry 동시 지정) 검증 오류가 발생한다.
+
+## P-003 AC
+- AC-1: 토큰 원문은 발급 직후 1회만 출력되고 이후 출력/조회에서는 앞 6자/뒤 4자 외 마스킹된다.
+- AC-2: 발급/삭제 시 실행자, bot_id, token_id(마스킹), 시각, 결과가 감사 로그에 기록된다.
+- AC-3: 로그에는 토큰 원문이 저장되지 않는다.
+
+## P-001 AC
+- AC-1: CLI에 bot 토큰 발급 명령과 삭제 명령이 추가되고 `--help`에서 확인 가능하다.
+- AC-2: 발급 명령 성공 시 `token_id`, `expires_at`, `revoked` 정보가 출력 포맷 정책에 맞게 표시된다.
+- AC-3: 삭제 명령 성공 시 토큰이 즉시 폐기되어 재사용이 불가능해야 한다.
+
+## P-004 AC
+- AC-1: 발급/삭제 명령은 기본적으로 확인 프롬프트를 표시하고 `--force` 사용 시 프롬프트를 생략한다.
+- AC-2: 잘못된 bot_id/token_id 입력 시 사용자 행동 지침이 포함된 오류 메시지를 제공한다.
+- AC-3: `table`/`json` 출력 모드에서 동일한 필수 필드 집합을 보장한다.
+
+## P-005 AC
+- AC-1: 신규 기능에 대해 정상 경로 1건 이상, 예외 경로 1건 이상의 테스트가 추가된다.
+- AC-2: docs sync 규칙 대상 문서(README, API/CLI 계약)가 코드 변경과 함께 갱신된다.
+- AC-3: Verification 단계에서 테스트 실행 증적을 첨부할 수 있는 로그/리포트가 생성된다.
+
+# 6. 우선순위 조정/예외
+- 동률 처리: WSJF 동률 시 RR/OE가 큰 항목 우선, 동률 지속 시 Job Size가 작은 항목 우선.
+- Override: 없음
+- 승인자: Justin
+
+# 7. Design 단계 전달 체크
+- [x] 우선순위 상위 백로그의 AC가 검증 가능한 문장으로 정의됨
+- [x] WSJF 계산 근거 기록 완료
+- [x] 이번 반복 In Scope/Out of Scope 확정
+- [x] 최종 승인
+
+# 8. 파일 처리 결과
+- 생성/갱신 경로: docs/sdlc/planning/pln-001_2026-04-14_cli-bot-token-lifecycle-cli.planning.md
+- 점수 파일 갱신: docs/sdlc/planning/planning-backlog-scores.out.csv
+
+# 9. 사용자 결정 필요 항목 요약
+현재 미해결 플레이스홀더 없음

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/3_design.md

@@ -0,0 +1,171 @@
+# 0. 문서 상태
+- 상태: confirmed
+- 승인자: Justin
+- 승인 시각: 2026-04-15
+
+# 1. Design 개요
+- 입력 Planning: pln-001
+- 목적: CLI bot 토큰 발급/삭제 기능을 정책 일관성, 보안성, 운영성 기준으로 구현 가능하도록 인터페이스/흐름/검증 포인트를 확정한다.
+- 설계 대상 작업 (WSJF 상위 3개):
+  - 1순위: P-002 만기 정책 및 권한 가드 구현
+  - 2순위: P-003 토큰 출력 마스킹 및 감사 로그 구현
+  - 3순위: P-001 CLI bot 토큰 발급/삭제 명령 추가
+
+# 2. 설계 대안 비교 (우선순위 상위 작업)
+## P-002: 만기 정책 및 권한 가드 구현
+### 대안 A
+- 설명: CLI 입력 단계(Typer 옵션 파싱/검증)에서 TTL 기본값, `--no-expiry` 상호배타성, 관리자 정책 검증을 선처리한다.
+- 장점:
+  - 잘못된 입력을 서비스 호출 전에 차단해 오류 원인이 명확하다.
+  - 단위 테스트가 간단하며 사용자 피드백이 빠르다.
+- 단점:
+  - 정책 검증 로직이 CLI 계층에 치우치면 API 계층과 중복될 수 있다.
+
+### 대안 B
+- 설명: 정책 검증을 auth/service 계층에서 처리하고 CLI는 입력 전달만 수행한다.
+- 장점:
+  - 정책 소스가 단일화되어 API/CLI 일관성이 높다.
+  - 다른 채널(예: 배치, API)에서도 동일 정책 재사용이 쉽다.
+- 단점:
+  - CLI 사용자 입장에서는 오류 맥락이 늦게 반환될 수 있다.
+  - 서비스 에러를 CLI 친화 메시지로 재매핑하는 추가 코드가 필요하다.
+
+### 선택 결정
+- 선택: 대안 A+B 혼합
+- 근거: 상호배타성/입력 형식 검증은 CLI에서 조기 차단하고, 권한 및 최종 만기 정책 강제는 서비스 계층에서 재검증해 정책 일관성과 UX를 동시에 확보한다.
+
+## P-003: 토큰 출력 마스킹 및 감사 로그 구현
+### 대안 A
+- 설명: 발급 응답 DTO 생성 시점에서 마스킹된 값만 남기고 원문을 폐기한다.
+- 장점:
+  - 출력/로그 경로를 일괄 통제해 원문 노출 위험이 낮다.
+  - 후속 렌더링 계층(table/json)에서 추가 안전장치 부담이 줄어든다.
+- 단점:
+  - 발급 직후 1회 원문 출력 요구를 처리하기 위해 예외 흐름이 필요하다.
+
+### 대안 B
+- 설명: 출력 직전 렌더링 함수에서 마스킹을 적용하고 내부 모델에는 원문을 유지한다.
+- 장점:
+  - 기존 데이터 모델 변경이 적다.
+  - 일부 디버깅 시 내부 상태 확인이 쉽다.
+- 단점:
+  - 로그/예외 경로에서 원문 누출 가능성이 높다.
+  - 마스킹 누락 지점이 생기기 쉽다.
+
+### 선택 결정
+- 선택: 대안 A
+- 근거: NFR-1/NFR-2와 R-3 완화 우선순위가 높아, 원문 보존 경로를 최소화하는 구조가 안전하다.
+
+## P-001: CLI bot 토큰 발급/삭제 명령 추가
+### 대안 A
+- 설명: 기존 `user/portfolio/strategy`와 동일하게 `bot` Typer group을 추가하고 `token issue`, `token revoke` 서브커맨드로 구성한다.
+- 장점:
+  - 현재 CLI 구조와 일관되어 학습 비용이 낮다.
+  - 명령 확장(예: token list) 시 구조가 자연스럽다.
+- 단점:
+  - 초기 구현 시 커맨드 트리/도움말 정비가 필요하다.
+
+### 대안 B
+- 설명: 기존 `user` 그룹에 `user bot-token issue/revoke` 형태로 통합한다.
+- 장점:
+  - 새로운 최상위 그룹 추가가 없어 변경 범위가 작다.
+- 단점:
+  - 사용자 관리와 bot 토큰 수명주기가 섞여 명령 의미가 불명확해진다.
+
+### 선택 결정
+- 선택: 대안 A
+- 근거: P-004의 UX 일관성 요구를 충족하고 장기 확장성(봇/토큰 명령 확장)에 유리하다.
+
+# 3. 인터페이스 정의
+## P-002: 만기 정책 및 권한 가드 구현
+- 입력: `--ttl-days`(optional), `--no-expiry`(flag), 실행자 컨텍스트(admin 여부)
+- 출력: 정책 유효성 통과 시 정규화된 만기 정책 객체(`expires_at` 또는 `never_expires=true`)
+- 오류 경로: 옵션 상충, 음수/0 TTL, 비관리자 `--no-expiry` 사용 시 검증 오류 반환
+
+## P-003: 토큰 출력 마스킹 및 감사 로그 구현
+- 입력: 발급/삭제 결과 객체(`token_id`, `raw_token` optional, `actor_id`, `bot_id`, `timestamp`)
+- 출력: 사용자 출력용 마스킹 토큰 값, 감사 로그 이벤트 레코드
+- 오류 경로: 감사 로그 기록 실패 시 `issue`는 트랜잭션 롤백으로 발급을 취소하고 명령을 실패 처리한다. `revoke`는 보안 우선 원칙에 따라 폐기는 유지하고 명령은 실패 처리하며 운영 경고를 발생시킨다.
+
+## P-001: CLI bot 토큰 발급/삭제 명령 추가
+- 입력: `bot_id`, 발급 옵션(`--ttl-days`/`--no-expiry`), 공통 옵션(`--force`, `--format`)
+- 출력: issue 시 `token_id/expires_at/revoked(false)` + 1회 토큰 원문, revoke 시 `token_id/revoked(true)`
+- 오류 경로: 미존재 bot/token, 권한 부족, 정책 위반, 저장소/서비스 예외
+
+## P-004: CLI UX 정합성 보강
+- 입력: 커맨드 실행 컨텍스트(확인 프롬프트 응답, `--force`, 출력 모드)
+- 출력: 표준화된 성공/실패 출력(table/json)
+- 오류 경로: 포맷 미지원, 사용자 취소 시 정상 종료(code 0), 도메인 오류 시 비정상 종료(code != 0)
+
+## P-005: 테스트/문서 동기화
+- 입력: 테스트 케이스 정의, docs sync 규칙 대상 파일 목록
+- 출력: 테스트 결과 리포트, 업데이트된 README/API 계약 문서
+- 오류 경로: 테스트 실패, docs sync 체크 실패, 누락 문서 갱신 감지
+
+# 4. 데이터/흐름 설계
+## P-002: 만기 정책 및 권한 가드 구현
+- 주요 데이터 경로:
+  - CLI 옵션 파싱 -> 입력 검증 -> 서비스 계층 정책 재검증 -> repository 요청 페이로드 구성
+- 상태 변화:
+  - `draft_policy` -> `validated_policy` -> `persistable_policy`
+
+## P-003: 토큰 출력 마스킹 및 감사 로그 구현
+- 주요 데이터 경로:
+  - 서비스 발급/삭제 결과 -> 마스킹 변환 -> 출력 렌더링 + 감사 로그 sink 기록
+- 상태 변화:
+  - `raw_token_state` -> `masked_view_state` -> `audited_state`
+
+## P-001: CLI bot 토큰 발급/삭제 명령 추가
+- 주요 데이터 경로:
+  - command dispatch -> service 호출(issue/revoke) -> 결과 DTO -> renderer(table/json)
+- 상태 변화:
+  - issue: `requested` -> `issued(active)`
+  - revoke: `issued(active)` -> `revoked(inactive)`
+
+## P-004: CLI UX 정합성 보강
+- 주요 데이터 경로:
+  - confirmation gate -> command executor -> unified output/error handler
+- 상태 변화:
+  - `pending_confirmation` -> `executed` 또는 `cancelled`
+
+## P-005: 테스트/문서 동기화
+- 주요 데이터 경로:
+  - code change set -> test run -> docs sync check -> verification evidence bundle
+- 상태 변화:
+  - `unverified` -> `verified` 또는 `failed-with-evidence`
+
+# 5. 테스트 전략 연계 (AC 매핑)
+| 작업 ID | AC | 검증 방법 | 검증 포인트 |
+|---|---|---|---|
+| P-002 | AC-1 | CLI 통합 테스트 | `ttl-days` 미입력 시 `expires_at`이 현재+365일로 계산됨 |
+| P-002 | AC-2 | 권한 예외 테스트 | 비관리자 컨텍스트에서 `--no-expiry` 요청 시 오류 코드/메시지 확인 |
+| P-002 | AC-3 | 옵션 조합 검증 테스트 | `--ttl-days`와 `--no-expiry` 동시 지정 시 검증 실패 |
+| P-003 | AC-1 | 출력 스냅샷 테스트 | issue 이후 재조회/목록 출력에서 앞6/뒤4 외 마스킹 확인 |
+| P-003 | AC-2 | 감사 로그 검증 테스트 | issue/revoke 각각에 actor/bot/token_id(마스킹)/결과 로그 생성 확인 |
+| P-003 | AC-3 | 보안 회귀 테스트 | 로그 파일/콘솔에 raw token 미노출 확인 |
+| P-001 | AC-1 | 커맨드 help 테스트 | `bot token issue`, `bot token revoke` help 노출 확인 |
+| P-001 | AC-2 | 성공 경로 E2E | issue 응답 필수 필드(`token_id/expires_at/revoked`) 존재 확인 |
+| P-001 | AC-3 | revoke E2E | revoke 이후 동일 토큰 인증 실패 확인 |
+| P-004 | AC-1 | UX 동작 테스트 | 기본 프롬프트 표시, `--force` 시 생략 확인 |
+| P-004 | AC-2 | 예외 메시지 테스트 | 잘못된 bot/token 입력에서 사용자 지침 포함 메시지 확인 |
+| P-005 | AC-1/AC-2 | CI 파이프라인 검증 | 정상+예외 테스트 최소 1건씩 통과 및 docs sync 통과 |
+
+# 6. 리스크 대응 설계
+| 리스크 ID | 리스크 내용 | 설계 대응 전략 |
+|---|---|---|
+| R-1 | 만기 정책 모호성으로 무기한 토큰 남발 가능 | CLI+서비스 이중 검증, 기본 TTL 365일 강제, `--no-expiry` 제한 경로 및 감사 로그 필수화 |
+| R-2 | 명령 체계 확장 시 오사용 가능 | `bot` 전용 그룹으로 분리, help 명세 표준화, 오류 메시지에 다음 행동 가이드 포함 |
+| R-3 | 토큰 출력/로그 유출 위험 | 원문 1회 출력 후 즉시 마스킹 전환, 로그 저장 시 원문 금지, 보안 회귀 테스트 추가 |
+
+# 7. Implementation 단계 전달 체크
+- [x] 우선순위 상위 작업의 설계 근거(대안 비교 + 선택 이유)가 존재함
+- [x] 전체 작업의 인터페이스(입력/출력/오류 경로)가 정의됨
+- [x] AC와 검증 포인트가 매핑됨
+- [x] Planning 리스크에 대한 설계 대응이 반영됨
+- [x] 최종 승인
+
+# 8. 파일 처리 결과
+- 생성/갱신 경로: docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md
+
+# 9. 사용자 결정 필요 항목 요약
+현재 미해결 플레이스홀더 없음

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/4_implementation.md

@@ -0,0 +1,103 @@
+# 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 단계 전달 체크
+- [x] 구현 범위가 설계 문서와 연결됨
+- [x] 작업 단위별 검증 방법이 정의됨
+- [x] 영향 파일과 의존성 점검 결과가 기록됨
+- [x] Verification에 전달할 실행/검증 근거가 정의됨
+- [x] 최종 승인
+
+# 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. 사용자 결정 필요 항목 요약
+현재 미해결 플레이스홀더 없음

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/5_verification.md

@@ -0,0 +1,52 @@
+# 0. 문서 상태
+- 상태: confirmed
+- 승인자: Justin
+- 승인 시각: 2026-04-15
+
+# 1. Verification 개요
+- 입력 Implementation: imp-001
+- 목적: CLI bot 토큰 발급/삭제 기능 구현이 요구된 Acceptance Criteria(AC)를 충족하는지 검증하고, 결함 및 품질 게이트를 점검하여 Release 단계로 전달한다.
+- 검증 대상 작업: I-001~I-008 (CLI bot token issue/revoke 노출, 옵션 검증, TTL/권한 정책, 응답 필드, 마스킹, 감사 로그 분기, UX 분기, 회귀/문서 동기화)
+
+# 2. 검증 범위
+- In Scope: imp-001 Implementation 문서의 In Scope 전체
+- Out of Scope: imp-001 Implementation 문서의 Out of Scope 전체
+
+# 3. AC별 검증 결과
+| Impl ID | 검증 방법 | 성공 기준 | 근거 | 검증 결과 | 결함 여부 |
+|---|---|---|---|---|---|
+| I-001 | CLI help 테스트 | `bot token issue/revoke`가 help에 노출된다 | tests/test_cli.py | PASSED | 없음 |
+| I-002 | 옵션 조합 예외 테스트 | `--ttl-days`와 `--no-expiry` 동시 입력 시 실패한다 | tests/test_auth.py | PASSED | 없음 |
+| I-003 | 권한/기본값 테스트 | 기본 TTL 365일, 비관리자 `--no-expiry` 차단 | tests/test_auth.py | PASSED | 없음 |
+| I-004 | 성공 경로 통합 테스트 | issue 응답에 `token_id/expires_at/revoked`가 존재한다 | tests/test_cli.py | PASSED | 없음 |
+| I-005 | 출력 스냅샷/회귀 테스트 | 재출력/로그에 raw token이 노출되지 않는다 | tests/test_app.py | PASSED | 없음 |
+| I-006 | 감사 로그 실패 분기 테스트 | issue는 롤백 실패 처리, revoke는 폐기 유지+경고를 만족한다 | tests/test_auth.py | PASSED | 없음 |
+| I-007 | UX 동작 테스트 | revoke 시 확인 프롬프트, `--force` 시 생략, 취소는 code 0 | tests/test_cli.py | PASSED | 없음 |
+| I-008 | 회귀+문서 동기화 확인 | 변경 경로 테스트 통과 및 문서 업데이트 반영 | 테스트 실행 로그 + 변경 문서 diff | PASSED | 없음 |
+
+# 4. 결함 목록
+| 결함 ID | Impl ID | 결함 요약 | 심각도(Blocker/Major/Minor) | 상태 | 비고 |
+|---|---|---|---|---|---|
+| 없음 | | | | | |
+
+# 5. 회귀 테스트 결과
+- 실행 명령: `.venv/bin/python -m pytest -v | tee temp/ver-001-test-output.txt`
+- 결과 요약: 76개 테스트 모두 통과, 실패 0건
+- 최종 판정: Blocker 0건, Major 0건
+
+# 6. 예외 승인 목록
+| Exception ID | 관련 Impl ID | 결함 심각도 | 사유 | 승인자 | 승인 시각 | 유효 기간 | 비고 |
+|---|---|---|---|---|---|---|---|
+| 없음 | | | | | | | |
+
+# 7. Release 단계 전달 체크
+- [x] Blocker 결함 없음
+- [x] Major 결함 없음 또는 승인 예외 존재
+- [x] 테스트 실행 근거 첨부
+- [x] 배포 가능 여부/잔여 리스크/예외 승인 정리
+
+# 8. 파일 처리 결과
+- 생성: docs/sdlc/verification/ver-001_2026-04-15_cli-bot-token-lifecycle-cli.verification.md
+
+# 9. 사용자 결정 필요 항목 요약
+현재 미해결 플레이스홀더 없음

docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/6_release.md

@@ -0,0 +1,115 @@
+# 0. 문서 상태
+- 상태: draft
+- 승인자: {{DECIDE: 이 Release의 최종 승인자는 누구인가?}}
+- 승인 시각: {{CONFIRM: 승인 후 기재}}
+
+# 1. Release 개요
+- 입력 Verification: ver-001
+- 배포 대상 범위: CLI bot token issue/revoke 기능, TTL/권한 정책 검증, 토큰 출력 마스킹, 감사 로그 분기 처리
+- 배포 방식: {{DECIDE: 점진 배포/일괄 배포 중 선택하라}}
+- 배포 환경: {{DATA: 배포 대상 환경(dev/staging/prod)과 배포 윈도우를 입력하라}}
+- 배포 가능성 근거: Verification 품질 게이트에서 Blocker 0건, Major 0건, 회귀 테스트 76건 통과 확인
+
+# 2. 배포 체크리스트
+
+| 항목 | 확인 내용 | 결과 (완료/미완료/해당없음) | 비고 |
+|---|---|---|---|
+| 설정 검증 | 환경 변수, 시크릿, 외부 연동 키 유효성 확인 | 미완료 | {{DATA: 실제 배포 환경의 시크릿/키 점검 결과를 입력하라}} |
+| 데이터 검증 | 마이그레이션 순서, 백업 상태, 복구 가능성 확인 | 완료 | 본 변경은 스키마 마이그레이션 비포함, 기존 백업/복구 절차 유지 |
+| 호환성 검증 | 이전 버전 클라이언트/API 호환 여부 확인 | 완료 | API 계약 변경 없음, CLI 기능 확장 중심 변경 |
+| 의존성 검증 | 신규/변경 라이브러리 버전 충돌 여부 확인 | 완료 | pyproject 의존성 추가 없음, 충돌 징후 없음 |
+| 트래픽 전략 | 점진/일괄 배포 방식과 중단 기준 확인 | 미완료 | 배포 방식 결정 후 중단 기준 수치 확정 필요 |
+| 커뮤니케이션 | 사용자 공지, 내부 공지, 온콜 담당자 공유 완료 | 미완료 | {{DATA: 공지 채널/온콜 담당자/공지 시점을 입력하라}} |
+
+# 3. 롤백 계획
+
+## 롤백 트리거
+- 에러율 임계치: 배포 후 15분 이동 평균 기준 5xx 비율 > 2.0% 5분 이상 지속
+- 지연 임계치: p95 응답 지연이 배포 전 기준 대비 50% 이상 상승 상태가 10분 이상 지속
+- 장애 지표: bot token issue/revoke 명령 실패율 > 5% 또는 인증/권한 오류 급증
+
+## 롤백 절차
+1. 배포 중단 선언 및 온콜 채널에 롤백 트리거 충족 사실 공유
+2. 직전 안정 커밋으로 애플리케이션 버전 롤백 후 서비스 재기동
+3. 롤백 완료 후 핵심 검증 시나리오와 모니터링 지표 정상화 여부 확인
+
+## 데이터 롤백 전략
+- 스키마/데이터 복원 여부: 스키마 변경 없음으로 데이터 롤백 불필요
+- 절차: 애플리케이션 바이너리/코드만 이전 버전으로 복구, 운영 데이터는 유지
+
+## 롤백 후 검증
+- 핵심 시나리오 확인 항목:
+  - healthcheck 200 응답 확인
+  - 기존 토큰 인증 경로 정상 동작 확인
+  - CLI 기본 조회/쓰기 흐름 회귀 스모크 통과 확인
+
+## 롤백 커뮤니케이션
+- 공지 채널: {{DATA: 롤백 공지 채널(예: Slack #oncall, #backend-alerts)을 입력하라}}
+- 공지 시각: 롤백 시작 즉시 1차 공지, 복구 완료 후 2차 공지
+- 상태 업데이트 주기: 15분 간격
+
+## 참조 런북
+- 롤백 런북: .github/templates/rollback-runbook.template.md
+
+# 4. 릴리즈 노트 초안
+
+## 변경 요약
+- CLI bot token 발급/삭제 명령 추가 및 관련 인증 정책/출력 보안 동작을 반영한다.
+
+## 주요 변경 내용
+- bot token issue/revoke CLI 명령 제공 및 help 노출
+- --ttl-days/--no-expiry 상호배타 검증, 기본 TTL 365일 정책 적용
+- 비관리자 no-expiry 제한 및 권한 검증 강화
+- 토큰 원문 출력 노출 방지(마스킹) 및 감사 로그 분기 처리 강화
+
+## 영향 범위
+- 사용자 영향: 운영자/개발자 CLI 사용 흐름에 bot token 라이프사이클 명령이 추가된다.
+- 시스템 영향: 인증/권한 경로와 감사 로그 경로의 실행 분기 증가, API 인터페이스 변경은 없음
+
+## 알려진 제한 사항
+- 배포 방식(점진/일괄) 및 운영 공지 채널/온콜 확정 전까지 운영 절차 최종 승인 불가
+
+# 5. 배포 후 관찰 계획
+
+| 모니터링 항목 | 측정 지표 | 정상 범위 | 이상 감지 기준 | 담당자 |
+|---|---|---|---|---|
+| API 안정성 | 5xx 비율 | < 1.0% | 2.0% 초과 5분 지속 | {{DATA: 담당자 지정}} |
+| API 성능 | p95 지연 | 배포 전 기준 ±20% | 기준 대비 +50% 10분 지속 | {{DATA: 담당자 지정}} |
+| CLI 기능 품질 | issue/revoke 성공률 | > 99% | 95% 미만 10분 지속 | {{DATA: 담당자 지정}} |
+| 인증/권한 오류 | 401/403 비율 | 배포 전 기준 ±20% | 기준 대비 2배 이상 10분 지속 | {{DATA: 담당자 지정}} |
+
+## 관찰 기간
+- 집중 관찰 기간: 배포 후 24시간
+- 일반 관찰 기간: 배포 후 7일
+
+# 6. 승인된 예외 인계 목록
+해당 없음
+
+# 7. Operations 단계 전달 체크
+- [ ] 롤백 가능한 배포 계획 승인됨
+- [ ] 배포 체크리스트 항목 전체 "완료" 또는 "해당없음" 처리됨
+- [x] 릴리즈/롤백 체크리스트가 근거와 함께 완료됨
+- [x] 배포 후 관찰 항목이 정의됨
+- [x] Operations에 전달할 관찰 포인트, 장애 트리거, 후속 대응 절차 준비됨
+- [x] 승인된 예외 이력 인계됨
+- [ ] 최종 승인
+  - {{CONFIRM: Release 초안 승인 여부를 확인하라}}
+
+# 8. 파일 처리 결과
+- 생성/갱신 경로: docs/sdlc/release/rel-001_2026-04-15_cli-bot-token-lifecycle-cli.release.md
+
+# 9. 사용자 결정 필요 항목 요약
+## {{DECIDE}}
+- 이 Release의 최종 승인자는 누구인가?
+- 점진 배포/일괄 배포 중 선택하라
+
+## {{CONFIRM}}
+- 승인 후 기재
+- Release 초안 승인 여부를 확인하라
+
+## {{DATA}}
+- 배포 대상 환경(dev/staging/prod)과 배포 윈도우를 입력하라
+- 실제 배포 환경의 시크릿/키 점검 결과를 입력하라
+- 공지 채널/온콜 담당자/공지 시점을 입력하라
+- 롤백 공지 채널(예: Slack #oncall, #backend-alerts)을 입력하라
+- 모니터링 담당자를 지정하라