feat: REQ-002/REQ-010 implementation — assets.tag_ids column + GET /v1/assets admin catalog (BAT-012)

- REQ-002 scope redefinition: portfolios.tag_ids → assets.tag_ids UUID[] column with GIN index
- REQ-010 augmentation: GET /v1/assets redesigned as admin catalog endpoint (admin-only, no token_type branching)
- Asset tagging infrastructure: tag_ids column, archived flag synthesis for inactive tags, list_assets N+1 optimization
- DB migration 20260521_0023: assets.tag_ids UUID[] NOT NULL DEFAULT '{}', idx_assets_tag_ids_gin
- Test suite: 17 new test cases for assets.tag_ids + GET /v1/assets AC-9~12 (362 tests total)
- Documentation: runtime flows, release baseline, batch verification all updated
- BAT-012 added to REL-001 Included Batch and marked release-candidate

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

docs/srs/Data/req-002_assets-tag-ids-column.md

@@ -6,38 +6,131 @@
 - Owner: Justin Ko
 
 ## Intent
-- assets(portfolios) 테이블에 UUID[] 배열 컬럼을 추가하여 junction 테이블 없이 tags 마스터 테이블 기반 태그 참조를 저장한다.
+- assets 카탈로그 테이블에 UUID[] 배열 컬럼을 추가하여 junction 테이블 없이 tags 마스터 테이블 기반 태그 참조를 저장한다.
+- admin이 카탈로그 종목에 분류 태그(예: "코스피200")를 부여할 수 있는 데이터 토대를 마련한다 (dcy-002 주요 시나리오).
 - GIN 인덱스로 배열 조회 성능을 확보하고, 비활성화된 태그는 조용히 제거하지 않고 archived 상태로 반환하여 이력 추적을 가능하게 한다.
 - 태그 적용 정책 검증(is_admin_tag=TRUE AND is_active=TRUE 확인, 403 반환)은 REQ-005에서 구현한다.
 
 ## Requirement
-- portfolios 테이블(asset에 해당)에 `tag_ids UUID[] NOT NULL DEFAULT '{}'` 컬럼을 추가해야 한다.
-- portfolios.tag_ids에 GIN 인덱스를 생성해야 한다.
+- assets 테이블에 `tag_ids UUID[] NOT NULL DEFAULT '{}'` 컬럼을 추가해야 한다.
+- assets.tag_ids에 GIN 인덱스(`idx_assets_tag_ids_gin`)를 생성해야 한다.
 - tag_ids 배열에 is_active = FALSE인 tag_id가 포함된 경우, 해당 항목을 조용히 제거하지 않고 archived 상태임을 명시하여 반환해야 한다.
 
 ## Acceptance Criteria
-1. Given Alembic 마이그레이션이 적용된 DB, When portfolios 테이블 스키마를 조회, Then tag_ids UUID[] NOT NULL DEFAULT '{}' 컬럼이 존재한다.
-2. Given 마이그레이션이 적용된 DB, When portfolios.tag_ids 인덱스를 조회, Then GIN 인덱스가 존재한다.
+1. Given Alembic 마이그레이션이 적용된 DB, When assets 테이블 스키마를 조회, Then `tag_ids UUID[] NOT NULL DEFAULT '{}'` 컬럼이 존재한다.
+2. Given 마이그레이션이 적용된 DB, When assets.tag_ids 인덱스를 조회, Then `idx_assets_tag_ids_gin` GIN 인덱스가 존재한다.
 3. Given asset의 tag_ids 배열에 is_active = FALSE인 tag_id가 포함, When 해당 asset의 태그 목록을 조회, Then 비활성 태그가 archived 표시와 함께 반환되며 배열에서 자동 제거되지 않는다.
 4. Given tag_ids = '{}' 기본값인 asset, When 태그가 적용되지 않은 상태로 조회, Then 빈 배열이 반환된다.
 
 ## Impacted Area
