From d20d7844520624a971c84b5ad69eff1a00a1a6f6 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Mon, 11 May 2026 12:13:29 +0000 Subject: [PATCH] docs: add rel-002 release and transition REQ-011, REQ-012, REQ-015 to Implemented Release: rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync Requirements Completed: - REQ-011: baseline docs update for trex-basic contract (BAT-008 verification passed) - REQ-012: service-token rotate CLI command (BAT-002 verification passed) - REQ-015: broker credential CLI command group (BAT-005 verification passed) Release Contents: - Operator CLI tooling with service-token rotate and broker credential management - Baseline documentation synchronized with trex-basic interface contract - Complete v1 API and portfolio ownership model documentation Documentation Updates: - Create rel-002 release document with included batches and deployment notes - Update docs/releases/index.md with release entry - Add implementation evidence to REQ-011, REQ-012, REQ-015 - Update SRS index with Implemented status transitions and change log --- docs/releases/index.md | 3 +- ...ator-cli-tooling-and-baseline-docs-sync.md | 114 ++++++++++++++++++ ...ine-docs-update-for-trex-basic-contract.md | 37 +++++- .../req-012_service-token-rotate-cli.md | 37 +++++- .../req-015_broker-credential-cli.md | 37 +++++- docs/srs/index.md | 10 +- 6 files changed, 229 insertions(+), 9 deletions(-) create mode 100644 docs/releases/rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md diff --git a/docs/releases/index.md b/docs/releases/index.md index 20b1231..ced420c 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -8,4 +8,5 @@ | REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link | | --- | --- | --- | --- | --- | --- | -| REL-001 | app-service | draft | BAT-001 | dcy-002 / REQ-004~010 | [rel-001_20260502_trex-basic-v1-api-contract](./rel-001_20260502_trex-basic-v1-api-contract.md) | \ No newline at end of file +| REL-001 | app-service | draft | BAT-001 | dcy-002 / REQ-004~010 | [rel-001_20260502_trex-basic-v1-api-contract](./rel-001_20260502_trex-basic-v1-api-contract.md) | +| REL-002 | tooling | confirmed | BAT-002, BAT-005, BAT-008 | minor-change + dcy-002 / REQ-011, REQ-012, REQ-015 | [rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync](./rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md) | \ No newline at end of file diff --git a/docs/releases/rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md b/docs/releases/rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md new file mode 100644 index 0000000..821beff --- /dev/null +++ b/docs/releases/rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md @@ -0,0 +1,114 @@ +# REL-002: operator CLI tooling and trex-basic baseline docs sync + +- Status: confirmed +- Profile: tooling +- Included Batch: BAT-002, BAT-005, BAT-008 + +## Scope + +- Included: + - BAT-002 (REQ-012) — `pfhub service-token rotate [--force]` CLI 명령 추가 + - BAT-005 (REQ-015) — `pfhub credential set/list/remove` CLI 명령 그룹 추가 + - BAT-008 (REQ-011) — `docs/interface-contract.md`, `docs/data-model.md`, `docs/runtime-flows.md` trex-basic 계약 기준 baseline 동기화 + - rotate 운영 메모 — 새 토큰 배포 후 downstream consumer는 새 토큰으로 다시 인증하고 `GET /v1/user_info` 기준 `runtime_id`를 재조회해야 함 + +- Excluded: + - BAT-001 app-service 배포 및 runtime health 확인 + - DB schema migration 실행 + - 신규 HTTP API 엔드포인트 추가 또는 서비스 프로세스 재기동 필수 변경 + +## Rollout Plan + +1. 대상 운영자 환경에 BAT-002, BAT-005, BAT-008이 포함된 현재 revision을 배포하거나 패키지 갱신한다. +2. `CREDENTIAL_ENCRYPTION_KEY` 설정 여부를 확인하고, rotate smoke용 no-expiry service-token과 credential smoke용 테스트 사용자를 준비한다. +3. 비운영 토큰으로 `pfhub service-token rotate --force`를 실행해 one-time token 출력과 DB 갱신을 확인한다. +4. rotate한 토큰을 실제 consumer에 배포할 계획이 있으면, 새 토큰으로 재인증 후 `GET /v1/user_info`를 재호출해 새 `runtime_id`를 재인식하는 절차를 운영 메모에 반영한다. +5. `pfhub credential set`, `pfhub credential list`, `pfhub credential remove --force` smoke를 실행해 broker credential 관리 동작을 확인한다. +6. 배포 산출물 또는 저장소에서 baseline 문서 3종이 최신 내용으로 노출되는지 확인한다. + +## Rollback Plan + +- 조건: CLI 명령 실행 실패, 패키지 회귀, 운영자 가이드 누락으로 release를 유지할 수 없을 때 +- 절차: + 1. 이전 revision 또는 패키지 버전으로 롤백한다. + 2. rotate smoke가 이미 토큰 값을 변경했으면, 해당 비운영 토큰을 다시 rotate하거나 새로 발급해 테스트 상태를 복구한다. + 3. credential smoke가 테스트 레코드를 남겼으면 `pfhub credential remove --force` 또는 기존 값 재설정으로 정리한다. + 4. 문서 게시 산출물이 있다면 이전 문서 버전으로 되돌린다. + +## Verification Checklist + +### 배포 전 + +- [ ] BAT-002 verification `verified`, BAT-005 verification `passed`, BAT-008 verification `passed` 확인 +- [ ] REQ-011, REQ-012, REQ-015가 `Implemented` 상태로 전환되었는지 확인 +- [ ] `CREDENTIAL_ENCRYPTION_KEY` 설정 및 비운영 smoke 대상(token, user) 준비 확인 +- [ ] DB schema migration이 이번 release 범위에 포함되지 않음을 운영자에게 재확인 + +### 배포 후 + +- [ ] `pfhub service-token rotate --force` smoke 성공 및 one-time token 안내 메시지 확인 +- [ ] rotate 대상 consumer의 `runtime_id` 재조회 필요성 전달 또는 runbook 반영 확인 +- [ ] `pfhub credential set/list/remove` smoke 성공 및 `encrypted_payload` 비노출 확인 +- [ ] `docs/interface-contract.md`, `docs/data-model.md`, `docs/runtime-flows.md` 최신 반영본 확인 + +## Release Execution Evidence + +- Release Status Transition Target: released + +### Deployment Facts + +- Executed At: + - (미기록 — 배포 미수행) +- Completed At: + - (미기록) +- Environment: + - (미기록) +- Operator: + - (미기록) +- Revision or Artifact: + - (미기록 — 배포 후 기록) +- Commands or Procedure: + - (미기록) + +### Profile-Specific Checks + +- tooling: + - Install or Upgrade Smoke: + - Source checkout 기준 tooling release로 별도 패키지 설치 단계는 없음. 현재 workspace revision에서 CLI regression evidence 확인: BAT-005 verification 기준 `python -m pytest tests/test_cli.py -q` → `49 passed in 1.49s`. + - CLI or Script Execution: + - BAT-002 verification 기준 rotate CLI acceptance evidence 확보: `test_cli_service_token_rotate_no_expiry_succeeds`, `test_cli_service_token_rotate_unknown_name_exits_error`, `test_cli_service_token_rotate_revoked_token_exits_error`, `test_cli_service_token_rotate_with_expiry_exits_error`, `test_cli_service_token_rotate_can_abort` 모두 PASS. + - BAT-005 verification 기준 credential CLI acceptance evidence 확보: `test_cli_credential_set_creates_record`, `test_cli_credential_list_hides_payload`, `test_cli_credential_set_with_unknown_user_exits_error`, `test_cli_credential_remove_deletes_record`, `test_cli_credential_set_requires_encryption_key` 모두 PASS. + - BAT-008 verification 기준 baseline 문서 sync evidence 확보: REQ-011 AC-1~3 PASS, Ready for Release true. + - Compatibility Note: + - rotate는 `runtime_id`를 새 값으로 갱신하므로 downstream consumer는 새 토큰 배포 후 `GET /v1/user_info` 기준 `runtime_id`를 재조회해야 함 + +### Rollback Outcome + +- Rollback Required: + - (미기록) +- Rollback Trigger: + - none +- Rollback Action: + - none + +### Release Decision Evidence + +- Released Decision: + - (미기록) +- Rationale: + - (미기록) +- Recorded By: + - (미기록) +- Recorded At: + - (미기록) + +## Feedback Handoff + +- Observation Summary: + - (배포 후 기록) +- Discovery Input: + - (배포 후 기록) +- REQ Input: + - (배포 후 기록) +- Change Request Input: + - (배포 후 기록) \ No newline at end of file diff --git a/docs/srs/Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md b/docs/srs/Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md index 7a53694..22d4f0f 100644 --- a/docs/srs/Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md +++ b/docs/srs/Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md @@ -1,6 +1,6 @@ # req-011: trex-basic 계약 반영을 위한 baseline 문서 갱신 -- Status: Approved +- Status: Implemented - Type: Documentation - Priority: Medium - Owner: repository-maintainers @@ -32,6 +32,41 @@ ## Change Log +### CHG-20260511-01 +- Date: 2026-05-11 +- Author: repository-maintainers + +#### Change Summary +- Implemented 전환 — BAT-008 verification passed, confirm-req-implemented 게이트 통과 + +#### Intent +- BAT-008 verification.md에서 REQ-011 AC-1~3의 문서화 기준과 evidence가 모두 PASS로 확인되어 Implemented로 승격한다. + +#### Acceptance Criteria Delta +- Added: none +- Updated: none +- Removed: none + +#### Impacted Area Delta +- Docs: none +- Modules: none +- Tests: none + +#### Delivery Trace Delta +- Batches: + - BAT-008 (release-candidate) +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: implemented +- Follow-up Action: draft-release 시 BAT-008 포함 여부 검토 + +#### Validation Plan +- BAT-008 verification.md의 REQ-011 AC-1~3 evidence와 Ready for Release: true 확인 + ### CHG-20260502-02 - Date: 2026-05-02 - Author: repository-maintainers diff --git a/docs/srs/Interface/req-012_service-token-rotate-cli.md b/docs/srs/Interface/req-012_service-token-rotate-cli.md index cacf981..47ca4ac 100644 --- a/docs/srs/Interface/req-012_service-token-rotate-cli.md +++ b/docs/srs/Interface/req-012_service-token-rotate-cli.md @@ -1,6 +1,6 @@ # req-012: service-token rotate CLI 명령 구현 -- Status: Approved +- Status: Implemented - Type: Interface - Priority: Medium - Owner: repository-maintainers @@ -54,6 +54,41 @@ ## Change Log +### CHG-20260511-02 +- Date: 2026-05-11 +- Author: repository-maintainers + +#### Change Summary +- Implemented 전환 — BAT-002 verification passed, confirm-req-implemented 게이트 통과 + +#### Intent +- BAT-002 verification.md에서 REQ-012 AC-1~6이 모두 PASS이고 blocking issue가 없음을 근거로 Implemented로 승격한다. + +#### Acceptance Criteria Delta +- Added: none +- Updated: none +- Removed: none + +#### Impacted Area Delta +- Docs: none +- Modules: none +- Tests: none + +#### Delivery Trace Delta +- Batches: + - BAT-002 (release-candidate) +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: implemented +- Follow-up Action: tooling release에 포함 시 rotate 후 runtime_id 재조회 운영 메모 반영 + +#### Validation Plan +- BAT-002 verification.md의 REQ-012 AC-1~6 evidence와 Ready for Release: true 확인 + ### CHG-20260511-01 - Date: 2026-05-11 - Author: repository-maintainers diff --git a/docs/srs/Interface/req-015_broker-credential-cli.md b/docs/srs/Interface/req-015_broker-credential-cli.md index 696be00..784dd6f 100644 --- a/docs/srs/Interface/req-015_broker-credential-cli.md +++ b/docs/srs/Interface/req-015_broker-credential-cli.md @@ -1,6 +1,6 @@ # req-015: CLI `credential` 명령 그룹 구현 (브로커 인증 정보 관리) -- Status: Approved +- Status: Implemented - Type: Interface - Priority: Medium - Owner: repository-maintainers @@ -38,6 +38,41 @@ ## Change Log +### CHG-20260511-01 +- Date: 2026-05-11 +- Author: repository-maintainers + +#### Change Summary +- Implemented 전환 — BAT-005 verification passed, confirm-req-implemented 게이트 통과 + +#### Intent +- BAT-005 verification.md에서 REQ-015 AC-1~5가 모두 passed이고 regression 없음이 확인되어 Implemented로 승격한다. + +#### Acceptance Criteria Delta +- Added: none +- Updated: none +- Removed: none + +#### Impacted Area Delta +- Docs: none +- Modules: none +- Tests: none + +#### Delivery Trace Delta +- Batches: + - BAT-005 (release-candidate) +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: implemented +- Follow-up Action: tooling release에 포함 시 credential smoke 절차 포함 + +#### Validation Plan +- BAT-005 verification.md의 AC-1~5 passed evidence와 residual risk 없음 확인 + ### CHG-20260503-02 - Date: 2026-05-03 - Author: repository-maintainers diff --git a/docs/srs/index.md b/docs/srs/index.md index 0cb7168..f7760b0 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -91,11 +91,11 @@ | REQ-008 | POST /v1/assets/{asset_id}/ledger/trades 엔드포인트 구현 | Interface | Implemented | High | repository-maintainers | [REQ-008](./Interface/req-008_v1-ledger-trades-endpoint.md) | | REQ-009 | v1 API 지원을 위한 DB 스키마 migration 추가 | Migration | Implemented | High | repository-maintainers | [REQ-009](./Migration/req-009_v1-api-db-schema-migration.md) | | REQ-010 | credential_payload Fernet 암호화 및 startup validation | Non-Functional | Implemented | High | repository-maintainers | [REQ-010](./Non-Functional/req-010_credential-payload-fernet-encryption.md) | -| REQ-011 | trex-basic 계약 반영을 위한 baseline 문서 갱신 | Documentation | Approved | Medium | repository-maintainers | [REQ-011](./Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md) | -| REQ-012 | service-token rotate CLI 명령 구현 | Interface | Approved | Medium | repository-maintainers | [REQ-012](./Interface/req-012_service-token-rotate-cli.md) | +| REQ-011 | trex-basic 계약 반영을 위한 baseline 문서 갱신 | Documentation | Implemented | Medium | repository-maintainers | [REQ-011](./Documentation/req-011_baseline-docs-update-for-trex-basic-contract.md) | +| REQ-012 | service-token rotate CLI 명령 구현 | Interface | Implemented | Medium | repository-maintainers | [REQ-012](./Interface/req-012_service-token-rotate-cli.md) | | REQ-013 | CLI `portfolio list --user` 필수화 및 소유자 기반 조회 | Interface | Implemented | Medium | repository-maintainers | [REQ-013](./Interface/req-013_portfolio-list-user-required.md) | | REQ-014 | CLI `portfolio create --user` 필수화 및 소유자 설정 | Interface | Implemented | Medium | repository-maintainers | [REQ-014](./Interface/req-014_portfolio-create-user-required.md) | -| REQ-015 | CLI `credential` 명령 그룹 구현 (브로커 인증 정보 관리) | Interface | Approved | Medium | repository-maintainers | [REQ-015](./Interface/req-015_broker-credential-cli.md) | +| REQ-015 | CLI `credential` 명령 그룹 구현 (브로커 인증 정보 관리) | Interface | Implemented | Medium | repository-maintainers | [REQ-015](./Interface/req-015_broker-credential-cli.md) | | REQ-016 | portfolios 테이블 UUID 전환 및 데이터 마이그레이션 | Migration | Implemented | High | repository-maintainers | [REQ-016](./Migration/req-016_portfolios-uuid-schema-migration.md) | | REQ-017 | CLI portfolio 명령 — name+user 조합 식별 방식 전환 | Interface | Implemented | High | repository-maintainers | [REQ-017](./Interface/req-017_portfolio-cli-name-user-identification.md) | | REQ-018 | HTTP API portfolio path parameter UUID 전환 및 v1 asset_id UUID 반환 | Interface | Implemented | High | repository-maintainers | [REQ-018](./Interface/req-018_portfolio-http-api-uuid-path-param.md) | @@ -103,8 +103,8 @@ ## Recent Change Log Summary +- 2026-05-11: REQ-011, REQ-012, REQ-015 Implemented 전환 — BAT-008/BAT-002/BAT-005 verification evidence 확인 - 2026-05-11: REQ-005 CHG-20260511-02 — service-token 발급 API 경로를 POST /auth/service-tokens로 명확화 - 2026-05-11: REQ-012 CHG-20260511-01 — rotate 후 runtime_id lifecycle 및 consumer 재조회 필요성 명시 - 2026-05-11: REQ-001~003 Implemented 전환 — BAT-007 verification passed, confirm-req-implemented 게이트 통과 -- 2026-05-11: REQ-006 CHG-20260511-02 — GET /v1/assets owner scope 회귀 수정 및 BAT-001 verification 정합화 -- 2026-05-11: REQ-004~010 Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과 \ No newline at end of file +- 2026-05-11: REQ-006 CHG-20260511-02 — GET /v1/assets owner scope 회귀 수정 및 BAT-001 verification 정합화 \ No newline at end of file