컬럼 정의 — 고급

기본 컬럼 문법은 컬럼 정의 (기본)을 참조하세요.

FK 참조 (fkRef)

{
  "name": "item_id",
  "displayName": "품목",
  "type": "UUID",
  "constraints": ["FK", "NOT_NULL"],
  "fkRef": {
    "targetTableRef": "hcm_items",
    "displayColumn": "item_name"
  }
}

필드	타입	설명
`targetTableRef`	`string`	참조 대상 테이블의 `refId`
`displayColumn`	`string`	대상 테이블에서 실제 존재하는 표시 컬럼명

FK 규칙 (중요!)

targetTableRef는 같은 JSON 파일 내 테이블의 refId만 참조 가능
displayColumn은 대상 테이블의 columns 중 실제 존재하는 name 이어야 함
기존 솔루션 테이블(541개) 참조 금지 — 고객 접두사 내에서만 참조
type은 반드시 "UUID"
자기 참조(self-reference)도 가능 (예: hcm_item_categories → hcm_item_categories)

SYSTEM_REF (시스템 테이블 참조)

{
  "name": "manager_id",
  "displayName": "담당자",
  "type": "UUID",
  "constraints": ["SYSTEM_REF"],
  "systemRef": "users"
}

systemRef 값	대상	설명
`"users"`	시스템 사용자 테이블	담당자, 작성자, 승인자 등
`"departments"`	시스템 부서 테이블	소속부서, 관리부서 등

이 두 테이블만 SYSTEM_REF로 참조 가능
FK와 달리 fkRef 불필요 — systemRef만 지정

FILE 타입

{
  "name": "drawing_file",
  "displayName": "도면",
  "type": "FILE",
  "constraints": [],
  "fileMeta": {
    "uploadEnabled": true,
    "allowedCategories": ["image", "document"],
    "maxFileSize": 10,
    "maxFiles": 5,
    "previewEnabled": true,
    "versioningEnabled": false
  }
}

fileMeta 필드	타입	설명
`uploadEnabled`	`boolean`	업로드 허용 여부
`allowedCategories`	`string[]`	허용 파일 유형: `image`, `document`, `excel`, `archive`, `general`
`maxFileSize`	`number`	최대 파일 크기 (MB)
`maxFiles`	`number`	최대 파일 수
`previewEnabled`	`boolean`	미리보기 허용
`versioningEnabled`	`boolean`	파일 버전 관리

자동 계산 컬럼 (isComputed + computedConfig)

isComputed: true인 컬럼은 DTO에서 제외되고, 런타임에서 읽기 전용으로 렌더링됩니다.

computedConfig 타입별 정의

1. formula (동일 레코드 필드 연산)

{
  "name": "total_amount",
  "displayName": "총액",
  "type": "DECIMAL",
  "constraints": [],
  "defaultValue": "0",
  "isComputed": true,
  "computedConfig": {
    "type": "formula",
    "expression": "quantity * unit_price",
    "dependsOn": ["quantity", "unit_price"]
  },
  "description": "수량 × 단가 자동 계산"
}

computedConfig 필드	타입	설명
`type`	`"formula"`	동일 레코드 내 필드 간 수식
`expression`	`string`	JavaScript 수식 (`+`, `-`, `*`, `/` 사용)
`dependsOn`	`string[]`	수식에 사용되는 컬럼명 배열 (실시간 재계산용)

2. aggregation (자식 테이블 집계)

{
  "name": "completion_rate",
  "displayName": "완성률",
  "type": "DECIMAL",
  "constraints": [],
  "defaultValue": "0",
  "isComputed": true,
  "computedConfig": {
    "type": "aggregation",
    "sourceTable": "work_orders",
    "sourceColumn": "good_qty",
    "function": "SUM",
    "fkColumn": "production_order_id",
    "expression": "SUM(good_qty) / order_qty * 100"
  },
  "description": "하위 작업지시 양품합계 ÷ 지시수량 × 100"
}

