vexplor_dev/docs/coding-rules/erp-coding-rules-lowcode.md

# ERP 화면 로우코드 규칙 (Low-Code Mode)

이 문서는 **로우코드** 방식으로 화면을 개발/리디자인할 때 참조하는 규칙입니다.
DataGrid, DynamicSearchFilter 등 공통 컴포넌트를 활용하여 설정(config) 기반으로 빠르게 화면을 구성합니다.

> **적용 대상:** COMPANY_7(탑씰) 기존 화면, COMPANY_29, COMPANY_9 등 공통 컴포넌트 기반 화면
> **주의:** 이 모드는 기존 로우코드 화면 유지보수용. 신규 개발은 날코딩 규칙(`erp-coding-rules-rawcode.md`) 권장.

---

## 1. 프로젝트 정보

- **프로젝트:** erp-node (Next.js App Router + Node.js/Express + PostgreSQL)
- **프론트엔드:** /Users/gbpark/erp-node/frontend/
- **백엔드:** /Users/gbpark/erp-node/backend-node/
- **화면 경로:** frontend/app/(main)/{COMPANY}/{category}/{screen}/page.tsx
- **공통 컴포넌트:** frontend/components/common/

---

## 2. 사용 가능한 공통 컴포넌트

### 2-1. DataGrid (테이블)
- 파일: `@/components/common/DataGrid`
- 용도: 편집 가능한 데이터 테이블 (컬럼 정의만으로 테이블 렌더링)
- 기능: 정렬, 행 선택, 체크박스, 인라인 편집, 컬럼 리사이즈

```tsx
import { DataGrid, DataGridColumn } from "@/components/common/DataGrid";

const GRID_COLUMNS: DataGridColumn[] = [
  { key: "order_no", label: "수주번호", width: "w-[120px]", type: "text" },
  { key: "part_code", label: "품번", width: "w-[120px]", editable: true },
  { key: "qty", label: "수량", width: "w-[80px]", type: "number", align: "right" },
  { key: "status", label: "상태", width: "w-[100px]", type: "badge",
    badgeMap: { active: { label: "확정", variant: "default" }, draft: { label: "작성중", variant: "secondary" } }
  },
];

<DataGrid
  columns={gridColumns}
  data={data}
  selectedId={selectedId}
  checkedIds={checkedIds}
  onRowClick={handleRowClick}
  onCheckChange={handleCheckChange}
  onSave={handleSave}
  loading={loading}
  emptyMessage="데이터가 없어요"
/>
```

### 2-2. DynamicSearchFilter (검색 필터)
- 파일: `@/components/common/DynamicSearchFilter`
- 용도: 설정 기반 동적 검색 필터 UI 자동 생성
- 기능: 텍스트, 셀렉트, 날짜 범위, 콤보박스 필터 자동 렌더링

```tsx
import { DynamicSearchFilter, FilterValue } from "@/components/common/DynamicSearchFilter";

const FILTER_CONFIG = [
  { key: "order_no", label: "수주번호", type: "text" },
  { key: "status", label: "상태", type: "select", options: statusOptions },
  { key: "order_date", label: "수주일", type: "dateRange" },
  { key: "customer", label: "거래처", type: "combo", options: customerOptions },
];

<DynamicSearchFilter
  fields={FILTER_CONFIG}
  values={filterValues}
  onChange={setFilterValues}
  onSearch={handleSearch}
  onReset={handleReset}
/>
```

### 2-3. SmartSelect (검색 가능 셀렉트)
- 파일: `@/components/common/SmartSelect`
- 용도: 검색 + 선택 통합 드롭다운 (거래처, 품목 선택 등)

```tsx
import { SmartSelect } from "@/components/common/SmartSelect";

<SmartSelect
  value={selectedCode}
  onChange={setSelectedCode}
  options={customerOptions}
  placeholder="거래처를 선택해주세요"
  searchable
/>
```

