portfolio-hub/docs/batches/bat-005_20260503_broker-credential-cli/planning.md

BAT-005 Planning

• Status: confirmed
• Batch: BAT-005
• Profile: batch-lite

Included REQ

• REQ-015: CLI credential 명령 그룹 구현 (브로커 인증 정보 관리)

Out of Scope

• HTTP API 엔드포인트 추가 (별도 REQ 대상)
• 브로커 인증 정보 복호화 출력 (보안 정책상 CLI에서 plain text 노출 금지)
• 브로커 종류 확장 (현재는 kis 기본값만 처리)

구현 순서

1단계: repository 메서드 추가

• app/repositories/postgres.py
  • delete_broker_credential(user_id: str, broker: str) -> bool 추가
    • 레코드 존재 시 삭제 후 True, 미존재 시 False 반환

2단계: CLI 명령 모듈 신규 생성

• app/cli/commands/credential.py
  • credential_app = typer.Typer(help="Broker credential management commands.")
  • _with_service(ctx, callback) 헬퍼: repository 생성 → callback 실행 → finally close
  • set 명령: --user, --broker (기본값 kis), --account-ref, --app-key, --app-secret
    • get_user_by_username → None이면 ValueError
    • settings.require_credential_encryption_key() → Fernet 암호화
    • upsert_broker_credential 호출
  • list 명령: --user
    • get_user_by_username → None이면 ValueError
    • list_broker_credentials 호출, encrypted_payload 제외 출력
  • remove 명령: --user, --broker, --force
    • get_user_by_username → None이면 ValueError
    • _confirm(force, ...) 확인 후 delete_broker_credential 호출

3단계: CLI 등록

• app/cli/main.py
  • from app.cli.commands.credential import credential_app import 추가
  • app.add_typer(credential_app, name="credential") 등록

4단계: 문서 갱신

• docs/project-structure.md — CLI 모듈 목록에 credential.py 항목 추가

5단계: 테스트

• tests/test_cli.py
  • test_cli_credential_set_creates_record (신규): alice 생성 후 set 실행 → list에 표시
  • test_cli_credential_list_hides_payload (신규): list 출력에 encrypted_payload 미포함 확인
  • test_cli_credential_set_with_unknown_user_exits_error (신규): 미존재 user → exit code 1
  • test_cli_credential_remove_deletes_record (신규): set 후 remove → list에서 사라짐
  • test_cli_credential_set_requires_encryption_key (신규): CREDENTIAL_ENCRYPTION_KEY 미설정 → exit code 1

Dependencies

• Internal:
  • broker_credentials 테이블 (migration 0014 — 이미 존재)
  • upsert_broker_credential, list_broker_credentials, get_broker_credential (이미 존재)
  • app/core/encryption.py — encrypt_payload (이미 존재)
  • app/core/config.py — settings.require_credential_encryption_key() (이미 존재)
  • _confirm, execute_command, render_output (기존 CLI 헬퍼 — 이미 존재)
• External: 없음

Design Gate

• Design Required Before Implementation: no
• Reason: 기존 _with_service 헬퍼 패턴 재사용 (user.py 동일 구조). 구조/런타임 흐름 변경 없음.