Files

권혁성 542ba40fa3 docs: [data-sync] 마스터 데이터 동기화 계획 추가 + 전체 동기화 문서 업데이트

- master-data-sync-plan.md 신규: 31개 마스터 테이블, 양방향(local↔dev↔prod)
- local-to-dev-data-sync-plan.md 업데이트: 35→62개 테이블 확장, FK 의존성 전수 분석
- kd_price_tables 삭제 반영 (미사용 레거시)

2026-03-18 14:53:17 +09:00

13 KiB

Raw Blame History

마스터 데이터 동기화 스크립트 계획

작성일: 2026-03-17 목적: 기초 데이터(마스터)를 환경 간 동기화하여 운영 초기 셋업 및 환경 복제 지원 기준 문서: docs/dev/dev_plans/local-to-dev-data-sync-plan.md (전체 동기화 v1) 상태: ⏳ 설계 확정 대기 대상: 31개 테이블 (Direct 27 + FK 4), DB만

📍 현재 진행 상태

항목	내용
마지막 완료 작업	테이블 분류 및 설계 검토
다음 작업	사용자 검토 → 스크립트 구현
진행률	0/3 (0%)
마지막 업데이트	2026-03-17

1. 개요

1.1 배경

SAM 시스템은 다음 환경을 사용한다:

환경	DB명	접근 방식	역할
로컬 (Docker)	`samdb`	`docker exec sam-mysql-1`	개발/테스트
개발 서버	`sam`	SSH `hskwon@114.203.209.83`	스테이징
운영 서버	`sam_prod`	SSH `sam-prod`	정식 서비스

문제: 스키마는 php artisan migrate로 올라가지만, 기초 데이터 없으면 시스템이 동작 안 함. 품목 893개, 단가 780개, 공정 4개, 문서양식 28개 등 마스터 데이터가 있어야 견적/수주/생산 기능이 작동한다.

기존 스크립트와의 관계:

스크립트	용도	대상
`scripts/data-sync.sh` (v1)	전체 동기화 — 개발 테스트용	62개 테이블 + 파일
`scripts/data-sync-master.sh` (v2, 신규)	기초정보만 — 환경 초기화/운영 셋업	31개 테이블, DB만

1.2 핵심 설계 원칙

┌─────────────────────────────────────────────────────────────────┐
│  🎯 설계 원칙                                                    │
├─────────────────────────────────────────────────────────────────┤
│  1. 양방향: 로컬→개발, 개발→운영 모두 지원                       │
│  2. 멱등성: 여러 번 실행해도 같은 결과 (DELETE → INSERT)          │
│  3. 테넌트 독립: tenant_id 파라미터화 (하드코딩 금지)             │
│  4. 마스터만: 트랜잭션/행위 데이터 절대 포함 금지                  │
│  5. DB만: 파일 동기화 없음 (R2 사용)                              │
│  6. 안전: 운영 대상 시 이중 확인 필수                              │
└─────────────────────────────────────────────────────────────────┘

1.3 변경 승인 정책

분류	예시	승인
✅ 즉시 가능	테이블 추가/제거, 옵션 추가	불필요
⚠️ 컨펌 필요	운영 대상 실행, DELETE 로직 변경	필수
🔴 금지	트랜잭션 테이블 포함, 운영 DB 직접 수정	별도 협의

2. 대상 테이블 (31개)

2.1 분류 기준

✅ 포함: 시스템 동작에 필수인 설정/마스터 데이터
❌ 제외: 사용자 행위로 생성되는 트랜잭션 데이터

2.2 포함 테이블 (Direct 27개 + FK 4개)

#	카테고리	테이블	유형	설명
	기준 정보
1	카테고리	categories	direct	품목 분류 체계
2	품목	items	direct	품목 마스터
3	부서	departments	direct	조직 구조
4	거래처	clients	direct	거래처 마스터
5	거래처 그룹	client_groups	direct	거래처 분류
6	공통 코드	common_codes	direct	시스템 코드
7	계정 코드	account_codes	direct	회계 계정
8	카테고리 그룹	category_groups	direct	카테고리 분류
9	직위	positions	direct	직위 마스터 (대리, 과장 등)
10	테넌트 설정	tenant_settings	direct	테넌트 기본 설정값
	품목 하위
