feat: dcy-003/004 토큰 surface 개편 및 daemon lifecycle 정책 구현 (BAT-006/007)

BAT-006 (REQ-016/017/018): - client token 발급 경로 제거 (issue_client_token, POST /auth/tokens, 관련 스키마/테스트) - service-token rotate unique index revoked_at IS NULL 조건 추가 (Alembic CONCURRENTLY 마이그레이션) - POST /auth/service-tokens body daemon_id forward 누락 보정 (1-line fix) BAT-007 (REQ-022/023): - daemon deactivate 시 바인딩 service token 자동 revoke (CLI --force 옵션 + revoke_tokens_by_daemon_id) - NULL daemon_id legacy token 진단 CLI (migrate-null-daemon --dry-run) 거버넌스 문서: dcy-003/004 Discovery, REQ-016~023/025~032 신규, BAT-006/007 전체 산출물 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-21 01:03:39 +00:00
parent d4b841bc37
commit c815ce39b6
48 changed files with 3573 additions and 117 deletions
@@ -47,7 +47,7 @@
  - `tests/test_asset_catalog.py` (신규) — admin CRUD CLI/API AC 검증, non-admin 403 검증

 ## Notes
- `pfhub asset list`의 HTTP 대응(catalog 전용 GET)은 별도 admin 전용 엔드포인트로 구현하거나, GET /v1/assets에 `?mode=catalog` 파라미터로 분기할 수 있다. 설계 결정은 batch design 단계에서 확정한다. REQ-013(GET /v1/assets 포트폴리오 조회)과 충돌하지 않도록 주의한다.
+- `pfhub asset list`의 HTTP 대응(catalog 전용 GET): dcy-003 옵션 B(path 명명 분리) 결정에 따라 REQ-013(GET /v1/assets 포트폴리오 조회)이 Deprecated(2026-05-20) 처리되어 path 충돌 우려가 해소됨. **`GET /v1/assets`는 admin catalog 조회 전용**으로 본 REQ에서 다루며, dcy-001 batch design 단계에서 본 REQ에 GET 명세를 보강(change-req)하거나 별도 신규 REQ로 분리한다. 포지션 조회 `GET /v1/portfolios`는 dcy-003의 별도 신규 REQ로 분리 예정.
 - deactivate 후 해당 asset을 참조하는 기존 portfolio는 보존된다. 신규 portfolio 생성만 거부(REQ-012에서 처리).
 - REQ-009 선행 필요.
 - Source: dcy-001 FR-2, NFR-3
@@ -1,9 +1,10 @@
 # REQ-013: GET /v1/assets 토큰 타입별 분기 재정의

- Status: Approved
+- Status: Deprecated
 - Type: Interface
 - Priority: High
 - Owner: Justin Ko
+- Deprecated By: dcy-003 (path 명명 분리 옵션 B 결정), 2026-05-20

 ## Intent
 - 현재 service token(daemon) 전용으로 구현된 `GET /v1/assets`를 user token 및 admin token도 지원하는 통합 portfolio 조회 엔드포인트로 재정의한다.
@@ -46,6 +47,44 @@

 ## Change Log

+### CHG-20260520-01
+- Date: 2026-05-20
+- Author: Justin Ko
+
+#### Change Summary
+- Status: Approved → **Deprecated**. dcy-003(`docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md`, confirmed 2026-05-20)의 옵션 B(완전 분리) 결정으로 본 REQ의 path 결정이 무효화됨.
+
+#### Intent
+- dcy-003은 `GET /v1/assets`를 admin asset catalog 전용으로 회수하고 포지션 조회는 `GET /v1/portfolios` 신설 경로로 분리하는 정책을 채택했다. 본 REQ의 통합 endpoint 정의(`GET /v1/assets`가 토큰 타입별로 catalog/포지션을 동시 처리)는 dcy-003 결정에 따라 더 이상 기준 문서가 아니므로 Deprecated로 전환한다.
+- 본 REQ의 후속:
+  - `GET /v1/assets` (admin catalog 조회 의미) → dcy-001 batch design 단계에서 REQ-010 또는 신규 REQ로 분리 처리 (REQ-010 Notes 참조)
+  - `GET /v1/portfolios` (포지션 토큰 분기 조회) → dcy-003 FR-5에서 별도 신규 REQ로 작성 예정 (dcy-003 draft-req 단계)
+
+#### Acceptance Criteria Delta
+- Removed: AC-1~7 전체 (본 REQ Deprecated로 인해 검증 대상에서 제외). 후속 신규 REQ에서 새 path 기준으로 재작성 예정.
+
+#### Impacted Area Delta
+- Docs:
+  - docs/discovery/dcy-003 §6 OQ-5, §10 CONFIRM_DCY001_FR5_CHANGE_REQ가 본 Deprecated 처리의 근거
+  - docs/srs/Interface/req-010 Notes에 후속 GET /v1/assets catalog 명세 처리 계획 반영
+- Modules:
+  - 본 REQ Approved 시점에 코드 변경이 일어나지 않은 상태였으므로 코드 회귀 없음. 후속 신규 REQ에서 `app/api/v1_portfolios.py` 신규 + `app/api/v1_assets.py` 정리.
+- Tests:
+  - 신규 `tests/test_v1_asset_catalog.py`(REQ-013 Notes에 지정)는 작성되지 않은 상태. 후속 신규 REQ로 이관.
+
+#### Delivery Trace Delta
+- Batches: 본 REQ가 포함된 batch 미정. Deprecated 이후 batch 편입 없음.
+- Releases: 본 REQ 포함 release 미정.
+
+#### Revalidation Impact
+- Reverification Needed: no (구현 미진행 상태에서 Deprecated)
+- Existing Implementation Invalidated: no
+- Status Recommendation: deprecated
+- Follow-up Action: dcy-003 draft-req 단계에서 `GET /v1/portfolios` 신규 REQ 작성, dcy-001 batch design 단계에서 `GET /v1/assets` catalog 조회 명세 처리(REQ-010 보강 또는 신규 REQ)
+
+#### Validation Plan
+- 없음 (Deprecated 전환만)
+
 ### CHG-20260519-02
 - Date: 2026-05-19
 - Author: Justin Ko
