@flextudio/scenario 0.1.0

package/skill/docs/control/image-box.md

@@ -0,0 +1,237 @@
+# ImageBox
+
+이미지 표시/업로드 컨트롤. `ImageBoxType` 으로 두 모드 분기.
+
+## 스키마
+
+`control/image-box.schema.json` — `controlBase` + 분기 키 (`ControlType="ImageBox"`, `ImageBoxType`, `ViewGroup`, `EditGroup`).
+
+## ImageBoxType (제한)
+
+| 값 | 동작 | 필수 프로퍼티 |
+|---|---|---|
+| `"View"` | 읽기 전용 표시 | `ViewGroup` |
+| `"Edit"` | 업로드/촬영 + 표시 | `ViewGroup` (placeholder) + `EditGroup` (FlexFile 저장) |
+
+> **원리**: Edit 업로드 → 파일키가 `EditGroup.FlexKey.ckey` 컬렉션 필드에 저장. View 에서 동일 `ImageSrcType: "FlexFile"` + 동일 `FlexKey`/`ckey` 값으로 표시.
+
+## ImageSrcType (ViewGroup.ImageSrcType)
+
+| 값 | 키 | 의미 |
+|---|---|---|
+| `"FlexFile"` | `FlexKey` + `ckey` | Edit 업로드 이미지 표시 (둘은 같은 값) |
+| `"Url"` | `ImageUrl` | 외부 URL. `{=ImageField}` 바인딩 가능 |
+| `"Base64"` | `ImageUrl` | Base64 인코딩 인라인 |
+| `"Upload"` | — | **Edit 모드 전용** — `ViewGroup` 의 업로드 placeholder. `EditGroup` 와 짝 |
+
+## 시나리오 생성 시 (AI 생성 스켈레톤)
+
+**AI 가 시나리오를 생성할 때는 데이터 바인딩 메타(`ViewGroup` / `EditGroup`)를 생략해도 된다.** FlexFile 키 / 카테고리 필드명 / SharedTarget 등은 스튜디오 또는 사용자가 사후 설정한다.
+
+```jsonc
+// AI 생성 — View 스켈레톤 (데이터 미설정)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ControlDefaultName": "ImgView1",
+  "ControlName2": "ImgView1",
+  "Caption": "ImgView1",
+  "Id": "f_41",
+  "Width":  { "SizeValue": "80",  "SizeUnit": "px" },
+  "Height": { "SizeValue": "80",  "SizeUnit": "px" },
+  "isColumnCtrl": false
+}
+```
+
+```jsonc
+// AI 생성 — Edit 스켈레톤 (데이터 미설정)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ControlDefaultName": "ImgUpload1",
+  "ControlName2": "ImgUpload1",
+  "Caption": "ImgUpload1",
+  "Id": "f_42",
+  "Width":  { "SizeValue": 100,   "SizeUnit": "%" },
+  "Height": { "SizeValue": "200", "SizeUnit": "px" },
+  "isColumnCtrl": false
+}
+```
+
+> **원칙**: AI 는 `ImageBoxType` 만 결정하고 데이터 메타는 두지 않는다. 다만 `ViewGroup` / `EditGroup` 을 **굳이 작성한다면** 아래 정식 예시처럼 **유효한 형태로** (ImageSrcType 별 필수 키를 채워서) 작성해야 한다 — 빈 객체 / 누락 키는 schema 차단.
+
+## 예시 — View 모드 (FlexFile)
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": "PhotoUrl",
+    "ckey": "PhotoUrl"
+  },
+  "Width":  { "SizeValue": "80", "SizeUnit": "px" },
+  "Height": { "SizeValue": "80", "SizeUnit": "px" },
+  "ControlDefaultName": "ImgView",
+  "ControlName2": "ImgView",
+  "Caption": "ImgView",
+  "Id": "f_41",
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — View 모드 (Url)
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "{=ImageField}"
+  },
+  "ControlDefaultName": "ImgUrl",
+  "ControlName2": "ImgUrl",
+  "Caption": "ImgUrl",
+  "Id": "f_42",
+  "isColumnCtrl": false
+}
+```
+
+## 예시 — Edit 모드
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ViewGroup": {
+    "ImageSrcType": "Upload"
+  },
+  "EditGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": { "ckey": "PhotoUrl", "Name": "" },
+    "Module": "FlexFile"
+  },
+  "UseCondition": "false",
+  "UseMultiData": "false",
+  "UseEvents": "false",
+  "Events": {},
+  "Width":  { "SizeValue": 100,    "SizeUnit": "%" },
+  "Height": { "SizeValue": "200",  "SizeUnit": "px" },
+  "ControlDefaultName": "ImgUpload",
+  "ControlName2": "ImgUpload",
+  "Caption": "ImgUpload",
+  "Id": "f_43",
+  "isColumnCtrl": false
+}
+```
+
+> **Edit 모드 필수**: `ViewGroup`(`ImageSrcType: "Upload"`) + `EditGroup`(FlexFile 저장) 둘 다. `UseCondition`/`UseMultiData`/`UseEvents`/`Events` 함께 작성하는 것이 실 샘플 패턴 (값은 문자열 `"false"` 도 통과).
+
+## 이벤트 (제한)
+
+`Events` 는 `_base.schema.json#/$defs/imageBoxEvents` 적용. `ImageEventOrder` 에 `Click` 만. EventOrder ↔ 핸들러 일치 강제.
+
+```jsonc
+{
+  "UseEvents": true,
+  "Events": {
+    "ImageEventOrder": ["Click"],
+    "Click": "ON_IMAGE_CLICK_E"
+  }
+}
+```
+
+## FlexKey 형태
+
+| 모드 | 형태 | 비고 |
+|---|---|---|
+| `View` | string (필드명) | `ckey` 와 동일 값으로 동시에 작성 |
+| `Edit.EditGroup` | `{ "ckey": "...", "Name": "" }` | `ckey` 가 저장 대상 필드명 |
+
+## SharedTarget
+
+`"tenant"` (테넌트 공유, 일반) / `"user"` (사용자 전용) / `"global"` (전역 공유). 실 샘플 대부분 `"tenant"`.
+
+## `UseDefaultValue` — 기본(폴백) 이미지
+
+`UseDefaultValue` 는 **단일 boolean 키**(`engine const K.USE_DEFAULTVALUE='UseDefaultValue'`) 지만 `ImageBoxType` 별로 의미가 다르다. property-data.js 가 두 개의 UI 토글(`createUseDefault` / `createUseDefaultView`)로 노출하지만 둘 다 같은 키에 기록.
+
+| ImageBoxType | 토글 UI 위치 | UseDefaultValue=true 효과 | 추가 키 |
+|---|---|---|---|
+| `Edit` | `createUseDefault` (id `UseDefault`) — Edit 그룹 안 | EditGroup 업로드 실패/미설정 시 `ViewGroup` 의 이미지를 placeholder 로 표시 ([imagebox.js:42-45](public/engine/control/imagebox.js#L42)) | `ViewGroup` (기존) |
+| `View` | `createUseDefaultView` (id `UseDefaultView`) — View 그룹 안 | `ViewGroup` 의 FlexFile/Base64 로드가 비어있을 때 `DefaultViewGroup` 의 이미지를 fallback 으로 표시 | `DefaultViewGroup` 추가 |
+
+> **View 모드의 토글 표시 조건** (property-data.js line 11780): `ViewGroup.ImageSrcType ∈ { "FlexFile", "Base64" }` 일 때만 스튜디오 프로퍼티 패널에 노출. `Url` 일 때는 표시 안 됨 (URL 은 외부 리소스라 fallback 의미 약함).
+
+### `DefaultViewGroup` 형태
+
+`ViewGroup` 과 **완전히 동일한 shape** — `_base.schema.json#/$defs/imageBoxViewGroup` 그대로 재사용. 즉 `ImageSrcType` 분기에 따라 `FlexKey`/`ckey`/`ImageUrl` 등이 같은 규약으로 채워진다.
+
+```jsonc
+// View 모드 + UseDefaultValue=true (운영 메타 예 — AI 생성에는 두지 말 것)
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "View",
+  "ViewGroup": {
+    "ImageSrcType": "FlexFile",
+    "SharedTarget": "tenant",
+    "FlexKey": "PhotoUrl",
+    "ckey":    "PhotoUrl"
+  },
+  "UseDefaultValue": true,
+  "DefaultViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "/imagesCommon/avatar-placeholder.png"
+  },
+  "Id": "f_60"
+}
+```
+
+→ `_collections` 에서 `PhotoUrl` 이 비어있거나 FlexFile 다운로드가 실패하면 `DefaultViewGroup` 의 placeholder URL 이 대신 표시.
+
+### Edit 모드 — `UseDefaultValue=true` 만 두는 케이스
+
+```jsonc
+{
+  "ControlType": "ImageBox",
+  "ImageBoxType": "Edit",
+  "ViewGroup": {
+    "ImageSrcType": "Url",
+    "ImageUrl": "/imagesCommon/upload-placeholder.png"
+  },
+  "EditGroup": {
+    "ImageSrcType": "FlexFile",
+    "FlexKey": { "ckey": "PhotoUrl", "Name": "" },
+    "Module":  "FlexFile"
+  },
+  "UseDefaultValue": true,
+  "Id": "f_61"
+}
+```
+
+→ 업로드 전에는 `ViewGroup` 의 placeholder URL 이 보이고, 업로드 후에는 그 자리에 업로드한 이미지가 표시. Edit 모드에서는 `DefaultViewGroup` 을 두지 않는다 — `ViewGroup` 자체가 placeholder 역할.
+
+### ★ AI 생성 정책
+
+- `UseDefaultValue` 는 **boolean strict** (CHECKBOX 진실원본). 문자열 `"true"`/`"false"` 금지.
+- `DefaultViewGroup` 은 **AI 생성 시 미포함** — 운영에서 placeholder 이미지를 정한 다음 사용자가 수동 설정. AI 가 굳이 placeholder 경로를 추측하지 않는다. ([control.md §AI 샘플 생성 금지 키](../control.md#ai-critical) 단일 진실원본 표 등재 — `AI_GEN_STRICT=1` 시 validate.mjs `[ai-gen]` 태그 차단.)
+- AI 생성 스켈레톤 단계에서는 둘 다 생략 권장. ImageBoxType 만 결정.
+
+## Edit ↔ View 연동
+
+- Edit 업로드 시 → `EditGroup.FlexKey.ckey` 컬렉션 필드에 파일키 저장.
+- View 에서 표시할 때 → `ImageSrcType: "FlexFile"` + 같은 `FlexKey`/`ckey` 값.
+- View 에서 `ImageSrcType: "Url"` 로 두면 FlexFile 파일키는 표시 못 함 — 외부 URL 만.
+
+## 함정
+
+- `ControlName2` 누락 = 런타임 에러. `ControlDefaultName` 과 같은 값.
+- `isColumnCtrl: false` 항상 명시 (Sheet 컬럼 모드는 OtherControl).
+- AI 생성 단계에서는 `ViewGroup` / `EditGroup` 을 생략해도 schema 통과 (스켈레톤). 운영에 투입하려면 사후 설정 필수.
+- Edit 모드 운영 시 `ViewGroup` 누락 → 업로드 후 표시 영역 비어 있음. `ImageSrcType: "Upload"` 로 placeholder 명시.
+- Edit 모드 `EditGroup.FlexKey` 는 **객체** (`{ ckey, Name }`), View 모드 `FlexKey` 는 **string**. 혼동 주의.
+- `Ckeys` 미사용 — 데이터 바인딩은 `ViewGroup.ckey` / `EditGroup.FlexKey.ckey` 로 처리 (별도 `Ckeys` 배열은 두지 않는다).

package/skill/docs/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/skill/docs/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 와 동일 형태).