@flextudio/scenario 0.1.0

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

@@ -0,0 +1,125 @@
+# Firestore Service (Firestore.schema.json)
+
+Google Firestore 직접 연동. 테넌트 설정의 Firebase Admin 정보 기반.
+
+> **참고**: [docs.flextudio.com — Firestore](https://docs.flextudio.com/flextudio/scenario/dev-mode/service/firestore).
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+
+## 1. 사용 시점
+
+- NoSQL 컬렉션 데이터 조회/추가/수정/삭제.
+- Firebase Admin 인증 기반 — 백엔드 구성 없이 직접 연동.
+
+## 2. 식별 필드
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"Firestore"` (고정) | const |
+| `ModuleID` | `Query` / `Save` / `Update` / `Delete` | enum 4종 |
+| `Collection` | string | Firestore 컬렉션 명칭 (서비스 대상) |
+
+## 3. ModuleID 4종 — 작업별 데이터 흐름 (docs.flextudio.com)
+
+| 모듈 | 보내는 데이터 | 받는 데이터 | Firestore 매핑 |
+|---|---|---|---|
+| `Query` | **ParamBlock1 의 첫 번째 섹터** = 검색 조건 | 조회된 데이터 | `collection().where(...).get()` |
+| `Save` | **ParamBlock1 의 모든 섹터** → 새 문서로 생성 (그대로 저장) | 저장된 문서의 `_SUID` | `collection().add({...})` |
+| `Update` | **ParamBlock1 의 모든 섹터** → 업데이트 조건 따라 수정 | 업데이트된 문서의 `_SUID` | `doc(id).update({...})` |
+| `Delete` | **ParamBlock1 의 모든 섹터** → 식별자로 사용해 삭제 | 삭제된 문서의 `_SUID` | `doc(id).delete()` |
+
+## 4. Query — 정렬 + 검색
+
+### 4.1 지원 연산자
+
+| 연산자 | 의미 |
+|---|---|
+| `==` / `!=` | 같음 / 같지 않음 (FlexAutoQuery 의 `=`/`!=` 와 다름) |
+| `<` / `<=` / `>` / `>=` | 비교 |
+
+> ⚠️ Firestore 는 `LIKE` / `NOT LIKE` / `IS NULL` 미지원. 부분 일치는 별도 인덱스 텍스트 검색.
+
+### 4.2 정렬 + 검색 동시 사용
+
+> **인덱스 등록 필요**. [Firestore 색인 등록 페이지](https://console.firebase.google.com/project/_/firestore/indexes) 에서 미리 설정.
+> 정렬 기준 필드 + 검색 조건 필드가 다르면 복합 인덱스 필수.
+
+```jsonc
+"Filters": [
+  { "FilterType": "Condition", "ConditionOperators": "==",
+    "ConditionKey": "category", "ConditionValue": "{%_c.search[0].category%}" }
+]
+```
+
+## 5. Update — 두 가지 타입
+
+| Update 타입 | 동작 |
+|---|---|
+| **전체 수정** | 보낸 데이터로 문서 전체 덮어쓰기 |
+| **부분 수정** | 지정된 필드만 수정 |
+
+### 5.1 Update Value 타입
+
+| 타입 | 의미 |
+|---|---|
+| **컬렉션키** | ParamBlock 의 컬렉션키 값으로 필드 업데이트 |
+| **FieldValue 함수** | Firestore `FieldValue` 함수 사용 |
+
+### 5.2 FieldValue 함수
+
+| 함수 | 동작 |
+|---|---|
+| `increment(1)` | 값 +1 증가 |
+| `increment(-1)` | 값 -1 감소 |
+| `delete()` | 해당 필드를 문서에서 삭제 |
+
+## 6. 형태
+
+```jsonc
+"ServiceBinding": {
+  "getCou": {
+    "SystemID":       "Firestore",
+    "ModuleID":       "Query",
+    "Collection":     "ideationList",
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true,
+    "UseInnerBlock":  true,
+    "UseSearch":      false,
+    "NotSeperateInnerBlock": true
+  }
+}
+```
+
+## 7. ParamBlock → Firestore 쿼리 변환
+
+| ParamBlock 필드 | Firestore 변환 |
+|---|---|
+| `Filters[FilterType:'Condition']` | `.where(ConditionKey, ConditionOperators, ConditionValue)` |
+| `Filters[FilterType:'Status']` | (런타임에서 status 필드로 변환) |
+| `UserData[]` | 인증된 사용자 컨텍스트로 자동 필터 (예: `where('userId', '==', currentUserId)`) |
+
+## 8. ResultBlocks 매핑
+
+| TargetType | Firestore 동작 |
+|---|---|
+| `replace` | 카테고리 전체를 결과 docs 로 교체 |
+| `add` | 결과 docs 를 기존 섹터 끝에 append |
+| `merge` | `PKeys` (Firestore docId 가능) 기준 병합 |
+
+## 9. UseSearch
+
+`UseSearch: true` 로 설정 시 Firestore 의 인덱스 기반 텍스트 검색 활성화. 기본 false.
+
+## 10. API 연동 흐름
+
+```
+[1] Action='Service' SystemID='Firestore' → Firestore 라우팅
+[2] ModuleID 별 분기 (Query/Save/Update/Delete)
+[3] ParamBlocks → Firestore 쿼리 변환
+[4] Firestore 응답 → ResultBlocks 카테고리 반영 (+ _SUID)
+```
+
+## 11. 인증
+
+`_base.User.fBaseUserNo` 컨텍스트가 Firestore Authentication 사용자와 매핑. UserData 에 인증 키 포함 시 자동으로 `where('uid', '==', ...)` 적용.

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/Firestore.schema.json",
+  "title": "Firestore ServiceBinding",
+  "description": "Google Firestore 서비스 호출 정의. SystemID='Firestore' 고정. ModuleID 로 작업 종류 식별 (Query / Save / Update / Delete).",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "Firestore" },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["Query", "Save", "Update", "Delete"],
+          "description": "Firestore 작업 종류. Query=조회 / Save=신규 저장 / Update=업데이트 / Delete=삭제."
+        },
+        "Collection":     { "type": "string", "description": "Firestore 컬렉션 명칭 (서비스 대상)." },
+        "UseSearch":      { "type": "boolean", "description": "검색 모드 토글. true 면 인덱스 기반 텍스트 검색 활성화 (정렬+검색 동시 사용 시 복합 인덱스 등록 필요)." },
+        "UsePKey":        { "type": "boolean" },
+        "UseParamBlock":  { "type": "boolean" },
+        "UseResultBlock": { "type": "boolean" },
+        "UseInnerBlock":  { "type": "boolean" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,128 @@
+# FlexAutoQuery Service (FlexAutoQuery.schema.json)
+
+`SystemID:'FlexAutoQuery'` — FlexSQL 없이 **FlexDB 자동생성 테이블에 대한 CRUD 자동 구성**. 카테고리 연결/수정 시 "AI로 DB연결하기" 로 생성된 테이블 전용.
+
+> **참고**: [docs.flextudio.com — FlexAutoQuery](https://docs.flextudio.com/flextudio/scenario/dev-mode/service/flexautoquery), flextudio-guide §6.8.
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+> **Business 플랜 이상** 필요.
+
+## 1. 사용 시점
+
+- "AI로 DB연결하기" 로 자동생성된 테이블의 단순 CRUD.
+- 별도 SQL 작성 없이 빠른 조회/저장/갱신/삭제.
+- **새로 추가되는 컬럼은 자동 연결 끊어짐** — 추가 컬럼 사용하려면 FlexSQL 갱신 필요.
+
+## 2. 자동생성 테이블의 기본 컬럼
+
+| 컬럼 | 타입 | 의미 |
+|---|---|---|
+| `DataSeq` | number | 자동 증가 PK |
+| `CreateDate` | datetime | 생성 시각 |
+| `CreateUserID` | string | 생성자 |
+| `UpdateDate` | datetime | 갱신 시각 |
+| `UpdateUserID` | string | 갱신자 |
+| `TenantID` | string | 테넌트 식별자 (멀티테넌트) |
+
+## 3. 식별 필드
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"FlexAutoQuery"` (고정) | const |
+| `ModuleID` | `"Default"` | const.js 상 단일 모듈 |
+| `ServiceType` | `Query` / `Save` / `Update` / `Delete` | 서비스 유형 |
+| `TargetTable` | string | 자동생성 테이블 이름 |
+| `OrderBy` / `OrderDirection` | string | 정렬 (Query 전용) |
+
+## 4. 서비스 유형 4종 (docs.flextudio.com)
+
+| 유형 | 동작 | 보내는 데이터 | 받는 데이터 |
+|---|---|---|---|
+| `Query` | SELECT | **ParamBlock1 의 첫 번째 섹터** = 검색 조건 | 조회된 데이터 |
+| `Save` | INSERT | **ParamBlock1 의 모든 섹터** (테이블 컬럼명과 일치 항목만) | 저장된 데이터 + `_SUID` |
+| `Update` | UPDATE | **ParamBlock1 의 모든 섹터** (컬럼명 일치 항목만) | 업데이트 결과 + `_SUID` |
+| `Delete` | DELETE | **ParamBlock1 의 모든 섹터** | 삭제 결과 + `_SUID` |
+
+> **테이블 컬럼명과 일치하는 항목만 자동 매핑** — 컬렉션의 다른 필드는 무시됨.
+
+## 5. Query — 검색 (3가지 모드)
+
+### 5.1 키워드 검색
+
+지원 연산자 (FlexAutoQuery 전용 — Firestore 의 `==` 와 다름):
+
+| 연산자 | 의미 |
+|---|---|
+| `=` / `!=` | 같음 / 같지 않음 |
+| `<` / `<=` / `>` / `>=` | 비교 |
+| `LIKE` / `NOT LIKE` | 부분 일치 |
+| `IS NULL` / `IS NOT NULL` | NULL 체크 |
+
+```jsonc
+"Filters": [
+  { "FilterType": "Condition", "ConditionOperators": "LIKE",
+    "ConditionKey": "Title", "ConditionValue": "{%_c.searchInput[0].keyword%}" }
+]
+```
+
+### 5.2 기간 검색
+
+시작일/종료일 컬렉션 키 지정.
+
+```jsonc
+"Filters": [
+  { "FilterType": "Condition", "ConditionOperators": ">=",
+    "ConditionKey": "CreateDate", "ConditionValue": "{%_c.search[0].StartDate%}" },
+  { "FilterType": "Condition", "ConditionOperators": "<=",
+    "ConditionKey": "CreateDate", "ConditionValue": "{%_c.search[0].EndDate%}" }
+]
+```
+
+### 5.3 작성자 검색
+
+서비스 호출자의 UserID 와 `CreateUserID` 컬럼 비교 (자동).
+
+```jsonc
+"Filters": [
+  { "FilterType": "Condition", "ConditionOperators": "=",
+    "ConditionKey": "CreateUserID", "ConditionValue": "{%_base.User.fBaseUserNo%}" }
+]
+```
+
+### 5.4 정렬 순서
+
+`OrderBy` + `OrderDirection` (ASC/DESC) 를 ServiceBinding 에 직접 박음.
+
+## 6. 형태
+
+```jsonc
+"ServiceBinding": {
+  "queryProducts": {
+    "SystemID":       "FlexAutoQuery",
+    "ModuleID":       "Default",
+    "ServiceType":    "Query",
+    "TargetTable":    "Product",
+    "OrderBy":        "CreateDate",
+    "OrderDirection": "DESC",
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true,
+    "UseInnerBlock":  true
+  }
+}
+```
+
+## 7. FlexSQL 자동생성
+
+FlexAutoQuery 설정 값에 따라 내부적으로 FlexSQL 이 자동 생성됨. 새 컬럼 추가 시 이 자동 생성 FlexSQL 과의 연결이 끊어지므로, **수동으로 FlexSQL 업데이트 필요**.
+
+## 8. ksystem 과의 차이
+
+| 항목 | FlexAutoQuery | ksystem (FlexAPI) |
+|---|---|---|
+| SystemID | `'FlexAutoQuery'` | `'ksystem'` |
+| ModuleID | `'Default'` | `'FlexAPI'` |
+| 추상화 수준 | 높음 (ServiceType + TargetTable) | 낮음 (SP 이름 직접 지정) |
+| 호출 방식 | 자동 CRUD | SPList 의 SP 호출 |
+
+자세한 ksystem 정의는 [`ksystem.md`](ksystem.md) 참조.

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

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/FlexAutoQuery.schema.json",
+  "title": "FlexAutoQuery ServiceBinding",
+  "description": "FlexAutoQuery 서비스 호출 정의. const.js 의 SYSTEM_ID.FLEXAUTOQUERY='FlexAutoQuery' 에 매핑. FlexSQL 없이 FlexDB '자동생성 테이블 (AI로 DB연결하기)' 에 대한 CRUD 자동 구성. flextudio-guide §6.8 / FlexAutoQuery. Business+ 플랜.",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "FlexAutoQuery", "description": "FlexAutoQuery 호출 시 'FlexAutoQuery' 고정." },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["Default"],
+          "description": "FlexAutoQuery 모듈 — const.js 상 'Default' 단일."
+        },
+        "ServiceType": {
+          "type": "string",
+          "enum": ["Query", "Save", "Update", "Delete"],
+          "description": "FlexAutoQuery 서비스 유형 4종 (조회/저장/업데이트/삭제)."
+        },
+        "TargetTable":      { "type": "string", "description": "자동생성 테이블 이름." },
+        "OrderBy":          { "type": "string", "description": "정렬 기준 컬럼명 (Query 전용)." },
+        "OrderDirection":   { "type": "string", "enum": ["ASC", "DESC", ""], "description": "정렬 순서." },
+        "UsePKey":          { "type": "boolean" },
+        "UseParamBlock":    { "type": "boolean" },
+        "UseResultBlock":   { "type": "boolean" },
+        "UseInnerBlock":    { "type": "boolean" },
+        "BeforeScript":     { "type": "string" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,96 @@
+# FlexSQL Service (FlexSQL.schema.json)
+
+워크스페이스 콘솔에 **사용자가 등록한 SQL 쿼리** 를 시나리오에서 호출. FlexDB 또는 외부 DB와 연동.
+
+> **참고**: [docs.flextudio.com — FlexSQL](https://docs.flextudio.com/flextudio/scenario/dev-mode/service/flexsql), flextudio-guide §6.7.
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단. 운영 메타 검증 시 `strict_no_service:false`.
+
+## 1. 사용 시점
+
+- DB (FlexDB / MySQL / Azure MSSQL) 에서 데이터 조회/저장/갱신/삭제.
+- Business 플랜 이상 필요.
+- Before Script / After Script 로 전후처리.
+
+## 2. 식별 필드
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"FlexSQL"` (고정) | const |
+| `ModuleID` | `"Default"` | 다중 모듈 환경에서만 다른 값 |
+| `ServiceName` | `"FlexSQL"` (보통) | 표기용 |
+| `SQLServiceName` | `<시나리오명>:<서비스명>` | 콜론 1 개. 예: `"메인화면:showReceiveWho"`, `"Ideation:getDetail"` |
+| `MajorVersion` | `1` 또는 `2` | FlexSQL 메이저 버전 |
+
+## 3. 형태
+
+```jsonc
+"ServiceBinding": {
+  "showReceiveWho_S": {
+    "SystemID":         "FlexSQL",
+    "ModuleID":         "Default",
+    "ServiceName":      "FlexSQL",
+    "SQLServiceName":   "메인화면:showReceiveWho",
+    "MajorVersion":     1,
+    "ExternalDB":       true,
+    "SetCategory":      true,
+    "UsePKey":          true,
+    "UseParamBlock":    true,
+    "UseResultBlock":   true,
+    "UseInnerBlock":    true,
+    "NotSeperateInnerBlock": true,
+    "BeforeScript":     "",
+    "ResultScript":     ""
+  }
+}
+```
+
+## 4. ParamBlocks / ResultBlocks
+
+표준 형식 — [`../events.md §2.3.1 / §2.3.2`](../events.md) 와 동일.
+
+```jsonc
+"ParamBlocks": [
+  {
+    "CategoryName": "questionList",
+    "UseFilter":    true,
+    "Filters":      [{ "FilterType": "Status", "Status": ["active"] }]
+  }
+],
+"ResultBlocks": [
+  { "TargetType": "replace", "CategoryName": "showReceiveWho" }
+]
+```
+
+## 5. Before / After Script
+
+> **paramBlock / resultBlocks 는 이차원 배열** (docs.flextudio.com 명시). `paramBlock[i][j]` = i번째 ParamBlock 의 j번째 섹터. 스크립트 안에서 직접 수정 가능 — 별도 반환 없이 그대로 호출에 사용된다.
+
+```jsonc
+"BeforeScript": "paramBlock[0][0].UserSeq = _base.User.fBaseUserNo;",
+"ResultScript": "resultBlocks[0].forEach(r => { r.DisplayName = r.FirstName + ' ' + r.LastName; });"
+```
+
+| 스크립트 | 시점 | 입력 변수 | 동작 |
+|---|---|---|---|
+| `BeforeScript` | SQL 호출 전 | `paramBlock[i][j]` (이차원 배열) | 내부 값 직접 수정 → 수정된 paramBlock 으로 SQL 실행 |
+| `ResultScript` | SQL 호출 후 | `resultBlocks[i][j]` (이차원 배열) | 내부 값 직접 수정 → 변경된 resultBlocks 가 별도 반환 없이 컬렉션에 바로 반영 |
+
+두 스크립트 모두 **서버 측에서 실행** (클라이언트 아님).
+
+## 6. API 연동 흐름
+
+```
+[1] 클라이언트 Action='Service' → 서버 라우팅
+[2] BeforeScript 실행 (_param 변환)
+[3] SQLServiceName 으로 등록된 SQL 실행 (FlexDB / 외부 RDB)
+[4] ResultScript 실행 (_result 후처리)
+[5] 응답 → 클라이언트 ResultBlocks.TargetType 에 따라 컬렉션 반영
+```
+
+## 7. 검증 규칙 (스키마 강제)
+
+| 규칙 | 동작 |
+|---|---|
+| `SystemID === 'FlexSQL'` const | 다른 SystemID 면 분기 미적용 |
+| `SQLServiceName` 필수 + `:` 포함 | 콜론 1개 이상 (`pattern: ".+:.+"`) |
+| `additionalProperties: true` | forward-compat — 운영 메타의 추가 키 허용 |

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

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/FlexSQL.schema.json",
+  "title": "FlexSQL ServiceBinding",
+  "description": "FlexSQL 서비스 호출 정의. 워크스페이스 콘솔에 등록된 SQL 쿼리를 시나리오 명:서비스 명 형식으로 호출. flextudio-guide §6.7. SystemID 'FlexSQL' 고정.",
+  "type": "object",
+  "required": ["SystemID", "SQLServiceName"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID":         { "const": "FlexSQL", "description": "FlexSQL 호출 시 'FlexSQL' 고정." },
+        "ModuleID":         { "type": "string", "description": "보통 'Default'. 다중 모듈 환경에서만 다른 값." },
+        "ServiceName":      { "type": "string", "description": "FlexSQL 표기 이름 (보통 'FlexSQL' 고정)." },
+        "SQLServiceName":   {
+          "type": "string",
+          "minLength": 1,
+          "pattern": ".+:.+",
+          "description": "FlexSQL 서비스 식별자. 형식: `<시나리오/그룹명>:<서비스명>` (예: `메인화면:showReceiveWho`, `Ideation:getDetail`). 콜론 1 개 필수."
+        },
+        "MajorVersion":     { "type": "integer", "minimum": 1, "description": "FlexSQL 메이저 버전 (정수, 보통 1 또는 2)." },
+        "ExternalDB":       { "type": "boolean", "description": "외부 DB 연결 사용 여부. 프로퍼티 SWITCH 가 boolean 저장." },
+        "UsePKey":          { "type": "boolean" },
+        "UseParamBlock":    { "type": "boolean" },
+        "UseResultBlock":   { "type": "boolean" },
+        "UseInnerBlock":    { "type": "boolean" },
+        "BeforeScript":     { "type": "string", "description": "Before Script — SQL 호출 전 전처리 (param 가공 등)." },
+        "ResultScript":     { "type": "string", "description": "After Script — SQL 결과 후처리 (반환 데이터 가공)." }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,161 @@
+# Flextudio API Service (Flextudio API.schema.json)
+
+`SystemID:'Flextudio API'` (공백 포함) — Flextudio 사용자/메시지/그룹 도메인의 **REST API** 호출. const.js `SYSTEM_ID.FLEXTUDIO_API='Flextudio API'`. `flexApiKey` 인증 기반.
+
+런타임 구현: [`public/system/flextudio/flextudio_api.js`](../../../../public/system/flextudio/flextudio_api.js).
+
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+> **`Flextudio` ([`Flextudio.md`](Flextudio.md)) 와 다름!** `flexApiKey` 가 필수, REST 호출 형태. ModuleID 도 다름 (User/Message/Group ↔ GetUserList/QueryMessage/SendMessage).
+
+## 1. ModuleID + SubModuleID 매트릭스
+
+| ModuleID | SubModuleID | HTTP | Path | 의미 |
+|---|---|---|---|---|
+| `User` | `Query` | GET | `/v1/company/{companyID}/users` | 사용자 목록 조회 (검색/페이지네이션 지원) |
+| `User` | `Save` | POST | `/v1/company/{companyID}/users` | 사용자 신규 등록 |
+| `User` | `Update` | PATCH | `/v1/company/{companyID}/users` | 사용자 갱신 |
+| `User` | `Delete` | DELETE | `/v1/company/{companyID}/users/{...}` | 사용자 삭제 |
+| `Message` | `Query` | GET | `/v1/app/message` | 메시지 조회 (읽지 않음 필터 옵션) |
+| `Group` | `UserQuery` | GET | `/v1/company/{companyID}/groups/{groupName}/users` | 특정 그룹의 회원 조회 |
+
+> SubModuleID 는 메타에서 별도 `SubModuleID` 필드로 박힌다 (`SB_SUB_MODULE_ID="SubModuleID"`).
+
+## 2. 식별 필드 (필수)
+
+| 필드 | 값 | 비고 |
+|---|---|---|
+| `SystemID` | `"Flextudio API"` (공백 포함, 고정) | const |
+| `ModuleID` | `User` / `Message` / `Group` | enum |
+| `SubModuleID` | 위 표 참조 | ModuleID 별 분기 |
+| `flexApiKey` | string | **필수** — HTTP 헤더 `x-flex-api-key` 로 전송 |
+
+## 3. 모듈별 추가 속성 (const.js K_FLEXTUDIO_API_PROP)
+
+| 속성 | 적용 모듈 | 의미 |
+|---|---|---|
+| `flexApiKey` | 모두 | API 인증 키 (필수) |
+| `useUserAppGrant` | User Save | 현재 앱 사용 권한 자동 부여 (`_base.appid` 함께 전송) |
+| `UseSearch` | User Query | 검색 모드 토글 |
+| `SearchItem[]` | User Query | 검색 조건 배열 (`UseSearch:true` 일 때) |
+| `UseUnreadMessage` | Message Query | 읽지 않은 메시지만 |
+| `groupName` | Group UserQuery (필수) | 대상 그룹 이름 (`{% %}` 표현식 가능) |
+
+### 3.1 SearchItem 구조
+
+```jsonc
+"SearchItem": [
+  { "FieldName": "DepartmentSeq",  "SearchFilter": "==",       "FieldValue": "deptSeq" },
+  { "FieldName": "Name",           "SearchFilter": "contains", "FieldValue": "keyword" }
+]
+```
+
+| 필드 | 의미 |
+|---|---|
+| `FieldName` | 서버 필드명 |
+| `SearchFilter` | 연산자 — `contains` / `!contains` / `exists` / `!exists` / `==` / `!=` / `<` / `<=` / `>` / `>=` (const.js `K_FLEXTUDIO_API_USER_FILTER`) |
+| `FieldValue` | sector(섹터) 의 키 이름 — 그 키의 값으로 비교 |
+
+## 4. 형태 — User Query (검색 + 페이지네이션)
+
+```jsonc
+"ServiceBinding": {
+  "QueryActiveUsers": {
+    "SystemID":     "Flextudio API",
+    "ModuleID":     "User",
+    "SubModuleID":  "Query",
+    "flexApiKey":   "{% _base.flextudio.flexApiKey %}",
+    "UseSearch":    true,
+    "SearchItem": [
+      { "FieldName": "Status", "SearchFilter": "==", "FieldValue": "userStatus" }
+    ],
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true
+  }
+}
+```
+
+호출 측 Action:
+
+```jsonc
+{
+  "Action":         "Service",
+  "ServiceBinding": "QueryActiveUsers",
+  "ServiceName":    "QueryActiveUsers",
+  "SystemID":       "Flextudio API",
+  "ParamBlocks":    [
+    {
+      "CategoryName": "queryFilter",
+      "UseFilter":    false
+    }
+  ],
+  "ResultBlocks":   [
+    { "TargetType": "replace", "CategoryName": "userList" }
+  ]
+}
+```
+
+## 5. 형태 — User Save (앱 권한 자동 부여)
+
+```jsonc
+{
+  "SystemID":         "Flextudio API",
+  "ModuleID":         "User",
+  "SubModuleID":      "Save",
+  "flexApiKey":       "{% _base.flextudio.flexApiKey %}",
+  "useUserAppGrant":  true
+}
+```
+
+ParamBlock1 의 모든 섹터가 `body.userData` 로 직렬화되어 POST 발송.
+
+## 6. 형태 — Group UserQuery (특정 그룹 회원 조회)
+
+```jsonc
+{
+  "SystemID":     "Flextudio API",
+  "ModuleID":     "Group",
+  "SubModuleID":  "UserQuery",
+  "flexApiKey":   "{% _base.flextudio.flexApiKey %}",
+  "groupName":    "{%_c.activeGroup[0].groupName%}"
+}
+```
+
+## 7. 모듈별 데이터 흐름
+
+| 모듈/SubModule | 보내는 데이터 | 받는 데이터 |
+|---|---|---|
+| `User.Query` | ParamBlock1[0][0] 의 첫 섹터 → 쿼리 파라미터 | `Items[]` + `pagination` (별도 ResultBlock 으로) |
+| `User.Save` | ParamBlock1 의 모든 섹터 → `body.userData` | 저장된 사용자 목록 |
+| `User.Update` | ParamBlock1 의 모든 섹터 → `body.userData` | 갱신된 사용자 목록 |
+| `User.Delete` | ParamBlock1[0] → URL path 의 사용자 ID | 삭제 결과 |
+| `Message.Query` | ParamBlock1[0][0] → 쿼리 파라미터 (UseUnreadMessage 옵션) | `Items[]` |
+| `Group.UserQuery` | (ParamBlock 미사용) | `Items[]` (그룹 회원 목록) |
+
+## 8. 인증 / 헤더
+
+| HTTP 헤더 | 값 |
+|---|---|
+| `Content-Type` | `application/json` |
+| `x-flex-api-key` | `flexApiKey` 의 값 |
+| `fRequestID` | 자동 발급 |
+| `Flex-Offline` | `methodMeta.flexOffline` (선택, 오프라인 큐 모드) |
+| `Flex-Submission` | (선택) 오프라인 모드 한정 |
+| `Flex-Source` | (선택) |
+| `Flex-Mapper` | JSON.stringify(매퍼) (선택) |
+
+## 9. 검증 규칙 (스키마 강제)
+
+| 규칙 | 동작 |
+|---|---|
+| `SystemID === 'Flextudio API'` const | 공백 포함 정확 일치 |
+| `ModuleID` enum 3종 | `User` / `Message` / `Group` |
+| `flexApiKey` minLength 1 | 빈 키 거부 |
+| `User` 모듈 → `SubModuleID` ∈ `Query`/`Save`/`Update`/`Delete` 필수 | if/then |
+| `Message` 모듈 → `SubModuleID:'Query'` 필수 | if/then |
+| `Group` 모듈 → `SubModuleID:'UserQuery'` + `groupName` 필수 | if/then |
+
+## 10. `Flextudio` vs `Flextudio API` 비교
+
+자세한 비교는 [`Flextudio.md §6`](Flextudio.md) 참조.