L5 워크플로우 공통 규칙 명세
목적과 적용 범위
이 명세는 특정 프로세스명·화면 배치·Y/N 사례에 대한 예외 처리가 아니다. L5 워크플로우에서 START, 현재 L5 하위 L6, 타 L5, 의사결정, 자동 조건분기, END와 모든 전이에 일관되게 적용되는 저장·편집·배치·라우팅 규칙이다. 기존 프로세스 노드와 전이 데이터는 삭제하거나 자동 변환하지 않는다.
엔티티와 전이 계약
| 엔티티 | 역할 | 허용 후행 대상 | 결과 상태 |
|---|---|---|---|
| START | 현재 L5 내부 시작점 | L6, 타 L5, 의사결정, 자동 조건분기 | DEFAULT 하나 |
| L6 | 현재 L5의 실행 태스크 | L6, 타 L5, 의사결정, 자동 조건분기, END | DEFAULT 하나 |
| 타 L5 | 현재 L5 안에서 처리 결과를 반환하는 외부 프로세스 엔티티 | 현재 L5의 L6, 타 L5, 의사결정, 자동 조건분기 | DEFAULT 하나 |
| 의사결정 | 사람이 판단·승인·선택하는 다이아몬드 | L6, 타 L5, 의사결정, 자동 조건분기 | Y/N 또는 사용자 정의 결과, 결과별 하나 |
| 자동 조건분기 | 데이터·상태·규칙으로 자동 분기하는 다이아몬드 | L6, 타 L5, 의사결정, 자동 조건분기 | A/B/C/ELSE 등, 결과별 조건식 필수 |
| END | 명시적 종료점 | 없음 | 없음 |
일반 엔티티(START·L6·타 L5)는 하나의 직접 후행만 가진다. 다른 후행으로 변경하여 저장하면 기존 직접 후행을 교체한다. 다중 결과가 필요한 경우에는 의사결정 또는 자동 조건분기를 사용한다. 모든 엔티티는 여러 선행을 받을 수 있으며, 순환 연결과 START로의 인입은 허용하지 않는다. END는 현재 L5 하위 L6의 명시적 종료 연결에서만 사용할 수 있다.
타 L5는 원본 L5의 속성은 읽기 전용이지만, 현재 L5 캔버스에서는 정상적인 선행·후행 관계를 갖는
process엔티티다. 타 L5의 처리 결과는 현재 L5의 다음 L6·의사결정·조건분기로 연결할 수 있다.
관계 편집 UI 규칙
모든 START·L6·타 L5는 엔티티 목록에서 선택 가능해야 하며, 동일한 관계 편집기를 통해 후행 엔티티를 선택한다. 의사결정과 자동 조건분기는 결과별 후행 엔티티 편집기를 사용한다. 대상 목록은 유형을 명시적으로 표시하고, 현재 선택된 선행·기존 저장 연결·저장 실패 이유를 보여야 한다.
저장 API는 소스·대상 엔티티 유형과 결과 상태를 함께 검증한다. 일반 엔티티의 후행 변경은 충돌 오류로 막지 않고 유효한 단일 기본 전이를 원자적으로 교체한다. 의사결정과 자동 조건분기는 결과 상태를 키로 하여 각 결과 전이를 교체한다.
L5 간 핸드오프는 (출발 단계 → 후행 L5) 쌍마다 한 행을 유지한다. 후행 지정(A에서 "다음 L5 = B")과 선행 지정(B에서 "이 엔티티의 선행 = A")은 같은 행을 다루며, 선행 지정은 그 행의 대상 단계만 구체화한다. 같은 쌍의 행으로 인정하는 모양은 세 가지다 — EXTERNAL_L5_HANDOFF 표식이 있는 정본 행, 표식 없이 저장된 예전 후행 연결(대상이 출발 L5의 "타 L5" 대리 엔티티), 표식 없이 저장된 "후행 L5의 단계로 직접 지정" 행(옛 화면이 선행 지정으로 구체화한 행). 이 중 하나라도 후보에서 빠지면 같은 쌍에 행이 하나 더 생겨 상대 L5 화면에 유입이 두 줄로 보인다.
초기 배치 원칙
그래프의 세로 레벨은 전이 방향에 따라 정하고, 캔버스는 세로로 확장한다. 초기 수평 위치는 읽기 쉬운 시작 배치일 뿐 고정값이 아니다. 실제 라우팅에서 충돌·관통·3회 초과 굽힘·라벨 충돌이 발생할 때만 후행 또는 필요한 선행 엔티티를 수평 이동 후보로 평가한다. 이미 안전한 배치는 미관상 이유만으로 움직이지 않는다.
의사결정 또는 조건분기에서 한 결과만 추가 엔티티를 거쳐 공통 단계로 재합류하면, 추가 엔티티는 해당 결과 방향으로 수평 배치하고 공통 단계로 직접 가는 결과는 가능한 한 아래 방향을 유지한다. 이는 특정 Y/N 이름이 아니라 모든 비대칭 분기에 적용한다.
포트 및 직각 라우팅 원칙
모든 연결은 수평·수직 선분만 사용하고, 최대 굽힘 수는 3회다. 어떤 선도 엔티티 내부 또는 안전 여백을 통과해서는 안 되며, 다른 선 및 라벨과 겹치거나 교차해서는 안 된다.
| 구분 | 공통 규칙 |
|---|---|
| 일반 엔티티 출발 | 하단에서 출발한다. |
| 일반 엔티티 인입 | 상단 인입을 절대 우선한다. 먼저 직선·1회·2~3회 굽힘의 상단 인입 경로를 모두 평가하고, 안전 경로가 없을 때만 위·좌·우·아래 측면·하단 보조 후보를 평가한다. 다중 인입은 선택된 변을 따라 분산한다. |
| 의사결정·조건분기 인입 | 상단 꼭지점으로 진입하는 3회 이하 안전 경로를 먼저 탐색한다. 이 경로가 없을 때만 좌·우 꼭지점을 보조 인입 후보로 평가한다. |
| 의사결정·조건분기 출발 | 좌·하·우 포트를 모두 후보로 사용한다. 측면 포트는 먼저 해당 방향으로 짧은 수평 stub를 만든 뒤 내려간다. 하단 포트는 먼저 아래로 출발한다. |
| 포트 선택 | 결과 라벨(Y/N/A/B 등)이 아닌 목적지 방향·하단 축 겹침·충돌·라벨 여백·기존 선 예약을 평가한다. 대상 인입 우선순위는 직선 상단 → 1회 굽힘 상단 → 2~3회 굽힘 상단 → 측면·하단 보조 인입이다. |
| 하단 우선 | 목적지 상자가 다이아몬드의 하단 축과 겹치거나 안전 여백 안에 있고 하단 경로가 안전하면, 중심점이 정확히 같지 않아도 하단 포트를 우선한다. |
| 측면 정합 | 측면 포트를 선택하면 목적지 또는 재배치된 목적지는 그 측면에 있어야 한다. |
| 재배치 | 가능한 경로가 없거나 3회 초과가 필요한 경우, 후보 수평 위치에서 전체 그래프를 다시 라우팅하고 점수가 실제로 개선될 때만 반영한다. |
여러 인입선은 선택된 대상 변에서 충돌 없이 분산하며, 의사결정·조건분기의 상단 꼭지점으로 합류하는 최종 접근선은 동일한 종점 예약으로 허용한다. 일반 엔티티에 상단 인입이 여러 개이고 현재 위치에서 안전하게 분산되지 않으면, 개별 선만 우회하지 말고 공유 대상 엔티티 자체의 수평 위치를 후보로 평가하여 전체 그래프의 인입을 다시 계산한다. 인입선 수에 따른 임의의 상한으로 전이를 생략하지 않는다. 라우팅에 실패한 저장 전이는 조용히 사라지지 않아야 하며, 관리자에게 전이와 실패 사유를 표시해야 한다.
라우팅 우선순위와 복구 순서
우선순위의 정본은 이 목록 하나다 — 다른 문서는 이 순서를 다시 쓰지 않고 참조한다.
- 안전 — 엔티티·라벨·다른 선과 겹치거나 교차하지 않고, 엔티티 내부·안전 여백을 통과하지 않는다.
- 꺾임 한도 — 수평·수직 선분만 쓰고 최대 3회 굽힘(문서화·테스트된 조밀 이진 분기만 4회,
MAX_COMPLEX_BINARY_ROUTE_BENDS). - 꺾임 최소 — 위 두 조건을 지키는 후보가 여럿이면 꺾임이 적은 포트를 먼저 고른다. 관례·구조 규칙보다 먼저 본다: 선행 아래에 정렬된 분기가 있으면 그 분기가 다이아몬드 하단 꼭짓점의 직선(0꺾임) 을 갖고, 나머지 분기가 옆면으로 돈다(
planDecisionExitPort, 분기가 둘일 때만). - 방향 보존 — 분기 결과의 방향(NO 좌 / YES 우)과 대상 인입 변(상단 인입 절대 우선)을 지킨다. 꺾임 판정이 없을 때의 규칙이다.
- 정렬 — 호출 노드는 선행 L6 중심축에, 비대칭 분기의 재합류는 아래 방향에 맞춘다.
- 중심 맞춤 — 위 조건이 모두 만족될 때만 후보 위치를 평가한다. 이미 안전한 배치는 미관만으로 옮기지 않는다.
복구 패스도 같은 순서로만 동작한다: ① 호출 노드 축 정렬(alignCallSitesToPredecessorCenter, 라우팅 전) → ② 기본 직각 라우팅 → ③ 후보 수평 위치 재배치(전체 재라우팅 점수가 실제로 개선될 때만 채택) → ④ 마지막 안전망(separateOverlappingNodes, 최소 간격 8 유지). 뒤 단계가 앞 단계를 되돌릴 수 있다 — 안전이 항상 정렬보다 우선한다.
박스 엔티티 사이는 선행의 X 중심선을 맞춘다. L6·타 L5 대리(호출 카드)·하단 밴드 카드처럼 사각 박스로 그리는 엔티티끼리 이어질 때는 후행 박스의 중심을 선행 박스의 중심과 같게 두고, 그 사이 선은 수직 직선으로 그린다 — 세 패스가 같은 기준을 쓴다: 호출 카드 alignCallSitesToPredecessorCenter, 일반 후행 alignSuccessorsToPredecessorCenters, 하단 밴드 카드 placeOutboundCards. 예외는 겹침(최소 간격 28)과 캔버스 경계뿐이며, 정렬을 이유로 겹치게 두지 않는다. 다이아몬드(의사결정·자동 조건분기)는 중심선이 아니라 꼭짓점으로 출입하므로 이 규칙의 대상이 아니다.
정렬 기준 (대상별 표)
정렬은 한 가지 계산을 공유한다: 선행 박스 중심들의 평균에 후행 박스의 중심을 맞추고, 캔버스 가장자리에서는 여백만큼 떼며, 여백이 서로 충돌하면 왼쪽 여백을 우선한다. 단일 계산은 alignedCenterX이고, 여백·간격 상수도 client/src/features/workflow-map/ui/workflowLayout.ts 상단에만 있다 — 기준을 바꾸면 그 한 곳과 이 표를 함께 고친다.
| 대상 | 기준 | 여백·간격 | 예외 |
|---|---|---|---|
| 박스↔박스(일반 후행 L6·타 L5 카드) | 불변식: 후행 박스 중심 = 박스 선행들의 중심 평균, 수직 일직선 (라우팅 전 패스 alignBoxesToBoxCenters + 모든 점수 기반 패스 뒤 재확인 reassertBoxAlignment) | ALIGN_SIDE_MARGIN 28 · 채택 가드 ALIGN_MIN_SEPARATION 28 | 겹침·캔버스 경계면 이동하지 않는다. 재확인이 라우팅 실패를 늘리면 양보한다. 평행 분기처럼 한 축에 모두 설 수 없으면 먼저 온 하나만 서고 나머지는 행 배치를 지킨다(안전 > 정렬) |
| 호출 카드(인라인 타 L5) | 같음 — 라우팅 전에 먼저 맞춘다 | 위와 같음 | 복구 패스가 나중에 옮길 수 있다 |
| 하단 유출 카드 | 같음 + 좌→우 밀어내기, 캔버스 밖이면 다음 줄 | 28 · 카드 간격 28 | 줄 넘김 |
| 유입 밴드 카드 | 선행이 아니라 대상 단계 중심에 맞춘다(고정 4열) | INBOUND_CARD_SIDE_MARGIN 16 | 남은 폭에 맞춰 카드 폭을 줄인다 |
| 루프 펼침(확장 박스 + 안쪽 흐름) | 프레임은 컨테이너 박스와 같은 사각형(박스 안쪽 레이어). 크기는 내부 흐름 경계 + 여백(loopFrameSize, 하한 LOOP_FRAME_MIN_WIDTH 166)이고, 그 크기를 호스트 배치가 예약해 뒤 단계가 재배치된다(layout의 sizeOverrides). 펼치기/접기는 박스 우측 상단 코너의 아이콘(절대 위치, 배치 계산에 영향 없음) | 안쪽 여백 16 · 머리 LOOP_FRAME_HEADER_HEIGHT 92 · 입구 통로 16 | 박스가 최소 폭보다 좁아지지 않는다. layout()의 캔버스 폭 980은 쓰지 않는다(실측 Qualified: 166×88 → 198×474) |
| 다이아몬드(의사결정·자동 조건분기) | 중심 정렬 대상 아님(꼭짓점 출입). 출구는 꺾임 최소가 먼저(planDecisionExitPort — 분기가 둘일 때만): 선행 아래에 정렬된 분기(중심 오차 ≤ ROUTE_CLEARANCE 18)가 있으면 그중 가까운 하나가 하단 직선(0꺾임) 을 갖고, 나머지 분기는 옆면(정렬된 분기면 오른쪽)으로 돈다. 그 판정이 없으면 종전 규칙 — 후행이 박스면 좌·우, 후행이 박스가 아니면(다른 다이아몬드·합류점 = 바이패스) 아래. 좌/우의 선택 기준은 연결선이 교차하지 않는 쪽(대상이 옆에 있으면 그 쪽)이고, 관례(YES=오른쪽·NO=왼쪽)는 대상이 축에 정렬돼 어느 쪽이든 같을 때의 tie-breaker다. 같은 다이아몬드의 분기끼리는 수평 통로를 공유하지 않는다 — 한 점에서 만나는 T자 접합도 교차로 보므로, 나중 분기는 다른 통로를 찾는다 | — | 분기가 셋 이상이면 꺾임 판정을 쓰지 않고 포트 재사용·분기 간격 규칙이 우선한다. 결과 박스의 위치는 라우팅 평가로 정한다. 종류 미상이면 종전 관례 |
| 박스 출발 → 다이아몬드 도착(대상이 아래 단계) | 출발은 박스 하단 중심, 도착은 다이아몬드 상단 꼭짓점 | — | 대상이 위·옆이면 방향 우선 규칙(directionalSourceAnchor) |
| START/END | 정렬 대상 아님(유입·유출 밴드가 담당) | — | — |
| 최후 안전망 | 모든 패스 뒤 겹침 제거가 최우선 | SAFETY_MIN_SEPARATION 8 | 정렬을 되돌릴 수 있다 |
여백이 28 / 16으로 다른 이유. 두 값은 의도가 다른 두 가지다.
ALIGN_SIDE_MARGIN(28) — 카드 박스를 캔버스 가장자리에서 떼는 여백. 박스끼리 붙어 보이지 않게 하는 시각 여유다.INBOUND_CARD_SIDE_MARGIN(16) — 유입 밴드는 고정 4열 그리드라 열 수가 정해져 있고 열 간격(8)까지 한 줄에 담아야 한다. 28로 키우면 좁은 캔버스에서 카드 폭이 더 줄어 이름이 잘린다.
루프 펼침은 여백이 아니라 박스 안쪽(안쪽 여백
LOOP_FRAME_PADDING16)이다 — 캔버스 가장자리와 만나지 않으므로 이 목록에 없다.
값 통일은 별도 결정 사항이다. 지금 고정하는 것은 의도가 다르므로 값도 다르다는 사실이고, 값을 바꾸려면 이 표와 구현 상수를 같은 커밋에서 함께 고친다.
라우팅에 실패한 저장 전이는 임의 상한으로 생략하지도, 선을 지우지도 않는다. 경로를 못 찾은 전이는 폴백 경로(출발 하단 중앙 → 중간 높이 수평 → 대상 상단 중앙)를 회색 점선으로 그리고(buildFallbackRoute, 표식 workflow-edge-fallback-<전이 id>, 라벨은 그대로 남긴다), 관리자 실패 안내(WorkflowRoutingFailures)에 전이와 실패 사유를 모아 보여준다. 마지막 폴백으로 실패한 전이에 한해 우회 1꺾임(최대 5회, MAX_DETOUR_BENDS)을 허용해 다시 그리며, 실패가 실제로 줄 때만 채택한다.
라벨은 통로를 막지 않는다. 라벨 박스는 아직 그리지 않은 다른 분기의 출발 통로 밴드(같은 출발 노드 아래 48px, LABEL_DEPARTURE_BAND_HEIGHT)에 두지 않는다 — 첫 가지 라벨이 노드 바로 아래를 차지하면 두 번째 가지는 출발 지점이 막혀 안전 경로를 못 찾고 사라진다(실측: L5 18 사업규모의 ELSE 가지).
연결선 시각 체계
결과 상태가 색·글리프를 정한다(코드 edgeVisual·edgeLabel).
| 결과 | 글리프 | 선·화살촉 | 라벨 박스 채움 | 라벨 글자 |
|---|---|---|---|---|
YES | ✓ | #3f8f5b | #e5f4e8 | #245c34 |
NO | × | #b5524d | #fff0ef | #7c2f2b |
DEFAULT | → | #466174 | #eef3f7 | #2f536c |
| 그 외(A·B·ELSE 등) | • | #7659a5 | #f4effa | #56327d |
| 선 종류 | 굵기 | 점선 | 색 | 표식(testid) |
|---|---|---|---|---|
| 일반 전이 | 2 | 실선 | 결과 색 | workflow-edge-label-<전이 id> |
| 외부 유입 화살표 | 2.2 | 5 3 | 결과 색 — A/ELSE=보라, DEFAULT=청회색, Y=초록, N=빨강 | workflow-inbound-arrow-<전이 id> |
| 유입에서 이어지는 첫 내부 간선 | 3 | 실선 | #7659a5(보라) | workflow-inbound-successor-edge-<전이 id> |
| 인계(타 L5) 합성 간선 | 2 | 실선 | 결과 색(실제 행과 동일) | workflow-handoff-edge-<인계 id> |
| 라우팅 실패 폴백 | 2 | 6 4 | #9aa7b4(회색) | workflow-edge-fallback-<전이 id> |
화살촉은 선과 같은 색의 삼각형이며 꼭짓점이 대상 엔티티 경계에 정확히 닿는다.
| 라벨 규칙 | 내용 |
|---|---|
YES·NO | 글리프와 함께 Y / N 만 표시한다(사용자 라벨 텍스트는 쓰지 않는다). |
| 그 외 결과 | 사용자 라벨이 있으면 라벨, 없으면 결과 문자열(A·ELSE 등). |
DEFAULT | 라벨 텍스트가 있을 때만 박스를 그린다 — 없으면 박스를 그리지 않는다. |
| 복귀 이어짐 | 호출 카드에서 나가는 간선의 라벨을 복귀로 덮어쓴다. |
| 외부 유입 출발 라벨 | 유입 화살표가 2건 이상이거나 같은 출발 L5에서 여러 건일 때만 그린다(흰 박스·#9fafc0 테두리). |
| 위치 | 엔티티·다른 선·다른 라벨과 겹치지 않는 위치만 쓴다. |
라벨, 화살표, 캔버스 규칙
연결 라벨은 엔티티·연결선·다른 라벨과 겹치지 않는 위치만 사용한다. 화살표는 연결선 색상과 같은 색의 삼각형이며, 꼭짓점이 대상 엔티티 경계에 정확히 닿아야 한다. 확대·축소 버튼은 제공하지 않는다. 캔버스가 가로 뷰포트보다 넓을 때만 가로 비율을 축소하고 세로 길이는 축소하지 않는다.
공통 회귀 검증 매트릭스
테스트는 다음 조합을 공통적으로 검증한다.
- START·L6·타 L5 각각에서 L6·타 L5·의사결정·조건분기로의 단일 기본 전이 저장 및 교체.
- 의사결정·조건분기에서 L6·타 L5·의사결정·조건분기로의 결과별 전이 저장 및 교체.
- N:1 인입, 일반 엔티티의 직선·1회·2~3회 상단 인입 절대 우선 및 측면 보조 인입, 의사결정 상단 우선·측면 보조 인입, 비대칭 분기, 하단 축 겹침, 장애물·라벨·기존 선 충돌, 최대 3회 굽힘 경계.
- 노드 내부 관통 금지, 라벨 충돌 금지, 화살촉 경계·색상 일치, 실패 전이 가시성.
- 기존 프로세스 노드·기존 전이 데이터가 삭제되거나 자동 변환되지 않음을 검증.
이 명세는 이후 개별 사례가 추가될 때도 예외 코드를 만드는 대신, 해당 사례를 위 매트릭스의 일반 규칙 회귀 테스트로 추가하는 기준이 된다.