### 2-4. FullscreenDialog (전체화면 다이얼로그)
- 파일: `@/components/common/FullscreenDialog`
- 용도: 등록/수정 시 전체화면 모달

```tsx
import { FullscreenDialog } from "@/components/common/FullscreenDialog";

<FullscreenDialog
  open={isModalOpen}
  onOpenChange={setIsModalOpen}
  title={isEditMode ? "수주 수정" : "수주 등록"}
>
  {/* 폼 내용 */}
</FullscreenDialog>
```

### 2-5. TableSettingsModal (테이블 설정)
- 파일: `@/components/common/TableSettingsModal`
- 용도: 컬럼 표시/숨김, 순서 변경, 너비 조정

```tsx
import { TableSettingsModal, loadTableSettings, saveTableSettings } from "@/components/common/TableSettingsModal";

<TableSettingsModal
  open={settingsOpen}
  onOpenChange={setSettingsOpen}
  columns={gridColumns}
  onSave={(newColumns) => { setGridColumns(newColumns); saveTableSettings(SETTINGS_KEY, newColumns); }}
  settingsKey={SETTINGS_KEY}
/>
```

### 2-6. FormDatePicker (날짜 선택)
- 파일: `@/components/common/FormDatePicker`
- 용도: 캘린더 UI 기반 날짜 입력

```tsx
import { FormDatePicker } from "@/components/common/FormDatePicker";

<FormDatePicker
  value={formData.order_date}
  onChange={(date) => setFormData(prev => ({ ...prev, order_date: date }))}
  placeholder="날짜를 선택해주세요"
/>
```

### 2-7. 기타 사용 가능 컴포넌트

```tsx
import { useConfirmDialog } from "@/components/common/ConfirmDialog";       // 확인 다이얼로그 훅
import { ExcelUploadModal } from "@/components/common/ExcelUploadModal";     // 엑셀 업로드
import { exportToExcel } from "@/lib/utils/excelExport";                     // 엑셀 다운로드 유틸
import { ShippingPlanBatchModal } from "@/components/common/ShippingPlanBatchModal"; // 출하계획 배치
import { TimelineScheduler } from "@/components/common/TimelineScheduler";   // 타임라인 스케줄러
import { EditableSpreadsheet } from "@/components/common/EditableSpreadsheet"; // 스프레드시트형 편집
```

---

## 3. 허용 import 패턴

### shadcn/ui 기본 (공통 컴포넌트와 혼용)
```tsx
"use client";

import React, { useState, useEffect, useCallback, useMemo } from "react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Badge } from "@/components/ui/badge";
import { Checkbox } from "@/components/ui/checkbox";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter, DialogDescription } from "@/components/ui/dialog";
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@/components/ui/resizable";
```

### 아이콘 (lucide-react만)
```tsx
import {
  Plus, Trash2, Save, Loader2, Search, X, Pencil,
  ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight,
  RotateCcw, Download, Upload, FileSpreadsheet, Settings2,
} from "lucide-react";
```

### 유틸
```tsx
import { cn } from "@/lib/utils";
import { apiClient } from "@/lib/api/client";
import { useAuth } from "@/hooks/useAuth";
import { toast } from "sonner";
import { exportToExcel } from "@/lib/utils/excelExport";
```

---

## 4. 디자인 규칙

### 4-1. 색상: CSS 변수만 사용 (하드코딩 절대 금지)
```
✅ 허용: bg-primary, text-muted-foreground, bg-muted, bg-destructive, border-border
❌ 금지: bg-gray-50, bg-white, text-black, text-gray-500, #3b82f6
```

### 4-2. 테마
- 라이트 모드 기본 + `.dark` 클래스로 다크 모드 자동 전환
- Primary: Vivid Blue (HSL 217 91% 60%)
- Dark 배경: Deep Navy (HSL 222 47% 6%)

### 4-3. 컴포넌트 규칙
- shadcn/ui + 공통 컴포넌트 조합 사용
- 아이콘: lucide-react만
- Card-in-Card 중첩 금지
- 인라인 콘텐츠에 `max-h` / `overflow-y-auto` 금지
- 새 UI 라이브러리 설치 금지