11	품목 필드	item_fields	direct	동적 필드 정의
12	품목 섹션	item_sections	direct	필드 그룹
13	품목 페이지	item_pages	direct	섹션 그룹
14	BOM 구성	item_bom_items	direct	BOM 마스터
15	단가	prices	direct	품목 단가
16	엔티티 관계	entity_relationships	direct	page→section→field 매핑
17	품목 상세	item_details	FK	item_id → items. 단가 조회 핵심 (EstimatePriceService)
	공정
18	공정	processes	direct	공정 마스터
19	공정 단계	process_steps	FK	process_id → processes
20	분류 규칙	process_classification_rules	FK	process_id → processes
21	공정-품목 매핑	process_items	FK	process_id → processes. 품목별 공정 배정
	설정/양식
22	문서 양식	document_templates	direct	검사/작업일지 양식
23	체크리스트 템플릿	checklist_templates	direct	QMS 템플릿
24	근무 설정	work_settings	direct	근무시간/요일
25	채번 규칙	numbering_rules	direct	번호 생성 패턴
26	폴더 구조	folders	direct	문서 폴더
27	파일	files	direct	품목 이미지, 양식 첨부 등 설정 파일
	심사 체계
28	심사 체크리스트	audit_checklists	direct
29	심사 카테고리	audit_checklist_categories	direct
30	심사 항목	audit_checklist_items	direct
31	심사 표준문서	audit_standard_documents	direct

2.3 제외 테이블 (트랜잭션/행위 데이터)

카테고리	제외 테이블	사유
견적	quotes, quote_items, quote_revisions	견적 행위
수주	orders, order_items, order_nodes, order_histories, order_item_components	수주 행위
생산	work_orders, work_order_items, work_order_step_progress, work_order_assignees, work_order_material_inputs, work_order_issues, work_order_bending_details, work_results	생산 행위
출하	shipments, shipment_items, shipment_vehicle_dispatches	출하 행위
재고	stocks, stock_lots, stock_transactions, receivings	재고 행위
품질	inspections, quality_documents, quality_document_orders, quality_document_locations, performance_reports	검사 행위
문서	documents, document_data, document_approvals, document_attachments	문서 행위
매출	sales	매출 행위
사용자	users, user_tenants, tenant_user_profiles	환경에 이미 존재 전제 (운영자/테스트 계정)
메뉴	menus, permission_overrides	동기화 시 권한 설정 초기화 위험 (CLAUDE.md 규칙)
채번	numbering_sequences	환경별 독립 (UPSERT 자동 생성)
감사	audit_logs	환경별 독립

3. 스크립트 설계

3.1 사용법

# 기본 (로컬 → 개발)
./scripts/data-sync-master.sh

# 명시적 방향
./scripts/data-sync-master.sh --source local --target dev
./scripts/data-sync-master.sh --source dev --target prod

# 테넌트 지정 (기본: 287)
./scripts/data-sync-master.sh --source dev --target prod --tenant 123

# 미리보기
./scripts/data-sync-master.sh --source dev --target prod --dry-run

# 확인 생략 (CI/CD용)
./scripts/data-sync-master.sh --source local --target dev --yes

3.2 환경 설정

환경	식별자	DB 접근	.env 위치
로컬	`local`	`docker exec sam-mysql-1 mysql ...`	`api/.env`
개발	`dev`	`ssh sam-dev "mysql ..."`	`/home/webservice/api/.env`
운영	`prod`	`ssh sam-prod "mysql ..."`	`/home/webservice/api/.env`

DB 접속 정보는 각 환경의 api/.env에서 자동 읽기 (하드코딩 금지)
운영 대상 시 --prod-confirm 자동 요구 (이중 확인)

3.3 실행 흐름

1. 옵션 파싱 (source, target, tenant_id, dry-run)
2. 환경 검증
   ├── source 접속 확인 + .env에서 DB 정보 읽기
   └── target 접속 확인 + .env에서 DB 정보 읽기
3. 운영 안전 검증 (target=prod 시)
   ├── "--prod-confirm" 플래그 확인
   ├── 대상 테넌트 존재 여부 확인
   └── "정말 운영 DB에 반영하시겠습니까?" 2차 확인
4. source DB 덤프
   ├── Direct 테이블 (WHERE tenant_id=?)
   └── FK 테이블 (부모 ID 경유)