computedConfig 필드	타입	설명
`type`	`"aggregation"`	자식 테이블 집계
`sourceTable`	`string`	집계 대상 자식 테이블 `refId`
`sourceColumn`	`string`	집계 대상 컬럼명
`function`	`string`	집계 함수: `"SUM"`, `"AVG"`, `"COUNT"`, `"MAX"`, `"MIN"`
`fkColumn`	`string`	자식 테이블에서 부모를 참조하는 FK 컬럼
`expression`	`string`	선택 — 집계 후 추가 연산 수식

3. reference (다른 테이블 참조 조회)

{
  "name": "customer_name",
  "displayName": "고객명",
  "type": "VARCHAR",
  "constraints": [],
  "isComputed": true,
  "computedConfig": {
    "type": "reference",
    "sourceTable": "partners",
    "sourceColumn": "partner_name",
    "fkColumn": "partner_id"
  },
  "description": "거래처 테이블에서 조회"
}

computedConfig 필드	타입	설명
`type`	`"reference"`	다른 테이블 값 조회
`sourceTable`	`string`	참조 대상 테이블 `refId`
`sourceColumn`	`string`	참조 대상 컬럼명
`fkColumn`	`string`	현재 테이블의 FK 컬럼

isComputed 규칙

isComputed: true 컬럼은 Create/Update DTO에서 자동 제외
런타임 폼에서 읽기 전용 + fx 배지 표시
런타임 리스트에서 인라인 편집 비활성 + fx 텍스트 배지
computedConfig.type에 따라 계산 시점이 다름:
- formula: 폼 입력 실시간 + 서버 CREATE/UPDATE 시
- aggregation: 자식 레코드 변경 시 (CascadeUpdateService 또는 서버 재집계)
- reference: 서버 조회 시
NaN/Infinity 방지를 위해 서버에서 validateComputedValue() 적용
시드 데이터에 반드시 계산 결과와 일치하는 값 제공 필요

자동 채번 컬럼 (supportsAutoNumbering)

{
  "name": "wo_number",
  "displayName": "작업지시번호",
  "type": "VARCHAR",
  "constraints": ["NOT_NULL", "UNIQUE"],
  "supportsAutoNumbering": true,
  "autoNumberingPrefix": "WO",
  "description": "WO-{YYYY}{MM}-{SEQ:4} 패턴 자동 생성"
}

필드	타입	필수	설명
`supportsAutoNumbering`	`boolean`	✅	`true`로 설정 시 자동 채번 활성화
`autoNumberingPrefix`	`string`	선택	채번 접두어 (예: `"PO"`, `"SO"`, `"WO"`)

접두어 네이밍 규칙 가이드

autoNumberingPrefix를 정의할 때 다음 규칙을 따릅니다.

규칙	설명	예시
2~4자 영문 대문자	접두어 길이는 2~4자로 제한	`PO`, `WO`, `CAPA`
업계 표준 약어 우선	국제적으로 통용되는 약어 사용	`PO` = Purchase Order, `SO` = Sales Order
도메인 내 중복 금지	같은 솔루션(도메인) 안에서 접두어 중복 불가	ERP 내 `PO`가 있으면 다른 테이블에 `PO` 재사용 금지
필수 지정 권장	솔루션 정의 시 `autoNumberingPrefix` 명시 권장	미지정 시 빈 문자열로 생성되어 런타임에서 별도 설정 필요

접두어는 테이블별 문서번호의 식별자 역할 (예: PO = Purchase Order, SO = Sales Order)
캔버스 노드의 컬럼 설정에서 직접 입력 가능
접두어를 지정하면 배포 시 기본 채번 규칙이 자동 생성됨
미지정 시 빈 문자열로 생성 (런타임에서 수정 가능)

배포 시 자동 생성되는 기본 규칙

배포 시 autoNumberingPrefix 값을 기반으로 auto_numbering_rules 레코드가 자동 생성됩니다. 기본 생성 패턴은 {PREFIX}-{YYYY}{MM}-{SEQ:4}입니다.

항목	기본값	설명
`prefix`	`autoNumberingPrefix` 값	접두어
`date_format`	`{YYYY}{MM}`	날짜 패턴 (년월)
`separator`	`-`	구분자
`sequence_length`	`4`	시퀀스 자릿수 (0001~9999)
`reset_period`	`monthly`	월별 시퀀스 리셋
`timezone`	`Asia/Seoul`	타임존
`is_active`	`true`	기본 활성 상태

생성 예시:

