MH-DashBoard-organization/docs/DEV_PROD_DB_PROTOCOL.md

# Dev / Prod DB Protocol

## 목적

- `8081` 작업용은 기능 개발과 화면 검증을 먼저 수행하는 환경이다.
- `8080` 공개용은 실제 기준 데이터와 운영 화면을 제공하는 환경이다.
- 코드와 데이터의 기준을 분리해서 관리하되, 데이터 정본은 항상 `8080` 공개용 DB로 유지한다.

## 현재 구조

### 코드 경로

- 공개용 `8080`: `/home/hyunho/projects/mh-dashboard-organization`
- 작업용 `8081`: `/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081`

### 작업용 Compose 기준

- 공개용 `8080` stack: `docker-compose.yml`
- 작업용 `8081` stack: `docker-compose.8081.yml`
- 작업용 project name 기본값: `mh-dashboard-organization-dev`
- 작업용 `8081`는 반드시 `/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081`에서 띄운다

### DB 볼륨

- 공개용 `8080`: `mh-dashboard-organization_postgres_data`
- 작업용 `8081`: `mh-dashboard-organization-dev_postgres_data`

즉 현재는 `8080` 과 `8081` 이 코드 workspace 와 DB volume 모두 분리된 상태로 운영한다.

## 정본 기준

- 코드 선행 환경: `8081`
- 데이터 정본: `8080`
- 공개 반영 기준: `8081`에서 검증 완료된 코드만 `8080`에 승격

중요:
- `8081` DB는 독립 정본이 아니다.
- `8081` DB는 `8080` DB를 기준으로 맞춘 검증용 복제본이어야 한다.

## 왜 이 규칙이 필요한가

- 조직현황, 조직도, 자리배치 인원, 퇴사자 제외, 멤버 수는 코드보다 DB 영향이 크다.
- 작업용 DB가 공개용과 달라지면 기능 검증 결과 자체가 왜곡된다.
- 원인 분석 시 `코드 차이`와 `DB 차이`를 분리할 수 있어야 한다.

## 현재 확인된 차이 예시

2026-03-27 확인 기준:

- `members`
  - `8080`: `227`
  - `8081`: `236`
- `member_retirements`
  - `8080`: `9`
  - `8081`: `0`
- `seat_maps`
  - `8080`: `21`
  - `8081`: `3`
- `seat_positions`
  - `8080`: `5`
  - `8081`: `0`
- `seat_slots`
  - `8080`: `57308`
  - `8081`: `370`

## 기준 테이블 분류

### A. 공개용 정본 기준으로 항상 맞춰야 하는 테이블

- `members`
- `member_aliases`
- `member_overrides`
- `member_retirements`
- `seat_maps`
- `seat_slots`
- `seat_positions`

### B. 원본 재적재로 다시 만들 수 있는 통합 테이블

- `integration_import_batches`
- `integration_raw_organization_rows`
- `integration_raw_mh_rows`
- `integration_raw_mh_pm_rows`
- `integration_raw_payment_rows`
- `integration_projects`
- `integration_project_aliases`
- `integration_project_category_mappings`
- `integration_project_pm_assignments`
- `integration_work_logs`
- `integration_work_log_segments`
- `integration_vouchers`

### C. 별도 정책이 필요한 영역

- `snapshots`
- 인증 관련 스키마와 테이블

## 작업 프로토콜

### 1. 작업 시작 전

1. `8080`과 `8081` 모두 기동 상태 확인
2. 이번 작업이 `코드 변경`인지 `데이터 변경`인지 먼저 구분
3. 공개용 기준 데이터가 필요한 화면이면 `8081` DB를 먼저 `8080` 기준으로 맞춤
4. 작업 전후 검증은 [REGRESSION_CHECKLIST.md](/home/hyunho/projects/mh-dashboard-organization/docs/REGRESSION_CHECKLIST.md) 기준으로 수행

### 2. 기능 개발 중

1. 코드 수정은 먼저 `8081`에서 수행
2. UI, 계산식, 자리배치도 동작은 `8081`에서 확인
3. 조직도/멤버/자리배치 검증은 공개용 기준 데이터가 반영된 `8081` DB에서만 수행

### 3. 검증 완료 후

1. 코드만 `8080`으로 승격
2. 데이터 반영이 필요한 기능은 별도 절차를 문서화한 뒤 적용
3. 공개용 DB를 개발 실험용으로 사용하지 않음

## 금지 사항

- `8081` DB를 장기간 독립 정본처럼 취급하지 않기
- 퇴사자, 멤버, 좌석 정보를 작업용에서 수작업으로만 유지하지 않기
- DB 차이를 무시하고 `8081` 검증 결과가 `8080`과 같다고 가정하지 않기

## 권장 동기화 범위

### 최소 범위

조직도/자리배치도 검증 전 반드시 동기화:

1. `members`
2. `member_aliases`
3. `member_overrides`
4. `member_retirements`
5. `seat_maps`
6. `seat_slots`
7. `seat_positions`

### 전체 범위

분석 화면까지 공개용 기준으로 검증해야 하면 아래도 포함:

1. `integration_import_batches`
2. `integration_raw_*`
3. `integration_projects`
4. `integration_project_*`
5. `integration_work_logs`
6. `integration_work_log_segments`
7. `integration_vouchers`

## 세션 시작 체크

1. 지금 작업이 `코드 변경`인지 `데이터 변경`인지 구분
2. 공개용 기준 데이터가 필요한지 판단
3. 필요하면 `8081` DB를 `8080` 기준으로 먼저 동기화
4. 그 뒤 기능 개발과 검증 수행
5. 검증은 [REGRESSION_CHECKLIST.md](/home/hyunho/projects/mh-dashboard-organization/docs/REGRESSION_CHECKLIST.md) 기준으로 수행
6. 검증 완료 후 공개용에 코드 승격

## 다음 액션

- `8081` DB를 `8080` 기준으로 맞추는 반복 가능한 동기화 절차를 만든다
- 최소한 `A 그룹` 테이블은 수동 기억에 의존하지 않고 다시 수행 가능해야 한다
- 이후 모든 작업은 이 문서를 기본 프로토콜로 따른다

## 실행 절차

반복 가능한 동기화 스크립트:

- [sync_prod_db_to_dev.sh](/home/hyunho/projects/mh-dashboard-organization/scripts/sync_prod_db_to_dev.sh)
- [docker-compose.8081.yml](/home/hyunho/projects/mh-dashboard-organization/docker-compose.8081.yml)

사용 방법:

```bash
./scripts/prepare_dev_worktree.sh
cd /home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081
docker compose -p mh-dashboard-organization-dev --env-file .env -f docker-compose.8081.yml up -d --build
./scripts/sync_prod_db_to_dev.sh minimal
./scripts/sync_prod_db_to_dev.sh full
```

`prepare_dev_worktree.sh`가 같이 처리하는 것:

- 메인 workspace를 `.dev-worktree-8081`로 복제 또는 재사용
- `.env` 복사
- 로컬 전용 디자인 참고 자산 복사
  - `incoming-files/sample style.css`
  - `incoming-files/260320.html`
  - `incoming-files/reference/ledger/`
  - `incoming-files/1.png`
  - `incoming-files/seat/center_chair_people_map(2).html`

중요:

- `8081`은 현재 메인 workspace를 직접 마운트하면 안 된다
- 컨테이너가 `/home/hyunho/projects/mh-dashboard-organization/...`를 물고 있으면 분리 상태가 깨진 것이다
- 정상 상태는 `docker inspect mh-dashboard-organization-dev-backend-1` 기준 마운트 소스가 `/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/...`로 나와야 한다

규칙:

- `minimal`
  - 조직도, 멤버, 자리배치도 검증 전 사용
- `full`
  - 분석 화면까지 공개용 기준 데이터로 맞춰야 할 때 사용

주의:

- 스크립트는 동기화 전에 `8081`의 `proxy`, `frontend`, `backend` 를 잠시 멈춘다
- 이유는 중간 상태를 읽는 API 요청과 DB truncate/restore 가 충돌하면 deadlock 또는 부분 검증이 발생할 수 있기 때문이다
- 스크립트는 `8080` DB 데이터를 덤프해서 `8081` DB의 대상 테이블을 비우고 다시 적재한다
- `8081`에서만 존재하던 대상 테이블 데이터는 사라진다
- `seat_positions` 는 portable CSV 경로로 별도 복원한다
- 복원 후 `members.seat_label`, `auth.users`, history backfill 을 다시 맞춘다
- 실행 후 주요 테이블 수량과 seat 정합성 수치를 출력한다
- 따라서 실행 전 현재 작업용 DB 상태를 유지해야 하면 별도 백업 후 실행한다