From a701c98338199785eb5779f75ee32f55e894655c Mon Sep 17 00:00:00 2001 From: Jinhwan Ko Date: Tue, 14 Apr 2026 23:43:47 +0900 Subject: [PATCH] draft --- ...14_cli-bot-token-issue-delete.discovery.md | 109 ++++++++++++++++++ .../planning/planning-backlog-scores.out.csv | 6 + ...14_cli-bot-token-lifecycle-cli.planning.md | 101 ++++++++++++++++ 3 files changed, 216 insertions(+) create mode 100644 docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.discovery.md create mode 100644 docs/sdlc/planning/planning-backlog-scores.out.csv create mode 100644 docs/sdlc/planning/pln-001_2026-04-14_cli-bot-token-lifecycle-cli.planning.md diff --git a/docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.discovery.md b/docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.discovery.md new file mode 100644 index 0000000..95176b6 --- /dev/null +++ b/docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.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}} +- 없음 diff --git a/docs/sdlc/planning/planning-backlog-scores.out.csv b/docs/sdlc/planning/planning-backlog-scores.out.csv new file mode 100644 index 0000000..ebd4641 --- /dev/null +++ b/docs/sdlc/planning/planning-backlog-scores.out.csv @@ -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" diff --git a/docs/sdlc/planning/pln-001_2026-04-14_cli-bot-token-lifecycle-cli.planning.md b/docs/sdlc/planning/pln-001_2026-04-14_cli-bot-token-lifecycle-cli.planning.md new file mode 100644 index 0000000..f732f11 --- /dev/null +++ b/docs/sdlc/planning/pln-001_2026-04-14_cli-bot-token-lifecycle-cli.planning.md @@ -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)