-- Docs: docs/data-model.md (portfolios 스키마에 tag_ids 컬럼 추가)
+- Docs: docs/data-model.md (assets 스키마에 tag_ids 컬럼 추가)
 - Modules:
-  - migrations/versions/ — portfolios.tag_ids 컬럼 추가 및 GIN 인덱스 생성 Alembic revision
-  - app/domain/models.py — Portfolio 도메인 모델에 tag_ids 필드 추가
-  - app/repositories/postgres.py — tag_ids 배열 조회 시 archived 표시 로직
-  - app/schemas/v1.py — AssetItem에 tag_ids 필드 추가
-- Tests: portfolios 테이블 스키마 검증, GIN 인덱스 존재 확인, archived 표시 동작 확인
+  - migrations/versions/ — assets.tag_ids 컬럼 추가 및 GIN 인덱스 생성 Alembic revision (신규)
+  - app/domain/models.py — Asset 도메인 모델에 tag_ids 필드 추가
+  - app/repositories/postgres.py — assets 조회 시 tag_ids 배열 archived 표시 로직
+  - app/schemas/v1.py — admin asset catalog 응답 스키마에 tag_ids 필드 추가 (REQ-010 augmentation 범위와 정합)
+- Tests: assets 테이블 tag_ids 스키마 검증, GIN 인덱스 존재 확인, archived 표시 동작 확인
 
 ## Notes
-- dcy-001의 assets 테이블(portfolios)이 확정된 이후 이 REQ를 구현해야 한다 (dcy-002 R-2).
+- REQ-009(assets 테이블 스키마 도입) 이후 이 REQ가 구현되어야 한다. REQ-009 Impacted Area에 본 REQ가 cross-reference된다.
 - 배열 참조 무결성은 애플리케이션 레이어에서 보장한다 (dcy-002 NFR-2). PostgreSQL ARRAY FK는 미사용.
-- portfolios 테이블이 v1 API의 "asset" 개념에 해당한다 (portfolio_id = asset_id in v1 API).
+- portfolios.tag_ids 컬럼은 REQ-003에서 독립적으로 관리한다 (dcy-002 FR-3).
 - Source: dcy-002 FR-2, NFR-2
 
 ## Change Log
 
