# BAT-007 Implementation

- Status: completed
- Batch: BAT-007

## Plan Summary

- REQ-002: `app/repositories/postgres.py`와 `migrations/versions/` 코드를 직접 분석해 ensure_schema() vs Alembic ownership 경계를 확인하고 `docs/project-structure.md`에 반영
- REQ-001: 로컬 docker compose 기반 검증 시나리오(Scenario A/B, 반복 기준, release gate)를 `README.md`와 `docs/runtime-flows.md`에 반영
- REQ-003: README runbook + docs/project-structure.md, docs/runtime-flows.md baseline 갱신

코드 변경 없음. 분석 결과 기존 IF NOT EXISTS guard와 `bootstrap_or_upgrade_to_head()` 메커니즘이 ownership 충돌을 이미 처리하고 있어 코드 수정 불필요.

## Changed Files

| 파일 | 변경 내용 | REQ |
|------|-----------|-----|
| `README.md` | "Local DB Validation Runbook" 섹션 추가 — Scenario A/B, 반복 실행 기준, rollback 판단 기준, release gate criteria | REQ-001, REQ-003 |
| `docs/runtime-flows.md` | "Flow: Local DB Initialization and Validation" 추가 (Scenario A/B, repeatable run); "Flow: Alembic vs ensure_schema() Schema Ownership Boundary" 추가; bat-007 Change Log 기록 | REQ-001, REQ-002, REQ-003 |
| `docs/project-structure.md` | "Schema Ownership Boundary" 섹션 추가 (소유 경계 표, 허용 순서, 운영 제약, legacy 범위 제외); bat-007 Change Log 기록 | REQ-002, REQ-003 |

## Analysis Results (REQ-002)

### ensure_schema() 전용 객체 (Alembic에 없음)
- `idx_auth_tokens_service_name_unique` (partial unique index, WHERE token_type='service')

### Alembic 전용 객체 (ensure_schema()에 없음)
- `portfolios.market` (revision 0014)
- `auth_tokens.runtime_id` + `idx_auth_tokens_runtime_id_unique` (revision 0014)
- `broker_credentials` table (revision 0014)
- `ledger_trades` table (revision 0014)

### 공유 객체 (양쪽 모두 관리)
- users, auth_tokens, strategy_sets, portfolios, portfolio_ledger, portfolio_comments, portfolio_tags + 대부분의 인덱스
- 모두 IF NOT EXISTS 또는 inspector guard로 보호됨

### 충돌 해결 메커니즘 확인
- `bootstrap_or_upgrade_to_head()` (app/db/migrations.py): alembic_version 테이블 여부 → legacy 테이블 여부로 stamp 분기. 코드 확인 완료.
- Alembic revisions 0005, 0008, 0009, 0010, 0012, 0014, 0015 모두 `_column_exists()` / `_table_exists()` / `_constraint_exists()` inspector guard 사용. 확인 완료.

## Execution Log

1. `app/repositories/postgres.py` ensure_schema() 전체 분석 완료 — 생성 객체 18종 목록화
2. `migrations/versions/` 15개 revision 분석 완료 — 소유 경계 분류
3. `bootstrap_or_upgrade_to_head()` 로직 확인 — legacy stamp 경로 정상 동작 확인
4. `docker-compose.local-test.yml` 확인 — 검증 시나리오 실행 환경 충족 (TimescaleDB healthcheck 설정 완비)
5. `app/cli/commands/health.py` 확인 — init-db/migrate-db/health-check 출력 필드 고정 확인
6. README.md, docs/runtime-flows.md, docs/project-structure.md 갱신 완료

## Validation

코드 변경 없음 → pytest 재실행 불필요. 문서 변경 only.

```
# 문서 변경 범위 확인
git diff --name-only
# 기대: README.md, docs/runtime-flows.md, docs/project-structure.md,
#       docs/batches/bat-007_.../design.md, planning.md, implementation.md
```

## Remaining Risks

- Scenario B (ensure_schema() 선행) 흐름은 실제 로컬 환경에서 수동 검증이 필요하다. 이 batch는 코드 분석 + 문서화 기반 evidence이며 실제 DB 기반 실행 검증은 release 전 수행 권장.
- `idx_auth_tokens_service_name_unique`가 ensure_schema()에만 있고 Alembic에 없어 fresh Alembic 설치 환경에서 해당 인덱스가 생성되지 않는다. 기능 영향: service token name unique 보장 불완전. 후속 batch 검토 필요.