hyunho/MH-DashBoard-organization
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MH-DashBoard-organization/docs/DEV_PROD_DB_PROTOCOL.md
hyunho 4b4ffafbd2 docs: persist isolated 8081 startup workflow
2026-03-31 17:47:39 +09:00

7.4 KiB
Raw Permalink Blame History

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 기준으로 수행

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 그룹 테이블은 수동 기억에 의존하지 않고 다시 수행 가능해야 한다
  • 이후 모든 작업은 이 문서를 기본 프로토콜로 따른다

실행 절차

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

사용 방법:

./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/사업관리대장/
    • 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 상태를 유지해야 하면 별도 백업 후 실행한다
Reference in New Issue View Git Blame Copy Permalink