33 lines
3.4 KiB
Markdown
33 lines
3.4 KiB
Markdown
# BAT-015 Design
|
|
|
|
- Status: confirmed
|
|
- Batch: BAT-015
|
|
|
|
## Architecture Summary
|
|
- REL-001 잔여 정합화 3건을 단일 batch로 묶어 처리한다. DB schema 마이그레이션 1건(REQ-033), Pydantic 스키마 강화 1건(REQ-034), Health 응답 + baseline 문서 갱신 1건(REQ-035). 변경 면적은 좁지만 cross-cutting nature(데이터 + 인증 + 운영)로 한 batch에 응집된다.
|
|
|
|
## Changed Areas
|
|
- 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` 응답 확장
|
|
|
|
## Key Decisions
|
|
1. **REQ-033 마이그레이션 전략**: 단일 `ALTER TABLE ledger_trades RENAME COLUMN asset_id TO portfolio_id` 트랜잭션 사용. 별도 컬럼 추가 + backfill + drop 패턴은 채택하지 않음(데이터 의미가 이미 portfolio_id로 일관되어 backfill 불요, dcy-005 A-1 가정 + 사용자 confirm).
|
|
2. **REQ-034 enforcement 위치**: `LoginRequest.model_config = ConfigDict(extra="forbid")` 스키마 단계에서 처리. `AuthService.login`에 별도 검증 로직 추가 안 함(스키마 단계에서 Pydantic 표준 422 응답이 더 명확).
|
|
3. **REQ-035 db_enabled 의미**: `settings.db_enabled`(환경변수) 값 노출. actual DB ping은 본 batch 범위 밖이며 `docs/runtime-flows.md`에 의미 명문화로 해소.
|
|
4. **baseline 갱신 위치**: `docs/runtime-flows.md`의 "Health Probe Flow"(또는 유사 섹션)에 `db_enabled` 의미 노트 1단락 추가. `docs/project-structure.md`는 영향 없음.
|
|
5. **마이그레이션 revision 번호**: 기존 head(`20260521_0023`) 다음으로 `20260601_NNNN_ledger_trades_portfolio_id_rename.py`. revision 본문은 `op.execute("ALTER TABLE ... RENAME COLUMN ...")` 또는 `op.alter_column(...)` 패턴.
|
|
|
|
## Edge Cases
|
|
- 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) 명시.
|
|
|
|
## Architecture Impact
|
|
- runtime-flows
|
|
|
|
## Reference Doc Update Plan
|
|
- 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단락 추가
|