# req-001: 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의

- Status: Approved
- Type: Testing
- Priority: High
- Owner: repository-maintainers

## Intent
- 이 요구사항은 로컬 docker compose 기반 PostgreSQL 또는 TimescaleDB 환경에서 init-db, migrate-db, health-check, 최소 smoke flow를 반복 가능하게 검증하기 위한 기준선을 정의한다.
- 운영자와 유지보수 담당자가 같은 명령 순서와 같은 증거 형식으로 DB 준비 결과를 비교할 수 있도록 검증 절차를 명시하는 것이 목표다.

## Requirement
- 프로젝트는 로컬 docker compose 기반 DB 환경에 대해 fresh DB 시나리오와 app runtime이 일부 schema를 먼저 만든 시나리오를 포함한 검증 매트릭스를 정의해야 하며, init-db, migrate-db, health-check, 최소 인증 또는 portfolio smoke flow의 실행 순서, 기대 결과, 실패 조건, 증거 수집 방식을 함께 제공해야 한다.

## Acceptance Criteria
1. Given 로컬 docker compose 기반 DB와 필요한 환경 변수가 준비되어 있을 때, When 운영자가 init-db, health-check, 최소 인증 또는 portfolio smoke flow를 실행하면, Then 명령 순서, 기대 출력, pass or fail 기준, 남겨야 할 로그가 문서로 정의되어 있어야 한다.
2. Given fresh DB와 app runtime이 일부 schema를 먼저 만든 DB 시나리오가 있을 때, When 운영자가 migrate-db를 실행하면, Then 각 시나리오별 기대 결과와 실패 조건, 확인해야 할 증거가 구분되어 문서화되어 있어야 한다.
3. Given 동일한 로컬 검증 절차를 반복 실행할 때, When 운영자가 같은 명령 세트를 다시 실행하면, Then 결과 비교가 가능하도록 출력 형식과 로그 수집 위치가 일관되게 정의되어 있어야 한다.

## Impacted Area
- Docs: README.md, docs/runtime-flows.md, docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md
- Modules: docker-compose.local-test.yml, app/cli/commands/health.py, app/db/migrations.py
- Tests: 로컬 docker compose 기반 수동 검증 체크리스트 또는 동등한 smoke validation 절차

## Notes
- 이 요구사항은 dcy-001의 FR-1, NFR-1, NFR-2, S-1을 주로 구현 가능한 backlog로 정규화한 것이다.
- shared dev DB, staging, production-like 환경 검증은 이번 요구사항 범위에 포함하지 않는다.
- 성공 지표의 세부 artifact 형식은 REQ 승인 또는 batch planning 단계에서 확정할 수 있다.

## Change Log

### CHG-20260430-02
- Date: 2026-04-30
- Author: GitHub Copilot

#### Change Summary
- confirm-req 승인 게이트를 통과해 이 REQ를 Approved로 전환했다.

#### Intent
- dcy-001의 delivery input으로 사용할 수 있는 확정 requirement로 승격하기 위해 상태를 변경했다.

#### Acceptance Criteria Delta
- Added:
  - none
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - docs/srs/index.md
- Modules:
  - none
- Tests:
  - none

#### Delivery Trace Delta
- Batches:
  - none
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: approved
- Follow-up Action: suggest-batch-reqs 또는 draft-batch 단계에서 REQ-001의 검증 절차를 delivery scope로 연결한다.

#### Validation Plan
- REQ 본문 필수 섹션, Acceptance Criteria 구체성, docs/srs/index.md 상태 동기화를 확인한다.

### CHG-20260430-01
- Date: 2026-04-30
- Author: GitHub Copilot

#### Change Summary
- dcy-001에서 로컬 DB 검증 시나리오 요구사항을 신규 Proposed REQ로 생성했다.

#### Intent
- 로컬 DB 준비와 smoke validation 절차를 독립 구현 및 독립 검증 가능한 Testing 단위로 분리하기 위해 생성했다.

#### Acceptance Criteria Delta
- Added:
  - 로컬 docker compose 기반 init-db, health-check, smoke flow의 검증 기준 정의
  - fresh DB와 runtime-precreated schema 시나리오별 migrate-db 검증 기준 정의
  - 반복 실행 가능한 증거 수집 형식 정의
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - README.md
  - docs/runtime-flows.md
  - docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md
- Modules:
  - docker-compose.local-test.yml
  - app/cli/commands/health.py
  - app/db/migrations.py
- Tests:
  - 로컬 DB 수동 검증 체크리스트 또는 동등한 smoke validation 절차

#### 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 단계에서 검증 매트릭스 초안의 범위와 증거 형식을 승인한다.

#### Validation Plan
- confirm-req 전까지 Acceptance Criteria가 dcy-001의 FR-1 및 S-1과 일치하는지 검토하고, 이후 batch 단계에서 실제 검증 절차와 로그 수집 artifact를 작성한다.