trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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>
This commit is contained in:
genichin
2026-05-21 23:37:08 +09:00
co-authored by Claude Opus 4.7
parent d01039e98f
commit 9038f41010
19 changed files with 867 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/srs/Data/req-002_assets-tag-ids-column.md
+106 -13
View File
@@ -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
+39
View File
@@ -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
docs/srs/Interface/req-010_admin-asset-catalog-crud.md
+35 -1
View File
@@ -1,6 +1,6 @@
# REQ-010: admin asset catalog CRUD
- Status: Approved
- Status: Implemented
- Type: Interface
- Priority: High
- Owner: Justin Ko
@@ -60,6 +60,40 @@
## Change Log
### CHG-20260521-03
- Date: 2026-05-21
- Author: Justin Ko
#### Change Summary
- Status: Approved → Implemented (CHG-20260521-02 augmentation으로 신설된 AC-9~12가 BAT-012 verification에서 evidence 확보)
#### Intent
- BAT-012 confirm-batch-verification 완료. GET /v1/assets admin catalog 재정의(AC-9~12) 신규 evidence + 기존 AC-1~8 회귀 통과 모두 확인.
#### Acceptance Criteria Delta
- No change
#### Impacted Area Delta
- No change
#### Delivery Trace Delta
- Batches:
- BAT-012 (release-candidate) — primary trace, AC-1~12 전체 evidence
- BAT-002 (release-candidate) — augmentation superseded by BAT-012. BAT-002 본래 trace인 REQ-012/REQ-015는 영향 없음.
- Releases:
- REL-001 — CHG-20260521-02 augmentation scope는 BAT-012로 이관됨. REL-001 release 본문은 BAT-012 inclusion 정리 시 별도 갱신 필요.
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: REL-001 release 문서에 BAT-012 trace 반영 (또는 신규 REL에 BAT-012 포함)
#### Validation Plan
- tests/test_asset_catalog.py AC-9~12 신규 8건: test_get_v1_assets_admin_returns_catalog_response, test_get_v1_assets_status_filter_*, test_get_v1_assets_market_filter, test_get_v1_assets_user_token_returns_403, test_get_v1_assets_service_token_returns_403
- 기존 AC-1~8 회귀 9건: test_asset_cli_create_success / list / update / deactivate / test_asset_http_create_returns_201 / update_returns_200 / deactivate_returns_200 / non_admin_403
- 전체 회귀: 362 passed in 13.06s
### CHG-20260521-02
- Date: 2026-05-21
- Author: Justin Ko
docs/srs/index.md
+3 -3
View File
@@ -90,7 +90,7 @@
| REQ-007 | pfhub tag CLI 명령어 | Interface | Implemented | Medium | Justin Ko | [req-007](./Interface/req-007_pfhub-tag-cli.md) |
| REQ-008 | 태그 모델 도입 baseline 문서 갱신 | Documentation | Implemented | Low | Justin Ko | [req-008](./Documentation/req-008_tag-baseline-docs-update.md) |
| REQ-009 | assets 테이블 스키마 도입 | Data | Implemented | High | Justin Ko | [req-009](./Data/req-009_assets-table-schema.md) |
| REQ-010 | admin asset catalog CRUD | Interface | Approved | High | Justin Ko | [req-010](./Interface/req-010_admin-asset-catalog-crud.md) |
| REQ-010 | admin asset catalog CRUD | Interface | Implemented | High | Justin Ko | [req-010](./Interface/req-010_admin-asset-catalog-crud.md) |
| REQ-011 | portfolios asset_id FK 추가 및 symbol/market 제거 | Data | Implemented | High | Justin Ko | [req-011](./Data/req-011_portfolios-asset-id-fk-and-column-removal.md) |
| REQ-012 | portfolio 생성 CLI catalog 검증 | Interface | Implemented | High | Justin Ko | [req-012](./Interface/req-012_portfolio-create-catalog-validation.md) |
| REQ-013 | GET /v1/assets 토큰 타입별 분기 재정의 | Interface | Deprecated | High | Justin Ko | [req-013](./Interface/req-013_get-v1-assets-token-branching.md) |
@@ -116,8 +116,8 @@
## Recent Change Log Summary
- 2026-05-21: REQ-002 / REQ-010 Approved → Implemented (CHG-20260521-03 각각) — BAT-012 confirm-batch-verification 완료. 362 PASSED (32 신규: REQ-002 AC-1~4 8건 + REQ-010 AC-9~12 9건 + AC-1~8 회귀 9건 + 단위 6건). assets.tag_ids 마이그레이션·도메인·repository·schema·GET 라우트 archived 합성 모두 evidence 확보. REQ-010 BAT-002 trace는 superseded by BAT-012로 표기.
- 2026-05-21: REQ-002 Implemented → Approved (CHG-20260521-02) — 파일명(`req-002_assets-tag-ids-column.md`)·dcy-002 FR-2와 본문 정합성 회복. 기존 본문(portfolios.tag_ids)은 dcy-001 분리 이전 portfolios==asset 시절 흔적으로 REQ-003과 중복이었음. 새 범위(assets.tag_ids + `idx_assets_tag_ids_gin`)는 미구현 — BAT-003 verification은 REQ-002 범위 무효화. REQ-009 Impacted Area에 cross-reference 추가(CHG-20260521-02, Implemented 유지). 신규 batch 편입 필요.
- 2026-05-21: REQ-010 Implemented → Approved (CHG-20260521-02) — REL-001 smoke 검증에서 GET /v1/assets가 dcy-001 시점 portfolio 조회 코드를 유지 중인 불일치 확인. dcy-003 옵션 B(REQ-013 Deprecation) 후속의 GET admin catalog 재정의를 본 REQ에 augmentation. AC-9~12 신설, app/api/v1_assets.py GET 라우트 재정의 + AssetCatalogListResponse 추가. BAT-002 verification 재실행 필요.
- 2026-05-21: REQ-001~018 (17건, REQ-013 제외) Approved → Implemented — BAT-001~006 confirm-req-implemented 일괄 전환. BAT-001(REQ-009/011/014), BAT-002(REQ-010/012/015), BAT-003(REQ-001/002/003/006), BAT-004(REQ-004/005), BAT-005(REQ-007/008), BAT-006(REQ-016/017/018). DB-integration ACs는 REL-001 배포 시 최종 확인 예정.
- 2026-05-21: REQ-030/031/032 Approved → Implemented — BAT-010 confirm-batch-verification 완료. 330/330 PASSED (32 신규 tests in test_v1_portfolios_tags_comments.py). GET /v1/portfolios/{id}/tags 신설; POST/DELETE tag disabled 409 + service/client 403 보강; comment CRUD 4종 신설; baseline 4종 갱신(interface-contract/runtime-flows/data-model/project-structure).
- 2026-05-21: REQ-025/026/027/028 Approved → Implemented — BAT-009 confirm-batch-verification 완료. 298 PASSED (0 failed). test_v1_portfolios_crud.py 22건(REQ-025/026/027), test_v1_portfolios_list.py 10건(REQ-028) 전 AC 통과.
- 2026-05-21: REQ-019/020/021/024 Approved → Implemented — BAT-008 confirm-batch-verification 완료. 모든 grep AC 통과, 사람 리뷰 완료. REQ-021 follow-up: session no_expiry 코드 enforcement 미구현 → 별도 처리. REQ-024 AC-5: staging dry-run은 release plan 단계로 이관.