feat: implement portfolio UUID migration and v1 API finalization (BAT-006, BAT-001 re-verified)

Core Changes: - Migrate portfolio_id from string to UUID in schema and repository layer - Update portfolio CLI commands to use name+user combination for identification - Update HTTP API to accept portfolio_id as UUID path parameter - Implement portfolio ownership validation in repository queries Requirements Completed (REQ-016 to REQ-019): - REQ-016: portfolios table UUID schema migration with data migration script - REQ-017: CLI portfolio commands with name+user identification - REQ-018: HTTP API portfolio path parameters and v1 asset_id UUID returns - REQ-019: Portfolio UUID baseline documentation updates BAT-001 Re-verification: - REQ-004~010 marked as Implemented after verification evidence validation - All v1 API endpoints verified with comprehensive test coverage Documentation Updates: - Update data-model.md with portfolio UUID structure - Update interface-contract.md with UUID path parameters - Update runtime-flows.md with ownership-based resolution flows - Update project-structure.md with database layer changes - Add migration script for portfolio UUID transition Testing: - Add test_portfolio_uuid.py for migration validation - Update test_cli.py and test_portfolio_ownership.py for ownership checks
2026-05-11 09:27:57 +00:00
parent 9ed307555a
commit 829629fa8f
46 changed files with 3260 additions and 220 deletions
@@ -0,0 +1,145 @@
+# req-019: portfolio UUID 전환 관련 baseline 문서 갱신
+
+- Status: Implemented
+- Type: Documentation
+- Priority: Medium
+- Owner: repository-maintainers
+
+## Intent
+- REQ-016~018의 구현으로 변경되는 DB 스키마, CLI 흐름, HTTP API 계약을 baseline 문서(`docs/project-structure.md`, `docs/runtime-flows.md`, `docs/data-model.md`, `docs/interface-contract.md`)에 반영해 문서와 구현 간 불일치를 방지한다.
+- trex-basic 동시 배포 계획을 `docs/interface-contract.md`에 기록한다.
+
+## Requirement
+- `docs/project-structure.md`를 갱신해 `app/repositories/postgres.py`에 신규 추가된 `get_portfolio_by_name_and_user()` 메서드와 `app/domain/models.py`의 `portfolio_id`(UUID 문자열) 의미 변경을 반영한다.
+- `docs/runtime-flows.md`를 갱신해 아래를 반영한다.
+  - CLI 명령 흐름: `<name>` + `--user <username>` 조합으로 portfolio를 식별하고 내부에서 UUID를 조회하는 흐름
+  - `v1 API — GET /v1/assets` flow: `asset_id` 필드가 UUID를 반환함
+- `docs/data-model.md`를 갱신해 `portfolios` 테이블의 `portfolio_id`(UUID, TEXT, PRIMARY KEY), `name`(TEXT) 신규 컬럼, `(owner_user_id, name)` 복합 UNIQUE 제약을 반영한다.
+- `docs/interface-contract.md`를 갱신해 `GET /v1/assets` `asset_id` 필드가 UUID를 반환함을 기록하고, trex-basic과 portfolio-hub의 동시 배포 계획을 명시한다.
+
+## Acceptance Criteria
+1. Given `docs/project-structure.md`를 검토하면, Then `app/repositories/postgres.py` 설명에 `get_portfolio_by_name_and_user()` 메서드가 언급되고, `app/domain/models.py`의 `portfolio_id`가 UUID 기반임이 반영된다.
+2. Given `docs/runtime-flows.md`를 검토하면, Then CLI 명령 흐름 설명에 `<name>` + `--user <username>` 조합 식별 방식이 반영되고, `v1 API — GET /v1/assets` flow에 `asset_id`가 UUID임이 명시된다.
+3. Given `docs/data-model.md`를 검토하면, Then `portfolios` 테이블 스키마에 `portfolio_id`(UUID TEXT, PK), `name`(TEXT), `(owner_user_id, name)` UNIQUE 제약이 반영된다.
+4. Given `docs/interface-contract.md`를 검토하면, Then `GET /v1/assets` `asset_id` 필드가 UUID를 반환함이 명시되고, trex-basic과 portfolio-hub의 동시 배포 계획이 기록된다.
+
+## Impacted Area
+- Docs:
+  - `docs/project-structure.md`
+  - `docs/runtime-flows.md`
+  - `docs/data-model.md`
+  - `docs/interface-contract.md`
+- Modules: 없음 (문서 전용)
+- Tests: 없음 (문서 전용)
+
+## Notes
+- 이 REQ는 REQ-016, REQ-017, REQ-018 구현 완료 후 또는 동일 batch에서 함께 처리하는 것이 적절하다.
+- trex-basic 측 코드 변경은 이번 범위 밖이며, 동시 배포 계획을 문서화하는 것만 이 REQ 범위에 포함된다.
+- NFR-1(단일 revision, IF NOT EXISTS, atomic)은 REQ-016에 흡수. NFR-2(단일 DB 쿼리, 오류 메시지)는 REQ-017에 흡수. NFR-3(동시 배포 계획 기록)은 이 REQ에서 처리.
+- Source Discovery: dcy-004_20260511_portfolio-id-uuid-migration-and-user-scoped-name-resolution (FR-6, NFR-3)
+
+## Change Log
+
+### CHG-20260511-01
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- 최초 생성 — dcy-004 draft-req에 의해 생성
+
+#### Intent
+- dcy-004 Discovery의 FR-6(docs/project-structure.md, docs/runtime-flows.md 갱신), NFR-3(동시 배포 계획 docs/interface-contract.md 기록) 반영. docs/data-model.md, docs/interface-contract.md 갱신 포함.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 1~4 (최초 생성)
+
+#### Impacted Area Delta
+- Docs:
+  - docs/project-structure.md
+  - docs/runtime-flows.md
+  - docs/data-model.md
+  - docs/interface-contract.md
+
+#### Delivery Trace Delta
+- Batches: none (batch 미결정)
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req → suggest-batch-reqs → draft-batch
+
+#### Validation Plan
+- 각 baseline 문서에 변경 내용이 포함됐는지 코드 리뷰로 확인
+
+### CHG-20260511-02
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- Approved 전환 — confirm-req 게이트 통과
+
+#### Intent
+- Delivery 입력으로 사용할 수 있도록 REQ-019를 승인 상태로 승격한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - none
+- Updated:
+  - none
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - none
+- Modules:
+  - none
+- Tests:
+  - none
+
+#### Delivery Trace Delta
+- Batches:
+  - none
+- Releases:
+  - none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: suggest-batch-reqs로 batch grouping 검토
+
+#### Validation Plan
+- confirm-req 게이트 재평가 결과: 필수 메타데이터, 구체적 Acceptance Criteria, Impacted Area, Change Log, blocker 없음 확인
+
+### CHG-20260511-03
+- Date: 2026-05-11
+- Author: repository-maintainers
+
+#### Change Summary
+- Implemented 전환 — BAT-006 verification passed, confirm-req-implemented 게이트 통과
+
+#### Intent
+- BAT-006 verification.md의 REQ-019 AC-1~4 모두 baseline 문서 변경 내용 직접 확인으로 evidence 충족. 문서 전용 REQ로 테스트 불필요. Blocking Issues 없음.
+
+#### Acceptance Criteria Delta
+- none
+
+#### Impacted Area Delta
+- none
+
+#### Delivery Trace Delta
+- Batches: BAT-006 (release-candidate)
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented
+- Follow-up Action: draft-release (BAT-006)
+
+#### Validation Plan
+- BAT-006 verification.md AC-1~4: project-structure.md / runtime-flows.md / data-model.md / interface-contract.md 각 문서 변경 내용 manual 확인 완료