+### CHG-20260521-03
+- Date: 2026-05-21
+- Author: Justin Ko
+
+#### Change Summary
+- Status: Approved → Implemented (CHG-20260521-02로 재정의된 assets.tag_ids 범위가 BAT-012 verification에서 evidence 확보)
+
+#### Intent
+- BAT-012 confirm-batch-verification 완료. assets.tag_ids 컬럼·GIN 인덱스·archived 표시·빈 배열 기본값 4개 AC 모두 evidence 연결됨.
+
+#### Acceptance Criteria Delta
+- No change
+
+#### Impacted Area Delta
+- No change
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-012 (release-candidate) — primary trace for assets.tag_ids 범위
+  - BAT-003 trace는 CHG-20260521-02에서 무효 처리됨 (구 portfolios.tag_ids 범위, REQ-003에서 실질 커버)
+- Releases:
+  - 신규 release 대상 (REL-002 등) — BAT-012 포함 release 발의 시 trace
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: implemented
+- Follow-up Action: REL 배포 시 alembic upgrade 결과로 DB-integration AC 최종 확인
+
+#### Validation Plan
+- tests/test_asset_catalog.py::test_migration_assets_tag_ids_adds_column_and_gin_index (AC-1, AC-2)
+- tests/test_asset_catalog.py::test_get_v1_assets_archived_flag_for_inactive_tag (AC-3 통합) + test_build_tag_refs_archived_for_inactive_tags (AC-3 단위)
+- tests/test_asset_catalog.py::test_asset_model_tag_ids_defaults_to_empty_list + test_asset_catalog_response_schema_has_tag_ids_field (AC-4)
+- 전체 회귀: 362 passed in 13.06s
+
+### CHG-20260521-02
+- Date: 2026-05-21
+- Author: Justin Ko
+
+#### Change Summary
+- Status: Implemented → Approved
+- Requirement scope 재정의: portfolios.tag_ids → assets.tag_ids (파일명·dcy-002 FR-2 의도와 정합성 회복)
+
+#### Intent
+- REQ-002 파일명(`req-002_assets-tag-ids-column.md`)과 dcy-002 FR-2(`assets.tag_ids UUID[]` 컬럼 추가, admin 태그만 적용 가능)에 본문을 정합화한다.
+- 기존 본문은 dcy-001 분리 결정 이전 `portfolios == "asset"` 등치 시절에 작성된 흔적으로, 실질적으로 REQ-003(portfolios.tag_ids)과 동일 범위였다.
+- assets.tag_ids 컬럼은 현재 마이그레이션(`migrations/versions/20260519_0017_create_assets_table.py`)에 부재하며, 본 REQ는 그 추가를 요구한다.
+
+#### Acceptance Criteria Delta
+- Removed (구 portfolios.tag_ids 범위 — REQ-003에서 동일 컬럼 커버됨):
+  - AC-1 (구) portfolios.tag_ids 컬럼 존재 확인
+  - AC-2 (구) portfolios.tag_ids GIN 인덱스 확인
+  - AC-3 (구) portfolio archived 표시 동작
+  - AC-4 (구) portfolio 빈 배열 기본값
+- Added (신 assets.tag_ids 범위):
+  - AC-1 assets 테이블에 `tag_ids UUID[] NOT NULL DEFAULT '{}'` 컬럼 존재
+  - AC-2 `idx_assets_tag_ids_gin` GIN 인덱스 존재
+  - AC-3 asset archived 태그 표시 동작
+  - AC-4 asset 빈 배열 기본값
+
+#### Impacted Area Delta
+- Docs:
+  - Removed: docs/data-model.md (portfolios.tag_ids — REQ-003 영역)
+  - Added: docs/data-model.md (assets 스키마에 tag_ids 컬럼 추가)
+- Modules:
+  - Removed: app/domain/models.py Portfolio 필드 / portfolios 배열 archived 로직 / AssetItem(v1) 스키마 — 전부 REQ-003 영역으로 이관
+  - Added:
+    - migrations/versions/ — assets.tag_ids 컬럼 + `idx_assets_tag_ids_gin` 추가 신규 Alembic revision
+    - app/domain/models.py — Asset 도메인 모델에 tag_ids 필드
+    - app/repositories/postgres.py — assets 조회 시 archived 표시 로직
+    - app/schemas/v1.py — admin asset catalog 응답 스키마에 tag_ids 필드
+- Tests:
+  - Removed: portfolios 컬럼 검증 (REQ-003 영역)
+  - Added: assets.tag_ids 스키마·GIN 인덱스·archived 표시 검증
+
+#### Delivery Trace Delta
+- Batches:
+  - Invalidated for REQ-002 scope: BAT-003 (구 portfolios.tag_ids 범위 검증 — 신규 assets.tag_ids 범위에 대한 evidence 없음). BAT-003 verification 자체는 REQ-001/REQ-003/REQ-006 측면에서 유효.
+  - 신규 batch 편입 필요: assets.tag_ids 마이그레이션 + 도메인/리포지터리/스키마 반영 (TBD).
+- Releases:
+  - REL-001: 구 REQ-002 trace는 portfolios.tag_ids 변경(REQ-003에서 실질 커버)으로 reroute. 신규 assets.tag_ids 변경분은 후속 release 대상.
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: yes — assets.tag_ids 컬럼/인덱스/도메인/스키마 모두 미구현. BAT-003 verification은 portfolios.tag_ids만 커버.
+- Status Recommendation: revert-to-approved
+- Follow-up Action: 신규 batch에서 assets.tag_ids 도입(마이그레이션 + 도메인 모델 + 리포지터리 + 스키마 + 테스트). REQ-009 Impacted Area에 본 REQ cross-reference 추가.
+
+#### Validation Plan
+- Alembic 마이그레이션 적용 후 SQLAlchemy Inspector로 assets.tag_ids 컬럼 및 `idx_assets_tag_ids_gin` 존재 확인.
+- pytest로 archived 표시 동작 및 빈 배열 기본값 검증.
+
 ### CHG-20260521-01
 - Date: 2026-05-21
 - Author: Justin Ko

