ERP-node/docs/DDD1542/본서버_개발서버_마이그레이션_가이드.md

본서버 → 개발서버 마이그레이션 가이드 (공용)

이 문서는 다음 AI 에이전트가 마이그레이션 작업을 이어받을 때 참고하는 핵심 가이드입니다.

---

빠른 시작

마이그레이션 방향 (절대 잊지 말 것)

본서버 (Production)  →  개발서버 (Development)
211.115.91.141:11134     39.117.244.52:11132
screen_layouts (V1)      screen_layouts_v2 (V2)

반대로 하면 안 됨! 개발서버 완성 후 → 본서버로 배포 예정

DB 접속 정보

# 본서버 (Production)
docker exec pms-backend-mac node -e '
const { Pool } = require("pg");
const pool = new Pool({ 
  connectionString: "postgresql://postgres:vexplor0909!!@211.115.91.141:11134/plm?sslmode=disable", 
  ssl: false 
});
// 쿼리 실행
'

# 개발서버 (Development)
docker exec pms-backend-mac node -e '
const { Pool } = require("pg");
const pool = new Pool({ 
  connectionString: "postgresql://postgres:ph0909!!@39.117.244.52:11132/plm?sslmode=disable", 
  ssl: false 
});
// 쿼리 실행
'

---

핵심 개념

V1 vs V2 구조 차이

구분	V1 (본서버)	V2 (개발서버)
테이블	screen_layouts	screen_layouts_v2
레코드	컴포넌트별 1개	화면당 1개
설정 저장	properties JSONB	layout_data.components[].overrides
채번/카테고리	menu_objid 기반	table_name + column_name 기반
컴포넌트 참조	component_type 문자열	url 경로 (@/lib/registry/...)

데이터 타입 관리 (V2)

table_type_columns (input_type)
├── 'category' → category_values 테이블
├── 'numbering' → numbering_rules 테이블 (detail_settings.numberingRuleId)
├── 'entity' → 엔티티 검색
└── 'text', 'number', 'date', etc.

컴포넌트 URL 매핑

const V1_TO_V2_MAPPING = {
  'table-list': '@/lib/registry/components/v2-table-list',
  'button-primary': '@/lib/registry/components/v2-button-primary',
  'text-input': '@/lib/registry/components/v2-text-input',
  'select-basic': '@/lib/registry/components/v2-select',
  'date-input': '@/lib/registry/components/v2-date-input',
  'entity-search-input': '@/lib/registry/components/v2-entity-search',
  'category-manager': '@/lib/registry/components/v2-category-manager',
  'numbering-rule': '@/lib/registry/components/v2-numbering-rule',
  'tabs-widget': '@/lib/registry/components/v2-tabs-widget',
  'textarea-basic': '@/lib/registry/components/v2-textarea',
};

모달 처리 방식 변경

• V1: 별도 화면(screen_id)으로 모달 관리
• V2: 부모 화면에 overlay/dialog 컴포넌트로 통합

---

마이그레이션 대상 메뉴 현황

품질관리 (우선순위 1)

본서버 코드	화면명	상태	비고
COMPANY_7_126	검사정보 관리	✅ V2 존재	컴포넌트 검증 필요
COMPANY_7_127	품목옵션 설정	✅ V2 존재	v2-category-manager 사용중
COMPANY_7_138	카테고리 설정	❌ 누락	table_name 기반으로 변경
COMPANY_7_139	코드 설정	❌ 누락	table_name 기반으로 변경
COMPANY_7_142	검사장비 관리	❌ 누락	모달 통합 필요
COMPANY_7_143	검사장비 등록모달	❌ 누락	→ 142에 통합
COMPANY_7_144	불량기준 정보	❌ 누락	모달 통합 필요
COMPANY_7_145	불량기준 등록모달	❌ 누락	→ 144에 통합

다음 마이그레이션 대상 (미정)

• 물류관리
• 생산관리
• 영업관리
• 기타 메뉴들

---

마이그레이션 작업 절차

Step 1: 분석

-- 본서버 특정 메뉴 화면 목록 조회
SELECT 
  sd.screen_id, sd.screen_code, sd.screen_name, sd.table_name,
  COUNT(sl.layout_id) as component_count
FROM screen_definitions sd
LEFT JOIN screen_layouts sl ON sd.screen_id = sl.screen_id
WHERE sd.screen_name LIKE '%[메뉴명]%'
  AND sd.company_code = 'COMPANY_7'
GROUP BY sd.screen_id, sd.screen_code, sd.screen_name, sd.table_name;

-- 개발서버 V2 현황 확인
SELECT 
  sd.screen_id, sd.screen_code, sd.screen_name,
  sv2.layout_id IS NOT NULL as has_v2
FROM screen_definitions sd
LEFT JOIN screen_layouts_v2 sv2 ON sd.screen_id = sv2.screen_id
WHERE sd.company_code = 'COMPANY_7';

