draft

2026-04-14 23:43:47 +09:00
parent cc66e5f9a1
commit a701c98338
3 changed files with 216 additions and 0 deletions
@@ -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}}
+- 없음
@@ -0,0 +1,6 @@
+item_id,work_item,business_value,time_criticality,rr_oe,job_size,reach,impact,confidence,effort,method,notes
+P-002,만기 정책 및 권한 가드 구현 (--no-expiry 및 기본 TTL 365일),9,10,9,4,,,,,WSJF,"WSJF=7.00; Priority=1; FR-3/R-1"
+P-003,토큰 출력 마스킹 및 감사 로그 구현,8,8,10,4,,,,,WSJF,"WSJF=6.50; Priority=2; NFR-1/NFR-2/R-3"
+P-001,CLI bot 토큰 발급/삭제 명령 추가,10,9,8,5,,,,,WSJF,"WSJF=5.40; Priority=3; FR-1/FR-2/FR-4/FR-5"
+P-004,CLI UX 정합성 보강 (confirm-force/오류/출력 포맷),7,7,7,4,,,,,WSJF,"WSJF=5.25; Priority=4; NFR-3/NFR-4"
+P-005,테스트 및 문서 동기화,7,6,8,5,,,,,WSJF,"WSJF=4.20; Priority=5; S-1/S-2/S-3"
@@ -0,0 +1,101 @@
+# 0. 문서 상태
+- 상태: draft
+- 승인자: Justin
+- 승인 시각: {{CONFIRM: 승인 후 기재}}
+
+# 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 | Priority |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| P-002 | 만기 정책 및 권한 가드 구현 | 9 | 10 | 9 | 4 | 7.00 | 1 |
+| P-003 | 토큰 출력 마스킹 및 감사 로그 구현 | 8 | 8 | 10 | 4 | 6.50 | 2 |
+| P-001 | CLI bot 토큰 발급/삭제 명령 추가 | 10 | 9 | 8 | 5 | 5.40 | 3 |
+| P-004 | CLI UX 정합성 보강 | 7 | 7 | 7 | 4 | 5.25 | 4 |
+| P-005 | 테스트/문서 동기화 | 7 | 6 | 8 | 5 | 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 확정
+- [ ] 최종 승인
+  - {{CONFIRM: Planning 초안 승인 여부를 확인하라}}
+
+# 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. 사용자 결정 필요 항목 요약
+## {{CONFIRM}}
+- 승인 시각 기재. (위치: #0)
+- Planning 초안 승인 여부를 확인하라. (위치: #7)