Edge → Screen 자동 연동 (Auto-Bridge)

개요

캔버스에서 테이블 노드 간 1:N Edge에 서브테이블 설정을 하면, document 타입 Screen 노드의 documentConfig.lineItems가 자동으로 생성됩니다. 프리셋 JSON을 수동 작성하지 않아도 전표(견적서, 주문서 등) 화면을 구성할 수 있습니다.

작동 원리

Edge 방향 규칙

• source = 자식 테이블 (FK 보유, 예: quotation_items)
• target = 부모 테이블 (참조 대상, 예: quotations)

이중 실행 구조

시점	역할	구현
캔버스 실시간	미리보기 표시	useMemo (ScreenViewNodePanel)
배포 시	최종 documentConfig 생성	enrichScreenNodesFromEdges() (서버)

lineItems는 파생 데이터

• Screen 노드에 저장하지 않음
• Edge가 변경되면 자동 반영
• 배포 시 서버에서 최종 빌드 후 canvas_deployments에 persist

설정 방법

1단계: Edge 서브테이블 설정

1:N Edge를 선택하고 속성 패널에서:

• 서브테이블 표시 활성화
• 제목, 표시 컬럼, 행 추가/삭제 허용 설정
• (선택) 정렬 순서 (order)

2단계: 행 수식 설정 (Phase 2)

• 대상 컬럼과 수식 표현식 입력 (예: quantity * unit_price)
• 의존성 자동 추출
• 순환 참조 감지

3단계: 품목 Lookup 설정 (Phase 2)

• 참조 마스터 테이블 선택
• FK 컬럼 지정
• 자동 채움 매핑 (source → target)

4단계: Screen 노드 설정 (Phase 3)

document 타입 Screen 노드에서:

• 합계 영역 (footerSummary): SUM(amount) → total_amount
• 자동채번 (documentNumbering): QT-202603-0001
• 상태 흐름 (statusFlow): 작성 → 제출 → 협상 → 수주전환

데이터 흐름

[Canvas UI]
  Edge subtableConfig 설정
  Screen document 타입 선택
  |
  v
[Deploy 트리거]
  POST /schema-designer/canvas/{id}/deploy
  → canvas_deployments에 원본 노드 저장
  |
  v
[Code-Gen 파이프라인]
  enrichScreenNodesFromEdges()
  → Edge subtableConfig → lineItems 변환
  → Phase 3 필드 (footerSummary, documentNumbering, statusFlow) 병합
  |
  v
[Enriched 데이터 Persist]
  updateDeployedScreens() → PATCH internal API
  → canvas_deployments.deployed_screens 업데이트
  |
  v
[자동채번 동기화]
  syncAutoNumberingRules()
  → auto_numbering_rules 테이블 UPSERT
  |
  v
[Runtime]
  deployed_screens 조회 → RuntimeDocumentView 렌더링
  상태 전이 검증 (CRUD UPDATE 시 서버 검증)
  crossCalculations (서브테이블 CUD 시 헤더 자동 갱신)

병합 규칙

우선순위	소스	설명
1 (최우선)	Edge subtableConfig	캔버스에서 직접 설정한 Edge
2	프리셋 JSON lineItems	솔루션 템플릿에서 정의된 값
3	기본값	addable=true, deletable=true

동일 boundTableRef가 있으면 Edge 설정이 우선. 프리셋에만 있는 lineItems는 유지됨.

수식 보안

항목	규칙
실행 엔진	AST 기반 파서 (safe-formula.ts)
금지	eval(), new Function()
허용 연산자	+, -, *, /, ()
허용 함수	round, floor, ceil
허용 변수	해당 서브테이블 컬럼명만 (화이트리스트)
길이 제한	200자
순환 감지	DFS 기반 dependency graph 검증

백엔드 검증

상태 전이 검증

• CRUD UPDATE 시 statusFlow 규칙에 따라 서버에서 검증
• 허용되지 않은 전이 시 400 BadRequest 반환
• 5분 TTL 캐시로 성능 최적화

헤더 자동 갱신 (crossCalculations)

• 서브테이블 행 INSERT/UPDATE/DELETE 시 헤더 SUM 자동 갱신
• 예: quotation_items 변경 → quotations.total_amount = SUM(amount)

자동채번 동기화

• 배포 시 auto_numbering_rules 테이블에 UPSERT
• current_sequence는 보존 (리셋하지 않음)
• 기존 AutoNumberingService와 연동

하위 호환성

• Edge subtableConfig가 없으면 기존 방식 그대로 동작
• 모든 새 필드는 optional -- 기존 데이터 역직렬화 안전
• 프리셋에 이미 lineItems가 있으면 병합 (Edge 우선)
• statusFlow가 없는 테이블은 전이 검증 스킵

관련 파일

구성 요소	파일
타입 정의	packages/shared/src/solutions/types.ts (SubtableEdgeConfig)
수식 파서	packages/shared/src/utils/safe-formula.ts
서버 변환	packages/services/code-generation/.../schema-designer-client.service.ts
배포 동기화	packages/services/code-generation/.../codegen-orchestrator.service.ts
상태 전이/crossCalc	packages/services/code-generation/.../dynamic-crud.service.ts
Edge UI	packages/frontend/.../panels/RelationPanel.tsx
Screen UI	packages/frontend/.../panels/ScreenViewNodePanel.tsx
수식 편집	packages/frontend/.../panels/relation/LineFormulaEditor.tsx
Lookup 편집	packages/frontend/.../panels/relation/ItemLookupEditor.tsx
Document 패널	packages/frontend/.../panels/document/ (4개 컴포넌트)