feat(BAT-005): add broker credential CLI command with persistence and tests

- Add CredentialService for managing broker credentials - Implement credential CLI commands (create, list, get, update, delete) - Add postgres repository support for credential operations - Add comprehensive test coverage for credential CLI - Update docs/batches/index.md and docs/srs/index.md with BAT-005 - Update docs/project-structure.md to reflect credential service
2026-05-03 12:44:40 +00:00
parent fb555dd72e
commit 222c66bb7f
12 changed files with 670 additions and 4 deletions
@@ -0,0 +1,108 @@
+# req-015: CLI `credential` 명령 그룹 구현 (브로커 인증 정보 관리)
+
+- Status: Approved
+- Type: Interface
+- Priority: Medium
+- Owner: repository-maintainers
+
+## Intent
+- 운영자가 CLI(`pfhub credential`)를 통해 KIS 브로커 인증 정보를 안전하게 등록, 조회, 삭제할 수 있어야 한다.
+- `broker_credentials` 테이블(migration 0014)과 기존 Fernet 암호화 인프라(`app/core/encryption.py`, `CREDENTIAL_ENCRYPTION_KEY`)를 재사용해 CLI 레이어만 추가한다.
+
+## Requirement
+- 시스템은 `pfhub credential set --user <username> --broker <broker> --account-ref <ref> --app-key <key> --app-secret <secret>` 명령을 제공해야 한다. 이 명령은 `{"app_key": ..., "app_secret": ...}` JSON을 Fernet으로 암호화한 뒤 `broker_credentials` 테이블에 upsert한다.
+- 시스템은 `pfhub credential list --user <username>` 명령을 제공해야 한다. 이 명령은 사용자의 브로커 인증 정보 목록을 반환하되, `encrypted_payload`는 출력하지 않는다.
+- 시스템은 `pfhub credential remove --user <username> --broker <broker> [--force]` 명령을 제공해야 한다. 이 명령은 해당 인증 정보 레코드를 삭제한다.
+- 존재하지 않는 사용자를 지정하면 에러 메시지와 함께 exit code 1로 종료해야 한다.
+
+## Acceptance Criteria
+1. Given alice 사용자와 유효한 `CREDENTIAL_ENCRYPTION_KEY`가 설정된 환경에서, When `pfhub credential set --user alice --broker kis --account-ref REF --app-key KEY --app-secret SECRET`을 실행하면, Then `broker_credentials` 테이블에 암호화된 payload로 레코드가 생성(또는 갱신)된다.
+2. Given `broker_credentials`에 alice의 kis 레코드가 있을 때, When `pfhub credential list --user alice`를 실행하면, Then broker, account_ref, credential_version, last_rotated_at이 출력되고 `encrypted_payload`는 포함되지 않는다.
+3. Given 존재하지 않는 username을 지정할 때, When `pfhub credential set --user unknown ...`을 실행하면, Then 에러 메시지와 함께 exit code 1로 종료된다.
+4. Given alice의 kis 인증 정보가 있을 때, When `pfhub credential remove --user alice --broker kis --force`를 실행하면, Then 해당 레코드가 삭제되고 `pfhub credential list --user alice`에서 더 이상 표시되지 않는다.
+5. Given `CREDENTIAL_ENCRYPTION_KEY`가 설정되지 않은 환경에서, When `pfhub credential set ...`을 실행하면, Then 설정 미비 에러 메시지와 함께 exit code 1로 종료된다.
+
+## Impacted Area
+- Docs: `docs/project-structure.md` (CLI 모듈 목록 갱신)
+- Modules:
+  - `app/cli/commands/credential.py` (신규 — `credential_app`, `set`, `list`, `remove` 명령)
+  - `app/cli/main.py` (`credential_app` 등록 추가)
+  - `app/repositories/postgres.py` (`delete_broker_credential` 메서드 추가)
+- Tests: `tests/test_cli.py` (credential 명령 통합 테스트 추가)
+
+## Notes
+- `broker_credentials` 테이블 DDL과 `upsert_broker_credential`, `list_broker_credentials`, `get_broker_credential` 메서드는 migration 0014에서 이미 구현됨. `delete_broker_credential` 메서드는 이번 REQ에서 추가.
+- `app/core/encryption.py`의 `encrypt_payload(key, plaintext)` 사용.
+- 기존 CLI 패턴(`_with_service` 헬퍼, `execute_command`, `render_output`, `_confirm`) 동일하게 적용.
+- `--broker` 기본값은 `kis`.
+
+## Change Log
+
+### CHG-20260503-02
+- Date: 2026-05-03
+- Author: repository-maintainers
+
+#### Change Summary
+- REQ-015 Approved 전환 — minor-change fast path (단일 저위험 REQ, CLI 레이어만 추가, 구조/런타임 영향 없음)
+
+#### Intent
+- Acceptance Criteria 5개 모두 구현 판단에 충분하며 blocking assumption 없음
+
+#### Acceptance Criteria Delta
+- Added: none
+- Updated: none
+- Removed: none
+
+#### Impacted Area Delta
+- Docs: none
+- Modules: none
+- Tests: none
+
+#### Delivery Trace Delta
+- Batches: BAT-005 (batch-lite)
+- Releases: 미정
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: run-batch-implementation 진행
+
+#### Validation Plan
+- BAT-005 verification 통과 확인
+
+---
+
+### CHG-20260503-01
+- Date: 2026-05-03
+- Author: repository-maintainers
+
+#### Change Summary
+- REQ-015 최초 작성 — CLI `credential` 명령 그룹 구현 (브로커 인증 정보 관리)
+
+#### Intent
+- 운영자가 KIS 브로커 인증 정보를 CLI로 관리할 수 있도록 Interface 레이어 추가
+
+#### Acceptance Criteria Delta
+- Added:
+  - 위 Acceptance Criteria 1~5 전체
+- Updated: none
+- Removed: none
+
+#### Impacted Area Delta
+- Docs: `docs/project-structure.md`
+- Modules: `app/cli/commands/credential.py` (신규), `app/cli/main.py`, `app/repositories/postgres.py`
+- Tests: `tests/test_cli.py`
+
+#### Delivery Trace Delta
+- Batches: 미정 (BAT-005 예정)
+- Releases: 미정
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: 없음
+
+#### Validation Plan
+- `tests/test_cli.py`에 credential 명령 통합 테스트 작성 후 `pytest tests/test_cli.py` 전체 통과 확인