# BAT-007 Planning

- Status: confirmed
- Batch: BAT-007
- Profile: batch-lite

## Included REQ

- REQ-001: 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의
- REQ-002: Alembic와 runtime schema ownership 경계 정리
- REQ-003: 로컬 DB 운영 runbook 및 baseline 문서 갱신

## Out of Scope

- shared dev DB, staging, production-like 환경 검증 (REQ-001 Notes 참고)
- legacy DB 지원 및 legacy stamp 경로 검증 (REQ-002 Notes 참고)
- baseline 문서 전체 복제 또는 로컬 DB 검증과 무관한 구조 변경 (REQ-003 Notes 참고)
- trex-basic 연동 환경 검증 (이번 batch 범위 외)

## 구현 순서

### 1단계: 현황 파악 (REQ-002 선행)

- `app/repositories/postgres.py`의 `ensure_schema()` 메서드가 다루는 테이블/인덱스 목록 확인
- `migrations/versions/*.py` revision들이 다루는 객체 목록 확인
- 충돌 가능 지점 식별: 동일 객체를 두 경로가 모두 CREATE/ALTER하는 경우
- 허용 순서와 금지 순서, 사전 점검 규칙 초안 작성

### 2단계: 검증 시나리오 정의 (REQ-001)

- fresh DB 시나리오: DB 컨테이너 초기화 후 `init-db` → `migrate-db` → `health-check` → smoke flow 실행 순서와 기대 결과 정의
- runtime-precreated schema 시나리오: app 실행 후 `ensure_schema()` 적용 상태에서 `migrate-db` 실행 기대 결과 정의
- 각 시나리오별 pass/fail 기준, 남겨야 할 로그, 증거 수집 위치 명시
- 반복 실행 시 출력 형식 일관성 기준 정의

### 3단계: 문서 갱신 (REQ-003 + REQ-001, REQ-002 산출물 통합)

- `README.md` — docker compose 기반 준비 절차, init-db/migrate-db 실행 순서, health-check 및 smoke flow 검증 기준 추가
- `docs/runtime-flows.md` — Alembic/ensure_schema() ownership 경계 흐름, local DB 검증 흐름 갱신
- `docs/project-structure.md` — schema ownership 경계 및 local DB 운영 제약 반영
- rollback 또는 재시도 판단 기준과 검증 로그 수집 위치 runbook에 명시

### 4단계: 코드/설정 확인 및 필요 시 최소 수정

- `docker-compose.local-test.yml` — 검증 시나리오 실행 환경 점검 (변경 필요 시 최소 반영)
- `app/cli/commands/health.py` — health-check 출력 형식이 검증 기준과 일치하는지 확인
- `app/db/migrations.py` — IF NOT EXISTS 패턴 및 ownership 경계 준수 확인

## Dependencies

- Internal:
  - `app/repositories/postgres.py` — `ensure_schema()` ownership 분석 대상
  - `app/db/migrations.py` — migration 실행 entry point 확인
  - `migrations/versions/*.py` — Alembic revision 대상 객체 목록
  - `docker-compose.local-test.yml` — 로컬 검증 환경
- External: 없음

## Design Gate

- Design Required Before Implementation: no
- Reason: 신규 인터페이스, DB 스키마, 런타임 흐름 변경 없음. 기존 코드 분석 → 문서 작성 중심 batch. 구조적 결정 사항이 분석 과정에서 발견되면 planning을 갱신하고 필요 시 design.md를 추가한다.

## Milestones

1. REQ-002: Alembic vs ensure_schema() ownership 경계 분석 완료 + 문서 초안
2. REQ-001: 검증 시나리오 매트릭스 정의 완료
3. REQ-003: README, docs/runtime-flows.md, docs/project-structure.md 갱신 완료

## Risks

- `ensure_schema()`와 Alembic revision 간 실제 충돌 지점이 분석 후 발견되면 코드 수정이 필요해질 수 있음 — 이 경우 scope를 확대해 planning 갱신 후 진행
- `docker-compose.local-test.yml`이 현행 환경(PostgreSQL + TimescaleDB)과 맞지 않으면 수동 검증 절차 수정 필요