### 4-4. 텍스트 톤
- Toss 스타일 **~해요 체**
  - 빈 상태: "수주를 등록해주세요", "좌측에서 거래처를 선택해주세요"
  - 확인 다이얼로그: "삭제하시겠어요?"

### 4-5. 사이즈 표준
- 입력필드 높이: `h-9` (36px)
- 버튼 기본: `h-9`, 소형: `h-8` (`size="sm"`)
- 폰트: `text-sm` (14px) 기본, `text-xs` (12px) 보조

---

## 5. 화면 유형별 레이아웃

### Type A: 단일 테이블형
```
page-container(flex flex-col h-full gap-3 p-4)
  ├─ DynamicSearchFilter
  ├─ card(flex-1 flex flex-col border rounded-lg)
  │    ├─ panel-header (타이틀 + 건수 Badge + 액션 버튼)
  │    ├─ DataGrid (컬럼 정의로 자동 렌더링)
  │    └─ pagination
  └─ FullscreenDialog (등록/수정 모달)
```

### Type B: 마스터-디테일형 (좌우 분할)
```
page-container
  ├─ DynamicSearchFilter
  └─ ResizablePanelGroup(horizontal)
       ├─ ResizablePanel (좌측: DataGrid)
       ├─ ResizableHandle
       └─ ResizablePanel (우측: 상세 Tabs)
            ├─ 미선택: empty-state
            └─ 선택: Tabs (탭별 DataGrid 또는 상세 폼)
```

### Type C: 트리+디테일형
```
Type B + 우측에 트리뷰 + 상세카드
```

### Type D: 탭 멀티뷰형
```
page-container
  └─ card > Tabs
       └─ TabsContent × N (각각 DynamicSearchFilter + DataGrid)
```

### Type E: 카드 리스트형
```
Type B에서 좌측을 DataGrid 대신 카드 리스트로 구현
```

### Type F: 리포트형
```
ReportEngine에 config 전달 (선언적)
```

---

## 6. 공통 API 패턴

### 6-1. 범용 CRUD (table-management)

```tsx
// ★ 목록 조회 (POST)
const fetchData = async () => {
  setLoading(true);
  try {
    const filters: any[] = [];
    if (searchValue) {
      filters.push({ columnName: "column_name", operator: "contains", value: searchValue });
    }

    const res = await apiClient.post(`/table-management/tables/${TABLE_NAME}/data`, {
      page: currentPage,
      size: pageSize,
      dataFilter: filters.length > 0 ? { enabled: true, filters } : undefined,
      autoFilter: true,
      sort: { columnName: "created_date", order: "desc" },
    });

    const rows = res.data?.data?.data || res.data?.data?.rows || [];
    const total = res.data?.data?.totalCount || res.data?.data?.total || 0;
    setData(rows);
    setTotalCount(total);
  } catch (err) {
    toast.error("조회에 실패했어요");
  } finally {
    setLoading(false);
  }
};

// ★ 등록 (POST /add)
await apiClient.post(`/table-management/tables/${TABLE_NAME}/add`, {
  field1: value1,
  field2: value2,
});

// ★ 수정 (PUT /edit)
await apiClient.put(`/table-management/tables/${TABLE_NAME}/edit`, {
  originalData: { id: selectedId },
  updatedData: { field1: newValue1, field2: newValue2 },
});

// ★ 삭제 (DELETE /delete)
await apiClient.delete(`/table-management/tables/${TABLE_NAME}/delete`, {
  data: selectedIds.map(id => ({ id })),
});
```

### 6-2. 카테고리 옵션 로드
```tsx
const res = await apiClient.get(`/table-categories/${TABLE_NAME}/${COLUMN}/values`);

const flatten = (items: any[]): { code: string; label: string }[] => {
  return items.reduce((acc, item) => {
    acc.push({ code: item.code || item.value, label: item.label || item.name });
    if (item.children?.length > 0) acc.push(...flatten(item.children));
    return acc;
  }, [] as any[]);
};

const options = res.data?.data?.length > 0 ? flatten(res.data.data) : [];
```

