kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ERP-node/docs/DDD1542/본서버_개발서버_마이그레이션_가이드.md

14 KiB
Raw Blame History

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

이 문서는 다음 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 
});
// 쿼리 실행
'

절대 주의: 컴포넌트-컬럼 연결 (이전 실패 원인)

"component" vs "v2-input" 구분

❌ 잘못된 상태                    ✅ 올바른 상태
┌──────────────────┐              ┌──────────────────┐
│ component        │              │ v2-input         │
│ 업체코드         │              │ 업체코드         │
└──────────────────┘              └──────────────────┘
    ↑                                 ↑
    overrides.type 없음               overrides.type = "v2-input"

핵심 원인: 컴포넌트를 그냥 배치하면 "component"로 표시됨. 반드시 왼쪽 패널에서 테이블 컬럼을 드래그해야 올바른 v2-xxx 컴포넌트가 생성됨.

🔥 핵심 발견: overrides.type 필수 (2026-02-04 발견)

"component"로 표시되는 근본 원인:

항목 드래그로 배치 마이그레이션 (잘못된)
overrides.type "v2-input" ✅ 없음 ❌
overrides.webType "text" 등 없음
overrides.tableName "carrier_mng" 등 없음

프론트엔드가 컴포넌트 타입을 인식하는 방법:

  1. overrides.type 확인 → 있으면 해당 값 사용 (예: "v2-input")
  2. 없으면 → 기본값 "component"로 폴백

결론: 마이그레이션 시 overrides.type 필드를 반드시 설정해야 함!

input_type → V2 컴포넌트 자동 매핑

table_type_columns.input_type 드래그 시 생성되는 V2 컴포넌트
text v2-input
number v2-input (type=number)
date v2-date
category v2-select (category_values 연동)
numbering v2-numbering-rule 또는 v2-input
entity v2-entity-search

절대 규칙: 컴포넌트가 "component"로 표시되면 연결 실패 상태. 반드시 "v2-xxx"로 표시되어야 함.

핵심 개념

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 누락 (멀티테넌시 필수)
  4. 테이블-컬럼 연결 없이 컴포넌트 배치 ("component"로 표시되면 실패)
  5. menu_objid 기반 카테고리/채번 사용 (V2는 table_name + column_name 기반)

반드시 할 것

  1. 마이그레이션 전 개발서버 백업
  2. 컴포넌트 변환 시 V2 컴포넌트만 사용 (v2- prefix)
  3. 모달 화면은 부모 화면에 통합
  4. 카테고리/채번은 table_name + column_name 기반
  5. 컴포넌트 배치 후 "v2-xxx"로 표시되는지 반드시 확인

실패 사례 (이전 작업자)

물류정보관리 → 운송업체 관리 마이그레이션 실패

  • 원인: 컴포넌트를 직접 배치하여 "component"로 생성됨
  • 증상: 화면에 "component" 라벨 표시, 데이터 바인딩 실패
  • 해결: 왼쪽 패널에서 테이블 컬럼을 드래그하여 "v2-input" 등으로 생성

🔧 일괄 수정 SQL (overrides.type 누락 문제)

문제 진단 쿼리

-- overrides.type이 없는 컴포넌트 수 확인
SELECT 
  COUNT(DISTINCT sv2.screen_id) as affected_screens,
  COUNT(*) as affected_components
FROM screen_layouts_v2 sv2, 
     jsonb_array_elements(sv2.layout_data->'components') as comp
WHERE (comp->>'url' LIKE '%/v2-input' 
       OR comp->>'url' LIKE '%/v2-select' 
       OR comp->>'url' LIKE '%/v2-date')
  AND NOT (comp->'overrides' ? 'type');

일괄 수정 쿼리 (개발서버에서만!)

UPDATE screen_layouts_v2 
SET layout_data = jsonb_set(
  layout_data,
  '{components}',
  (
    SELECT jsonb_agg(
      CASE 
        WHEN comp->>'url' LIKE '%/v2-input' AND NOT (comp->'overrides' ? 'type')
        THEN jsonb_set(comp, '{overrides,type}', '"v2-input"')
        WHEN comp->>'url' LIKE '%/v2-select' AND NOT (comp->'overrides' ? 'type')
        THEN jsonb_set(comp, '{overrides,type}', '"v2-select"')
        WHEN comp->>'url' LIKE '%/v2-date' AND NOT (comp->'overrides' ? 'type')
        THEN jsonb_set(comp, '{overrides,type}', '"v2-date"')
        WHEN comp->>'url' LIKE '%/v2-textarea' AND NOT (comp->'overrides' ? 'type')
        THEN jsonb_set(comp, '{overrides,type}', '"v2-textarea"')
        ELSE comp
      END
    )
    FROM jsonb_array_elements(layout_data->'components') comp
  )
),
updated_at = NOW()
WHERE EXISTS (
  SELECT 1 FROM jsonb_array_elements(layout_data->'components') c
  WHERE (c->>'url' LIKE '%/v2-input' OR c->>'url' LIKE '%/v2-select' 
         OR c->>'url' LIKE '%/v2-date' OR c->>'url' LIKE '%/v2-textarea')
    AND NOT (c->'overrides' ? 'type')
);

2026-02-04 일괄 수정 실행 결과

항목 수량
수정된 화면 397개
수정된 컴포넌트 2,455개
v2-input 1,983개
v2-select 336개
v2-date 136개

마이그레이션 진행 로그

날짜 메뉴 담당 상태 비고
2026-02-03 품질관리 DDD1542 분석 완료 마이그레이션 대기
2026-02-03 물류관리 (운송업체) 이전 신하 ❌ 실패 component 연결 오류
2026-02-03 문서 학습 DDD1542 ✅ 완료 핵심 4개 문서 정독, 학습노트 작성
2026-02-04 overrides.type 원인 분석 AI ✅ 완료 핵심 원인 발견: overrides.type 누락
2026-02-04 전체 입력폼 일괄 수정 AI ✅ 완료 397개 화면, 2,455개 컴포넌트 수정
물류관리 - 미시작
생산관리 - 미시작
영업관리 - 미시작

다음 작업 요청 예시

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

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

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

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

변경 이력

날짜 작성자 내용
2026-02-03 DDD1542 초안 작성
2026-02-03 DDD1542 컴포넌트-컬럼 연결 주의사항 추가 (이전 실패 원인)
2026-02-03 DDD1542 개인 학습노트 작성 (V2_마이그레이션_학습노트_DDD1542.md)
2026-02-04 AI 핵심 원인 발견: overrides.type 필드 누락 문제
2026-02-04 AI 일괄 수정 SQL 추가 및 397개 화면 수정 완료