feat: v1 portfolio mutation, sub-resources, ledger path migration (BAT-008~011)

dcy-003/004 기반 v1 API surface 완성 및 BAT-008~011 구현·검증 완료:

- BAT-008 (REQ-019~021,024): 토큰 surface baseline 문서 갱신
- BAT-009 (REQ-025~028): POST/PATCH/DELETE/GET /v1/portfolios CRUD 신설
  - _require_write_token, _get_portfolio_or_404, soft delete, daemon-scoped list
- BAT-010 (REQ-030~032): portfolio tag/comment 서브 라우트 신설 + baseline 갱신
  - GET/POST/DELETE /v1/portfolios/{id}/tags
  - POST/GET/PATCH/DELETE /v1/portfolios/{id}/comments
- BAT-011 (REQ-029): ledger path migration
  - POST /v1/assets/{asset_id}/ledger/trades → /v1/portfolios/{portfolio_id}/ledger/trades
  - v1_ledger.py 제거, disabled 차단(409) 추가
  - test_v1.py / test_daemon_assignment.py 구 path 갱신
- 신규 tests: test_v1_portfolios_crud.py, test_v1_portfolios_list.py,
  test_v1_portfolios_tags_comments.py, test_v1_portfolios_ledger.py
- 전체 suite: 340 passed

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-21 07:25:39 +00:00
co-authored by Claude Sonnet 4.6
parent c815ce39b6
commit 4bf6b554a7
50 changed files with 3989 additions and 249 deletions
@@ -1,6 +1,6 @@
# REQ-019: 토큰 surface baseline 문서 정합성 회복
- Status: Approved
- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko
@@ -51,6 +51,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-008 confirm-batch-verification 완료: 모든 AC(AC-1~5) 검증됨(grep + 사람 리뷰). verification.md Status: release-candidate.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-008 (release-candidate)
- Releases: none (미정)
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-020: 토큰 발급 권한 매트릭스 정의
- Status: Approved
- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko
@@ -34,6 +34,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-008 confirm-batch-verification 완료: AC-1~4 모두 검증됨(grep + 사람 리뷰). docs/interface-contract.md에 "Token Issuance Authorization Matrix" 섹션 신규 추가 확인.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-008 (release-candidate)
- Releases: none (미정)
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-021: 토큰 만료·회전 정책 정의
- Status: Approved
- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko
@@ -39,6 +39,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-008 confirm-batch-verification 완료: AC-1~5 검증됨(grep + 사람 리뷰). docs/runtime-flows.md에 "Token Expiry and Rotation Policy" 섹션 신규 추가 확인. AC-4(session no_expiry 코드 enforcement) 미구현 → follow-up 기록됨.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-008 (release-candidate)
- Releases: none (미정)
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: session no_expiry 코드 enforcement 미구현 — 별도 follow-up REQ 또는 다음 batch에서 처리
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-024: env admin token 운영 SOP 정의
- Status: Approved
- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko
@@ -48,6 +48,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-008 confirm-batch-verification 완료: AC-1~4 검증됨(grep + 사람 리뷰). docs/runtime-flows.md에 "env admin token 운영 SOP" 섹션 신규 추가 확인. AC-5(staging dry-run)는 release plan verification 영역으로 분리됨.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-008 (release-candidate)
- Releases: none (미정)
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: AC-5(staging dry-run)는 release plan verification 단계에서 수행
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-032: portfolio v1 baseline 문서 갱신
- Status: Approved
- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko
@@ -57,6 +57,33 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-010 구현 완료: baseline 4종 일괄 갱신 — `docs/interface-contract.md` (v1 Portfolio API 섹션 신설; tag/comment 서브 라우트 명세; ledger "pending REQ-029" 마킹); `docs/runtime-flows.md` (portfolio mutation flow, GET 분기 flow, soft delete flow, comment CRUD flow 추가); `docs/data-model.md` (Portfolio.status='disabled' 의미 + 의존 데이터 보존); `docs/project-structure.md` (v1_portfolios.py + v1.py 갱신)
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-010 (release-candidate)
- Releases: pending
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: BAT-010 release candidate → draft-release
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-025: POST /v1/portfolios 신설 (토큰 분기 + catalog 검증)
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -54,6 +54,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-009 confirm-batch-verification 완료. tests/test_v1_portfolios_crud.py AC-1~7 전 케이스 pytest 통과 (2026-05-21, 298 PASSED).
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-009 (release-candidate)
- Releases: TBD
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-026: PATCH /v1/portfolios/{portfolio_id} 신설
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -51,6 +51,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-009 confirm-batch-verification 완료. tests/test_v1_portfolios_crud.py AC-1~9 전 케이스 pytest 통과 (2026-05-21, 298 PASSED).
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-009 (release-candidate)
- Releases: TBD
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-027: DELETE /v1/portfolios/{portfolio_id} 신설 (soft delete)
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -62,6 +62,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-009 confirm-batch-verification 완료. tests/test_v1_portfolios_crud.py AC-1~10 전 케이스 pytest 통과 (2026-05-21, 298 PASSED). soft_delete_portfolio: status='disabled', managed_by_daemon_id=NULL, 의존 데이터 보존.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-009 (release-candidate)
- Releases: TBD
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-028: GET /v1/portfolios 신설 (토큰 분기 조회)
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -57,6 +57,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-009 confirm-batch-verification 완료. tests/test_v1_portfolios_list.py AC-1~11 전 케이스 pytest 통과 (2026-05-21, 298 PASSED). 토큰 분기 + status filter + daemon filter 모두 검증.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-009 (release-candidate)
- Releases: TBD
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: 없음
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-029: POST /v1/portfolios/{portfolio_id}/ledger/trades 이전
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -53,6 +53,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-011 구현 완료: `app/api/v1_portfolios.py`에 `POST /{portfolio_id}/ledger/trades` 신설 (daemon 인가 3단계 + disabled 409 + idempotency 보존); `app/api/v1_ledger.py` 삭제; `app/main.py` include 정리; `tests/test_v1_portfolios_ledger.py` AC-1~10 신규; `tests/test_v1.py` + `tests/test_daemon_assignment.py` 구 path 갱신
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-011 (release-candidate)
- Releases: pending
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: BAT-011 release candidate → draft-release; trex-basic 동시 배포 순서 잠금 필수
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -70,14 +96,14 @@
- No change
#### Delivery Trace Delta
- Batches: none (미정)
- Batches: BAT-011 (in-delivery)
- Releases: none (미정)
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-approved
- Follow-up Action: batch 계획 편입
- Follow-up Action: BAT-011 draft-batch-planning 완료 → draft-batch-design 진행
### CHG-20260520-01
- Date: 2026-05-20
@@ -1,6 +1,6 @@
# REQ-030: portfolio tag 적용/해제/조회 v1 라우트
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: Medium
- Owner: Justin Ko
@@ -57,6 +57,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-010 구현 완료: `app/api/v1_portfolios.py`에 GET /v1/portfolios/{id}/tags 신설 + POST/DELETE 라우트에 disabled 409 + service/client 403 보강; `app/schemas/v1.py`에 `PortfolioTagListResponse` 추가; `tests/test_v1_portfolios_tags_comments.py` 32 tests (AC-1~11 커버); baseline 4종 갱신(REQ-032)
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-010 (release-candidate)
- Releases: pending
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: BAT-010 release candidate → draft-release
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
@@ -1,6 +1,6 @@
# REQ-031: portfolio comment CRUD v1 라우트
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: Medium
- Owner: Justin Ko
@@ -54,6 +54,32 @@
## Change Log
### CHG-20260521-01
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented
#### Intent
- BAT-010 구현 완료: `app/api/v1_portfolios.py`에 POST/GET/PATCH/DELETE /v1/portfolios/{id}/comments 4종 신설; `app/schemas/v1.py`에 comment schema 4종 추가; `tests/test_v1_portfolios_tags_comments.py` AC-1~11 커버; comment 작성자 ownership은 portfolio ownership만 적용(design decision #3)
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches: BAT-010 (release-candidate)
- Releases: pending
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: BAT-010 release candidate → draft-release
### CHG-20260520-02
- Date: 2026-05-20
- Author: Justin Ko
+15 -12
View File
@@ -99,23 +99,26 @@
| REQ-016 | client token 발급 경로 코드 폐지 | Interface | Approved | High | Justin Ko | [req-016](./Interface/req-016_client-token-issuance-deprecation.md) |
| REQ-017 | service-token rotate unique index 보강 | Migration | Approved | High | Justin Ko | [req-017](./Migration/req-017_service-token-rotate-unique-index-fix.md) |
| REQ-018 | POST /auth/service-tokens body daemon_id forward 보정 | Interface | Approved | High | Justin Ko | [req-018](./Interface/req-018_service-token-http-daemon-id-forward.md) |
| REQ-019 | 토큰 surface baseline 문서 정합성 회복 | Documentation | Approved | Medium | Justin Ko | [req-019](./Documentation/req-019_token-surface-baseline-docs-consistency.md) |
| REQ-020 | 토큰 발급 권한 매트릭스 정의 | Documentation | Approved | Medium | Justin Ko | [req-020](./Documentation/req-020_token-issuance-authorization-matrix.md) |
| REQ-021 | 토큰 만료·회전 정책 정의 | Documentation | Approved | Medium | Justin Ko | [req-021](./Documentation/req-021_token-expiry-and-rotation-policy.md) |
| REQ-019 | 토큰 surface baseline 문서 정합성 회복 | Documentation | Implemented | Medium | Justin Ko | [req-019](./Documentation/req-019_token-surface-baseline-docs-consistency.md) |
| REQ-020 | 토큰 발급 권한 매트릭스 정의 | Documentation | Implemented | Medium | Justin Ko | [req-020](./Documentation/req-020_token-issuance-authorization-matrix.md) |
| REQ-021 | 토큰 만료·회전 정책 정의 | Documentation | Implemented | Medium | Justin Ko | [req-021](./Documentation/req-021_token-expiry-and-rotation-policy.md) |
| REQ-022 | daemon deactivation 시 바인딩 service token 자동 revoke | Interface | Implemented | High | Justin Ko | [req-022](./Interface/req-022_daemon-deactivation-auto-revoke.md) |
| REQ-023 | NULL daemon_id legacy token 마이그레이션 CLI | Interface | Implemented | Medium | Justin Ko | [req-023](./Interface/req-023_null-daemon-token-migration-cli.md) |
| REQ-024 | env admin token 운영 SOP 정의 | Documentation | Approved | Medium | Justin Ko | [req-024](./Documentation/req-024_env-admin-token-rotation-sop.md) |
| REQ-025 | POST /v1/portfolios 신설 (토큰 분기 + catalog 검증) | Interface | Approved | High | Justin Ko | [req-025](./Interface/req-025_v1-portfolios-create.md) |
| REQ-026 | PATCH /v1/portfolios/{portfolio_id} 신설 | Interface | Approved | High | Justin Ko | [req-026](./Interface/req-026_v1-portfolios-update.md) |
| REQ-027 | DELETE /v1/portfolios/{portfolio_id} 신설 (soft delete) | Interface | Approved | High | Justin Ko | [req-027](./Interface/req-027_v1-portfolios-soft-delete.md) |
| REQ-028 | GET /v1/portfolios 신설 (토큰 분기 조회) | Interface | Approved | High | Justin Ko | [req-028](./Interface/req-028_v1-portfolios-list.md) |
| REQ-029 | POST /v1/portfolios/{portfolio_id}/ledger/trades 이전 | Interface | Approved | High | Justin Ko | [req-029](./Interface/req-029_v1-portfolios-ledger-trades-migration.md) |
| REQ-030 | portfolio tag 적용/해제/조회 v1 라우트 | Interface | Approved | Medium | Justin Ko | [req-030](./Interface/req-030_v1-portfolios-tags-crud.md) |
| REQ-031 | portfolio comment CRUD v1 라우트 | Interface | Approved | Medium | Justin Ko | [req-031](./Interface/req-031_v1-portfolios-comments-crud.md) |
| REQ-032 | portfolio v1 baseline 문서 갱신 | Documentation | Approved | Medium | Justin Ko | [req-032](./Documentation/req-032_portfolio-v1-baseline-docs-update.md) |
| REQ-024 | env admin token 운영 SOP 정의 | Documentation | Implemented | Medium | Justin Ko | [req-024](./Documentation/req-024_env-admin-token-rotation-sop.md) |
| REQ-025 | POST /v1/portfolios 신설 (토큰 분기 + catalog 검증) | Interface | Implemented | High | Justin Ko | [req-025](./Interface/req-025_v1-portfolios-create.md) |
| REQ-026 | PATCH /v1/portfolios/{portfolio_id} 신설 | Interface | Implemented | High | Justin Ko | [req-026](./Interface/req-026_v1-portfolios-update.md) |
| REQ-027 | DELETE /v1/portfolios/{portfolio_id} 신설 (soft delete) | Interface | Implemented | High | Justin Ko | [req-027](./Interface/req-027_v1-portfolios-soft-delete.md) |
| REQ-028 | GET /v1/portfolios 신설 (토큰 분기 조회) | Interface | Implemented | High | Justin Ko | [req-028](./Interface/req-028_v1-portfolios-list.md) |
| REQ-029 | POST /v1/portfolios/{portfolio_id}/ledger/trades 이전 | Interface | Implemented | High | Justin Ko | [req-029](./Interface/req-029_v1-portfolios-ledger-trades-migration.md) |
| REQ-030 | portfolio tag 적용/해제/조회 v1 라우트 | Interface | Implemented | Medium | Justin Ko | [req-030](./Interface/req-030_v1-portfolios-tags-crud.md) |
| REQ-031 | portfolio comment CRUD v1 라우트 | Interface | Implemented | Medium | Justin Ko | [req-031](./Interface/req-031_v1-portfolios-comments-crud.md) |
| REQ-032 | portfolio v1 baseline 문서 갱신 | Documentation | Implemented | Medium | Justin Ko | [req-032](./Documentation/req-032_portfolio-v1-baseline-docs-update.md) |
## Recent Change Log Summary
- 2026-05-21: REQ-030/031/032 Approved → Implemented — BAT-010 confirm-batch-verification 완료. 330/330 PASSED (32 신규 tests in test_v1_portfolios_tags_comments.py). GET /v1/portfolios/{id}/tags 신설; POST/DELETE tag disabled 409 + service/client 403 보강; comment CRUD 4종 신설; baseline 4종 갱신(interface-contract/runtime-flows/data-model/project-structure).
- 2026-05-21: REQ-025/026/027/028 Approved → Implemented — BAT-009 confirm-batch-verification 완료. 298 PASSED (0 failed). test_v1_portfolios_crud.py 22건(REQ-025/026/027), test_v1_portfolios_list.py 10건(REQ-028) 전 AC 통과.
- 2026-05-21: REQ-019/020/021/024 Approved → Implemented — BAT-008 confirm-batch-verification 완료. 모든 grep AC 통과, 사람 리뷰 완료. REQ-021 follow-up: session no_expiry 코드 enforcement 미구현 → 별도 처리. REQ-024 AC-5: staging dry-run은 release plan 단계로 이관.
- 2026-05-20: REQ-016~032 (17건) 일괄 Proposed → Approved 전환 — confirm-req 무인자 일괄 모드 실행, 승인 게이트(필수 필드/AC 구체성/Change Log) 모두 충족, blocker 없음. 각 REQ에 CHG-20260520-02 entry 추가
- 2026-05-20: REQ-025~032 최초 생성 — dcy-003 (User Portfolio Mutation v1 API 이전, confirmed 2026-05-20) 후 draft-req 실행. POST/PATCH/DELETE/GET /v1/portfolios + ledger path 이전 + tag/comment v1 + baseline 정합성 (FR-1~10 분해, FR-9는 REQ-013 Deprecated로 이미 처리됨)
- 2026-05-20: REQ-016~024 최초 생성 — dcy-004 (토큰 발급 및 관리 전면 정비, confirmed 2026-05-20) 후 draft-req 실행. client token 폐지 / rotate index 보강 / HTTP daemon_id forward / baseline 정합성 / 발급 권한 매트릭스 / TTL·회전 정책 / daemon deactivation 자동 revoke / NULL daemon 마이그레이션 CLI / env admin SOP