@flextudio/scenario 0.1.0

package/contract-data/schema/v1/control/tree.md

@@ -0,0 +1,278 @@
+# Tree
+
+> 공식 가이드: <https://docs.flextudio.com/flextudio/scenario/component/control/tree>
+
+계층형(부모-자식) 데이터를 트리 구조로 표시. `NodeId` / `ParentId` 로 **flat array** 의 부모-자식 관계를 표현한다.
+
+## 스키마
+
+`control/tree.schema.json` — `controlBase` + 분기 키.
+
+## 필수 / 핵심 속성
+
+| 속성 | 필수 | 설명 |
+|---|---|---|
+| `DataSourceName` | ★ | 트리 데이터 DataSource 이름. Fixed/Collection/Service/API 모두 가능. |
+| `NodeId` | ★ | 각 노드 고유 ID 필드명 (DataSource Items 의 키 이름). |
+| `ParentId` | ★ | 부모 노드 ID 필드명. 루트는 `''` / `null` / `undefined` / 자기참조(`parentId===nodeId`). |
+| `Title` | ★ | 노드 표시 텍스트 필드명. |
+| `SubTitle` | | (선택) 노드 부제목 필드명. |
+| `Icon` | | (선택) 노드 아이콘 필드명. |
+| `UseExpandAll` | | 초기 전체 펼침. default=false. |
+| `UseSearchBar` | | 검색바 표시. default=false. |
+| `UseMultiData` | | 다중 선택 모드 (체크박스). default=false. |
+| `UseSelectAllData` | | '전체선택' 체크박스 표시 (UseMultiData=true 일 때). default=false. |
+| `UseParentAutoSelect` | | 자식 전체 체크 시 부모 자동 체크 (UseMultiData=true 일 때). default=true. |
+| `CategoryName` | | 다중 선택 모드에서 체크된 노드가 저장되는 카테고리. |
+| `CollectionMapper` | | `{ MapperOrder, 대상Ckey: 원본필드, ... }` 매핑. |
+| `Ckeys` | | 단일 선택 시 부모 카테고리, 다중 선택 시 CategoryName 의 키. |
+
+> **CRITICAL — 필드명 일치:** DataSource Items 의 키 이름과 Tree 컨트롤의 `NodeId` / `ParentId` / `Title` 값이 **정확히 일치**해야 한다.
+
+## 데이터 구조 — flat array
+
+DataSource 의 Items 는 **계층 정보를 가진 평탄(flat) 객체 배열**. 각 row 가 한 노드이고 `ParentId` 값으로 부모-자식 관계를 표현. 엔진(`public/engine/control/tree.js`) 진실원본 기준.
+
+### DataSource 자체의 형태
+
+| 폼 | 엔진 처리 (`getTreeResult.init`) |
+|---|---|
+| **배열** `[ {...}, {...} ]` | 그대로 사용 (가장 일반) |
+| **단일 객체로 감싼 배열** `[ {...전체결과...} ]` (length===1) | 첫 원소로 자동 unwrap (`data = data[0]`) — Service 응답이 한 번 더 감싼 경우 대응 |
+| **JSON 문자열** | `changeObjStrToObject()` 로 자동 parse |
+| 비어있음 / null | 렌더 skip — 에러 없이 빈 트리 |
+
+배열 내부 인덱싱은 `1..N` 번호 키로 재매핑 (NodeId 가 키가 아님). 따라서 NodeId 값이 중복되어도 row 자체는 유지된다.
+
+### Items[*] (각 row) 필드 규약
+
+| 메타 키 | 데이터 필드명 (=ctrlJson 값) | 필수 | 의미 |
+|---|---|---|---|
+| `NodeId` (기본 `'NodeId'`) | 데이터 row 의 ID 필드명 | ★ 필수 | 노드 고유 식별자. **이 키가 없는 row 는 엔진이 건너뜀** (`hasOwnProperty(NodeID)` 체크). 시나리오 안에서 중복 안 되도록 권장 (다중 모드 체크박스 DOM id 충돌). |
+| `ParentId` (기본 `'ParentId'`) | row 의 부모 ID 필드명 | ★ 필수 | 부모 노드의 NodeId 값. 루트면 `''` / `null` / `undefined` / `NodeId 와 동일값` (자기참조) 중 하나. |
+| `Title` (기본 `'Title'`) | row 의 표시 텍스트 필드명 | ★ 필수 | 노드 라벨로 그려질 문자열. |
+| `SubTitle` | (선택) | — | 보조 텍스트 — Title 아래 한 줄 더. 미지정/빈문자열 시 미표시. |
+| `ThumbNail` | (선택) | — | 노드 썸네일 이미지 필드명. row 값이 URL/경로면 `<img class="img-thumbnail">` 렌더. **키 표기 `ThumbNail`** (engine const `K_THUMBNAIL='ThumbNail'` — `Thumbnail` 소문자 n 아님). |
+| `Icon` | (선택) | — | 노드 좌측 아이콘 필드명. row 값 형식에 따라 자동 분기 (아래 표). |
+| `SubIcon` | (선택) | — | 노드 우측 보조 아이콘 필드명. Icon 과 동일 형식 분기. 렌더 클래스만 `icon-sub` 로 차이 — engine const `K_SUB_ICON='SubIcon'`. |
+
+> 메타 키 (좌측) 의 값으로 **데이터의 필드명** 을 적는다. 예: `"NodeId": "nodeId"` → 엔진이 각 row 에서 `row.nodeId` 를 NodeId 값으로 사용. 데이터 필드명이 우연히 'NodeId'/'ParentId'/'Title' 이면 메타 키 자체를 생략해도 기본값으로 동작.
+
+### Icon / SubIcon — row 값 형식별 렌더 (engine `getImageHTML`)
+
+`Icon` / `SubIcon` 으로 지정한 메타 키에서 가져온 **row 값** 의 패턴에 따라 자동 분기:
+
+| row 값 형식 | 렌더 결과 | 용도 |
+|---|---|---|
+| `B_xxx` (B_ prefix) | `<div class="imgSvgMask B_xxx icon-node">` | 디자인 시스템 라인 아이콘 (SVG mask) |
+| `C_xxx` (C_ prefix) | `<img src="../public/imagesCommon/icon/C_xxx.svg">` | 컬러 아이콘 |
+| `icon` 부분 문자열 포함 (URL 형식 아님) | `<div class="imgSvgMask ... icon-node">` | 라인 아이콘 처리 (legacy 경로) |
+| `http://` / `https://` / `//` 시작 URL | `<img src="${val}" class="img-thumbnail">` | 외부 URL 이미지 |
+| 그 외 일반 문자열 | `<img src="${val}" class="img-thumbnail">` | 상대 경로 이미지 |
+
+`SubIcon` 만 다른 점: 컨테이너 클래스가 `icon-sub` (Icon 은 `icon-node`).
+
+### Icon / SubIcon / ThumbNail 데이터 예
+
+```jsonc
+{
+  "TreeDS": {
+    "DataSourceType": "Fixed",
+    "Items": [
+      { "nodeId": "D01", "parentId": "",    "nodeName": "본사",       "thumb": "/img/dept/hq.png",   "icon": "B_000_004", "subicon": "C_status_ok" },
+      { "nodeId": "D02", "parentId": "D01", "nodeName": "인사팀",     "thumb": "",                    "icon": "B_000_007", "subicon": "" },
+      { "nodeId": "D03", "parentId": "D01", "nodeName": "외주협력업체","thumb": "https://example.com/logo.png", "icon": "", "subicon": "C_status_pending" }
+    ]
+  }
+}
+```
+
+→ Tree 컨트롤 메타:
+```jsonc
+{
+  "ControlType": "Tree",
+  "DataSourceName": "TreeDS",
+  "NodeId":   "nodeId",
+  "ParentId": "parentId",
+  "Title":    "nodeName",
+  "ThumbNail":"thumb",
+  "Icon":     "icon",
+  "SubIcon":  "subicon"
+}
+```
+
+- `D01` 행: 좌측 라인 아이콘(`B_000_004`) + 썸네일 + 우측 컬러 아이콘.
+- `D02`: `thumb`/`subicon` 빈 문자열 → 해당 슬롯 비표시. 좌측 아이콘만 렌더.
+- `D03`: 외부 URL 썸네일 + 우측 컬러 아이콘. Icon 빈 문자열 → 좌측 아이콘 슬롯 비표시.
+
+> **빈 값(`""`/null/undefined) → 슬롯 비표시** (`getImageHTML(val)` 첫 줄 `if (!val) return ''`). row 마다 슬롯이 있어야/없어야 하는 게 아니라, 값 유무로 결정.
+
+### Root / 부모-자식 매칭 규칙 (엔진 `firstNodes` + `getNodes`)
+
+- **Root 판정**: `node[ParentId] === undefined` OR `node[ParentId] === null` OR `node[ParentId] === ''` OR `node[ParentId] === node[NodeId]` (자기참조).
+- **자식 매칭**: `String(child[ParentId]) === String(parent[NodeId])` 그리고 `child[ParentId] !== child[NodeId]` (자기참조 제외). 비교는 **문자열 변환 후** 일치 검사 — `nodeId: 1` (number) 과 `parentId: "1"` (string) 도 매칭됨.
+- 같은 부모 ID 를 가진 row 는 형제로 묶임. 정렬은 DataSource Items 순서 그대로.
+
+### 자주 발생하는 깨짐 패턴
+
+| 증상 | 원인 | 해결 |
+|---|---|---|
+| 첫 레벨(root) 만 보이고 자식이 안 보임 | 자식 row 의 `ParentId` 가 부모 row 의 `NodeId` 와 **문자열 비교에서 다름** (공백/대소문자/타입 차이 아닌 실제 다른 값) | 데이터 정합성 재확인. 엔진이 `String()` 캐스팅하므로 1 vs "1" 은 문제 없음. |
+| 일부 row 가 트리에 안 나옴 | row 에 `NodeId` 필드 누락 | row 마다 `NodeId` 가 반드시 있어야 함 — Service/Fixed 의 컬럼 누락 검토. |
+| 무한 들여쓰기 / stack overflow | `ParentId === NodeId` 가 root 가 아닌데 잘못 들어감 | root 자기참조는 1개만 허용. 비 root 노드는 다른 부모 가리켜야 함. |
+| 한 row 가 root + child 양쪽으로 등장 | 같은 `NodeId` 가 여러 row 에 존재 | NodeId 는 시나리오에서 유니크해야 함. |
+
+### 예시 — Fixed DataSource 풀폼
+
+```jsonc
+{
+  "TreeDS": {
+    "DataSourceType": "Fixed",
+    "Items": [
+      { "nodeId": "D01", "parentId": "",    "nodeName": "경영지원본부", "memo": "본부" },
+      { "nodeId": "D02", "parentId": "D01", "nodeName": "인사팀",       "memo": "팀" },
+      { "nodeId": "D03", "parentId": "D01", "nodeName": "총무팀",       "memo": "팀" },
+      { "nodeId": "D04", "parentId": "",    "nodeName": "개발본부",     "memo": "본부" },
+      { "nodeId": "D05", "parentId": "D04", "nodeName": "프론트엔드팀", "memo": "팀" }
+    ]
+  }
+}
+```
+
+→ Tree 컨트롤에서 `NodeId: "nodeId"`, `ParentId: "parentId"`, `Title: "nodeName"` 으로 매핑. `SubTitle: "memo"` 추가하면 한 줄 더 표시.
+
+> **자기참조 root 변형** — 일부 운영 데이터는 root 를 `ParentId === NodeId` (예: `D01.parentId === "D01"`) 로 표현. 엔진이 이걸 root 로 정상 인식 (line 211). `""`/`null`/누락 형태 모두 호환.
+
+> **DataSourceType 호환**: `Fixed` / `Grid` / `Collection` / `Service` / `API` 전부 동일한 flat row 형태 기대. Collection/Service 응답이 `[ { Items: [...] } ]` 처럼 한 번 더 감싸져 와도 엔진의 length===1 unwrap 으로 처리. 그 이상 중첩이면 시나리오의 데이터 변환 단계에서 평탄화 필요.
+
+## 단일 선택 모드 (Selected)
+
+노드 클릭 시 `Selected` 이벤트가 발화하고, `CollectionMapper` 로 선택된 노드 데이터가 부모 카테고리의 activeSector 에 매핑된다.
+
+```jsonc
+{
+  "ControlType": "Tree",
+  "Id": "f_tree1",
+  "ControlDefaultName": "Tree1", "ControlName2": "Tree1",
+  "Caption": "{{부서}}",
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "SizeValue": "400", "SizeUnit": "px", "MatchText": false },
+  "isColumnCtrl": false,
+  "DataSourceName": "TreeDS",
+  "NodeId": "nodeId",
+  "ParentId": "parentId",
+  "Title": "nodeName",
+  "CollectionMapper": {
+    "MapperOrder": ["selectedId", "selectedName"],
+    "selectedId": "nodeId",
+    "selectedName": "nodeName"
+  },
+  "Ckeys": ["selectedId", "selectedName"],
+  "UseExpandAll": true,
+  "UseSearchBar": true,
+  "UseEvents": true,
+  "Events": {
+    "TreeOrder": ["Selected"],
+    "Click": "",
+    "Selected": "TreeNodeSelect_E"
+  }
+}
+```
+
+> 단일 선택 시 래퍼 그룹에 `UseDataConnection: true` + `DataConnection.CategoryName` 필수 (선택값 저장 위치).
+
+## 다중 선택 모드 (Checked)
+
+`UseMultiData: true` 로 체크박스 활성화. 체크된 노드가 `CategoryName` 카테고리에 섹터로 추가/제거된다.
+
+```jsonc
+{
+  "ControlType": "Tree",
+  "Id": "f_tree1",
+  "DataSourceName": "TreeDS",
+  "NodeId": "nodeId", "ParentId": "parentId", "Title": "nodeName",
+  "UseMultiData": true,
+  "UseSelectAllData": true,
+  "UseParentAutoSelect": true,
+  "CategoryName": "CtgSelectedNodes",
+  "CollectionMapper": {
+    "MapperOrder": ["selNodeId", "selNodeName"],
+    "selNodeId": "nodeId",
+    "selNodeName": "nodeName"
+  },
+  "Ckeys": ["selNodeId", "selNodeName"],
+  "UseEvents": true,
+  "Events": {
+    "TreeOrder": ["Selected", "Checked"],
+    "Click": "",
+    "Selected": "",
+    "Checked": "TreeNodeCheck_E"
+  },
+  "isColumnCtrl": false
+}
+```
+
+> 다중 선택 모드는 Tree 자체의 `CategoryName` 으로 카테고리 관리. 래퍼 그룹의 DataConnection 은 별도 용도(표시/검색 등) 로만 사용.
+>
+> 체크 → `_collections[CategoryName].addSector(...)` / 해제 → `.remove(suid)`. 부모 노드 체크 시 모든 자식도 체크/해제 (`UseParentAutoSelect: true` 일 때).
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/treeEvents` 가 적용. **`TreeOrder`** 키 사용 (TreeEventOrder 아님 — 운영 메타에서 자주 틀리는 함정).
+
+| 이벤트 | 발화 | 모드 |
+|---|---|---|
+| `Selected` | 노드 클릭 | 단일/다중 모두 |
+| `Checked` | 체크박스 토글 | UseMultiData=true 전용 |
+
+> **CRITICAL — `Click: ""` 반드시 포함** (빈 문자열). 운영 컨벤션 — 누락 시 일부 빌드에서 동작 이상.
+>
+> **`Selected` / `Checked` PascalCase** — `SELECTED` / `CHECKED` 등 대문자 형식 금지.
+
+## `UseDCLink` — 데이터 연결고리 (운영 메타 잔존)
+
+`UseMultiData: true` + 상위 Group `UseDataConnection: true` 조합일 때만 스튜디오 프로퍼티 패널에 표시되는 사용자 수동 설정 필드. 부모 카테고리의 필드와 Tree 가 속한 컬렉션의 필드를 묶어 신규 섹터 추가 시 부모 키를 자동으로 채워준다 (property-data.js `createDCLinkGroup` 진실원본 — visibility: `meta[K.TREE.USE_MULTIDATA] && dcInfo.useData`).
+
+| 키 | 비고 |
+|---|---|
+| `UseDCLink` | boolean strict. true 면 `DCLinkCkey` 필수. ★ **AI 생성 시 미포함** — 사용자 수동 설정 전용. |
+| `DCLinkCkey.DCLinkItems[]` | `{ DCParentKey, DCChildKey }` 쌍 배열. 부모/자식 컬렉션의 필드명을 묶음. |
+
+```jsonc
+// 운영 메타 예 (참고용 — AI 생성에는 두지 말 것)
+{
+  "ControlType": "Tree",
+  "UseMultiData": true,
+  "UseDCLink": true,
+  "DCLinkCkey": {
+    "DCLinkItems": [
+      { "DCParentKey": "CompanyId", "DCChildKey": "CompanyId" }
+    ]
+  }
+}
+```
+
+DCLinkCkey 정의는 `_base.schema.json#/$defs/useDCLinkBlock` 의 properties 를 그대로 공유 — Calendar(InputDate 내부) / List(Search 내부) 와 동일 스키마.
+
+> **AI 생성 차단**: `UseDCLink` / `DCLinkCkey` 는 [control.md §AI 샘플 생성 금지 키](../control.md#ai-critical) 정책의 단일 진실원본 표에 등재. `AI_GEN_STRICT=1` 환경변수로 validate.mjs 가 `[ai-gen]` 태그로 차단.
+
+## reload — 래퍼 그룹 Id 사용
+
+```javascript
+f.Content('f_treeWrapGroup').reload();   // ✓ 래퍼 그룹
+f.Content('f_tree1').reload();           // ✗ 에러 — Tree 컨트롤 자체에는 reload 불가
+```
+
+## 함정
+
+- **TreeEventOrder 가 아니라 TreeOrder** — 자주 틀리는 키 이름.
+- **`Click: ""` 반드시 포함** — 빈 문자열이라도 누락 금지.
+- 이벤트 명은 PascalCase (`Selected` / `Checked`) — 대문자(`SELECTED`) 금지.
+- 단일 선택 모드에서 래퍼 그룹 `UseDataConnection: true` 필수 (선택값 저장 위치).
+- 모바일에서 Tree + 리스트를 좌우(row) 배치 금지 → 상하(column) 배치.
+- `reload()` 는 래퍼 그룹 Id — Tree 컨트롤 자체 Id 사용 금지.
+- **DataSource Items 의 필드명과 NodeId/ParentId/Title 값이 정확히 일치** — 메타의 우측 값(예: `"NodeId": "nodeId"` 의 `"nodeId"`)이 데이터 row 의 실제 키와 동일해야 함.
+- **row 에 NodeId 필드 누락 시 그 row 는 트리에 안 나타남** — 엔진이 조용히 skip (에러 없음).
+- **루트 노드 표현** — `ParentId` 가 `""` / `null` / `undefined` / `NodeId 와 동일값` 4가지 모두 OK. 일관성 위해 한 시나리오 안에서는 하나로 통일 권장.
+- **NodeId 중복 금지** — 같은 `NodeId` 가 여러 row 에 있으면 형제 매칭/체크박스 상태가 깨짐. 다중 모드 체크박스 DOM id 가 `tree<NodeId>_<treeAreaId>` 라 중복 시 첫 매치만 동작.
+- **부모-자식 비교는 String 캐스팅 후 일치** — `nodeId: 1` (number) + `parentId: "1"` (string) 은 문제 없으나, 값 자체가 다르면 (예: `"D01"` vs `"d01"`) 매칭 실패.

package/contract-data/schema/v1/control/tree.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/tree.schema.json",
+  "title": "Tree",
+  "description": "계층형(부모-자식) 데이터를 트리 구조로 표시. NodeId/ParentId 로 flat array 의 트리 관계 표현. 단일 선택(Selected) 과 다중 선택(UseMultiData=true → Checked 체크박스) 모드.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "Tree" },
+
+        "DataSourceName": { "type": "string", "description": "트리 데이터 DataSource 이름. Fixed/Collection/Service/API 모두 가능. 필수." },
+
+        "NodeId":   { "type": "string", "description": "각 노드 고유 ID 필드명 (DataSource Items 의 키 이름)." },
+        "ParentId": { "type": "string", "description": "부모 노드 ID 필드명. 루트는 ''/null/undefined 또는 자기참조(parentId===nodeId)." },
+        "Title":    { "type": "string", "description": "노드 표시 텍스트 필드명." },
+        "SubTitle": { "type": "string", "description": "(선택) 노드 부제목 필드명. Title 아래 한 줄 더." },
+
+        "ThumbNail": { "type": "string", "description": "(선택) 노드 썸네일 이미지 필드명. row 의 해당 필드값이 URL/경로면 `<img class=\"img-thumbnail\">` 렌더. 키 표기 'ThumbNail' (camelCase 'Thumbnail' 아님) — engine const K_THUMBNAIL='ThumbNail'." },
+        "Icon":      { "type": "string", "description": "(선택) 노드 좌측 아이콘 필드명. row 의 해당 필드값 형식에 따라 분기: `B_xxx`=라인 아이콘(SVG mask) / `C_xxx`=컬러 아이콘(/imagesCommon/icon/C_xxx.svg) / 'icon' 포함 문자열=라인 아이콘 / URL=이미지." },
+        "SubIcon":   { "type": "string", "description": "(선택) 노드 우측 보조 아이콘 필드명. Icon 과 동일 형식 분기. 렌더 클래스만 'icon-sub' 로 차이 — engine const K_SUB_ICON='SubIcon'." },
+
+        "UseExpandAll":        { "type": "boolean", "default": false, "description": "초기 전체 펼침." },
+        "UseSearchBar":        { "type": "boolean", "default": false, "description": "검색바 표시 — 키워드 포함 노드 조회." },
+        "UseMultiData":        { "type": "boolean", "default": false, "description": "다중 선택 모드 (체크박스). true 면 Checked 이벤트 사용 가능. ★ 프로퍼티 EDITOR_CTRL.CHECKBOX 저장 — boolean 고정." },
+        "UseSelectAllData":    { "type": "boolean", "default": false, "description": "다중 선택 모드의 '전체선택' 체크박스 표시 (UseMultiData=true 일 때)." },
+        "UseParentAutoSelect": { "type": "boolean", "default": true,  "description": "자식 노드 전체 체크 시 부모 자동 체크 (UseMultiData=true 일 때). 기본 true." },
+        "UseCondition":        { "type": "boolean", "default": false },
+
+        "TreeType": {
+          "type": "string",
+          "enum": ["Single", "UseMultiData"],
+          "description": "런타임 분류값 (engine const TREE_TYPE). 'Single'=단일 / 'UseMultiData'=다중. 일반적으로 UseMultiData boolean 으로 충분 — 운영 메타에는 명시 안 됨."
+        },
+
+        "CategoryName": {
+          "type": "string",
+          "description": "다중 선택 (UseMultiData=true) 모드에서 체크된 노드가 저장되는 카테고리. 체크 → addSector / 해제 → remove."
+        },
+
+        "CollectionMapper": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "minProperties": 1,
+          "description": "{ MapperOrder: [...], 대상Ckey: 원본필드, ... } 매핑. 단일 선택 시 activeSector 에 매핑, 다중 선택 시 CategoryName 의 섹터에 매핑. Tree 는 항상 DataSource 기반이므로 콜렉션 ↔ DataSource 필드 매핑 필수 (빈 객체 금지). ★ additionalProperties 는 자유 매핑키(값=원본필드명, string)이므로 {type:string} — true 로 두면 strict 변환이 unevaluatedProperties:false 로 뒤집어 매핑키를 오탐 차단한다 (MapperOrder 는 properties 라 array 허용).",
+          "properties": {
+            "MapperOrder": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+
+        "UseEvents": {
+          "type": "boolean",
+          "default": false,
+          "description": "이벤트 사용. true 면 Events.TreeOrder + 핸들러 등록."
+        },
+        "Events": { "$ref": "_base.schema.json#/$defs/treeEvents" },
+
+        "UseDCLink":  { "type": "boolean", "default": false, "description": "데이터 연결고리 사용. ★ AI 생성 시 미포함 — 운영 메타 잔존 필드 (UseMultiData=true + 상위 DataConnection 활성 조합에서만 스튜디오 UI 노출). useDCLinkBlock 정책 동일." },
+        "DCLinkCkey": { "$ref": "_base.schema.json#/$defs/useDCLinkBlock/properties/DCLinkCkey" }
+      },
+      "required": ["DataSourceName", "NodeId", "ParentId", "Title", "CollectionMapper"]
+    },
+    {
+      "$comment": "UseMultiData=true → CategoryName 권장 (체크된 노드가 저장될 위치). 운영 메타에 종종 누락 — 후검증/가이드 차원으로 두고 schema 강제는 안 함.",
+      "if": {
+        "properties": { "UseMultiData": { "const": true } },
+        "required": ["UseMultiData"]
+      },
+      "then": {}
+    },
+    {
+      "$comment": "UseDCLink=true 면 DCLinkCkey 필수 (useDCLinkBlock 정책).",
+      "if": {
+        "properties": { "UseDCLink": { "const": true } },
+        "required": ["UseDCLink"]
+      },
+      "then": { "required": ["DCLinkCkey"] }
+    }
+  ]
+}

