BAT-015 Design

Architecture Summary

REL-001 잔여 정합화 3건을 단일 batch로 묶어 처리한다. DB schema 마이그레이션 1건(REQ-033), Pydantic 스키마 강화 1건(REQ-034), Health 응답 + baseline 문서 갱신 1건(REQ-035). 변경 면적은 좁지만 cross-cutting nature(데이터 + 인증 + 운영)로 한 batch에 응집된다.

Docs: docs/data-model.md(ledger_trades 컬럼), docs/interface-contract.md(/health 응답), docs/runtime-flows.md(health probe 의미 명문화 — baseline 갱신)
Modules: app/repositories/postgres.py(ledger_trades SQL), app/domain/models.py(LedgerTrade dataclass, 있다면), app/api/v1_portfolios.py(ledger handler 응답 매핑, 있다면), app/schemas/auth.py(LoginRequest model_config), app/api/health.py(HealthResponse + handler), migrations/versions/(신규 revision)
Interfaces: POST /v1/portfolios/{id}/ledger/trades 응답 schema 일관성, POST /auth/login 422 거부 동작, GET /health 응답 확장

REQ-033 마이그레이션 전략: 단일 ALTER TABLE ledger_trades RENAME COLUMN asset_id TO portfolio_id 트랜잭션 사용. 별도 컬럼 추가 + backfill + drop 패턴은 채택하지 않음(데이터 의미가 이미 portfolio_id로 일관되어 backfill 불요, dcy-005 A-1 가정 + 사용자 confirm).
REQ-034 enforcement 위치: LoginRequest.model_config = ConfigDict(extra="forbid") 스키마 단계에서 처리. AuthService.login에 별도 검증 로직 추가 안 함(스키마 단계에서 Pydantic 표준 422 응답이 더 명확).
REQ-035 db_enabled 의미: settings.db_enabled(환경변수) 값 노출. actual DB ping은 본 batch 범위 밖이며 docs/runtime-flows.md에 의미 명문화로 해소.
baseline 갱신 위치: docs/runtime-flows.md의 "Health Probe Flow"(또는 유사 섹션)에 db_enabled 의미 노트 1단락 추가. docs/project-structure.md는 영향 없음.
마이그레이션 revision 번호: 기존 head(20260521_0023) 다음으로 20260601_NNNN_ledger_trades_portfolio_id_rename.py. revision 본문은 op.execute("ALTER TABLE ... RENAME COLUMN ...") 또는 op.alter_column(...) 패턴.

REQ-034: 기존 LoginRequest에 정의된 필드만 보내는 client는 영향 없음. username/password 외 어떤 키든 422로 거부됨.
REQ-035: PORTFOLIOHUB_DB_ENABLED 환경변수가 미설정(default false)인 경우 db_enabled: false 응답. 본 워크스페이스 .env는 true로 설정되어 있음.
REQ-033: ledger_trades에 데이터가 없는 환경(개발 초기)에서도 ALTER COLUMN RENAME은 즉시 완료. 대량 데이터 환경 staging은 dry-run에서 측정.
3건 통합: 동일 release에 묶일 예정이지만 각 변경이 서로 의존하지 않으므로 implementation 순서 자유. planning에서 권장 순서(REQ-034 → REQ-035 → REQ-033) 명시.

project-structure.md: none (구조 변경 없음, 기존 모듈에 한정된 변경)
runtime-flows.md: REQ-035에서 /health probe flow 섹션에 "db_enabled는 환경변수 PORTFOLIOHUB_DB_ENABLED 설정값 노출이며 actual DB connectivity ping이 아니다. production-grade readiness probe는 별도 /readiness endpoint 분리로 후속 처리"의 의미 명문화 노트 1단락 추가