@@ -0,0 +1,99 @@
+# REQ-016: client token 발급 경로 코드 폐지
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- dcy-003 옵션 B 결정으로 client token이 v1 portfolio mutation에서 거부되며, dcy-004 OQ-8 결정으로 user 자동화 use case는 admin 발급 service token으로 흡수된다. client token 발급 경로 자체를 코드에서 폐지해 토큰 surface를 session/service/env 3종으로 축소하고 발급 경로 중복을 제거한다.
+- DATA-1 inventory(2026-05-20) active client token 0건 확인됐으므로 즉시 코드 폐지로 진행하며 별도 revoke 스크립트나 grace period 운영 없이 release 단계에서 직접 제거한다.
+
+## Requirement
+- `POST /auth/tokens` HTTP route([app/api/auth_routes.py:100-122](app/api/auth_routes.py#L100-L122)), `app/services/auth_service.py:issue_client_token`, `app/schemas/auth.py:CreateClientTokenRequest`/`IssuedClientTokenResponse`, 관련 헬퍼·테스트를 모두 제거한다.
+- HTTP 호출 시 라우트가 등록되어 있지 않아 FastAPI 기본 404 응답을 반환하도록 한다(별도 405 처리 추가하지 않음).
+- 폐지 release 직전 `SELECT COUNT(*) FROM auth_tokens WHERE token_type='client' AND revoked_at IS NULL` 재확인을 release plan에 포함하며, >0이면 발급 사유 조사 후 release 보류 또는 즉시 revoke 처리한다.
+- 토큰 분기에서 `token_type='client'`는 더 이상 발급될 수 없으므로 dcy-003 FR-1/3/4/5의 게이트는 자연 유효한 상태로 유지되되 게이트 자체는 제거하지 않는다(env token 침투 방어).
+
+## Acceptance Criteria
+1. Given codebase grep `grep -rn "issue_client_token\|CreateClientTokenRequest\|IssuedClientTokenResponse"`, When 본 REQ 구현 후, Then 결과는 0건이다.
+2. Given `POST /auth/tokens` HTTP 호출, When 본 REQ 구현 후, Then HTTP 404(또는 FastAPI 기본 not-found 응답)가 반환된다.
+3. Given 폐지 release 직전 DATA-1 재확인 쿼리, When 실행, Then `COUNT = 0` 결과가 release plan evidence로 첨부된다.
+4. Given dcy-003 신규 REQ들의 token_type 게이트 회귀 테스트, When 본 REQ 구현 후 재실행, Then 모두 통과한다(client token 발급 불가에 따른 회귀 없음).
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — POST /auth/tokens 명세 제거 (REQ-019 baseline 정합 작업에 포함)
+- Modules:
+  - `app/api/auth_routes.py` — POST /auth/tokens 라우트, CreateClientTokenRequest/IssuedClientTokenResponse import, `create_token`/`revoke_token` 중 client 의존 부분 제거
+  - `app/services/auth_service.py` — `issue_client_token`, `IssuedClientToken` 데이터 클래스 제거. 단, `list_tokens`/`revoke_token` 등이 client 토큰을 함께 다루는 부분은 token_type 분기 정리 검토
+  - `app/schemas/auth.py` — `CreateClientTokenRequest`, `IssuedClientTokenResponse` 제거
+- Tests:
+  - 신규 `tests/test_auth_surface_after_client_deprecation.py` — AC-1/AC-2/AC-4 검증
+  - 기존 `tests/test_auth.py` 중 client token 관련 케이스 제거 또는 service token 케이스로 대체
+
+## Notes
+- DATA-1 inventory(2026-05-20) active client token 0건 확인됨. 발급 보유자에 대한 별도 통보 절차 불요.
+- 토큰 surface 3종(session/service/env)으로 축소 후 user 자동화 use case는 admin 발급 service token으로 흡수(dcy-004 OQ-8 결정).
+- dcy-003 OQ-5 결정의 token_type 게이트는 본 REQ 구현 후에도 코드에 유지(env token 외부 침투 방어).
+- Source: dcy-004 FR-1, dcy-004 NFR-1, dcy-003 OQ-5 후속.
+
+## Change Log
+
+### 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-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-1 (client token 발급 경로 코드 폐지) 산출물.
+
+#### Intent
+- 토큰 surface 3종 축소 + client 폐지 정책 코드 반영.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md (REQ-019에서 처리)
+- Modules: app/api/auth_routes.py, app/services/auth_service.py, app/schemas/auth.py — 최초 지정
+- Tests: tests/test_auth_surface_after_client_deprecation.py (신규), 기존 tests/test_auth.py — 최초 지정
+
+#### 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 계획 편입; release 직전 DATA-1 재확인 절차 포함
+
+#### Validation Plan
+- pytest로 AC-1~4 검증; codebase grep + HTTP 404 회귀 + dcy-003 token_type 게이트 회귀
@@ -0,0 +1,97 @@
+# REQ-018: POST /auth/service-tokens body daemon_id forward 보정
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- 현행 `POST /auth/service-tokens` HTTP route([app/api/auth_routes.py:131-137](app/api/auth_routes.py#L131-L137))가 `IssueServiceTokenRequest.daemon_id` 필드를 스키마에서 노출하지만 `service.issue_service_token` 호출 시 forward하지 않아 silently drop되는 결함을 정상화한다.
+- CLI `pfhub service-token issue --daemon-id`는 정상 forward하나 HTTP 경로만 daemon binding이 불가능한 상태였다. HTTP/CLI 일관성을 회복한다.
+
+## Requirement
+- `app/api/auth_routes.py:131-137`의 `service.issue_service_token(...)` 호출에 `daemon_id=payload.daemon_id`를 추가한다.
+- 비존재 또는 비활성 daemon_id가 body로 전달되면 `AuthService.issue_service_token`의 기존 검증 로직(`get_daemon_by_id` None 또는 `is_active=False`)이 ValueError를 발생시키고, `_raise_auth_error`를 통해 HTTP 4xx로 변환된다.
+- daemon_id 검증 실패 응답 코드는 ValueError detail에 따라 HTTP 400 또는 404로 분기된다(`_raise_auth_error` 기존 로직).
+- 본 REQ는 HTTP body daemon_id 처리만 보정한다. CLI 동작, daemon registry 자체, service token 발급 정책은 변경하지 않는다.
+
+## Acceptance Criteria
+1. Given admin token, When `POST /auth/service-tokens` body `{"name": "...", "username": "...", "daemon_id": "<existing-active-daemon-id>"}` 호출, Then HTTP 201 + issued token의 `auth_token.daemon_id == <daemon-id>` 반환.
+2. Given admin token, When `POST /auth/service-tokens` body `{"name": "...", "username": "...", "daemon_id": "<non-existing-daemon-id>"}` 호출, Then HTTP 4xx + `_raise_auth_error` 패턴에 따른 오류 메시지 반환.
+3. Given admin token, When `POST /auth/service-tokens` body `daemon_id` 필드 미포함 또는 null, Then 기존 동작 유지(daemon binding 없는 service token 발급, HTTP 201).
+4. Given AC-1과 CLI `pfhub service-token issue NAME --user U --daemon-id <daemon-id>` 실행 결과 비교, When 둘 다 발급된 토큰의 `daemon_id` 확인, Then 동일한 값이 저장된다(HTTP/CLI 동등성).
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — POST /auth/service-tokens body 명세에 daemon_id forward 동작 추가 (REQ-019에서 처리)
+- Modules:
+  - `app/api/auth_routes.py:131-137` — `issue_service_token` 호출 시 `daemon_id=payload.daemon_id` 추가
+- Tests:
+  - 갱신 `tests/test_auth.py` — AC-1~3 HTTP request 시뮬레이션 추가
+  - 갱신 `tests/test_daemon_registry.py` — AC-4 HTTP/CLI 동등성 회귀
+
+## Notes
+- 본 REQ는 1-line 보정에 가까운 단순 결함 수정이지만, HTTP API 사용자에게는 daemon binding 경로가 새로 작동하기 시작하는 의미 있는 변경이라 별도 REQ로 분리.
+- daemon registry 자체(존재/활성 검증)는 기존 `AuthService.issue_service_token` 내부 로직이 그대로 처리하므로 본 REQ에서는 daemon 모델을 건드리지 않는다.
+- HTTP body daemon_id를 누락하거나 null로 보내는 경우의 기본 동작(unbound service token 발급)은 dcy-004 OQ-7에서 "수동 매핑" 정책이 결정되었으므로 본 REQ에서 추가 제한하지 않는다. NULL daemon 토큰의 운영 정리는 REQ-023(마이그레이션 CLI)에서 처리.
+- Source: dcy-004 FR-3.
+
+## Change Log
+
+### 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-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-3 산출물.
+
+#### Intent
+- HTTP/CLI 토큰 발급 surface 일관성 회복 (daemon_id forward 누락 결함 정상화).
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md (REQ-019에서 처리)
+- Modules: app/api/auth_routes.py — 최초 지정
+- Tests: tests/test_auth.py, tests/test_daemon_registry.py — 최초 지정
+
+#### 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 계획 편입
+
+#### Validation Plan
+- pytest TestClient로 AC-1~4 검증; HTTP/CLI 동등성 회귀
@@ -0,0 +1,103 @@
+# REQ-022: daemon deactivation 시 바인딩 service token 자동 revoke
+
+- Status: Implemented
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- 현재 `pfhub daemon update --deactivate`가 daemon `is_active=false`만 설정하고 바인딩된 service token에 영향이 없어 비활성 daemon의 토큰이 계속 유효한 상태로 남는 운영 공백을 해소한다.
+- dcy-004 OQ-3 결정에 따라 deactivation 즉시 바인딩 service token 모두 revoke해 daemon 권한 종료를 token 단계까지 즉각 반영한다.
+
+## Requirement
+- `pfhub daemon update <daemon_id> --deactivate` 실행 시(또는 동등 service 메서드 호출 시) 동일 트랜잭션 내에서 `auth_tokens` 중 `daemon_id == <daemon_id>` AND `revoked_at IS NULL`인 모든 row를 revoke(`revoked_at = NOW()`)한다.
+- 회피 옵션(예: `--keep-tokens`)은 노출하지 않는다(정책 일관성).
+- graceful drain은 daemon 측 책임으로 분리한다. release plan에 "(1) daemon 프로세스 종료/drain 완료 확인 → (2) `pfhub daemon update --deactivate` 실행 → (3) 자동 revoke" 순서로 SOP를 명시한다(REQ-019 baseline 작업에 포함).
+- `app/cli/commands/daemon.py:update_daemon`이 `deactivate=True`로 호출될 때 `repository` 또는 신규 service 메서드(`revoke_tokens_for_daemon(daemon_id)`)를 통해 자동 revoke를 트리거한다.
+- 재활성화(`--activate`)는 자동 token 재발급이나 unrevoke를 수행하지 않는다. 운영자가 별도 발급 또는 rebind를 수행해야 한다.
+- 본 REQ는 v1 API의 daemon 모델([app/domain/models.py:Daemon](app/domain/models.py))과 service token 모델 위에서 작동하며 daemon registry 자체는 변경하지 않는다.
+
+## Acceptance Criteria
+1. Given active daemon에 바인딩된 active service token 1개 이상 존재, When `pfhub daemon update <daemon_id> --deactivate --force` 실행, Then 해당 daemon에 바인딩된 모든 service token의 `revoked_at`가 NOT NULL로 갱신되고 daemon `is_active=false`로 설정된다.
+2. Given AC-1 실행 후, When revoke된 token으로 v1 API 호출(예: `GET /v1/portfolios` 또는 `GET /v1/assets`), Then HTTP 401(Invalid token) 반환.
+3. Given daemon에 바인딩된 token이 0개인 daemon, When `--deactivate --force` 실행, Then daemon만 비활성화되고 token revoke 동작은 no-op이며 정상 종료.
+4. Given AC-1 실행 후 `--activate`로 재활성화, When 재실행, Then daemon만 활성화되고 이미 revoke된 token은 자동 복구되지 않는다(운영자가 신규 발급 필요).
+5. Given deactivation 실행 중 in-flight 거래(daemon이 ledger trade 호출 중), When 자동 revoke가 즉시 적용, Then in-flight 거래는 daemon 측 graceful drain 책임이며 본 REQ는 추가 보호하지 않음(release plan SOP 참조).
+
+## Impacted Area
+- Docs:
+  - `docs/runtime-flows.md` — "Daemon Deactivation 자동 Revoke" flow 추가 (REQ-019 baseline 작업에 포함)
+  - `README.md` — daemon provisioning runbook의 deactivation SOP 갱신 (REQ-019 또는 release plan)
+- Modules:
+  - `app/cli/commands/daemon.py:update_daemon` — `--deactivate` 분기에서 자동 revoke 호출 추가
+  - `app/services/auth_service.py` 또는 신규 service — `revoke_tokens_for_daemon(daemon_id)` 헬퍼 추가
+  - `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py` — `revoke_tokens_by_daemon_id(daemon_id)` 메서드 신규 추가
+- Tests:
+  - 갱신 `tests/test_daemon_registry.py` — AC-1~4 회귀 시나리오 추가
+  - 신규 또는 갱신 `tests/test_v1_*.py` — AC-2 revoke된 token으로 v1 호출 시 401 확인
+
+## Notes
+- graceful drain을 본 REQ 범위에 포함하지 않기로 결정(dcy-004 OQ-3). drain은 daemon 측(trex-basic 등)이 종료 신호 수신 시 in-flight 마무리 후 종료하는 형태로 구현되어야 한다. portfolio-hub 측은 즉시 revoke만 수행.
+- 본 REQ는 daemon registry CRUD(REQ-009/010 후속의 daemon 모델) 위에 얹는 추가 동작이며 daemon 모델 자체에는 변경 없음.
+- 재활성화 시 token 자동 복구를 하지 않는 이유: revoke된 token은 보안상 폐기 의미가 있어 자동 복구하면 권한 escalation 위험. 운영자가 신규 발급 절차를 통해 새 token을 부여하는 게 안전.
+- Source: dcy-004 FR-7, dcy-004 OQ-3 결정.
+
+## Change Log
+
+### 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-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-7 산출물.
+
+#### Intent
+- daemon deactivation 운영 공백 해소 — 비활성 daemon의 token이 계속 유효한 문제를 즉시 revoke 정책으로 정상화.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/runtime-flows.md, README.md — 최초 지정 (REQ-019 baseline 작업 또는 release plan)
+- Modules: app/cli/commands/daemon.py, app/services/auth_service.py, app/repositories/portfolio_repository.py, app/repositories/postgres.py — 최초 지정
+- Tests: tests/test_daemon_registry.py, tests/test_v1_*.py — 최초 지정
+
+#### 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 계획 편입
+
+#### Validation Plan
+- pytest로 AC-1~4 검증; AC-5는 정책 reference (release plan SOP 점검)
@@ -0,0 +1,103 @@
+# REQ-023: NULL daemon_id legacy token 마이그레이션 CLI
+
+- Status: Implemented
+- Type: Interface
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- `daemon_id IS NULL`인 active service token이 운영 환경에 존재하면 v1 API daemon-scoped endpoints가 fail-closed로 작동해 운영 정리가 필요하다. 자동 매핑은 권한 escalation 리스크로 채택하지 않고(dcy-004 OQ-7), 운영자 수동 매핑을 보조하는 진단 CLI를 제공한다.
+- dry-run으로 inventory + 매핑 후보를 진단 출력하고, 운영자가 token별 `rebind` 또는 `revoke`를 명시적으로 실행하는 패턴을 표준화한다.
+
+## Requirement
+- 신규 CLI 서브커맨드 `pfhub service-token migrate-null-daemon` 추가:
+  - `--dry-run` 옵션: NULL daemon active service token inventory를 출력. 각 token에 대해 `id`, `user_id`, `name`, `runtime_id`, `created_at`, 매핑 후보 daemon(같은 `owner_user_id == user_id`인 active daemon 목록)을 표 또는 JSON 형식으로 보고.
+  - 매핑 후보 검증: `token.user_id == daemon.owner_user_id` 일치 여부를 명시 표시. 불일치 가능성이 있는 token은 별도 경고 표시.
+  - `--dry-run` 없이 실행하면 안전상 명시적 거부(예: "use --dry-run for inspection, then `pfhub service-token rebind` or `revoke` per token") 또는 no-op.
+- 본 CLI는 자동 rebind/revoke를 수행하지 않는다. 실제 적용은 운영자가 token별로 `pfhub service-token rebind NAME --daemon-id ID` 또는 `pfhub service-token revoke NAME`을 명시 실행해야 한다.
+- 본 CLI는 idempotent하다(재실행 안전, NULL token이 0건이어도 정상 종료).
+- DATA-2 inventory(2026-05-20)에서 발견된 admin 테스트 fixture 1건은 본 batch release 시점에 운영자가 직접 `pfhub service-token revoke admin` 수동 실행으로 정리(release plan에 명시).
+
+## Acceptance Criteria
+1. Given `pfhub service-token migrate-null-daemon --dry-run` 실행, When NULL daemon active service token 1건 이상 존재, Then 각 token의 `id`, `user_id`, `name`, `runtime_id`, `created_at`, 매핑 후보 daemon 목록, user_id 일치 여부가 출력된다.
+2. Given `pfhub service-token migrate-null-daemon --dry-run` 실행, When NULL daemon 활성 service token이 0건, Then "no NULL daemon tokens" 메시지 출력 후 exit code 0으로 정상 종료.
+3. Given `pfhub service-token migrate-null-daemon` (--dry-run 없이) 실행, When 호출, Then 자동 변경을 거부하고(예: error message + non-zero exit) 운영자에게 `rebind`/`revoke` 수동 실행을 안내한다.
+4. Given AC-1 출력 후 운영자가 `pfhub service-token rebind NAME --daemon-id ID` 실행, When 매핑이 성공적으로 적용, Then 해당 token의 `daemon_id`가 갱신되고 다시 `--dry-run` 실행 시 해당 token이 inventory에서 제외된다.
+5. Given AC-1 실행 후 운영자가 `pfhub service-token revoke admin` 실행, When DATA-2 admin 테스트 fixture가 revoke, Then 다시 `--dry-run` 실행 시 해당 token이 inventory에서 제외된다.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — `pfhub service-token migrate-null-daemon` CLI 명세 추가 (REQ-019 baseline 작업)
+- Modules:
+  - `app/cli/commands/service_tokens.py` — `migrate_null_daemon` 함수 신규 추가 (Typer 서브커맨드 등록)
+  - `app/services/auth_service.py` — `list_null_daemon_service_tokens()` 및 `find_candidate_daemons_for_user(user_id)` 헬퍼 추가(또는 직접 repository 조회)
+  - `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py` — `list_service_tokens_with_null_daemon()` 메서드 신규 추가
+- Tests:
+  - 신규 `tests/test_null_daemon_migration.py` — AC-1~5 시나리오. dry-run 출력 검증 + idempotency 회귀 + non-dry-run 거부 동작 검증
+
+## Notes
+- dcy-004 OQ-7 결정으로 자동 매핑/auto-create daemon은 채택하지 않음(권한 escalation 리스크). 본 CLI는 진단 도구로만 작동.
+- DATA-2 inventory 1건(admin 테스트 fixture)은 본 batch release 시점에 운영자가 직접 처리. CLI 진단 + 운영자 수동 적용이라는 본 REQ 패턴의 첫 번째 적용 사례.
+- 매핑 후보가 0건(같은 user_id의 active daemon 없음)인 token은 dry-run 출력에 별도 표시해 운영자가 daemon 신규 생성 후 rebind를 진행하거나 token revoke를 결정하도록 안내.
+- 본 CLI는 batch 시점 1회 정리 + 향후 NULL daemon token이 발생할 때마다 사용 가능한 영구 운영 도구로 작동한다.
+- Source: dcy-004 FR-8, dcy-004 NFR-5, dcy-004 OQ-7 결정.
+
+## Change Log
+
+### 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-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-8 산출물.
+
+#### Intent
+- NULL daemon legacy token 마이그레이션을 운영자 수동 매핑 패턴으로 표준화 + 진단 CLI 제공.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md (REQ-019에서 처리)
+- Modules: app/cli/commands/service_tokens.py, app/services/auth_service.py, app/repositories/portfolio_repository.py, app/repositories/postgres.py — 최초 지정
+- Tests: tests/test_null_daemon_migration.py — 최초 지정
+
+#### Delivery Trace Delta
+- Batches: none (미정)
+- Releases: none (미정). DATA-2 정리(admin 테스트 fixture revoke)는 release plan에 명시.
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 계획 편입
+
+#### Validation Plan
+- pytest로 AC-1~5 검증; CLI smoke + idempotency 회귀 + non-dry-run 거부 동작
@@ -0,0 +1,113 @@
+# REQ-025: POST /v1/portfolios 신설 (토큰 분기 + catalog 검증)
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio 생성 경로(`POST /v1/portfolios`)를 신설해 user/admin이 HTTP로 본인 또는 타 user의 portfolio를 직접 프로비저닝할 수 있도록 한다.
+- dcy-001 FR-4의 catalog 검증(asset_id active)을 portfolio 생성 시점에 통합 적용해 dcy-001 asset catalog 모델 위에서만 portfolio가 생성되도록 강제한다.
+
+## Requirement
+- 신규 라우트 `POST /v1/portfolios` (Bearer 인증 필수).
+- **토큰 분기 규칙** (dcy-003 OQ-2 + OQ-5 결정, dcy-004 정책과 정합):
+  - `token_type ∈ {service, client}` → HTTP 403 fail-closed (`detail="service token cannot create portfolios"` 또는 client 대응 메시지). service는 daemon-bound로 portfolio CRUD 주체가 아니며 client는 dcy-004 REQ-016에서 폐지 확정.
+  - 그 외(`token_type=session` 또는 env token):
+    - `permission='admin'` → admin 분기. body `user_id` non-null이면 해당 user의 portfolio로, null이면 인증 주체의 user_id로 생성.
+    - `permission ∈ {read, trade-write}` → user 분기. 인증 주체의 user_id로 생성. body `user_id` 지정은 무시 또는 HTTP 422.
+- **catalog 검증** (dcy-001 FR-4 통합): `asset_id`가 `assets` 테이블에 존재하고 `status='active'`인지 검증. 미등록/inactive면 dcy-001 FR-4와 일관된 응답 코드로 거부(HTTP 422 또는 403; REQ 단계 확정은 본 REQ 또는 후속 보강).
+- **body 스키마** (`PortfolioCreateRequest` 신규):
+  - 필수: `asset_id`, `broker`
+  - 선택: `name`, `cash_balance`, `asset_quantity`, `asset_price`, `profit_buffer`, `strategy_name`, `strategy_params`, `managed_by_daemon_id`, `user_id`(admin 분기 전용)
+- 응답: HTTP 201 + 생성된 portfolio의 `PortfolioItem`(`portfolio_id`, `asset_id`, `owner_user_id`, ...).
+- catalog 검증 위치(서비스 계층 공통 진입점 vs v1 라우터 레이어 한정)는 본 REQ 구현 시점에 결정. dcy-003 R-5 트레이드오프 reference 참조.
+
+## Acceptance Criteria
+1. Given admin token + body `{"asset_id": "<catalog-uuid>", "broker": "kiwoom", "user_id": "<target-user-uuid>"}`, When `POST /v1/portfolios`, Then HTTP 201 + 생성된 portfolio의 `owner_user_id == <target-user-uuid>` 반환.
+2. Given session/env token with `permission ∈ {read, trade-write}` + body `{"asset_id": ..., "broker": ...}`, When `POST /v1/portfolios`, Then HTTP 201 + `owner_user_id == auth.user_id` 반환.
+3. Given service token, When `POST /v1/portfolios`, Then HTTP 403 fail-closed + `detail="service token cannot create portfolios"`.
+4. Given client token(폐지 전 운영 단계), When `POST /v1/portfolios`, Then HTTP 403 fail-closed.
+5. Given body `asset_id`가 catalog에 미존재 또는 `status='inactive'`, When `POST /v1/portfolios`, Then HTTP 422 또는 403로 거부되고 portfolio row가 생성되지 않는다.
+6. Given Bearer token 없음, When `POST /v1/portfolios`, Then HTTP 401.
+7. Given non-admin token + body `user_id` 지정, When `POST /v1/portfolios`, Then `user_id`는 무시되어 `owner_user_id == auth.user_id`로 생성되거나 HTTP 422.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — POST /v1/portfolios 명세 추가 (REQ-032 baseline 작업)
+  - `docs/runtime-flows.md` — portfolio create flow + catalog 검증 단계 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` (신규) — POST /v1/portfolios 라우트, 토큰 분기 인증 헬퍼(`_require_portfolio_access`)
+  - `app/main.py` — v1_portfolios_router include
+  - `app/schemas/v1.py` — `PortfolioCreateRequest`, `PortfolioItem` 신규
+  - `app/services/portfolio_service.py:create_portfolio` — catalog 검증 통합(dcy-001 FR-4 정책)
+  - `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py` — `get_asset_by_id(asset_id, only_active=True)` 헬퍼(또는 직접 query) 추가
+- Tests:
+  - 신규 `tests/test_v1_portfolios_crud.py` — AC-1~7 검증
+
+## Notes
+- 본 REQ는 dcy-003 FR-1(생성) + FR-2(catalog 검증)을 통합. 생성 시점에 catalog 검증이 자연 적용되므로 단일 REQ로 분리.
+- catalog 검증 위치: dcy-003 §5 FR-2 본문에 "REQ 작성 단계에서 결정" 위임. R-5(CLI 회귀) 완화 방안을 참조해 본 REQ 구현 시 결정.
+- 토큰 분기 게이트는 dcy-004 REQ-016 client 폐지 이후 client 분기가 자연 사라지나, 폐지 release 이전·이후 모두 정합하도록 게이트 자체는 유지(env token 침투 방어).
+- daemon이 portfolio를 직접 생성하지 못함(OQ-2). v1 API에서 daemon의 권한은 조회(REQ-028)와 ledger 기록(REQ-029)에 한정.
+- Source: dcy-003 FR-1, FR-2, OQ-2, OQ-5, NFR-1, NFR-3, NFR-4. dcy-001 FR-4 통합.
+
+## Change Log
+
+### 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-1 + FR-2 통합 산출물.
+
+#### Intent
+- v1 portfolio mutation의 핵심 진입점(생성) + dcy-001 catalog 검증 통합.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~7 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md, docs/runtime-flows.md (REQ-032에서 처리)
+- Modules: app/api/v1_portfolios.py (신규), app/main.py, app/schemas/v1.py, app/services/portfolio_service.py, app/repositories/* — 최초 지정
+- Tests: tests/test_v1_portfolios_crud.py (신규) — 최초 지정
+
+#### 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 계획 편입; dcy-001 REQ-009/011/012 선행 의존성 확인(assets 테이블 + portfolios asset_id FK)
+
+#### Validation Plan
+- pytest TestClient로 AC-1~7 검증; 토큰 타입별·permission별 시나리오 + catalog hit/miss
@@ -0,0 +1,110 @@
+# REQ-026: PATCH /v1/portfolios/{portfolio_id} 신설
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio 부분 수정 경로(`PATCH /v1/portfolios/{portfolio_id}`)를 신설해 user/admin이 HTTP로 portfolio 속성(broker/status/name/symbol/strategy 등)을 직접 수정할 수 있도록 한다.
+- 토큰 분기 + ownership 검증을 REQ-025와 동일 패턴으로 적용해 v1 portfolio CRUD 인가 일관성을 확보한다.
+
+## Requirement
+- 신규 라우트 `PATCH /v1/portfolios/{portfolio_id}` (Bearer 인증 필수).
+- **토큰 분기 규칙** (REQ-025 + dcy-003 OQ-2/OQ-5 결정과 정합):
+  - `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+  - 그 외(`token_type=session` 또는 env token):
+    - `permission='admin'` → 모든 portfolio 수정 가능.
+    - `permission ∈ {read, trade-write}` → 자기 소유(`owner_user_id = auth.user_id`) portfolio만 수정 가능, 불일치 시 HTTP 403.
+- 비존재 portfolio는 HTTP 404.
+- 수정 가능 필드는 기존 `UpdatePortfolioRequest` 범위: `broker`, `status`, `name`, `symbol`, `strategy_name`, `strategy_params`, `asset_price`, `managed_by_daemon_id` 등.
+- **disabled portfolio 보호** (REQ-027 soft delete 정책 정합): `portfolios.status == 'disabled'`인 portfolio에 대해 status 전이(`'enabled'`로 복구) 외 다른 필드 변경 시 HTTP 409 또는 422로 거부.
+- 응답: HTTP 200 + 갱신된 `PortfolioItem`.
+
+## Acceptance Criteria
+1. Given admin token + 본인 또는 타 user portfolio, When `PATCH /v1/portfolios/{id}` body `{"strategy_name": "..."}`, Then HTTP 200 + 갱신된 portfolio 반환.
+2. Given session/env token with `permission ∈ {read, trade-write}` + 본인 portfolio, When `PATCH /v1/portfolios/{id}`, Then HTTP 200 + 갱신된 portfolio.
+3. Given session/env token with `permission ∈ {read, trade-write}` + 타 user portfolio, When `PATCH /v1/portfolios/{id}`, Then HTTP 403 (ownership 불일치).
+4. Given service token, When `PATCH /v1/portfolios/{id}`, Then HTTP 403 fail-closed.
+5. Given client token(폐지 전), When `PATCH /v1/portfolios/{id}`, Then HTTP 403 fail-closed.
+6. Given Bearer token 없음, When `PATCH /v1/portfolios/{id}`, Then HTTP 401.
+7. Given 비존재 `portfolio_id`, When `PATCH /v1/portfolios/{id}`, Then HTTP 404.
+8. Given `status='disabled'` portfolio + body `{"strategy_name": "..."}`(status 외 필드), When `PATCH`, Then HTTP 409 또는 422 (disabled write 차단).
+9. Given `status='disabled'` portfolio + body `{"status": "enabled"}` (admin), When `PATCH`, Then HTTP 200 + status 복구.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — PATCH /v1/portfolios/{id} 명세 추가 (REQ-032)
+  - `docs/runtime-flows.md` — portfolio update flow + ownership 검증 + disabled 보호 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — PATCH 라우트 추가 (REQ-025의 인증 헬퍼 재사용)
+  - `app/schemas/v1.py` — `PortfolioUpdateRequest` 신규 (기존 `UpdatePortfolioRequest` 재사용 또는 v1 전용 래핑)
+  - `app/services/portfolio_service.py:update_portfolio` — 기존 메서드 재사용 + disabled 보호 검증 추가
+- Tests:
+  - 신규/갱신 `tests/test_v1_portfolios_crud.py` — AC-1~9 검증
+
+## Notes
+- ownership 검증은 admin/user 분기 후 service 계층 또는 라우터에서 일관 처리. 본 REQ의 검증 위치는 REQ-025 catalog 검증 위치 결정과 함께 결정한다.
+- disabled portfolio 보호는 REQ-027(soft delete) 정책의 일부로, 본 REQ에서 PATCH 측면 검증을 명시. ledger trade/tag/comment 측면은 REQ-029/030/031에서 각각 처리.
+- 본 REQ는 dcy-003 FR-3 산출물이며 NFR-1/NFR-3/NFR-4를 검증 기준에 흡수.
+- Source: dcy-003 FR-3, OQ-2, OQ-5, NFR-1, NFR-3, NFR-4.
+
+## Change Log
+
+### 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-3 산출물.
+
+#### Intent
+- v1 portfolio mutation의 부분 수정 진입점 + ownership 검증 + disabled 보호.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~9 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md, docs/runtime-flows.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/schemas/v1.py, app/services/portfolio_service.py — 최초 지정
+- Tests: tests/test_v1_portfolios_crud.py — 최초 지정
+
+#### 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와 동일 batch 권장
+
+#### Validation Plan
+- pytest TestClient로 AC-1~9 검증; ownership·token type·disabled 보호 시나리오
@@ -0,0 +1,121 @@
+# REQ-027: DELETE /v1/portfolios/{portfolio_id} 신설 (soft delete)
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio 종료 경로(`DELETE /v1/portfolios/{portfolio_id}`)를 신설해 user/admin이 HTTP로 portfolio를 종료할 수 있도록 한다.
+- dcy-003 OQ-1 결정에 따라 soft delete(`status='disabled'`)로 구현해 데이터 보존성과 운영 복구 가능성을 확보한다. hard delete 경로는 v1에 노출하지 않는다.
+
+## Requirement
+- 신규 라우트 `DELETE /v1/portfolios/{portfolio_id}` (Bearer 인증 필수).
+- **토큰 분기 규칙** (REQ-025/026과 동일 패턴):
+  - `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+  - 그 외(`token_type=session` 또는 env token):
+    - `permission='admin'` → 모든 portfolio 삭제 가능.
+    - `permission ∈ {read, trade-write}` → 자기 소유(`owner_user_id = auth.user_id`) portfolio만, 불일치 시 HTTP 403.
+- **soft delete 동작**:
+  - `portfolios.status = 'disabled'`로 전환
+  - `managed_by_daemon_id`는 `NULL`로 자동 해제
+  - `updated_at` 갱신
+  - 의존 데이터(`portfolio_ledger`, `ledger_trades`, `portfolio_comments`, `portfolios.tag_ids`) 모두 보존
+- **disabled 상태 write 차단** (REQ-026/029/030/031에서도 검증되는 정책):
+  - `PATCH`(status 전이 외 필드 변경) → HTTP 409 또는 422
+  - `POST /ledger/trades` → 차단(REQ-029에서 처리)
+  - tag/comment 추가·수정·삭제 → 차단(REQ-030/031에서 처리)
+- **복구 경로**: admin이 `PATCH /v1/portfolios/{portfolio_id}` body `{"status": "enabled"}`(또는 이전 status)로 전환(REQ-026 AC-9). daemon 재배정은 별도 호출.
+- 비존재 `portfolio_id`는 HTTP 404. ownership 불일치는 HTTP 403.
+- 이미 `disabled` 상태인 portfolio에 재호출 시 HTTP 200 + 멱등 응답(또는 HTTP 409 — 본 REQ 구현 시 확정).
+- 응답: HTTP 200 또는 204 + (HTTP 200 시) disabled 상태 portfolio 또는 확정 응답.
+
+## Acceptance Criteria
+1. Given session token + 본인 active portfolio, When `DELETE /v1/portfolios/{id}`, Then HTTP 200/204 + `portfolios.status='disabled'` + `managed_by_daemon_id IS NULL` 사후 상태.
+2. Given AC-1 실행 후, When `portfolio_ledger`/`ledger_trades`/`portfolio_comments`/`portfolios.tag_ids` 조회, Then 의존 데이터가 모두 보존되어 있다.
+3. Given admin token + 타 user active portfolio, When `DELETE /v1/portfolios/{id}`, Then HTTP 200/204 + 동일 사후 상태.
+4. Given session token + 타 user portfolio, When `DELETE /v1/portfolios/{id}`, Then HTTP 403 (ownership 불일치).
+5. Given service token, When `DELETE /v1/portfolios/{id}`, Then HTTP 403 fail-closed.
+6. Given client token(폐지 전), When `DELETE /v1/portfolios/{id}`, Then HTTP 403 fail-closed.
+7. Given Bearer token 없음, When `DELETE /v1/portfolios/{id}`, Then HTTP 401.
+8. Given 비존재 `portfolio_id`, When `DELETE /v1/portfolios/{id}`, Then HTTP 404.
+9. Given disabled portfolio + admin `PATCH status='enabled'`, When `PATCH`, Then HTTP 200 + 복구. (REQ-026 AC-9와 연계)
+10. Given AC-1 실행 후 disabled portfolio에 ledger trade/tag/comment write 시도, When 시도, Then 모두 차단(HTTP 409 또는 422). (REQ-029/030/031과 연계 검증)
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — DELETE /v1/portfolios/{id} 명세 (REQ-032)
+  - `docs/runtime-flows.md` — soft delete flow + disabled write 차단 + 복구 (REQ-032)
+  - `docs/data-model.md` — Portfolio.status='disabled' 의미 + 의존 데이터 보존 정책 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — DELETE 라우트
+  - `app/services/portfolio_service.py:delete` — 기존 메서드 재사용 시 soft delete로 변경 또는 신규 `soft_delete_portfolio` 헬퍼
+  - `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py` — `set_portfolio_status(portfolio_id, status, clear_daemon=True)` 메서드 신규 또는 기존 `update_portfolio` 활용
+- Tests:
+  - 신규/갱신 `tests/test_v1_portfolios_crud.py` — AC-1~10 검증
+
+## Notes
+- dcy-003 R-2(disabled 누적 가시성·write 차단 일관성)는 본 REQ + REQ-028 `?include_disabled` opt-in 정책 + REQ-026/029/030/031의 차단 검증으로 함께 완화.
+- 누적 disabled 정리(아카이브, 영구 삭제 운영 SOP)는 본 Discovery 범위 밖. 별도 운영 Discovery로 위임.
+- 본 REQ는 hard delete 경로를 v1에 노출하지 않으므로 hard 삭제 운영은 DB 직접 접근 또는 별도 운영 도구로만 가능.
+- Source: dcy-003 FR-4, OQ-1, OQ-2, OQ-5, NFR-1, NFR-3, NFR-4.
+
+## Change Log
+
+### 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-4 산출물.
+
+#### Intent
+- v1 portfolio 종료 경로 + soft delete 정책 명시.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~10 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md, docs/runtime-flows.md, docs/data-model.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/services/portfolio_service.py, app/repositories/* — 최초 지정
+- Tests: tests/test_v1_portfolios_crud.py — 최초 지정
+
+#### 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/026과 동일 batch 권장
+
+#### Validation Plan
+- pytest TestClient로 AC-1~10 검증; soft delete 사후 상태 + 의존 데이터 보존 + 복구 경로 + write 차단 일관성
@@ -0,0 +1,116 @@
+# REQ-028: GET /v1/portfolios 신설 (토큰 분기 조회)
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio 조회 경로(`GET /v1/portfolios`)를 신설해 service/user/admin 세 principal이 단일 엔드포인트로 분기 조회할 수 있도록 한다.
+- dcy-001 FR-5(REQ-013 Deprecated 처리)에서 회수된 `GET /v1/assets` 통합 endpoint 정의를 본 신규 path로 이전한다(dcy-003 옵션 B 결정).
+
+## Requirement
+- 신규 라우트 `GET /v1/portfolios` (Bearer 인증 필수).
+- **토큰 분기 규칙** (dcy-003 OQ-5 결정):
+  - `token_type='service'`: daemon-bound 조회. `daemon_id is None`이면 HTTP 403 fail-closed. 그 외 `managed_by_daemon_id = auth.daemon_id` 필터 + `?market=<code>` 지원.
+  - `token_type='client'`: HTTP 403 fail-closed (dcy-004 REQ-016 폐지 확정 정합).
+  - `token_type ∈ {session, None(env)}`:
+    - `permission='admin'` → 기본 `owner_user_id = auth.user_id`(본인 portfolio) 반환. `?user_id=<id>` 지정 시 해당 user의 portfolio 반환.
+    - `permission ∈ {read, trade-write}` → `owner_user_id = auth.user_id` 필터, 본인 portfolio만 반환.
+- **`?market=<code>` 필터**: 모든 토큰 타입에서 지원. `<code> = ANY(assets.markets)`인 portfolio만 반환(catalog와 join).
+- **`?include_disabled=true` 옵션** (dcy-003 R-2 완화): 기본 응답은 `status='disabled'`인 portfolio 제외. opt-in 시에만 포함.
+- 응답 항목 schema: 신규 `PortfolioItem` (`portfolio_id`, `asset_id`, `owner_user_id`, `broker`, `status`, `cash_balance`, ..., `tag_ids`, `managed_by_daemon_id`, ...). `asset_id`는 catalog의 `assets.asset_id`(UUID) 참조.
+- 응답: HTTP 200 + `PortfolioListResponse` (`portfolios: list[PortfolioItem]`, `total: int`).
+
+## Acceptance Criteria
+1. Given service token(daemon-bound, `daemon_id` 있음), When `GET /v1/portfolios`, Then `managed_by_daemon_id = auth.daemon_id`인 portfolio 목록만 반환.
+2. Given service token(`daemon_id` 없음), When `GET /v1/portfolios`, Then HTTP 403 fail-closed.
+3. Given session/env token + `permission ∈ {read, trade-write}`, When `GET /v1/portfolios`, Then `owner_user_id = auth.user_id`인 portfolio 목록만 반환.
+4. Given admin token (no `?user_id`), When `GET /v1/portfolios`, Then admin 본인의 portfolio 목록 반환.
+5. Given admin token + `?user_id=<target>`, When `GET /v1/portfolios`, Then `<target>` user의 portfolio 목록 반환.
+6. Given 임의 토큰 + `?market=KRX`, When `GET /v1/portfolios?market=KRX`, Then `'KRX' = ANY(assets.markets)`인 portfolio만 반환.
+7. Given disabled portfolio 1건 + active portfolio 1건 보유 user, When `GET /v1/portfolios` (`?include_disabled` 없음), Then active 1건만 반환.
+8. Given AC-7 환경 + `?include_disabled=true`, When `GET /v1/portfolios?include_disabled=true`, Then 2건 모두 반환.
+9. Given client token, When `GET /v1/portfolios`, Then HTTP 403 fail-closed.
+10. Given Bearer token 없음, When `GET /v1/portfolios`, Then HTTP 401.
+11. Given 응답 portfolio 항목, When `asset_id` 필드 확인, Then `assets.asset_id`(catalog UUID)를 참조한다.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — GET /v1/portfolios 명세 + `?market`/`?user_id`/`?include_disabled` 파라미터 (REQ-032)
+  - `docs/runtime-flows.md` — 토큰 분기 조회 flow + daemon-scoped 필터 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — GET 라우트 (REQ-025의 인증 헬퍼 재사용 + GET 전용 service 토큰 분기 추가)
+  - `app/api/v1_assets.py` — 기존 `list_assets` 함수에서 portfolio 조회 로직 제거(catalog 전용 회수). REQ-013 Deprecated 후속 정리.
+  - `app/schemas/v1.py` — `PortfolioItem`, `PortfolioListResponse` 신규
+  - `app/services/portfolio_service.py:list_portfolios` — token-type별 분기 + `?market`/`?include_disabled` 처리. dcy-001 REQ-013 Deprecated 후속 작업 흡수.
+  - `app/repositories/postgres.py:list_portfolios_with_strategies` — `managed_by_daemon_id` 필터 + `markets` array 필터 + `include_disabled` 분기
+- Tests:
+  - 신규 `tests/test_v1_portfolios_list.py` — AC-1~11 검증
+
+## Notes
+- 본 REQ는 dcy-001 REQ-013 Deprecated(CHG-20260520-01)의 후속 신규 REQ. 토큰 분기 정책은 REQ-013의 본문을 path만 변경해 흡수.
+- `GET /v1/assets`(catalog 조회 의미)는 본 REQ 범위 밖이며 dcy-001 batch design 단계에서 REQ-010 보강 또는 신규 REQ로 처리.
+- service token이 NULL `daemon_id`로 호출하면 fail-closed. NULL daemon legacy token 운영 정리는 dcy-004 REQ-023(`migrate-null-daemon` CLI)로 처리.
+- `?include_disabled` 기본 false 정책은 R-2 완화의 핵심. REQ-027 soft delete와 정합.
+- Source: dcy-003 FR-5, OQ-5, NFR-1, NFR-3, R-2 완화. dcy-001 REQ-013 후속.
+
+## Change Log
+
+### 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-5 산출물 + REQ-013 Deprecated 후속.
+
+#### Intent
+- v1 portfolio 조회 신설 + 토큰 분기 정책 path 이전 + R-2 disabled 가시성 완화.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~11 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md, docs/runtime-flows.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/api/v1_assets.py(catalog 회수), app/schemas/v1.py, app/services/portfolio_service.py, app/repositories/postgres.py — 최초 지정
+- Tests: tests/test_v1_portfolios_list.py (신규) — 최초 지정
+
+#### 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 계획 편입; dcy-001 REQ-013 Deprecated 정리 후속
+
+#### Validation Plan
+- pytest TestClient로 AC-1~11 검증; 토큰 분기 + `?market` + `?user_id` + `?include_disabled` 시나리오
@@ -0,0 +1,112 @@
+# REQ-029: POST /v1/portfolios/{portfolio_id}/ledger/trades 이전
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- 기존 `POST /v1/assets/{asset_id}/ledger/trades`(`app/api/v1_ledger.py`)의 path param 이름이 `asset_id`이나 실제 값은 `portfolios.portfolio_id`(UUID)로 의미 혼용되는 결함을 해소한다.
+- dcy-003 옵션 B(path 명명 분리)에 따라 신 path `POST /v1/portfolios/{portfolio_id}/ledger/trades`로 이전하고 구 path는 동일 release에서 제거한다. 동작·인가·idempotency는 그대로 보존.
+
+## Requirement
+- 신규 라우트 `POST /v1/portfolios/{portfolio_id}/ledger/trades` (Bearer 인증 필수).
+- **동작은 기존 `POST /v1/assets/{asset_id}/ledger/trades`와 동일하게 보존**:
+  - **daemon assignment 3단계 fail-closed 인가**: (1) token `daemon_id IS NULL` → HTTP 403, (2) portfolio `managed_by_daemon_id IS NULL`(미배정 asset) → HTTP 403, (3) `portfolio.managed_by_daemon_id != auth.daemon_id`(불일치) → HTTP 403.
+  - **idempotency**: `(portfolio_id, order_id, execution_id)` unique constraint (기존 `uq_ledger_trades_idempotency` 재사용).
+  - **duplicate/conflict 응답**: 동일 키 + 동일 payload → HTTP 200 + `status="duplicate"`. 동일 키 + 다른 payload → HTTP 409.
+  - **새 ledger row** → HTTP 201 + `status="new"`.
+- **disabled portfolio 차단** (REQ-027 정합): `portfolios.status='disabled'`인 portfolio에 대해서는 HTTP 409 또는 422로 차단.
+- 구 path `POST /v1/assets/{asset_id}/ledger/trades` 제거: 동일 batch release에서 라우트 삭제. 호출 시 HTTP 404.
+- **trex-basic 동시 배포 필수** (dcy-003 OQ-3 + NFR-2): 신 path 단일 서빙. 한시적 별칭/redirect 없음. release plan에 배포 순서 잠금(trex-basic 클라이언트 사전 빌드 → portfolio-hub 배포 → trex-basic 배포) + rollback 시 trex-basic 동반 rollback 전제 명시.
+
+## Acceptance Criteria
+1. Given service token + 본인 daemon에 배정된 active portfolio + 신규 trade payload, When `POST /v1/portfolios/{portfolio_id}/ledger/trades`, Then HTTP 201 + `status="new"` + 생성된 ledger row.
+2. Given AC-1 실행 후 동일 key + 동일 payload 재호출, When 호출, Then HTTP 200 + `status="duplicate"` + 단일 ledger row 유지.
+3. Given AC-1 실행 후 동일 key + 다른 payload 호출, When 호출, Then HTTP 409 + ledger row 변경 없음.
+4. Given service token `daemon_id IS NULL`, When `POST /v1/portfolios/{portfolio_id}/ledger/trades`, Then HTTP 403 fail-closed.
+5. Given service token + `portfolio.managed_by_daemon_id IS NULL`(미배정 asset), When 호출, Then HTTP 403 fail-closed.
+6. Given service token + `portfolio.managed_by_daemon_id != auth.daemon_id`(불일치), When 호출, Then HTTP 403 fail-closed.
+7. Given service token + `status='disabled'` portfolio, When 호출, Then HTTP 409 또는 422 (disabled write 차단).
+8. Given 비존재 `portfolio_id`, When 호출, Then HTTP 404.
+9. Given 구 path `POST /v1/assets/{asset_id}/ledger/trades` 호출, When 본 REQ 구현 후 동일 batch release, Then HTTP 404.
+10. Given Bearer token 없음, When 호출, Then HTTP 401.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — POST /v1/portfolios/{id}/ledger/trades 명세 + 구 path 제거 (REQ-032)
+  - `docs/runtime-flows.md` — daemon assignment 3단계 인가 + idempotency + path 이전 흐름 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — `POST /v1/portfolios/{portfolio_id}/ledger/trades` 라우트 추가 (또는 별도 `v1_ledger.py`를 신 path로 이전)
+  - `app/api/v1_ledger.py` — 구 path 제거 또는 신 path로 라우트 prefix 이전
+  - `app/main.py` — 라우터 include 갱신 (구 ledger 라우터 제거)
+  - `app/services/portfolio_service.py` 또는 `app/services/ledger_service.py` — 기존 ledger trade 로직 재사용 + disabled 차단 검증 추가
+- Tests:
+  - 갱신 `tests/test_v1.py` — 구 path 케이스를 신 path로 갱신, 구 path 호출 시 HTTP 404 확인
+  - 신규 `tests/test_v1_portfolios_ledger.py` — AC-1~10 검증
+
+## Notes
+- 본 REQ는 기능 추가가 아닌 **path 이전**이라 기존 동작·테스트 시나리오를 그대로 재사용한다. 다만 disabled portfolio 차단(AC-7)은 REQ-027 soft delete 정책 정합 검증으로 신규.
+- dcy-003 NFR-2(trex-basic 동시 배포)는 본 REQ의 가장 큰 운영 리스크(R-1)이며, release plan에 배포 순서 잠금·rollback 전제를 명시해야 함. release plan은 batch design/release 단계 작업.
+- ledger_trades 테이블의 `asset_id` 컬럼명은 본 REQ에서 변경하지 않는다(dcy-001 `assets.asset_id`와 의미 혼용이 잔존하나, ledger_trades 컬럼은 portfolio_id를 가리킨다는 점이 path 이름 정합화로 충분히 명확해짐). 컬럼명 변경은 별도 migration REQ로 분리 가능.
+- Source: dcy-003 FR-6, OQ-3, NFR-1, NFR-2, R-1 완화.
+
+## Change Log
+
+### 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-6 산출물.
+
+#### Intent
+- ledger trade path 명명 정합화 + 동시 배포 정책 명시 + disabled 차단 추가.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~10 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md, docs/runtime-flows.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/api/v1_ledger.py(제거 또는 이전), app/main.py, app/services/* — 최초 지정
+- Tests: tests/test_v1.py(갱신), tests/test_v1_portfolios_ledger.py(신규) — 최초 지정
+
+#### Delivery Trace Delta
+- Batches: none (미정)
+- Releases: none (미정). trex-basic 동시 배포 release plan은 batch design 단계에서 작성.
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 계획 편입; trex-basic 측 release readiness(DATA_TREX_BASIC_RELEASE_WINDOW) 외부 확인 필요
+
+#### Validation Plan
+- pytest TestClient로 AC-1~10 검증; 신·구 path 회귀 + daemon 인가 3단계 + idempotency·conflict + disabled 차단
@@ -0,0 +1,116 @@
+# REQ-030: portfolio tag 적용/해제/조회 v1 라우트
+
+- Status: Approved
+- Type: Interface
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio tag 적용·해제·조회 경로(`/v1/portfolios/{portfolio_id}/tags`)를 신설해 user/admin이 HTTP로 portfolio에 태그를 적용·관리할 수 있도록 한다.
+- dcy-002 FR-3 portfolios.tag_ids 정책(`tags.is_admin_tag=TRUE` 또는 `tags.created_by_user_id = portfolio.owner_user_id`)을 v1 라우트에 일관 적용해 태그 적용 정책 위반을 fail-closed로 거부한다.
+
+## Requirement
+- 신규 라우트 (Bearer 인증 필수):
+  - `POST /v1/portfolios/{portfolio_id}/tags` — body: `{"tag_id": "<uuid>"}`. 응답 HTTP 201 + 적용된 tag 정보.
+  - `DELETE /v1/portfolios/{portfolio_id}/tags/{tag_id}` — 응답 HTTP 200 또는 204.
+  - `GET /v1/portfolios/{portfolio_id}/tags` — 응답 HTTP 200 + 해당 portfolio에 적용된 tag 목록.
+- **ownership 규칙** (REQ-026과 동일):
+  - `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+  - `permission='admin'` → 모든 portfolio.
+  - `permission ∈ {read, trade-write}` → 자기 소유 portfolio만, 불일치 시 HTTP 403.
+- **dcy-002 FR-3 태그 적용 정책 검증** (POST 시): `tags.is_active=TRUE`이고 (`tags.is_admin_tag=TRUE` 또는 `tags.created_by_user_id = portfolio.owner_user_id`)인 경우에만 적용 허용. 정책 위반 시 HTTP 403.
+- **disabled portfolio 차단** (REQ-027 정합): `status='disabled'`인 portfolio에 대해 POST/DELETE는 HTTP 409 또는 422로 거부. GET은 허용(`?include_disabled=true` 별도 제어 불필요 — GET tag는 항상 조회 가능).
+- 비존재 `portfolio_id` 또는 `tag_id`는 HTTP 404.
+- tag 적용 후 portfolio의 `tag_ids` UUID 배열에 추가(dcy-002 portfolios.tag_ids 스키마 반영). 중복 적용은 HTTP 409 또는 멱등 200 (REQ 구현 시 확정).
+
+## Acceptance Criteria
+1. Given session token + 본인 active portfolio + admin이 생성한 active tag, When `POST /v1/portfolios/{id}/tags` body `{"tag_id": ...}`, Then HTTP 201 + portfolio.tag_ids 배열에 tag_id 추가.
+2. Given session token + 본인 portfolio + 본인이 생성한 active tag, When `POST`, Then HTTP 201.
+3. Given session token + 본인 portfolio + 타 user 생성한 non-admin tag, When `POST`, Then HTTP 403 (dcy-002 FR-3 정책 위반).
+4. Given session token + 본인 portfolio + `tags.is_active=FALSE` tag, When `POST`, Then HTTP 403 (비활성 tag 적용 불가).
+5. Given admin token + 타 user portfolio + 임의 active tag, When `POST`, Then dcy-002 정책 그대로 적용(admin tag 또는 portfolio.owner 생성 tag만 허용). 위반 시 HTTP 403.
+6. Given session token + 타 user portfolio, When `POST`, Then HTTP 403 (ownership 불일치).
+7. Given service/client token, When `POST`, Then HTTP 403 fail-closed.
+8. Given session token + disabled portfolio, When `POST` 또는 `DELETE`, Then HTTP 409 또는 422.
+9. Given session token + 본인 portfolio + 적용된 tag, When `DELETE /v1/portfolios/{id}/tags/{tag_id}`, Then HTTP 200/204 + portfolio.tag_ids 배열에서 제거.
+10. Given session token + 본인 portfolio, When `GET /v1/portfolios/{id}/tags`, Then HTTP 200 + 해당 portfolio에 적용된 tag 목록 반환.
+11. Given 비존재 `portfolio_id` 또는 `tag_id`, When 호출, Then HTTP 404.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — `/v1/portfolios/{id}/tags` 명세 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — tag 서브 라우트 추가
+  - `app/schemas/v1.py` — `PortfolioTagApplyRequest`, `PortfolioTagResponse` 신규
+  - `app/services/portfolio_service.py:add_tag`/`remove_tag`/`list_tags` — dcy-002 FR-3 정책 검증 추가
+  - `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py` — `apply_tag(portfolio_id, tag_id)`, `remove_tag`, `list_tags` 메서드 (dcy-002 REQ-003 portfolios.tag_ids 배열 처리와 정합)
+- Tests:
+  - 신규 `tests/test_v1_portfolios_tags_comments.py` — AC-1~11 (tag 부분)
+
+## Notes
+- dcy-002 REQ-001(tags 마스터)·REQ-003(portfolios.tag_ids) 선행 필요. dcy-002 REQ가 모두 Approved 상태이므로 batch design 단계에서 의존성 순서 명시.
+- 본 REQ의 tag 적용 정책 검증은 dcy-002 FR-3 본문을 그대로 채택. dcy-002 REQ-005(태그 적용·해제 HTTP API)와 본 REQ의 범위 경계는 다음과 같이 분리:
+  - dcy-002 REQ-005: `/v1/portfolios/{id}/tags` 적용 정책 정의 + 일반 portfolio 측면
+  - 본 REQ: v1 portfolio mutation surface 내에서의 라우트·ownership·disabled 통합 검증
+  - 본 REQ가 dcy-002 REQ-005를 흡수하거나 보강하는 형태로 batch design 단계에서 결정.
+- Source: dcy-003 FR-7, dcy-002 FR-3.
+
+## Change Log
+
+### 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-7 산출물.
+
+#### Intent
+- v1 portfolio tag 적용/해제/조회 라우트 신설 + dcy-002 tag 정책 v1 일관 적용.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~11 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/schemas/v1.py, app/services/portfolio_service.py, app/repositories/* — 최초 지정
+- Tests: tests/test_v1_portfolios_tags_comments.py — 최초 지정
+
+#### 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 계획 편입; dcy-002 REQ-001/003/005 선행 의존성 + 본 REQ와의 범위 경계 확정
+
+#### Validation Plan
+- pytest TestClient로 AC-1~11 검증; ownership + dcy-002 tag 정책 위반 + disabled 차단 시나리오
@@ -0,0 +1,113 @@
+# REQ-031: portfolio comment CRUD v1 라우트
+
+- Status: Approved
+- Type: Interface
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- v1 API에 portfolio comment CRUD 경로(`/v1/portfolios/{portfolio_id}/comments`)를 신설해 user/admin이 HTTP로 portfolio에 코멘트를 작성·관리할 수 있도록 한다.
+- ownership 규칙과 disabled 차단을 REQ-026/027과 동일 패턴으로 적용해 v1 portfolio surface 인가 일관성을 확보한다.
+
+## Requirement
+- 신규 라우트 (Bearer 인증 필수):
+  - `POST /v1/portfolios/{portfolio_id}/comments` — body: `{"content": "<text>"}`. 응답 HTTP 201 + 생성된 comment.
+  - `GET /v1/portfolios/{portfolio_id}/comments` — 응답 HTTP 200 + comment 목록(created_at desc 순).
+  - `PATCH /v1/portfolios/{portfolio_id}/comments/{comment_id}` — body: `{"content": "<updated>"}`. 응답 HTTP 200 + 갱신된 comment.
+  - `DELETE /v1/portfolios/{portfolio_id}/comments/{comment_id}` — 응답 HTTP 200 또는 204.
+- **ownership 규칙** (REQ-026/030과 동일):
+  - `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+  - `permission='admin'` → 모든 portfolio.
+  - `permission ∈ {read, trade-write}` → 자기 소유 portfolio만, 불일치 시 HTTP 403.
+- **disabled portfolio 차단** (REQ-027 정합): `status='disabled'`인 portfolio에 대해 POST/PATCH/DELETE는 HTTP 409 또는 422로 거부. GET은 허용.
+- 비존재 `portfolio_id` 또는 `comment_id`는 HTTP 404.
+- 기존 `CommentCreateRequest`/`CommentUpdateRequest`/`CommentResponse` schema 재사용 또는 v1 전용 래핑(`PortfolioCommentRequest`, `PortfolioCommentResponse`).
+- 기존 service 메서드(`create_comment`, `list_comments`, `update_comment`, `delete_comment`) 재사용.
+
+## Acceptance Criteria
+1. Given session token + 본인 active portfolio, When `POST /v1/portfolios/{id}/comments` body `{"content": "..."}`, Then HTTP 201 + 생성된 comment.
+2. Given session token + 본인 portfolio + 적용된 comments, When `GET /v1/portfolios/{id}/comments`, Then HTTP 200 + 코멘트 목록(created_at desc).
+3. Given session token + 본인 portfolio + 본인 comment, When `PATCH /v1/portfolios/{id}/comments/{comment_id}` body `{"content": "..."}`, Then HTTP 200 + 갱신된 comment.
+4. Given session token + 본인 portfolio + 본인 comment, When `DELETE /v1/portfolios/{id}/comments/{comment_id}`, Then HTTP 200/204.
+5. Given session token + 타 user portfolio, When 임의 동사 호출, Then HTTP 403 (ownership 불일치).
+6. Given service/client token, When 임의 동사 호출, Then HTTP 403 fail-closed.
+7. Given session token + disabled portfolio, When `POST`/`PATCH`/`DELETE`, Then HTTP 409 또는 422.
+8. Given session token + disabled portfolio, When `GET /v1/portfolios/{id}/comments`, Then HTTP 200 + 기존 comments 목록 반환(조회는 허용).
+9. Given admin token + 타 user portfolio, When 임의 동사 호출, Then HTTP 200/201/204 (admin은 모든 portfolio 허용).
+10. Given Bearer token 없음, When 호출, Then HTTP 401.
+11. Given 비존재 `portfolio_id` 또는 `comment_id`, When 호출, Then HTTP 404.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — `/v1/portfolios/{id}/comments` 명세 (REQ-032)
+- Modules:
+  - `app/api/v1_portfolios.py` — comment 서브 라우트 추가
+  - `app/schemas/v1.py` — comment 관련 스키마 (기존 `app/schemas/portfolio.py:CommentCreateRequest`/`CommentUpdateRequest`/`CommentResponse` 재사용 또는 v1 래핑)
+  - `app/services/portfolio_service.py:create_comment`/`list_comments`/`update_comment`/`delete_comment` — 기존 메서드 재사용 + disabled 차단 검증 추가
+- Tests:
+  - 신규/갱신 `tests/test_v1_portfolios_tags_comments.py` — AC-1~11 (comment 부분)
+
+## Notes
+- comment 작성자 ownership(본인 comment만 수정/삭제 가능)은 기존 portfolio_comments 테이블 구조에 따라 처리. dcy-003 본문은 portfolio ownership만 명시하고 comment 작성자 ownership은 별도 결정 사항 — 본 REQ에서는 portfolio ownership을 일관 적용하고 comment 작성자 ownership은 batch design 단계에서 확정.
+- 본 REQ는 dcy-003 FR-8 산출물. tag(REQ-030)와 별도 REQ로 분리해 동사 surface를 명확히 함.
+- Source: dcy-003 FR-8, NFR-1, NFR-3, NFR-4.
+
+## Change Log
+
+### 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-8 산출물.
+
+#### Intent
+- v1 portfolio comment CRUD 라우트 신설 + ownership/disabled 검증 일관 적용.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~11 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.md (REQ-032)
+- Modules: app/api/v1_portfolios.py, app/schemas/v1.py, app/services/portfolio_service.py — 최초 지정
+- Tests: tests/test_v1_portfolios_tags_comments.py — 최초 지정
+
+#### 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 계획 편입; comment 작성자 ownership 정책은 batch design 단계에서 확정
+
+#### Validation Plan
+- pytest TestClient로 AC-1~11 검증; ownership + disabled 차단 + admin 분기 시나리오