@flextudio/scenario 0.1.0

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

@@ -0,0 +1,175 @@
+# InputDate
+
+날짜 입력 + 캘린더 다이얼로그. **자식 트리 보유** — 리프 아님.
+
+## 스키마
+
+`control/input-date.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="InputDate"`, `DateFormat`, `Dialog`).
+
+## 예시 (단일 일자, dayCalendar)
+
+```jsonc
+{
+  "ControlType": "InputDate",
+  "DateFormat": "YYYY-MM-DD",
+  "DisplayValue": "",
+  "Ckeys": ["AppDate"],
+  "ControlDefaultName": "InputDate1",
+  "ControlName2": "InputDate1",
+  "Caption": "{{날짜}}",
+  "Placeholder": "{{날짜 선택}}",
+  "Id": "f_34",
+  "isColumnCtrl": false,
+  "Dialog": {
+    "Layouts": [{
+      "ContentsType": "Layout",
+      "Controls": [{
+        "ControlType": "Calendar",
+        "CalendarType": "dayCalendar",
+        "SelectType": "SingleDate",
+        "SingleDate": { "Ckeys": ["AppDate"] },
+        "Id": "f_35"
+      }]
+    }]
+  }
+}
+```
+
+## InputDate 본체 제한값
+
+### `DateFormat` (제한)
+
+스키마 enum 으로 강제. 빈 문자열 `""` 은 런타임 기본 포맷.
+
+| 값 | 표시 | 짝 CalendarType |
+|---|---|---|
+| `""` | 런타임 기본 | (모든 타입) |
+| `YYYY-MM-DD` | 2026-05-06 | `dayCalendar` |
+| `YYYY.MM.DD` | 2026.05.06 | `dayCalendar` |
+| `YYYY/MM/DD` | 2026/05/06 | `dayCalendar` |
+| `YYYY-MM` | 2026-05 | `monthCalendar` |
+
+> **CalendarType 정합 cross-check (validate.mjs 후검증):**
+> - `DateFormat: "YYYY-MM"` 면 자식 Calendar 의 `CalendarType` 은 반드시 `monthCalendar`.
+> - `CalendarType: "monthCalendar"` 면 `DateFormat` 은 `""` 또는 `"YYYY-MM"` 만.
+
+## 자식 Calendar 컨트롤 (`Dialog.Layouts[*].Controls[*]`)
+
+`Dialog.Layouts[*].Controls[*]` 의 Calendar 컨트롤이 실제 캘린더 UI. **`CalendarType` / `SelectType` 은 InputDate 본체가 아니라 여기에 위치**.
+
+### 키 / 제한값
+
+| 키 | 비고 |
+|---|---|
+| `ControlType` | `"Calendar"` (const 고정) |
+| `CalendarType` | enum: `"dayCalendar"` / `"monthCalendar"` / `"yearCalendar"` |
+| `SelectType` | enum: `"SingleDate"` / `"FromTo"` |
+| `SingleDate.Ckeys` | `SelectType="SingleDate"` — 객체 자체는 항상 필수, `Ckeys` 는 조상 Group `UseDataConnection:true` 면 1개 이상·비연결이면 `[]` |
+| `StartDate.Ckeys` | `SelectType="FromTo"` — 객체 항상 필수, `Ckeys` 는 데이터연결 컨텍스트면 1개 이상·비연결이면 `[]` |
+| `EndDate.Ckeys` | `SelectType="FromTo"` — 객체 항상 필수, `Ckeys` 는 데이터연결 컨텍스트면 1개 이상·비연결이면 `[]` |
+| `Id` | `^f_[1-9][0-9]*$` — 시나리오 전체 유일 |
+
+### 스키마 if/then 강제
+
+- `SelectType="SingleDate"` → `SingleDate` **객체는 항상 필수**. `SingleDate.Ckeys` 는 **조상 Group `UseDataConnection:true` 인 데이터연결 컨텍스트에서만 1개 이상 필수**, 비연결(프로토타이핑)이면 `"Ckeys": []` 허용 (`Ckeys` 키 자체는 항상 둘 것).
+- `SelectType="FromTo"` → `StartDate` + `EndDate` **객체 모두 항상 필수**. 각 `Ckeys` 도 동일 규칙 — 데이터연결 컨텍스트면 1개 이상, 비연결이면 `[]`.
+- `CalendarType ∈ {monthCalendar, yearCalendar}` → `SelectType` 은 `SingleDate` 만 허용 (`FromTo` 는 `dayCalendar` 전용).
+
+> ★ **빈 객체 금지** (`[date]` cross-check) — `SingleDate: {}` / `StartDate: {}` / `EndDate: {}` 처럼 `Ckeys` 누락된 빈 객체는 런타임 `dlgJson.SingleDate.Ckeys` / `dlgJson.StartDate.Ckeys` / `dlgJson.EndDate.Ckeys` 접근 시 TypeError. 분기 키 객체는 항상 `Ckeys: ["..."]` 와 함께 채울 것.
+
+## CalendarType별 분기 요약
+
+| CalendarType | DateFormat | SelectType | Ckeys 위치 | 용도 |
+|---|---|---|---|---|
+| `dayCalendar` | `""` / `YYYY-MM-DD` / `YYYY.MM.DD` / `YYYY/MM/DD` | `SingleDate` 또는 `FromTo` | SingleDate.Ckeys 또는 StartDate.Ckeys + EndDate.Ckeys | 일 picker / 기간 picker |
+| `monthCalendar` | `""` 또는 `YYYY-MM` | `SingleDate` 만 | SingleDate.Ckeys | 월 picker |
+| `yearCalendar` | `""` (기본) | `SingleDate` 만 | SingleDate.Ckeys | 년 picker |
+
+### 예시 — monthCalendar (단일 월 선택)
+
+```jsonc
+{
+  "ControlType": "InputDate",
+  "DateFormat": "YYYY-MM",
+  "Ckeys": ["AppMonth"],
+  "Dialog": {
+    "Layouts": [{
+      "ContentsType": "Layout",
+      "Controls": [{
+        "ControlType": "Calendar",
+        "CalendarType": "monthCalendar",
+        "SelectType": "SingleDate",
+        "SingleDate": { "Ckeys": ["AppMonth"] },
+        "Id": "f_36"
+      }]
+    }]
+  }
+}
+```
+
+### 예시 — dayCalendar + FromTo (기간 선택)
+
+```jsonc
+{
+  "ControlType": "InputDate",
+  "DateFormat": "YYYY-MM-DD",
+  "Dialog": {
+    "Layouts": [{
+      "ContentsType": "Layout",
+      "Controls": [{
+        "ControlType": "Calendar",
+        "CalendarType": "dayCalendar",
+        "SelectType": "FromTo",
+        "StartDate": { "Ckeys": ["FromDate"] },
+        "EndDate":   { "Ckeys": ["ToDate"] },
+        "Id": "f_37"
+      }]
+    }]
+  }
+}
+```
+
+> InputDate 본체의 `Ckeys` 는 `SingleDate` 모드에서만 의미있음. `FromTo` 모드는 자식 Calendar 의 `StartDate.Ckeys` + `EndDate.Ckeys` 가 실 바인딩 키.
+
+## 데이터 바인딩
+
+`SingleDate.Ckeys` / `StartDate.Ckeys` / `EndDate.Ckeys` 는 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 이 있어야 동작 (직접 부모가 아닌 조상 Group 도 OK).
+
+InputDate 본체의 `Ckeys` 와 자식 Calendar 의 `SingleDate.Ckeys` 는 같은 필드명을 권장 (서로 동기화).
+
+## DisplayType / DisplayValue (InputDate 본체)
+
+InputDate 의 표시는 본질적으로 자식 Calendar 의 `Ckeys` + 본체 `DateFormat` 이 결정 — 본체 `DisplayValue` 는 **빈 문자열 `""`** 두는 패턴이 대다수 (DateFormat 기반 자동 표시).
+
+| 키 | 일반 패턴 |
+|---|---|
+| `DisplayType` | 생략 (default `"CtrlDisplayCkey"`). |
+| `DisplayValue` | `""` 빈 문자열 — 런타임 기본 (DateFormat 적용). |
+| `CtrlDisplayCkey` | 생략. (자식 Calendar 의 `SingleDate.Ckeys` 가 표시 필드 역할.) |
+
+선택값을 다른 표현식으로 가공하고 싶으면 `DisplayType: "DisplayValue"` + `DisplayValue: "{=Field}"` 로 명시. inputBase 의 DisplayType 두 모드는 [combo.md DisplayType 섹션](combo.md) 참조.
+
+## 이벤트 (제한)
+
+**InputDate 본체가 아니라 자식 Calendar (`Dialog.Layouts[0].Controls[0]`) 안에 둠.** 본체에 `UseEvents`/`Events` 두면 validate.mjs `[event]` cross-check 로 차단.
+
+`Events` 는 `_base.schema.json#/$defs/dateEvents` 가 적용. `DateOrder` enum: `DialogClose` 만.
+
+```jsonc
+{
+  "ControlType": "Calendar",
+  "UseEvents": true,
+  "Events": {
+    "DateOrder": ["DialogClose"],
+    "DialogClose": "ON_DATE_SELECTED"
+  }
+}
+```
+
+## 함정
+
+- **`CalendarType` 위치** — 본체가 아니라 자식 Calendar 컨트롤. 본체에 두면 무시됨.
+- `monthCalendar` 면 `DateFormat: "YYYY-MM"` 으로 맞춰야 일관됨 (validate.mjs 후검증으로 차단).
+- `FromTo` 모드는 `dayCalendar` 에서만 사용. 월/년 picker 에는 의미없음 — schema if/then 으로 차단.
+- 자식 Calendar 의 `Id` 도 시나리오 전체 유일성 검증 대상.
+- `Ckeys` 와 `SingleDate.Ckeys` 가 다르면 양쪽이 서로 다른 필드를 가리키게 되어 동기화 실패 — 같은 값 권장.

