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