kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
ERP-node/.cursor/agents/pipeline-common-rules.md

13 KiB
Raw Blame History

WACE ERP 파이프라인 공통 룰 (모든 에이전트 필수 준수)

!!!! STOP - 작업 시작 전 필수 게이트 (이것을 건너뛰면 모든 작업이 REJECT 된다) !!!!

PRE-CHECK GATE: 파일 생성/수정 전 반드시 확인

어떤 에이전트든 파일을 생성하거나 수정하기 전에 반드시 이 게이트를 통과해야 한다. 이 게이트를 건너뛰거나 무시한 작업은 전부 REJECT + ROLLBACK 대상이다.

GATE 1: 이 파일을 만들어도 되는가?

아래 경로에 .tsx 페이지 파일을 절대 생성하지 마라:

frontend/app/(main)/production/**    ← 금지! 사용자 메뉴!
frontend/app/(main)/warehouse/**     ← 금지! 사용자 메뉴!
frontend/app/(main)/quality/**       ← 금지! 사용자 메뉴!
frontend/app/(main)/logistics/**     ← 금지! 사용자 메뉴!
frontend/app/(main)/inventory/**     ← 금지! 사용자 메뉴!
frontend/app/(main)/purchase/**      ← 금지! 사용자 메뉴!
frontend/app/(main)/sales/**         ← 금지! 사용자 메뉴!
frontend/app/(main)/bom/**           ← 금지! 사용자 메뉴!
frontend/app/(main)/mold/**          ← 금지! 사용자 메뉴!
frontend/app/(main)/packaging/**     ← 금지! 사용자 메뉴!
frontend/app/(main)/document/**      ← 금지! 사용자 메뉴!
frontend/app/(main)/work/**          ← 금지! 사용자 메뉴!
frontend/app/(main)/order/**         ← 금지! 사용자 메뉴!
frontend/app/(main)/material/**      ← 금지! 사용자 메뉴!
frontend/app/(main)/equipment/**     ← 금지! 사용자 메뉴!
frontend/app/(main)/inspection/**    ← 금지! 사용자 메뉴!

유일하게 React 페이지(.tsx)를 만들 수 있는 경로:

frontend/app/(main)/admin/**         ← 허용! 관리자 메뉴만!

판단 로직 (의사코드):

IF 생성하려는 파일 경로가 "frontend/app/(main)/admin/" 하위가 아니다
  AND 파일이 page.tsx 또는 layout.tsx 또는 React 컴포넌트다
THEN
  !!!! 즉시 중단 !!!!
  → 이것은 사용자 메뉴다
  → React 페이지를 만들면 안 된다
  → DB 등록 방식(screen_definitions + screen_layouts_v2 + menu_info)으로 전환하라
  → pipeline-common-rules.md의 "사용자 메뉴 구현 방법" 섹션을 따르라
END IF

GATE 2: 사용자 메뉴인데 코드로 만들려고 하는가?

아래 키워드가 요구사항에 포함되어 있으면 사용자 메뉴일 가능성이 높다:

  • 포장, 적재, 금형, BOM, 입출고, 품질, 검사, 재고, 자재, 문서, 생산, 작업, 설비
  • "목록 + 상세" 구조, "좌측 테이블 + 우측 폼" 구조
  • 일반 업무 화면, CRUD 화면

사용자 메뉴라면:

  • .tsx 페이지 파일 생성 → 금지
  • screen_definitions + screen_layouts_v2 + menu_info INSERT → 올바른 방법
  • 백엔드 API(controller/routes)는 필요하면 코드로 작성 가능
  • 프론트엔드 API 클라이언트(lib/api/)도 필요하면 코드로 작성 가능
  • 하지만 프론트엔드 화면 UI 자체는 절대 코드로 만들지 않는다!

GATE 3: 관리자 메뉴가 맞는가?

관리자 메뉴는 다음 조건을 전부 만족해야 한다:

  • 시스템 관리자만 사용하는 기능 (사용자 관리, 권한 관리, 시스템 설정 등)
  • URL이 /admin/* 패턴
  • frontend/app/(main)/admin/ 하위에만 page.tsx 생성

이 3가지 게이트를 모두 통과한 후에만 작업을 시작하라.

1. 화면 유형 구분 (절대 규칙!)

이 시스템은 관리자 메뉴와 사용자 메뉴가 완전히 다른 방식으로 동작한다. 기능 구현 시 반드시 어느 유형인지 먼저 판단하라.

관리자 메뉴 (Admin)

  • 구현 방식: React 코드 기반 페이지 (.tsx 파일)
  • 경로: frontend/app/(main)/admin/{기능명}/page.tsx 이 경로만 허용!
  • 메뉴 등록: menu_info 테이블에 INSERT 필수 (코드만 만들고 메뉴 등록 안 하면 미완성!)
  • 대상: 시스템 설정, 사용자 관리, 결재 관리, 코드 관리 등
  • 특징: 하드코딩된 UI, 관리자만 접근

사용자 메뉴 (User/Screen) - 절대 하드코딩 금지!!!

  • 구현 방식: 로우코드 기반 (DB에 JSON으로 화면 구성 저장)
  • 데이터 저장: screen_layouts_v2 테이블에 V2 JSON 형식 보관
  • 화면 디자이너: 스크린 디자이너로 드래그앤드롭 구성
  • V2 컴포넌트: frontend/lib/registry/components/v2-* 디렉토리
  • 대상: 일반 업무 화면, BOM, 문서 관리, 포장/적재, 금형 관리 등
  • 특징: 코드 수정 없이 화면 구성 변경 가능
  • 절대 금지: React .tsx 페이지 파일로 직접 UI를 하드코딩하는 것!
  • 위반 시: 해당 작업 전체 REJECT + 파일 삭제 + 처음부터 DB 등록 방식으로 재작업

판단 기준

질문 관리자 메뉴 사용자 메뉴
누가 쓰나? 시스템 관리자 일반 사용자
화면 구조 고정? 고정 (코드) 유동적 (JSON)
URL 패턴 /admin/* /screen/{screen_code}
메뉴 등록 menu_info INSERT screen_definitions + menu_info INSERT
프론트엔드 코드 frontend/app/(main)/admin/ 하위에 page.tsx 작성 코드 작성 금지! DB에 스크린 정의만 등록

사용자 메뉴 구현 방법 (반드시 이 방식으로!)

절대 규칙: 사용자 메뉴는 React 페이지(.tsx)를 직접 만들지 않는다! 이미 /screen/[screenCode]/page.tsx → /screens/[screenId]/page.tsx 렌더링 시스템이 존재한다. 새 화면이 필요하면 DB에 등록만 하면 자동으로 렌더링된다.

Step 1: screen_definitions에 화면 등록

INSERT INTO screen_definitions (screen_name, screen_code, table_name, company_code, is_active)
VALUES ('포장/적재정보 관리', 'COMPANY_7_PKG', 'pkg_unit', 'COMPANY_7', 'Y')
RETURNING screen_id;
  • screen_code: {company_code}_{기능약어} 형식 (예: COMPANY_7_PKG)
  • table_name: 메인 테이블명 (V2 컴포넌트가 이 테이블 기준으로 동작)
  • company_code: 대상 회사 코드

Step 2: screen_layouts_v2에 V2 레이아웃 JSON 등록

INSERT INTO screen_layouts_v2 (screen_id, company_code, layer_id, layer_name, layout_data)
VALUES (
  {screen_id},
  'COMPANY_7',
  1,
  '기본 레이어',
  '{
    "version": "2.0",
    "components": [
      {
        "id": "comp_split_1",
        "url": "@/lib/registry/components/v2-split-panel-layout",
        "position": {"x": 0, "y": 0},
        "size": {"width": 1200, "height": 800},
        "displayOrder": 0,
        "overrides": {
          "leftTitle": "포장단위 목록",
          "rightTitle": "상세 정보",
          "splitRatio": 40,
          "leftTableName": "pkg_unit",
          "rightTableName": "pkg_unit",
          "tabs": [
            {"id": "basic", "label": "기본정보"},
            {"id": "items", "label": "매칭품목"}
          ]
        }
      }
    ]
  }'::jsonb
);
  • V2 컴포넌트 목록: v2-split-panel-layout, v2-table-list, v2-table-search-widget, v2-repeater, v2-button-primary, v2-tabs-widget 등
  • 상세 컴포넌트 가이드: .cursor/rules/component-development-guide.mdc 참조

Step 3: menu_info에 메뉴 등록

-- 먼저 부모 메뉴 objid 조회
-- SELECT objid, menu_name_kor FROM menu_info WHERE company_code = '{회사코드}' AND menu_name_kor LIKE '%물류%';

INSERT INTO menu_info (objid, menu_type, parent_obj_id, menu_name_kor, seq, menu_url, screen_code, company_code, status)
VALUES (
  (SELECT COALESCE(MAX(objid), 0) + 1 FROM menu_info),
  2,                          -- 2 = 메뉴 항목
  {부모_objid},               -- 상위 메뉴의 objid
  '포장/적재정보',
  10,                         -- 정렬 순서
  '/screen/COMPANY_7_PKG',   -- /screen/{screen_code} 형식 (절대!)
  'COMPANY_7_PKG',           -- screen_definitions.screen_code와 일치
  'COMPANY_7',
  'Y'
);

핵심: menu_url은 반드시 /screen/{screen_code} 형식이어야 한다! 프론트엔드가 이 URL을 받아 screen_definitions에서 screen_id를 찾고, screen_layouts_v2에서 레이아웃을 로드한다.

2. 관리자 메뉴 등록 (코드 구현 후 필수!)

관리자 기능을 코드로 만들었으면 반드시 menu_info에 등록해야 한다.

-- 예시: 결재 템플릿 관리 메뉴 등록
INSERT INTO menu_info (objid, menu_type, parent_obj_id, menu_name_kor, seq, menu_url, company_code, status)
VALUES (
  (SELECT COALESCE(MAX(objid), 0) + 1 FROM menu_info),
  2, {부모_objid}, '결재 템플릿', 40, '/admin/approvalTemplate', '대상회사코드', 'Y'
);
  • 기존 메뉴 구조를 먼저 조회해서 parent_obj_id, seq 등을 맞춰라
  • company_code 별로 등록이 필요할 수 있다
  • menu_auth_group 권한 매핑도 필요하면 추가

3. 하드코딩 금지 / 범용성 필수

  • 특정 회사에만 동작하는 코드 금지
  • 특정 사용자 ID에 의존하는 로직 금지
  • 매직 넘버 사용 금지 (상수 또는 설정 파일로 관리)
  • 하드코딩 색상 금지 (CSS 변수 사용: bg-primary, text-destructive 등)
  • 하드코딩 URL 금지 (환경 변수 또는 API 클라이언트 사용)

4. 테스트 환경 정보

  • 테스트 계정: userId=wace, password=qlalfqjsgh11
  • 역할: SUPER_ADMIN (company_code = "*")
  • 개발 프론트엔드: http://localhost:9771
  • 개발 백엔드 API: http://localhost:8080
  • 개발 DB: postgresql://postgres:ph0909!!@39.117.244.52:11132/plm

5. 기능 구현 완성 체크리스트

기능 하나를 "완성"이라고 말하려면 아래를 전부 충족해야 한다:

공통

  • DB: 마이그레이션 작성 + 실행 완료
  • DB: company_code 컬럼 + 인덱스 존재
  • BE: API 엔드포인트 구현 + 라우트 등록 (app.ts에 import + use 추가!)
  • BE: company_code 필터링 적용
  • 빌드 통과: 백엔드 tsc + 프론트엔드 tsc

관리자 메뉴인 경우

  • FE: frontend/app/(main)/admin/{기능}/page.tsx 작성
  • FE: API 클라이언트 함수 작성 (lib/api/)
  • DB: menu_info INSERT (menu_url = /admin/{기능})

사용자 메뉴인 경우 (코드 작성 금지!)

  • DB: screen_definitions INSERT (screen_code, table_name, company_code)
  • DB: screen_layouts_v2 INSERT (V2 레이아웃 JSON)
  • DB: menu_info INSERT (menu_url = /screen/{screen_code})
  • BE: 필요한 경우 전용 API 작성 (범용 table-management API로 커버 안 되는 경우만)
  • FE: .tsx 페이지 파일 만들지 않음 (이미 /screens/[screenId]/page.tsx가 렌더링)

6. 절대 하지 말 것 (위반 시 전체 작업 REJECT)

  1. 페이지 파일만 만들고 메뉴 등록 안 하기 (미완성!)
  2. fetch() 직접 사용 (lib/api/ 클라이언트 필수)
  3. company_code 필터링 빠뜨리기
  4. 하드코딩 색상/URL/사용자ID 사용
  5. Card 안에 Card 중첩 (중첩 박스 금지)
  6. 백엔드 재실행하기 (nodemon이 자동 재시작)
  7. [최우선 금지] 사용자 메뉴를 React 하드코딩(.tsx)으로 만들기
    • frontend/app/(main)/ 하위에서 /admin/ 이외의 경로에 page.tsx를 만드는 것은 절대 금지
    • 구체적 금지 경로: production/, warehouse/, quality/, logistics/, inventory/, purchase/, sales/, bom/, mold/, packaging/, document/, work/, order/, material/, equipment/, inspection/ 및 기타 모든 비-admin 경로
    • 사용자 메뉴는 반드시 screen_definitions + screen_layouts_v2 + menu_info DB 등록 방식으로 구현
    • 이미 /screen/[screenCode] → /screens/[screenId] 렌더링 시스템이 존재함
    • 백엔드 API(controller/routes)와 프론트엔드 API 클라이언트(lib/api/)는 필요하면 코드로 작성 가능
    • 하지만 프론트엔드 화면 UI 자체는 DB의 V2 레이아웃 JSON으로만 구성
    • 위반 발견 시: 해당 라운드 전체 FAIL 처리, 생성된 파일 즉시 삭제, DB 등록 방식으로 처음부터 재작업

7. 위반 사례 및 올바른 대응

위반 사례 (실제 발생한 문제)

# 이런 파일을 만들면 절대 안 된다!
frontend/app/(main)/production/packaging/page.tsx     ← REJECT!
frontend/app/(main)/warehouse/inventory/page.tsx      ← REJECT!
frontend/app/(main)/quality/inspection/page.tsx       ← REJECT!
frontend/app/(main)/mold/management/page.tsx          ← REJECT!

올바른 대응

-- 1. screen_definitions에 등록
INSERT INTO screen_definitions (screen_name, screen_code, table_name, company_code, is_active)
VALUES ('포장관리', 'COMPANY_7_PKG', 'pkg_unit', 'COMPANY_7', 'Y');

-- 2. screen_layouts_v2에 V2 레이아웃 JSON 등록
INSERT INTO screen_layouts_v2 (screen_id, company_code, layer_id, layer_name, layout_data)
VALUES ({screen_id}, 'COMPANY_7', 1, '기본 레이어', '{...V2 JSON...}'::jsonb);

-- 3. menu_info에 메뉴 등록
INSERT INTO menu_info (..., menu_url, screen_code, ...)
VALUES (..., '/screen/COMPANY_7_PKG', 'COMPANY_7_PKG', ...);

React 페이지(.tsx) 파일은 단 한 줄도 만들지 않는다. DB INSERT만으로 화면이 완성된다.