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

REQ-009: assets 테이블 스키마 도입

• Status: Implemented
• Type: Data
• Priority: High
• Owner: Justin Ko

Intent

• admin이 거래 가능한 종목을 중앙 관리할 수 있도록 assets catalog 테이블을 신규 도입한다.
• 기존 portfolios 테이블에 혼합된 asset 정의(symbol, market)를 독립 엔티티로 분리하여 "자산"과 "포지션" 개념을 명확히 구분한다.

Requirement

• assets 테이블을 신규 생성한다: asset_id UUID PK, symbol TEXT NOT NULL UNIQUE, markets TEXT[] NOT NULL DEFAULT '{}', display_name TEXT, status TEXT NOT NULL DEFAULT 'active', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW().
• assets.markets 컬럼에 GIN 인덱스(idx_assets_markets_gin)를 생성한다.
• 시장 코드 허용 값을 Python Enum MarketCode(KRX, NXT, SOR, NASDAQ, NYSE, UPBIT, BITTHUMB)로 app/domain/models.py에 정의한다. API 수신 시 대문자 정규화 후 Enum 검증을 수행한다. DB CHECK constraint는 사용하지 않는다.
• app/domain/models.py에 Asset 도메인 모델(asset_id, symbol, markets, display_name, status, created_at, updated_at)을 추가한다.
• app/repositories/portfolio_repository.py Protocol에 asset CRUD 메서드(get_asset_by_id, get_asset_by_symbol, list_assets, insert_asset, update_asset)를 선언한다.
• app/repositories/postgres.py에 위 메서드의 Postgres 구현을 추가한다.

Acceptance Criteria

1. Given Alembic migration 적용 후, When assets 테이블 스키마를 확인, Then asset_id UUID PK, symbol TEXT NOT NULL UNIQUE, markets TEXT[] NOT NULL DEFAULT '{}', display_name TEXT, status TEXT NOT NULL DEFAULT 'active', created_at, updated_at 컬럼이 존재한다.
2. Given assets 테이블 존재, When 동일 symbol로 두 번 insert를 시도, Then UNIQUE constraint violation이 발생한다.
3. Given assets 테이블 존재, When 인덱스 목록을 확인, Then idx_assets_markets_gin GIN 인덱스가 존재한다.
4. Given MarketCode Enum 검증 로직, When 허용되지 않은 코드(예: 'UNKNOWN')를 전달, Then Enum 검증 오류가 반환된다.
5. Given MarketCode Enum 검증 로직, When 소문자 'krx'를 전달, Then 대문자 정규화 후 MarketCode.KRX로 검증이 통과한다.

Impacted Area

• Docs:
  • docs/data-model.md — assets 엔티티 추가 (REQ-015에서 처리)
• Modules:
  • migrations/versions/ — assets 테이블 생성 Alembic revision 신규 추가
  • app/domain/models.py — Asset 도메인 모델, MarketCode Enum 추가
  • app/repositories/portfolio_repository.py — asset CRUD Protocol 선언 추가
  • 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

Change Summary

• Status: Approved → Implemented

Intent

• BAT-001 confirm-batch-verification 완료. assets 테이블 스키마·GIN 인덱스·MarketCode Enum 검증 통과. DB-integration ACs는 실 DB 의존 — CI에서 migration 파일 구조 검증으로 대체, release 배포 시 최종 확인 예정.

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • BAT-001
• Releases:
  • REL-001

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: REL-001 배포 시 alembic upgrade 결과로 DB-integration AC 최종 확인

CHG-20260519-02

• Date: 2026-05-19
• Author: Justin Ko

Change Summary

• Status: Proposed → Approved

Intent

• 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC 구체성 확인 완료

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • none (미정)
• Releases:
  • none (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: promote-to-approved
• Follow-up Action: batch 계획 편입

CHG-20260519-01

• Date: 2026-05-19
• Author: Justin Ko

Change Summary

• 최초 생성 — dcy-001 confirm-discovery 후 draft-req 실행

Intent

• dcy-001 FR-1을 Data REQ로 분리; assets 테이블 스키마, 도메인 모델, MarketCode Enum 정의

Acceptance Criteria Delta

• Added:
  • AC-1~5 최초 작성

Impacted Area Delta

• Docs:
  • docs/data-model.md — 최초 지정
• Modules:
  • migrations/versions/, app/domain/models.py, app/repositories/portfolio_repository.py, app/repositories/postgres.py — 최초 지정
• Tests:
  • tests/test_asset_catalog.py — 최초 지정

Delivery Trace Delta

• Batches:
  • none (미정)
• Releases:
  • none (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 계획 편입

Validation Plan

• pytest로 AC-1~5 검증; DB 스키마 검사는 SQLAlchemy Inspector 또는 PostgreSQL psql로 확인