@flextudio/scenario 0.1.0

package/contract-data/schema/v1/patterns/molecule/input-pair.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/patterns/molecule/input-pair.schema.json",
+  "title": "pattern.molecule.input-pair",
+  "description": "두 개의 입력 컨트롤이 가로로 나란히 50%/50% 로 배치되는 페어 (molecule). 쿼리/필터 행에 자주 쓰이는 'duo' 구조 — 예: 부서(inputCombo) + 담당자(inputSearch), 시작일(inputDate) + 종료일(inputDate), 기간(inputCombo) + 상태(inputCombo). 두 입력은 서로 다른 inputType 을 가질 수 있다 (per-item). 각 입력은 Caption(입력 위 라벨) 을 옵션으로 가질 수 있으며 Caption 유무에 따라 Height 가 68px(라벨 포함) / 44px(라벨 없음) 로 자동 결정.\n\nbgColor 가 있으면 'carded' 모드 — wrapper 에 라이트 톤 배경 + 상하 20px Margin + (8/10) Padding 이 깔리고, 두 입력은 columnGap 8px 로 모이고 border 는 radius-only(시각 hairline 없음) 가 되어 카드 안에 잠긴다. bgColor 가 없으면 'open' 모드 — wrapper 는 투명, columnGap 16px 로 더 여유 있고, 두 입력은 1px Gray4 hairline 으로 페이지 위에 또렷이 선다.\n\n[naming] inputType 식별자 + per-type 옵션 키 prefix — `inputCombo / inputSearch / inputDate`, `comboItems`, `comboDataSourceName`, `comboTitle`, `searchDataSourceName`, `searchTitle`, `searchSubTitle`, `searchKeywordCkey`, `dateFormat`, `dateSelectType`. 공통 키(`name`, `caption`, `placeholder`) 는 접두사 없음.",
+  "x-tier": "molecule",
+  "x-tags": [
+    "input",
+    "pair",
+    "duo",
+    "horizontal",
+    "filter",
+    "query-row",
+    "combo",
+    "search",
+    "date",
+    "mixed"
+  ],
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["inputOptions"],
+  "properties": {
+    "inputOptions": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "두 입력 컨트롤의 옵션 (배열 인덱스 0=왼쪽, 1=오른쪽). 각 항목이 자신의 inputType 을 가지며 서로 달라도 된다.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["inputType"],
+        "properties": {
+          "inputType": {
+            "type": "string",
+            "enum": ["inputCombo", "inputSearch", "inputDate"],
+            "description": "입력 컨트롤 종류. inputCombo=Combo(고정 Items 또는 DataSource ComboList), inputSearch=Search(DataSource 기반 Lookup List), inputDate=InputDate(Calendar Dialog)."
+          },
+          "caption": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 30,
+            "description": "입력 컨트롤 위에 표시되는 라벨 텍스트. 지정 시 Height 68px(라벨 포함), 미지정 시 44px. CaptionStyle 은 고정 (SemiBold 13 left). 다국어/바인딩 토큰 가능."
+          },
+          "placeholder": {
+            "type": "string",
+            "maxLength": 80,
+            "description": "Placeholder 텍스트. 미지정 시 빈 문자열."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40,
+            "description": "ControlName / ControlName2 (스튜디오 explorer 식별자 + 데이터 키). 미지정 시 inputType + 인덱스 기반 기본값 (ComboLeft / ComboRight, DateLeft / DateRight, SearchLeft / SearchRight)."
+          },
+          "comboItems": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 8,
+            "items": { "type": "string", "minLength": 1, "maxLength": 30 },
+            "description": "inputType=inputCombo 의 고정 항목 모드. 각 문자열이 ComboList Items[].ItemName + ItemValue 로 매핑. 8개 초과 / 동적 데이터는 comboDataSourceName 사용."
+          },
+          "comboDataSourceName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "inputType=inputCombo 의 DataSource ComboList 모드. comboItems 와 둘 중 하나 필수."
+          },
+          "comboTitle": {
+            "type": "string",
+            "minLength": 1,
+            "description": "inputType=inputCombo + comboDataSourceName 모드의 ComboList 항목 Title 필드 (선택)."
+          },
+          "searchDataSourceName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "inputType=inputSearch 일 때 필수. Dialog 내 List 의 DataSourceName."
+          },
+          "searchTitle": {
+            "type": "string",
+            "minLength": 1,
+            "description": "inputType=inputSearch 일 때 필수. List 의 항목 Title 필드 (보통 검색 결과의 표시 컬럼명)."
+          },
+          "searchSubTitle": {
+            "type": "string",
+            "description": "inputType=inputSearch 일 때 선택. List 의 SubTitle 필드."
+          },
+          "searchKeywordCkey": {
+            "type": "string",
+            "description": "inputType=inputSearch 일 때 선택. 키워드 검색 컬럼키. 지정 시 UseKeywordSearch=true 활성."
+          },
+          "dateFormat": {
+            "type": "string",
+            "enum": ["YYYY-MM-DD", "YYYY.MM.DD", "YYYY/MM/DD", "YYYY-MM"],
+            "description": "inputType=inputDate 일 때. 기본 'YYYY-MM-DD'."
+          },
+          "dateSelectType": {
+            "type": "string",
+            "enum": ["SingleDate", "FromTo"],
+            "description": "inputType=inputDate 의 캘린더 선택 모드. 기본 'SingleDate'. 시작일/종료일 페어는 두 입력 모두 SingleDate."
+          }
+        },
+        "allOf": [
+          {
+            "$comment": "inputCombo 는 comboItems 또는 comboDataSourceName 중 하나 필요.",
+            "if": {
+              "properties": { "inputType": { "const": "inputCombo" } },
+              "required": ["inputType"]
+            },
+            "then": {
+              "anyOf": [
+                { "required": ["comboItems"] },
+                { "required": ["comboDataSourceName"] }
+              ]
+            }
+          },
+          {
+            "$comment": "inputSearch 는 searchDataSourceName + searchTitle 필수.",
+            "if": {
+              "properties": { "inputType": { "const": "inputSearch" } },
+              "required": ["inputType"]
+            },
+            "then": { "required": ["searchDataSourceName", "searchTitle"] }
+          }
+        ]
+      }
+    },
+    "bgColor": {
+      "type": "string",
+      "enum": [
+        "surface",
+        "surface.subtle",
+        "surface.tag",
+        "surface.brand-soft"
+      ],
+      "description": "컨테이너 wrapper 배경 토큰 (_base.style.mjs COLOR 가족 중 surface 톤). 지정 시 wrapper 가 라이트 톤 카드형 쿼리 영역이 되며: 상하 20px Margin + (좌우 10 / 상하 8) Padding 적용, 두 입력 사이 8px gap, 입력 border 는 radius-only(시각 hairline 없음). 미지정 시 wrapper 는 투명, 입력 사이 16px gap, 입력 border 는 1px Gray4 hairline. 일반적 선택: surface.tag (Gray10), surface.subtle (Gray9)."
+    },
+    "override": {
+      "type": "object",
+      "propertyNames": { "enum": ["root", "left", "right"] },
+      "additionalProperties": { "type": "object" },
+      "description": "(L1 escape hatch) 패턴이 노출하지 않는 raw 엔진 메타데이터를 materialized 트리의 특정 노드에 deep-merge 로 주입한다. anchor 로 위치 지정 — root=외부 Group, left=좌측 입력(inputOptions[0]), right=우측 입력(inputOptions[1]). 값은 엔진 필드 패치 객체이며, 어떤 엔진 스키마에든 정의된 필드명만 검증을 통과한다(예: UseDataConnection, UseMove). 배열 필드는 deep-merge 가 아니라 통째 교체된다. 일반 케이스는 props 로 충분하므로 props 로 표현 못 하는 필드가 필요할 때만 사용.",
+      "examples": [
+        { "left": { "UseDataConnection": true } },
+        { "root": { "UseDataConnection": true } }
+      ]
+    }
+  },
+  "examples": [
+    {
+      "inputOptions": [
+        {
+          "inputType": "inputCombo",
+          "name": "duration",
+          "placeholder": "최근 3개월",
+          "comboItems": ["최근 3개월", "최근 6개월"]
+        },
+        {
+          "inputType": "inputCombo",
+          "name": "status",
+          "placeholder": "전체",
+          "comboItems": ["전체", "신청", "승인", "완료"]
+        }
+      ],
+      "bgColor": "surface.tag"
+    },
+    {
+      "inputOptions": [
+        {
+          "inputType": "inputCombo",
+          "name": "replyDept",
+          "caption": "부서선택",
+          "comboItems": [
+            "경영기획팀",
+            "IT전략팀",
+            "시설안전관리팀",
+            "영업팀",
+            "생산팀",
+            "공정개선팀",
+            "제조팀"
+          ]
+        },
+        {
+          "inputType": "inputSearch",
+          "name": "replyUser",
+          "caption": "담당자명",
+          "searchDataSourceName": "UserQuery",
+          "searchTitle": "UserName",
+          "searchKeywordCkey": "UserName"
+        }
+      ]
+    },
+    {
+      "inputOptions": [
+        {
+          "inputType": "inputDate",
+          "caption": "시작일",
+          "placeholder": "YYYY.MM.DD",
+          "dateFormat": "YYYY.MM.DD",
+          "dateSelectType": "SingleDate"
+        },
+        {
+          "inputType": "inputDate",
+          "caption": "종료일",
+          "placeholder": "YYYY.MM.DD",
+          "dateFormat": "YYYY.MM.DD",
+          "dateSelectType": "SingleDate"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,112 @@
+# Scenario
+
+`scenarioMeta` JSON 의 루트.
+
+> **호환 엔진:** flextudio 6.4.x (verified 2026-05-04, 45 시나리오 샘플 + public/engine 소스 검증). 엔진 메이저 변경(6→7) 시 v2 컨트랙트로 분리.
+>
+> **schema ↔ md 동기화:** 본 md 의 필드 표는 `scenario.schema.json` 과 1:1 일치해야 한다. schema 갱신 시 반드시 이 표도 같이 수정. ajv 가 검증하는 사실 출처는 `.schema.json` 이고, 본 md 는 사람/AI 가 읽는 가이드다.
+
+## 최상위 구조
+
+```jsonc
+{
+  "modules": {},                          // const {} 고정
+  "htmlkey": "stephtml",                  // const "stephtml" 고정
+  "ScenarioTitle": "",                    // const "" 고정 (가비지 슬롯)
+  "fScenarioName": "시나리오 이름",
+  "fConverterVersion": 1,                 // const 1 고정
+  "StartSteps": ["Step1"],                // Steps 있으면 minItems: 1
+  "Steps": {                              // ← 객체 (Map). 키가 StepId.
+    "Step1": { /* Step */ },
+    "Step2": { /* Step */ }
+  },
+  "Language": {},
+  "Events": {},
+  "ServiceBinding": {},
+  "Collections": {},                      // const {} 고정 (Ksystem 호출 시 타입 결정용 — 런타임이 채움)
+  "DataSources": {},
+  "Scenario": { "StyleURLs": [] },        // 외부 라이브러리 JS 경로 배열
+  "Panel": {                              // 6키 고정, additionalProperties: false
+    "Collection": { "Ckeys": [] },
+    "Category": {},
+    "CategoryOrder": [],
+    "Table": [],
+    "ExternalTable": [],
+    "AuthKey": []
+  },
+  "LastSavedTime": 1766022252184,         // 옵션 (스튜디오 자동 기록)
+  "FlexSQLService": {}                    // const {} 고정 (AI 생성 시)
+  // EmbedScenarioPrefix: 절대 추가 금지 (schema에서 false 로 거부)
+}
+```
+
+## 필드
+
+| 키 | 타입 / 강제 | 비고 |
+|---|---|---|
+| `modules` | **const `{}`** | 런타임 모듈 슬롯. 항상 빈 객체. |
+| `htmlkey` | **const `"stephtml"`** | 고정값. |
+| `ScenarioTitle` | **const `""`** | 가비지 슬롯. 표시명은 `fScenarioName` 사용. |
+| `fScenarioName` | string | 시나리오 표시명. |
+| `fConverterVersion` | **const `1`** | 메타 컨버터 버전. |
+| `StartSteps` | string[] | 진입 StepId 배열. **Steps가 1개 이상이면 minItems: 1 강제**. |
+| `Steps` | object (Map) | 키 = StepId (`Step[A-Za-z0-9_]+`), 값 = Step. patternProperties + additionalProperties: false. |
+| `Language` | object | 다국어 매핑 (`{{key}}` 치환 대상). |
+| `Events` | object | 이벤트 핸들러 정의. |
+| `ServiceBinding` | object | 서비스 바인딩. |
+| `Collections` | **const `{}`** | Ksystem 호출 시 타입 결정용 슬롯. 운영 메타에서는 시스템이 type 정의를 채우는 영역이라 일부 운영 메타에는 데이터 존재. **AI 생성 시 빈 객체**. 추후 AI가 직접 type 정의를 추가하는 요건이 생기면 const 해제. |
+| `DataSources` | object | Combo/RadioBox/Search용 명명 데이터소스. |
+| `Scenario` | object | `additionalProperties: false`. 현재 `StyleURLs` (string[]) 만 허용. **외부 JS 라이브러리(Chart.js, 지도 SDK 등) URL 추가 위치 — 라이브러리 로드는 `f.Script.load()` 보다 여기 등록을 우선**(정적 URL, 진입 시 자동 로드). |
+| `Panel` | object (6키 고정) | `additionalProperties: false`. 키 6개: `Collection`, `Category`, `CategoryOrder`, `Table`, `ExternalTable`, `AuthKey`. AI 생성 시 별도 키 추가 금지. 내부 값(Ckeys 배열, Category 객체 등)은 운영 메타에서 채워질 수 있으나 AI 생성 시 빈 형태. |
+| `LastSavedTime` | number | 마지막 저장 시각 (Unix timestamp ms). 스튜디오 저장 시 자동 기록 — 실 시나리오 42/45 에 존재. AI 생성 시 누락/0 허용. |
+| `FlexSQLService` | **const `{}`** | FlexSQL 서비스 이름/버전 매핑 슬롯. 코드: scenario-studio/studio-util.js:2957. 운영 메타에서는 `{NameArray, VersionMap}` 으로 채워질 수 있으나 AI 생성 시 빈 객체 고정. |
+| `EmbedScenarioPrefix` | **`false` (금지)** | 임베디드 시나리오 ID 접두사. 코드: engine/common/fquery.js:54. **AI 생성에 절대 등장 금지** (schema에서 properties: false 로 거부). |
+
+### Panel 세부 필드
+
+| 키 | 타입 | AI 생성 권장 |
+|---|---|---|
+| `Collection` | `{ Ckeys: array }` | `{ "Ckeys": [] }` |
+| `Category` | object | `{}` |
+| `CategoryOrder` | array | `[]` |
+| `Table` | array | `[]` |
+| `ExternalTable` | array | `[]` |
+| `AuthKey` | array | `[]` |
+
+## StepType / Step 식별 규칙
+
+- StepId 형식: `Step[A-Za-z0-9_]+` (예: `Step1`, `StepMain`).
+- Steps 객체의 키 자체가 StepId (별도 `StepId` 필드 없음).
+- 자세한 Step 분기는 `step.md` 참조.
+
+## 검증 요점 (Schema + Reachability 후검증)
+
+### Schema 차원
+- `Steps` 키 패턴: `^Step[1-9][0-9]*$` (예: `Step1`, `Step2`, `Step10`. **0 시작 불가, 영문/언더스코어 불가, `Step0` 도 불가**.)
+- `StartSteps` 는 **반드시 배열** (단수 `StartStep` 아님 — 단수 `StartStep` 은 StepSub의 `Protocol.StartStep` 키이며 의미가 다름).
+- Steps가 1개 이상이면 `StartSteps` 도 minItems: 1 강제.
+- `htmlkey` 누락 시 런타임 인식 실패.
+- 위 const 들 위반 시 ajv 가 잡아냄.
+
+### Reachability 후검증 (`validate.mjs`)
+- `StartSteps[*]` 는 반드시 `Steps` 의 키 중 하나.
+- `Step.Next[*]` 도 반드시 `Steps` 의 키 중 하나.
+- **모든 Step은 (StartSteps + 모든 Step.Next 합집합) 에서 정확히 1번 등장**해야 한다.
+  - 0회 = 고아 Step (진입 불가).
+  - 2회 이상 = 순환구조 또는 다중 진입 (트리 위반).
+
+이 cross-reference 규칙들은 표준 JSON Schema 로 표현 불가하므로 `validate.mjs` 의 `checkStepReachability()` 후검증 로직으로 처리한다.
+
+## 루트에 없는 필드 (혼동 방지)
+
+다음 키는 **scenarioMeta 루트에 존재하지 않으므로** 컨트랙트나 AI 생성에서 절대 추가하지 말 것:
+
+- `MetaContractVersion` — 컨트랙트 자체의 버전이지 메타 안에 들어가는 값이 아님.
+- `ScenarioId` (루트) — 루트 식별자는 따로 없음. 단, **StepSub의 자식 필드로서의 `ScenarioId`** (호출 대상 시나리오 ID) 는 `StepType: "StepSub"` 와 함께 쓰이는 정상 키.
+- `StartStep` (단수) — 루트에는 항상 **`StartSteps`(복수, 배열)**. 단수 `StartStep` 은 StepSub의 `Protocol.StartStep` 안에서만 등장 (의미: 호출할 서브 시나리오의 시작 Step).
+- `fAppJson` — 일부 운영 메타에 존재하지만 AI 생성 schema에서는 정의하지 않음 (필요시 운영 도구가 처리). `additionalProperties: true` 라 운영 메타도 통과.
+- `EmbedScenarioPrefix` — schema 에서 `false` 로 명시적 거부.
+
+## 예시
+
+`examples/simple-form.json`, `examples/nested-groups.json`, `examples/combo-with-dialog.json`.

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/scenario.schema.json",
+  "title": "Scenario",
+  "description": "flextudio scenarioMeta 루트. modules/htmlkey/ScenarioTitle/fConverterVersion/Collections 는 고정값 강제.",
+  "$comment": "Compatible flextudio engine: 6.4.x (verified against 6.4 series scenario samples and public/engine source). Engine major bump (6→7) requires new contract version (v2).",
+  "x-engineCompat": {
+    "minEngine": "6.4.0",
+    "testedAgainst": "6.4.x",
+    "verifiedSamples": "flextudio-ai-studio/scenario_sample*/*.json (45 files)",
+    "lastVerified": "2026-05-04"
+  },
+  "type": "object",
+  "required": ["Steps"],
+  "additionalProperties": true,
+  "properties": {
+
+    "modules": {
+      "description": "런타임 모듈 슬롯. 항상 빈 객체 고정.",
+      "const": {}
+    },
+
+    "htmlkey": {
+      "description": "고정값 'stephtml'.",
+      "const": "stephtml"
+    },
+
+    "ScenarioTitle": {
+      "description": "가비지 슬롯. 항상 빈 문자열 '' 고정 (실제 표시명은 fScenarioName 사용).",
+      "const": ""
+    },
+
+    "fScenarioName": {
+      "type": "string",
+      "description": "시나리오 표시명."
+    },
+
+    "fConverterVersion": {
+      "description": "메타 컨버터 버전. 1 고정.",
+      "const": 1
+    },
+
+    "StartSteps": {
+      "type": "array",
+      "description": "진입 StepId 배열. Steps가 있으면 1개 이상 필수.",
+      "items": { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+    },
+
+    "Steps": {
+      "type": "object",
+      "description": "Step 컨테이너. 키가 StepId, 값이 Step 객체.",
+      "patternProperties": {
+        "^Step[1-9][0-9]*$": { "$ref": "step.schema.json" }
+      },
+      "additionalProperties": false
+    },
+
+    "Language": {
+      "type": "object",
+      "description": "다국어 매핑 ({{key}} 치환 대상)."
+    },
+
+    "Events": {
+      "$ref": "events.schema.json",
+      "description": "시나리오 이벤트 핸들러 맵. 키=핸들러 이름, 값=Action 배열(Script/LinkedEvent/Service/API). 스킬 생성 시 Service/API 액션 금지 — [no-service] strict."
+    },
+
+    "ServiceBinding": {
+      "$ref": "service-binding.schema.json",
+      "description": "서비스 바인딩 맵. 스킬 생성 시 비어있는 객체 {} 만 허용 — [no-service] strict (`strict_no_service:true`). 운영 메타 호환을 위해 형식 정의."
+    },
+
+    "Collections": {
+      "description": "런타임 채움 슬롯. AI 생성 모드에서는 **빈 객체 const 고정** — 스튜디오가 컬렉션키 type 정의를 자동 재생성하므로 AI 는 채우지 않는다. Panel.{Category, CategoryOrder, Collection.Ckeys} 도 동일 정책.",
+      "const": {}
+    },
+
+    "DataSources": {
+      "$ref": "data-sources.schema.json",
+      "description": "명명 DataSource 모음. Combo/RadioBox/Search/Tree/MultiCheckBox/Approval/TimeTable/Scheduler 의 DataSourceName 참조 대상."
+    },
+
+    "__notes": {
+      "type": "array",
+      "description": "비대화형 생성(`flex-scenario gen`) 호출 시 모델이 자기-인터뷰 5질문에 답한 결정 가정. 사용자가 결과 JSON 만 보고도 '어떤 가정으로 만들어졌는가' 를 파악해 redirect 할 수 있게 5~7줄 권장. UI 에 표시되지 않으며 strict-fields 통과용 화이트리스트 슬롯. 진실원본: skill-guides/prompt-interview.md",
+      "items": { "type": "string", "minLength": 1 },
+      "maxItems": 12
+    },
+
+    "Scenario": {
+      "type": "object",
+      "description": "시나리오 옵션. StyleURLs 배열에 외부 JS 라이브러리(Chart.js, 지도 SDK 등) 경로 추가.",
+      "additionalProperties": false,
+      "properties": {
+        "StyleURLs": {
+          "type": "array",
+          "description": "외부 라이브러리 JS 경로 배열. 차트/지도/외부 SDK 등 사용 시 여기에 URL 추가.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+
+    "Panel": {
+      "type": "object",
+      "description": "데이터 모델 슬롯. 키 6개 고정 — AI 생성 시 별도 키 추가 금지. 각 슬롯의 내부 값(Ckeys 배열, Category 객체 등)은 운영 메타에서 채워짐.",
+      "additionalProperties": false,
+      "properties": {
+        "Collection": {
+          "type": "object",
+          "description": "전역 컬렉션. AI 생성 시 { Ckeys: [] } 빈 형태. 운영 메타에서 채울 때는 `_SUID` 시스템 키 + 모든 카테고리 Ckey 합집합. 시스템 게터 (`status`/`isActive`/`length` 등) / JS 빌트인 충돌 키는 schema 차단 (단 `_SUID` 는 시스템 등록 키이므로 예외).",
+          "properties": {
+            "Ckeys": { "$ref": "naming-objects.schema.json#/$defs/ckeysArrayWithSuid" }
+          }
+        },
+        "Category":      {
+          "type": "object",
+          "description": "카테고리 정의. AI 생성 시 빈 객체. 운영 메타에서 채울 때 키(카테고리명) 는 JS 식별자 규칙 + JS 빌트인 충돌 차단 (naming-objects.categoryName).",
+          "propertyNames": { "$ref": "naming-objects.schema.json#/$defs/categoryName" }
+        },
+        "CategoryOrder": {
+          "type": "array",
+          "description": "카테고리 순서. AI 생성 시 빈 배열. Category 키 집합과 정확히 일치해야 함 (validator).",
+          "items": { "$ref": "naming-objects.schema.json#/$defs/categoryName" }
+        },
+        "Table":         { "type": "array",  "description": "AI 생성 시 빈 배열." },
+        "ExternalTable": { "type": "array",  "description": "AI 생성 시 빈 배열." },
+        "AuthKey":       { "type": "array", "maxItems": 0, "description": "★ AI 생성 시 반드시 빈 배열 `[]` — 권한키는 사용자 수동 설정 전용 (schema 레벨 maxItems:0 로 차단)." }
+      }
+    },
+
+    "LastSavedTime": {
+      "type": "number",
+      "description": "마지막 저장 시각 (Unix timestamp, milliseconds). 스튜디오 저장 시 자동 기록 — 실 시나리오 42/45 에 존재. AI 생성 시 누락/0 허용."
+    },
+
+    "FlexSQLService": {
+      "description": "FlexSQL 서비스 이름/버전 매핑 슬롯(getFlexSQLServiceList). 운영 메타에서는 {NameArray, VersionMap} 으로 채워질 수 있으나, AI 생성 시 빈 객체 고정.",
+      "const": {}
+    },
+
+    "EmbedScenarioPrefix": false
+  },
+
+  "allOf": [
+    {
+      "$comment": "Steps 가 1개 이상이면 StartSteps 도 1개 이상 필수.",
+      "if": {
+        "required": ["Steps"],
+        "properties": {
+          "Steps": { "type": "object", "minProperties": 1 }
+        }
+      },
+      "then": {
+        "required": ["StartSteps"],
+        "properties": {
+          "StartSteps": { "type": "array", "minItems": 1 }
+        }
+      }
+    }
+  ]
+}

package/contract-data/schema/v1/service/CustomSystem.md

@@ -0,0 +1,139 @@
+# CustomSystem Service (CustomSystem.schema.json) — Action='API' 와 짝
+
+사용자 정의 시스템 (외부 마이크로서비스 / 인증 시스템 / 별도 도메인 백엔드 등) 호출. 워크스페이스 콘솔에서 등록한 [API 연동 템플릿](https://docs.flextudio.com/flextudio/workspace/interface/data/api) 을 이벤트로 등록한 결과 메타.
+
+스튜디오 UI 의 **이벤트 → API 추가** 가 메타에서는 `Action: 'API'` + `SystemType: 'CustomSystem'` 으로 박힘. **`fEventKey` + `fEvent` (= docs.flextudio.com 의 "Event Config Key") 로 외부 라우팅** 정의.
+
+> **참고**: [docs.flextudio.com — API 호출](https://docs.flextudio.com/flextudio/scenario/dev-mode/event/api), [API 연동 템플릿](https://docs.flextudio.com/flextudio/workspace/interface/data/api).
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+
+각 fEvent 값은 [대체 스크립트 `{% %}`](https://docs.flextudio.com/flextudio/concept/alternative) 로 동적 치환. docs.flextudio.com 의 "Event Config Key" 항목이 본 schema 의 `fEventKey` 배열에 해당.
+
+## 1. 사용 시점
+
+- 워크스페이스 콘솔에서 등록한 CustomSystem (이름: `New_01`, `New_02`, `New_05`, ...) 으로의 라우팅.
+- Custom REST 와 차이: URL/Method 직접 노출 X. 시스템 식별자(`New_NN`) + 모듈 GUID + fEvent 매핑으로 추상화.
+- 회사 내부 마이크로서비스, 다른 시나리오 / 도메인 호출.
+
+## 2. 식별 필드
+
+| 필드 | 값 / 패턴 | 비고 |
+|---|---|---|
+| `SystemID` | `^New_[0-9]+$` | 실 샘플: `New_01`, `New_02`, `New_05` |
+| `SystemType` | `"CustomSystem"` (고정) | const |
+| `ModuleID` | GUID v4 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | 워크스페이스가 발급 |
+| `fEventKey` | string[] | 사용할 키 이름 배열 |
+| `fEvent` | { [key]: string } | 키 → 값 매핑 |
+
+## 3. fEventKey + fEvent 페어링
+
+`fEventKey` 에 나열한 키들이 `fEvent` 객체의 키와 일치해야 한다 (워크스페이스 라우팅이 fEventKey 기준으로 fEvent 값을 추출).
+
+```jsonc
+"fEventKey": ["companySeq", "memSeq", "groupSeq", "url", "mapping"],
+"fEvent": {
+  "companySeq": "{%_c.userInfo[0].companySeq%}",
+  "memSeq":     "{%_c.userInfo[0].memSeq%}",
+  "groupSeq":   "{%_c.activeGroup[0].groupSeq%}",
+  "url":        "{%_base.flextudio.serviceUrl%}",
+  "mapping":    "ideation/getmanualmembers"
+}
+```
+
+### fEvent 값 종류
+
+| 형태 | 의미 |
+|---|---|
+| 정적 문자열 (`"ideation/newideation"`) | 외부 시스템의 endpoint path 또는 라우팅 코드 |
+| `{%_base.X.Y%}` | 시스템 컨텍스트 — `_base.User`, `_base.Company`, `_base.flextudio.serviceUrl` 등 |
+| `{%_c.<Cat>[0].<field>%}` | 컬렉션 첫 섹터의 필드 |
+| `{%_c.<Cat>.activeSector.<field>%}` | 활성 섹터의 필드 |
+
+### 표준 fEventKey 항목
+
+실 샘플에서 자주 등장하는 키:
+
+| 키 | 용도 |
+|---|---|
+| `url` | 외부 시스템 base URL (`{%_base.flextudio.serviceUrl%}`) |
+| `mapping` | 라우팅 path (정적 문자열, 예: `"ideation/clickend"`) |
+| `companySeq` / `fBaseCompanyID` | 회사 식별자 |
+| `memSeq` / `fBaseUserNo` | 사용자 식별자 |
+| `groupSeq` | 그룹/조직 식별자 |
+| `ideationSeq` | 기능별 도메인 키 |
+
+## 4. 형태
+
+```jsonc
+"ServiceBinding": {
+  "newIdeation": {
+    "SystemID":       "New_05",
+    "SystemType":     "CustomSystem",
+    "ModuleID":       "59f96601-69c3-411f-93b7-b0b230523fa2",
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true,
+    "NotSeperateInnerBlock": true,
+    "fEventKey":      ["url", "mapping"],
+    "fEvent": {
+      "url":     "{%_base.flextudio.serviceUrl%}",
+      "mapping": "ideation/newideation"
+    }
+  }
+}
+```
+
+## 5. Action 인라인 형태
+
+ServiceBinding 을 별도 등록하지 않고 Action 안에 인라인 박는 패턴:
+
+```jsonc
+"Events": {
+  "doStuff": [{
+    "Action": "API",
+    "ModuleID":      "13be8848-501d-4fa4-a0c7-e5a5b0bcb5e6",
+    "SystemID":      "New_05",
+    "SystemType":    "CustomSystem",
+    "UseCategory":   true,
+    "UseParamBlock": true,
+    "UseResultBlock":true,
+    "UsePKey":       true,
+    "SetCategory":   true,
+    "NotSeperateInnerBlock": true,
+    "fEventKey":     ["fBaseCompanyID", "fBaseUserNo", "url", "mapping"],
+    "fEvent": {
+      "fBaseCompanyID": "{%_base.Company.fBaseCompanyID%}",
+      "fBaseUserNo":    "{%_base.User.fBaseUserNo%}",
+      "url":            "{%_base.flextudio.serviceUrl%}",
+      "mapping":        "member/userinfo"
+    },
+    "ParamBlocks":  [],
+    "ResultBlocks": [{ "TargetType":"replace", "CategoryName":"userInfo" }]
+  }]
+}
+```
+
+`Action: 'API'` 로 적는 게 실 샘플 패턴 (CustomSystem 은 API 호출 형태로 표기).
+
+## 6. API 연동 흐름
+
+```
+[1] Action='API' SystemType='CustomSystem' → 워크스페이스 라우팅
+[2] fEventKey 의 각 키에 대해 fEvent[key] 템플릿 평가
+    (예: {%_base.flextudio.serviceUrl%} → 실제 URL 치환)
+[3] {url}/{mapping} 으로 HTTP 요청 (백엔드 자동 정의된 Method)
+[4] ParamBlocks → 요청 본문
+[5] 응답 → ResultBlocks 카테고리 반영
+```
+
+## 7. 검증 규칙 (스키마 강제)
+
+| 규칙 | 동작 |
+|---|---|
+| `SystemID` 패턴 `^New_[0-9]+$` | `New_NN` 외 거부 |
+| `SystemType === 'CustomSystem'` const | |
+| `ModuleID` GUID v4 패턴 | 잘못된 형식 거부 |
+| `fEventKey` 항목 패턴 `^[A-Za-z_][A-Za-z0-9_]*$` | 식별자 형태 |
+| `fEvent` 모든 값 string | 객체/숫자/null 금지 |
+| `fEventKey` ↔ `fEvent.keys()` 일치 | $comment — 후검증 후크 (TODO) |

package/contract-data/schema/v1/service/CustomSystem.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/CustomSystem.schema.json",
+  "title": "CustomSystem ServiceBinding",
+  "description": "API 연동 사용자 정의 시스템 호출 (외부 마이크로서비스 / 인증 시스템 등). SystemType='CustomSystem' 고정. SystemID 문자열. fEventKey + fEvent 로 외부 라우팅 정의.",
+  "type": "object",
+  "required": ["SystemID", "SystemType", "ModuleID", "fEventKey", "fEvent"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID":   {
+          "type": "string",
+          "description": "CustomSystem 식별자. (실 샘플: New_01, New_02, New_05, GUID v4 형식 식별자)."
+        },
+        "SystemType": { "const": "CustomSystem" },
+        "ModuleID":   {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+          "description": "GUID v4 형식의 모듈 식별자."
+        },
+        "fEventKey": {
+          "type": "array",
+          "minItems": 1,
+          "description": "fEvent 객체에서 사용할 키 이름 배열. 호출 시 이 키들이 실제 외부 시스템 파라미터로 전달.",
+          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
+        },
+        "fEvent": {
+          "type": "object",
+          "description": "fEventKey 의 각 키에 대응하는 실제 값. 값은 정적 문자열 또는 `{%_base.X.Y%}` / `{%_c.Cat[0].field%}` 템플릿 표현식.",
+          "additionalProperties": { "type": "string" }
+        },
+        "UsePKey":      { "type": "boolean" },
+        "UseParamBlock":{ "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" }
+      },
+      "$comment": "fEventKey 와 fEvent.keys() 가 일치해야 함은 후검증으로 처리 (TODO: [service-fevent] 추가 가능)."
+    }
+  ]
+}