# 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` 동일 구조). 구조/런타임 흐름 변경 없음.