8.0 KiB
8.0 KiB
WACE ERP 파이프라인 공통 룰 (모든 에이전트 필수 준수)
1. 화면 유형 구분 (절대 규칙!)
이 시스템은 관리자 메뉴와 사용자 메뉴가 완전히 다른 방식으로 동작한다. 기능 구현 시 반드시 어느 유형인지 먼저 판단하라.
관리자 메뉴 (Admin)
- 구현 방식: React 코드 기반 페이지 (
.tsx파일) - 경로:
frontend/app/(main)/admin/{기능명}/page.tsx - 메뉴 등록:
menu_info테이블에 INSERT 필수 (코드만 만들고 메뉴 등록 안 하면 미완성!) - 대상: 시스템 설정, 사용자 관리, 결재 관리, 코드 관리 등
- 특징: 하드코딩된 UI, 관리자만 접근
사용자 메뉴 (User/Screen)
- 구현 방식: 로우코드 기반 (DB에 JSON으로 화면 구성 저장)
- 데이터 저장:
screen_layouts테이블에 JSON 형식 보관 - 화면 디자이너: 스크린 디자이너로 드래그앤드롭 구성
- V2 컴포넌트:
frontend/lib/registry/components/v2-*디렉토리 - 대상: 일반 업무 화면, BOM, 문서 관리 등
- 특징: 코드 수정 없이 화면 구성 변경 가능
판단 기준
| 질문 | 관리자 메뉴 | 사용자 메뉴 |
|---|---|---|
| 누가 쓰나? | 시스템 관리자 | 일반 사용자 |
| 화면 구조 고정? | 고정 (코드) | 유동적 (JSON) |
| URL 패턴 | /admin/* |
스크린 디자이너 경유 |
| 메뉴 등록 | menu_info INSERT 필수 |
스크린 레이아웃 등록 |
2. 관리자 메뉴 등록 (코드 구현 후 필수!)
관리자 기능을 코드로 만들었으면 반드시 menu_info에 등록해야 한다.
-- 예시: 결재 템플릿 관리 메뉴 등록
INSERT INTO menu_info (menu_id, menu_name, url, parent_id, menu_type, sort_order, is_active, company_code)
VALUES ('approvalTemplate', '결재 템플릿', '/admin/approvalTemplate', 'approval', 'ADMIN', 40, 'Y', '대상회사코드');
- 기존 메뉴 구조를 먼저 조회해서 parent_id, sort_order 등을 맞춰라
- 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 엔드포인트 구현 + 라우트 등록
- BE: company_code 필터링 적용
- FE: API 클라이언트 함수 작성 (lib/api/)
- FE: 화면 컴포넌트 구현
- 메뉴 등록: 관리자 메뉴면 menu_info INSERT, 사용자 메뉴면 스크린 레이아웃 등록
- 빌드 통과: 백엔드 tsc + 프론트엔드 tsc
6. 절대 하지 말 것
- 페이지 파일만 만들고 메뉴 등록 안 하기 (미완성!)
- fetch() 직접 사용 (lib/api/ 클라이언트 필수)
- company_code 필터링 빠뜨리기
- 하드코딩 색상/URL/사용자ID 사용
- Card 안에 Card 중첩 (중첩 박스 금지)
- 백엔드 재실행하기 (nodemon이 자동 재시작)
7. 파이프라인 태스크 설계 원칙
파일 스코프 규칙
- task의
files에 명시되지 않은 파일을 수정하면 라운드 종료 시 자동 롤백됨 - 크로스커팅 수정(SSR 호환, import 경로 변경 등)은 반드시 별도 task로 분리해야 함
- 한 task에 파일이 너무 많으면(3개+) 에이전트가 tool_call 처리 중 멈출 수 있음
대형 파일 규칙
- 1000줄 이상 파일: task당 최대 2개
- 2000줄 이상 파일: task당 1개만
- 파일 크기를 모르면
wc -l로 먼저 확인 후 task 분할 - 3개 대형 파일(1000줄+)을 한 task에 넣으면 hang 위험 매우 높음
파일럿 패턴 (새 UI 패턴 일괄 적용 시)
- 새로운 디자인 패턴을 10개+ 파일에 적용할 때:
- task-1 (파일럿): 대표 1개 파일에 시범 적용
- PM 확인: 사용자 피드백 수집 (파이프라인 중단 후)
- task-2~N (전파): 확인된 패턴을 나머지 파일에 적용
- 사용자 피드백 없이 일괄 적용하면 전부 롤백해야 할 위험이 있음
- 예시: max-h 스크롤 제한을 14개 파일에 일괄 적용 -> 사용자가 거부 -> 14개 파일 전부 원복 필요
hang 프로세스 대응
- 10분 이상 출력 없으면 hang으로 판단
kill <pid>로 프로세스 종료git diff --stat HEAD로 커밋된 변경 확인- 남은 task를 새 plan.md로 재작성하여 resume
- hang이 잦으면 task당 파일 수를 줄이거나 timeout을 늘릴 것
파이프라인으로 적합하지 않은 작업
- Props/데이터 플로우 디버깅 (교차 컴포넌트 의존 관계 추적)
- SSR 호환성 같은 크로스커팅 수정 (files scope 제한 때문)
- 사용자 확인 없이 디자인 패턴 일괄 전파 (거부 시 전체 롤백 위험)
- 이런 작업은 PM이 직접 처리하는 것이 10배 빠르고 안전함
8. 프로젝트 필수 패턴 (코드 생성 시 반드시 준수)
Backend 필수
- 라우트 등록: 새 라우트 파일 생성 시 반드시
backend-node/src/app.ts에 import +app.use()등록. 이거 안 하면 API 404. - 권한 체크:
req.user?.isAdmin쓰지 마라. 반드시import { isAdmin, isSuperAdmin } from "../utils/permissionUtils"의 함수를 사용. 예:if (!isAdmin(req.user)). - DB 쿼리:
import { getPool } from "../database/db"사용.const pool = getPool(req)패턴. - 멀티테넌시:
company_code필터 필수.companyCode === "*"이면 전체 조회 허용 (SUPER_ADMIN). - 에러 처리: try/catch +
logger.error()+res.status(500).json({ success: false, message: "..." }).
Frontend 필수
- 페이지 등록: 새 관리자 페이지 생성 시 반드시 2곳 등록:
frontend/app/(main)/admin/{기능명}/page.tsx파일 생성 (wrapper)frontend/components/layout/AdminPageRenderer.tsx의ADMIN_PAGE_REGISTRY에 추가 이거 안 하면 페이지 접근 불가.
- API 호출:
import { apiClient } from "@/lib/api/client"사용. fetch 직접 쓰지 마라. - 인증 훅:
import { useAuth } from "@/hooks/useAuth".const { isAdmin } = useAuth(). - UI 컴포넌트: shadcn/ui 기반 (
@/components/ui/*). 새 UI 라이브러리 설치 금지. - 목록 페이지:
ResponsiveDataView+Pagination컴포넌트 사용. - 아이콘:
lucide-react에서 import.
DB 필수
- 마이그레이션 파일:
db/migrations/YYMMDD_설명.sql형식. - 멱등성:
CREATE TABLE IF NOT EXISTS,ADD COLUMN IF NOT EXISTS사용. - company_code: 모든 비즈니스 테이블에
company_code VARCHAR(20) NOT NULL필수.
9. 설정 패널 디자인 규칙 (UI 작업 시 필수)
설정 패널(config panel) 관련 작업 시 반드시 _local/agent-pipeline/agents/ui-design-philosophy.mdc를 참조하라.
핵심 규칙 요약
- 참조 모델:
V2SelectConfigPanel.tsx(Gold Standard) - 섹션 헤더: Icon + Label + Badge 카운트
- 텍스트 오버플로우:
min-w-0 flex-1+truncate필수 - max-h 금지: 인라인 콘텐츠(CollapsibleContent, div)에 max-h/overflow-y-auto 절대 금지
- max-h 허용: CommandGroup, CommandList 등 드롭다운 팝업만
- Progressive Disclosure: 고급 설정은 Collapsible 기본 닫힘 + Badge 상태 요약