autoNumberingPrefix: "SO" → SO-202603-0001, SO-202603-0002, ...
autoNumberingPrefix: "PO" → PO-202603-0001, PO-202603-0002, ...
autoNumberingPrefix: "WO" → WO-202603-0001, WO-202603-0002, ...

런타임 상세 설정

배포 후 런타임의 자동 채번 다이얼로그에서 다음 항목을 미세조정할 수 있습니다:

접두어, 날짜 패턴, 구분자, 시퀀스 자릿수, 접미어
리셋 주기 (일별/월별/연별)
수동 입력 허용 여부
오버플로우 정책 (시퀀스 초과 시 처리 방식)

supportsAutoNumbering 규칙

supportsAutoNumbering: true 컬럼은 런타임 폼에서 읽기 전용 + 잠금 아이콘 표시
런타임 리스트에서 인라인 편집 비활성 + 잠금 아이콘
배포 시 자동 규칙 생성: autoNumberingPrefix 기반으로 auto_numbering_rules 레코드 자동 INSERT (ON CONFLICT 무시로 재배포 안전)
채번 패턴은 auto_numbering_rules 테이블에 테넌트별 DB 저장 → 세션 간 유지
패턴 구성요소: {PREFIX}, {YYYY}, {MM}, {DD}, {SEQ:N} (N자리 시퀀스)
시퀀스는 타임존 인식 리셋 (일별/월별) + 오버플로우 처리
Create DTO에서 제외되지 않으나, 빈 값이면 서버가 자동 생성
런타임의 자동 채번 다이얼로그에서 접두어, 날짜 패턴, 시퀀스 자릿수 등 상세 커스터마이즈 가능

자동채번 설정 흐름

프리셋 정의부터 런타임까지의 자동채번 설정 흐름은 다음과 같습니다.

솔루션/프리셋 정의 (autoNumberingPrefix)
    ↓
캔버스 적용 (solutionSlice에서 복사)
    ↓
캔버스에서 접두어 확인/수정 가능
    ↓
배포 (deployment-saga에서 auto_numbering_rules 생성)
    ↓
런타임에서 상세 설정 미세조정 가능

도메인별 표준 접두어 참조

솔루션 정의 시 참조할 수 있는 도메인별 표준 접두어 목록입니다.

ERP 기본

접두어	용도	예시
`PO`	생산오더 (Production Order)	PO-202603-0001
`PR`	구매요청 (Purchase Requisition)	PR-202603-0001
`SO`	주문/수주 (Sales Order)	SO-202603-0001
`GR`	입고 (Goods Receipt)	GR-202603-0001
`SH`	출하 (Shipment)	SH-202603-0001
`QT`	견적 (Quotation)	QT-202603-0001
`CT`	계약 (Contract)	CT-202603-0001
`GL`	전표 (General Ledger)	GL-202603-0001
`AR`	채권 (Accounts Receivable)	AR-202603-0001
`AP`	채무 (Accounts Payable)	AP-202603-0001
`TI`	세금계산서 (Tax Invoice)	TI-202603-0001
`ECO`	설계변경 (Engineering Change Order)	ECO-202603-0001
`NCR`	부적합 (Non-Conformance Report)	NCR-202603-0001

MES

접두어	용도	예시
`WO`	작업지시 (Work Order)	WO-202603-0001
`LOT`	LOT번호	LOT-202603-0001
`QI`	검사 (Quality Inspection)	QI-202603-0001

SCM/WMS

접두어	용도	예시
`RFQ`	견적요청 (Request for Quotation)	RFQ-202603-0001
`IPO`	수입발주 (Import Purchase Order)	IPO-202603-0001
`LC`	신용장 (Letter of Credit)	LC-202603-0001
`WI`	입고 (Warehouse Inbound)	WI-202603-0001
`WBO`	출고 (Warehouse Outbound)	WBO-202603-0001
`PK`	피킹 (Picking)	PK-202603-0001
`ADJ`	조정 (Adjustment)	ADJ-202603-0001

QMS

접두어	용도	예시
`CAPA`	시정조치 (Corrective & Preventive Action)	CAPA-202603-0001
`PPAP`	양산승인 (Production Part Approval)	PPAP-202603-0001
`DEV`	일탈 (Deviation)	DEV-202603-0001

