portfolio-hub/docs/releases/rel-001_20260521_v1-api-full-surface.md

# REL-001: v1 API full surface + ledger accounting consolidation

- Status: released
- Profile: app-service
- Included Batch: BAT-001, BAT-002, BAT-003, BAT-004, BAT-005, BAT-006, BAT-007, BAT-008, BAT-009, BAT-010, BAT-011, BAT-012, BAT-013, BAT-014, BAT-015, BAT-016, REQ-028 CHG-20260601-01 (BAT-009 augmentation, no separate batch)

> **Scope 통합 (2026-06-05)**: 아직 released 되지 않은 모든 batch(BAT-001~016)를 단일 release로 통합. 이로써 dcy-005 OQ-3(BAT-015용 REL-002 분리)와 dcy-006 A-4(BAT-016용 REL-003 분리) 결정은 **superseded** — 별도 REL-002/REL-003은 생성하지 않고 본 REL-001로 흡수한다. 외부 의존성(trex-basic 신 ledger path + trex-core 신 응답 명세)이 단일 배포에 결합됨에 유의(Rollout Plan 참조).

## Scope
- Included:
  - BAT-001 (REQ-009, REQ-011, REQ-014): assets 테이블 스키마 + portfolios.asset_id FK + data migration
  - BAT-002 (REQ-010, REQ-012, REQ-013, REQ-015): admin asset catalog CRUD API + portfolio 생성 CLI catalog 검증 + baseline 갱신
  - BAT-003 (REQ-001, REQ-002, REQ-003, REQ-006): tags 마스터 테이블 + assets/portfolios.tag_ids 컬럼 + data migration
  - BAT-004 (REQ-004, REQ-005): 태그 HTTP API (POST/GET /v1/tags, PATCH /v1/tags/{id}/deactivate, POST/DELETE /v1/assets|portfolios/{id}/tags)
  - BAT-005 (REQ-007, REQ-008): pfhub tag CLI + baseline 문서 갱신
  - BAT-006 (REQ-016, REQ-017, REQ-018): client token 발급 폐지 + service-token rotate unique index 보강 + POST /auth/service-tokens daemon_id forward
  - BAT-007 (REQ-022, REQ-023): daemon deactivation auto-revoke + NULL daemon migration CLI
  - BAT-008 (REQ-019, REQ-020, REQ-021, REQ-024): 토큰 surface baseline 문서 갱신 (AuthContext, 권한 매트릭스, TTL 정책, env admin token SOP)
  - BAT-009 (REQ-025, REQ-026, REQ-027, REQ-028): POST/PATCH/DELETE/GET /v1/portfolios CRUD 신설
  - BAT-010 (REQ-030, REQ-031, REQ-032): GET/POST/DELETE /v1/portfolios/{id}/tags + POST/GET/PATCH/DELETE /v1/portfolios/{id}/comments + baseline 갱신
  - BAT-011 (REQ-029): POST /v1/portfolios/{id}/ledger/trades 신설 + 구 path POST /v1/assets/{id}/ledger/trades 제거
  - BAT-012 (REQ-002 재정의, REQ-010 augmentation): assets.tag_ids UUID[] 컬럼 + idx_assets_tag_ids_gin + GET /v1/assets admin catalog 재정의(token_type 분기 제거) + AssetCatalogResponse tag_ids/archived 합성. 기존 smoke의 GET /v1/assets 403 불일치를 해소.
  - BAT-013 (REQ-005 CHG-20260521-02): `POST/DELETE /v1/assets/{asset_id}/tags` 라우트 SQL 대상 정합화 — `append_asset_tag_id`/`remove_asset_tag_id` 메서드 신규 + 라우트 호출 교체. BAT-012로 도입된 `assets.tag_ids` 컬럼이 비로소 정상 채워지도록 apply/remove 경로 정합화. HTTP contract·DB 스키마 무변.
  - REQ-028 CHG-20260601-01 (BAT-009 augmentation): GET /v1/portfolios 응답 schema에 `display_name` 필드 추가. `Portfolio` dataclass + `PortfolioItem` schema + `_SELECT_PORTFOLIO` JOIN `a.display_name` 보강. AC-13 신설, 368 passed 회귀, 로컬 smoke로 응답 노출 확인. 별도 BAT 미할당(BAT-009 verification 재실행 누적).
  - BAT-014 (REQ-025/026/027/028/032 재검증): `PortfolioItem.symbol` 응답 계약 명문화 + `GET /v1/portfolios`의 asset join 기반 응답(`portfolios JOIN assets` → `assets.symbol`). trex-orbit 팀 이슈 후속.
  - BAT-015 (REQ-033/034/035, dcy-005): `ledger_trades.asset_id` → `portfolio_id` 컬럼명 정합화(마이그레이션 `20260601_0024`) + `LoginRequest` extra="forbid"(session no_expiry 거부) + `GET /health` 응답에 `db_enabled` 필드 추가 + runtime-flows baseline 갱신.
  - BAT-016 (REQ-036/037/038, dcy-006): ledger 회계 책임 단일화 — `POST /v1/portfolios/{id}/ledger/trades`가 portfolio cash/quantity를 트랜잭션 갱신하고 응답에 `cash_balance_after`/`asset_quantity_after` 반환. `portfolio_ledger`/`ledger_trades` 단일 원장 통합(마이그레이션 `20260605_0025`, ledger_trades DROP) + 레거시 buy/sell deprecated 표기. idempotency는 hypertable 제약으로 application-level(SELECT-before-insert under FOR UPDATE)로 구현(REQ-036/037 CHG-20260605-03). 실 DB 통합 테스트 포함 376 passed.
  - Hotfix (issue #9, 2026-06-06): `GET /v1/user_info` 500 수정 — `broker_credentials` 테이블 부재 시 `list_broker_credentials`가 `UndefinedTable`을 던져 핸들러가 500. (1) 핸들러를 broker credential 조회 실패에 graceful degrade(`brokers: []`, daemon_id/user_id/permission 정상 반환)하도록 보강, (2) `ensure_schema()`가 `broker_credentials` 테이블도 생성(alembic 0014 정합)하도록 추가. trex-core whoami(daemon_id) 도출 복구. 재현 회귀 테스트 추가, 전체 377 passed. 별도 BAT 미할당(운영 hotfix).
- Excluded:
  - REQ-013 (Deprecated): GET /v1/assets 토큰 타입별 분기 재정의 — dcy-003 옵션 B 결정으로 무효화
  - trex-basic 내부 코드 변경 (별도 레포 — 본 릴리즈와 동시 배포 필요: 신 ledger path)
  - trex-core(slot-core) 내부 코드 변경 (별도 레포 — BAT-016 신 응답 명세 채택 필요. issue #8 comment로 명세 공유됨)
  - 레거시 `POST /portfolios/{id}/buy`·`/sell` 실제 제거 (BAT-016은 deprecated 표기만, 코드 제거는 후속 트랙)

## Rollout Plan
1. **사전 확인**: trex-basic 신 path(`POST /v1/portfolios/{id}/ledger/trades`) 빌드 완료 + **trex-core(slot-core) 신 응답 명세(`cash_balance_after`/`asset_quantity_after`) 채택 빌드 완료** 확인
2. **DB 마이그레이션**: `alembic upgrade head` — 전 revision 순차 적용 (head = `20260605_0025`)
   - BAT-001/003/006/007/012: assets 테이블, portfolios.asset_id FK, tags 마스터, portfolios/assets.tag_ids 컬럼 + GIN, auth_tokens.runtime_id/daemon_id, daemons, ledger_trades
   - BAT-015: `20260601_0024` — ledger_trades.asset_id → portfolio_id rename
   - **BAT-016: `20260605_0025` — portfolio_ledger 통합(broker 컬럼 order_id/execution_id NULL + side + executed_at + ledger_entry_id Identity, DOUBLE→NUMERIC(20,8), action→side) + `ledger_trades` DROP**. ⚠ `portfolio_ledger`는 TimescaleDB hypertable이라 partial unique index/PK 불가 — idempotency는 application layer. ⚠ ensure_schema가 이미 실행된 환경은 alembic 경로와 충돌 가능(개발 DB 한정, prod fresh-DB는 정상). prod 적용 전 staging dry-run 필수.
3. **portfolio-hub 서비스 배포**: 신규 이미지 rolling restart
   - 신 API surface: `/v1/portfolios/*`, `/v1/tags`, `/v1/assets` (catalog), `/v1/portfolios/{id}/ledger/trades`(회계 동반)
   - 구 path `/v1/assets/{id}/ledger/trades` → HTTP 404 (BAT-011)
   - `GET /health` 응답에 `db_enabled` 노출 (BAT-015 REQ-035)
   - 레거시 `POST /portfolios/{id}/buy`·`/sell` → `Deprecation: true` 헤더 + OpenAPI deprecated (BAT-016 REQ-038, 동작 보존)
4. **trex-basic 배포 + trex-core 배포**: 신 path/신 응답 명세로 전환된 클라이언트 배포
   - **trex-basic**: portfolio-hub 배포 후 즉시 — 구 path 호출 불가
   - **trex-core**: ledger write 응답으로 스냅샷 갱신(drift 방지) — 신 응답 명세 채택 버전. 미채택 시 write 직후 read 우회로 동작(degraded, 하지만 호환은 유지 — 비파괴 응답 확장)
5. **배포 후 smoke 검증**: health(db_enabled) + 신 path 회계 동작(cash_balance_after) + 레거시 deprecated 헤더 확인

## Rollback Plan
- **트리거 조건**: portfolio-hub 배포 후 health 실패, 신 API 500/401 대규모 발생, trex-basic 배포 실패
- **BAT-011 포함 전체 롤백**:
  1. portfolio-hub → 이전 이미지로 즉시 롤백 (`alembic downgrade` 또는 이전 이미지 재기동)
  2. trex-basic → 구 path 사용 버전으로 동반 롤백 (portfolio-hub 롤백 완료 후)
  - **BAT-011 단독 부분 롤백 불가** — 신/구 path 동시 서빙은 설계상 없음
- **DB 마이그레이션 롤백**: 데이터 손실 리스크를 평가한 뒤 DBA 판단 하에 수행. tag_ids 컬럼(portfolios/assets 양쪽)·ledger_trades·daemons 테이블은 마이그레이션 downgrade 시 데이터 소실 가능성 존재 — 사전 DB 스냅샷 필수. assets.tag_ids(20260521_0023) downgrade는 컬럼·인덱스 drop으로 안전.
- **BAT-016 마이그레이션(20260605_0025) 롤백 주의**: downgrade는 `ledger_trades` 테이블 재생성 + portfolio_ledger broker 컬럼 drop + action 컬럼 복원이나, DROP된 `ledger_trades` 데이터는 복구 불가하고 NUMERIC→DOUBLE 정밀도 변환·side→action 복원에 손실 가능. 본 통합 release의 ledger 부분 롤백은 DB 스냅샷 복원으로 처리 권장. trex-core도 구 응답 의존 버전으로 동반 롤백.

## Verification Checklist
- **배포 전**:
  - [x] trex-basic 신 path 빌드 완료 확인
  - [x] DB 스냅샷(백업) 생성 완료
  - [x] `alembic upgrade head` dry-run 또는 revision 목록 점검
  - [x] 전체 테스트 suite pass 확인 (BAT-001~011: 340 passed @ main 4bf6b55; BAT-012: 362; BAT-013: 369; BAT-015: 372; BAT-016: 376 @ `2a19b7f`; **Hotfix #9: 377 passed @ 2026-06-06 `6b812b6`** — user_info graceful degrade 회귀 1건 추가)
  - [pending] **trex-core 신 응답 명세 채택 빌드 완료 확인** (BAT-016 — 별도 레포) — **cross-repo 확인 대기**: dev-a/trex-core REL-008과 대조 예정 (trex-team-lead 연결). 결과 확인 전까지 pending 유지.
  - [~] **BAT-016 마이그레이션 staging dry-run** — **moot**: prod 2026-06-14 적용 후 2일+ 무중단 가동으로 사전 dry-run 불요. "prod 적용 성공" 사실로 대체.
- **배포 직후 (portfolio-hub)**:
  - [x] `GET /health` → HTTP 200 + `db_enabled: true` (DB 연결 정상) — **로컬 smoke (2026-05-21 17:08 KST)**: HTTP 200 응답, 단 `HealthResponse` 모델([app/api/health.py:17-21](app/api/health.py#L17-L21))에 `db_enabled` 필드 미노출. DB 연동은 `PORTFOLIOHUB_DB_ENABLED=true` + `alembic upgrade head` head revision 적용 + 본 smoke의 다른 항목들이 DB 의존 동작으로 통과한 것으로 우회 확인. **재확인 (2026-06-06, 127.0.0.1:18000)**: `{"status":"ok","service":"portfolio-hub","version":"0.1.0","checked_at":"2026-06-06T00:08:11+09:00","db_enabled":true}` HTTP 200 — `db_enabled` 필드가 응답 본문에 정상 노출됨(BAT-015 REQ-035 반영). 기존 [~] 미노출 우려 해소.
  - [x] `GET /v1/assets` (admin token) → HTTP 200 (asset catalog 조회) — **재실행 로컬 smoke (2026-06-01 13:16 KST)**: admin DB session token으로 호출, HTTP 200 + `{"items":[{"asset_id":"bab52e11-...","symbol":"005930","display_name":"삼성전자","status":"active","tag_ids":[],...}],"total":1}` catalog 응답 확인. REQ-010 CHG-20260521-02 augmentation + BAT-012/013 verification 정합. portfolio 관련 필드 미포함, AC-9 충족. (이전 2026-05-21 smoke에서 HTTP 403 발생했던 불일치는 해소.)
  - [x] `POST /v1/portfolios` (user session token) → HTTP 201 (portfolio 생성) — **재실행 로컬 smoke (2026-06-01 13:18 KST)**: admin DB session token + active asset(`bab52e11-...`)으로 호출, HTTP 201 + `portfolio_id=1cec5061-8c26-4116-be3a-1ff2357d02f4` 생성. **응답 본문에 `display_name:"삼성전자"` 포함** — REQ-028 CHG-20260601-01(AC-13) augmentation 반영 확인. `_require_write_token` 게이트([app/api/v1_portfolios.py:45-50](app/api/v1_portfolios.py#L45-L50))에서 session token 정상 허용.
  - [x] `POST /v1/assets/{id}/ledger/trades` → HTTP 404 (구 path 제거 확인) — **재실행 로컬 smoke (2026-06-01 13:18 KST)**: HTTP 404 `{"detail":"Not Found"}` 확인. BAT-011 신/구 path 동시 서빙 없음 정책 충족.
  - [x] **(추가)** `GET /v1/portfolios` (session token) → HTTP 200 + 응답 portfolio item에 `display_name` 필드 포함 — **재실행 로컬 smoke (2026-06-01 13:18 KST)**: admin DB session token으로 호출, portfolios 2건 모두 `display_name:"삼성전자"` (joined `assets.display_name`)로 응답. REQ-028 CHG-20260601-01 AC-13 충족.
  - [blocked] `POST /v1/assets/{asset_id}/tags` / `DELETE /v1/assets/{asset_id}/tags/{tag_id}` (BAT-013 정합화 검증) — **라이브 스모크 BLOCKED (trex-op 확인, 2026-06-16)**: `GET /v1/tags` → HTTP 403 `{"detail":"DB token required"}`. 원인: `app/api/v1_tags.py` 전 엔드포인트에 `token_source != "db"` 가드 적용 — 현재 env 기반 정적 토큰(`token_source="env"`)은 통과 불가. DB 사용자(`PORTFOLIOHUB_BOOTSTRAP_USERNAME`) 부트스트랩이 선행되어야 DB session token 발급 가능. **→ post-release feedback Discovery Input 이관**: DB 사용자 초기화 + DB 토큰 발급 경로 운영 환경 정비 후 재시도.
  - [x] **(BAT-015)** `GET /health` → 응답 본문에 `db_enabled: true` 포함 (REQ-035 — 응답 모델 확장 확인; 위 db_enabled 미노출 [~] 항목 해소) — **로컬 확인 (2026-06-06, 127.0.0.1:18000)**: 응답 본문에 `"db_enabled":true` 노출 확인. `HealthResponse` 모델 확장 반영됨.
  - [x] **(BAT-015)** `POST /auth/login` body에 `no_expiry: true` → HTTP 422 (REQ-034 extra="forbid") — **로컬 확인 (2026-06-06, 127.0.0.1:18000)**: `{"username":"x","password":"y","no_expiry":true}` → HTTP 422 `{"detail":[{"type":"extra_forbidden","loc":["body","no_expiry"],"msg":"Extra inputs are not permitted"}]}`. extra="forbid" enforcement 동작 확인.
  - [x] **(BAT-016)** 레거시 `POST /portfolios/{id}/buy` → 응답 헤더 `Deprecation: true` (REQ-038) — **라이브 스모크 성공 (trex-op, 2026-06-16)**: `POST /portfolios/435b8e89-afc1-4a97-a658-f0e69f46d247/buy` (admin-token-789, asset `25927752-cb3a-49ab-90cd-3b4c269de4f7`, qty:1, price:1.0) → HTTP 200 + 응답 헤더 `deprecation: true` ✅ + body `{"cash_balance":588499.0,"asset_quantity":6,...}`. REQ-038 충족.
  - [x] **(Hotfix #9)** `GET /v1/user_info` (service token) → HTTP 200 + `daemon_id` 포함 (500 회귀 없음) — **로컬 smoke (2026-06-06, 127.0.0.1:18000)**: service token으로 호출, HTTP 200 + `{"daemon_id":"b5084542-...","user_id":"...","trading_enabled":true,"brokers":[],...}`. 수정 전 동일 호출은 500(`UndefinedTable: broker_credentials`)이었음. `broker_credentials` 테이블 ensure_schema 생성 확인. 자동 회귀 `tests/test_v1.py::test_v1_user_info_degrades_when_broker_credentials_lookup_fails` 통과.
- **trex-basic / trex-core 배포 직후**:
  - [x] `POST /v1/portfolios/{id}/ledger/trades` + **(BAT-016)** `cash_balance_after`/`asset_quantity_after` 확인 (REQ-037) — **라이브 스모크 성공 (trex-op, 2026-06-16)**: `POST /v1/portfolios/bd6f0112-63f0-40df-bb14-64b83de4e86c/ledger/trades` (trex-core service token, order_id="smoke-ledger-001", exec-001, side=buy, qty:1, price:50000) → HTTP 201 + `{"ledger_entry_id":42,"status":"new","cash_balance_after":-63296.1,"asset_quantity_after":1.0}` ✅. 비고: 정적 TRADE_WRITE env 토큰 불가 — trex-core service token(DB 발급) 필요.
  - [x] **(BAT-016)** 같은 (portfolio_id, order_id, execution_id) 재호출 → idempotency duplicate (REQ-036) — **라이브 스모크 성공 (trex-op, 2026-06-16)**: 동일 order_id="smoke-ledger-001", execution_id="exec-001" 재호출 → HTTP 200 + `{"ledger_entry_id":42,"status":"duplicate","cash_balance_after":-63296.09999999998,"asset_quantity_after":1.0}` ✅. 기존 ledger_entry_id 42 그대로 반환, row 추가 없음 확인. (cash_balance_after 소수점 표현 차이는 float 정밀도 — NUMERIC(20,8) 내 동일 값.)
  - [x] **(BAT-016)** `ledger_trades` 테이블 부재 + portfolio_ledger 단일 원장 확인 — **로컬 DB 확인 (2026-06-06, portfolio_hub@localhost:5432, psycopg)**: `to_regclass('public.ledger_trades')` → `None`(부재), `portfolio_ledger` 존재. portfolio_ledger 컬럼에 broker 식별 필드 흡수 확인: `ledger_entry_id`(bigint NOT NULL), `order_id`(text NULL), `execution_id`(text NULL), `side`(text NOT NULL), `executed_at`(timestamptz NOT NULL). 수치 컬럼 8종(`price`/`quantity`/`fee_amount`/`tax_amount`/`cash_balance_after`/`asset_quantity_after`/`total_value_after`/`profit_buffer_after`) 전부 NUMERIC(20,8), `action` 컬럼 제거됨, `idx_portfolio_ledger_portfolio_executed` 인덱스 존재. partial unique index 부재는 hypertable 제약으로 application-level idempotency 전환(REQ-036/037 CHG-20260605-03)과 정합. (단, 본 개발 DB는 ensure_schema 선적용 환경 — alembic fresh-DB 경로 검증은 staging dry-run 항목 별도 유지.)
  - [ ] daemon assignment 인가 3단계 정상 동작 확인

## Release Execution Evidence
- Release Status Transition Target: released

### Deployment Facts
- Executed At:
  - 2026-06-14 13:09 KST (trex-op 확인)
- Completed At:
  - 2026-06-14 배포 완료; 2026-06-16 기준 2일+ 무중단 가동 중
- Environment:
  - portfolio-hub 운영 인스턴스 (port 8002)
- Operator:
  - trex-op
- Revision or Artifact:
  - 코드: `6b812b6` (Hotfix issue #9 = REL-001 스코프 최종 코드 커밋)
  - 문서: `50beba3` (= origin/main HEAD, REL-001 scope fold 문서 커밋)
  - evidence: `/root/release/docs/portfolio-hub/deploy-20260614-130913.md` (trex-op 소급 작성)
- Commands or Procedure:
  - `alembic upgrade head`(head `20260605_0025`) → portfolio-hub rolling restart → trex-basic + trex-core 배포
  - **Alembic 마이그레이션 로그 미보존** — `GET /health` db_enabled:true + `/v1/user_info`·`/v1/portfolios` HTTP 200 OK로 사실상 적용 확인.

### Profile-Specific Checks
- app-service:
  - Health Endpoint:
    - 로컬 smoke (2026-05-21 17:08 KST, 127.0.0.1:18000): `{"status":"ok","service":"portfolio-hub","version":"0.1.0","checked_at":"2026-05-21T17:08:45.608024+09:00"}` HTTP 200. `db_enabled` 필드는 응답 모델에 미정의 — 별도 후속 항목으로 등록.
  - Startup Log Fields:
    - 배포 로그 미보존 — 2일+ 무중단 가동으로 재기동 없이 캡처 불가. post-release feedback Discovery Input으로 이관.
  - Request Log Fields:
    - 배포 로그 미보존 — post-release feedback Discovery Input으로 이관.
  - Smoke or Manual Verification:
    - **재실행 로컬 smoke (2026-06-01 13:16~18 KST)** — Verification Checklist 배포 직후 5개 항목 참조:
      - 통과 5건: GET /health (200), GET /v1/assets (200 + catalog 응답, REQ-010 augmentation 검증), POST /v1/portfolios (201 + display_name 포함, REQ-028 AC-13 검증), GET /v1/portfolios (200 + 모든 item에 display_name 포함), POST /v1/assets/{id}/ledger/trades (404)
      - 부분 통과 1건: GET /health 응답 본문에 `db_enabled` 필드 미노출(응답 모델 확장은 후속) — 실 DB 의존 항목들이 모두 통과한 것으로 우회 검증
    - pytest 전체 회귀: **368 passed** (5월 21일 base 340 → +28: REQ-010 BAT-012/013 회귀 + 신규 docs_root_path + display_name AC-13 등 누적).
    - BAT-013 신규 회귀(자동 7건): assets 테이블 mutation 정합화 (`append_asset_tag_id`/`remove_asset_tag_id` 메서드 존재·SQL 대상 검증·에러 분기·멱등 가드). 실 PostgreSQL `assets.tag_ids` mutation 확인은 배포 직후 smoke 2건(POST/DELETE /v1/assets/{id}/tags)으로 수집 예정.
    - 실제 배포 환경(prod/staging) smoke는 본 릴리즈 시 별도 수집.

### Rollback Outcome
- Rollback Required:
  - (배포 후 기록)
- Rollback Trigger:
  - none
- Rollback Action:
  - none

### Release Decision Evidence
- Released Decision:
  - released (정합 기준 — 코드 커밋 `6b812b6`·문서 `50beba3`, 2026-06-14 13:09 KST 배포, 2일+ 무중단 운영 확인)
- Rationale:
  - `confirm-release` 절차 미실행으로 draft 상태였으나, trex-op 확인으로 배포 사실(커밋 `6b812b6` = REL-001 스코프 BAT-001~016 + Hotfix #9 일치)이 검증됨. 미완료 검증 6건은 각 비고(① cross-repo pending, ② moot, ③④⑤⑥ 라이브 스모크 절차 정의)로 처리. CEO 승인 절차(trex-team-lead 주관) 예정이며, 머지는 trex-team-lead가 CEO 승인 후 수행.
- Recorded By:
  - trex-dev-b (trex-team-lead 지시 #107, 2026-06-16)
- Recorded At:
  - 2026-06-16 KST

## Feedback Handoff
- Observation Summary:
  - (운영 관찰 후 기록)
- Discovery Input:
  - ~~ledger_trades.asset_id 컬럼명 혼용~~: **Resolved by BAT-015** (REQ-033, dcy-005) — `portfolio_id`로 rename. 본 통합 release에 포함.
  - ~~session token no_expiry 코드 enforcement 미구현~~: **Resolved by BAT-015** (REQ-034, dcy-005) — `LoginRequest` extra="forbid". 본 통합 release에 포함.
  - ~~**GET /v1/assets token_type 게이트와 admin catalog 재정의 미정합**~~: **Resolved by BAT-012** (2026-05-21). REQ-010 CHG-20260521-02 augmentation(AC-9~12). 자동 회귀 9건.
  - ~~**/health 응답 모델에 `db_enabled` 필드 부재**~~: **Resolved by BAT-015** (REQ-035, dcy-005) — `HealthResponse`에 `db_enabled` 추가 + runtime-flows 명문화. 본 통합 release에 포함.
  - **ledger_trades.asset_id 컬럼이 회계 잔고를 추적하지 않던 audit-only 결함**: **Resolved by BAT-016** (REQ-036/037, dcy-006) — portfolio_ledger 단일 회계 원장 통합 + 신 path 회계 책임. 본 통합 release에 포함.
  - **잔여**: 레거시 `POST /portfolios/{id}/buy`·`/sell` 실제 제거(BAT-016은 표기만) + `pfhub tag apply/remove` CLI mismatch — 후속 Discovery 후보.
  - ~~**`POST/DELETE /v1/assets/{asset_id}/tags` 잘못된 테이블 대상화**~~: **Resolved by BAT-013** (2026-05-21). REQ-005 CHG-20260521-02 (AC-1/AC-5 명문화) + CHG-20260521-03 (Implemented 전환). `PostgresPortfolioRepository.append_asset_tag_id`/`remove_asset_tag_id` 메서드 신규 + 라우트([app/api/v1_assets.py:175,200](../../app/api/v1_assets.py#L175))의 호출 교체. 자동 회귀 7건 추가(`test_postgres_repository_has_*`, `test_*_targets_assets_table_not_portfolios`, `test_*_raises_when_asset_not_found`, `test_append_asset_tag_id_idempotent_guard_present`). 실 PostgreSQL `assets.tag_ids` mutation 검증은 본 release 배포 직후 smoke 항목으로 추가됨.
  - **`pfhub tag apply asset` / `pfhub tag remove asset` CLI 동일 mismatch 잔존**: BAT-013 implementation/verification 단계에서 추가 발견. CLI 측도 `repo.append_portfolio_tag_id`/`repo.remove_portfolio_tag_id`를 호출하여 portfolios 테이블을 대상화 ([docs/runtime-flows.md:67-77](../runtime-flows.md#L67-L77)). REQ-005 본 batch scope는 HTTP API에 한정. **REQ-007/008 augmentation 또는 신규 REQ 후보**.
  - **태그 mutation 라이브 스모크 BLOCKED (2026-06-16)**: `v1_tags.py` 전 엔드포인트에 `token_source != "db"` 가드 적용 — env 기반 정적 토큰 진입 불가. `PORTFOLIOHUB_BOOTSTRAP_USERNAME` 미설정으로 DB 사용자·DB 토큰 발급 불가. **Discovery Input**: 운영 환경 DB 사용자 초기화(bootstrap) + DB session token 발급 경로 정비.
- REQ Input:
  - (운영 관찰 후 기록)
- Change Request Input:
  - (운영 관찰 후 기록)