# REQ-032: portfolio v1 baseline 문서 갱신

- Status: Implemented
- Type: Documentation
- Priority: Medium
- Owner: Justin Ko

## Intent
- REQ-025~031의 v1 portfolio mutation 라우트 신설 + path 분리 + soft delete + 토큰 분기 정책을 baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`, `docs/data-model.md`, `docs/project-structure.md`)에 일괄 반영해 후속 batch/release가 단일 source of truth로 사용할 수 있도록 정합성을 회복한다.
- dcy-001 FR-5(REQ-013) Deprecated 후속 정리도 함께 반영 — `GET /v1/assets`는 catalog 전용 의미로 baseline에 복원.

## Requirement
- `docs/interface-contract.md` 갱신:
  - `/v1/portfolios*` 라우트 명세 추가: POST(REQ-025), PATCH(REQ-026), DELETE(REQ-027), GET(REQ-028), `/ledger/trades`(REQ-029), `/tags`(REQ-030), `/comments`(REQ-031)
  - 각 라우트의 토큰 분기 규칙(`token_type ∈ {service, client}` 거부 + `permission` 기준 분기) 일관 명시
  - `PortfolioItem` 응답 예시에 `symbol` 필드를 포함하고, 특히 `GET /v1/portfolios` 는 `portfolios JOIN assets` 기반 응답으로 `assets.symbol` 을 노출한다는 점을 명시
  - 구 path `POST /v1/assets/{asset_id}/ledger/trades` 제거 + 동일 batch release 정책 명시
  - `GET /v1/assets`는 dcy-001 FR-2 admin catalog 조회 전용으로 의미 복원 (REQ-013 Deprecated 정합)
  - daemon authorization model 갱신 (3단계 fail-closed)
- `docs/runtime-flows.md` 갱신:
  - portfolio mutation flow(create + catalog 검증 + ownership 검증 + disabled 보호)
  - GET /v1/portfolios 토큰 분기 조회 flow
  - ledger trade path 이전 흐름 + daemon assignment 3단계 인가
  - soft delete flow (status 전환 + daemon 자동 해제 + 의존 데이터 보존 + 복구 경로)
- `docs/data-model.md` 갱신:
  - Portfolio 엔티티의 `status` 필드 `disabled` 의미 명시 + 의존 데이터 보존 정책
  - dcy-001 catalog/portfolio 분리 모델 baseline 반영(REQ-009/011 정합 — dcy-001 REQ-015에서 처리될 수 있음, 본 REQ는 portfolio v1 측면만 보강)
- `docs/project-structure.md` 갱신:
  - `app/api/v1_portfolios.py` 신규 파일 추가 + 라우터 책임 갱신
  - `app/api/v1_ledger.py` 제거 또는 v1_portfolios.py에 흡수 반영
- 갱신은 v1 portfolio mutation surface 정합성 회복에 집중한다. dcy-002 tag 정책의 baseline 반영은 dcy-002 REQ-008이 별도로 다루며, 본 REQ는 portfolio tag 적용 라우트 명세만 포함한다.

## Acceptance Criteria
1. Given `grep -n "POST /v1/portfolios\|PATCH /v1/portfolios\|DELETE /v1/portfolios\|GET /v1/portfolios" docs/interface-contract.md`, When 본 REQ 구현 후, Then 각 라우트 명세 entry가 1건 이상 발견된다.
2. Given `grep -n "POST /v1/assets/{asset_id}/ledger/trades" docs/interface-contract.md`, When 본 REQ 구현 후, Then 구 path 명세가 제거되어 0건이거나 "deprecated/removed" 표시로만 잔존.
3. Given `grep -n "GET /v1/portfolios.*?market\|managed_by_daemon_id" docs/runtime-flows.md`, When 본 REQ 구현 후, Then `GET /v1/portfolios` 토큰 분기 flow + daemon-scoped 필터가 명시된다.
4. Given `grep -n "soft delete\|status='disabled'\|disabled" docs/data-model.md`, When 본 REQ 구현 후, Then Portfolio.status='disabled' 의미와 의존 데이터 보존 정책이 반영된다.
5. Given `grep -n "v1_portfolios.py" docs/project-structure.md`, When 본 REQ 구현 후, Then 신규 라우터 파일이 명시된다.
6. Given 사람 리뷰, When baseline 4종 문서를 점검, Then REQ-025~031의 v1 portfolio mutation 정책과 충돌하는 잔재가 없다.
7. Given `grep -n "symbol" docs/interface-contract.md`, When 본 REQ 구현 후, Then `PortfolioItem` 기반 POST/PATCH/DELETE/GET `/v1/portfolios` 응답 설명에 `symbol` 필드가 명시되고 GET 항목은 joined asset result 설명을 포함한다.

## Impacted Area
- Docs:
  - `docs/interface-contract.md`
  - `docs/runtime-flows.md`
  - `docs/data-model.md`
  - `docs/project-structure.md`
- Modules: 없음 (문서 전용)
- Tests: 없음 (문서 전용. AC-1~6은 grep + 사람 리뷰)

## Notes
- 본 REQ는 REQ-025~031 코드 변경 후 또는 동일 batch에서 함께 처리하는 것이 적절하다. baseline 문서가 코드 변경 사항을 반영하지 않으면 후속 REQ/batch가 잘못된 source of truth를 참조한다.
- dcy-004 REQ-019(토큰 surface baseline 정합성)와 본 REQ는 baseline 갱신 대상이 부분적으로 겹치나 책임 분담:
  - REQ-019: 토큰 surface (client 폐지, rebind, AuthContext daemon_id, auth_tokens 인덱스)
  - 본 REQ-032: portfolio v1 surface (path 분리, soft delete, ownership/disabled, ledger path 이전)
  - 두 REQ가 동일 batch에서 처리될 경우 baseline 문서 동시 갱신 시 conflict 회피를 위해 commit 순서 또는 작업자 분담 명시 필요.
- dcy-001 REQ-015(asset catalog baseline)도 baseline 갱신 대상이라 batch design 단계에서 3개 REQ(REQ-015 + REQ-019 + REQ-032)의 baseline 작업을 통합 batch로 묶거나 의존성 순서를 명시.
- Source: dcy-003 FR-10. dcy-001 REQ-013 Deprecated 후속 baseline 정리 포함.

## Change Log

### CHG-20260524-02
- Date: 2026-05-24
- Author: Hermes Agent

#### Change Summary
- Status: Approved → Implemented

#### Intent
- BAT-014 verification 완료. `docs/interface-contract.md` 에 portfolio CRUD/list 응답의 `symbol` 필드와 GET join 기반 응답 설명이 반영되어 REQ-032 augmentation 범위가 충족되었다.

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

#### Delivery Trace Delta
- Batches: BAT-014 (release-candidate); BAT-010 interface-contract evidence superseded by BAT-014
- Releases: pending

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-implemented
- Follow-up Action: release 단계 전 추가 baseline drift 점검

### CHG-20260524-01
- Date: 2026-05-24
- Author: Hermes Agent

#### Change Summary
- portfolio v1 baseline 문서에 `PortfolioItem.symbol` 및 GET `/v1/portfolios` asset-join 응답 계약 반영이 필요해 REQ-032를 augment 하고 상태를 Implemented → Approved로 되돌림.

#### Intent
- trex-orbit 팀 요청으로 CRUD/list portfolio 응답 계약이 `symbol` 포함 형태로 확장되었다. baseline 문서가 이를 반영하지 않으면 구현 후에도 API source of truth가 stale 해지므로, interface-contract/runtime 설명의 후속 갱신을 별도 delivery trace로 강제한다.

#### Acceptance Criteria Delta
- Added:
  - AC-7: baseline 문서에 `symbol` 필드 및 GET join 기반 응답 설명이 존재해야 함

#### Impacted Area Delta
- Docs: `docs/interface-contract.md` (필수), 필요 시 `docs/runtime-flows.md` 의 GET `/v1/portfolios` 설명 보강
- Modules: 없음
- Tests: 없음 (문서 grep + 사람 리뷰)

#### Delivery Trace Delta
- Batches: BAT-010 evidence partially superseded; follow-up BAT-014 예정
- Releases: REL-001 baseline evidence 일부 재검토 필요

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: yes (baseline documentation evidence partial)
- Status Recommendation: revert-to-approved
- Follow-up Action: BAT-014에서 interface-contract 예시와 설명 갱신 후 재검증

#### Validation Plan
- `docs/interface-contract.md` 에서 POST/PATCH/DELETE/GET `/v1/portfolios` 응답 설명과 예시에 `symbol` 이 추가됐는지, GET 섹션에 joined asset result 설명이 있는지 grep + 사람 리뷰로 확인한다.

### 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

#### Change Summary
- Status: Proposed → Approved

#### Intent
- 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC 구체성 확인 완료, blocker 없음

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

#### Delivery Trace Delta
- Batches: none (미정)
- Releases: none (미정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-approved
- Follow-up Action: batch 계획 편입

### CHG-20260520-01
- Date: 2026-05-20
- Author: Justin Ko

#### Change Summary
- 최초 생성 — dcy-003 confirm-discovery 후 draft-req 실행. dcy-003 FR-10 산출물.

#### Intent
- v1 portfolio mutation surface의 baseline 문서 정합성 회복 + dcy-001 REQ-013 Deprecated 후속 정리.

#### Acceptance Criteria Delta
- Added:
  - AC-1~6 최초 작성

#### Impacted Area Delta
- Docs: docs/interface-contract.md, docs/runtime-flows.md, docs/data-model.md, docs/project-structure.md — 최초 지정
- Modules: 없음
- Tests: 없음

#### Delivery Trace Delta
- Batches: none (미정)
- Releases: none (미정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 batch 계획 편입; REQ-025~031 코드 변경 후 또는 동일 batch에서 처리. dcy-004 REQ-019, dcy-001 REQ-015와의 baseline 작업 충돌 조율 필요.

#### Validation Plan
- grep + 사람 리뷰로 AC-1~6 검증