Add multi-office seat maps and dev/prod DB sync protocol

docs/DEV_PROD_DB_PROTOCOL.md

@@ -0,0 +1,182 @@
+# Dev / Prod DB Protocol
+
+## 목적
+
+- `8081` 작업용은 기능 개발과 화면 검증을 먼저 수행하는 환경이다.
+- `8080` 공개용은 실제 기준 데이터와 운영 화면을 제공하는 환경이다.
+- 코드와 데이터의 기준을 분리해서 관리하되, 데이터 정본은 항상 `8080` 공개용 DB로 유지한다.
+
+## 현재 구조
+
+### 코드 경로
+
+- 공개용 `8080`: `/home/hyunho/projects/mh-dashboard-organization`
+- 작업용 `8081`: `/tmp/mh-dashboard-organization-dev`
+
+### DB 볼륨
+
+- 공개용 `8080`: `mh-dashboard-organization_postgres_data`
+- 작업용 `8081`: `mh-dashboard-organization-dev_postgres_data`
+
+즉 현재는 코드도 분리, DB도 분리 상태다.
+
+## 정본 기준
+
+- 코드 선행 환경: `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` 기준으로 맞춤
+
+### 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. 검증 완료 후 공개용에 코드 승격
+
+## 다음 액션
+
+- `8081` DB를 `8080` 기준으로 맞추는 반복 가능한 동기화 절차를 만든다
+- 최소한 `A 그룹` 테이블은 수동 기억에 의존하지 않고 다시 수행 가능해야 한다
+- 이후 모든 작업은 이 문서를 기본 프로토콜로 따른다
+
+## 실행 절차
+
+반복 가능한 동기화 스크립트:
+
+- [sync_prod_db_to_dev.sh](/home/hyunho/projects/mh-dashboard-organization/scripts/sync_prod_db_to_dev.sh)
+
+사용 방법:
+
+```bash
+chmod +x scripts/sync_prod_db_to_dev.sh
+./scripts/sync_prod_db_to_dev.sh minimal
+./scripts/sync_prod_db_to_dev.sh full
+```
+
+규칙:
+
+- `minimal`
+  - 조직도, 멤버, 자리배치도 검증 전 사용
+- `full`
+  - 분석 화면까지 공개용 기준 데이터로 맞춰야 할 때 사용
+
+주의:
+
+- 스크립트는 `8080` DB 데이터를 덤프해서 `8081` DB의 대상 테이블을 비우고 다시 적재한다
+- `8081`에서만 존재하던 대상 테이블 데이터는 사라진다
+- 따라서 실행 전 현재 작업용 DB 상태를 유지해야 하면 별도 백업 후 실행한다