portfolio-hub/docs/srs/Documentation/req-019_portfolio-uuid-baseline-docs-update.md

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 확인 완료