portfolio-hub/docs/srs/Documentation/req-032_portfolio-v1-baseline-docs-update.md

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 검증