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: /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 기준으로 맞춤
4. 작업 전후 검증은 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 기준으로 수행
6. 검증 완료 후 공개용에 코드 승격

다음 액션

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

실행 절차

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

• sync_prod_db_to_dev.sh

사용 방법:

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 상태를 유지해야 하면 별도 백업 후 실행한다