@flextudio/scenario 0.1.0

package/contract-data/schema/v1/service/Flextudio API.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/Flextudio%20API.schema.json",
+  "title": "Flextudio API ServiceBinding",
+  "description": "Flextudio API 시스템 호출. const.js 의 SYSTEM_ID.FLEXTUDIO_API='Flextudio API' (공백 포함) 에 매핑. flexApiKey 기반 인증. 사용자(User) / 메시지(Message) / 그룹(Group) 3 모듈 + SubModuleID 로 CRUD 식별. 런타임: public/system/flextudio/flextudio_api.js.",
+  "type": "object",
+  "required": ["SystemID", "ModuleID", "flexApiKey"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID":   { "const": "Flextudio API", "description": "Flextudio API 호출 시 'Flextudio API' 고정 (공백 포함)." },
+        "ModuleID":   {
+          "type": "string",
+          "enum": ["User", "Message", "Group"],
+          "description": "Flextudio API 모듈. User=사용자 CRUD / Message=메시지 조회 / Group=그룹 회원 조회. const.js MODULE_ID[FLEXTUDIO_API]."
+        },
+        "SubModuleID":{
+          "type": "string",
+          "enum": ["Query", "Save", "Update", "Delete", "UserQuery"],
+          "description": "ModuleID 별 하위 작업. User: Query/Save/Update/Delete · Message: Query · Group: UserQuery. const.js SUB_MODULE_ID[FLEXTUDIO_API]."
+        },
+        "flexApiKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Flextudio API 호출용 인증 키 (필수). HTTP 요청 헤더 `x-flex-api-key` 로 전송. 워크스페이스 콘솔에서 발급."
+        },
+        "useUserAppGrant": {
+          "type": "boolean",
+          "description": "User Save 시 현재 앱 ID(_base.appid)를 함께 전송해 앱 사용 권한 자동 부여. const.js K_FLEXTUDIO_API_PROP.USE_USER_APP_GRANT."
+        },
+        "UseSearch": {
+          "type": "boolean",
+          "description": "User Query 검색 모드 토글. true 면 SearchItem 의 필터 조건이 쿼리 파라미터로 전송."
+        },
+        "SearchItem": {
+          "type": "array",
+          "description": "User Query 검색 조건 배열. UseSearch:true 일 때 사용.",
+          "items": { "$ref": "#/$defs/searchItem" }
+        },
+        "UseUnreadMessage": {
+          "type": "boolean",
+          "description": "Message Query 시 읽지 않은 메시지만 조회 토글. const.js K_FLEXTUDIO_API_PROP.USE_UNREAD_MESSAGE."
+        },
+        "groupName": {
+          "type": "string",
+          "description": "Group UserQuery 의 대상 그룹 이름. `{% %}` 대체 표현식 가능 (예: `'{%_c.activeGroup[0].groupName%}'`)."
+        },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" },
+        "UseInnerBlock": { "type": "boolean" }
+      },
+      "allOf": [
+        {
+          "$comment": "User 모듈은 Query/Save/Update/Delete SubModule 중 하나 필수.",
+          "if": {
+            "properties": { "ModuleID": { "const": "User" } },
+            "required": ["ModuleID"]
+          },
+          "then": {
+            "required": ["SubModuleID"],
+            "properties": {
+              "SubModuleID": { "enum": ["Query", "Save", "Update", "Delete"] }
+            }
+          }
+        },
+        {
+          "$comment": "Message 모듈은 Query 만.",
+          "if": {
+            "properties": { "ModuleID": { "const": "Message" } },
+            "required": ["ModuleID"]
+          },
+          "then": {
+            "required": ["SubModuleID"],
+            "properties": {
+              "SubModuleID": { "const": "Query" }
+            }
+          }
+        },
+        {
+          "$comment": "Group 모듈은 UserQuery 만 + groupName 필수.",
+          "if": {
+            "properties": { "ModuleID": { "const": "Group" } },
+            "required": ["ModuleID"]
+          },
+          "then": {
+            "required": ["SubModuleID", "groupName"],
+            "properties": {
+              "SubModuleID": { "const": "UserQuery" }
+            }
+          }
+        }
+      ]
+    }
+  ],
+
+  "$defs": {
+    "searchItem": {
+      "type": "object",
+      "description": "User Query 검색 항목. 필드명 + 연산자 + 컬렉션 키 매핑.",
+      "additionalProperties": true,
+      "properties": {
+        "FieldName":    { "type": "string", "description": "조회 대상 필드명 (서버 필드)." },
+        "SearchFilter": {
+          "type": "string",
+          "enum": ["contains", "!contains", "exists", "!exists", "==", "!=", "<", "<=", ">", ">="],
+          "description": "검색 연산자. const.js K_FLEXTUDIO_API_USER_FILTER."
+        },
+        "FieldValue":   { "type": "string", "description": "비교값이 들어있는 컬렉션 키 (sector 의 키 이름)." }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+# Flextudio Service (Flextudio.schema.json)
+
+`SystemID:'Flextudio'` — flextudio 워크스페이스 내장 시스템 호출. const.js `SYSTEM_ID.FLEXTUDIO='Flextudio'`. 사용자/메시지 도메인 내장 기능.
+
+런타임 구현: [`public/system/flextudio/flextudio.js`](../../../../public/system/flextudio/flextudio.js).
+
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+> **`Flextudio API` ([`Flextudio API.md`](Flextudio%20API.md)) 와 다름!** 같은 도메인이지만 SystemID 가 다른 별개 시스템.
+
+## 1. ModuleID 3종
+
+| ModuleID | 동작 |
+|---|---|
+| `GetUserList` | 워크스페이스 회원/조직원 목록 조회 |
+| `QueryMessage` | 메시지 목록 조회 |
+| `SendMessage` | 메시지 발송 (푸시 등) |
+
+> 결재자 조회 등에서 흔히 사용 (`SystemID:'Flextudio'`, `ModuleID:'GetUserList'`).
+
+## 2. 식별 필드
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"Flextudio"` (고정) | const |
+| `ModuleID` | enum 3종 | |
+
+## 3. 형태 — GetUserList (결재자 조회 패턴)
+
+```jsonc
+"ServiceBinding": {
+  "GetApprovalUsers": {
+    "SystemID":       "Flextudio",
+    "ModuleID":       "GetUserList",
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true
+  }
+}
+```
+
+호출 측 Action:
+
+```jsonc
+{
+  "Action":         "Service",
+  "ServiceBinding": "GetApprovalUsers",
+  "ServiceName":    "GetUserList",
+  "SystemID":       "Flextudio",
+  "ParamBlocks": [
+    {
+      "CategoryName": "filterUser",
+      "UseFilter":    false,
+      "UserData":     ["DepartmentSeq"]
+    }
+  ],
+  "ResultBlocks": [
+    { "TargetType": "replace", "CategoryName": "approvalUserList" }
+  ]
+}
+```
+
+## 4. SendMessage 패턴
+
+푸시/메시지 발송용 Service Action. ParamBlock 으로 발송 대상 + 본문을 명시한다. (런타임 모달 다이얼로그는 `f.MessageBox(...)...show()` — 정본: [runtime/v1/script/f_messagebox.md](../../runtime/v1/script/f_messagebox.md).)
+
+## 5. API 연동 흐름
+
+```
+[1] Action='Service' SystemID='Flextudio' → flextudio.js 라우팅
+[2] ModuleID 분기 (GetUserList / QueryMessage / SendMessage)
+[3] 워크스페이스 내부 사용자/메시지 데이터 조회/발송
+[4] 결과 → ResultBlocks 카테고리 반영
+```
+
+## 6. `Flextudio` vs `Flextudio API` 차이
+
+| 항목 | Flextudio | Flextudio API |
+|---|---|---|
+| SystemID | `'Flextudio'` | `'Flextudio API'` (공백 포함) |
+| 인증 | 워크스페이스 세션 (자동) | `flexApiKey` 필요 |
+| 모듈 | 3종 (GetUserList / QueryMessage / SendMessage) | 3종 (User / Message / Group) + SubModuleID |
+| 호출 형태 | 내장 라우팅 | REST 호출 (`/v1/company/.../users`) |
+| 런타임 | `flextudio.js` | `flextudio_api.js` |
+| 용도 | 시나리오 내부 사용자/메시지 헬퍼 | 외부 API Key 기반 사용자/메시지/그룹 CRUD |
+
+자세한 차이는 [`Flextudio API.md`](Flextudio%20API.md) 참조.

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

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/Flextudio.schema.json",
+  "title": "Flextudio ServiceBinding",
+  "description": "Flextudio 내장 시스템 호출. const.js 의 SYSTEM_ID.FLEXTUDIO='Flextudio' 에 매핑. 워크스페이스 사용자/메시지 도메인 기능 (GetUserList / QueryMessage / SendMessage). 런타임 구현: public/system/flextudio/flextudio.js.",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "Flextudio", "description": "Flextudio 내장 시스템 호출 시 'Flextudio' 고정." },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["GetUserList", "QueryMessage", "SendMessage"],
+          "description": "Flextudio 모듈. GetUserList=사용자 목록 조회 / QueryMessage=메시지 조회 / SendMessage=메시지 발송."
+        },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" },
+        "UseInnerBlock": { "type": "boolean" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,71 @@
+# GoogleSheet Service (GoogleSheet.schema.json)
+
+Google Sheet 데이터 직접 조작. 테넌트 설정의 Google Sheet 인증 정보 기반.
+
+> **참고**: [docs.flextudio.com — GoogleSheet](https://docs.flextudio.com/flextudio/scenario/dev-mode/service/googlesheet).
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단. 단순 데이터 조작에만 적합 — 복잡한 조작은 Firestore 권장.
+
+## 1. GoogleSheet 의 특성
+
+- 빈 행/빈 열 = 다른 테이블로 인식.
+- 첫 행 헤더 영역 ~ 빈 행 직전까지를 한 테이블로 정의.
+- 시트 위에 여러 표가 있으면 **첫 헤더 영역만** 인식.
+
+## 2. 식별 필드
+
+| 필드 | 값 / 패턴 | 비고 |
+|---|---|---|
+| `SystemID` | `"GoogleSheet"` (고정) | const |
+| `ModuleID` | `Query` / `Append` / `Update` / `Clear` | 4종 |
+| `SpreadsheetId` | string | URL `/spreadsheets/d/{spreadsheetId}/edit` 부분 |
+| `SheetName` | string | 시트 탭 이름 |
+| `BaseColumn` | string | 기준 컬럼명. 보통 `_SUID` |
+
+## 3. ModuleID 4종 (Firestore 와 다름!)
+
+| ModuleID | 동작 | 보내는 데이터 | 받는 데이터 |
+|---|---|---|---|
+| `Query` | 조회 | 사용 안 함 (시트 전체) | 조회된 데이터 + `_rowIndex` |
+| `Append` | 추가 | ParamBlock1 의 **기준 컬럼 항목이 있는 섹터** | 저장한 데이터의 `_SUID` + `_rowIndex` |
+| `Update` | 수정 | ParamBlock1 의 **`_rowIndex` 와 기준 컬럼이 일치하는 섹터** | 수정한 데이터의 `_SUID` + `_rowIndex` |
+| `Clear` | 값 비움 | ParamBlock1 의 **`_rowIndex` 와 기준 컬럼이 일치하는 섹터** | 삭제 결과의 `_SUID` + `_rowIndex` + 삭제 결과 |
+
+> ⚠️ **`Clear` 는 행 삭제가 아님** — 기준 컬럼 외 값만 비움. 완전한 행 삭제는 시트에서 직접 **Delete Row** 로만 가능 (이 경우 무결성 미보장).
+
+## 4. 기준 컬럼명 (BaseColumn)
+
+- 시트의 행 식별자. Update/Clear 시 `_rowIndex` 와 함께 키로 사용.
+- 별도 관리값 없으면 `_SUID` 컬럼 생성 + 기준 키 등록 → 자동 생성.
+- 업데이트/삭제 작업 시에도 값 변경 안 됨.
+
+## 5. 형태
+
+```jsonc
+"ServiceBinding": {
+  "saveOrder": {
+    "SystemID":      "GoogleSheet",
+    "ModuleID":      "Append",
+    "SpreadsheetId": "1ABCdef-XYZ_someLongIdHere",
+    "SheetName":     "Orders",
+    "BaseColumn":    "_SUID",
+    "SetCategory":   true,
+    "UsePKey":       true,
+    "UseParamBlock": true,
+    "UseResultBlock":true
+  }
+}
+```
+
+## 6. ParamBlock / ResultBlock
+
+| 블록 | GoogleSheet 매핑 |
+|---|---|
+| ParamBlock1.첫 섹터 | (Query 는 미사용) |
+| ParamBlock1.모든 섹터 | Append/Update/Clear 의 대상 행들 |
+| `_rowIndex` 자동 추가 | Query 결과에 자동 포함 |
+
+## 7. 제약 / 주의
+
+- **GoogleSheet 서비스는 단순 작업 전용** — 복잡한 트랜잭션이나 관계형 데이터는 FlexSQL / Firestore 사용.
+- 동시 편집 충돌 무결성 미보장 (Delete Row 등).
+- API 쿼터 제한 (Google API 정책).

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/GoogleSheet.schema.json",
+  "title": "GoogleSheet ServiceBinding",
+  "description": "Google Sheet 직접 연동. SystemID='GoogleSheet'. spreadsheetId + Sheet 명 + 기준 컬럼명 (보통 _SUID) 으로 동작. ModuleID 4종 (Query / Append / Update / Clear).",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "GoogleSheet" },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["Query", "Append", "Update", "Clear"],
+          "description": "GoogleSheet 작업 종류. Firestore 와 다름 — Save→Append, Delete→Clear (행 삭제 X, 값만 비움)."
+        },
+        "SpreadsheetId": {
+          "type": "string",
+          "description": "Google Spreadsheet ID — URL `/spreadsheets/d/{spreadsheetId}/edit` 의 부분."
+        },
+        "SheetName":     { "type": "string", "description": "시트 명 (탭 이름)." },
+        "BaseColumn":    { "type": "string", "description": "기준 컬럼명. 보통 `_SUID` — 빈 컬럼이면 자동 생성. Update/Clear 시 _rowIndex 와 함께 행 식별 키." },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,127 @@
+# Service 폴더 — 서비스 종류별 메타 + API 연동
+
+`scenarioMeta.ServiceBinding[<name>]` 항목 / `Events.X[*].Action='Service'` 의 인라인 ServiceBinding 객체에서 사용하는 **서비스 종류별 분기 스키마와 가이드**.
+
+> **스킬 생성에서는 모든 서비스 사용 금지** — `[no-service]` 가 차단 (`strict_no_service:true` 기본). 본 폴더의 스키마/가이드는 **운영 메타 검증** 과 **AI 가 사용자 질문에 답할 때의 참고 자료**로 사용. 운영 메타 검증 시 `strict_no_service:false` 로 호출.
+> **참고 문서**: [docs.flextudio.com — Event 와 Service](https://docs.flextudio.com/flextudio/concept/eventservice), [docs.flextudio.com — Service](https://docs.flextudio.com/flextudio/scenario/dev-mode/service), [docs.flextudio.com — API 호출](https://docs.flextudio.com/flextudio/scenario/dev-mode/event/api), [flextudio-guide §6.6–6.8](../../../../flextudio-ai-studio/docs/flextudio-guide.md), [const.js SYSTEM_ID](../../../../public/engine/common/const.js).
+
+## 명명 원칙
+
+**파일명 = `SYSTEM_ID` 값 그대로** (대소문자/공백 보존). const.js `SYSTEM_ID` 의 string value 가 그대로 파일명 basename. 예외: `CustomSystem` 은 `SystemType` (별도 `CUSTOM_SYSTEM_TYPE='CustomSystem'`) 매핑.
+
+## 폴더 구조
+
+```
+schema/v1/service/
+├── README.md                          # 이 파일 — 인덱스 + 비교표
+├── _base.schema.json                  # 공통 commonBase $defs
+├── FlexSQL.{schema.json,md}           # SystemID='FlexSQL'        — 워크스페이스 SQL
+├── FlexAutoQuery.{schema.json,md}     # SystemID='FlexAutoQuery'  — FlexDB 자동 CRUD
+├── ksystem.{schema.json,md}           # SystemID='ksystem'        — 영림원 ksystem (FlexAPI/OpenAPI/Codehelp/Ksystem/Filehelp)
+├── Firestore.{schema.json,md}         # SystemID='Firestore'      — Google Firestore
+├── GoogleSheet.{schema.json,md}       # SystemID='GoogleSheet'    — Google Sheet
+├── Flextudio.{schema.json,md}         # SystemID='Flextudio'      — 워크스페이스 내장 (GetUserList/QueryMessage/SendMessage)
+├── Flextudio API.{schema.json,md}     # SystemID='Flextudio API'  — 사용자/메시지/그룹 REST API (flexApiKey)
+└── CustomSystem.{schema.json,md}      # SystemType='CustomSystem' (SystemID='New_NN') — Action='API' 매핑 + fEventKey/fEvent
+```
+
+## 시스템 비교표
+
+const.js `SYSTEM_ID` 정의 + docs.flextudio.com 공식 문서 + 실 샘플 시나리오 기반.
+
+| 시스템 | SystemID (const.js) | SystemType | ModuleID 후보 | 핵심 필드 | 플랜 | 빈도 |
+|---|---|---|---|---|---|---|
+| **FlexSQL** | `FlexSQL` | — | `Default` | `SQLServiceName`(`<시나리오>:<서비스>`), `MajorVersion`, `ExternalDB`, `BeforeScript`, `ResultScript` | Business+ | 39 |
+| **FlexAutoQuery** | `FlexAutoQuery` | — | `Default` | `ServiceType`(Query/Save/Update/Delete), `TargetTable`, `OrderBy` | Business+ | (실 샘플은 ksystem 으로 박힘) |
+| **ksystem** | `ksystem` | — | `FlexAPI` / `OpenAPI` / `Codehelp` / `Ksystem` / `Filehelp` | `UseTable`(BIZ), `SelectTable`, `SPList[]`, `UseBundle` | Business+ | 25 |
+| **Firestore** | `Firestore` | — | `Query` / `Save` / `Update` / `Delete` | `Collection`, `UseSearch` | All | 4 |
+| **GoogleSheet** | `GoogleSheet` | — | `Query` / `Append` / `Update` / `Clear` | `SpreadsheetId`, `SheetName`, `BaseColumn`(`_SUID`) | All | 0 (실 샘플) |
+| **Flextudio** | `Flextudio` | — | `GetUserList` / `QueryMessage` / `SendMessage` | (없음) | All | (헬퍼) |
+| **Flextudio API** | `Flextudio API` (공백) | — | `User` / `Message` / `Group` | `flexApiKey`, `SubModuleID`, `useUserAppGrant`, `UseSearch`+`SearchItem`, `UseUnreadMessage`, `groupName` | All | (REST) |
+| **CustomSystem** | `New_NN` | `CustomSystem` | GUID v4 | `fEventKey[]`, `fEvent{}` (= "Event Config Key") | All | 12 |
+
+> **`Custom` 시스템은 v1 컨트랙트에서 제외** (const.js `SYSTEM_ID.CUSTOM='Custom'` 은 정의되어 있으나 본 컨트랙트는 미지원 — Custom REST 는 외부 백엔드 호출용으로 보안/검증 부담이 커서 의도적으로 제외).
+
+### ModuleID 비교 (혼동 주의)
+
+| 작업 | FlexAutoQuery | Firestore | GoogleSheet |
+|---|---|---|---|
+| 조회 | `Query` (ServiceType) | `Query` | `Query` |
+| 추가/저장 | `Save` | `Save` | `Append` |
+| 수정 | `Update` | `Update` | `Update` |
+| 삭제 | `Delete` | `Delete` | `Clear` (값만 비움) |
+
+### Flextudio 도메인 모듈 비교 (혼동 주의)
+
+| 작업 | Flextudio (`SystemID='Flextudio'`) | Flextudio API (`SystemID='Flextudio API'`) |
+|---|---|---|
+| 사용자 조회 | `ModuleID:'GetUserList'` | `ModuleID:'User'` + `SubModuleID:'Query'` |
+| 메시지 조회 | `ModuleID:'QueryMessage'` | `ModuleID:'Message'` + `SubModuleID:'Query'` |
+| 메시지 발송 | `ModuleID:'SendMessage'` | (해당 없음 — REST 미지원) |
+| 그룹 회원 조회 | (해당 없음) | `ModuleID:'Group'` + `SubModuleID:'UserQuery'` + `groupName` |
+| 인증 | 워크스페이스 세션 (자동) | `flexApiKey` 헤더 |
+
+### 연산자 비교
+
+| 서비스 | 지원 연산자 |
+|---|---|
+| **FlexAutoQuery** | `=`, `!=`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`, `IS NULL`, `IS NOT NULL` |
+| **Firestore** | `==`, `!=`, `<`, `<=`, `>`, `>=` (LIKE/IS NULL 미지원) |
+| **Flextudio API User Query** (`SearchFilter`) | `contains`, `!contains`, `exists`, `!exists`, `==`, `!=`, `<`, `<=`, `>`, `>=` |
+
+## 분기 결정 규칙
+
+`ServiceBinding[<name>]` 또는 `Action.ServiceBinding` 의 `SystemID` / `SystemType` 값으로 어느 스키마를 적용할지 결정 (const.js SYSTEM_ID 와 1:1).
+
+```
+SystemID === 'FlexSQL'                               → FlexSQL.schema.json
+SystemID === 'FlexAutoQuery'                         → FlexAutoQuery.schema.json
+SystemID === 'ksystem'                               → ksystem.schema.json
+SystemID === 'Firestore'                             → Firestore.schema.json
+SystemID === 'GoogleSheet'                           → GoogleSheet.schema.json
+SystemID === 'Flextudio'                             → Flextudio.schema.json
+SystemID === 'Flextudio API'                         → Flextudio API.schema.json
+SystemType === 'CustomSystem' (SystemID = 'New_NN')  → CustomSystem.schema.json
+그 외                                                → service-binding.schema.json (관용 모드)
+```
+
+## 공통 ParamBlocks / ResultBlocks
+
+서비스 종류와 무관하게 모든 서비스 호출은 `ParamBlocks` (보내는 데이터) / `ResultBlocks` (받은 데이터) / `InnerBlocks` (중첩 매핑) 구조를 공유한다. 자세한 형식은 [`../events.md §2.3`](../events.md) 참조.
+
+| 블록 | 역할 | 필수 필드 |
+|---|---|---|
+| `ParamBlocks[]` | 카테고리/필터/사용자 컨텍스트 데이터 송신 | `CategoryName` 또는 `UserData` |
+| `ResultBlocks[]` | 결과를 컬렉션 카테고리에 반영 (`category` / `replace` / `add` / `merge`) | `TargetType`, `CategoryName` (`merge` 시 `PKeys` 추가) |
+| `InnerBlocks[]` | 결과 객체 안의 자식 배열 키 매핑 | `InnerBlockKey` |
+
+## 런타임 내부 / 미사용 필드 (AI 생성 금지)
+
+> ⚠️ const.js `K_EVENT.SERVICE` 에는 아래 필드들도 정의되어 있으나 일반 시나리오에서는 거의 미사용 — 런타임 내부 / 스튜디오 디버그 전용. AI 생성에서는 **절대 박지 말 것**. 운영 메타에서 마주치면 그대로 보존(스키마 `additionalProperties:true` 가 통과).
+
+| 분류 | 필드 | 용도 |
+|---|---|---|
+| **비동기 콜백** | `useAsync` / `asyncThenScript` / `asyncCatchScript` / `asyncFinallyScript` | 비동기 호출 then/catch/finally 스크립트. 일반 시나리오는 동기 `_fEvent.pause/resume` 흐름 사용 |
+| **모바일 오프라인 큐** | `Flex-Offline` / `FlexOfflineModeType` (`Queue`\|`Cache`) / `FlexOfflineAfterEvent` | 푸시/큐 라우팅 — 모바일 한정 |
+| **오프라인 트랜잭션 키** | `UseFlexSourceID` / `UseFlexSubmissionID` / `Flex-SubmissionID` / `Flex-SourceID` / `Flex-Mapper` (+ `map`/`path`/`match`/`preserveSource`) | 오프라인 큐 SubmissionID/SourceID 매핑 — 운영 환경 자동 채움 |
+| **스튜디오 디버그** | `UseTestGround` / `TestScript` | Test Ground — 스튜디오에서 테스트 호출 시 자동 박힘 |
+| **스튜디오 API 테스트** | `UseApiGround` / `ApiModuleId` / `ApiSystemId` / `ApiEvent` / `ApiEventKey` | API Ground — 스튜디오에서 API 모듈 시뮬레이션 시 사용 |
+| **FlexSQL 임시 테이블** | `UseTempTable` / `TempTableName` | FlexSQL 임시 테이블 — 운영 한정 |
+| **트랜잭션 / 외부 시스템** | `useCommonTran` / `UseExternal` | 공통 트랜잭션 묶음 / 외부 토글 — 운영 한정 |
+| **결과 옵션** | `UseResultOptions` / `NotReflect` / `IsReplace` | 결과 반영 세부 토글 — `ResultBlocks.TargetType` 으로 충분 |
+
+> step.md `AfterOfflineEvent` (`STEP_EVENT.AFTEROFFLINE`) 와 동일한 정책 — const.js 에는 정의되어 있어 형식상 통과되지만 AI 생성 메타에는 박지 않음. 운영 메타와 충돌 회피 목적으로만 정의되어 있다.
+
+## 운영 메타 검증
+
+```jsonc
+{
+  "name": "validate_scenario",
+  "arguments": {
+    "scenario": {…},
+    "strict_no_service": false      // ServiceBinding / Service / API 통과
+  }
+}
+```
+
+`strict_no_service:false` 모드에서도 본 폴더의 스키마는 형식 강제력을 유지한다 — 예: FlexSQL 의 `SQLServiceName` 콜론 패턴, Flextudio API 의 ModuleID/SubModuleID 분기, CustomSystem 의 `New_NN` SystemID 패턴 등.

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/_base.schema.json",
+  "title": "Service Base",
+  "description": "서비스 종류별 ServiceBinding 분기에서 공통으로 쓰는 $defs. 각 service/<type>.schema.json 은 commonBase 위에 분기별 키를 얹는다 (allOf).",
+
+  "$defs": {
+    "commonBase": {
+      "type": "object",
+      "description": "모든 ServiceBinding 항목에 공통으로 등장하는 필드. 실 샘플 99 항목 통계 기반.",
+      "properties": {
+        "SystemID":             { "type": "string", "description": "시스템 식별자. FlexSQL / Firestore / Custom / ksystem / New_<NN> 등." },
+        "SystemType":           { "type": "string", "description": "시스템 종류 (CustomSystem / 비어있음 / FlexAutoQuery 등)." },
+        "ModuleID":             { "type": "string", "description": "모듈 식별자. FlexSQL='Default' / Firestore='Query' / FlexAPI / GUID(CustomSystem) 등." },
+        "ServiceName":          { "type": "string" },
+        "SetCategory":          { "type": "boolean", "description": "결과 반영 대상 카테고리 토글. 프로퍼티 SWITCH 가 boolean 저장." },
+        "UsePKey":              { "type": "boolean" },
+        "UseParamBlock":        { "type": "boolean" },
+        "UseResultBlock":       { "type": "boolean" },
+        "UseInnerBlock":        { "type": "boolean" },
+        "NotSeperateInnerBlock":{ "type": "boolean", "description": "InnerBlock 분리 안 함. 서버 내부 동작에 영향." }
+      }
+    },
+
+    "systemIDPattern": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+      "description": "SystemID 패턴. 영문 시작, 영문/숫자/언더스코어. 실 샘플: FlexSQL / Firestore / Custom / ksystem / New_01 / New_05."
+    }
+  }
+}

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

@@ -0,0 +1,76 @@
+# ksystem Service (ksystem.schema.json)
+
+`SystemID:'ksystem'` (소문자) — 영림원소프트랩 ksystem 사내 시스템 호출. const.js `SYSTEM_ID.KSYSTEM='ksystem'` 에 매핑.
+
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+> **운영 메타 호환** 목적으로 형식 정의. AI 자동 생성 시나리오에는 등장 안 함.
+
+## 1. ModuleID 5종
+
+| ModuleID | 의미 |
+|---|---|
+| `FlexAPI` | BIZ 테이블 (자동생성 비즈니스 테이블) 의 스토어드 프로시저 호출 — 가장 흔한 형태 |
+| `OpenAPI` | ksystem 공개 API |
+| `Codehelp` | 코드 매핑 (도메인 코드 ↔ 표시명) |
+| `Ksystem` | ksystem 본체 모듈 |
+| `Filehelp` | 파일 처리 헬퍼 |
+
+> 실 샘플 25 항목 중 대부분이 `ModuleID:'FlexAPI'` + `UseTable:'BIZ'` + `SPList:[...]` 패턴.
+
+## 2. 식별 필드
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"ksystem"` (고정, 소문자) | const |
+| `ModuleID` | enum 5종 (위 표) | |
+| `UseTable` | `"BIZ"` / `false` | BIZ = 비즈니스 테이블 |
+| `SelectTable` | 테이블 이름 또는 정의 객체 | |
+| `SPList[]` | 자동생성 SP 이름 배열 | 예: `["_SWFlexARUsualCostAppListQuery"]` |
+| `UseBundle` | boolean | 여러 SP 묶음 호출 |
+
+## 3. 형태 — FlexAPI 모듈 (BIZ 테이블 SP 호출)
+
+```jsonc
+"ServiceBinding": {
+  "UsualCostAppListQuery_S": {
+    "SystemID":              "ksystem",
+    "ModuleID":              "FlexAPI",
+    "SetCategory":           true,
+    "UsePKey":               true,
+    "UseParamBlock":         true,
+    "UseResultBlock":        true,
+    "UseInnerBlock":         true,
+    "NotSeperateInnerBlock": true,
+    "UseTable":              "BIZ",
+    "SelectTable":           "",
+    "SPList":                ["_SWFlexARUsualCostAppListQuery"],
+    "UseBundle":             false
+  }
+}
+```
+
+## 4. UseBundle (번들 호출)
+
+여러 SP 를 묶어서 한 번에 호출. `SPList` 에 여러 항목 + `UseBundle: true`.
+
+```jsonc
+{
+  "SPList":    ["_SWFlexUserSave", "_SWFlexUserPrefSave"],
+  "UseBundle": true
+}
+```
+
+## 5. API 연동 흐름
+
+```
+[1] Action='Service' SystemID='ksystem' → ksystem 라우팅
+[2] ModuleID 분기 (FlexAPI / OpenAPI / Codehelp / Ksystem / Filehelp)
+[3] FlexAPI 면 SPList 의 SP 를 BIZ 테이블에 대해 자동 실행
+[4] 결과 → ResultBlocks 카테고리 반영
+```
+
+## 6. FlexAutoQuery 와의 관계
+
+- ksystem `FlexAPI` 모듈은 자동생성된 SP 호출.
+- [`FlexAutoQuery.md`](FlexAutoQuery.md) 는 별도 SystemID — 자동 CRUD 추상화 한 단계 더 위.
+- 둘 다 BIZ 테이블 기반 자동 SP 를 사용하지만 메타 표기가 다르다 — 운영 환경/플랜에 따라 선택.

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

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/ksystem.schema.json",
+  "title": "ksystem ServiceBinding",
+  "description": "ksystem 서비스 호출 정의. const.js 의 SYSTEM_ID.KSYSTEM='ksystem' 에 매핑. 영림원소프트랩 ksystem 사내 모듈 (FlexAPI / OpenAPI / Codehelp / Ksystem / Filehelp). 자동생성 BIZ 테이블에 대한 SP 호출 형태가 가장 흔함.",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "ksystem", "description": "ksystem 호출 시 'ksystem' 고정 (소문자)." },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["FlexAPI", "OpenAPI", "Codehelp", "Ksystem", "Filehelp"],
+          "description": "ksystem 모듈. FlexAPI=BIZ 테이블 SP 호출 / OpenAPI=공개 API / Codehelp=코드 매핑 / Ksystem=ksystem 본체 / Filehelp=파일 헬퍼."
+        },
+        "UseTable":      { "type": "string", "examples": ["BIZ", "FLEX"], "description": "테이블 유형 코드. 보통 'BIZ' (비즈니스 테이블) / 'FLEX'." },
+        "SelectTable":   { "type": "string", "description": "대상 테이블 이름." },
+        "SPList":        {
+          "type": "array",
+          "description": "스토어드 프로시저 목록. 자동생성된 SP 이름 (예: '_SWFlexARUsualCostAppListQuery'). FlexAPI 모듈에서 흔히 사용.",
+          "items": { "type": "string" }
+        },
+        "UseBundle":     { "type": "boolean", "description": "번들 호출 — 여러 SP 묶음 실행." },
+        "UseSearch":     { "type": "boolean" },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" },
+        "UseInnerBlock": { "type": "boolean" },
+        "BeforeScript":  { "type": "string" }
+      }
+    }
+  ]
+}