LookupColumnDef 확장 (소스 문서 패널 컬럼)

sourceDocumentConfig의 displayColumns에서 사용하는 확장된 컬럼 정의입니다. 기본 표시 외에 모바일 카드 렌더링과 가상 계산 컬럼을 지원합니다.

LookupColumnDef 인터페이스

interface LookupColumnDef {
  columnName: string;     // 표시할 컬럼명
  label: string;          // 한글 라벨
  width: number;          // 컬럼 너비 (px)
  render?: 'number' | 'date' | 'badge' | 'link';
  cardRole?: 'title' | 'subtitle' | 'quantity' | 'status';   // 카드 역할
  computed?: {                                                  // 가상 계산 컬럼
    expression: string;
    label: string;
  };
}

필드 명세

필드	타입	필수	설명
`columnName`	`string`	필수	소스 테이블의 컬럼명
`label`	`string`	필수	패널에 표시할 한글 라벨
`width`	`number`	필수	테이블 모드에서의 컬럼 너비 (px)
`render`	`string`	선택	렌더러 타입: `number`, `date`, `badge`, `link`
`cardRole`	`string`	선택	모바일 카드 모드에서의 역할
`computed`	`object`	선택	가상 계산 컬럼 정의 (DB에 없는 계산값)

cardRole (모바일 카드 역할)

SourceDocumentPanel을 모바일(카드 뷰)로 렌더링할 때, 각 컬럼이 카드의 어느 위치에 표시될지 결정합니다.

cardRole	카드 위치	설명
`title`	카드 제목	굵은 글씨, 상단 표시
`subtitle`	카드 부제	제목 아래 작은 글씨
`quantity`	수량 영역	오른쪽 정렬, 숫자 강조
`status`	상태 배지	색상 배지로 표시

{
  "displayColumns": [
    { "columnName": "order_number", "label": "수주번호", "width": 120, "cardRole": "title" },
    { "columnName": "item_name", "label": "품목명", "width": 150, "cardRole": "subtitle" },
    { "columnName": "quantity", "label": "주문수량", "width": 80, "render": "number", "cardRole": "quantity" },
    { "columnName": "status", "label": "상태", "width": 80, "render": "badge", "cardRole": "status" }
  ]
}

computed (가상 계산 컬럼)

DB에 존재하지 않는 가상 컬럼을 패널에서 계산하여 표시합니다. 주로 잔량(미출하수량, 미입고수량)을 표시할 때 사용합니다.

{
  "displayColumns": [
    { "columnName": "quantity", "label": "주문수량", "width": 80, "render": "number" },
    { "columnName": "shipped_qty", "label": "출하수량", "width": 80, "render": "number" },
    {
      "columnName": "_remaining",
      "label": "미출하수량",
      "width": 80,
      "render": "number",
      "cardRole": "quantity",
      "computed": {
        "expression": "quantity - shipped_qty",
        "label": "미출하"
      }
    }
  ]
}

computed 규칙

expression에 사용되는 컬럼은 같은 displayColumns 또는 소스 테이블에 존재해야 함
columnName은 _로 시작하는 가상 이름 사용 권장 (예: _remaining, _balance)
계산 결과는 클라이언트 사이드에서 실시간 연산 — 서버 집계와 별개
음수 결과 방지를 위해 Math.max(0, result) 처리 적용

이전: 컬럼 정의 (기본) | 다음: 관계 정의

FK 참조 (fkRef)​

FK 규칙 (중요!)​

SYSTEM_REF (시스템 테이블 참조)​

FILE 타입​

자동 계산 컬럼 (isComputed + computedConfig)​

computedConfig 타입별 정의​

isComputed 규칙​

자동 채번 컬럼 (supportsAutoNumbering)​

접두어 네이밍 규칙 가이드​

배포 시 자동 생성되는 기본 규칙​

supportsAutoNumbering 규칙​

자동채번 설정 흐름​

도메인별 표준 접두어 참조​

LookupColumnDef 확장 (소스 문서 패널 컬럼)​

LookupColumnDef 인터페이스​

필드 명세​

cardRole (모바일 카드 역할)​

computed (가상 계산 컬럼)​

computed 규칙​