### 6-3. 코드→라벨 변환
```tsx
const resolveLabel = (code: string, optionKey: string): string => {
  const opts = categoryOptions[optionKey] || [];
  return opts.find(o => o.code === code)?.label || code || "-";
};
```

### 6-4. 마스터-디테일 저장 패턴
```tsx
// 신규: 마스터 add → 디테일 각 행 add
// 수정: 마스터 edit → 기존 디테일 delete → 디테일 재 add
// 시스템 필드 제외: id, created_date, updated_date, writer, company_code, created_by, updated_by
```

---

## 7. 로우코드 페이지 기본 골격

```tsx
"use client";

import React, { useState, useEffect, useCallback } from "react";
import { Button } from "@/components/ui/button";
import { Badge } from "@/components/ui/badge";
import { DataGrid, DataGridColumn } from "@/components/common/DataGrid";
import { DynamicSearchFilter, FilterValue } from "@/components/common/DynamicSearchFilter";
import { FullscreenDialog } from "@/components/common/FullscreenDialog";
import { TableSettingsModal, loadTableSettings } from "@/components/common/TableSettingsModal";
import { SmartSelect } from "@/components/common/SmartSelect";
import { FormDatePicker } from "@/components/common/FormDatePicker";
import { useConfirmDialog } from "@/components/common/ConfirmDialog";
import { ExcelUploadModal } from "@/components/common/ExcelUploadModal";
import { exportToExcel } from "@/lib/utils/excelExport";
import { cn } from "@/lib/utils";
import { apiClient } from "@/lib/api/client";
import { useAuth } from "@/hooks/useAuth";
import { toast } from "sonner";
import { Plus, Trash2, Download, Upload, Settings2, Loader2 } from "lucide-react";

const TABLE_NAME = "your_table";
const SETTINGS_KEY = "table_settings_your_page";

const GRID_COLUMNS: DataGridColumn[] = [
  { key: "col1", label: "컬럼1", width: "w-[120px]" },
  { key: "col2", label: "컬럼2", width: "w-[100px]", type: "number" },
  { key: "status", label: "상태", width: "w-[100px]", type: "badge" },
];

const FILTER_CONFIG = [
  { key: "col1", label: "컬럼1", type: "text" },
  { key: "status", label: "상태", type: "select", options: [] },
];

export default function YourPage() {
  const { user } = useAuth();
  const { confirm, ConfirmDialogComponent } = useConfirmDialog();

  const [data, setData] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);
  const [totalCount, setTotalCount] = useState(0);
  const [filterValues, setFilterValues] = useState<FilterValue>({});
  const [gridColumns, setGridColumns] = useState<DataGridColumn[]>(GRID_COLUMNS);

  const [isModalOpen, setIsModalOpen] = useState(false);
  const [isEditMode, setIsEditMode] = useState(false);
  const [saving, setSaving] = useState(false);
  const [formData, setFormData] = useState<Record<string, any>>({});

  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [checkedIds, setCheckedIds] = useState<string[]>([]);
  const [settingsOpen, setSettingsOpen] = useState(false);

  const [categoryOptions, setCategoryOptions] = useState<Record<string, { code: string; label: string }[]>>({});

  const fetchData = useCallback(async () => { /* table-management API */ }, [filterValues]);
  const loadCategories = useCallback(async () => { /* 카테고리 로드 */ }, []);

  useEffect(() => { loadCategories(); }, [loadCategories]);
  useEffect(() => { fetchData(); }, [fetchData]);
  useEffect(() => {
    const saved = loadTableSettings(SETTINGS_KEY);
    if (saved) setGridColumns(saved);
  }, []);

  return (
    <div className="flex flex-col h-full gap-3 p-4">
      {/* 검색 필터 */}
      <DynamicSearchFilter
        fields={FILTER_CONFIG}
        values={filterValues}
        onChange={setFilterValues}
        onSearch={fetchData}
        onReset={() => { setFilterValues({}); }}
      />

      {/* 메인 카드 */}
      <div className="flex-1 flex flex-col border rounded-lg bg-card overflow-hidden">
        {/* 패널 헤더 */}
        <div className="flex items-center justify-between p-3 border-b">
          <div className="flex items-center gap-2">
            <h3 className="text-sm font-semibold">목록</h3>
            <Badge variant="secondary" className="text-xs font-mono">{totalCount}</Badge>
          </div>
          <div className="flex items-center gap-1.5">
            <Button size="sm" variant="outline" onClick={() => { setIsEditMode(false); setFormData({}); setIsModalOpen(true); }}>
              <Plus className="h-3.5 w-3.5 mr-1" /> 등록
            </Button>
            <Button size="sm" variant="outline" className="text-destructive" onClick={handleDelete}>
              <Trash2 className="h-3.5 w-3.5 mr-1" /> 삭제
            </Button>
            <Button size="sm" variant="ghost" onClick={() => setSettingsOpen(true)}>
              <Settings2 className="h-3.5 w-3.5" />
            </Button>
          </div>
        </div>

        {/* 데이터 그리드 */}
        <DataGrid
          columns={gridColumns}
          data={data}
          selectedId={selectedId}
          checkedIds={checkedIds}
          onRowClick={(row) => setSelectedId(row.id)}
          onCheckChange={setCheckedIds}
          loading={loading}
          emptyMessage="데이터가 없어요"
        />
      </div>

      {/* 등록/수정 모달 */}
      <FullscreenDialog open={isModalOpen} onOpenChange={setIsModalOpen} title={isEditMode ? "수정" : "등록"}>
        <div className="grid grid-cols-4 gap-4">
          {/* SmartSelect, FormDatePicker 등 공통 컴포넌트 활용 */}
        </div>
      </FullscreenDialog>

      {/* 테이블 설정 모달 */}
      <TableSettingsModal
        open={settingsOpen}
        onOpenChange={setSettingsOpen}
        columns={gridColumns}
        onSave={setGridColumns}
        settingsKey={SETTINGS_KEY}
      />

      {ConfirmDialogComponent}
    </div>
  );
}
```