package/contract-data/schema/v1/control/input-date.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/input-date.schema.json",
+  "title": "InputDate",
+  "description": "날짜 입력 + 캘린더 다이얼로그. CalendarType / SelectType 은 InputDate 본체가 아니라 Dialog.Layouts[*].Controls[*] 의 Calendar 컨트롤에 위치. DateFormat 은 본체에 위치하며 CalendarType 과 정합되어야 한다.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "InputDate" },
+        "DateFormat": {
+          "type": "string",
+          "enum": ["", "YYYY-MM-DD", "YYYY.MM.DD", "YYYY/MM/DD", "YYYY-MM"],
+          "description": "표시 포맷. dayCalendar→YYYY-MM-DD/YYYY.MM.DD/YYYY/MM/DD, monthCalendar→YYYY-MM, yearCalendar→'' (기본). 빈 문자열은 런타임 기본 포맷."
+        },
+        "Dialog": { "$ref": "_base.schema.json#/$defs/calendarDialog" }
+      }
+    },
+    {
+      "$comment": "DateFormat='YYYY-MM' 이면 monthCalendar 와 함께 사용해야 함. Dialog 내 Calendar.CalendarType 과 정합 cross-check 는 validate.mjs 후검증 (JSON Schema 에서 Calendar.CalendarType 까지 추적하는 if/then 은 표현 가능하나 가독성 이슈로 후검증으로 분리)."
+    }
+  ]
+}

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