docs/srs/Data/req-009_assets-table-schema.md

@@ -34,15 +34,54 @@
   - `app/repositories/postgres.py` — asset CRUD Postgres 구현 추가
 - Tests:
   - `tests/test_asset_catalog.py` (신규) — schema 존재 확인, UNIQUE constraint, GIN 인덱스, MarketCode Enum 검증
+- Cross-reference:
+  - REQ-002 — assets.tag_ids UUID[] 컬럼은 본 REQ의 후속 augmentation으로 별도 마이그레이션에서 추가된다 (dcy-002 FR-2 영역).
 
 ## Notes
 - REQ-010(admin CRUD), REQ-011(portfolios 재설계), REQ-013(GET /v1/assets), REQ-014(migration) 모두 이 REQ 선행 구현을 필요로 한다.
 - NFR-2(성능): `assets JOIN portfolios` 쿼리 성능은 이 REQ의 GIN 인덱스와 REQ-011의 FK 인덱스로 커버한다. 구체적인 응답 시간 목표는 batch design 단계에서 정의한다.
 - `assets` 테이블은 Alembic으로만 관리한다(ensure_schema() 대상 아님). runtime-flows.md Alembic/ensure_schema 경계 규칙 준수.
+- assets 카탈로그에 대한 태깅(`assets.tag_ids UUID[]`)은 본 REQ의 직접 범위가 아니며 REQ-002가 별도로 다룬다.
 - Source: dcy-001 FR-1
 
 ## Change Log
 
+### CHG-20260521-02
+- Date: 2026-05-21
+- Author: Justin Ko
+
+#### Change Summary
+- Impacted Area cross-reference 추가: REQ-002(assets.tag_ids UUID[] 컬럼) 후속 augmentation 명시
+- Notes 보강: 카탈로그 태깅은 본 REQ 범위 밖이며 REQ-002 영역임을 명시
+
+#### Intent
+- REQ-002 본문 재정의(portfolios.tag_ids → assets.tag_ids) 후속으로, 본 REQ(assets 스키마 도입)와 REQ-002(assets.tag_ids 추가) 사이 trace를 명시한다.
+- 향후 dcy-002 FR-2 구현 시 본 REQ 산출물(assets 테이블)이 선행 의존임을 문서 트레이스로 남긴다.
+
+#### Acceptance Criteria Delta
+- No change
+
+#### Impacted Area Delta
+- Added:
+  - Cross-reference: REQ-002 (assets.tag_ids UUID[] 컬럼 후속 augmentation)
+- Notes:
+  - 카탈로그 태깅(assets.tag_ids)이 본 REQ 직접 범위가 아님을 명시
+
+#### Delivery Trace Delta
+- Batches:
+  - No change (BAT-001 verification 영향 없음)
+- Releases:
+  - No change (REL-001 trace 영향 없음)
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no — 본 REQ의 컬럼·인덱스·도메인 모델 정의는 그대로 유효
+- Status Recommendation: keep-current (Implemented)
+- Follow-up Action: REQ-002 후속 batch 편입 시 본 REQ를 선행 dependency로 표기
+
+#### Validation Plan
+- 문서 cross-reference 변경이므로 추가 코드/DB 검증 불요
+
 ### CHG-20260521-01
 - Date: 2026-05-21
 - Author: Justin Ko