package/contract-data/schema/v1/control.md

@@ -0,0 +1,264 @@
+# Control (인덱스)
+
+화면의 입력/표시 단위. v1 명시 범위는 입력류 12종 + 특수/컨테이너 5종(`Calendar`, `CalendarNavigator`, `Tab`, `Tree`, `Embed`) = 본체 17종 (Dialog 자식 전용 `ComboList`/`List` 별도), 폴더 안에 컨트롤별로 정의가 분리되어 있다. 진실원본은 `catalog.json` 의 `controlTypes`.
+
+## 컨트롤 목록 (v1)
+
+| ControlType | 스키마 | 문서 | 자식 트리 |
+|---|---|---|---|
+| `InputText` | [control/input-text.schema.json](control/input-text.schema.json) | [input-text.md](control/input-text.md) | — |
+| `InputNumber` | [control/input-number.schema.json](control/input-number.schema.json) | [input-number.md](control/input-number.md) | — |
+| `InputMask` | [control/input-mask.schema.json](control/input-mask.schema.json) | [input-mask.md](control/input-mask.md) | — |
+| `InputDate` | [control/input-date.schema.json](control/input-date.schema.json) | [input-date.md](control/input-date.md) | `Dialog…Calendar` |
+| `MultiInputBox` | [control/multi-input-box.schema.json](control/multi-input-box.schema.json) | [multi-input-box.md](control/multi-input-box.md) | — |
+| `Combo` | [control/combo.schema.json](control/combo.schema.json) | [combo.md](control/combo.md) | `Dialog…ComboList` |
+| `Search` | [control/search.schema.json](control/search.schema.json) | [search.md](control/search.md) | `Dialog…List` |
+| `CheckBox` | [control/check-box.schema.json](control/check-box.schema.json) | [check-box.md](control/check-box.md) | — |
+| `RadioBox` | [control/radio-box.schema.json](control/radio-box.schema.json) | [radio-box.md](control/radio-box.md) | — |
+| `Label` | [control/label.schema.json](control/label.schema.json) | [label.md](control/label.md) | — |
+| `ImageBox` | [control/image-box.schema.json](control/image-box.schema.json) | [image-box.md](control/image-box.md) | — (ViewGroup / EditGroup 인라인) |
+| `InputFile` | [control/input-file.schema.json](control/input-file.schema.json) | [input-file.md](control/input-file.md) | — |
+| `Button` | [control/button.schema.json](control/button.schema.json) | [button.md](control/button.md) | — |
+| `Calendar` | [control/calendar.schema.json](control/calendar.schema.json) | [calendar.md](control/calendar.md) | — (InputDate 자식 또는 Group 직접 자식 단독) |
+| `CalendarNavigator` | [control/calendar-navigator.schema.json](control/calendar-navigator.schema.json) | [calendar-navigator.md](control/calendar-navigator.md) | — |
+| `Tab` | [control/tab.schema.json](control/tab.schema.json) | [tab.md](control/tab.md) | `Tabs[*].Layouts[*]` |
+| `Tree` | [control/tree.schema.json](control/tree.schema.json) | [tree.md](control/tree.md) | — |
+| `Embed` | [control/embed.schema.json](control/embed.schema.json) | [embed.md](control/embed.md) | — |
+
+[control.schema.json](control.schema.json) 은 디스패처 (oneOf + 위 18종 + `OtherControl` fallback). [control/_base.schema.json](control/_base.schema.json) 에 공통 `controlBase` / `inputBase` / `dialogLayout` / `calendarControl` / `imageBoxViewGroup` / `imageBoxEditGroup` $defs.
+
+## 식별 규칙 (모든 컨트롤 공통)
+
+- 키: `Id` 형식 **`^f_[1-9][0-9]*$`** — `f_` + 1 이상 양의 정수. `f_0` / `f_01` / `f_abc` 불가.
+- **시나리오 전체 유일** — Group / Control / BottomButton / 자식 Calendar 의 Id 가 한 시나리오 안에서 중복 금지 (validate.mjs 후검증).
+- discriminator: `ControlType` (catalog.json `controlTypes[].value`).
+
+## 공통 필드 (controlBase)
+
+[control/_base.schema.json#/$defs/controlBase](control/_base.schema.json) 참조.
+
+| 키 | 비고 |
+|---|---|
+| `Id` | 🔴 |
+| `ControlType` | 🔴 |
+| `ControlDefaultName` | AI 생성 시 필수 |
+| `ControlName2` | **AI 생성 시 필수, ControlDefaultName 과 같은 값**. 누락 시 런타임 에러. |
+| `ControlName` | 탐색기 표시명 (선택) |
+| `Caption` | Input 계열: `{{필드명}}` 또는 `""`. Label: 내부명(=ControlDefaultName). |
+| `ControlStyle` | 스타일 식별자 |
+| `ControlKey` | `""` \| `"Required"` \| `"ReadOnly"` \| `"Hide"` \| `"Disabled"` |
+| `DataName` | 데이터 바인딩 키 |
+| `DefaultValue` | 초기값 |
+| `Placeholder` | 힌트 |
+| `Maxlength` | 최대 길이 |
+| `Ckeys` | string[] — 컬렉션 필드 바인딩 |
+| `SaveValueKey` | string — Combo/Search 에서 선택 후 저장할 주값 필드명 (`Ckeys` 중 하나). InputText 등 단일 값 컨트롤도 지원. 사용 시 조상 Group 의 DataConnection 필수 (`Ckeys` 와 동일 규칙) |
+| `isColumnCtrl` | **`const false`** — v1 컨트롤은 항상 false 강제 (Sheet 컬럼 모드는 OtherControl) |
+| `Width`, `Height` | sizeObject |
+| `FontStyle`, `BorderStyle`, `BgStyle`, `CaptionStyle` | 스타일 객체 |
+| `Padding`, `Margin` | spacing |
+| `Events` | 이벤트 핸들러 맵 (UseEvents / UseClickEvent 와 함께) |
+| `LoadScript` | 컴포넌트 로드 직전 실행 |
+| `UseAbsoluteLayout` + `AbsolutePosition` | 절대 위치 오버레이 |
+| `UseFixedSize` | 부모 Flex 안 고정 크기 |
+
+> **데이터 바인딩 규칙**: `Ckeys` / `SaveValueKey` 사용 컨트롤(`InputText` / `InputNumber` / `InputMask` / `InputDate` / `MultiInputBox` / `Combo` / `Search` / `CheckBox` / `RadioBox` / `Label` `LabelCKey` / `Button` `ButtonValueCKey`)은 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 이 반드시 있어야 한다. 직접 부모가 아닌 조상 Group 이어도 바인딩 동작.
+
+## 입력 공통 필드 (inputBase, InputText / InputNumber / InputMask / InputDate / MultiInputBox / Combo / Search)
+
+[control/_base.schema.json#/$defs/inputBase](control/_base.schema.json) 참조.
+
+| 키 | 비고 |
+|---|---|
+| `UseEvents` | 이벤트 사용 여부. `Events.InputEventOrder` + 핸들러 명과 함께. |
+| `DisplayValue` | 표시용 포맷 값 (money / Date 등). |
+| `UseValidate` | 내장 검증 사용. |
+
+지원 이벤트: `change`, `focusin`, `focusout`, `input`. (Sheet 셀 컨트롤에서는 `dblClick` 추가.)
+
+## ControlKey 상태 (제한)
+
+스키마 enum 으로 강제. LoadScript 동적 변경 시 약어(`'hid'`/`'dis'`) 통용.
+
+| 값 | 동작 | 사용 위치 |
+|---|---|---|
+| `""` | 정상 | meta + LoadScript |
+| `"Required"` | 필수 입력 — 런타임 자동 검증 | meta 만 (LoadScript 동적 변경 불가) |
+| `"ReadOnly"` | 읽기 전용 | meta + LoadScript |
+| `"Hide"` / `"hid"` | 숨김 | meta(`Hide`) + LoadScript(`hid`) |
+| `"Disabled"` / `"dis"` | 비활성 | meta(`Disabled`) + LoadScript(`dis`) |
+
+> **CRITICAL**: 필수 입력은 `"ControlKey": "Required"` 로 처리. 수동 검증 Script 작성 금지 — 런타임이 BottomButton Step 이동 시 자동 검증. Script 기반 저장이면 `f.checkRequired()` 사용.
+
+## v1 외 ControlType (OtherControl fallback)
+
+[control/other.schema.json](control/other.schema.json) — `Id` + `ControlType` 만 강제, 나머지는 `additionalProperties: true` 로 통과.
+
+해당 컨트롤: `InputBox`, `Sheet`, `TimeTable`, `Approval`, `Scheduler`, `Image`, `ComboList`(단독), `List`(단독), `Signature`, `Line` 등. 상세 schema 는 v2 후속.
+
+> `Calendar` 는 단독 사용도 자체 schema 분기로 빠져 있다 — [control/calendar.schema.json](control/calendar.schema.json) 참고 (`Calendar` standalone 은 OtherControl 이 아님).
+
+## ★ AI 샘플 생성 금지 키 (CRITICAL)
+
+AI 가 시나리오 메타를 생성할 때 **아래 키들은 생성하지 말 것**. 모두 사용자 수동 설정 / 운영 사후 설정 / PC 전용 등의 사유로 자동 생성에 적합하지 않음. 운영 메타에는 잔존할 수 있어 schema 자체는 통과시키되, validate.mjs 가 `AI_GEN_STRICT=1` 환경변수 시 `[ai-gen]` 태그로 차단.
+
+| 적용 범위 | 금지 키 | 사유 |
+|---|---|---|
+| 모든 Control + Group (Size 최소/최대) | `minWidth` / `maxWidth` / `minHeight` / `maxHeight` | 사용자 수동 설정 — AI 가 추측할 근거 없음 |
+| 모든 Control (FontStyle 자간) | `FontStyle.LetterSpacing` | 사용자 수동 미세 조정 전용 |
+| `Label` | `UseFullShape` / `UseTriming` | 사용자 수동 설정 |
+| `Label` | `TooltipType` / `TooltipText` / `TooltipCKey` | **PC 전용** — 모바일 시나리오 생성 시 부적합 (label.schema.json 에서 `not.anyOf.required` 로 schema 차단 병행) |
+| `ImageBox` (View 모드) | `DefaultViewGroup` | 운영 사후 설정 — placeholder 이미지 경로는 AI 가 추측 금지 |
+| 데이터 연결고리 (Calendar 내부 / List 내부 / Tree) | `UseDCLink` / `DCLinkCkey` | 운영 메타 잔존 필드 — 부모-자식 카테고리 매핑은 사용자 수동 설정 |
+
+> **schema 비등재 키**: `properties` 에 아예 등재하지 않은 키는 별도 정책 표가 필요 없다. 스킬 생성의 `strict_fields`(항상 ON) 가 `additionalProperties: true` 를 false 로 뒤집어 자동 reject. (운영 메타 호환을 위해 CLI 기본 경로는 통과시키지만, AI 생성 결과는 strict 검증을 쓰므로 무관.)
+
+### 적용 방식 (3-Tier)
+
+| Tier | 적용 키 | 메커니즘 |
+|---|---|---|
+| **Hard block (schema)** | Tooltip 3종 | `label.schema.json` 의 `not.anyOf.required` — 스키마 차원에서 차단. 운영 메타에도 등장 금지. |
+| **Soft guide (description + cross-check)** | 나머지 모든 키 | 각 schema 의 description 에 "★ AI 생성 시 미포함" 마커 + cross-check `checkAiGenerationForbidden` 가 `[ai-gen]` 태그로 보고. |
+
+### 실행 경로별 차이
+
+| 경로 | 모드 | 비고 |
+|---|---|---|
+| **스킬 생성** (`flex-scenario validate`) | **항상 strict — 토글 불가** | AI 생성 경로 전용이라 env 게이트 없이 무조건 차단. opts 토글도 없음 (`runAllCrossChecks` 가 `'ai-gen'` 키를 무조건 채움). |
+| **운영 메타 검증** (`node validate.mjs ...`) | env 게이트 `AI_GEN_STRICT=1` | 운영 메타 검증과 AI 생성 결과 검증을 동일 도구로 처리하기 위해 env 토글 유지. 기본 OFF — 운영 메타는 통과. |
+
+### 사용 예
+
+```bash
+# CLI — 운영 메타 검증 (기본 — AI 금지 키 무시)
+node meta-contract/validate.mjs scenario.json
+
+# CLI — AI 생성 결과 검증 (금지 키 차단)
+AI_GEN_STRICT=1 node meta-contract/validate.mjs ai-generated.json
+
+# 스킬 생성 — flex-scenario validate (항상 strict, 별도 옵션 없음)
+# flex-scenario validate <file>  → errors[].'ai-gen' 자동 포함
+```
+
+> **단일 진실원본**: 본 표가 AI 금지 키의 단일 진실원본. 새 금지 키를 추가하려면 ① 해당 schema description 에 "★ AI 생성 시 미포함" 마커 추가, ② 본 표 갱신, ③ `validate.mjs` 의 `AI_GEN_FORBIDDEN_KEYS_*` 상수 갱신 — 3 곳을 함께 손봐야 정합성 유지.
+
+## Caption 규칙
+
+- **Input 컨트롤**: 필드명 필요시 `"{{필드명}}"` (다국어), 맥락상 명확하면 `""`.
+- **Label**: Caption 은 내부명 (=`ControlDefaultName`). 화면 표시 텍스트는 `labeltext` 또는 `LabelCKey`.
+
+`CaptionStyle.CaptionPosition`:
+- `""` — 스타일이 캡션 자체 렌더 (`styleInputValueLine` 기본)
+- `"Left"` — 옆
+- `"Top"` — 위 (row 레이아웃)
+
+## 키별 입력값 제한 요약
+
+| 컨트롤 | 키 | 제한 |
+|---|---|---|
+| 모든 v1 컨트롤 | `isColumnCtrl` | `const false` |
+| `InputText` | `InputType` | enum `text` / `password` / `number` / `email` / `tel` |
+| `InputNumber` | `InputType` | enum `number` / `decimal` / `password`. 1000단위 콤마(금액) 는 `InputMask` + `InputType:"money"` 사용 |
+| `InputMask` | `InputType` | enum `hhmm` / `money` / `yyyymmdd` / `phone` |
+| `InputMask` | `MaskType` | enum `Time` / `Money` / `Date` / `Phone` |
+| `InputDate` | `DateFormat` | enum `""` / `YYYY-MM-DD` / `YYYY.MM.DD` / `YYYY/MM/DD` / `YYYY-MM` |
+| `InputDate.Dialog…Calendar` | `ControlType` | const `Calendar` |
+| `InputDate.Dialog…Calendar` | `CalendarType` | enum `dayCalendar` / `monthCalendar` / `yearCalendar` |
+| `InputDate.Dialog…Calendar` | `SelectType` | enum `SingleDate` / `FromTo` (FromTo 는 dayCalendar 전용) |
+| `Combo.Dialog…ComboList` | `ControlType` | const `ComboList` |
+| `Combo.Dialog…ComboList` | `DlgCtrlType` | const `Common` |
+| `Search.Dialog…List` | `ControlType` | const `List` |
+| `Search.Dialog…List` | `DataSourceName` | required (Search 의 List 는 항상 DataSource 기반) |
+| `CheckBox` | `ControlStyle` | enum `""` / `None` / `styleSquare` / `styleCircle` / `styleCircleGray` / `styleSwitch` / `styleIconHeart` / `styleRadius` |
+| `CheckBox` | `Items` | required, minItems 1 |
+| `CheckBox` | `DefaultValue` | **boolean strict** (`true`/`false` 만), 기본 `false` — 문자열 `"true"`/`"false"` 금지 (JS truthy 함정) |
+| `RadioBox` | `ControlStyle` | enum `""` / `None` / `styleRectangle` / `styleTab` / `stylePeriod` / `styleRadius` |
+| `Label` | `LabelType` | enum `labeltext` / `LabelCKey` |
+| `ImageBox` | `ImageBoxType` | enum `View` / `Edit` |
+| `ImageBox.ViewGroup` | `ImageSrcType` | enum `FlexFile` / `Url` / `Base64` / `Upload` |
+| `ImageBox.EditGroup` | `ImageSrcType` | const `FlexFile` (Module=`FlexFile` 고정) |
+
+## 이벤트 등록 표 (system-prompt-v2 §7.7 + 실 샘플 기반 강제)
+
+각 컨트롤은 정해진 EventOrder 키 + 정해진 이벤트 집합만 받는다. **컨트롤 종류에 따라 가능한 이벤트가 다르며**, EventOrder 배열에 이벤트를 등록하면 **동명 핸들러 키가 필수**(schema if/then 강제).
+
+스키마 분기:
+- `inputEventsFull` — InputText / MultiInputBox (4종 input 이벤트)
+- `inputEventsChangeOnly` — InputNumber / InputMask (`change` 만)
+- `dateEvents` — InputDate 의 자식 Calendar
+- `comboEvents` — Combo 의 자식 ComboList
+- `searchEvents` — Search 의 자식 List
+- `checkBoxEvents` — CheckBox
+- `directClickEvents` — RadioBox
+- `labelEvents` — Label
+- `buttonEvents` — Button
+- `groupEvents` — Group
+- `imageBoxEvents` — ImageBox (`ImageEventOrder` + `Click`)
+- `inputFileEvents` — InputFile (`InputFileOrder` + `change`)
+
+| 컨트롤 | EventOrder 키 | 지원 이벤트 | 위치 |
+|---|---|---|---|
+| `Group` | `ContentEvent` | `Click` / `ScrollEnd` | Group 본체 |
+| `InputText` | `InputEventOrder` | `change` / `input` / `focusin` / `focusout` | 본체 |
+| `MultiInputBox` | `InputEventOrder` | `change` / `input` / `focusin` / `focusout` | 본체 |
+| `InputNumber` | `InputEventOrder` | **`change` 만** | 본체 |
+| `InputMask` | `InputEventOrder` | **`change` 만** | 본체 |
+| `InputDate` | `DateOrder` | `DialogClose` | **자식 Calendar** |
+| `Combo` | `ComboOrder` | `change` / `DialogClose` | **자식 ComboList** |
+| `Search` | `SearchOrder` | `change` / `Delete` / `DialogClose` | **자식 List** |
+| `CheckBox` | `CheckBoxOrder` (선택) | `Click` | 본체 |
+| `RadioBox` | (없음 — 직접) | `Click` | 본체 |
+| `Label` | (없음 — 직접) | `Click` | 본체 (`UseClickEvent`+`Events.Click`) |
+| `Button` | (없음 — 직접) | `Click` | 본체 (`UseClickEvent`+`Events.Click`) |
+| `ImageBox` | `ImageEventOrder` | `Click` | 본체 |
+| `InputFile` | `InputFileOrder` | `change` | 본체 |
+
+> **CRITICAL — Dialog 컨트롤 이벤트 위치 (Combo / Search / InputDate):** `UseEvents` / `Events` 는 본체가 아니라 **`Dialog.Layouts[0].Controls[0]`** 안에 둬야 한다. 본체에 두면 [event] cross-check 로 차단.
+
+### EventOrder ↔ 핸들러 일치 (schema if/then 강제)
+
+EventOrder 배열에 이벤트를 등록하면 **동명 키의 핸들러가 반드시 존재**해야 한다. 예:
+
+```jsonc
+{ "InputEventOrder": ["change", "input"], "change": "E1", "input": "E2" }   // OK
+{ "InputEventOrder": ["change", "input"], "change": "E1" }                  // FAIL: input 핸들러 누락
+```
+
+### 입력 이벤트 의미 (소문자 — 런타임 규약)
+
+- `change` — 입력 완료 (Enter 키 포함). 검색 필드 + 단일 입력은 `change` 권장.
+- `input` — 키 입력마다 (실시간 필터링용). InputText / MultiInputBox 만.
+- `focusin` / `focusout` — 포커스 변경. InputText / MultiInputBox 만.
+
+> system-prompt §7.7 표는 PascalCase(`FocusIn`/`FocusOut`)로 표기되어 있으나, 런타임 메타는 모두 **소문자** 사용 — 실 샘플 기준으로 소문자 enum 강제.
+
+## 조건부 강제 (schema `if/then` + validate.mjs 후검증)
+- `Calendar.SelectType="SingleDate"` → `SingleDate` 객체 필수
+- `Calendar.SelectType="FromTo"` → `StartDate` + `EndDate` 객체 필수
+- `Calendar.CalendarType ∈ {monthCalendar, yearCalendar}` → `SelectType="SingleDate"` 만 허용
+- `InputDate.DateFormat="YYYY-MM"` ↔ 자식 `Calendar.CalendarType="monthCalendar"` (validate.mjs 후검증)
+- `ComboList.UseDataSource=true` → `DataSourceName` 필수
+- `List.UseKeywordSearch=true` → `KeywordSearchCkey` 필수
+- `RadioBox.UseDataSource=true` → `DataSourceName` 필수
+- `RadioBox.UseItemDesign=true` → `ItemDesign` 필수
+- `Label.LabelType="labeltext"` → `labeltext` 필수
+- `Label.LabelType="LabelCKey"` → `LabelCKey` 필수
+- `Label.UseMove=true` → `MoveSteps` 필수
+- `Button.UseClickEvent=true` → `Events.Click` 필수
+- `Button` 은 `UseMove` / `MoveSteps` 미지원 — `property-data.js` `button()` 진실원본에 없는 키. **AI 생성 시 두지 말 것**. (운영 메타 잔존 호환을 위해 스키마는 미정의 통과.)
+- `ImageBox.ImageBoxType="View"` → `ViewGroup` 필수
+- `ImageBox.ImageBoxType="Edit"` → `ViewGroup` + `EditGroup` 둘 다 필수
+- `ImageBox.ViewGroup.ImageSrcType="FlexFile"` → `FlexKey` + `ckey` 필수
+- `ImageBox.ViewGroup.ImageSrcType ∈ {Url, Base64}` → `ImageUrl` 필수
+- `InputFile.Attributes.UseCategory=true` → `Attributes.CategoryName` 필수
+- `Combo` / `Search` / `InputDate` 본체에 `UseEvents` / `Events` 두지 않음 — 자식 Dialog 컨트롤에만 (validate.mjs `[event]` cross-check)
+
+## 공통 함정
+
+- `ControlName2` 누락 = 런타임 에러. `ControlDefaultName` 과 같은 값으로 함께 작성.
+- `isColumnCtrl: false` 항상 명시.
+- Input 컨트롤은 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.
+- `InputDate` 의 `CalendarType` / `SelectType` 은 본체가 아니라 **자식 Calendar 컨트롤** 에 위치.
+- `Label` 의 `labeltext` 안에서는 `Load.sector` 사용 불가 — `{=Field}` 만.
+- `Combo` / `Search` 의 ComboList/List `Title` 은 **원본 데이터 필드명** (Fixed=`ItemName`, Collection=원본 Ckey, Service=서비스 반환 필드).
+- `Combo` / `Search` 의 본체에 `Events` 두지 않음 — 자식 ComboList/List 안에 둠.