# 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`에 등록해야 한다.

```sql
-- 예시: 결재 템플릿 관리 메뉴 등록
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. 절대 하지 말 것

1. 페이지 파일만 만들고 메뉴 등록 안 하기 (미완성!)
2. fetch() 직접 사용 (lib/api/ 클라이언트 필수)
3. company_code 필터링 빠뜨리기
4. 하드코딩 색상/URL/사용자ID 사용
5. Card 안에 Card 중첩 (중첩 박스 금지)
6. 백엔드 재실행하기 (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개+ 파일에 적용할 때:
  1. **task-1 (파일럿)**: 대표 1개 파일에 시범 적용
  2. **PM 확인**: 사용자 피드백 수집 (파이프라인 중단 후)
  3. **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곳 등록:
  1. `frontend/app/(main)/admin/{기능명}/page.tsx` 파일 생성 (wrapper)
  2. `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 상태 요약