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

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 시작 시점은 보류.
• 범위(In Scope/Out of Scope) 확정
  • 기준: 본 문서 #5 범위 경계에 포함/제외 항목이 명시되어 있다.
• 성공 지표의 측정 방식/데이터 출처 확정
  • 운영 지표 수집 채널: "운영자는 CLI 실행 결과를 터미널 출력으로 직접 확인하며, 별도 중앙 로그/대시보드는 없음. 추후 자동화/감사 필요 시 /var/log/portfoliohub/cli.log에 기록 예정."
• High 영향 플레이스홀더 우선순위 및 해소 책임자 지정
  • 기준: [x] 미해결 High 영향 플레이스홀더 없음
• 승인자 확정
  • 기준: 승인자가 Justin으로 명시되어 있다.

9. 파일 처리 결과 (생성/미생성 경로)

• 처리 결과: 신규 생성
• 생성 경로: docs/sdlc/discovery/dcy-001_2026-04-14_cli-bot-token-issue-delete.discovery.md
• 재검토: Planning 이전에 운영 지표 수집 채널 확정 필요
• 참조 문서: 없음

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

{{DECIDE}}

• 없음

{{CONFIRM}}

• 승인 시각 기재.

{{DATA}}

• 없음