5. target DB 기존 데이터 DELETE (WHERE tenant_id=?)
6. 덤프 전송 + 임포트
7. 검증 (건수 비교: source vs target)
8. 완료 리포트

3.4 안전장치

장치	설명
`FOREIGN_KEY_CHECKS = 0`	DELETE/INSERT 시 FK 제약 임시 해제
`tenant_id 필터`	모든 DELETE에 WHERE tenant_id = ? → 다른 테넌트 보호
`--complete-insert`	ID 값 포함 → auto_increment 충돌 방지
`--prod-confirm`	운영 대상 시 이중 확인
`--dry-run`	실제 실행 없이 대상 확인
`--no-create-info`	데이터만 동기화, 스키마 변경 없음

3.5 운영 배포 시나리오

┌─────────────────────────────────────────────────────────────────┐
│  🚀 운영 배포 절차                                               │
├─────────────────────────────────────────────────────────────────┤
│  1. 개발서버에서 마스터 데이터 최종 검증                          │
│  2. 운영서버에 마이그레이션 실행 (스키마)                         │
│     ssh sam-prod "cd /home/webservice/api && php artisan migrate --force" │
│  3. 마스터 데이터 투입                                           │
│     ./scripts/data-sync-master.sh --source dev --target prod     │
│  4. 운영서버에서 데이터 확인                                     │
│  5. 앱 동작 확인                                                 │
└─────────────────────────────────────────────────────────────────┘

4. 작업 단계

Phase 1: 스크립트 구현

#	작업 항목	상태	비고
1.1	`scripts/data-sync-master.sh` 작성	⏳	옵션 파싱, 환경 자동 감지
1.2	source/target별 DB 접근 함수	⏳	local=docker, dev/prod=ssh
1.3	덤프/DELETE/임포트 로직	⏳	31개 테이블
1.4	운영 안전장치	⏳	--prod-confirm, 이중 확인
1.5	검증 및 리포트	⏳	건수 비교 출력

Phase 2: 테스트

#	작업 항목	상태	비고
2.1	`--dry-run` 테스트	⏳	모든 방향
2.2	로컬 → 개발 실행 테스트	⏳
2.3	개발 → 운영 시뮬레이션	⏳	dry-run으로

Phase 3: 문서 정비

#	작업 항목	상태
3.1	기존 `local-to-dev-data-sync-plan.md`에서 분리 명시	⏳
3.2	`docs/INDEX.md`에 등록	⏳
3.3	운영 배포 매뉴얼에 연결	⏳

5. 기존 스크립트와의 관계

scripts/
├── data-sync.sh          # v1: 전체 동기화 (62개 테이블 + 파일)
│                         #     용도: 로컬→개발 테스트 데이터 복제
│                         #     방향: 로컬→개발 단방향
│
└── data-sync-master.sh   # v2: 마스터 데이터만 (31개 테이블, DB만)
                          #     용도: 환경 초기화, 운영 셋업
                          #     방향: 양방향 (local↔dev↔prod)

v1은 유지 — 개발 테스트 시 트랜잭션 데이터까지 필요한 경우 사용. v2가 운영 배포의 핵심 — 한번 셋팅하면 운영에 그대로 반영.

6. 향후 확장

항목	설명	우선순위
테이블 추가	새 마스터 테이블 발생 시	필요시
다중 테넌트	한 번에 여러 테넌트 동기화	낮음
롤백	동기화 전 자동 백업 + 복원 스크립트	중간
변경 감지	source/target 차이만 보여주는 diff 모드	낮음

7. 참고 문서

전체 동기화 계획: docs/dev/dev_plans/local-to-dev-data-sync-plan.md
서버 운영 매뉴얼: docs/dev/deploys/ops-manual/README.md
서버 접근 관리: docs/system/server-access-management.md
운영 배포 계획: docs/dev/dev_plans/production-deployment-plan.md
DB 구조: docs/system/database/README.md

변경 로그

날짜	작업	비고
2026-03-17	최초 작성	소스 코드 belongsTo 기준 FK 전수 분석, 27개 마스터 테이블 선정
2026-03-17	MCP 검토 반영	Sequential Thinking 검토: item_details(단가 조회 핵심), process_items(공정-품목 매핑), positions(직위), tenant_settings(테넌트 설정) 4개 추가 → 31개. menus 제외 사유 명시

13 KiB Raw Blame History