---

## 8. 메뉴 등록 규칙 (신규 화면 필수)

### 8-1. AdminPageRenderer 레지스트리 등록
```tsx
"/{COMPANY}/{category}/{screen}": dynamic(
  () => import("@/app/(main)/{COMPANY}/{category}/{screen}/page"),
  { ssr: false, loading: LoadingFallback }
),
```

### 8-2. menu_info 테이블 업데이트
- `menu_url`: 새 경로 / `screen_code`: NULL / `screen_group_id`: NULL

### 8-3. screen_menu_assignments 비활성화
해당 메뉴의 모든 할당을 `is_active = 'N'`으로 변경.

---

## 9. 절대 금지 사항

1. `fetch()` 직접 사용 (반드시 `apiClient` 사용)
2. 하드코딩 색상 (`bg-gray-*`, `bg-white`, `text-black`, `#hex`)
3. 새 라이브러리 설치
4. `console.log` 남기기
5. `any` 타입 남발 (최소한의 타입 정의)
6. 비즈니스 로직 변경 (UI 리디자인 태스크일 때)
7. Card-in-Card 중첩
8. 인라인 콘텐츠에 `max-h` / `overflow-y-auto`

---

## 10. 화면별 고유 디자인 원칙

- 다른 화면을 "복사"하지 말 것. 각 화면의 컬럼/필드/모달은 독립 설계
- `ref_files`에 다른 화면 코드가 있어도 **패턴 참고**일 뿐
- 각 화면의 DB 테이블과 비즈니스 로직에 맞게 구성