feat: REQ-005 assets table tag apply/remove SQL alignment (BAT-013)

- REQ-005 CHG-20260521-02 follow-up: clarify AC-1/AC-5 to target assets table
- Add append_asset_tag_id/remove_asset_tag_id on PostgresPortfolioRepository
- Replace internal calls in apply_asset_tag/remove_asset_tag routes (HTTP contract unchanged)
- 7 new regression tests: method existence, SQL target table, error branches, idempotency guard
- Update existing AC-1/AC-5 assertions to verify new methods + portfolios methods uncalled
- Documentation: runtime-flows.md flow body + change log; rel-001 includes BAT-013
- REQ-005 transition: Approved → Implemented (CHG-20260521-03) via BAT-013 verification
- Total tests: 362 → 369 passed

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/releases/index.md

@@ -8,4 +8,4 @@
 
 | REL ID | Profile | Status | Included Batch | Date | Doc |
 | --- | --- | --- | --- | --- | --- |
-| REL-001 | app-service | draft | BAT-001~012 | 2026-05-21 | [rel-001](./rel-001_20260521_v1-api-full-surface.md) |
+| REL-001 | app-service | draft | BAT-001~013 | 2026-05-21 | [rel-001](./rel-001_20260521_v1-api-full-surface.md) |

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

@@ -2,7 +2,7 @@
 
 - Status: draft
 - 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
+- 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
 
 ## Scope
 - Included:
@@ -18,6 +18,7 @@
   - 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 스키마 무변.
 - Excluded:
   - REQ-013 (Deprecated): GET /v1/assets 토큰 타입별 분기 재정의 — dcy-003 옵션 B 결정으로 무효화
   - trex-basic 내부 코드 변경 (별도 레포 — 본 릴리즈와 동시 배포 필요)
@@ -29,6 +30,7 @@
 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)
+   - `POST/DELETE /v1/assets/{id}/tags` 내부 SQL이 `assets` 테이블 대상으로 정합화됨 (BAT-013) — HTTP contract 무변, DB 스키마 무변
 4. **trex-basic 배포**: 신 path로 전환된 클라이언트 배포
    - **이 단계가 완료되기 전까지 구 path 호출 불가 — portfolio-hub 배포 후 즉시 trex-basic 배포 수행**
 5. **배포 후 smoke 검증**: health endpoint + 신 path 동작 확인
@@ -46,12 +48,14 @@
   - [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 passed @ 2026-05-21 BAT-012 confirm-batch-verification**)
+  - [x] 전체 테스트 suite pass 확인 (BAT-001~011: 340 passed @ main 4bf6b55; BAT-012 추가 후: 362 passed @ 2026-05-21 BAT-012 confirm-batch-verification; BAT-013 추가 후: **369 passed @ 2026-05-21 BAT-013 confirm-batch-verification** — +7 신규 회귀: assets 테이블 mutation 정합성 검증)
 - **배포 직후 (portfolio-hub)**:
   - [~] `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 의존 동작으로 통과한 것으로 우회 확인.
   - [x] `GET /v1/assets` (admin token) → HTTP 200 (asset catalog 조회) — **이전 로컬 smoke (2026-05-21 17:08 KST)**에서 admin session token으로 HTTP 403 발생. **BAT-012에서 해소** (2026-05-21): REQ-010 augmentation(CHG-20260521-02 AC-9~12) 구현으로 GET /v1/assets가 admin catalog 응답을 반환하도록 재정의됨. 자동 회귀 통과: `tests/test_asset_catalog.py::test_get_v1_assets_admin_returns_catalog_response` + status/market 필터 + non-admin(user/service) 403. 실 배포 환경 smoke는 REL 배포 시 재확인.
   - [x] `POST /v1/portfolios` (user session token) → HTTP 201 (portfolio 생성) — **로컬 smoke (2026-05-21 17:13 KST)**: admin session token + active asset(`bab52e11-...`)으로 호출, HTTP 201 + `portfolio_id=c629c31e-b77d-44fb-a515-0edfe4f00cee` 생성 확인. `_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-05-21 17:13 KST)**: HTTP 404 `{"detail":"Not Found"}` 확인. BAT-011 신/구 path 동시 서빙 없음 정책 충족.
