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>

docs/discovery/dcy-001_20260519_asset-catalog-and-user-portfolio-model.md

@@ -5,10 +5,10 @@
 - 문서 ID: dcy-001_20260519_asset-catalog-and-user-portfolio-model
 - 이슈명: 자산 관리 구조 재설계 — admin 관리 asset catalog와 user portfolio 분리 모델 도입
 - 작성 시각(KST): 2026-05-19T00:00+09:00
-- 마지막 갱신 시각(KST): 2026-05-19 (draft-req 완료 — REQ-009~015 생성)
+- 마지막 갱신 시각(KST): 2026-05-20T12:00+09:00 (후속 Discovery 참조 추가 — dcy-003 옵션 B 결정으로 REQ-013 Deprecated 처리, 본 Discovery FR-5의 `GET /v1/assets` 통합 endpoint 결정은 dcy-003으로 회수됨)
 - 대체됨: 없음
-- 후속 Discovery 참조: 없음
-- 생성된 REQ 참조: REQ-009, REQ-010, REQ-011, REQ-012, REQ-013, REQ-014, REQ-015
+- 후속 Discovery 참조: docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md (confirmed 2026-05-20 — path 명명 분리: `GET /v1/assets`는 admin catalog 전용으로 회수, `GET /v1/portfolios` 포지션 조회 신설. 본 Discovery FR-5의 `GET /v1/assets` 통합 endpoint 결정은 REQ-013 Deprecated로 처리 완료)
+- 생성된 REQ 참조: REQ-009, REQ-010, REQ-011, REQ-012, ~~REQ-013~~ (Deprecated 2026-05-20 — dcy-003 옵션 B 결정), REQ-014, REQ-015
 
 # 1. 계획 상태 요약
 현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md

@@ -0,0 +1,304 @@
+# 0. 문서 상태
+이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
+
+- 상태: confirmed
+- 문서 ID: dcy-003_20260520_user-portfolio-mutation-v1-api-migration
+- 이슈명: User Portfolio Mutation v1 API 이전 및 path 명명 분리 (/v1/portfolios* 신설)
+- 작성 시각(KST): 2026-05-20T00:00+09:00
+- 마지막 갱신 시각(KST): 2026-05-20T15:00+09:00 (draft-req 완료 — REQ-025~032 8건 생성. FR-1+2 통합, FR-3/4/5/6/7/8/10 각 분리, FR-9는 REQ-013 Deprecated로 처리 완료라 별도 REQ 없음, NFR-1~4 흡수, docs/srs/index.md 갱신)
+- 대체됨: 없음
+- 후속 Discovery 참조: docs/discovery/dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md (client token 발급 경로 폐지 + 토큰 surface 정비, 2026-05-20 confirmed)
+- 생성된 REQ 참조: REQ-025, REQ-026, REQ-027, REQ-028, REQ-029, REQ-030, REQ-031, REQ-032
+
+# 1. 계획 상태 요약
+현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
+
+- 연계 문서 현황:
+	- 관련 점수 파일: 미생성
+	- 관련 TODO/메모: temp/2026-05-18_todo.md (구현 결함 inventory — `POST /v1/assets/{asset_id}/ledger/trades`의 path param 의미 불일치 항목이 본 Discovery로 해소될 가능성)
+- 해석:
+	- dcy-001(asset catalog 분리, confirmed)이 `# 5. 요구사항 목록 > 범위 경계 > Out of Scope`에서 "user portfolio mutation HTTP API ... 별도 Discovery에서 `/v1/` 경로로 이전 예정"을 명시했고, 본 Discovery가 그 후속에 해당한다. dcy-001 FR-2/FR-5가 정의한 `/v1/assets` path 위에 portfolio CRUD를 더 얹는 대신, path를 `/v1/portfolios*`로 완전 분리(옵션 B)하여 catalog와 포지션의 의미를 갈라낸다.
+	- 본 Discovery는 dcy-001 FR-5의 "GET /v1/assets = portfolio 조회 endpoint" 결정을 명시적으로 override한다. dcy-001 REQ-009~015는 2026-05-19 일괄 Approved, REQ-013(FR-5 산출물)은 본 Discovery 확정(2026-05-20) 후 change-req(CHG-20260520-01)로 Deprecated 처리 완료. 본 Discovery REQ 작성을 위한 선행 조건은 모두 충족됨.
+
+# 2. 요구사항 판정 결과
+이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
+
+- 판정: 신규
+- 근거
+	- 현재 활성 SDLC(docs/discovery/, docs/srs/) 어디에도 user portfolio mutation HTTP API 요구사항이 존재하지 않으며, dcy-001 Out of Scope가 "별도 Discovery에서 처리" 명시 예고를 남겼다.
+	- `temp/20260519_old_sdlc/discovery/dcy-007_20260518_v1-asset-crud-endpoints.md`는 폐기된 옛 SDLC의 draft 잔재로 active 후보가 아니다. 본 Discovery는 dcy-001(catalog 분리)과 dcy-002(tag_ids 정책)로 재정의된 새 데이터 모델 위에서 path 명명을 분리해 재구성하므로 기존 어떤 주기와도 중복되지 않는다.
+
+# 3. 문제점의 요약
+문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
+
+- 현재 상태
+	- v1 API에 portfolio mutation 경로가 존재하지 않는다. `app/api/v1_assets.py`(GET /v1/assets, daemon-scoped 조회), `app/api/v1_user_info.py`(GET /v1/user_info), `app/api/v1_ledger.py`(POST /v1/assets/{asset_id}/ledger/trades) 3종만 라우터에 등록되어 있다.
+	- `POST /v1/assets/{asset_id}/ledger/trades`의 path parameter 이름은 `asset_id`이나 실제 값은 `portfolios.portfolio_id`(UUID)로, asset과 portfolio의 의미가 한 path에 혼용된다.
+	- dcy-001 FR-5는 `GET /v1/assets`를 "토큰 타입별 통합 portfolio 조회"로 재정의했지만, 같은 path가 dcy-001 FR-2 정의의 catalog CRUD(`POST/PATCH /v1/assets`)와 포지션 조회 두 의미를 동시에 가져 응답 schema가 토큰 타입별로 갈라진다.
+	- portfolio 생성/수정/삭제/매수/매도/입출금/이체/태그/코멘트의 도메인 로직은 `app/services/portfolio_service.py`(`create_portfolio`, `update_portfolio`, `delete`, `buy`, `sell`, `invest`, `transfer`, `add_tag`, `remove_tag`, `create_comment`, `update_comment`, `delete_comment` 등)에 이미 구현되어 있으나 v1 라우터로 노출되지 않는다. CLI(`pfhub portfolio ...`)와 비-v1 `app/api/portfolios.py` 라우트만 해당 기능을 노출한다.
+	- baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`, `docs/data-model.md`, `docs/project-structure.md`)는 모두 존재하며 dcy-001/002 변경 사항을 아직 반영하지 않은 직전 baseline 상태다.
+- 기대 상태
+	- `/v1/assets*` = admin asset catalog 전용 경로(dcy-001 FR-2 정의 범위만 유지).
+	- `/v1/portfolios*` = user/daemon/admin이 portfolio(포지션)를 CRUD하고 ledger·tags·comments를 다루는 경로 집합.
+	- `GET /v1/portfolios`는 토큰 타입별 분기 조회(admin: 본인 또는 `?user_id=<id>`로 타 user, user: 본인, daemon: `managed_by_daemon_id` 필터 + `?market` 지원).
+	- ledger 기록은 `POST /v1/portfolios/{portfolio_id}/ledger/trades`로 이전, path param 이름과 의미가 일치한다.
+	- portfolio 생성 시 dcy-001 catalog 검증(`asset_id`가 `status='active'`인지 확인) 적용, portfolio 태그 적용 시 dcy-002 tag_ids 정책(is_admin_tag=TRUE 또는 소유자 생성 태그) 준수.
+- 이해관계자
+	- admin: portfolio HTTP CRUD를 통해 본인 또는 타 user의 포지션을 프로비저닝하는 운영자
+	- 로그인 user: 자신의 portfolio를 HTTP로 생성/수정/삭제/거래하려는 사용자
+	- daemon (trex-basic): 배정된 portfolio에 대해 조회·ledger 기록을 수행하는 서비스 에이전트. 본 Discovery 시점에 v1 path가 `/v1/portfolios*`로 변경되어 클라이언트 코드 수정이 필요하다
+	- repository-maintainers: 본 Discovery의 REQ 작성·구현·검증 담당
+- 제약사항
+	- dcy-001 FR-5 결정을 override → dcy-001 REQ-013(Approved)에 change-req 처리 완료(2026-05-20). REQ-013 Status → Deprecated, dcy-001 §0 후속 Discovery 참조 갱신, REQ-010 Notes에 GET /v1/assets catalog 명세 처리 계획 추가.
+	- 선행 조건 충족: dcy-001 REQ-009~015 모두 Approved 상태(2026-05-19 일괄 승인). 본 Discovery REQ 작성은 즉시 가능.
+	- dcy-002 portfolios.tag_ids 정책(is_admin_tag 또는 소유자 검증) 준수
+	- trex-basic은 본 batch와 동시 배포 필요(한시적 별칭 운영 없이 — OQ-3 Answered 2026-05-20). 구 path는 동일 release에서 제거된다.
+	- 인증 모델은 현행 Bearer token 체계(env token 또는 DB user/service token + Permission 체계 ADMIN/TRADE_WRITE/READ)를 그대로 사용한다
+
+## 주요 사용자 시나리오
+사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
+
+- admin이 `POST /v1/portfolios`에 body `{"asset_id": "<catalog-uuid>", "broker": "kiwoom", "cash_balance": 1_000_000, "user_id": "alice-uuid"}`로 요청해 alice의 portfolio를 프로비저닝한다. asset_id가 catalog에 `status='active'`로 존재하지 않으면 거부된다.
+- alice가 로그인으로 발급받은 session token으로 `PATCH /v1/portfolios/{portfolio_id}`로 본인 portfolio의 `strategy_name`을 변경한다. bob의 token으로 alice의 portfolio를 수정하려 하면 HTTP 403을 받는다.
+- alice가 `DELETE /v1/portfolios/{portfolio_id}`로 본인 portfolio를 종료한다. portfolio는 `status='disabled'`로 전환되고 `managed_by_daemon_id`는 자동 해제되며, ledger·comments·tags는 보존된다(soft delete, OQ-1 Answered 2026-05-20).
+- daemon(service-token, daemon-bound)이 `GET /v1/portfolios?market=KRX`를 호출해 KRX 시장 활성 자산에 매핑되고 자신에게 배정된 portfolio만 받는다.
+- daemon이 체결 발생 시 `POST /v1/portfolios/{portfolio_id}/ledger/trades`로 idempotent하게 거래 기록을 등록한다.
+- user가 `POST /v1/portfolios/{portfolio_id}/tags` body `{"tag_id": "<uuid>"}`로 태그를 적용한다. 태그가 admin 생성이 아니고 소유자가 아니라면 HTTP 403(dcy-002 FR-3 정책)을 받는다.
+
+# 4. 이번에 정의할 변경
+이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
+
+- `/v1/portfolios*` 신설 — POST/GET/PATCH/DELETE 및 `/ledger/trades`·`/tags`·`/comments` 서브 라우트 일괄 구현. 단일 라우트에서 토큰 타입(admin/user/daemon) 분기로 authorization 처리.
+- `GET /v1/assets`의 portfolio 조회 의미 회수 → catalog 전용으로 복원. dcy-001 FR-5 산출물 REQ-013에 change-req(CHG-20260520-01) 적용 완료(Status → Deprecated, 2026-05-20).
+- `POST /v1/assets/{asset_id}/ledger/trades`를 `POST /v1/portfolios/{portfolio_id}/ledger/trades`로 이전, path param 이름과 의미를 일치시킴. 동일 batch에서 구 path 제거.
+- portfolio 생성 시 dcy-001 catalog 검증(asset_id `status='active'`) 통합, portfolio tag 적용 시 dcy-002 tag_ids 정책 준수.
+- baseline 문서 갱신: `docs/interface-contract.md`, `docs/runtime-flows.md` (path 분리, daemon authorization, catalog 검증 흐름 반영)
+
+## 영향 범위
+변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
+
+- 코드 영향:
+	- `app/api/v1_portfolios.py`: 신규 파일 — `/v1/portfolios*` 라우트 전체 (CRUD + ledger + tags + comments). 토큰 타입 분기 인증 헬퍼(`_require_portfolio_access`) 포함.
+	- `app/api/v1_assets.py`: GET 동작에서 portfolio 조회 로직 제거, catalog 전용으로 회수. dcy-001 FR-2의 admin catalog CRUD는 유지.
+	- `app/api/v1_ledger.py`: 신규 path(`/v1/portfolios/{portfolio_id}/ledger/trades`)로 라우트 prefix 이전하거나 `v1_portfolios.py`에 흡수. 구 path는 제거.
+	- `app/main.py`: v1 라우터 include 목록 갱신.
+	- `app/schemas/v1.py`: `PortfolioCreateRequest`, `PortfolioUpdateRequest`, `PortfolioItem`, `PortfolioListResponse`, `PortfolioTagApplyRequest`, `PortfolioCommentRequest` 등 신규 schema. 기존 `AssetItem`/`AssetsResponse`는 catalog 응답 의미로 회수 또는 분리.
+	- `app/services/portfolio_service.py`: 기존 메서드 재사용. `create_portfolio`에 catalog 검증(asset_id active 확인) 추가.
+	- `app/repositories/portfolio_repository.py`, `app/repositories/postgres.py`: 신규 메서드 도입 없음 또는 catalog 검증용 read-path만 추가. 기존 mutation 메서드 재사용.
+	- `app/api/portfolios.py`(legacy 비-v1 `/portfolios/*` 라우트): 본 Discovery 범위 밖. 제거 시점은 후속 Discovery로 분리.
+- 문서 영향:
+	- `docs/interface-contract.md`: `/v1/portfolios*` 명세 추가, `/v1/assets*`의 의미 회수 반영, daemon authorization model 갱신
+	- `docs/runtime-flows.md`: portfolio mutation flow, catalog 검증 flow, /v1/portfolios path 명명 분리 정책, ledger path 이전 흐름
+	- `docs/discovery/dcy-001_20260519_asset-catalog-and-user-portfolio-model.md`: §0 후속 Discovery 참조 → dcy-003 추가 완료(2026-05-20), 생성된 REQ 참조에 REQ-013 Deprecated 표기. REQ-013(`docs/srs/Interface/req-013_get-v1-assets-token-branching.md`)은 Deprecated 전환 + Change Log CHG-20260520-01 기록. REQ-010 Notes는 GET /v1/assets catalog 명세 처리 계획 보강 완료.
+	- `docs/project-structure.md`: `app/api/v1_portfolios.py` 신규 파일 추가 및 라우터 책임 갱신 — 필요 시 baseline 갱신
+- 운영 영향:
+	- trex-basic은 본 batch release window에 새 path로 동시 배포 필요. release plan에 동시 배포 절차와 verification checklist 명시.
+	- admin이 HTTP로 타 user portfolio를 생성/삭제할 수 있게 되므로 admin token 발급·관리 절차에 권한 영향 반영
+	- DELETE 방식: soft delete로 확정(OQ-1 Answered 2026-05-20). 운영 SOP — portfolio status='disabled' 전환 + admin이 `PATCH status='enabled'`로 복구, 의존 데이터(ledger·comments·tags) 보존, 누적 disabled 정리는 별도 운영 Discovery로 위임
+
+# 5. 요구사항 목록
+실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
+
+## 기능 요구사항
+- FR-1: `POST /v1/portfolios` 신설 — Bearer 인증 후 portfolio 생성. body 필수 필드: `asset_id`, `broker`. 선택 필드: `name`, `cash_balance`, `asset_quantity`, `asset_price`, `profit_buffer`, `strategy_name`, `strategy_params`, `managed_by_daemon_id`, `user_id`. **토큰 분기 규칙 (OQ-2, OQ-5 Answered 2026-05-20)**:
+	- (1) `token_type ∈ {service, client}` → HTTP 403 fail-closed. `service`는 daemon-bound이며 portfolio CRUD 주체가 아님(OQ-2). `client`는 발급 경로 자체가 [dcy-004](./dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md)(confirmed 2026-05-20)에서 폐지 확정. 본 Discovery는 폐지 release 이전 운영에서도 v1 portfolio mutation 진입을 사전 차단해 일관성 유지(OQ-5).
+	- (2) 그 외(`token_type=session` 또는 env token, `token_source` 무관):
+		- `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.
+	- env admin token과 admin permission을 가진 session token은 admin 분기에서 동일하게 처리된다.
+- FR-2: portfolio 생성 시 `asset_id`가 dcy-001 catalog의 `assets` 테이블에 존재하고 `status='active'`인지 검증한다. 미등록 또는 inactive면 HTTP 422(요청 검증) 또는 403(권한/정책) 중 dcy-001 FR-4와 일관된 응답 코드로 거부한다. 검증 위치(서비스 계층 공통 진입점 vs v1 라우터 레이어 한정)는 REQ 작성 단계에서 결정한다 — 공통 서비스 진입점에 두면 CLI 회귀 영향이 있고(R-5), 라우터 레이어에 두면 CLI는 무영향이나 검증 중복이 발생한다.
+- FR-3: `PATCH /v1/portfolios/{portfolio_id}` 신설 — Bearer 인증 후 부분 수정. **토큰 분기 규칙 (OQ-2, OQ-5 Answered 2026-05-20, FR-1과 동일 패턴)**:
+	- (1) `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+	- (2) 그 외(`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` 등).
+- FR-4: `DELETE /v1/portfolios/{portfolio_id}` 신설 — Bearer 인증 후 portfolio를 **soft delete**한다(OQ-1 Answered 2026-05-20). **토큰 분기 규칙 (OQ-2, OQ-5 Answered 2026-05-20, FR-1과 동일 패턴)**:
+	- (1) `token_type ∈ {service, client}` → HTTP 403 fail-closed.
+	- (2) 그 외(`token_type=session` 또는 env token):
+		- `permission='admin'` → 모든 portfolio 삭제 가능.
+		- `permission ∈ {read, trade-write}` → 자기 소유 portfolio만 삭제 가능, 불일치 시 HTTP 403.
+	- 동작: `portfolios.status = 'disabled'`로 전환, `managed_by_daemon_id`는 `NULL`로 자동 해제, `updated_at` 갱신. 의존 데이터(`portfolio_ledger`, `ledger_trades`, `portfolio_comments`, `portfolios.tag_ids`)는 모두 보존한다. disabled 상태 portfolio는 다음 write/도메인 동작이 차단된다: `PATCH`(status 전이 외 필드 변경), `POST /ledger/trades`, tag/comment 추가·수정·삭제. disabled portfolio는 `GET /v1/portfolios` 기본 응답에서 제외하되 `?include_disabled=true`로 조회 가능. 복구는 admin이 `PATCH /v1/portfolios/{portfolio_id}`로 `status='enabled'`(또는 그 전 status)로 전환하면 가능하며, daemon 재배정은 별도 호출로 수행한다. hard delete 경로는 v1에 노출하지 않는다. 비존재 portfolio는 HTTP 404, 이미 `disabled` 상태인 portfolio에 재호출 시 HTTP 200 + 멱등 응답(또는 HTTP 409 — REQ 단계에서 응답 코드 확정).
+- FR-5: `GET /v1/portfolios` 신설 — 토큰 분기 조회 (dcy-001 FR-5의 정의를 path만 변경해 흡수). **토큰 분기 규칙 (OQ-5 Answered 2026-05-20)**:
+	- `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](./dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md) confirmed 2026-05-20 — 발급 경로 폐지 확정, OQ-5).
+	- `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만 반환.
+	- 응답 항목의 `asset_id`는 dcy-001 catalog UUID 참조. 항목 schema는 새 `PortfolioItem`으로 정의.
+- FR-6: `POST /v1/portfolios/{portfolio_id}/ledger/trades` 신설 — 기존 `POST /v1/assets/{asset_id}/ledger/trades` 동작을 path만 변경해 그대로 이전. daemon assignment 3단계 fail-closed 인가(token daemon_id NULL → 403, asset 미배정 → 403, 불일치 → 403), idempotency(uq_ledger_trades_idempotency), duplicate/conflict 응답(HTTP 200 status="duplicate" / HTTP 409) 동일 유지. 동일 batch에서 구 path는 제거되어 호출 시 HTTP 404.
+- FR-7: portfolio tag 적용/해제/조회 — `POST /v1/portfolios/{portfolio_id}/tags` (body: `{"tag_id": "<uuid>"}`), `DELETE /v1/portfolios/{portfolio_id}/tags/{tag_id}`, `GET /v1/portfolios/{portfolio_id}/tags`. dcy-002 FR-3 정책 준수: `tags.is_active=TRUE`이고 `tags.is_admin_tag=TRUE` 또는 `tags.created_by_user_id = portfolio.owner_user_id`인 경우에만 적용 허용. 정책 위반 시 HTTP 403. ownership 규칙은 FR-3과 동일.
+- FR-8: portfolio comment CRUD — `POST/GET /v1/portfolios/{portfolio_id}/comments`, `PATCH/DELETE /v1/portfolios/{portfolio_id}/comments/{comment_id}`. ownership 규칙은 FR-3과 동일. 기존 `CommentCreateRequest`/`CommentUpdateRequest`/`CommentResponse` schema 재사용 또는 v1 전용 래핑.
+- FR-9: dcy-001 FR-5의 "GET /v1/assets = portfolio 조회 endpoint" 결정을 회수한다. `GET /v1/assets`는 dcy-001 FR-2의 admin catalog 조회 전용 의미로 복원. **dcy-001 FR-5 산출물 REQ-013에 change-req CHG-20260520-01 적용 완료(2026-05-20)** — Status → Deprecated, dcy-001 §0 후속 Discovery 참조 갱신, REQ-010 Notes 보강. `GET /v1/assets` catalog 조회 명세는 dcy-001 batch design 단계에서 REQ-010 보강 또는 신규 REQ로 처리 예정.
+- FR-10: baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`) 갱신 — `/v1/portfolios*` 신설 명세, `/v1/assets*` 의미 회수, ledger path 이전, daemon authorization model 갱신, portfolio create flow에 catalog 검증 단계 추가.
+
+## 비기능 요구사항
+성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
+
+- NFR-1: 모든 `/v1/portfolios*` 엔드포인트는 Bearer token 필수. 미인증 요청은 HTTP 401, 권한 부족은 HTTP 403, 비존재 자원은 HTTP 404로 통일한다.
+- NFR-2: trex-basic과 portfolio-hub는 본 batch release window에서 **동시 배포된다(OQ-3 Answered 2026-05-20 — 한시적 별칭/redirect 채택하지 않음)**. 구 `/v1/assets`의 portfolio 조회 의미와 구 `POST /v1/assets/{asset_id}/ledger/trades` path는 동일 release에서 제거되며, 신 path(`/v1/portfolios*`)만 단일 서빙된다. release plan에 동시 배포 절차, 배포 순서(예: trex-basic 클라이언트 변경 사전 빌드 완료 → portfolio-hub 배포 → trex-basic 배포의 시점 잠금), rollback 조건(portfolio-hub 단독 rollback 시 trex-basic 영향 격리 방법)을 명시한다.
+- NFR-3: authorization 분기는 라우터 레이어의 토큰 타입(admin/user/daemon) 분기로 단일 라우트 내에서 처리한다. principal별로 별도 라우트(예: `/v1/admin/portfolios`)를 신설하지 않는다.
+- NFR-4: 기존 `app/services/portfolio_service.py`의 메서드 시그니처와 동작은 catalog 검증 통합 외 변경을 최소화한다. 서비스 계층 회귀를 줄이고 라우터 레이어 추가에 집중한다.
+
+## 범위 경계
+이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
+
+- In Scope
+	- `/v1/portfolios*` 라우트 신설: CRUD + ledger + tags + comments
+	- `/v1/assets`의 portfolio 조회 의미 회수 (catalog 전용 복원)
+	- `POST /v1/assets/{asset_id}/ledger/trades` → `POST /v1/portfolios/{portfolio_id}/ledger/trades` 이전 및 구 path 제거
+	- portfolio 생성 시 dcy-001 catalog 검증 통합
+	- portfolio tag 적용 시 dcy-002 tag_ids 정책 준수
+	- baseline 문서 갱신 (interface-contract.md, runtime-flows.md)
+	- dcy-001 FR-5 change-req 등록 — REQ-013 Deprecated 처리 완료(2026-05-20)
+	- trex-basic 동시 배포 운영 계획 수립 (절차 상세는 NFR-2 source of truth)
+- Out of Scope
+	- 비-v1 `app/api/portfolios.py`의 legacy `/portfolios/*` 라우트 제거 — 후속 Discovery로 분리
+	- 사용자 로그인/세션 시스템 신설 — 현행 Bearer token 체계 유지
+	- 매수/매도/입출금/이체 등 거래 동사(`buy`, `sell`, `invest`, `transfer`)의 v1 HTTP 노출 — OQ-4 결정으로 본 Discovery 범위 밖 확정(2026-05-20). v1에서는 `POST /v1/portfolios/{portfolio_id}/ledger/trades`(idempotency key 기반 ledger 기록)만 제공하며, 거래 동사는 현행 CLI(`pfhub portfolio buy/sell/invest/transfer`)로 계속 운용한다. HTTP 노출 필요성이 실증되면 후속 Discovery에서 거래 의미론(사후 기록 vs broker 호출 위임)과 daemon ledger 경로 책임 분리를 별도 정의한 뒤 추가한다.
+	- daemon(service-token)이 portfolio를 v1 API로 직접 생성·수정·삭제하는 경로 — OQ-2 결정으로 거부 확정(HTTP 403). daemon의 v1 권한은 조회(GET /v1/portfolios)와 ledger 기록(POST /v1/portfolios/{id}/ledger/trades)에 한정한다.
+	- trex-basic 클라이언트 코드 수정 — portfolio-hub 측 release plan에 동시 배포만 포함, trex-basic 측 변경은 해당 저장소 작업
+
+# 6. 리스크/가정 목록
+불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
+
+## 리스크
+- R-1 (High): trex-basic 동시 배포(NFR-2) 실패 시 trex-basic이 구 `/v1/assets`(포지션 조회) 또는 구 `POST /v1/assets/{asset_id}/ledger/trades`를 계속 호출해 HTTP 404가 발생하고 거래 기록이 차단되는 운영 장애가 발생할 수 있다. OQ-3에서 한시적 별칭을 채택하지 않기로 결정했으므로 동시 배포 절차의 정확성이 본 리스크의 유일한 방어선이다.
+	- 완화 방안: (a) release plan에 trex-basic 배포 의존성과 배포 순서 잠금(trex-basic 신 path 클라이언트 빌드 사전 완료 → portfolio-hub 배포 → trex-basic 배포)을 명시. (b) batch verification 단계에서 trex-basic의 신 path 호출 evidence(통합 smoke test 또는 staging 환경 dry-run)를 확보. (c) trex-basic 측 클라이언트가 양방향 호환(구·신 path 둘 다 시도) 가능하도록 일시 코드를 둘지 여부는 trex-basic 저장소 책임으로 분리 — portfolio-hub 측에서는 신 path 단일 서빙. (d) rollback 시나리오: portfolio-hub 단독 rollback이 trex-basic을 깨뜨리므로, rollback은 trex-basic 동반 rollback을 전제로 release plan에 명시한다.
+- R-2 (Medium): DELETE를 soft delete로 결정(OQ-1 Answered)했으므로 hard delete로 인한 데이터 손실 리스크는 해소되었으나, `status='disabled'` portfolio가 누적되면 운영 가시성 저하와 `GET /v1/portfolios` 기본 응답 필터링 회귀 가능성이 남는다. 또한 disabled 상태에서 write 차단 경계(ledger trade·tag·comment 거부)가 누락되면 데이터 일관성이 깨질 수 있다.
+	- 완화 방안: disabled portfolio는 `GET /v1/portfolios` 기본 응답에서 제외하고 `?include_disabled=true` opt-in으로만 노출(FR-5 보강 필요 — REQ 단계에서 명시). 모든 write/도메인 동작 경로(`PATCH` status 외 필드, ledger trade, tag/comment 변경)에 disabled guard를 일관 적용하고 회귀 테스트로 검증한다. 누적 disabled 정리(아카이브, 영구 삭제 운영 SOP)는 별도 운영 Discovery로 위임한다.
+- R-3 (해소됨, 잔여 모니터링 Low): dcy-001 FR-5 → REQ-013(Approved)에 대한 change-req 처리는 2026-05-20에 REQ-013 Deprecated 전환으로 완료. dcy-001 batch 일정 영향은 REQ-010 보강(GET /v1/assets catalog 명세) 작업이 batch design 단계에 추가되는 정도로 한정. 잔여 리스크는 REQ-010 보강 작업의 batch 편입 시점이 dcy-001 batch 일정을 지연시킬 가능성.
+	- 완화 방안: dcy-001 batch planning 시 REQ-010 보강 작업(또는 GET /v1/assets catalog용 신규 REQ)을 명시 항목으로 포함. dcy-003 신규 REQ들(`GET /v1/portfolios` 등)과 dcy-001 batch의 의존성을 batch planning 단계에서 정리.
+- R-4 (Medium): `/v1/portfolios*` 신규 라우트가 기존 `app/api/portfolios.py`의 legacy `/portfolios/*` 라우트와 책임 중복을 일으켜 API 사용자 혼동 및 코드 유지보수 비용 증가 가능.
+	- 완화 방안: 본 Discovery에서 두 라우트 set의 책임 경계와 client guidance(권장 path, deprecation 안내)를 `docs/interface-contract.md`에 명시한다. legacy 제거는 후속 Discovery로 분리하되 본 Discovery 시점에 deprecation 표시.
+- R-5 (Low): `app/services/portfolio_service.py`의 메서드 시그니처에 catalog 검증을 추가하면 CLI(`pfhub portfolio create`) 경로에도 영향을 미친다. CLI 회귀 가능성.
+	- 완화 방안: catalog 검증을 service 계층 공통 진입점에 두되 CLI 경로의 기존 동작과 호환되도록 입력 형태(legacy: symbol+broker, 신규: asset_id)를 모두 처리하거나 CLI 측 입력 변환 단계를 추가한다. REQ 작성 시 CLI 영향 범위 명시.
+
+## 가정
+아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
+
+- A-1: dcy-001 FR-5는 dcy-001 draft-req 단계(2026-05-19)에서 REQ-013(`GET /v1/assets` 통합 endpoint)으로 작성되어 Approved 상태였으며, 본 Discovery 확정(2026-05-20) 후 REQ-013에 change-req(CHG-20260520-01) 적용으로 Deprecated 전환 완료. `GET /v1/assets` catalog 조회 의미는 REQ-010 보강 또는 신규 REQ로 dcy-001 batch design 단계에서 처리. 본 Discovery의 FR-9는 이 처리의 근거 문서다.
+- A-2: dcy-002 portfolios.tag_ids 정책(`tags.is_admin_tag=TRUE` 또는 `tags.created_by_user_id = portfolio.owner_user_id`)은 본 Discovery FR-7의 portfolio tag 적용 라우트에서 그대로 적용된다. tag entity 자체의 CRUD는 dcy-002 범위.
+- A-3: 기존 `app/services/portfolio_service.py`의 메서드는 catalog 검증을 추가하는 형태로 재사용 가능하다. 서비스 계층의 시그니처 변경은 catalog 검증 통합에 한정하며, 신규 메서드를 대량 추가하지 않는다.
+- A-4: trex-basic은 portfolio-hub 본 batch release window 내에 클라이언트 코드를 갱신해 동시 배포 가능하다. 별도 별칭/redirect 운영 없이 deploy 시점 조율만으로 충분하다(OQ-3 Answered 2026-05-20). trex-basic 측 release readiness는 DATA_TREX_BASIC_RELEASE_WINDOW로 외부 확인이 남아 있다.
+- A-5: 인증 모델은 현행 `app/core/auth.py`의 Permission 체계(ADMIN/TRADE_WRITE/READ) + `AuthContext`(token_source, token_type, user_id, daemon_id, runtime_id) 기반으로 충분하며, 본 Discovery는 신규 권한 체계나 토큰 종류를 도입하지 않는다.
+
+## 오픈 질문
+답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
+
+- OQ-1: `DELETE /v1/portfolios/{portfolio_id}` 방식 — soft delete(`status='disabled'` 전환, 데이터 보존) vs hard delete(DB row 제거, ledger 함께 또는 `?keep_ledger=true` 옵션 노출)?
+	- 상태: Answered
+	- 처리 방안: soft delete로 결정(2026-05-20). `status='disabled'` 전환 + `managed_by_daemon_id` NULL 자동 해제 + 의존 데이터(ledger·comments·tags) 보존. disabled 상태에서 write/도메인 동작은 모두 차단하고, 복구는 admin의 `PATCH status` 전환으로 수행. hard delete 경로는 v1에 노출하지 않는다.
+	- 반영 위치: FR-4 본문 갱신 완료, R-2 완화 방안 갱신 완료, §10 DECIDE에서 DECIDE_DELETE_STRATEGY 처리 완료.
+- OQ-2: `POST /v1/portfolios`에서 daemon(service-token)이 portfolio를 직접 생성할 수 있는가? 허용 시 `owner_user_id`는 token에 연결된 owner_user_id로 강제되는가? 거부 시 HTTP 403 응답 정책은 어떻게 정의하는가?
+	- 상태: Answered
+	- 처리 방안: 거부로 결정(2026-05-20). daemon(service-token)은 `POST /v1/portfolios` 호출 시 token_type 검사 단계에서 HTTP 403 + `detail="service token cannot create portfolios"`로 fail-closed 응답한다. daemon은 v1 API에서 portfolio CRUD 주체가 아니며 권한은 조회(GET)와 ledger 기록(POST /ledger/trades)에 한정한다.
+	- 반영 위치: FR-1 본문 갱신 완료, 범위 경계 Out of Scope 갱신 완료, §10 DECIDE에서 DECIDE_DAEMON_CREATE_ALLOWANCE 처리 완료.
+- OQ-3: trex-basic 마이그레이션 전략 — 한시적 별칭(구 `/v1/assets` portfolio 조회와 구 ledger path를 신 path로 redirect 또는 dual-serve) 없이 동시 배포만으로 충분한가, 아니면 별칭/소프트 deprecation 기간이 필요한가?
+	- 상태: Answered
+	- 처리 방안: 한시적 별칭/redirect 없이 동시 배포로 결정(2026-05-20). 구 path는 동일 release에서 제거되고 신 `/v1/portfolios*`만 단일 서빙. rollback 시 portfolio-hub 단독 rollback은 trex-basic을 깨뜨리므로 release plan에 trex-basic 동반 rollback 전제를 명시한다.
+	- 반영 위치: NFR-2 본문 갱신 완료, R-1 완화 방안 갱신 완료, A-4 갱신 완료, §10 DECIDE에서 DECIDE_TREX_MIGRATION_STRATEGY 처리 완료. trex-basic 측 release readiness(DATA_TREX_BASIC_RELEASE_WINDOW)는 외부 확인 항목으로 잔존.
+- OQ-4: 매수/매도/입출금/이체 등 거래 동사를 별도 sub-route(`POST /v1/portfolios/{portfolio_id}/buy`, `/sell`, `/invest`, `/transfer`)로 노출할 것인가, `PATCH /v1/portfolios/{portfolio_id}`로 통합할 것인가, 또는 v1에는 `POST /v1/portfolios/{portfolio_id}/ledger/trades`만 노출하고 거래 동사는 CLI 전용으로 분리할 것인가?
+	- 상태: Answered
+	- 처리 방안: 옵션 C로 결정(2026-05-20). v1에는 `POST /v1/portfolios/{portfolio_id}/ledger/trades`만 노출하고 거래 동사(`buy`/`sell`/`invest`/`transfer`)는 본 Discovery 범위에서 CLI 전용으로 유지. 근거: (a) ledger 기록 경로 단일화 — daemon ledger/trades와 user 거래 동사 sub-route가 동일 portfolio에 ledger를 작성하는 책임 중복을 방지. (b) §3 user 시나리오에 거래 동사 HTTP 호출이 명시되지 않음 — 본 Discovery 핵심 가치는 CRUD + tags + comments + 조회. (c) v1 API 표면 최소화로 batch 인가/검증/테스트 부하 감소. (d) HTTP 노출이 후속에서 필요해지면 별도 Discovery에서 거래 의미론(사후 기록 vs broker 호출 위임) 정의 후 추가 — 회수 비용 낮음.
+	- 반영 위치: §5 범위 경계 Out of Scope 갱신 완료, §10 DECIDE에서 DECIDE_TRADE_VERB_ROUTING 처리 완료. FR 추가는 없음(기존 FR-6 ledger/trades 노출로 충분).
+- OQ-5: 본 Discovery에서 일관 사용하는 "user token" 개념의 `AuthContext.token_type` 매핑은 무엇인가? 현행 코드의 token_type은 `session`(로그인 발급), `client`(CLI/API 발급), `service`(daemon-bound) 3종이며, env admin token과 DB admin token이 동일하게 admin 분기에 들어가는지도 함께 정의해야 한다. FR-1/FR-3/FR-5의 토큰 분기 정책은 이 매핑이 확정되어야 REQ에서 인가 헬퍼(`_require_portfolio_access` 등)로 구현 가능하다.
+	- 상태: Answered
+	- 처리 방안: token_type 게이트 + permission 기준 분기로 결정(2026-05-20). (a) `token_type ∈ {service, client}` → HTTP 403 fail-closed. service는 daemon-bound로 portfolio CRUD 주체가 아님(OQ-2). client는 발급 경로 자체를 [dcy-004](./dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md)(confirmed 2026-05-20)에서 폐지 확정 — 본 Discovery는 폐지 release 이전 운영에서도 v1 portfolio mutation 진입을 차단해 일관성 유지. (b) 그 외(`token_type=session` 또는 env token)는 `permission` 기준 분기 — admin이면 admin 분기, `read`/`trade-write`이면 user 분기. `token_source`(env/db)는 분기 기준에 사용하지 않으며 env admin token과 admin permission을 가진 session token은 admin 분기에서 동일 처리(dcy-004 OQ-5와 동일 결정). GET /v1/portfolios(FR-5)에서도 client 토큰은 거부되며 service 토큰은 daemon-bound 조회 의미로 별도 분기에서 정상 처리.
+	- 반영 위치: FR-1 본문 갱신 완료, FR-3 본문 갱신 완료, FR-4 본문 갱신 완료, FR-5 본문 갱신 완료, §3 사용자 시나리오 "session token"으로 명시 변경 완료, §10 DECIDE에서 DECIDE_USER_TOKEN_MAPPING 처리 완료. client token 발급 경로 폐지는 dcy-004(confirmed 2026-05-20)에서 확정되어 §10 DATA_CLIENT_TOKEN_DEPRECATION_DISCOVERY는 Collected 상태로 종료.
+
+### 오픈 질문 처리 기준
+- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
+- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
+- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
+- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
+- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
+- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
+- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
+
+# 7. 초기 성공 기준
+이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
+
+- S-1: `POST /v1/portfolios`를 admin/user 토큰으로 호출했을 때 토큰 타입별 ownership 규칙(admin + user_id body로 타 user 생성, user 본인 생성)이 정확히 적용되고, daemon(service-token) 호출은 HTTP 403으로 fail-closed 거부되며, dcy-001 catalog 검증(asset_id active hit/miss 케이스)이 기대대로 응답한다.
+- S-2: `PATCH /v1/portfolios/{id}`와 `DELETE /v1/portfolios/{id}`에서 ownership 불일치 시 HTTP 403, 미인증 시 HTTP 401, 비존재 portfolio 호출 시 HTTP 404를 반환한다. daemon(service-token)이 PATCH/DELETE를 호출하면 token_type 검사 단계에서 HTTP 403 fail-closed로 거부된다(FR-1 CREATE 거부와 동일 패턴). DELETE 호출 후 `portfolios.status='disabled'` + `managed_by_daemon_id IS NULL` 사후 상태 및 의존 데이터(ledger/comments/tags) 보존이 검증 가능하다. disabled portfolio에 대한 write 차단(PATCH status 외 필드, ledger trade, tag/comment 변경)이 일관 적용된다.
+- S-3: `GET /v1/portfolios`가 service token + daemon-scoped 필터, user token 본인 portfolio, admin token + `?user_id`로 타 user portfolio, `?market` 필터를 모두 정확히 처리한다. NULL daemon_id service token은 fail-closed(HTTP 403).
+- S-4: `POST /v1/portfolios/{portfolio_id}/ledger/trades`가 구 `POST /v1/assets/{asset_id}/ledger/trades`와 동일한 idempotency, daemon assignment authorization 3단계, duplicate/conflict 응답(HTTP 200/409)을 보장한다. 동일 batch에서 구 path는 HTTP 404를 반환한다.
+- S-5: `/v1/portfolios/{portfolio_id}/tags`와 `/v1/portfolios/{portfolio_id}/comments`가 ownership 규칙과 dcy-002 tag_ids 정책을 위반한 호출에 대해 HTTP 403을 반환한다.
+- S-6: trex-basic이 본 batch release window에 새 path로 무중단 이전되어 release 후 portfolio-hub `/health`는 200 OK를 반환하고 sample ledger write가 정상 성공한다.
+- S-7: baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`)에 `/v1/portfolios*` 명세, `/v1/assets*` 의미 회수, ledger path 이전 흐름이 모두 반영되어 후속 REQ/Batch가 해당 문서를 단일 source of truth로 사용할 수 있다.
+
+## 측정 방식 및 데이터 출처
+각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
+
+- S-1 측정 방식: pytest로 admin/user principal별 create 시나리오(catalog active hit/miss, ownership 정상/위반, admin `user_id` body 처리) + daemon principal 호출 시 HTTP 403 거부 회귀를 검증 / 데이터 출처: 신규 `tests/test_v1_portfolios_crud.py`
+- S-2 측정 방식: pytest로 PATCH/DELETE의 ownership 위반·미인증·비존재 케이스 검증 + daemon(service-token) 호출 시 HTTP 403 fail-closed 거부 회귀 + DELETE 사후 상태(`status='disabled'`, `managed_by_daemon_id IS NULL`, 의존 데이터 보존) 확인 + disabled portfolio에 대한 후속 write(ledger/tag/comment) 차단 회귀 검증 / 데이터 출처: 신규 `tests/test_v1_portfolios_crud.py`
+- S-3 측정 방식: pytest로 GET /v1/portfolios 토큰별 분기, `?user_id`, `?market` 필터, NULL daemon_id 403 회귀 검증 / 데이터 출처: 신규 `tests/test_v1_portfolios_list.py`
+- S-4 측정 방식: 기존 `tests/test_v1.py`의 ledger trade idempotency·daemon authorization 케이스를 신 path로 갱신해 회귀 통과 + 구 path 호출 시 HTTP 404 확인 / 데이터 출처: 갱신 `tests/test_v1.py`, 신규 `tests/test_v1_portfolios_ledger.py`
+- S-5 측정 방식: pytest로 tag/comment CRUD 시나리오와 dcy-002 정책(is_admin_tag, 소유자 검증) 위반 케이스 검증 / 데이터 출처: 신규 `tests/test_v1_portfolios_tags_comments.py`
+- S-6 측정 방식: release verification checklist의 health endpoint + sample portfolio create → ledger write smoke / 데이터 출처: 본 Discovery 후속 release 문서의 verification 섹션
+- S-7 측정 방식: baseline 문서 갱신 후 docs/interface-contract.md, docs/runtime-flows.md를 검토해 `/v1/portfolios*` 명세, `/v1/assets*` 의미 회수, ledger path 이전 항목이 모두 반영되었는지 확인 / 데이터 출처: 갱신된 baseline 문서
+
+# 8. REQ로 넘기기 전 확인 체크
+REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
+
+- [x] 범위(In Scope/Out of Scope) 확정
+	- 기준: OQ-1~5 전체 Answered 완료(2026-05-20). 토큰 분기 정책까지 명확해 In/Out of Scope 경계 최종화 완료. CONFIRM 2건 + DATA 2건은 §10에 잔존(사용자 확인 + 외부 데이터 + 후속 Discovery 작성 필요).
+- [x] 성공 지표의 측정 방식/데이터 출처 확정
+	- 기준: S-1~7 측정 방식이 §7 측정 방식 섹션에 각각 신규/갱신 pytest 시나리오(`tests/test_v1_portfolios_crud.py`, `tests/test_v1_portfolios_list.py`, `tests/test_v1_portfolios_ledger.py`, `tests/test_v1_portfolios_tags_comments.py`) 또는 release verification 체크 항목(S-6/S-7)으로 명시 연결됨.
+- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
+	- 기준: R-1(trex-basic 동시 배포) 완화 방안 4단계(a~d) 명시, R-2(disabled 누적·write 차단) 완화 방안 명시, R-3 해소(REQ-013 Deprecated 처리 완료), R-4(legacy 라우트 책임 경계)·R-5(CLI 회귀) 완화 방안 명시. 책임자 = repository-maintainers(본 Discovery 단계). REQ 작성 시 작업별 책임자가 REQ Impacted Area에 반영될 예정.
+- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
+	- 기준: OQ-1~5 전체 Answered 완료(2026-05-20). Open 상태 OQ 0건.
+- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
+	- 기준: §11 Confirmed By에 Justin 지정 완료(2026-05-20).
+- [x] dcy-001 FR-5 change-req 처리 계획 확정 + 실행
+	- 기준: REQ-013(Approved, dcy-001 FR-5 산출물)에 change-req CHG-20260520-01 적용 완료 (Status → Deprecated, 2026-05-20). dcy-001 §0 후속 Discovery 참조 갱신 + REQ-010 Notes 보강 처리 완료. 후속: `GET /v1/assets` catalog 명세는 dcy-001 batch design 단계에서 REQ-010 보강 또는 신규 REQ로 처리.
+
+# 9. 파일 처리 결과
+이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
+
+- 처리 결과: 생성
+- 생성 경로: docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md
+- 참조 문서:
+	- docs/discovery/dcy-001_20260519_asset-catalog-and-user-portfolio-model.md (선행 Discovery — FR-5 override 대상, Out of Scope 후속 예고의 본 Discovery 해당)
+	- docs/discovery/dcy-002_20260519_tag-ownership-and-applicability-policy.md (병행 Discovery — portfolio tag 적용 정책 준수)
+	- docs/discovery/dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md (후속 Discovery, confirmed 2026-05-20 — client token 발급 경로 폐지 + 토큰 surface 정비. 본 Discovery의 FR-1/3/4/5 token_type 게이트가 dcy-004 폐지 결정과 정합)
+	- temp/20260519_old_sdlc/discovery/dcy-007_20260518_v1-asset-crud-endpoints.md (참조 — 폐기된 옛 SDLC의 draft 초안, FR/OQ 일부 승계 및 재구성)
+	- docs/interface-contract.md (현행 v1 API 계약, 본 Discovery로 갱신 예정)
+	- docs/runtime-flows.md (현행 v1 API flow, 본 Discovery로 갱신 예정)
+	- docs/project-structure.md (현행 패키지/모듈 baseline, v1 라우터 파일 추가에 따라 일부 영향)
+
+# 10. 사용자 결정 필요 항목 요약
+사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
+
+## DECIDE
+- ~~{{DECIDE_DELETE_STRATEGY}}~~: **Decided** — soft delete(`status='disabled'` 전환, 데이터 보존)로 확정. hard delete 경로는 v1에 노출하지 않음. FR-4·R-2·OQ-1 본문 반영 완료. (OQ-1 Answered 2026-05-20)
+- ~~{{DECIDE_DAEMON_CREATE_ALLOWANCE}}~~: **Decided** — daemon(service-token)의 `POST /v1/portfolios` 호출 거부 확정. HTTP 403 + `detail="service token cannot create portfolios"` fail-closed 응답. FR-1·범위 경계 Out of Scope·OQ-2 본문 반영 완료. (OQ-2 Answered 2026-05-20)
+- ~~{{DECIDE_TREX_MIGRATION_STRATEGY}}~~: **Decided** — 한시적 별칭/redirect 없이 trex-basic + portfolio-hub 동시 배포로 확정. 구 path는 동일 release에서 제거. rollback 시 trex-basic 동반 rollback 전제. NFR-2·R-1·A-4·OQ-3 본문 반영 완료. (OQ-3 Answered 2026-05-20)
+- ~~{{DECIDE_TRADE_VERB_ROUTING}}~~: **Decided** — 옵션 C로 확정. v1에는 `POST /v1/portfolios/{portfolio_id}/ledger/trades`만 노출, 거래 동사(buy/sell/invest/transfer)는 본 Discovery 범위에서 CLI 전용 유지. ledger 기록 경로 단일화, v1 표면 최소화, 후속 Discovery에서 거래 의미론 정의 후 추가 가능. §5 범위 경계 Out of Scope·OQ-4 본문 반영 완료. (OQ-4 Answered 2026-05-20)
+- ~~{{DECIDE_USER_TOKEN_MAPPING}}~~: **Decided** — token_type 게이트 + permission 기준 분기. `service`/`client` token은 v1 portfolio mutation 진입 차단(HTTP 403). `session` 또는 env token은 `permission`이 admin이면 admin 분기, 그 외는 user 분기. `token_source`(env/db)는 분기 기준에 사용하지 않음. FR-1·FR-3·FR-4·FR-5·§3 시나리오·OQ-5 본문 반영 완료. client token 발급 경로 폐지는 후속 Discovery로 분리(DATA 항목 추적). (OQ-5 Answered 2026-05-20)
+
+## CONFIRM
+- ~~{{CONFIRM_DCY001_FR5_CHANGE_REQ}}~~: **Confirmed + Executed (2026-05-20)** — 옵션 B-3(REQ-013 Deprecated + REQ-010 보강 + 신규 REQ로 분리) 채택. REQ-013(Approved, dcy-001 FR-5 산출물)에 change-req CHG-20260520-01 적용 완료, Status → Deprecated. dcy-001 §0 후속 Discovery 참조 갱신, REQ-010 Notes 보강, docs/srs/index.md Register/Change Log Summary 갱신 완료. `GET /v1/assets` catalog 명세 처리는 dcy-001 batch design 단계로 이관.
+- ~~{{CONFIRM_LEGACY_PORTFOLIOS_ROUTE_SCOPE}}~~: **Confirmed (2026-05-20)** — 본 Discovery는 `/v1/portfolios*` 신설만 다루고 기존 `app/api/portfolios.py`의 legacy `/portfolios/*` 라우트 제거는 후속 Discovery로 분리하는 범위 결정에 사용자 동의 완료. §4 영향 범위·§5 Out of Scope·R-4 본문에 이미 명시됨. 후속 Discovery 작성 시점은 본 Discovery REQ drafting 또는 batch 진행 중 별도 결정.
+
+## DATA
+- ~~{{DATA_TREX_BASIC_RELEASE_WINDOW}}~~: **External tracking (release plan 단계 수집)** — trex-basic 배포 운영 담당자가 본 batch release window에 동시 배포 가능한 일정과 rollback 절차를 확정해 제공한다. 본 Discovery는 정책(NFR-2 동시 배포·R-1 완화 방안)을 정의하고 실제 release window 확정은 batch design / release plan 단계 운영 작업이라 confirm-discovery 게이트 차단 사유 아님. release plan 작성 시 evidence(예: trex-basic 배포 일정, rollback 절차 협의 결과)를 batch verification 문서에 기록.
+- ~~{{DATA_CLIENT_TOKEN_DEPRECATION_DISCOVERY}}~~: **Collected (2026-05-20)** — 후속 Discovery [dcy-004](./dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md) (confirmed 2026-05-20) 작성 완료. dcy-004 FR-1에서 `POST /auth/tokens`, `issue_client_token`, `CreateClientTokenRequest`, `IssuedClientTokenResponse` 모두 폐지로 확정. DATA-1 inventory 0건 확인으로 grace period/revoke 스크립트 불필요. 본 Discovery의 FR-1/3/4/5 token_type 게이트는 dcy-004 폐지 release 이전·이후 모두 정합.
+
+# 11. Discovery Freeze
+REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
+
+## 섹션 참조
+- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
+- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
+- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
+- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
+- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
+
+## Freeze 플래그
+- Handoff Decision: 승인
+- Handoff Rationale: OQ-1~5 Answered + CONFIRM 2건 Confirmed + DATA-1 Collected(dcy-004) + DATA-2 External tracking(release plan 단계) + §8 체크리스트 6건 모두 [x] 완료(2026-05-20). confirm-discovery 게이트 통과로 본 Discovery는 `confirmed` 상태로 승급되어 REQ 초안 작성 가능. **외부 의존**: DATA_TREX_BASIC_RELEASE_WINDOW(release plan 단계 수집), 향후 batch design 단계에서 dcy-001 REQ-010 보강 또는 신규 REQ(`GET /v1/assets` catalog 명세) 처리.
+- Ready for REQ Drafting: true
+- Confirmed By: Justin
+- Confirmed At (KST): 2026-05-20T14:00+09:00

docs/discovery/dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md

@@ -0,0 +1,322 @@
+# 0. 문서 상태
+이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
+
+- 상태: confirmed
+- 문서 ID: dcy-004_20260520_token-issuance-and-lifecycle-overhaul
+- 이슈명: 토큰 발급 및 관리 전면 정비 — client token 폐지, service-token rotate 정상화, 발급 권한 매트릭스, 만료·회전·자동 revoke 정책
+- 작성 시각(KST): 2026-05-20T07:00+09:00
+- 마지막 갱신 시각(KST): 2026-05-20T14:30+09:00 (draft-req 완료 — REQ-016~024 9건 생성. FR-1/2/3/4+10/5/6/7/8/9 분해, NFR-1~6 흡수, docs/srs/index.md 갱신)
+- 대체됨: 없음
+- 후속 Discovery 참조: 없음
+- 생성된 REQ 참조: REQ-016, REQ-017, REQ-018, REQ-019, REQ-020, REQ-021, REQ-022, REQ-023, REQ-024
+
+# 1. 계획 상태 요약
+현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
+
+- 연계 문서 현황:
+	- 관련 점수 파일: 미생성
+	- 관련 TODO/메모: temp/2026-05-18_todo.md (운영 결함 inventory — service-token rotate 실패, HTTP daemon_id forward 누락, rebind/AuthContext 문서 누락), temp/20260519_old_sdlc/releases/rel-006_20260513_daemon-model-implementation.md (rotate verification 실패 기록 + Feedback Handoff에 NULL daemon_id 마이그레이션·daemon deactivation 자동 revoke 항목 잔존)
+- 해석:
+	- 현행 토큰 surface는 4종(session/client/service/env)이 발급 경로·만료·회전·문서화에서 부분 정합성 결함을 누적해 왔고, 작은 결함들(client v1 mutation 진입, service-token rotate 실 DB 실패, HTTP body daemon_id silently drop, rebind/AuthContext 문서 누락)이 운영 단계에서 노출되었다. dcy-003에서 client token 폐지를 후속 Discovery에 명시 위임하면서 토큰 surface 정비를 단일 batch로 묶을 시점이 됐다.
+	- 본 Discovery는 토큰 surface 전면 정비 — client token 발급 경로 폐지, rotate 정상화, HTTP/CLI 일관성, 발급 권한 매트릭스, 만료·회전 정책, daemon deactivation 자동 revoke, NULL daemon_id legacy token 마이그레이션, env admin token 운영 SOP — 를 단일 주기로 처리한다.
+
+# 2. 요구사항 판정 결과
+이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
+
+- 판정: 신규
+- 근거
+	- 활성 SDLC(dcy-001 asset catalog, dcy-002 tag 정책, dcy-003 portfolio v1)는 모두 도메인 모델·portfolio API에 집중하며 토큰 surface 정비를 다루는 active Discovery는 없다. dcy-003 §10 DATA_CLIENT_TOKEN_DEPRECATION_DISCOVERY가 본 Discovery의 명시 예고에 해당한다.
+	- 폐기된 옛 SDLC의 dcy-005(production-admin-bootstrap)는 운영 admin 토큰 절차의 일부만 다루며 본 Discovery의 토큰 surface 전반 정비 범위와는 부분 겹침에 그친다. 새 SDLC 리셋(2026-05-19) 이후 토큰 surface 정비는 미수용 backlog로 남아 있었다.
+
+# 3. 문제점의 요약
+문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
+
+- 현재 상태
+	- 토큰 surface 4종: `app/core/auth.py`의 `AuthContext`가 `token_type ∈ {session, client, service, None(env)}` × `token_source ∈ {db, env}` 두 축으로 분류. 발급 경로는 `app/services/auth_service.py`의 `login`(session), `issue_client_token`(client), `issue_service_token`(service)에 분리. env token은 `settings.admin_tokens`/`trade_write_tokens`/`read_tokens`로 환경 변수에 박힌 형태.
+	- **결함 1 — client token 발급 경로 잔존**: `POST /auth/tokens` HTTP API([app/api/auth_routes.py:100-109](app/api/auth_routes.py#L100-L109))로 user가 본인 명의 발급 가능. dcy-003에서 v1 portfolio mutation 진입을 차단하기로 결정(token_type 게이트)했으나 발급 경로·`issue_client_token`·`CreateClientTokenRequest` 코드는 잔존.
+	- **결함 2 — service-token rotate 실 DB 실패**: `app/repositories/postgres.py:161-167`의 `idx_auth_tokens_service_name_unique` partial index가 `WHERE token_type='service'` 조건만 적용해 revoked row와 새 row가 같은 name으로 unique 충돌. [REL-006 verification](temp/20260519_old_sdlc/releases/rel-006_20260513_daemon-model-implementation.md#L74)에 "rotate insert 막힘" 검증 실패 기록.
+	- **결함 3 — POST /auth/service-tokens body `daemon_id` silently drop**: `app/schemas/auth.py:74-80`의 `IssueServiceTokenRequest.daemon_id` 필드는 노출되나 [app/api/auth_routes.py:131-137](app/api/auth_routes.py#L131-L137)에서 `service.issue_service_token` 호출 시 forward 하지 않음. CLI `--daemon-id`는 정상 forward하나 HTTP 경로만 daemon binding 불가.
+	- **결함 4 — `pfhub service-token rebind` CLI 문서화 누락**: [app/cli/commands/service_tokens.py:119-141](app/cli/commands/service_tokens.py#L119-L141)에 구현 완료, repository protocol/postgres 모두 존재하나 `docs/interface-contract.md` CLI surface 열거에 명시 없음.
+	- **결함 5 — runtime-flows.md AuthContext 필드 목록 daemon_id 누락**: `docs/runtime-flows.md:76`이 `user_id, token_type, permission, runtime_id`로 `daemon_id` 누락. 실제 코드는 보유.
+	- **정책 공백 1 — 발급 권한 매트릭스 부재**: 누가 어떤 token type을 발급/회전/폐기할 수 있는가가 코드에 흩어진 dependency(require_admin/require_read)로만 표현되고 baseline에 명시 없음.
+	- **정책 공백 2 — 만료·회전 정책 부재**: session은 `settings.session_token_ttl_hours` 강제, client는 발급 시 ttl 인자, service는 `--no-expiry` 허용. 일관 기준·강제 회전 주기 미정의.
+	- **정책 공백 3 — daemon deactivation 자동 revoke 부재**: `pfhub daemon update --deactivate`가 daemon `is_active=false`만 설정하고 바인딩 service token에 영향 없음 (REL-006 Feedback Handoff에 후속 항목으로 기록).
+	- **정책 공백 4 — NULL daemon_id legacy token 마이그레이션 자동화 부재**: REL-006 Feedback Handoff에 "rotate + rebind 자동화" 후보로 기록만 됨.
+	- **정책 공백 5 — env admin token 운영 SOP 부재**: 환경 변수 갱신·회전·폐기 절차가 baseline에 없음.
+- 기대 상태
+	- 토큰 surface 3종(session/service/env)으로 정리, client token 발급 경로 코드 폐지
+	- service-token rotate가 실 DB에서 정상 작동
+	- HTTP/CLI 토큰 발급 surface가 일관 (daemon_id forward 누락 해소, rebind/AuthContext 문서 반영)
+	- 발급 권한 매트릭스·만료·회전 정책이 baseline에 명시
+	- daemon deactivation 시 바인딩 service token 자동 revoke (또는 grace period)
+	- NULL daemon_id legacy token 마이그레이션 자동화(CLI 서브커맨드 또는 스크립트, dry-run 포함)
+	- env admin token 회전·폐기 운영 SOP 정의
+- 이해관계자
+	- admin/운영자: 토큰 발급·회전·폐기 SOP의 일관성 확보, env admin token 회전 책임
+	- 로그인 user: client 폐지 후 자동화 use case의 대체 경로 명확화
+	- daemon 운영 주체 (trex-basic 등): rotate/rebind 정상 작동, daemon deactivation 동기화
+	- repository-maintainers: 토큰 surface 정합성 유지, baseline 문서 일관성
+- 제약사항
+	- dcy-003(draft, 본 Discovery 결정 완료 후 진행 재개 예정)이 client token v1 portfolio mutation 진입 차단을 이미 결정(OQ-5 Answered 2026-05-20) → 본 Discovery는 그 결정 위에서 발급 경로 자체 폐지로 진행. 진행 순서: 본 Discovery 결정·confirm 완료 → dcy-003 잔여 항목(CONFIRM 2건, DATA 1건, dcy-001 REQ Approved 선행 조건) 처리 재개
+	- 기존 발급된 client token이 운영 중일 수 있어 폐지 마이그레이션 절차 필요 (DB inventory 사전 조사)
+	- service-token rotate 정상화는 unique index 변경을 포함 → Alembic migration 추가
+	- env admin token 회전은 코드 변경과 환경 변수 갱신을 동시 수행해야 운영 차단 회피
+	- 본 Discovery 범위는 토큰 surface 정비에 한정. 신규 토큰 타입 도입(OAuth, PAT 등), 외부 SSO 통합, 감사 로그 정책은 별도 Discovery로 분리
+
+## 주요 사용자 시나리오
+사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
+
+- admin이 alice의 trex-basic daemon용 service-token을 발급한다. `pfhub service-token issue NAME --user alice --daemon-id DID` (CLI) 또는 `POST /auth/service-tokens` body `{"name": "...", "username": "alice", "daemon_id": "DID", ...}` (HTTP) 두 경로 모두 동일하게 daemon_id binding이 작동한다.
+- admin이 alice의 service-token을 회전한다. `pfhub service-token rotate NAME --force` 실행 시 새 raw token이 발급되고 unique index 충돌 없이 성공한다. 새 토큰의 `runtime_id`는 새로 발급, `daemon_id`는 유지(invariant).
+- admin이 alice의 daemon을 비활성화한다(`pfhub daemon update DID --deactivate`). 해당 daemon에 바인딩된 service token이 자동 revoke되어 후속 v1 호출은 HTTP 401/403.
+- user가 본인 명의 client token 발급을 시도하면 HTTP 404 또는 405 (path 자체 제거)를 받는다. 자동화 use case는 admin이 발급한 service token으로 흡수 또는 OQ-8 결정에 따른 새 경로.
+- 운영자가 NULL daemon_id legacy service token을 일괄 마이그레이션한다. `pfhub service-token migrate-null-daemon --dry-run`으로 inventory 확인 후 매핑 결정, 실제 실행으로 rebind 또는 revoke 처리.
+- env admin token 회전 시점에 운영자가 SOP에 따라 신규 admin token을 환경 변수에 추가 → service rolling restart → 구 admin token 환경 변수 제거 절차를 단계적으로 수행한다.
+
+# 4. 이번에 정의할 변경
+이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
+
+- client token 발급 경로 코드 폐지: `POST /auth/tokens` HTTP route, `issue_client_token` service 메서드, `CreateClientTokenRequest`/`IssuedClientTokenResponse` schemas, 관련 테스트
+- service-token rotate unique index 보강: `idx_auth_tokens_service_name_unique`에 `AND revoked_at IS NULL` 조건 추가 또는 동등 효과 정책 채택
+- `POST /auth/service-tokens` HTTP body의 `daemon_id` forward 정상화: `auth_routes.py:131-137` 호출 시 `payload.daemon_id` 전달
+- 토큰 발급 권한 매트릭스·만료·회전 정책을 baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`)에 명시
+- daemon deactivation 시 바인딩 service token 자동 revoke 동작 추가 (`pfhub daemon update --deactivate` 흐름)
+- NULL daemon_id legacy token 마이그레이션 자동화: 신규 CLI 서브커맨드(`pfhub service-token migrate-null-daemon`) 또는 일괄 스크립트, dry-run + report 포함
+- env admin token 운영 SOP 정의: `docs/runtime-flows.md` 또는 `README.md`에 회전·폐기 절차 추가
+- baseline 문서 정합성 회복: `pfhub service-token rebind` CLI 명세 추가, `AuthContext` 필드 목록에 `daemon_id` 추가, 토큰 surface 전체 명세 갱신
+
+## 영향 범위
+변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
+
+- 코드 영향:
+	- `app/api/auth_routes.py`: `POST /auth/tokens` 라우트 + 관련 dependency 제거; `POST /auth/service-tokens`에서 `payload.daemon_id` forward 보정
+	- `app/services/auth_service.py`: `issue_client_token` 메서드 제거; `revoke_tokens_for_daemon(daemon_id)` 등 신규 헬퍼 도입 검토
+	- `app/schemas/auth.py`: `CreateClientTokenRequest`, `IssuedClientTokenResponse` 제거
+	- `app/repositories/postgres.py`: `idx_auth_tokens_service_name_unique` 조건 보강(`ensure_schema` + Alembic migration), daemon deactivation 시 바인딩 token 일괄 revoke를 위한 repository 메서드 추가
+	- `app/repositories/portfolio_repository.py`: Protocol에 신규 메서드 선언
+	- `app/cli/commands/daemon.py`: `update --deactivate` 동작에 자동 revoke 호출 추가
+	- `app/cli/commands/service_tokens.py`: `migrate-null-daemon` 신규 서브커맨드(또는 별도 모듈) 추가
+	- `migrations/versions/`: 신규 Alembic revision — partial index 조건 보강(CONCURRENTLY 적용 권장)
+	- `tests/`: client 폐지 후 호출 경로 회귀 테스트, rotate 정상화 통합 테스트, daemon deactivation 자동 revoke 회귀 테스트, NULL daemon_id 마이그레이션 dry-run 테스트
+- 문서 영향:
+	- `docs/interface-contract.md`: client 발급 경로 제거, `pfhub service-token rebind` 명세 추가, 토큰 발급 권한 매트릭스 표 추가, 만료·회전 정책 명시
+	- `docs/runtime-flows.md`: 토큰 발급/회전/리바인드/자동 revoke flow, `AuthContext` 필드 목록에 `daemon_id` 추가, env admin token 운영 SOP flow
+	- `docs/data-model.md`: `auth_tokens` 인덱스 변경 반영, 토큰 surface 3종 정리
+	- `docs/project-structure.md`: 신규 마이그레이션 스크립트/CLI 서브커맨드 추가에 따른 패키지 책임 갱신(필요 시)
+	- `README.md`: daemon provisioning runbook 갱신 (auto-revoke 정책 반영), env admin token 회전 SOP 섹션 추가
+- 운영 영향:
+	- 기존 발급된 client token 보유자 영향: 폐지 release 전 inventory 조사 + 보유자 통보 필요 (R-1)
+	- service-token rotate migration이 partial index recreate를 포함하므로 운영 시간대·CONCURRENTLY 적용 검토 필요 (R-2)
+	- daemon deactivation 자동 revoke가 in-flight 거래에 영향 가능 — graceful drain 절차 검토 (R-3)
+	- env admin token 회전 SOP가 잘못 적용되면 운영 차단 발생 — 다단계 절차 + rollback 명시 (R-4)
+
+# 5. 요구사항 목록
+실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
+
+## 기능 요구사항
+- FR-1: client token 발급 경로 코드 폐지 — `POST /auth/tokens` HTTP route, `app/services/auth_service.py:issue_client_token`, `CreateClientTokenRequest`, `IssuedClientTokenResponse`, 관련 테스트 모두 제거. 기존 발급된 client token 처리 정책(OQ-1 Answered 2026-05-20): **즉시 코드 폐지로 진행**. DATA-1 inventory(2026-05-20)에서 active client token 0건 확인됐으므로 별도 revoke 스크립트 실행이나 grace period 운영 불필요. 폐지 release 직전 동일 쿼리로 재확인하는 절차만 release plan에 포함한다.
+- FR-2: `idx_auth_tokens_service_name_unique` partial index 조건 보강 (OQ-2 Answered 2026-05-20) — 현행 `WHERE token_type='service'`에 `AND revoked_at IS NULL` 추가. `ensure_schema()`(app/repositories/postgres.py)와 신규 Alembic migration 양쪽 갱신. 기존 active service token 행에는 영향 없음. migration은 `CREATE INDEX CONCURRENTLY` 적용으로 R-2 lock 영향 최소화(autocommit 외부 트랜잭션 필요).
+- FR-3: `POST /auth/service-tokens` HTTP body `daemon_id` forward 정상화 — `app/api/auth_routes.py:131-137`이 `payload.daemon_id`를 `service.issue_service_token` 호출에 전달. CLI `--daemon-id`와 동등 동작 보장. 비존재/비활성 daemon 지정 시 동일한 ValueError → HTTP 4xx 변환.
+- FR-4: baseline 문서 정합성 회복 — `docs/interface-contract.md` CLI surface에 `service-token rebind` 추가, `docs/runtime-flows.md` `AuthContext` 필드 목록에 `daemon_id` 추가, 토큰 surface 전체(env vs DB, session/service 만료 정책, rotate runtime_id/daemon_id invariant) 명세 갱신.
+- FR-5: 토큰 발급 권한 매트릭스 정의 — type(session/service/env) × 발급자 권한(admin/trade-write/read) × 발급 가능 여부의 표를 `docs/interface-contract.md`에 명시. (client는 폐지 후 표에서 제거.) 매트릭스 위반 호출은 HTTP 403 fail-closed. **admin이 자기 자신에게 service token을 발급하는 경로는 허용**(OQ-4 Answered 2026-05-20)하며 admin은 본인 user_id를 대상으로 daemon-bound 또는 unbound service token을 발급할 수 있다. 발급된 self-service token의 권한 한도는 admin이 명시한 permission이지만, 관행상 자기 자동화에 필요한 최소 권한(예: trade-write)으로 발급할 것을 매트릭스 주석에 권장.
+- FR-6: 토큰 만료·회전 정책 정의 (OQ-5 Answered 2026-05-20 — 현행 유지) — type별 기본 TTL을 `docs/runtime-flows.md`에 명시: session = `settings.session_token_ttl_hours`(현행 값 유지), service = 365일 default, env = 만료 없음. `no_expiry` 허용 범위는 **service 한정**(session/client 발급 경로 모두 거부). 강제 회전 주기는 본 정책에 두지 않으며 env admin token 회전 주기만 OQ-6에서 별도 결정한다. 정책 위반 발급(예: `no_expiry`를 session에 요청)은 HTTP 422 또는 ValueError로 거부.
+- FR-7: daemon deactivation 자동 revoke (OQ-3 Answered 2026-05-20 — 즉시 revoke) — `pfhub daemon update <id> --deactivate` 실행 시 해당 daemon에 바인딩된 service token(`auth_tokens.daemon_id == <id>` AND `revoked_at IS NULL`)을 **동일 트랜잭션 내에서 즉시 revoke**. graceful drain은 daemon 측 책임이며 trex-basic 등 daemon 구현이 종료 전 in-flight 처리를 수행할 것을 release plan에 명시. CLI에 `--keep-tokens` 같은 회피 옵션은 노출하지 않는다(정책 일관성). 동작 evidence는 revoked_at 갱신 timestamp로 추적.
+- FR-8: NULL daemon_id legacy token 마이그레이션 (OQ-7 Answered 2026-05-20 — 운영자 수동 매핑) — 신규 CLI 서브커맨드 `pfhub service-token migrate-null-daemon` 또는 동등 진단 스크립트. dry-run(`--dry-run`) 옵션으로 inventory + 매핑 후보(같은 `user_id`의 active daemon 목록) 출력. 실제 적용은 운영자가 token별로 `pfhub service-token rebind NAME --daemon-id ID`(매핑) 또는 `pfhub service-token revoke NAME`(폐기)을 수동 실행한다. 자동 매핑/auto-create daemon 경로는 노출하지 않는다(권한 escalation 위험). idempotent 작동(재실행 안전) 필수. 본 batch release 시점에는 DATA-2 inventory에서 발견된 admin 테스트 fixture 1건을 운영자가 직접 revoke 처리(별도 운영 작업).
+- FR-9: env admin token 운영 SOP 정의 (OQ-6 Answered 2026-05-20 — 분기 권장 주기, 강제 없음) — `docs/runtime-flows.md` 또는 `README.md`에 명시할 항목: (1) **권장 회전 주기**: 분기(3개월). 강제 회전·만료 알람 없음. (2) **운영자 권한 매트릭스**: env admin token 추가/제거는 인프라 운영자 권한. (3) **다단계 회전 절차**: 신규 token 생성(`python -c "import secrets; print(secrets.token_urlsafe(48))"` 권장) → `PORTFOLIOHUB_ADMIN_TOKENS`에 신규 token 추가(콤마 분리) → service rolling restart → 운영 검증 → 구 token 제거 → service rolling restart. (4) **회전 트리거 조건**: 정기(분기) / token leak 의심 / 운영자 교체·퇴사 / 보안 사고 대응. (5) **rollback 절차**: 회전 실패 시 환경 변수에 구 token 재추가 후 rolling restart. (6) **token 강도 가이드**: 최소 48-byte URL-safe 무작위. 평문 단어·예측 가능한 패턴 금지.
+- FR-10: `docs/data-model.md`, `docs/project-structure.md` baseline 갱신 — `auth_tokens` 인덱스 변경 반영, 토큰 surface 3종 정리, 신규 CLI/migration 파일 책임 반영(필요 시).
+
+## 비기능 요구사항
+성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
+
+- NFR-1: client token 폐지 후 dcy-003 v1 portfolio mutation 동작에 회귀 없음. `token_type='client'` 자체가 생성 불가하므로 dcy-003 FR-1/3/4/5의 게이트 로직은 유지하되 실 트래픽에서는 자연 사라짐.
+- NFR-2: service-token rotate는 `docker-compose.local-test.yml` 실 DB 환경에서 unique 위반 없이 성공해야 한다. staging 환경 통합 검증 필수.
+- NFR-3: 기존 service-token의 daemon_id invariant(rotate 시 daemon_id 유지)는 본 Discovery 변경 후에도 보존. runtime_id는 매 rotate마다 갱신.
+- NFR-4: 토큰 발급 권한 매트릭스의 위반 호출은 HTTP 403 fail-closed로 통일.
+- NFR-5: NULL daemon_id 마이그레이션은 idempotent. 재실행 시 안전, 부분 실패 시 보고된 예외 목록과 일치.
+- NFR-6: `idx_auth_tokens_service_name_unique` 변경 migration은 운영 환경에서 long-running lock 회피를 위해 CONCURRENTLY 옵션 적용 또는 운영 시간대 적용 권장.
+
+## 범위 경계
+이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
+
+- In Scope
+	- client token 발급 경로 코드 폐지 + 기존 토큰 처리 절차
+	- service-token rotate unique index 보강 + migration
+	- HTTP `POST /auth/service-tokens` body daemon_id forward 정상화
+	- 토큰 발급 권한 매트릭스 정의 (baseline 명시)
+	- 토큰 만료·회전 정책 정의 (baseline 명시)
+	- daemon deactivation 자동 revoke
+	- NULL daemon_id legacy token 마이그레이션 자동화 (CLI + dry-run)
+	- env admin token 운영 SOP 정의
+	- baseline 문서 정합성 회복 (rebind, AuthContext daemon_id, 토큰 surface 전체)
+- Out of Scope
+	- 신규 토큰 타입 도입 (Personal Access Token, OAuth, API key 서비스) — 별도 Discovery
+	- user 신원/SSO 통합 — 별도 Discovery
+	- 토큰 사용 감사 로그·audit trail 정책 — 별도 Discovery (단, daemon deactivation 자동 revoke의 logging은 본 Discovery 범위)
+	- token 시각 동기화·시간대 정책 — 별도 운영 Discovery
+	- service-token 발급량/rate-limit 정책 — 별도 Discovery
+
+# 6. 리스크/가정 목록
+불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
+
+## 리스크
+- R-1 (해소됨, 잔여 모니터링 Low): DATA-1 inventory(2026-05-20)에서 active client token 0건 확인됐으므로 폐지 release 시 보유자 영향 없음. 잔여 리스크는 release 직전 새로 발급된 client token이 0건이 아닐 가능성뿐이다.
+	- 완화 방안: 폐지 release 직전 `SELECT COUNT(*) FROM auth_tokens WHERE token_type='client' AND revoked_at IS NULL` 재확인을 release plan에 포함. >0이면 발급 사유 조사 후 즉시 revoke 또는 release 보류.
+- R-2 (High): `idx_auth_tokens_service_name_unique` partial index 재생성이 long-running lock을 유발하면 운영 중 auth_tokens 쓰기가 블로킹된다.
+	- 완화 방안: Alembic migration에 `CREATE INDEX CONCURRENTLY` 적용(단, autocommit 외부 트랜잭션 필요), 운영 시간대 적용, staging 환경 dry-run으로 lock 시간 사전 측정. partial index 변경이 어려우면 OQ-2의 대안(name suffix 부여)으로 전환.
+- R-3 (Medium): daemon deactivation 즉시 revoke(OQ-3 Answered)는 정책상 단순하나 in-flight ledger trade가 진행 중인 시점에 deactivation이 실행되면 거래 기록이 누락될 수 있다.
+	- 완화 방안: graceful drain은 daemon 구현 측 책임으로 분리(trex-basic이 종료 신호 수신 시 in-flight 마무리 후 종료). release plan에 deactivation SOP를 "(1) daemon 프로세스 종료/drain 완료 확인 → (2) `pfhub daemon update --deactivate` 실행 → (3) 자동 revoke" 순서로 명시. deactivation 호출 전 daemon process health check 권장.
+- R-4 (Medium): env admin token 회전 절차가 잘못 적용되면 운영자가 admin HTTP/CLI 접근을 잃어 회복 자체가 불가.
+	- 완화 방안: env admin token 회전 SOP에 다단계 절차(신규 token 추가 → 동시 운영 기간 → 구 token 제거) + rollback 절차 명시. 회전 중 fallback admin 접근 경로(예: DB 직접 접근으로 토큰 재생성) 보장.
+- R-5 (해소됨, 잔여 모니터링 Low): OQ-7에서 자동 매핑/auto-create daemon 경로를 채택하지 않기로 결정(2026-05-20)했으므로 권한 escalation 리스크는 본 Discovery 범위에서 발생하지 않는다. DATA-2 inventory(2026-05-20)에서 NULL daemon service token 1건만 발견됐고 운영자 확인 결과 테스트 fixture로 분류돼 본 batch 시점 release에 운영자가 직접 revoke 처리한다.
+	- 완화 방안: release 직전 동일 쿼리로 NULL daemon token 0건 재확인. >0이면 운영자가 token별 `rebind` 또는 `revoke` 수동 실행. `pfhub service-token migrate-null-daemon --dry-run` 보고에 `token.user_id`와 매핑 후보 daemon의 `owner_user_id` 일치 여부를 명시 표시(자동 매핑은 하지 않더라도 진단 데이터 제공).
+- R-6 (Low): 토큰 발급 권한 매트릭스 정의가 현행 dependency 체계(require_admin/require_read)와 불일치하면 구현 단계에서 광범위 회귀 가능.
+	- 완화 방안: 매트릭스 정의 단계에서 코드 grep으로 현행 dependency 사용처와 1:1 매핑 확인, 불일치 시 매트릭스나 dependency 중 한쪽 우선 조정.
+- R-7 (High, 본 Discovery 범위 밖 — 별도 hotfix 권장): DATA-3 수집(2026-05-20) 결과 **prod 환경에 env admin token이 약한 placeholder 값(`admin-token-789` — 예측 가능한 영문+숫자 패턴)으로 운영 중**. 환경 변수 leak 또는 단순 brute-force 시 즉시 admin 권한 escalation 가능. 본 Discovery는 토큰 surface 정비 batch이므로 단일 token 값 교체는 본 Discovery 외부 hotfix로 분리하며, 본 Discovery FR-9의 SOP가 이 hotfix의 표준 절차를 제공한다.
+	- 완화 방안: 본 Discovery confirm-discovery 이전이라도 보안상 즉시 hotfix 권장. 절차(FR-9 SOP 미리 적용): (1) 강한 무작위 token 생성, (2) `PORTFOLIOHUB_ADMIN_TOKENS`에 신규 token 추가, (3) service rolling restart, (4) 운영 검증, (5) 구 token(`admin-token-789`) 제거, (6) service rolling restart, (7) 회전 evidence 기록. hotfix 추적은 §10 DATA_PROD_ADMIN_TOKEN_HOTFIX 항목으로 관리.
+
+## 가정
+아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
+
+- A-1: 본 Discovery 후 토큰 surface는 4종(session/client/service/env)에서 3종(session/service/env)으로 정리된다. user의 자동화 use case는 admin이 발급한 service token으로 흡수한다(OQ-8 Answered 2026-05-20 — admin 발급 service token으로 충분). PAT 등 새 토큰 타입 도입은 본 batch 후 운영 피드백을 보고 별도 Discovery에서 판단한다.
+- A-2: dcy-003 FR-1/3/4/5의 token_type 게이트(`token_type ∈ {service, client}` 거부)는 client 폐지 후 "client는 더 이상 발급 불가"로 자연 강화. 게이트 자체는 env token 외부 침투 방어로 유지.
+- A-3: `idx_auth_tokens_service_name_unique` 보강은 단일 Alembic migration으로 처리 가능. 기존 active service token 행 데이터에는 변경 없음.
+- A-4: daemon deactivation 자동 revoke는 기존 daemon registry CRUD(dcy-006 모델 — `daemons` 테이블, `is_active` 플래그) 위에 얹는 동작이며 daemon 모델 자체에는 변경 없음.
+- A-5: env admin token 회전 SOP는 환경 변수 다중 등록(예: `PORTFOLIOHUB_ADMIN_TOKENS` 콤마 분리)이 가능한 현행 구조([app/core/auth.py:43-50](app/core/auth.py#L43-L50)의 `_resolve_permission`이 set 기반)를 활용해 다단계 운영이 가능하다.
+- A-6: 본 Discovery는 기존 service-token의 정상 운영 중 daemon binding을 변경하지 않는다. NULL daemon_id token만 마이그레이션 대상이며, 이미 daemon-bound token은 그대로 유지.
+
+## 오픈 질문
+답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
+
+- OQ-1: 기존 발급된 client token 처리 정책 — 폐지 release에서 즉시 일괄 revoke vs grace period(기간 명시) vs 자연 만료 대기?
+	- 상태: Answered
+	- 처리 방안: 즉시 코드 폐지로 결정(2026-05-20). DATA-1 inventory에서 active client token 0건 확인됐으므로 grace period/revoke 스크립트 불필요. 폐지 release 직전 동일 쿼리로 재확인하는 절차만 release plan에 포함.
+	- 반영 위치: FR-1 본문 갱신 완료, R-1 완화 방안 갱신 완료, §10 DECIDE에서 DECIDE_CLIENT_TOKEN_DEPRECATION_POLICY 처리 완료, §10 DATA에서 DATA_CLIENT_TOKEN_INVENTORY 수집 완료(0건).
+- OQ-2: `idx_auth_tokens_service_name_unique` 보강 방식 — `AND revoked_at IS NULL` partial 조건 추가 vs rotate 시 revoked row의 name suffix 부여(예: `<name>__revoked_<ts>`) vs unique 제약을 active row로만 한정하는 별도 모델 재설계?
+	- 상태: Answered
+	- 처리 방안: partial 조건 추가로 결정(2026-05-20). `WHERE token_type='service' AND revoked_at IS NULL`. 단일 Alembic migration + CONCURRENTLY 적용으로 R-2 lock 영향 완화. ensure_schema와 migration 양쪽 갱신.
+	- 반영 위치: FR-2 본문 갱신 완료, §10 DECIDE에서 DECIDE_ROTATE_UNIQUE_INDEX_STRATEGY 처리 완료.
+- OQ-3: daemon deactivation 자동 revoke 동작 — 즉시 revoke vs grace period(예: 30분 drain) vs 운영자 별도 확정 명령?
+	- 상태: Answered
+	- 처리 방안: 즉시 revoke로 결정(2026-05-20). `pfhub daemon update --deactivate` 실행 시 동일 트랜잭션 내에서 바인딩 service token 모두 revoke. graceful drain은 daemon 측 책임으로 분리. release plan에 deactivation SOP(drain 완료 확인 → deactivate 실행 → 자동 revoke) 명시.
+	- 반영 위치: FR-7 본문 갱신 완료, R-3 완화 방안 갱신 완료, §10 DECIDE에서 DECIDE_DAEMON_DEACTIVATION_REVOKE_TIMING 처리 완료.
+- OQ-4: 토큰 발급 권한 매트릭스에서 admin이 자기 자신에게 service token을 발급할 수 있는가? (admin이 본인 user_id로 service token 발급해 운영 자동화에 사용하는 시나리오)
+	- 상태: Answered
+	- 처리 방안: 허용으로 결정(2026-05-20). admin이 본인 user_id 대상으로 daemon-bound 또는 unbound service token 발급 가능. 권한 한도는 admin이 명시한 permission이며, 관행상 최소 권한(예: trade-write) 발급을 매트릭스 주석에 권장.
+	- 반영 위치: FR-5 본문 갱신 완료, §10 DECIDE에서 DECIDE_ADMIN_SELF_SERVICE_TOKEN 처리 완료.
+- OQ-5: 토큰 type별 기본 TTL — session(현행 `session_token_ttl_hours`), service(현행 365일 default), env(만료 없음) 유지 vs 신규 정책?
+	- 상태: Answered
+	- 처리 방안: 현행 유지로 결정(2026-05-20). session/service/env 각 정책이 운영상 안정. `no_expiry` 옵션은 service 한정. 강제 회전 주기는 OQ-6 env admin 결정으로 흡수.
+	- 반영 위치: FR-6 본문 갱신 완료, §10 DECIDE에서 DECIDE_TOKEN_TTL_POLICY 처리 완료.
+- OQ-6: env admin token 회전 주기 — 권장 주기(예: 분기/반기/연간), 강제 회전 여부?
+	- 상태: Answered
+	- 처리 방안: 분기(3개월) 권장 주기, 강제 회전 없음으로 결정(2026-05-20). 만료 알람 없음. SOP에 회전 트리거 조건(정기·leak 의심·운영자 교체·보안 사고)과 다단계 절차·rollback·token 강도 가이드를 명시.
+	- 반영 위치: FR-9 본문 갱신 완료, §10 DECIDE에서 DECIDE_ENV_ADMIN_ROTATION_INTERVAL 처리 완료, §10 DATA에서 DATA_ENV_ADMIN_TOKEN_ROTATION_HISTORY 수집 완료. 추가로 R-7(prod 약한 token hotfix) 신규 추가 및 §10 DATA_PROD_ADMIN_TOKEN_HOTFIX 추적 항목 추가.
+- OQ-7: NULL daemon_id legacy token 마이그레이션 매핑 전략 — 운영자 수동 매핑(token name 기반 추정) vs daemon auto-create 후 매핑 vs 폐기 후 재발급?
+	- 상태: Answered
+	- 처리 방안: 운영자 수동 매핑으로 결정(2026-05-20). CLI는 dry-run으로 inventory + 매핑 후보(같은 user_id의 active daemon) 진단만 제공하고 실제 적용은 운영자가 `rebind` 또는 `revoke`를 명시적으로 실행. 자동 매핑/auto-create daemon은 권한 escalation 리스크로 채택하지 않음. DATA-2 inventory(2026-05-20)에서 발견된 admin 테스트 fixture 1건은 운영자가 직접 revoke 처리.
+	- 반영 위치: FR-8 본문 갱신 완료, R-5 완화 방안 갱신 완료, §10 DECIDE에서 DECIDE_NULL_DAEMON_MIGRATION_STRATEGY 처리 완료, §10 DATA에서 DATA_NULL_DAEMON_TOKEN_INVENTORY 수집 완료(1건, 테스트 fixture).
+- OQ-8: client token 폐지 후 user 자동화 경로 — admin 발급 service token으로 충분한가, user가 본인 명의로 발급 가능한 새 토큰 타입(예: Personal Access Token)을 후속 Discovery에서 도입할지?
+	- 상태: Answered
+	- 처리 방안: admin 발급 service token으로 충분으로 결정(2026-05-20). 본 batch 후 토큰 surface 3종(session/service/env)으로 종료. PAT 등 새 토큰 타입은 본 batch 후 운영 피드백을 확인한 뒤 필요 시 별도 Discovery에서 검토.
+	- 반영 위치: A-1 갱신 완료, §10 DECIDE에서 DECIDE_USER_AUTOMATION_PATH_AFTER_CLIENT 처리 완료.
+
+### 오픈 질문 처리 기준
+- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
+- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
+- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
+- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
+- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
+- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
+- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
+
+# 7. 초기 성공 기준
+이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
+
+- S-1: codebase에서 client token 관련 코드 모두 제거 — `POST /auth/tokens` 라우트, `issue_client_token` 메서드, `CreateClientTokenRequest`/`IssuedClientTokenResponse` schemas grep 결과 0건.
+- S-2: 실 DB 환경에서 `pfhub service-token issue NAME --user U --no-expiry` → `pfhub service-token rotate NAME --force` 시퀀스가 unique 위반 없이 성공. 새 token의 `runtime_id`는 갱신, `daemon_id`는 유지.
+- S-3: `POST /auth/service-tokens` body `{"daemon_id": "<id>", "name": "...", "username": "..."}`로 호출 시 issued token의 `auth_token.daemon_id == <id>` 반환.
+- S-4: `pfhub daemon update <id> --deactivate` 실행 후 해당 daemon에 바인딩된 service token이 모두 `revoked_at IS NOT NULL` 상태로 전환 (또는 OQ-3 결정 방식대로 grace period 후 전환).
+- S-5: `pfhub service-token migrate-null-daemon --dry-run` 실행 시 NULL daemon_id token inventory + 매핑 후보가 보고로 출력. 실 실행 후 NULL daemon_id token이 0건 또는 예외 보고 목록과 일치.
+- S-6: baseline 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`, `docs/data-model.md`)에 토큰 surface 변경(client 제거, rebind 추가, AuthContext daemon_id, 발급 권한 매트릭스, 만료·회전 정책, 자동 revoke flow, env admin SOP) 모두 반영. baseline grep으로 누락 없음 확인.
+- S-7: env admin token 회전 SOP가 `docs/runtime-flows.md` 또는 `README.md`에 명시되어 있고, staging 환경에서 dry-run으로 회전 절차 실행 가능.
+
+## 측정 방식 및 데이터 출처
+각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
+
+- S-1 측정 방식: codebase grep(`grep -rn "issue_client_token\|CreateClientTokenRequest\|POST /auth/tokens"`) + pytest로 폐지된 endpoint 호출 시 HTTP 404/405 확인 / 데이터 출처: codebase grep 결과 + 신규 `tests/test_auth_surface_after_client_deprecation.py`
+- S-2 측정 방식: 실 DB(`docker-compose.local-test.yml`) 환경 통합 테스트 / 데이터 출처: 신규 `tests/test_service_token_rotate_integration.py` (DB 의존 마킹)
+- S-3 측정 방식: pytest로 HTTP request 시뮬레이션 / 데이터 출처: 갱신 `tests/test_auth.py`
+- S-4 측정 방식: pytest로 daemon deactivation 후 바인딩 token 상태 검증 / 데이터 출처: 갱신 `tests/test_daemon_registry.py`
+- S-5 측정 방식: CLI smoke + 마이그레이션 스크립트 단위 테스트 (dry-run 출력 검증 + idempotency 회귀) / 데이터 출처: 신규 `tests/test_null_daemon_migration.py`
+- S-6 측정 방식: baseline 문서 grep + 사람 리뷰 (`grep -n "service-token rebind\|AuthContext.daemon_id\|발급 권한 매트릭스\|만료·회전 정책" docs/`) / 데이터 출처: 갱신된 baseline 문서
+- S-7 측정 방식: SOP 문서 + 운영 환경 dry-run 실행 결과 / 데이터 출처: 갱신 `README.md` 또는 `docs/runtime-flows.md`의 env admin SOP 섹션
+
+# 8. REQ로 넘기기 전 확인 체크
+REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
+
+- [x] 범위(In Scope/Out of Scope) 확정
+	- 기준: OQ-1~8 전체 Answered 완료(2026-05-20). In/Out of Scope 경계 최종화 완료. CONFIRM 2건 모두 Confirmed. DATA-1/2/3 Collected. R-7(prod 약한 token hotfix)는 본 Discovery 범위 밖 별도 운영 작업으로 분리.
+- [x] 성공 지표의 측정 방식/데이터 출처 확정
+	- 기준: S-1~7 측정 방식이 §7 측정 방식 섹션에 각각 신규/갱신 pytest 시나리오(`tests/test_auth_surface_after_client_deprecation.py`, `tests/test_service_token_rotate_integration.py`, `tests/test_auth.py`, `tests/test_daemon_registry.py`, `tests/test_null_daemon_migration.py`) 또는 SOP 문서(`README.md`/`docs/runtime-flows.md`)로 명시 연결됨.
+- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
+	- 기준: R-1(client token 보유자 식별)은 DATA-1 0건 확인으로 해소(잔여 Low), R-2(migration lock)는 CONCURRENTLY 적용으로 완화. R-7(prod 약한 admin token)은 본 Discovery 외부 hotfix로 분리. 책임자 = repository-maintainers(본 Discovery 단계). REQ 작성 시 개별 작업 책임자가 REQ Impacted Area에 반영될 예정.
+- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
+	- 기준: OQ-1~8 전체 Answered 완료(2026-05-20). Open 상태 OQ 0건.
+- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
+	- 기준: §11 Confirmed By에 Justin 지정 완료(2026-05-20).
+- [x] dcy-003 의존성 확인
+	- 기준: dcy-003(draft)의 client token 폐지 결정이 본 Discovery로 이관됐음을 §3 제약사항·§9 참조에 반영 완료. 진행 순서: 본 Discovery 결정·confirm 완료 → dcy-003 잔여 항목 처리 재개(사용자 결정 2026-05-20).
+- [x] 운영 inventory 수집
+	- 기준: DATA-1(client token, 0건) / DATA-2(NULL daemon service token, 1건 테스트 fixture) / DATA-3(env admin token 1개, 약한 placeholder, 회전 이력 없음) 모두 Collected(2026-05-20). DATA_PROD_ADMIN_TOKEN_HOTFIX는 본 Discovery 외부 hotfix 추적 항목으로 잔존.
+
+# 9. 파일 처리 결과
+이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
+
+- 처리 결과: 생성
+- 생성 경로: docs/discovery/dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md
+- 참조 문서:
+	- docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md (선행 Discovery — client token 폐지 결정 위임, DATA_CLIENT_TOKEN_DEPRECATION_DISCOVERY 명시 예고)
+	- temp/2026-05-18_todo.md (운영 결함 inventory — service-token rotate 실패, HTTP body daemon_id 무시, rebind/AuthContext 문서 누락)
+	- temp/20260519_old_sdlc/releases/rel-006_20260513_daemon-model-implementation.md (rotate verification 실패 기록 + Feedback Handoff에 NULL daemon_id 마이그레이션·daemon deactivation 자동 revoke 잔존)
+	- app/core/auth.py, app/services/auth_service.py, app/api/auth_routes.py, app/schemas/auth.py, app/repositories/postgres.py, app/cli/commands/service_tokens.py, app/cli/commands/daemon.py (저장소 근거)
+	- docs/interface-contract.md, docs/runtime-flows.md, docs/data-model.md, docs/project-structure.md (본 Discovery로 갱신 예정)
+
+# 10. 사용자 결정 필요 항목 요약
+사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
+
+## DECIDE
+- ~~{{DECIDE_CLIENT_TOKEN_DEPRECATION_POLICY}}~~: **Decided** — 즉시 코드 폐지. DATA-1 inventory(2026-05-20) active client token 0건 확인, grace period/revoke 스크립트 불필요. release 직전 재확인만 release plan에 포함. FR-1·R-1·OQ-1 본문 반영 완료. (OQ-1 Answered 2026-05-20)
+- ~~{{DECIDE_ROTATE_UNIQUE_INDEX_STRATEGY}}~~: **Decided** — `idx_auth_tokens_service_name_unique`에 `AND revoked_at IS NULL` partial 조건 추가. CONCURRENTLY migration으로 R-2 lock 완화. FR-2·OQ-2 본문 반영 완료. (OQ-2 Answered 2026-05-20)
+- ~~{{DECIDE_DAEMON_DEACTIVATION_REVOKE_TIMING}}~~: **Decided** — daemon deactivation 즉시 revoke. graceful drain은 daemon 측 책임 분리. release plan에 SOP 명시. FR-7·R-3·OQ-3 본문 반영 완료. (OQ-3 Answered 2026-05-20)
+- ~~{{DECIDE_ADMIN_SELF_SERVICE_TOKEN}}~~: **Decided** — admin이 본인 user_id 대상으로 service token 발급 허용. 권한 한도는 명시 permission, 최소 권한 발급 권장. FR-5·OQ-4 본문 반영 완료. (OQ-4 Answered 2026-05-20)
+- ~~{{DECIDE_TOKEN_TTL_POLICY}}~~: **Decided** — 현행 TTL 정책 유지(session/service/env 각 정책). `no_expiry`는 service 한정. 강제 회전 주기는 env admin(OQ-6)에서 별도 결정. FR-6·OQ-5 본문 반영 완료. (OQ-5 Answered 2026-05-20)
+- ~~{{DECIDE_ENV_ADMIN_ROTATION_INTERVAL}}~~: **Decided** — 분기(3개월) 권장 주기, 강제 회전 없음. SOP에 다단계 절차·rollback·token 강도 가이드 명시. FR-9·OQ-6 본문 반영 완료. (OQ-6 Answered 2026-05-20)
+- ~~{{DECIDE_NULL_DAEMON_MIGRATION_STRATEGY}}~~: **Decided** — 운영자 수동 매핑. CLI는 dry-run 진단(inventory + 매핑 후보 user_id 일치 표시)만 제공, 실제 rebind/revoke는 운영자가 명시적으로 실행. 자동 매핑/auto-create 미채택(권한 escalation 리스크). DATA-2 inventory(2026-05-20) 1건(admin 테스트 fixture)은 운영자가 직접 revoke 처리. FR-8·R-5·OQ-7 본문 반영 완료. (OQ-7 Answered 2026-05-20)
+- ~~{{DECIDE_USER_AUTOMATION_PATH_AFTER_CLIENT}}~~: **Decided** — admin 발급 service token으로 충분. PAT 등 새 토큰 타입은 본 batch 후 운영 피드백 확인 후 별도 Discovery에서 검토. A-1·OQ-8 본문 반영 완료. (OQ-8 Answered 2026-05-20)
+
+## CONFIRM
+- ~~{{CONFIRM_DISCOVERY_SCOPE_OPTION_C}}~~: **Confirmed** — 옵션 C(Wide — 토큰 발급/관리 전면 정비) 범위로 9개 변경 항목을 단일 batch로 다루는 결정 사용자 동의 완료. (2026-05-20)
+- ~~{{CONFIRM_DCY003_DEPENDENCY}}~~: **Confirmed** — dcy-003(draft)에서 결정된 client token v1 mutation 진입 차단 정책이 본 Discovery로 이관됐다는 의존성 관계 사용자 동의. 진행 순서: 본 Discovery 결정·confirm 완료 → dcy-003 잔여 항목 처리 재개. §3 제약사항·§8 체크리스트·§11 Handoff Rationale 반영 완료. (2026-05-20)
+
+## DATA
+- ~~{{DATA_CLIENT_TOKEN_INVENTORY}}~~: **Collected (2026-05-20)** — active client token 0건. `SELECT ... WHERE token_type='client' AND revoked_at IS NULL` 결과 0행. OQ-1 즉시 폐지 결정의 evidence.
+- ~~{{DATA_NULL_DAEMON_TOKEN_INVENTORY}}~~: **Collected (2026-05-20)** — NULL daemon_id active service token 1건. token name `admin`(user `500e336a-...`, created 2026-05-11, no_expiry). 운영자 확인 결과 **테스트 fixture, 운영 용도 없음**. release 시점에 운영자가 `pfhub service-token revoke admin` 수동 실행으로 정리. OQ-7 수동 매핑 결정의 evidence.
+- ~~{{DATA_ENV_ADMIN_TOKEN_ROTATION_HISTORY}}~~: **Collected (2026-05-20)** — prod 환경 `PORTFOLIOHUB_ADMIN_TOKENS=admin-token-789` 1개 운영 중. **token 강도: 약함**(예측 가능 영문+숫자 placeholder, dev default 추정). 회전 이력 없음(최초 발급 후 미회전). SOP 부재. OQ-6 회전 주기 결정 및 R-7 hotfix 트리거의 evidence.
+- ~~{{DATA_PROD_ADMIN_TOKEN_HOTFIX}}~~: **External tracking (본 Discovery 외부 hotfix)** — prod 환경 `admin-token-789` 교체는 §6 R-7로 추적. 본 Discovery는 SOP(FR-9)를 정의하고 hotfix는 그 SOP를 적용하는 운영 작업이라 본 Discovery confirm-discovery 게이트 차단 사유는 아님. 실행 evidence는 운영 노트에 별도 기록.
+
+# 11. Discovery Freeze
+REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
+
+## 섹션 참조
+- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
+- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
+- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
+- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
+- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
+
+## Freeze 플래그
+- Handoff Decision: 승인
+- Handoff Rationale: OQ-1~8 전체 Answered + CONFIRM 2건 모두 Confirmed + DATA-1/2/3 모두 Collected + §8 체크리스트 7건 모두 [x] 완료(2026-05-20). confirm-discovery 게이트 통과로 본 Discovery는 `confirmed` 상태로 승급되어 REQ 초안 작성 가능. **외부 의존 항목**: R-7(prod 약한 admin token) hotfix는 본 Discovery 외부 운영 작업이라 별도 처리, dcy-003 잔여 처리 + dcy-001 REQ Approved는 batch 통합 시점 의존성으로 §3 제약사항에 명시됨.
+- Ready for REQ Drafting: true
+- Confirmed By: Justin
+- Confirmed At (KST): 2026-05-20T11:00+09:00

docs/discovery/index.md

@@ -8,3 +8,5 @@
 |---|---|---|---|---|
 | dcy-001_20260519_asset-catalog-and-user-portfolio-model | 20260519 | 자산 관리 구조 재설계 — admin 관리 asset catalog와 user portfolio 분리 모델 도입 | [Discovery](./dcy-001_20260519_asset-catalog-and-user-portfolio-model.md) | confirmed |
 | dcy-002_20260519_tag-ownership-and-applicability-policy | 20260519 | 태그 소유권 및 적용 대상 정책 — admin/user 구분 태그 모델과 asset·portfolio 적용 정책 도입 | [Discovery](./dcy-002_20260519_tag-ownership-and-applicability-policy.md) | confirmed |
+| dcy-003_20260520_user-portfolio-mutation-v1-api-migration | 20260520 | User Portfolio Mutation v1 API 이전 및 path 명명 분리 (/v1/portfolios* 신설) | [Discovery](./dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md) | confirmed |
+| dcy-004_20260520_token-issuance-and-lifecycle-overhaul | 20260520 | 토큰 발급 및 관리 전면 정비 — client token 폐지, service-token rotate 정상화, 발급 권한 매트릭스, 만료·회전·자동 revoke 정책 | [Discovery](./dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md) | confirmed |