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
@@ -0,0 +1,110 @@
+# REQ-019: 토큰 surface baseline 문서 정합성 회복
+
+- Status: Approved
+- Type: Documentation
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- 현행 baseline 문서가 토큰 surface 결함(rebind 명세 누락, AuthContext daemon_id 필드 누락) + 본 batch 변경 사항(client token 폐지, rotate index 보강, HTTP daemon_id forward, auth_tokens 인덱스 변경)을 모두 반영해 후속 REQ·batch가 단일 source of truth로 사용할 수 있도록 정합성을 회복한다.
+- dcy-004 FR-4와 FR-10을 단일 REQ로 통합 처리한다(둘 다 baseline 갱신 작업).
+
+## Requirement
+- `docs/interface-contract.md` 갱신:
+  - `pfhub service-token rebind` CLI 명세 추가([app/cli/commands/service_tokens.py:119-141](app/cli/commands/service_tokens.py#L119-L141) 구현 반영)
+  - `POST /auth/tokens`(client token 발급) 명세 제거(REQ-016 처리 반영)
+  - `POST /auth/service-tokens` body `daemon_id` forward 동작 명시(REQ-018 처리 반영)
+- `docs/runtime-flows.md` 갱신:
+  - `AuthContext` 필드 목록에 `daemon_id` 추가([docs/runtime-flows.md:76](docs/runtime-flows.md#L76) 보강)
+  - 토큰 surface 3종(session/service/env)으로 축소 반영
+  - rotate runtime_id 갱신 + daemon_id invariant 보존 흐름 명시(REQ-017 처리 반영)
+- `docs/data-model.md` 갱신:
+  - `auth_tokens` 인덱스 변경(`idx_auth_tokens_service_name_unique`에 `AND revoked_at IS NULL` 조건 추가) 반영
+  - 토큰 타입 surface 정리(client 제거)
+- `docs/project-structure.md` 갱신:
+  - 신규 마이그레이션 스크립트 또는 CLI 서브커맨드(REQ-022 자동 revoke, REQ-023 NULL daemon 마이그레이션) 추가에 따른 패키지 책임 갱신 — 필요 시
+- 갱신은 baseline 정합성 회복에 한정한다. 새 정책 정의(매트릭스, TTL 정책, SOP)는 REQ-020/021/024가 별도로 다룬다.
+
+## Acceptance Criteria
+1. Given `grep -n "service-token rebind" docs/interface-contract.md`, When 본 REQ 구현 후, Then 명세 entry가 1건 이상 발견된다.
+2. Given `grep -n "POST /auth/tokens" docs/interface-contract.md`, When 본 REQ 구현 후, Then client token 발급 명세가 제거되어 0건이거나 deprecated 표시로만 잔존한다.
+3. Given `grep -n "AuthContext.*daemon_id\|daemon_id.*AuthContext" docs/runtime-flows.md`, When 본 REQ 구현 후, Then `AuthContext` 필드 목록에 `daemon_id`가 명시된다.
+4. Given `grep -n "revoked_at IS NULL\|active service token" docs/data-model.md`, When 본 REQ 구현 후, Then `idx_auth_tokens_service_name_unique` 변경 사항이 반영되어 발견된다.
+5. Given 사람 리뷰, When baseline 4종 문서를 점검, Then client token 잔재(예: `token_type='client'` 발급 경로 언급)가 모두 제거되거나 deprecated 표시되어 있다.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md`
+  - `docs/runtime-flows.md`
+  - `docs/data-model.md`
+  - `docs/project-structure.md` (필요 시)
+- Modules: 없음 (문서 전용)
+- Tests: 없음 (문서 전용. AC-1~5는 grep + 사람 리뷰)
+
+## Notes
+- 본 REQ는 REQ-016/017/018/022/023 코드 변경 후 또는 동일 batch에서 함께 처리하는 것이 적절하다. baseline 문서가 코드 변경 사항을 반영하지 않으면 후속 REQ/batch가 잘못된 source of truth를 참조한다.
+- 본 REQ는 surface 정합성 회복만 다루고 신규 정책 명세는 다음 REQ에서 처리:
+  - REQ-020: 토큰 발급 권한 매트릭스
+  - REQ-021: 토큰 만료·회전 정책
+  - REQ-024: env admin token 운영 SOP
+- Source: dcy-004 FR-4, dcy-004 FR-10.
+
+## 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-4 + FR-10 통합 산출물.
+
+#### Intent
+- 토큰 surface baseline 4종 문서의 정합성 회복(rebind 명세 누락, AuthContext daemon_id 누락, client token 잔재 제거, auth_tokens 인덱스 변경 반영).
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### 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-016/017/018/022/023 코드 변경 후 또는 동일 batch에서 처리
+
+#### Validation Plan
+- grep 명령 + 사람 리뷰로 AC-1~5 검증
@@ -0,0 +1,93 @@
+# REQ-020: 토큰 발급 권한 매트릭스 정의
+
+- Status: Approved
+- Type: Documentation
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- 누가 어떤 token type을 발급/회전/폐기할 수 있는가가 현재 코드에 흩어진 dependency(require_admin/require_read)로만 표현되고 baseline 문서에 없어 운영 일관성과 정책 추적이 어렵다. 토큰 발급 권한 매트릭스를 baseline에 명시해 정책 source of truth를 확보한다.
+
+## Requirement
+- `docs/interface-contract.md`에 "토큰 발급 권한 매트릭스" 섹션을 추가한다. 매트릭스 차원: token type(session / service / env) × 발급 동사(issue / rotate / rebind / revoke / list) × 발급자 권한(admin / trade-write / read).
+- client token은 REQ-016에서 폐지되므로 표에서 제거한다.
+- admin 자기 발급 정책 명시: admin이 본인 user_id 대상으로 daemon-bound 또는 unbound service token 발급 가능(dcy-004 OQ-4 결정). 매트릭스 주석에 "관행상 최소 권한 발급 권장" 명시.
+- 매트릭스 위반 호출은 HTTP 403 fail-closed로 통일한다(dcy-004 NFR-4).
+- 매트릭스 정의는 현행 코드 dependency(require_admin/require_read, AuthService 발급 메서드의 분기 로직)와 1:1 매핑되어야 한다. 불일치 시 본 REQ가 우선이며 코드 보정은 REQ-018 또는 별도 후속에서 처리.
+
+## Acceptance Criteria
+1. Given `docs/interface-contract.md` 검토, When 본 REQ 구현 후, Then "토큰 발급 권한 매트릭스" 섹션이 존재하고 token type 3종(session/service/env) × 발급 동사 5종(issue/rotate/rebind/revoke/list) × 발급자 권한 3종(admin/trade-write/read) 조합이 모두 명시된다.
+2. Given 매트릭스의 admin 자기 발급 정책 항목, When 본 REQ 구현 후 검토, Then admin이 본인 user_id로 service token 발급 가능함이 명시되고 최소 권한 권장 주석이 포함된다.
+3. Given 매트릭스 위반 호출 정책, When 본 REQ 구현 후 검토, Then 모든 위반 호출에 HTTP 403 fail-closed 응답이 명시된다.
+4. Given 매트릭스와 현행 코드 dependency(`require_admin`/`require_read`) 매핑, When 사람 리뷰, Then 1:1 매핑이 확인되고 불일치 항목은 별도 follow-up으로 기록된다.
+
+## Impacted Area
+- Docs:
+  - `docs/interface-contract.md` — "토큰 발급 권한 매트릭스" 섹션 신규 추가
+- Modules: 없음 (문서 전용. 코드 dependency 불일치 발견 시 별도 REQ 또는 REQ-018 보강)
+- Tests: 없음 (문서 전용. NFR-4 위반 호출 403 검증은 REQ-016/018/022 등 코드 REQ의 회귀 테스트에 포함)
+
+## Notes
+- 본 REQ는 매트릭스 baseline 문서화만 다룬다. 매트릭스 위반 호출의 코드 레벨 enforcement는 기존 dependency 체계로 충분하며 본 REQ에서는 정책 정의만 한다.
+- env admin token의 회전 주기·강도 가이드는 REQ-024(env admin SOP)가 별도로 다룬다. 본 REQ는 발급 권한 매트릭스에만 집중한다.
+- Source: dcy-004 FR-5, dcy-004 NFR-4, dcy-004 OQ-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-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-5 산출물.
+
+#### Intent
+- 토큰 발급 권한 정책 source of truth 확보 + admin 자기 발급 허용 정책 baseline 명시.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/interface-contract.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-019 baseline 정합 작업과 동일 batch 권장
+
+#### Validation Plan
+- 사람 리뷰로 AC-1~4 검증; 매트릭스-코드 dependency 매핑 사전 검토
@@ -0,0 +1,98 @@
+# REQ-021: 토큰 만료·회전 정책 정의
+
+- Status: Approved
+- Type: Documentation
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- 현행 토큰 만료 정책이 코드에 흩어져 있고(session은 settings.session_token_ttl_hours, service는 365일 default, `--no-expiry` 옵션) baseline 정책 명세가 없어 운영 일관성이 떨어진다. 토큰 type별 기본 TTL과 `no_expiry` 허용 범위·강제 회전 정책을 baseline에 명시한다.
+- dcy-004 OQ-5 결정에 따라 현행 TTL 유지로 시작하되 정책 표면을 명시해 후속 변경 추적 기반을 확보한다.
+
+## Requirement
+- `docs/runtime-flows.md`(또는 `docs/interface-contract.md`)에 "토큰 만료·회전 정책" 섹션을 추가한다. 명시 항목:
+  - **type별 기본 TTL**: session = `settings.session_token_ttl_hours`(현행 값 유지), service = 365일 default, env = 만료 없음
+  - **no_expiry 허용 범위**: service token 한정. session/(client는 폐지됨) 발급 경로는 모두 거부
+  - **강제 회전 주기**: 본 정책에서는 강제 주기 두지 않음. env admin token의 권장 회전 주기는 REQ-024(env admin SOP)에서 별도 정의
+  - **정책 위반 발급 처리**: `no_expiry`를 session에 요청하면 HTTP 422 또는 ValueError로 거부
+- 정책 명세는 현행 코드 구현과 일치해야 한다(`AuthService.login`, `AuthService.issue_service_token`의 만료 처리 로직 reference 명시).
+- 본 REQ는 정책 baseline 명시에 집중하고 코드 enforcement(no_expiry session 거부 등)가 누락된 경우 follow-up REQ로 분리한다.
+
+## Acceptance Criteria
+1. Given `docs/runtime-flows.md` 검토, When 본 REQ 구현 후, Then "토큰 만료·회전 정책" 섹션이 존재하고 type별 기본 TTL이 명시된다.
+2. Given 정책 검토, When `no_expiry` 허용 범위 항목을 확인, Then service 한정으로 명시되고 session/client는 거부됨이 명시된다.
+3. Given 정책 검토, When 강제 회전 주기 항목을 확인, Then 본 정책에서는 두지 않으며 env admin은 REQ-024에서 별도 정의됨이 명시된다.
+4. Given 정책 위반 발급 시도(예: `no_expiry`를 session에 요청), When 정책 명세 검토, Then HTTP 422 또는 ValueError 거부 응답이 명시된다.
+5. Given 정책 명세와 현행 코드 매핑, When `app/services/auth_service.py`의 `login`(session 만료)·`issue_service_token`(service 만료·no_expiry) 분기와 비교, Then 정책 본문이 코드와 일치하거나 불일치 항목이 follow-up으로 기록된다.
+
+## Impacted Area
+- Docs:
+  - `docs/runtime-flows.md` — "토큰 만료·회전 정책" 섹션 신규 추가 (또는 `docs/interface-contract.md`에 추가 후 runtime-flows에서 참조)
+- Modules: 없음 (정책 baseline 문서 정의. 코드 enforcement는 현행 그대로 유지)
+- Tests: 없음 (문서 전용. AC-4 정책 위반 거부 회귀는 향후 코드 변경 시점에 추가)
+
+## Notes
+- dcy-004 OQ-5 결정으로 현행 TTL 유지가 채택됐다. 본 REQ는 정책 명세 baseline화를 통해 후속 변경 추적 기반을 확보한다.
+- session 만료 시 in-flight 거래 영향 같은 정책 세부 사항은 본 REQ 범위 밖이며 release plan 또는 별도 운영 Discovery에서 다룬다.
+- 강제 회전 주기(분기/반기/연간)는 env admin token에 한정해 REQ-024에서 다루며, session/service에는 강제 주기를 두지 않는다.
+- Source: dcy-004 FR-6, dcy-004 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-6 산출물.
+
+#### Intent
+- 토큰 만료 정책 source of truth 확보 + 현행 TTL 유지 정책 baseline 명시.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/runtime-flows.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-019/020과 동일 batch 권장
+
+#### Validation Plan
+- 사람 리뷰로 AC-1~5 검증
@@ -0,0 +1,107 @@
+# REQ-024: env admin token 운영 SOP 정의
+
+- Status: Approved
+- Type: Documentation
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- 현행 env admin token(`PORTFOLIOHUB_ADMIN_TOKENS` 환경 변수)의 회전·폐기·강도 기준이 baseline에 명시되지 않아 운영 단계에서 회전이 잘못 적용되면 운영자 admin 접근이 차단될 수 있는 운영 리스크가 있다(dcy-004 R-4).
+- dcy-004 OQ-6 결정에 따라 분기(3개월) 권장 회전 주기, 강제 회전 없음 정책으로 SOP를 baseline에 명시한다.
+
+## Requirement
+- `docs/runtime-flows.md` 또는 `README.md`에 "env admin token 운영 SOP" 섹션을 추가한다. 명시 항목:
+  - **권장 회전 주기**: 분기(3개월). 강제 회전·만료 알람 없음. 운영자 자율로 회전 시점 결정.
+  - **회전 트리거 조건**: (a) 정기(분기), (b) token leak 의심, (c) 운영자 교체·퇴사, (d) 보안 사고 대응.
+  - **다단계 회전 절차**:
+    1. 강한 무작위 token 생성: `python3 -c "import secrets; print(secrets.token_urlsafe(48))"`
+    2. `PORTFOLIOHUB_ADMIN_TOKENS`에 신규 token을 콤마 분리로 추가(다중 token 동시 운영)
+    3. service rolling restart
+    4. 신규 token으로 admin 호출 검증(예: `GET /health`, admin 작업 sanity check)
+    5. 구 token을 `PORTFOLIOHUB_ADMIN_TOKENS`에서 제거
+    6. service rolling restart(구 token 무효화)
+    7. evidence 기록(회전 일자, 운영자, 신규 token 강도 확인, sanity check 결과)
+  - **rollback 절차**: 회전 실패 시 환경 변수에 구 token 재추가 후 rolling restart. fallback admin 접근 경로(예: DB 직접 접근으로 token 재생성) 보장.
+  - **운영자 권한 매트릭스**: env admin token 추가/제거는 인프라 운영자 권한. release approver 또는 운영자 교체 시 SOP를 참조.
+  - **token 강도 가이드**: 최소 48-byte URL-safe 무작위. 평문 단어·예측 가능한 패턴(예: `admin-token-789`) 금지.
+- SOP는 dev/test 환경과 prod 환경 모두에 적용되며, prod 환경의 약한 placeholder token이 발견된 경우(R-7) 본 SOP를 즉시 적용하도록 권고한다.
+
+## Acceptance Criteria
+1. Given `docs/runtime-flows.md` 또는 `README.md` 검토, When 본 REQ 구현 후, Then "env admin token 운영 SOP" 섹션이 존재하고 권장 회전 주기 + 강제 회전 없음 정책이 명시된다.
+2. Given SOP의 다단계 회전 절차 항목, When 검토, Then 7단계(token 생성 → 추가 → restart → 검증 → 구 token 제거 → restart → evidence 기록)가 명시된다.
+3. Given SOP의 rollback 절차 항목, When 검토, Then 회전 실패 시 환경 변수 복구 + fallback admin 접근 경로 명시.
+4. Given SOP의 token 강도 가이드, When 검토, Then 최소 48-byte URL-safe 무작위 요구 + 약한 placeholder 금지 명시.
+5. Given staging 환경에서 SOP에 따라 dry-run 회전 실행, When 7단계 절차 수행, Then 각 단계가 실제 환경에서 적용 가능함이 확인된다(release plan verification).
+
+## Impacted Area
+- Docs:
+  - `docs/runtime-flows.md` — "env admin token 운영 SOP" 섹션 신규 추가 (또는 `README.md`에 추가 후 runtime-flows에서 참조)
+  - `README.md` — daemon provisioning runbook에 env admin token SOP 링크 추가 (선택)
+- Modules: 없음 (정책 baseline 문서. 코드 변경 없음. 환경 변수 자체는 운영 작업)
+- Tests: 없음 (문서 전용. AC-5는 release plan verification 영역)
+
+## Notes
+- dcy-004 R-7(prod 환경 약한 admin token)은 본 SOP의 첫 번째 적용 사례로, dcy-004 confirm-discovery 시점 또는 이전에 운영자가 본 SOP의 7단계 절차를 적용해 `admin-token-789`를 강한 무작위 값으로 교체하기를 권고. hotfix 추적은 dcy-004 §10 DATA_PROD_ADMIN_TOKEN_HOTFIX 항목으로 관리.
+- env admin token 다중 운영 허용은 현행 `app/core/auth.py:_resolve_permission`이 set 기반으로 처리하므로 코드 변경 없이 가능([app/core/auth.py:43-50](app/core/auth.py#L43-L50)).
+- 본 SOP는 prod 환경 적용을 우선으로 작성됐으나 dev/test 환경에서도 약한 placeholder 사용을 금지한다. dev 환경 사용자는 `secrets.token_urlsafe` 또는 동등한 강도의 값을 생성해 .env 파일에 보관.
+- Source: dcy-004 FR-9, dcy-004 OQ-6 결정.
+
+## 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-9 산출물.
+
+#### Intent
+- env admin token 운영 SOP source of truth 확보 + 분기 권장 회전 주기 baseline 명시 + dcy-004 R-7 hotfix 표준 절차 정의.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### Impacted Area Delta
+- Docs: docs/runtime-flows.md, README.md — 최초 지정
+- Modules: 없음
+- Tests: 없음
+
+#### Delivery Trace Delta
+- Batches: none (미정)
+- Releases: none (미정). dcy-004 R-7 hotfix는 본 REQ confirm-req 이전이라도 본 SOP 절차로 즉시 적용 권장.
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 계획 편입; REQ-019/020/021과 동일 batch 권장
+
+#### Validation Plan
+- 사람 리뷰로 AC-1~4 검증; AC-5는 staging 환경 dry-run으로 release plan 검증
@@ -0,0 +1,116 @@
+# REQ-032: portfolio v1 baseline 문서 갱신
+
+- Status: Approved
+- 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` 기준 분기) 일관 명시
+  - 구 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 정책과 충돌하는 잔재가 없다.
+
+## 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-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 검증