Step 2: screen_definitions 동기화

본서버에만 있는 화면을 개발서버에 추가

Step 3: V1 → V2 레이아웃 변환

// layout_data 구조
{
  "version": "2.0",
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/v2-table-list",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 100, "height": 50 },
      "displayOrder": 0,
      "overrides": {
        "tableName": "테이블명",
        "columns": ["컬럼1", "컬럼2"]
      }
    }
  ]
}

Step 4: 카테고리 데이터 확인/생성

-- 테이블의 category 컬럼 확인
SELECT column_name, column_label
FROM table_type_columns
WHERE table_name = '[테이블명]'
  AND input_type = 'category';

-- category_values 데이터 확인
SELECT value_id, value_code, value_label
FROM category_values
WHERE table_name = '[테이블명]'
  AND column_name = '[컬럼명]'
  AND company_code = 'COMPANY_7';

Step 5: 채번 규칙 확인/생성

-- numbering 컬럼 확인
SELECT column_name, column_label, detail_settings
FROM table_type_columns
WHERE table_name = '[테이블명]'
  AND input_type = 'numbering';

-- numbering_rules 데이터 확인
SELECT rule_id, rule_name, table_name, column_name
FROM numbering_rules
WHERE company_code = 'COMPANY_7';

Step 6: 검증

• 화면 렌더링 확인
• 컴포넌트 동작 확인
• 저장/수정/삭제 테스트
• 카테고리 드롭다운 동작
• 채번 규칙 동작

---

핵심 테이블 스키마

screen_layouts_v2

CREATE TABLE screen_layouts_v2 (
  layout_id SERIAL PRIMARY KEY,
  screen_id INTEGER NOT NULL,
  company_code VARCHAR(20) NOT NULL,
  layout_data JSONB NOT NULL DEFAULT '{}'::jsonb,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(screen_id, company_code)
);

category_values

-- 핵심 컬럼
value_id, table_name, column_name, value_code, value_label,
parent_value_id, depth, path, company_code

numbering_rules + numbering_rule_parts

-- numbering_rules 핵심 컬럼
rule_id, rule_name, table_name, column_name, separator,
reset_period, current_sequence, company_code

-- numbering_rule_parts 핵심 컬럼
rule_id, part_order, part_type, generation_method,
auto_config, manual_config, company_code

table_type_columns

-- 핵심 컬럼
table_name, column_name, input_type, column_label,
detail_settings, company_code

---

참고 문서

필수 읽기

1. 본서버_개발서버_마이그레이션_상세가이드.md - 상세 마이그레이션 절차
2. 화면개발_표준_가이드.md - V2 화면 개발 표준
3. SCREEN_DEVELOPMENT_STANDARD.md - 영문 표준 가이드

코드 참조

파일	설명
backend-node/src/services/categoryTreeService.ts	카테고리 관리 서비스
backend-node/src/services/numberingRuleService.ts	채번 규칙 서비스
frontend/lib/registry/components/v2-category-manager/	V2 카테고리 컴포넌트
frontend/lib/registry/components/v2-numbering-rule/	V2 채번 컴포넌트

관련 문서

• docs/V2_컴포넌트_분석_가이드.md
• docs/V2_컴포넌트_연동_가이드.md
• docs/DDD1542/COMPONENT_LAYOUT_V2_ARCHITECTURE.md
• docs/DDD1542/COMPONENT_MIGRATION_PLAN.md

---

주의사항

절대 하지 말 것

1. 개발서버 → 본서버 마이그레이션 (반대 방향)
2. 본서버 데이터 직접 수정 (SELECT만 허용)
3. company_code 누락 (멀티테넌시 필수)

반드시 할 것

1. 마이그레이션 전 개발서버 백업
2. 컴포넌트 변환 시 V2 컴포넌트만 사용 (v2- prefix)
3. 모달 화면은 부모 화면에 통합
4. 카테고리/채번은 table_name + column_name 기반

---

마이그레이션 진행 로그

날짜	메뉴	담당	상태	비고
2026-02-03	품질관리	DDD1542	분석 완료	마이그레이션 대기
	물류관리	-	미시작
	생산관리	-	미시작
	영업관리	-	미시작

---

다음 작업 요청 예시

다음 AI에게 요청할 때 이렇게 말하면 됩니다:

"본서버_개발서버_마이그레이션_가이드.md 읽고 품질관리 메뉴 마이그레이션 진행해줘"

"본서버_개발서버_마이그레이션_가이드.md 참고해서 물류관리 메뉴 분석해줘"

"본서버_개발서버_마이그레이션_상세가이드.md 보고 COMPANY_7_142 화면 V2로 변환해줘"

---

변경 이력

날짜	작성자	내용
2026-02-03	DDD1542	초안 작성