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

> **작성일**: 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 사용법

```bash
# 기본 (로컬 → 개발)
./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 제외 사유 명시 |