+  - [ ] `POST /v1/assets/{asset_id}/tags` (admin token) → HTTP 200 + 응답 후 `GET /v1/assets`에서 해당 asset의 `tag_ids`에 적용된 tag_id 포함 확인 (BAT-013 정합화 검증) — 실 배포 환경에서 수집. unit-level은 cursor-mock SQL 검증으로 1차 안전망 확보.
+  - [ ] `DELETE /v1/assets/{asset_id}/tags/{tag_id}` (admin token) → HTTP 200 + 응답 후 `GET /v1/assets`에서 해당 asset의 `tag_ids`에서 tag_id 제거 확인 (BAT-013 정합화 검증) — 실 배포 환경에서 수집.
 - **trex-basic 배포 직후**:
   - [ ] `POST /v1/portfolios/{id}/ledger/trades` (service token) → HTTP 201 + `status="new"` (신 path 동작 확인)
   - [ ] daemon assignment 인가 3단계 정상 동작 확인
@@ -69,7 +73,9 @@
 - Operator:
   - (배포 수행자 — 배포 시 기록)
 - Revision or Artifact:
-  - main branch commit: `4bf6b55` (feat: v1 portfolio mutation, sub-resources, ledger path migration BAT-008~011) + BAT-012 commit (assets.tag_ids + GET /v1/assets admin catalog 재정의, 본 release 진입 시 commit hash 기록)
+  - main branch commit: `4bf6b55` (feat: v1 portfolio mutation, sub-resources, ledger path migration BAT-008~011)
+  - + BAT-012 commit: `9038f41` (feat: REQ-002/REQ-010 implementation — assets.tag_ids column + GET /v1/assets admin catalog)
+  - + BAT-013 commit: (assets 테이블 tag apply/remove SQL 정합화 — 본 release 진입 시 commit hash 기록)
 - Commands or Procedure:
   - `alembic upgrade head` → portfolio-hub rolling restart → trex-basic 배포
 
@@ -86,6 +92,7 @@
       - 통과 2건: POST /v1/portfolios (201), POST /v1/assets/{id}/ledger/trades (404)
       - 부분 통과 1건: GET /health (200, 단 `db_enabled` 필드 미노출)
       - **해소 1건**: GET /v1/assets (admin session token → 이전 403, BAT-012 augmentation으로 admin catalog 응답 재정의. 자동 회귀 통과 — tests/test_asset_catalog.py 50 passed)
+    - 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
@@ -114,7 +121,8 @@
   - session token의 no_expiry 코드 enforcement 미구현 (REQ-021 follow-up) — 후속 REQ 후보
   - ~~**GET /v1/assets token_type 게이트와 admin catalog 재정의 미정합**~~: **Resolved by BAT-012** (2026-05-21). REQ-010 CHG-20260521-02 augmentation(AC-9~12)을 BAT-012에서 구현 — GET /v1/assets가 `require_admin` 의존성으로 단일화되고 admin catalog 응답을 반환. session token이 admin permission을 가진 경우 정상 통과. 자동 회귀 9건 추가(test_get_v1_assets_*).
   - **/health 응답 모델에 `db_enabled` 필드 부재**: 운영 관점에서 health probe 결과로 DB 연결 상태를 외부 관찰자에게 노출하지 않는 상태. 체크리스트의 의도와 응답 모델 간 gap. `HealthResponse`([app/api/health.py:17-21](app/api/health.py#L17-L21)) 보강 또는 별도 readiness endpoint 분리 후보.
-  - **`POST/DELETE /v1/assets/{asset_id}/tags` 잘못된 테이블 대상화**: BAT-012 implementation 단계에서 발견. 라우트는 admin asset tagging을 의도하지만 내부적으로 `append_portfolio_tag_id`/`remove_portfolio_tag_id`(portfolios 테이블)를 호출. assets.tag_ids 컬럼은 본 release로 도입되었으나 apply/remove 경로가 정합되지 않아 실제로 채워지지 않음. **REQ-005 follow-up REQ 또는 신규 REQ 후보**.
+  - ~~**`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 후보**.
 - REQ Input:
   - (운영 관찰 후 기록)
 - Change Request Input: