테이블 정의 (tables)

테이블 정의

{
  "refId": "hcm_items",
  "tableName": "hcm_items",
  "displayName": "품목마스터",
  "connectUsers": true,
  "connectDepartments": false,
  "isHierarchical": false,
  "auditEnabled": true,
  "columns": [...]
}

테이블 필드 명세

필드	타입	필수	설명
refId	string	필수	솔루션 내 고유 참조 ID. tableName과 동일하게 설정
tableName	string	필수	실제 DB 테이블명. {접두사}_{기능명} 형식
displayName	string	필수	한글 표시명
columns	array	필수	컬럼 정의 배열
connectUsers	boolean	선택	true → created_by, updated_by 자동 추가
connectDepartments	boolean	선택	true → department_id 자동 추가
isHierarchical	boolean	선택	true → parent_id, sort_order, level 자동 추가 (트리 구조)
auditEnabled	boolean	선택	감사 로그 추적 (기본: true)
enableCsvImport	boolean	선택	CSV 업로드 허용
enableCsvExport	boolean	선택	CSV 다운로드 허용
enablePrint	boolean	선택	인쇄 기능 활성화

자동 생성 컬럼 (명시하지 않아도 자동 추가)

조건	자동 추가 컬럼
모든 테이블	id (UUID, PK)
connectUsers: true	created_by (UUID, SYSTEM_REF→users), updated_by (UUID, SYSTEM_REF→users)
connectDepartments: true	department_id (UUID, SYSTEM_REF→departments)
isHierarchical: true	parent_id (UUID), sort_order (INT), level (INT)
auditEnabled: true	created_at (TIMESTAMP), updated_at (TIMESTAMP)

규칙

• refId와 tableName은 반드시 동일해야 함
• 테이블명은 {고객접두사}_{기능명} 형식 (예: hcm_items, djn_work_orders)
• 고객 간 접두사 중복 금지 — 각 고객별 고유 접두사 사용
• id 컬럼을 columns에 직접 정의하지 않음 (시스템 자동 생성)

---

audit_trail (감사 추적 테이블 패턴)

audit_trail은 CascadeUpdateService에 의해 자동 관리되는 시스템 테이블입니다. 연쇄 갱신이 발생할 때마다 변경 이력이 자동으로 기록됩니다.

스키마

컬럼	타입	설명
id	UUID	PK (자동 생성)
entity_type	VARCHAR	변경된 대상 테이블명 (예: work_orders)
entity_id	UUID	변경된 대상 행의 ID
field_name	VARCHAR	변경된 컬럼명 (예: good_qty)
old_value	TEXT	변경 전 값
new_value	TEXT	변경 후 값
changed_by	UUID	변경을 수행한 사용자 ID
changed_at	TIMESTAMP	변경 시각 (서버 시간)
source_entity_type	VARCHAR	변경을 유발한 원본 테이블명 (예: production_results)
source_entity_id	UUID	변경을 유발한 원본 행의 ID

특징

• 자동 관리: CascadeUpdateService가 연쇄 갱신 시 자동으로 INSERT — 수동 시드 데이터 불필요
• 런타임 전용: 프리셋 JSON의 seedData에 audit_trail 데이터를 포함하지 않음
• 추적 가능성: source_entity_type + source_entity_id로 변경의 원인을 역추적 가능
• DB 마이그레이션: database/migrations/218_audit_trail.sql에서 테이블 생성

프리셋 JSON과의 관계

audit_trail 테이블은 프리셋 JSON에서 정의하지 않습니다. 시스템 마이그레이션에 의해 자동 생성되며, 솔루션 템플릿의 테이블 정의(tables 배열)에 포함할 필요가 없습니다.

프리셋 JSON 테이블 정의 (tables)
  └─ 사용자 정의 테이블만 포함
      ├─ work_orders
      ├─ production_results
      └─ sales_orders

시스템 테이블 (마이그레이션으로 자동 생성)
  └─ audit_trail ← CascadeUpdateService가 자동 INSERT

---

다음: 컬럼 정의 (기본) | 참조: 검증 체크리스트