@flextudio/scenario 0.1.0

package/contract-data/schema/v1/events.schema.json

@@ -0,0 +1,272 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/events.schema.json",
+  "title": "Scenario Events",
+  "description": "scenarioMeta.Events — 시나리오 레벨 이벤트 핸들러 맵. 키 패턴 `^[A-Za-z_][A-Za-z0-9_.]*$` (영문/숫자/언더스코어/점, 첫 글자는 영문/언더스코어). 값은 Action 객체 배열. Step / Group / Control / BottomButton 의 Events 안에서 핸들러 이름으로 참조한다 (validator.ts checkEventReferences 와 정합). 실 샘플 예: `Init`, `Loaded`, `Click`, `userCheck`, `getList`, `STEP1_Query_E`, `Step6Init`, `Chart.js`, `loadMapScript`. Event-Service 흐름 (Event 호출 → Service 호출 → DB 조회 → 결과를 컬렉션 카테고리에 저장 → Step 재로드) 을 코드로 표현.",
+
+  "type": "object",
+  "patternProperties": {
+    "^[A-Za-z_][A-Za-z0-9_.]*$": {
+      "type": "array",
+      "description": "Action 배열 — 위에서 아래로 순차 실행. IsSkip:true 면 그 항목 건너뜀 (디버깅 토글).",
+      "items": { "$ref": "#/$defs/eventAction" }
+    }
+  },
+  "additionalProperties": false,
+
+  "$defs": {
+    "eventAction": {
+      "title": "EventAction",
+      "description": "이벤트 한 단계의 동작 정의. `Action` discriminator 로 4분기 (Script / LinkedEvent / Service / API). 스킬 생성에서는 Script / LinkedEvent 만 허용 (Service / API 는 [no-service] 후검증으로 차단; 운영 메타 호환은 strict_no_service:false 로 비활성).",
+      "type": "object",
+      "required": ["Action"],
+      "oneOf": [
+        { "$ref": "#/$defs/scriptAction" },
+        { "$ref": "#/$defs/linkedEventAction" },
+        { "$ref": "#/$defs/serviceAction" },
+        { "$ref": "#/$defs/apiAction" }
+      ]
+    },
+
+    "scriptAction": {
+      "title": "Script Action",
+      "description": "JavaScript 한 줄/블록 실행. 가장 흔히 사용되는 액션 유형 (실 샘플 624 회). 생성 허용. 스크립트 안에서 Current.step / f.Content / Load.* / f.Date / f.Setting 등 런타임 API 호출 가능.",
+      "type": "object",
+      "required": ["Action", "Script"],
+      "additionalProperties": false,
+      "properties": {
+        "Action":        { "const": "Script" },
+        "Script":        { "type": "string", "description": "실행할 JavaScript 코드. 빈 문자열 금지 (의미 없음)." },
+        "EventName":     { "type": "string", "description": "(선택) 디버그/표시용 메모성 이름. 동작에 영향 없음." },
+        "IsSkip":        { "type": "boolean", "description": "true 면 이 단계 건너뜀 (디버깅 토글)." },
+        "isMethodClose": { "type": "boolean", "description": "(선택) 메서드 마무리 표시 — 런타임 내부용." },
+        "ResultBlocks":  { "type": "array", "description": "(선택) 결과 블록 정의 — 거의 사용 안 함. 일반 Script 에서는 비움." }
+      }
+    },
+
+    "linkedEventAction": {
+      "title": "LinkedEvent Action",
+      "description": "다른 이벤트 핸들러를 호출. EventName 은 scenarioMeta.Events 의 키 중 하나여야 함 ([event-ref] 검증). 실 샘플 239 회. 생성 허용.",
+      "type": "object",
+      "required": ["Action", "EventName"],
+      "additionalProperties": false,
+      "properties": {
+        "Action":            { "const": "LinkedEvent" },
+        "EventName":         { "type": "string", "minLength": 1, "description": "호출할 이벤트 핸들러 이름. scenarioMeta.Events 키 중 하나." },
+        "IsSkip":            { "type": "boolean" },
+        "isMethodClose":     { "type": "boolean" },
+        "Script":            { "type": "string", "description": "(선택) 호출 전 실행할 보조 스크립트. 보통 비움." },
+        "UseResultOptions":  { "type": "boolean" }
+      }
+    },
+
+    "serviceAction": {
+      "title": "Service Action",
+      "description": "ServiceBinding 항목 호출 (DB / 외부 시스템). 스킬 생성 시에는 사용 금지 — `[no-service]` 후검증이 strict (`strict_no_service:true`). 운영 메타 호환을 위해 형식만 정의. 실 샘플 116 회. ServiceBinding 필드는 string (scenario.ServiceBinding 키 참조) 또는 inline object (실 FlexSQL 패턴) 둘 다 가능.",
+      "type": "object",
+      "required": ["Action"],
+      "additionalProperties": true,
+      "properties": {
+        "Action":              { "const": "Service" },
+        "ServiceBinding":      {
+          "description": "scenarioMeta.ServiceBinding 의 키 문자열, 또는 인라인 ServiceBinding 정의 객체. 인라인 형태는 FlexSQL SQLServiceName 직접 명시 시 흔함.",
+          "oneOf": [
+            { "type": "string" },
+            { "$ref": "service-binding.schema.json#/$defs/serviceBindingEntry" }
+          ]
+        },
+        "ServiceName":         { "type": "string", "description": "(string ServiceBinding 사용 시) 서비스 이름. 인라인 ServiceBinding 사용 시 SQLServiceName 으로 식별." },
+        "SystemID":            { "type": "string", "description": "Flextudio / Other / FlexSQL / New_<ID> 등." },
+        "Version":             { "type": "number", "minimum": 1, "const": 2, "description": "프로퍼티가 숫자 저장. 고정값 2" },
+        "SetCategory":         { "type": "boolean", "description": "결과 반영 대상 카테고리 토글." },
+        "UseCategory":         { "type": "boolean" },
+        "UseInnerBlock":       { "type": "boolean" },
+        "UseParamOptions":     { "type": "boolean" },
+        "UseResultOptions":    { "type": "boolean" },
+        "ParamBlock":          {
+          "description": "(레거시) 단일 파라미터 블록. UserData / Filters 등을 직접 둠. 신 버전은 ParamBlocks 배열 사용.",
+          "$ref": "#/$defs/legacyParamBlock"
+        },
+        "ParamBlocks":         {
+          "type": "array",
+          "description": "보내는 데이터 블록 배열 — 카테고리별로 1개씩. 각 블록은 어느 카테고리의 어떤 섹터를 어떤 필터로 보낼지 정의. flextudio-guide §6.6 '서비스 보내는 데이터'.",
+          "items": { "$ref": "#/$defs/paramBlock" }
+        },
+        "ResultBlock":         {
+          "description": "(레거시) 단일 결과 블록. IsNotDelete 등.",
+          "$ref": "#/$defs/legacyResultBlock"
+        },
+        "ResultBlocks":        {
+          "type": "array",
+          "description": "받은 데이터 블록 배열 — 결과를 어느 카테고리에 어떻게 반영할지 정의 (replace/add/merge). flextudio-guide §6.6 '서비스 받은 데이터'.",
+          "items": { "$ref": "#/$defs/resultBlock" }
+        },
+        "InnerBlocks":         {
+          "type": "array",
+          "description": "받은 데이터의 중첩 배열 필드 정의 (예: 부모 row 안의 자식 list). InnerBlockKey 로 결과 객체 안의 어떤 필드가 반복 배열인지 식별.",
+          "items": { "$ref": "#/$defs/innerBlock" }
+        },
+        "Script":              { "type": "string", "description": "(선택) 서비스 호출 전/후 보조 스크립트." },
+        "IsSkip":              { "type": "boolean" },
+        "isMethodClose":       { "type": "boolean" },
+        "isResultBlocksClose": { "type": "boolean" },
+        "isBreakPoint":        { "type": "boolean" },
+        "useReflectContent":   { "type": "boolean", "description": "결과 반영 후 자동 reload 여부." }
+      }
+    },
+
+    "apiAction": {
+      "title": "API Action",
+      "description": "외부 API 호출 (FlexAutoQuery / 사용자 정의 시스템). 스킬 생성 시 사용 금지 — `[no-service]` 가 차단. 실 샘플 28 회. fEventKey + fEvent 로 외부 시스템 라우팅 정의.",
+      "type": "object",
+      "required": ["Action", "ModuleID"],
+      "additionalProperties": true,
+      "properties": {
+        "Action":              { "const": "API" },
+        "ModuleID":            { "type": "string", "description": "모듈 식별자 (FlexAutoQuery 의 경우 GUID 형태일 수 있음)." },
+        "ServiceName":         { "type": "string" },
+        "SystemID":            { "type": "string", "description": "Flextudio / Other / New_<ID> 등." },
+        "SystemType":          { "type": "string", "description": "FlexAutoQuery / CustomSystem 등." },
+        "fEvent":              {
+          "type": "object",
+          "description": "fEventKey 에 나열된 키들의 실제 값 매핑. 값은 보통 `{%_base.X.Y%}` / `{%_c.Cat[0].field%}` 등 템플릿 표현식.",
+          "additionalProperties": { "type": "string" }
+        },
+        "fEventKey":           {
+          "type": "array",
+          "description": "fEvent 객체에서 사용할 키 이름 배열. 예: ['fBaseCompanyID', 'fBaseUserNo', 'url', 'mapping'].",
+          "items": { "type": "string" }
+        },
+        "UseCategory":         { "type": "boolean" },
+        "UseParamBlock":       { "type": "boolean" },
+        "UseResultBlock":      { "type": "boolean" },
+        "UsePKey":             { "type": "boolean" },
+        "SetCategory":         { "type": "boolean", "description": "결과 반영 대상 카테고리 토글." },
+        "ParamBlocks":         { "type": "array", "items": { "$ref": "#/$defs/paramBlock" } },
+        "ResultBlocks":        { "type": "array", "items": { "$ref": "#/$defs/resultBlock" } },
+        "NotSeperateInnerBlock":{ "type": "boolean" },
+        "useReflectContent":   { "type": "boolean" }
+      }
+    },
+
+    "paramBlock": {
+      "title": "ParamBlock — 보내는 데이터 블록",
+      "description": "Service / API 호출 시 어느 카테고리의 데이터를 어떤 필터로 서버로 보낼지 정의. flextudio-guide §6.6 '서비스 보내는 데이터'. 'Event 가 Service 호출 → Service 가 DB 조회' 흐름의 Service 호출 입력.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "CategoryName": {
+          "$ref": "naming-objects.schema.json#/$defs/categoryNameOrEmpty",
+          "description": "보낼 카테고리 이름. 빈 문자열 `''` 이면 컬렉션 루트/기본 컨텍스트. UserData 만 사용할 때는 비움. JS 빌트인 충돌 키는 schema 차단."
+        },
+        "UseFilter": {
+          "type": "boolean",
+          "description": "true 면 Filters 배열로 섹터 필터링. false 면 카테고리 전체 섹터 전송."
+        },
+        "Filters": {
+          "type": "array",
+          "description": "섹터 필터링 규칙 (UseFilter:true 일 때). FilterType 별 분기는 data-objects sectorFilter 와 동일 (Status / Condition / Custom / Parent 4종).",
+          "items": { "$ref": "data-objects.schema.json#/$defs/sectorFilter" }
+        },
+        "UserData": {
+          "type": "array",
+          "description": "사용자/시스템 컨텍스트에서 직접 전송할 키 이름 배열. 예: `['CompanySeq', 'EmpSeq', 'BaseDate']` — `_base.User.<key>` / `_base.Company.<key>` 등에서 자동 매핑.",
+          "items": { "type": "string" }
+        },
+        "UserFilterOption": {
+          "type": "boolean",
+          "description": "사용자 필터 옵션 토글 (실 샘플은 모두 false). 보통 UseFilter 와 같이 쓰지 않음."
+        },
+        "ParamItems": {
+          "type": "array",
+          "description": "(레거시 / 일부 외부 시스템) 명시적 키-값 매핑 배열. 신 버전은 보통 UserData 또는 카테고리 데이터 자체 사용.",
+          "items": { "type": "object" }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "UseFilter": { "const": true } },
+            "required": ["UseFilter"]
+          },
+          "then": { "required": ["Filters"] }
+        }
+      ]
+    },
+
+    "legacyParamBlock": {
+      "title": "ParamBlock (레거시 단수형)",
+      "description": "(구버전) Service.ParamBlock — 단일 객체. 신 버전은 ParamBlocks 배열 사용. 일부 운영 메타에 잔존.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "UserData": { "type": "array", "items": { "type": "string" } },
+        "Filters":  { "type": "array", "items": { "$ref": "data-objects.schema.json#/$defs/sectorFilter" } }
+      }
+    },
+
+    "resultBlock": {
+      "title": "ResultBlock — 받은 데이터 블록",
+      "description": "Service / API 결과를 어느 카테고리에 어떻게 반영할지 정의. flextudio-guide §6.6 '서비스 받은 데이터' (화면 반영 = replace, 추가 = add, 덮어쓰기 = replace, 병합 = merge).",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "TargetType": {
+          "type": "string",
+          "enum": ["category", "replace", "add", "merge"],
+          "description": "결과 반영 방식. category=카테고리 자체 교체 / replace=섹터 전체 교체(덮어쓰기) / add=섹터 추가 / merge=PKeys 기준 병합."
+        },
+        "CategoryName": {
+          "$ref": "naming-objects.schema.json#/$defs/categoryName",
+          "description": "결과를 반영할 카테고리 이름 (예: `userInfo`, `questionList`, `pageInfo`). JS 빌트인 충돌 키는 schema 차단."
+        },
+        "PKeys": {
+          "$ref": "naming-objects.schema.json#/$defs/ckeysArray",
+          "description": "merge 모드에서 병합 키로 사용할 컬렉션 키 배열. 같은 PKey 값을 가진 섹터는 갱신, 없으면 추가. 시스템 게터 / JS 빌트인 차단."
+        },
+        "IsNotDelete": {
+          "type": "boolean",
+          "description": "true 면 기존 섹터 삭제 안 함 (replace 모드에서 누락 섹터 보존)."
+        },
+        "ResultItems": {
+          "type": "array",
+          "description": "(레거시) 명시적 결과 매핑. 보통 비움.",
+          "items": { "type": "object" }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "TargetType": { "const": "merge" } },
+            "required": ["TargetType"]
+          },
+          "then": { "required": ["PKeys"] }
+        }
+      ]
+    },
+
+    "legacyResultBlock": {
+      "title": "ResultBlock (레거시 단수형)",
+      "description": "(구버전) Service.ResultBlock — 단일 객체. 신 버전은 ResultBlocks 배열 사용.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "IsNotDelete": { "type": "boolean" }
+      }
+    },
+
+    "innerBlock": {
+      "title": "InnerBlock — 중첩 결과 배열 키",
+      "description": "결과 객체 안의 특정 필드가 자식 배열 (반복 데이터) 임을 명시. 예: 부모 schedule row 안의 dayData 배열. InnerBlockKey 로 그 필드 이름을 지정. **메타 트리의 UseInnerBlock (Group 의 자식 반복) 과는 별개 개념** — 이쪽은 Service 결과 데이터의 구조 매핑.",
+      "type": "object",
+      "required": ["InnerBlockKey"],
+      "additionalProperties": true,
+      "properties": {
+        "InnerBlockKey": {
+          "type": "string",
+          "description": "결과 객체 안의 자식 배열 필드 이름. 실 샘플: `dayData`, `scheduleData`, `WkDateList`."
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,146 @@
+# Group
+
+컨테이너 노드. `ContentsType: "Group"` 단일. 자식으로 Group 또는 Control 보유.
+
+## v1 단순화
+
+코드(`const.js`)에는 `ContentsType: "Layout"` 분기가 남아 있지만, **컨트랙트 v1 에서는 Group 단일**. Layout이 가졌던 역할(Control들의 직접 부모)은 Group이 흡수. 별도 `GroupType`/`LayoutType` 필드 없음.
+
+## 식별
+
+- 키: `Id` 형식 **`^f_[1-9][0-9]*$`** — `f_` + 1 이상 양의 정수 (자리수 무관). 예: `f_1`, `f_42`, `f_8161`. **`f_0`/`f_01`/`f_abc` 불가**.
+- **시나리오 전체 유일** — Group/Control/BottomButton 의 Id 는 한 시나리오 안에서 중복 금지. validate.mjs 의 `checkIdUniqueness()` 후검증으로 확인.
+- discriminator: `ContentsType: "Group"`
+
+## 핵심 필드
+
+| 키 | 타입 | 비고 |
+|---|---|---|
+| `Id` | string | 🔴 필수 |
+| `ContentsType` | const `"Group"` | 🔴 필수 |
+| `ContentsName` | string | 표시명 (탐색기) |
+| `ContentStyle` | string | 기본 `"None"` |
+| `Width`, `Height` | sizeObject | |
+| `UseDataConnection` | boolean | **모든 Group 에 반드시 명시 (false 라도)**. 데이터 연결 그룹은 `true` (+ DataConnection 객체), 정적/래퍼 그룹은 `false`. **키 생략 금지** — 생략하면 스튜디오가 `UseOldDataConnection:true` 를 자동 생성(레거시 렌더), `[group-dc]` 후검증이 차단. 직렬화 시 `"true"`/`"false"` 로 보일 수 있으나 데이터형은 boolean. |
+| `DataConnection` | object | UseDataConnection=true 일 때 함께 |
+| `ScrollType` | enum `""\|"ScrollY"\|"ScrollX"` | |
+| `UseEmptyView` | boolean | query 그룹 권장. `false` 면 빈 데이터 시 "값이 없습니다" 류 안내 문구 노출, `true` 면 안내 미표시. (property-data.js createUseEmptyView — SWITCH) |
+| `Padding`, `Margin` | spacing | `Btm` 키 |
+| `DisplayStyle` | object | Flex 레이아웃 |
+| `BgStyle`, `BorderStyle` | object | |
+| `UseAbsoluteLayout` | boolean | true 시 flow에서 빠짐 |
+| `AbsolutePosition` | spacing | 사용 방향만 키 포함 |
+| `UseFixedSize` | boolean | |
+| `Events` | object | Click, ScrollEnd 등 |
+| `LoadScript` | string | |
+| `Contents` | Node[] | 자식: Group \| Control |
+
+스타일 객체 상세는 `style-objects.md` 참조.
+
+## DataConnection (요약)
+
+`UseDataConnection: true` 일 때 같이:
+
+```jsonc
+"DataConnection": {
+  "TargetType": "category",
+  "DataUsage": "default" | "new" | "update" | "detail" | "query",
+  "CategoryName": "CtgXxx",
+  // DataUsage별 추가 필드:
+  //  default:       UseNewSector:true + OnlyIfNoSector:true
+  //  new:           UseNewSector:true
+  //  update/detail: UseTargetSector:true + TargetSector:{Filters:[{FilterType:"Status",Status:["active"]}]}
+  //  query:         추가 필드 없음 / (옵션) UseTargetSector:true + UseNewSector:false + Filters
+  // 상위 DataConnection 연동 (자식 Group):
+  //  new   + UseDCLink:true + DCLinkCkey.DCLinkItems[]   ← 부모 키 자동 매핑
+  //  query + UseTargetSector:true + Filters[Parent]      ← 부모 키 일치 섹터만
+}
+```
+
+- query 그룹: `UseEmptyView` 는 DataConnection 밖 Group 레벨 — `false` 시 빈 데이터 안내 문구 노출.
+- **하위 데이터 항목 콜렉션키 필수**: mock(또는 운영 데이터)을 박은 DC 그룹 하위에서 데이터가 연결되어야 하는 항목들은 콜렉션키(`LabelCKey`/`Ckeys`/`SaveValueKey` 등)로 바인딩해야 한다. 정적 텍스트만 두면 복제 카드가 같은 문구만 반복하고 데이터가 안 나옴 — [mockup-data.md](mockup-data.md) ★ 짝 규칙 / rules.md §5.6.
+  - **`[dc-empty]` 후검증이 차단**: DC 그룹의 자식 트리(중첩 DC 그룹 안쪽은 제외) 에 `LabelCKey` / `Ckeys` / `SaveValueKey` 가 단 하나도 없으면 에러. 반복 카드는 표시할 키를 라벨/입력으로 1개 이상 노출, 상세 그룹은 캡션-값 패턴의 **값 라벨에 LabelCKey** 를 박을 것. 부모-자식 DC 패턴(`FilterType:Parent`) 에서도 양쪽 모두 자체 자식에 컬렉션키가 박혀 있어야 한다.
+- boolean 키들은 직렬화 시 `"true"`/`"false"` 문자열로 보일 수 있으나 데이터형은 boolean (schema/md 모두 boolean 표기).
+- 데이터형이 애매한 키는 [property-data.js](../../../public/javascripts/scenario-studio/property-data.js) 의 `createXxx` 함수 EditControl 타입을 진실원본으로 본다.
+- 상세 분기 + 함정 카탈로그는 [data-objects.md](data-objects.md) 참조.
+
+## 자식 제약
+
+- `Contents[]` 에 Group 또는 Control. Step 자식 불가.
+- 무한 중첩 가능 — 단 불필요한 중첩은 성능 저하.
+- query 그룹에는 헤더/필터/추가버튼 같은 1번만 표시할 요소를 넣지 말 것 (그룹 자체가 복제됨). 비연결 래퍼로 분리.
+
+## Group 네비게이션 / 이벤트 (UseMove vs UseEvents)
+
+Group 도 클릭 시 Step 이동 또는 이벤트 호출 가능. UseMove 와 UseEvents 는 동시 활성화 지양 (의도 충돌). 둘은 상호배타적으로 사용.
+
+### UseMove — 클릭 시 Step 이동
+
+```jsonc
+{
+  "ContentsType": "Group",
+  "UseMove": true,
+  "MoveSteps": {
+    "MoveStepOrder": ["Step4"],
+    "Step4": { "Condition": "", "MoveTo": "Next", "Direction": "toBottom" }
+  }
+}
+```
+
+- `UseMove: true` 시 `MoveSteps` 필수 (schema 분기 강제).
+- `MoveSteps.MoveStepOrder`: 이동 대상 StepId 배열 (`^Step[1-9][0-9]*$`).
+- 각 StepId 키에 `{ Condition, MoveTo, Direction }` 옵션 객체 **동일 레벨 필수** — 누락 시 스튜디오 프로퍼티 패널 렌더 TypeError (`moveTypeCombo.value(valueObj[K.MOVETO])`). validators 의 `checkMoveStepsTargets` 가 후검증으로 잡음.
+- `MoveTo` enum: `Next` / `Prev` / `Prev_ReStart` / `Init` (group.schema.json patternProperties 강제).
+
+### UseEvents — 클릭 시 이벤트 호출
+
+```jsonc
+{
+  "ContentsType": "Group",
+  "UseEvents": true,
+  "Events": {
+    "ContentEvent": ["Click"],
+    "Click": "CardClicked_E"
+  }
+}
+```
+
+- `Events.ContentEvent` 에 `Click` / `ScrollEnd` 선언.
+- 이벤트 이름 키에 핸들러 이름 매핑.
+
+> Group / Label / Button 모두 UseMove + MoveSteps 와 Click 이벤트를 지원. Group 은 `UseEvents` + `Events.ContentEvent: ["Click"]` 패턴, Label/Button 은 `UseClickEvent` + `Events.Click` 패턴 (control.md 참조).
+
+## ★ InnerBlock — Group 메타 트리에서 사용 금지
+
+부모 섹터의 배열 필드를 자식 Group 으로 반복 렌더링하는 InnerBlock 패턴은 **AI 생성 금지** ([no-inner-block] 정책).
+
+스키마 차원에서 차단:
+
+```jsonc
+// group.schema.json
+"UseInnerBlock":  false,   // JSON Schema property false → 어떤 값이든 거부
+"InnerBlockKey":  false
+```
+
+따라서 **Group 메타에 `UseInnerBlock` / `InnerBlockKey` 키를 두면 검증 실패** — 별도 후검증 없이 생성 단계에서 차단된다.
+
+대안 패턴 (반복 렌더링이 필요할 때):
+
+| 의도 | 권장 패턴 |
+|---|---|
+| 카테고리 섹터 수만큼 반복 | `DataUsage: "query"` + `CategoryName` (DataConnection 5종 중 query) |
+| 부모 row 안의 자식 배열 표시 | 자식 배열을 별도 카테고리로 분리 + 자식 group 에 별도 query DataConnection |
+
+> **별개 개념: Service/DataSource 결과 매핑의 InnerBlock** — `events.schema.json` / `data-sources.schema.json` / `service/*` 의 `UseInnerBlock` / `InnerBlocks` / `NotSeperateInnerBlock` 은 Service 결과 데이터의 구조 매핑(부모 row 객체 안의 자식 배열 키 식별)을 위한 별개 개념. 운영 메타에서만 등장하며 `[no-service]` 와 함께 차단된다 — Group 메타 트리의 InnerBlock 과 혼동하지 말 것 (events.md §2.3.3 참조).
+
+## 함정
+
+- `reload()` 는 Group에만. Control 직접 reload 시 에러.
+- DataConnection 가진 Group 자체는 `reload()` 불가 (동일 Id 그룹 복제 문제).
+- `Padding: {}` (빈 객체) 도 허용되나, 사용 방향이 있으면 `{Btm: "10", SizeUnit: "px"}` 형태로 명시.
+- `ContentStyle: ""` 보다 `"None"` 사용.
+- **`UseDataConnection` 키 생략 금지** — 비연결 그룹도 `"UseDataConnection": false` 를 명시. 키가 없으면 스튜디오(`convertTopLevelDataConnection`)가 레거시로 간주해 `UseDataConnection:false` + **`UseOldDataConnection:true`** 를 자동 생성하고 구버전 데이터연결 프로퍼티로 렌더한다. `[group-dc]` 후검증이 차단.
+- `UseMove` 와 `UseEvents` 는 동시 활성화 지양 (의도 충돌). 클릭으로 Step 이동만 원하면 UseMove, 이벤트만 원하면 UseEvents.
+- **`Tab` 컨트롤을 감싸는(조상) Group 에는 `UseMove` 금지** — 탭 헤더 클릭이 그 Group 의 Step 이동을 트리거해 탭 전환 대신 화면이 넘어가 버린다. `[tab-move]` 후검증이 차단. 상세는 [control/tab.md](control/tab.md) "부모/형제 제약".
+- `UseInnerBlock` / `InnerBlockKey` 등장 금지 — 위 InnerBlock 섹션 참조.
+- `RepeatStyle` 은 구 메타로 v1 에서 제거. 생성 결과물에 출력 금지.

package/contract-data/schema/v1/group.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/group.schema.json",
+  "title": "Group",
+  "description": "ContentsType=\"Group\" 단일. 컨테이너 노드. 자식으로 Group | Control 보유.",
+  "$comment": "★ Group 메타 트리의 InnerBlock 반복 (UseInnerBlock / InnerBlockKey) 은 [no-inner-block] 정책으로 AI 생성 금지 — 두 키 모두 schema 값 false (어떤 값이든 거부) 로 차단. (Service/DataSource 결과 매핑의 동명 키와는 별개 개념.)",
+  "type": "object",
+  "required": ["Id", "ContentsType"],
+  "additionalProperties": true,
+
+  "properties": {
+    "Id":           { "type": "string", "pattern": "^f_[1-9][0-9]*$", "description": "f_숫자 형식. 1부터 시작, 선행 0 불가, 영문/언더스코어 불가. 시나리오 전체 유일 (validate.mjs 후검증)." },
+    "ContentsType": { "const": "Group" },
+    "ContentsName": { "type": "string" },
+    "ContentStyle": { "type": "string", "default": "None" },
+
+    "design": {
+      "$ref": "design-system/design.schema.json",
+      "description": "★ Group 스타일의 권장 short-form. verbose 한 raw 스타일 필드 대신 이 키로 배경·여백·테두리·정렬/레이아웃·그림자 등 스타일을 슬롯 이름으로 표현한다. design-system/materialize.mjs 가 검증 진입 직전에 raw 필드로 expand 하고 본 키는 결과에서 제거 — 따라서 validation 동작에는 영향 없음. 사용 가능한 슬롯·형식·enum 은 design-system/design.schema.json (Ajv 등록) 또는 DESIGN.md (get_design_rules) 참조. raw 필드와 공존 가능 — leaf 단위에서 design 이 우선."
+    },
+
+    "Width":  { "$ref": "style-objects.schema.json#/$defs/sizeObject" },
+    "Height": { "$ref": "style-objects.schema.json#/$defs/sizeObject" },
+
+    "UseDataConnection": {
+      "type": "boolean",
+      "default": false,
+      "description": "Group 의 데이터 연결 사용 여부. **모든 Group 에 반드시 명시(false 라도)** — 정적/래퍼 그룹도 false 를 명시할 것. 키를 생략하면 스튜디오가 레거시로 간주해 UseOldDataConnection:true 를 자동 생성(구버전 데이터연결 프로퍼티로 렌더) — `[group-dc]` 후검증이 누락을 차단. 데이터 연결 그룹은 true + DataConnection 객체와 함께 사용 (카테고리 섹터 수만큼 반복 렌더링 / 단일 섹터 바인딩 등 DataUsage 별 동작). ★ 프로퍼티 EDITOR_CTRL.CHECKBOX 저장 — boolean 고정."
+    },
+    "DataConnection":    { "$ref": "data-objects.schema.json#/$defs/dataConnection" },
+
+    "ScrollType":   { "type": "string", "enum": ["", "ScrollY", "ScrollX"] },
+
+    "Padding":     { "$ref": "style-objects.schema.json#/$defs/spacing" },
+    "Margin":      { "$ref": "style-objects.schema.json#/$defs/spacing" },
+    "DisplayStyle":{ "$ref": "style-objects.schema.json#/$defs/displayStyle" },
+    "BgStyle":     { "$ref": "style-objects.schema.json#/$defs/bgStyle" },
+    "BorderStyle": { "$ref": "style-objects.schema.json#/$defs/borderStyle" },
+
+    "UseAbsoluteLayout": { "type": "boolean", "default": false },
+    "AbsolutePosition":  { "$ref": "style-objects.schema.json#/$defs/absolutePosition" },
+
+    "UseFixedSize":  { "type": "boolean", "default": false },
+    "isColumnCtrl":  { "type": "boolean", "const": false, "default": false, "$comment": "★ JS truthy 회피 — boolean false 만." },
+
+    "UseOpacity":   { "type": "boolean", "default": false, "description": "투명도 사용 여부. true 일 때 OpacityValue 활성." },
+    "OpacityValue": { "type": "string", "$comment": "프로퍼티 SIZE_INPUT(unit=%) 으로 저장 — 문자열. 범위 0~100.", "description": "투명도 값. 0~100 사이 정수 문자열, 단위 % 고정. UseOpacity=true 일 때만 의미." },
+
+    "minWidth":  { "$ref": "style-objects.schema.json#/$defs/sizeObject", "description": "최소 너비. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+    "maxWidth":  { "$ref": "style-objects.schema.json#/$defs/sizeObject", "description": "최대 너비. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+    "minHeight": { "$ref": "style-objects.schema.json#/$defs/sizeObject", "description": "최소 높이. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+    "maxHeight": { "$ref": "style-objects.schema.json#/$defs/sizeObject", "description": "최대 높이. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." },
+
+    "UseMove": {
+      "type": "boolean",
+      "default": false,
+      "description": "Group 클릭 시 Step 이동 모드. true 면 MoveSteps 함께 사용. UseEvents 와 상호배타."
+    },
+    "MoveSteps": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "이동 대상 Step 정의. UseMove=true 일 때. MoveStepOrder 배열의 각 StepId 마다 동일 레벨에 옵션 객체(Condition/MoveTo/Direction 등) 슬롯이 함께 존재해야 한다",
+      "properties": {
+        "MoveStepOrder": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+        }
+      },
+      "patternProperties": {
+        "^Step[1-9][0-9]*$": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "StepId 별 이동 설정. 신규 생성 시 { Condition: '', MoveTo: 'Next' } 로 초기화.",
+          "properties": {
+            "Condition": { "type": "string", "description": "이동 조건식 (빈 문자열=무조건)." },
+            "MoveTo": {
+              "type": "string",
+              "enum": ["Next", "Prev", "Prev_ReStart", "Init"],
+              "description": "이동 동작. const.js MOVETYPE 참조 — bottom-buttons 의 None 은 Group MoveSteps 에서 사용 안 함 (이동 안 하면 UseEvents 사용)."
+            },
+            "Direction": {
+              "type": "string",
+              "description": "MoveTo='Next' 일 때 네비게이션 방향 (예: toBottom, toRight)."
+            },
+            "IsIgnoreRequired": { "type": "boolean", "description": "MoveTo='Next' 시 필수입력 검증 무시." },
+            "IsRequired":       { "type": "boolean", "description": "MoveTo='Prev'/'Prev_ReStart' 시 필수입력 보존 여부." },
+            "IsRestored":       { "type": "boolean", "description": "MoveTo='Prev'/'Prev_ReStart' 시 콜렉션 복원 여부." }
+          }
+        }
+      }
+    },
+
+    "UseEvents": {
+      "type": "boolean",
+      "default": false,
+      "description": "Group 이벤트 사용 (Click 등). UseMove 와 상호배타."
+    },
+    "Events": { "$ref": "control/_base.schema.json#/$defs/groupEvents" },
+    "LoadScript":   { "type": "string" },
+
+    "UseInnerBlock":  false,
+    "InnerBlockKey":  false,
+    "UseEmptyView": {
+      "type": "boolean",
+      "description": "빈 카테고리/query 시 빈 데이터 안내 문구 표시 여부. true 면 빈 데이터 안내 미표시, false 면 \"값이 없습니다\" 류 안내 문구 노출. query DataUsage 그룹에서 주로 사용 (DataConnection 밖 Group 레벨 키). 단일 진실원본."
+    },
+
+    "Contents": {
+      "type": "array",
+      "description": "자식 노드. Group | Control.",
+      "items": { "$ref": "node.schema.json" }
+    }
+  },
+
+  "allOf": [
+    {
+      "if": {
+        "properties": { "UseDataConnection": { "const": true } },
+        "required": ["UseDataConnection"]
+      },
+      "then": { "required": ["DataConnection"] }
+    },
+    {
+      "$comment": "UseMove=true 면 MoveSteps 필요.",
+      "if": {
+        "properties": { "UseMove": { "const": true } },
+        "required": ["UseMove"]
+      },
+      "then": { "required": ["MoveSteps"] }
+    }
+  ]
+}