@@ -0,0 +1,192 @@
+# InputFile
+
+파일 첨부 컨트롤. `Module` 값으로 저장 백엔드를 결정하고 그에 맞는 `Attributes` shape 를 사용한다.
+
+## 스키마
+
+`control/input-file.schema.json` — `controlBase` + 분기 키 (`ControlType="InputFile"`, `Module`, `Title`, `Description`, `Limit`, `AllowExtensions`, `UseClickdownload`, `Attributes`, `UseEvents`, `Events`).
+
+## 필수 / 핵심 속성
+
+| 속성 | 필수 | 설명 |
+|---|---|---|
+| `ControlType` | ★ | const `"InputFile"`. |
+| `Module` | ★ | 저장 백엔드 식별 — 5종 enum. 기본 `"FlexFile"`. |
+| `Attributes` | (Module 별 분기) | 모듈별 백엔드 옵션. shape 가 `Module` 값에 의존. |
+| `Title` | | 컨트롤 제목 (식별/문서용). |
+| `Description` | | 컨트롤 설명 텍스트. |
+| `Limit` | | 업로드 제한 (개수). `0`/미설정=런타임 기본. |
+| `AllowExtensions` | | 허용 확장자 화이트리스트 (string 배열, 소문자+숫자만). 일부 모듈만 노출 (아래 표). |
+| `UseClickdownload` | | **소문자 'd' 표기** 주의 — `'UseClickdownload'` (engine const). HostingFolder 외 모듈에서 노출. |
+| `UseEvents` / `Events` | | KsystemPayPDF 외 모듈에서 사용 가능. |
+
+## Module 5종 (engine const `FILE_MODULE`)
+
+| 값 | 워크스페이스 가시성 | Attributes 핵심 키 |
+|---|---|---|
+| `"FlexFile"` | 모든 ws | `UseCategory`(기본 true) / `CategoryName` 또는 `InnerCKey` / `FlexKey.ckey` / `SharedTarget` / `Directory` |
+| `"KsystemFile"` | 모든 ws | `UseCategory`(기본 false) / `Ckeys` / `Const` / `InnerCKey` 또는 `CategoryName` |
+| `"KsystemPayPDF"` | 모든 ws | `Ckeys` / `Const` (이벤트 미지원) |
+| `"HostingFolder"` | flex / okong / hallim / bhidev | `UseCategory`(기본 true) / `CategoryName` / `FlexKey.ckey` / `FileName` / `FolderRoute` |
+| `"ServerkitFile"` | flex / okong / hallim / bhidev | `UseCategory`(기본 true) / `CategoryName` / `FlexKey.ckey` / `FileName` / `FolderRoute` |
+
+> Module 전환 시 스튜디오가 `Attributes` 를 해당 모듈의 `FILEATTR` 기본형으로 초기화 + `UseEvents`/`Events` 도 리셋.
+
+## 모듈별 옵션 가시성
+
+| 옵션 | FlexFile | KsystemFile | KsystemPayPDF | HostingFolder | ServerkitFile |
+|---|:---:|:---:|:---:|:---:|:---:|
+| `AllowExtensions` | ✓ | — | — | ✓ | ✓ |
+| `UseClickdownload` | ✓ | ✓ | ✓ | — | ✓ |
+| `UseEvents` / `Events` | ✓ | ✓ | — | ✓ | ✓ |
+| `Limit` | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+## `AllowExtensions` 규칙
+
+런타임 검증 — `/^[a-z0-9]+$/` 정규식 통과해야 하고, 차단 리스트에 없어야 함. 잘못된 값은 자동 필터링.
+
+**차단 확장자**: `exe`, `msi`, `bat`, `cmd`, `com`, `ps1`, `vbs`, `js`, `jar`, `sh`, `apk`, `dmg`, `docm`, `xlsm`, `pptm`
+
+```jsonc
+"AllowExtensions": ["jpg", "png", "pdf", "docx"]   // OK
+"AllowExtensions": ["JPG", "EXE"]                  // 런타임 필터링 — JPG 는 소문자로, EXE 는 차단 리스트라 제거됨
+```
+
+## `UseClickdownload` — 키 표기 함정
+
+```jsonc
+"UseClickdownload": true     // ✓ 진실원본 (engine const K.FILE.USE_CLICK_DOWNLOAD)
+"UseClickDownload": true     // ✗ 잘못된 표기 — 대문자 'D' 쓰지 말 것
+```
+
+소문자 'd' 가 정상. boolean strict — 문자열 `"true"`/`"false"` 금지.
+
+## 예시 — Module='FlexFile' (가장 일반)
+
+```jsonc
+{
+  "ControlType": "InputFile",
+  "Id": "f_42",
+  "ControlDefaultName": "InputFile1",
+  "ControlName2": "InputFile1",
+  "Caption": "InputFile1",
+  "Title": "사진 첨부",
+  "Description": "지원 형식: jpg, png. 최대 5장.",
+  "Module": "FlexFile",
+  "Limit": 5,
+  "AllowExtensions": ["jpg", "jpeg", "png"],
+  "UseClickdownload": true,
+  "Attributes": {
+    "UseCategory": true,
+    "CategoryName": "CtgPhotos",
+    "FlexKey": { "ckey": "PhotoKey" },
+    "SharedTarget": "tenant"
+  },
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — Module='KsystemFile'
+
+```jsonc
+{
+  "ControlType": "InputFile",
+  "Id": "f_43",
+  "ControlDefaultName": "KsysFile1",
+  "ControlName2": "KsysFile1",
+  "Caption": "KsysFile1",
+  "Module": "KsystemFile",
+  "Limit": 1,
+  "Attributes": {
+    "Ckeys": ["FileSeq"],
+    "Const": "DOC_MODULE_X",
+    "UseCategory": false,
+    "InnerCKey": "FileBlock"
+  },
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — Module='HostingFolder'
+
+```jsonc
+{
+  "ControlType": "InputFile",
+  "Id": "f_44",
+  "ControlDefaultName": "Hosting1",
+  "ControlName2": "Hosting1",
+  "Caption": "Hosting1",
+  "Module": "HostingFolder",
+  "AllowExtensions": ["pdf"],
+  "Attributes": {
+    "UseCategory": true,
+    "CategoryName": "CtgDocs",
+    "FlexKey":    { "ckey": "DocKey" },
+    "FileName":   "DocFileName",
+    "FolderRoute":"contracts/2026/"
+  },
+  "Width":  { "SizeValue": 100, "SizeUnit": "%" },
+  "Height": { "MatchText": true, "SizeValue": "" },
+  "isColumnCtrl": false
+}
+```
+
+> `FolderRoute` 는 스튜디오가 입력 시 선행/후행 슬래시를 자동 정규화해 `"foo/bar/"` 형태로 저장. 메타에 박을 때도 같은 형태 권장.
+
+## `Attributes` 키 의미
+
+| 키 | 적용 모듈 | 의미 |
+|---|---|---|
+| `UseCategory` | FlexFile / KsystemFile / HostingFolder / ServerkitFile | true=별도 카테고리 누적 / false=InnerCKey 단일 |
+| `CategoryName` | UseCategory=true 일 때 | `scenario.Panel.Category` 에 정의된 카테고리명 |
+| `InnerCKey` | UseCategory=false 일 때 | 부모 섹터의 InnerBlock 키 |
+| `Ckeys` | KsystemFile / KsystemPayPDF | 파일 시퀀스 저장 컬렉션 필드들 |
+| `Const` | KsystemFile / KsystemPayPDF | 백엔드 상수 식별자 |
+| `FlexKey` | FlexFile / HostingFolder / ServerkitFile | `{ ckey: '...' }` — 파일키 저장 필드명 |
+| `SharedTarget` | FlexFile | `"user"` (사용자 전용) / `"tenant"` (테넌트 공유, 기본) |
+| `Directory` | FlexFile (선택) | 저장 경로 디렉토리 |
+| `FileName` | HostingFolder / ServerkitFile | 저장 파일명 컬렉션 필드명 |
+| `FolderRoute` | HostingFolder / ServerkitFile | 저장 폴더 경로 (`"foo/bar/"` 형태) |
+
+## 이벤트
+
+`Events` 는 `_base.schema.json#/$defs/inputFileEvents` 적용. `InputFileOrder` 에 등록한 이벤트마다 동명 핸들러 필수 (if/then).
+
+| 이벤트 | 발화 | 비고 |
+|---|---|---|
+| `change` | 파일 추가/제거 | `EVENT_CHANGE='change'` (소문자) |
+| `Click` | 컨트롤 클릭 | `EVENT_CLICK='Click'` (대문자 C) |
+| `upload` | 업로드 완료 | `EVENT_UPLOAD='upload'` (소문자) |
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputFileOrder": ["change", "upload"],
+    "change": "ON_FILE_CHANGE_E",
+    "upload": "ON_FILE_UPLOAD_E"
+  }
+}
+```
+
+> Module='KsystemPayPDF' 에서는 스튜디오 프로퍼티 패널이 Event 섹션을 노출하지 않는다 — UseEvents/Events 두지 말 것.
+
+## 데이터 바인딩
+
+- `Attributes.FlexKey.ckey` (FlexFile / HostingFolder / ServerkitFile) 또는 `Attributes.Ckeys` (Ksystem 계열) 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.
+- `Attributes.UseCategory: true` 면 첨부 메타가 `Attributes.CategoryName` 카테고리 섹터들로 추가/삭제됨 — `scenario.Panel.Category` 에 사전 등록 필요.
+
+## 함정
+
+- `ControlName2` 누락 = 런타임 에러. `ControlDefaultName` 과 같은 값.
+- `isColumnCtrl: false` 항상 명시.
+- **`UseClickdownload` 표기** — 소문자 'd' (`UseClickDownload` 아님). 대문자로 쓰면 런타임이 인식 못 함.
+- `AllowExtensions` 값은 모두 소문자 알파벳/숫자만 — 대문자/특수문자 들어가면 런타임이 필터링.
+- Module 전환 시 `Attributes` 가 새 모듈의 기본형으로 자동 초기화되므로 이전 모듈 키가 남아있으면 운영 메타. AI 생성 시에는 Module 에 맞는 키만 채울 것.
+- `Module='KsystemPayPDF'` 는 `UseEvents`/`Events` 두지 말 것 (프로퍼티 패널 비노출).
+- `Attributes.UseCategory: true` 인데 `CategoryName` 빠뜨리면 schema if/then 차단.
+- `Attributes.FlexKey` 는 **객체** `{ ckey: '...' }` — string 으로 두지 말 것 (ImageBox.EditGroup.FlexKey 와 동일 형태).

package/contract-data/schema/v1/control/input-file.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/input-file.schema.json",
+  "title": "InputFile",
+  "description": "파일 첨부 컨트롤. Module 값에 따라 백엔드 저장 방식이 갈리고 그에 맞는 Attributes shape 가 적용된다. 공통 옵션 (Title/Description/Limit/AllowExtensions/UseClickdownload) 은 본체에, 모듈별 옵션은 Attributes 안에. property-data.js inputFile() 진실원본.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType", "Module"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    {
+      "properties": {
+        "ControlType": { "const": "InputFile" },
+
+        "Title": {
+          "type": "string",
+          "description": "컨트롤 제목 (스튜디오 프로퍼티 EDITOR_CTRL.INPUTBOX). 화면 표시용은 아니며 식별/문서용."
+        },
+        "Description": {
+          "type": "string",
+          "description": "컨트롤 설명 텍스트 (스튜디오 프로퍼티 EDITOR_CTRL.INPUTBOX)."
+        },
+
+        "Module": {
+          "type": "string",
+          "enum": ["FlexFile", "KsystemFile", "KsystemPayPDF", "HostingFolder", "ServerkitFile"],
+          "default": "FlexFile",
+          "description": "파일 저장 백엔드. ★ engine const FILE_MODULE — 'FlexFile'/'KsystemFile'/'KsystemPayPDF' 는 모든 워크스페이스, 'HostingFolder'/'ServerkitFile' 은 flex/okong/hallim/bhidev 워크스페이스에서만 노출 (스튜디오 프로퍼티 가시성). Module 변경 시 Attributes 가 해당 모듈의 FILEATTR 기본형으로 자동 초기화."
+        },
+
+        "Limit": {
+          "type": ["number", "string"],
+          "description": "업로드 제한 (개수). 프로퍼티 EDITOR_CTRL.INPUTBOX(NUMBER) — 숫자 저장 권장. 빈 문자열/0/미설정=런타임 기본."
+        },
+        "AllowExtensions": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+$" },
+          "description": "허용 확장자 화이트리스트. 소문자/숫자만 (런타임 검증: `/^[a-z0-9]+$/`). 차단 확장자: exe, msi, bat, cmd, com, ps1, vbs, js, jar, sh, apk, dmg, docm, xlsm, pptm. ★ 스튜디오 프로퍼티 가시성: Module ∈ {FlexFile, HostingFolder, ServerkitFile} 만 노출 (KsystemFile / KsystemPayPDF 는 확장자 제어 없음)."
+        },
+        "UseClickdownload": {
+          "type": "boolean",
+          "default": false,
+          "description": "★ 키 표기 'UseClickdownload' — 소문자 'd' (engine const K.FILE.USE_CLICK_DOWNLOAD='UseClickdownload'). 'UseClickDownload' 아님. true=클릭 다운로드 활성화. ★ 스튜디오 프로퍼티 가시성: Module ≠ HostingFolder 일 때 노출 (HostingFolder 는 자체 다운로드 라우팅이라 불필요)."
+        },
+
+        "Attributes": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Module 별 백엔드 속성. shape 가 Module 값에 따라 결정됨 — 아래 if/then 분기로 강제. 운영 메타에는 모듈 전환 시 이전 모듈의 키가 남아있을 수 있어 additionalProperties:true.",
+          "properties": {
+            "UseCategory":  { "type": "boolean", "default": false, "description": "true=별도 컬렉션 카테고리에 파일 메타 누적. false=Ckeys 단일 필드에 저장 (★ InnerCKey 경로는 [no-inner-block] 정책으로 차단). FILEATTR 기본값 — FlexFile/HostingFolder/ServerkitFile=true / KsystemFile=false / KsystemPayPDF=N/A." },
+            "CategoryName": { "type": "string", "description": "UseCategory=true 일 때 사용할 카테고리명 (예: 'CtgFiles'). scenario.Panel.Category 에 정의 필요." },
+            "InnerCKey":    false,
+            "Ckeys":        { "type": "array", "items": { "type": "string" }, "description": "KsystemFile / KsystemPayPDF 의 시퀀스 키 배열 — 업로드된 파일 시퀀스를 저장할 컬렉션 필드들." },
+            "Const":        { "type": "string", "description": "KsystemFile / KsystemPayPDF — 백엔드 상수 식별자." },
+            "FlexKey":      {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "FlexFile / HostingFolder / ServerkitFile — 업로드한 파일키 저장 정보. { ckey } 구조.",
+              "properties": {
+                "ckey": { "type": "string", "description": "파일키를 저장할 컬렉션 필드명." }
+              }
+            },
+            "SharedTarget": {
+              "type": "string",
+              "enum": ["user", "tenant"],
+              "default": "tenant",
+              "description": "FlexFile 전용 공유 범위 — 'user'=사용자 전용 / 'tenant'=테넌트 공유. FILEATTR 기본값 'tenant'."
+            },
+            "Directory":  { "type": "string", "description": "FlexFile 전용 (선택) — 저장 경로 디렉토리." },
+            "FileName":   { "type": "string", "description": "HostingFolder / ServerkitFile — 저장 시 사용할 파일명 컬렉션 필드명." },
+            "FolderRoute":{ "type": "string", "description": "HostingFolder / ServerkitFile — 저장 폴더 경로 (선행/후행 슬래시 자동 정규화 — 항상 'foo/bar/' 형태)." }
+          },
+          "allOf": [
+            {
+              "$comment": "Attributes.UseCategory=true 면 CategoryName 필수.",
+              "if": {
+                "properties": { "UseCategory": { "const": true } },
+                "required": ["UseCategory"]
+              },
+              "then": { "required": ["CategoryName"] }
+            }
+          ]
+        },
+
+        "UseEvents": { "type": "boolean", "default": false, "description": "이벤트 사용. Module=KsystemPayPDF 에서는 스튜디오 프로퍼티에 노출 안 됨 (이벤트 미지원)." },
+        "Events":    { "$ref": "_base.schema.json#/$defs/inputFileEvents" }
+      }
+    },
+    {
+      "$comment": "Module='FlexFile' → Attributes.FlexKey + SharedTarget 권장. FileDataGroup 에 UseCategory 기본 true.",
+      "if": {
+        "properties": { "Module": { "const": "FlexFile" } },
+        "required": ["Module"]
+      },
+      "then": {
+        "properties": {
+          "Attributes": { "required": ["FlexKey"] }
+        }
+      }
+    },
+    {
+      "$comment": "Module='KsystemFile' → Attributes.Ckeys + Const 권장. UseCategory 기본 false.",
+      "if": {
+        "properties": { "Module": { "const": "KsystemFile" } },
+        "required": ["Module"]
+      },
+      "then": {
+        "properties": {
+          "Attributes": { "required": ["Ckeys", "Const"] }
+        }
+      }
+    },
+    {
+      "$comment": "Module='KsystemPayPDF' → Attributes.Ckeys + Const 필수. UseEvents/Events 미지원.",
+      "if": {
+        "properties": { "Module": { "const": "KsystemPayPDF" } },
+        "required": ["Module"]
+      },
+      "then": {
+        "properties": {
+          "Attributes": { "required": ["Ckeys", "Const"] }
+        }
+      }
+    },
+    {
+      "$comment": "Module='HostingFolder' / 'ServerkitFile' → Attributes.FlexKey + FileName + FolderRoute 권장.",
+      "if": {
+        "properties": { "Module": { "enum": ["HostingFolder", "ServerkitFile"] } },
+        "required": ["Module"]
+      },
+      "then": {
+        "properties": {
+          "Attributes": { "required": ["FlexKey"] }
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,89 @@
+# InputMask
+
+마스크 패턴 입력. `InputType` 으로 시간/통화/날짜/전화 처리.
+
+## 스키마
+
+`control/input-mask.schema.json` — `controlBase` + `inputBase` + 분기 키 (`ControlType="InputMask"`, `InputType`, `MaskType`, `UseNumberOnly`, `UseFixedDecimalPlaces`, `DecimalPlaces`, `RoundingMode`).
+
+## 제한값
+
+### `InputType`
+스키마 enum 으로 강제.
+
+| 값 | 의미 |
+|---|---|
+| `hhmm` | 시간 HH:MM |
+| `money` | 통화 (천단위 콤마). `UseNumberOnly: true` 권장 (필수 아님) |
+| `yyyymmdd` | 날짜 YYYY-MM-DD |
+| `phone` | 전화번호 패턴 |
+
+> `InputType` 은 위 4 enum 만 지원. 4종 외 패턴이 필요하면 다른 컨트롤 (`InputText` + 검증 등) 로 우회.
+
+### `MaskType`
+스키마 enum 으로 강제. 마스크 카테고리 표시용. `InputType` 과 정합되어야 함.
+
+| 값 | 짝 InputType |
+|---|---|
+| `Time` | `hhmm` |
+| `Money` | `money` |
+| `Date` | `yyyymmdd` |
+| `Phone` | `phone` |
+
+## 예시 — 시간
+
+```jsonc
+{
+  "ControlType": "InputMask",
+  "ControlStyle": "styleInputValueLine",
+  "ControlDefaultName": "StartTime",
+  "ControlName2": "StartTime",
+  "InputType": "hhmm",
+  "Placeholder": "18:00",
+  "Caption": "{{시작시간}}",
+  "Id": "f_32",
+  "Ckeys": ["StartTime"],
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — 통화
+
+```jsonc
+{
+  "ControlType": "InputMask",
+  "InputType": "money",
+  "UseNumberOnly": true,
+  "DisplayValue": "",
+  "Ckeys": ["Price"],
+  "ControlDefaultName": "Price",
+  "ControlName2": "Price",
+  "Caption": "{{금액}}",
+  "Id": "f_33",
+  "isColumnCtrl": false,
+  "FontStyle": { "UseFont": true, "FontAlign": "flex-end", "FontSize": "14" }
+}
+```
+
+## 데이터 바인딩
+
+`Ckeys` 사용 시 **상위 Group 계층 어딘가에** `UseDataConnection: true` + `DataConnection` 필요.
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/inputEventsChangeOnly` 적용. **`change` 만 지원** (InputNumber 와 동일). `input` / `focusin` / `focusout` 사용 불가.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "InputEventOrder": ["change"],
+    "change": "ON_TIME_CHANGED"
+  }
+}
+```
+
+## 함정
+
+- `money` 는 표시는 콤마 포함, 저장값은 숫자 문자열.
+- `hhmm` 은 24시간 형식 — AM/PM 자동 변환 없음.

package/contract-data/schema/v1/control/input-mask.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/control/input-mask.schema.json",
+  "title": "InputMask",
+  "description": "마스크 패턴 입력. hhmm/money/yyyymmdd/phone.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["Id", "ControlType"],
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/controlBase" },
+    { "$ref": "_base.schema.json#/$defs/inputBase" },
+    {
+      "properties": {
+        "ControlType":   { "const": "InputMask" },
+        "InputType": {
+          "type": "string",
+          "enum": ["hhmm", "money", "yyyymmdd", "phone"],
+          "description": "hhmm=HH:MM 시간 / money=천단위 콤마 / yyyymmdd=YYYY-MM-DD 날짜 / phone=전화번호 패턴."
+        },
+        "MaskType":      {
+          "type": "string",
+          "enum": ["Time", "Money", "Date", "Phone"],
+          "description": "마스크 카테고리 표시용. InputType 과 정합되어야 함 (hhmm↔Time, money↔Money, yyyymmdd↔Date, phone↔Phone)."
+        },
+        "UseNumberOnly": { "type": "boolean", "default": false, "description": "money 등에서 숫자만 입력 강제. money 사용 시 권장 (필수는 아님)." },
+
+        "UseFixedDecimalPlaces": { "type": "boolean", "default": false, "description": "InputType='money' 일 때 소수점 자릿수 고정 사용 여부. true 일 때 DecimalPlaces + RoundingMode 활성." },
+        "DecimalPlaces": {
+          "type": ["integer", "string", "null"],
+          "minimum": 0,
+          "maximum": 15,
+          "description": "고정 소수점 자릿수 (0~15). UseFixedDecimalPlaces=true 일 때만 의미. 빈 입력은 null."
+        },
+        "RoundingMode": {
+          "type": "string",
+          "enum": ["round", "ceil", "floor"],
+          "default": "round",
+          "description": "소수점 처리 방식. round=반올림 / ceil=올림 / floor=내림. UseFixedDecimalPlaces=true 일 때만 의미."
+        },
+
+        "Events":        { "$ref": "_base.schema.json#/$defs/inputEventsChangeOnly" }
+      }
+    }
+  ]
+}