flame-plus 1.3.27 → 1.3.29

package/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/node_modules/.pnpm/flame-plus@1.3.26_@element-plus+icons-vue@2.3.2_vue@3.3.4__@interactjs+core@1.10.27_@in_3c4e5d5dc5fd652459cb45b714b2aa3c/node_modules/flame-plus/flameDist/**)",
+      "Bash(pnpm run:*)"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)",
+      "Bash(npm run:*)",
+      "mcp__ide__getDiagnostics",
+      "Bash(cat /Users/albert/Workspaces/poba/flame-plus/node_modules/flame-types/lib/*.d.ts 2>/dev/null | head -30)",
+      "Bash(wc -l /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.vue 2>/dev/null | head -20)",
+      "Bash(ls -la /Users/albert/Workspaces/spark/flame-types/src/ 2>/dev/null || find /Users/albert/Workspaces/spark/flame-types -name \"*.ts\" -o -name \"*.d.ts\" | head -30)",
+      "Bash(cd /Users/albert/Workspaces/spark/flame-types && npm install 2>&1)",
+      "Bash(npm pack:*)",
+      "Bash(cd /Users/albert/Workspaces/poba/flame-plus && npm install /Users/albert/Workspaces/spark/flame-types/flame-types-1.1.7.tgz 2>&1)",
+      "Bash(npm install:*)",
+      "Bash(npx vue-tsc:*)",
+      "Bash(grep -l \"framework.vue\" /Users/albert/.claude/plans/*.md 2>/dev/null | head -5)"
+    ]
+  }
+}

package/cursor_modelvalue_prop_type_check_issue.md

@@ -0,0 +1,102 @@
+# ModelValue prop type check issue
+_Exported on 2026/4/1 at GMT+8 15:24:02 from Cursor (2.6.22)_
+
+---
+
+**User**
+
+排查问题
+
+MasterFormSwitch.vue?t=1775015461216:215 Invalid prop: type check failed for prop "modelValue". Expected Number | Null, got String with value "12". 
+Proxy(Object) {…}
+ at <ElInputNumber>
+at <FlmInputNumber>
+at <ElFormItem>
+at <ElForm>
+at <Anonymous>
+at <BaseTransition>
+at <Transition>
+at <ElCollapseTransition>
+at <ElCollapseItem>
+at <ElCollapse>
+at <FlmCollapse>
+at <FlmDynamicForm>
+at <ElFocusTrap>
+at <ElOverlay>
+at <BaseTransition>
+at <Transition>
+at <Teleport>
+at <ElDrawer>
+at <MasterFormSwitch>
+at <KeepAlive>
+at <RouterView>
+at <AppView>
+at <ElScrollbar>
+at <Layout>
+at <RouterView>
+at <ElConfigProvider>
+at <ConfigGlobal>
+at <App> 
+(28) [{…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}]
+
+
+
+---
+
+**Cursor**
+
+
+正在排查：`ElInputNumber` 的 `modelValue` 需要 `number | null`，但收到了字符串 `"12"`。正在查看 `MasterFormSwitch.vue` 与 `FlmInputNumber` 的数据流。
+
+
+
+
+## 结论
+
+这是 **Element Plus `el-input-number` 的类型校验**：`modelValue` 只能是 `number | null | undefined`，但当前收到的是字符串 **`"12"`**。  
+组件链是：`MasterFormSwitch` → `flm-dynamic-form` → `FlmInputNumber` → `ElInputNumber`。问题出在 **喂给动态表单的 model 里数字字段是字符串**，不是 `MasterFormSwitch` 模板里某一行写错类型。
+
+控制台里 `MasterFormSwitch.vue:215` 多半是 **Vite 带 query 的编译映射**，和源码行号不一定一致；真正相关的逻辑在下面这段。
+
+## 数据从哪来
+
+编辑时 `dynamicFormModel` 来自详情接口解析结果，或退化为表格行：
+
+```353:356:/Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/src/views/SPARKFORM/MasterFormSwitch/MasterFormSwitch.vue
+      dynamicFormModel.value =
+        Object.keys(fromApi).length > 0
+          ? { ...fromApi }
+          : { ...(data && typeof data === 'object' ? data : {}) }
+```
+
+`fromApi` 由 `parseDynamicFormGetDtlItems` 从 `dynamicFormGetDtl` 响应里拆出来，**不会做数字类型转换**，后端/JSON 里经常是 `"12"` 这种字符串：
+
+```289:317:/Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/src/views/SPARKFORM/MasterFormSwitch/MasterFormSwitch.vue
+const parseDynamicFormGetDtlItems = (res: any): Record<string, any> => {
+  // ...
+  if (typeof items === 'object') {
+    const row = (items as any).record ?? (items as any).row ?? items
+    if (row && typeof row === 'object' && !Array.isArray(row)) {
+      return { ...row }
+    }
+  }
+  return {}
+}
+```
+
+新增时 `dynamicFormModel` 先是 `{}`，一般 **不会** 立刻报这个错；**编辑**（或详情为空、走了表格行 `data` 回显）最容易复现。
+
+## 与 flame-plus 的关系
+
+你们仓库里的说明已经对齐根因：`flm-dynamic-form` / grid 把 model 里的值原样塞给控件，`FlmInputNumber` 又原样传给 `ElInputNumber`，**没有**把字符串数字转成 `number`。见 `docs/flame-plus-fix-input-number-string-modelValue.md`。
+
+## 处理思路（择一即可）
+
+1. **业务侧（本页）**：在赋给 `dynamicFormModel` 之前，按表单配置或字段元数据，对 `flmInputNumber` 对应字段做归一（空串/`null` 与 `Number()` 的规则见该文档表格）。  
+2. **组件库侧**：在 flame-plus 的 `FlmInputNumber`（或 grid 赋值处）统一归一 `modelValue`，升级依赖或用 `pnpm patch`。  
+3. **后端**：保证动态详情/列表里数值字段以 JSON number 返回（改动面取决于接口约定）。
+
+若只想先确认，可在 `editData` 里 `console.log(fromApi)` 或打断点，看对应数字字段是否为字符串 `"12"`。
+
+（当前为 Ask 模式，我无法直接改代码；若要我在项目里加归一或 patch，需要切换到 Agent 模式。）
+

package/docs/flame-plus-attrfields-onchange-support.md

@@ -0,0 +1,201 @@
+# FlameFramework attrFields onChange 支持修改文档
+
+## 问题描述
+
+FlameFramework 的 `attrFields` 配置中的 `props.onChange` 回调无法被触发，导致级联选择（项目 → 表 → 字段）无法在属性面板中实现。
+
+## 问题根因
+
+### 文件：`/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue`
+
+在 `controlDom` 函数（约第 215-266 行）中：
+
+```javascript
+const controlDom = (
+  prop: string,
+  controlType: ControlTypes,
+  controlConfig: ControlConfig
+) => {
+  const config: FormModel = { ...controlConfig }
+  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
+  config[event] = (value: any) => formChange(value, prop)  // ⚠️ 这里覆盖了原有的 onChange
+  config['modelValue'] = formModel[prop]
+  // ...
+}
+```
+
+**问题**：`flmForm` 在渲染控件时，**强制覆盖**了 `onChange`/`onInput` 事件处理器，导致 `attrFields.props` 中传入的 `onChange` 回调被替换，永远不会被调用。
+
+## 修改方案
+
+### 方案一：保留原有 onChange 并链式调用（推荐）
+
+修改 `flmForm.vue` 中的 `controlDom` 函数：
+
+```javascript
+const controlDom = (
+  prop: string,
+  controlType: ControlTypes,
+  controlConfig: ControlConfig
+) => {
+  const config: FormModel = { ...controlConfig }
+  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
+
+  // 保存原有的 onChange/onInput 回调
+  const originalHandler = controlConfig[event]
+
+  // 链式调用：先调用内部 formChange，再调用原有回调
+  config[event] = (value: any) => {
+    formChange(value, prop)
+    if (typeof originalHandler === 'function') {
+      originalHandler(value)
+    }
+  }
+
+  config['modelValue'] = formModel[prop]
+
+  // ... 后续代码保持不变
+}
+```
+
+### 方案二：新增 `onValueChange` 专用回调属性
+
+在 `types.ts` 中扩展 `AttrFieldConfig`：
+
+```typescript
+// /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/types.ts
+
+export interface AttrFieldConfig {
+  key: string
+  label: string
+  component: AttrFieldComponent
+  props?: Record<string, unknown>
+  /** 值变化时的回调，不同于 props.onChange，此回调不会被覆盖 */
+  onValueChange?: (value: unknown, model: Record<string, unknown>) => void
+  visible?: (model: Record<string, unknown>) => boolean
+}
+```
+
+然后在 `FrameworkAttrFieldsForm.vue` 中处理：
+
+```javascript
+// FrameworkAttrFieldsForm.vue
+
+const formItems = computed(() => {
+  return visibleFields.value
+    .filter((f) => componentToControlType[f.component])
+    .map((f) => {
+      const controlType = componentToControlType[f.component] as ControlTypes
+      return {
+        prop: f.key,
+        label: f.label,
+        controlType,
+        controlConfig: {
+          ...(f.props ?? {}),
+          'model-value': shadowModel[f.key],
+          // 传递 onValueChange 回调
+          _onValueChange: f.onValueChange
+        }
+      }
+    })
+})
+```
+
+然后在 `flmForm.vue` 中调用：
+
+```javascript
+config[event] = (value: any) => {
+  formChange(value, prop)
+  // 调用自定义回调
+  if (typeof controlConfig._onValueChange === 'function') {
+    controlConfig._onValueChange(value, formModel)
+  }
+}
+```
+
+## 推荐方案：方案一
+
+方案一修改最小，只需修改 `flmForm.vue` 一个文件，且保持向后兼容。
+
+## 修改步骤
+
+### Step 1: 修改 flmForm.vue
+
+文件路径：`/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue`
+
+找到 `controlDom` 函数（约第 215 行），修改如下：
+
+```javascript
+const controlDom = (
+  prop: string,
+  controlType: ControlTypes,
+  controlConfig: ControlConfig
+) => {
+  const config: FormModel = { ...controlConfig }
+  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
+
+  // ====== 新增：保存并链式调用原有回调 ======
+  const originalHandler = controlConfig[event]
+  config[event] = (value: any) => {
+    // 1. 内部表单状态更新
+    formChange(value, prop)
+    // 2. 调用外部传入的回调（如果有）
+    if (typeof originalHandler === 'function') {
+      originalHandler(value)
+    }
+  }
+  // ====== 修改结束 ======
+
+  config['modelValue'] = formModel[prop]
+
+  // ... 后续代码保持不变
+}
+```
+
+### Step 2: 重新构建 flame-plus
+
+```bash
+cd /Users/albert/Workspaces/poba/flame-plus
+pnpm run build
+```
+
+### Step 3: 更新 gmp-frontend 依赖
+
+```bash
+cd /Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform
+pnpm update flame-plus
+```
+
+## 验证方式
+
+修改完成后，在 `MasterForm.vue` 的 `attrFields` 中使用 `onChange`：
+
+```typescript
+attrFields: [
+  {
+    key: 'config.projectName',
+    label: '项目',
+    component: 'select',
+    props: {
+      placeholder: '请选择项目',
+      filterable: true,
+      options: PROJECT_OPTIONS,
+      onChange: (val: string) => {
+        console.log('项目已选择:', val)
+        if (val) loadTableOptions(val)
+      }
+    }
+  },
+  // ...
+]
+```
+
+当用户在属性面板中选择项目时，控制台应输出 `项目已选择: xxx`，并且 `loadTableOptions` 应被调用。
+
+## 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue` | 核心修改文件 |
+| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/components/FrameworkAttrFieldsForm.vue` | attrFields 渲染组件 |
+| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/types.ts` | 类型定义 |

package/docs/framework-dynamic-form-value-retrieval.md

@@ -0,0 +1,153 @@
+# 动态表单取值与提交数据详解
+
+本文说明 **`flmDynamicForm` 运行时**如何汇总各分组数据、数据在 **`flmGridForm`** 中如何维护，以及 **`componentList` 自定义控件**为何必须遵守 `onChange` / `onInput` 契约才能出现在提交结果中。
+
+与外部组件注册、设计器配置形态相关的说明见：[framework-external-components.md](./framework-external-components.md)。
+
+---
+
+## 1. 总览：数据从哪来
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ flmDynamicForm (config.groups + config.buttons)                  │
+│   ├─ type === 'form'  → flmGridForm (每个分组一个实例)              │
+│   │       └─ 内部 reactive: formModel { [prop]: value }          │
+│   └─ type === 'subForm' → flm-sub-form + 本组件内 subFormData     │
+│                                                                  │
+│ 底部按钮 submit/cancel/reset → getDynamicFormData() → emit        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**要点**：
+
+- 动态表单**不会**遍历 DOM 或调用各控件的「取值 API」；**只读 `flmGridForm` 暴露的 `formModel` 与子表单的 `subFormData`**。
+- 任一表单项的值要进提交 payload，必须在用户交互时通过 `flmGridForm` 已注入的回调写进 `formModel[prop]`（见第 3 节）。
+
+---
+
+## 2. 提交时：`getDynamicFormData` 行为
+
+源码：`src/packages/components/complex/flmDynamicForm/flmDynamicForm.vue`。
+
+### 2.1 `type === 'form'` 分组
+
+1. 用分组 **`id`** 在 `formRefs` 里取对应的 **`flmGridForm` 实例**（通过 `ref` 回调挂载）。
+2. 从实例上解析 **`formModel`**（兼容多种 Vue 3 实例形态）：
+
+   - `inst.formModel`
+   - `inst.exposed.formModel`
+   - `inst.$.exposed.formModel`
+   - `inst.$.setupState.formModel`
+
+3. 若当前 `id` 取不到 `formModel`，会**兜底**：在 `formRefs` 里找**第一个**能 `pickFormModel` 成功的实例（多表单分组时若 `id` 不一致可能出现合并错乱，应保证配置里 **`group.id` 与 ref 使用的 id 一致**）。
+4. 将 `formModel` **深拷贝为普通对象**后 **`Object.assign` 到结果根对象**，即：**同一动态表单里多个 `form` 分组的字段会摊平到同一层**；若不同分组出现相同 `prop` 键，**后遍历的分组会覆盖先遍历的**。
+
+### 2.2 `type === 'subForm'` 分组
+
+- 数据来自 **`subFormData[id]`**（与 `flm-sub-form` 的 `v-model` 同步），在结果中为 **`payload[groupId] = 行数组`**，**不摊平到根对象**。
+
+### 2.3 底部按钮与事件参数
+
+- `submit` / `cancel` / `reset`：`emit(event, getDynamicFormData())`，即上述合并后的 **payload**。
+- 其他按钮：`emit('customEvent', { event, data: btn })`，**不带**自动汇总的表单数据；若业务需要当前表单值，需自行 `ref` 动态表单或在外层监听并缓存。
+
+---
+
+## 3. `flmGridForm` 内：`formModel` 如何写入
+
+源码：`src/packages/components/complex/flmGirdForm/flmGridForm.vue`。
+
+### 3.1 核心结构
+
+- `formModel`：`reactive<Record<string, any>>({})`，通过 **`expose({ formModel, reset })`** 暴露给父级。
+- 任意字段更新统一走 **`formChange(value, prop)`** → **`formModel[prop] = value`**。
+
+### 3.2 与配置的双向同步
+
+- **`props.config.model`** 变化时：`updateFormModel` 把外部 model 合并进 `formModel`；`updateControl` 把 `formModel` 同步回各 `controlConfig` 的展示值（`modelValue` 或 `model-value`，由 `isInputControl` 决定）。
+- **`formModel` 变化时：`watch(formModel, …)` → `updateControl`，保证控件 config 上的当前值与模型一致。
+
+### 3.3 表单项 `prop` 即 `formModel` 的键
+
+每个 `items[]` 项有 **`prop`（字符串）**。`controlDom` 里注入回调时使用的就是这个 **`prop`**：
+
+```ts
+;(config as any)[event] = (value: any) => formChange(value, prop)
+```
+
+因此 **提交对象里字段名 = 各表单项的 `prop`**。设计器保存时，`FlameFramework` 通常用控件内部 id 作为 `prop`（如 `ctrl_xxx_时间戳`），业务若需要固定业务字段名，需在**加载配置后映射**或改设计器生成规则（见外部组件指南第 5 节）。
+
+---
+
+## 4. 控件渲染分支与「写回」方式
+
+`controlDom` 对不同类型处理不同，**只有写回路径接上了 `formChange`，值才会进 `formModel`**。
+
+| 类型 / 分支 | 写回方式 |
+|-------------|----------|
+| **`flmInput`** | `config.onInput` → `formChange(value, prop)`（注意不是 `onChange`） |
+| **`flmSearchSelect`** | 单独渲染，使用 `onUpdate` 等，内部再 `formChange` |
+| **`flmDatePicker`** | `onUpdate:modelValue` → `formChange` |
+| **`flmImage` / 上传** | `onUpload` 等 → `formChange` |
+| **`FlmEditor`** | `onUpdate` → `formChange` |
+| **其余（含 `resolveComponent` 自定义）** | 拷贝后的 `config` 上挂 **`onChange`**（非 flmInput）→ `formChange`；渲染 **`<DynamicComp config={config} />`** |
+
+**自定义组件（`componentList` 拖入、保存为某 `controlType`）**落在最后一行：**必须**在用户改值时调用传入的 **`config.onChange(newValue)`**。若错误地只使用 `emit('update:modelValue')` 而父级未绑定，**不会**更新 `formModel`。
+
+若某自定义控件**错误地把 `controlType` 设成 `flmInput`**，则框架会注入 **`onInput`**；此时组件内应调用 **`config.onInput`**，而不是 `onChange`。
+
+---
+
+## 5. 单独使用 `flmGridForm` 时的取值
+
+未包在 `flmDynamicForm` 里时：
+
+- **提交类按钮**：`flmGridForm` 内在校验通过后 **`emit('submit', formModel)`**（引用同一 reactive 对象）。
+- **程序化读取**：父组件通过 **`ref` + `expose`** 拿到子组件实例，读取 **`formModel`**（与 `flmDynamicForm` 的 `pickFormModel` 目标一致）。
+
+`flmDynamicForm` 正是依赖子级 **`expose` 的 `formModel`** 做聚合，而不是依赖 `submit` 事件参数。
+
+---
+
+## 6. 常见问题与排障
+
+### 6.1 基础控件有值，自定义控件提交没有
+
+1. 确认运行时 **`resolveComponent(controlType)`** 能解析到正确组件（全局注册名与 JSON 中 `controlType` 一致）。  
+2. 在自定义组件内确认用户操作后是否调用了 **`config.onChange`**（或 **`config.onInput`** 当类型为 `flmInput`）。  
+3. 确认没有把 `formModel` 当作只读：应通过回调写回，而不是仅本地 `ref`。
+
+### 6.2 多个 `form` 分组字段「串了」或只有一部分有数据
+
+- 检查每个 **`form` 分组的 `id`** 是否与 `flmDynamicForm` 里 `setFormRef(id, el)` 使用的 id 一致。  
+- 若 `id` 缺失或重复，`pickFormModel` 可能走到兜底逻辑，导致读到错误或单个实例。
+
+### 6.3 `prop` 为设计器 id，与后端字段不一致
+
+- 属**配置形态**问题：在加载 JSON 后批量改写 `items[].prop`，或在保存/加载管线做映射；不在 `getDynamicFormData` 内自动转换。
+
+### 6.4 `subForm` 有数据，`form` 没有
+
+- `subForm` 走 **`subFormData`**；`form` 走 **`flmGridForm.formModel`**。两套机制独立，勿混用。
+
+---
+
+## 7. 相关源码索引
+
+| 主题 | 路径 |
+|------|------|
+| 汇总提交、`formRefs`、`pickFormModel`、`getDynamicFormData` | `src/packages/components/complex/flmDynamicForm/flmDynamicForm.vue` |
+| `formModel`、`formChange`、`controlDom`、各特殊分支、`expose` | `src/packages/components/complex/flmGirdForm/flmGridForm.vue` |
+| 保存时 `items[].prop` / `controlType` / `controlConfig` | `src/packages/components/framework/framework.vue` → `buildFrameworkConfig` |
+| 自定义控件契约（注册与设计器） | [framework-external-components.md](./framework-external-components.md) |
+
+---
+
+## 8. 自检清单（取值相关）
+
+- [ ] 自定义控件在变更时调用 **`config.onChange`**（或 **`config.onInput`** 当 `controlType === 'flmInput'`）  
+- [ ] 从 **`config.modelValue` / `config['model-value']`** 读取当前值并与展示同步  
+- [ ] 多 **`form` 分组**时 **`group.id` 唯一且稳定**，与 ref 键一致  
+- [ ] 需要固定业务字段名时，已对 **`items[].prop`** 或 payload 做映射  
+- [ ] **`subForm`** 数据在 payload 中为 **`payload[groupId]`** 数组，而非根级扁平字段  

package/docs/framework-external-components.md

@@ -0,0 +1,182 @@
+# FlameFramework 外部组件接入指南
+
+本文说明**外部系统**如何开发（或封装）Vue 组件，并通过 `componentList` 传入 `FlameFramework`（表单设计器），使设计结果在 **`flmDynamicForm` / `flmGridForm` 运行时**中正确渲染。
+
+**运行时如何汇总表单值、为何自定义控件必须 `onChange`/`onInput`：** 见 [framework-dynamic-form-value-retrieval.md](./framework-dynamic-form-value-retrieval.md)。
+
+---
+
+## 1. 整体流程
+
+1. 在宿主应用中**全局注册**组件，**注册名**必须与表单项里的 `controlType` 字符串**完全一致**（例如 `flmSysUserSelect`）。
+2. 通过 `app.use(FlamePlus, …, [YourComponent])` 或 `app.component(name, YourComponent)` 完成注册（见第 3 节）。
+3. 将预设条目数组传给 `<FlameFramework :component-list="…" />`。
+4. 设计器保存后，配置中的 `items[].controlType` 即为上述名称；运行时由 `flmGridForm` 使用 `resolveComponent(controlType)` 解析。
+
+---
+
+## 2. `componentList` 数据结构
+
+`FlameFramework` 接收可选 prop：`componentList`。每一项在设计器左栏「**组件库**」中显示为可拖拽预设，拖入表单后会与内置默认配置合并。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `key` | `string` | 是 | 列表唯一标识（如 `sys-user-select`），便于外部列表渲染与去重 |
+| `label` | `string` | 是 | 左栏显示名称（如「人员单选」） |
+| `type` | `string` | 是 | **控件类型名**，写入保存结果的 `controlType`，须与全局注册的组件名一致 |
+| `icon` | `string` | 否 | 左栏图标，默认 `🧩` |
+| `defaultConfig` | `Record<string, unknown>` | 否 | 与 `getDefaultConfig(type)` 结果**浅合并**，覆盖默认 `controlConfig` |
+| `defaultFormItem` | 对象 | 否 | 覆盖默认表单项元数据（如 `label`、`required`、`rules`） |
+
+`defaultFormItem` 常用字段与 `FormItemSettings` 对齐，例如：`label`、`required`、`rules`、`labelWidth` 等。
+
+**注意**：源码中 `FrameworkComponentItem.type` 目前标注为 `BasicControlType`（仅内置基础控件）。传入 **`flmSearchSelect`、自定义 `flmXxx`** 等在运行时通常仍可用，但 TypeScript 可能需要 `as any` 或本地扩展类型声明，直至类型定义放宽。
+
+---
+
+## 3. 在宿主应用中注册组件
+
+### 3.1 使用 Flame-Plus `install` 第三参数合并
+
+`install` 会将自定义组件与内置表合并后统一 `app.component(name, component)`：
+
+```ts
+import { createApp } from 'vue'
+import FlamePlus from 'flame-plus'
+import FlmSysUserSelect from './components/FlmSysUserSelect.vue'
+
+const app = createApp(App)
+app.use(FlamePlus, undefined, { FlmSysUserSelect }) // 键名即全局组件名
+```
+
+对象形式下，**对象的 key** 为组件名（须与 `componentList[].type`、`controlType` 一致）。
+
+### 3.2 单独注册
+
+```ts
+app.component('FlmSysUserSelect', FlmSysUserSelect)
+```
+
+未全局注册的 `controlType` 在运行时会解析失败或无法渲染。
+
+---
+
+## 4. 传入 `FlameFramework`
+
+```vue
+<template>
+  <FlameFramework
+    :component-list="systemComponentPresets"
+    @save="onSave"
+  />
+</template>
+
+<script setup lang="ts">
+const systemComponentPresets = [
+  {
+    key: 'sys-user-single',
+    label: '人员（弹窗单选）',
+    icon: '👤',
+    type: 'flmSearchSelect',
+    defaultConfig: {
+      service_name: 'your-service',
+      fk_table_name: 'your_person_table',
+      placeholder: '请选择人员'
+    },
+    defaultFormItem: { label: '人员' }
+  },
+  {
+    key: 'sys-dept-tree',
+    label: '部门（下拉）',
+    type: 'flmSelect',
+    defaultConfig: {
+      placeholder: '请选择部门',
+      options: [],
+      clearable: true
+    },
+    defaultFormItem: { label: '部门' }
+  }
+]
+</script>
+```
+
+`defaultConfig` 的内容即落库后的 `controlConfig` 初始值（设计器内还可继续改）。
+
+---
+
+## 5. 保存结果中的表单项形态
+
+设计器 `save` 事件抛出配置，其中表单分组下的 `items` 与 `FormConfig['items']` 一致。每个控件对应一项，核心字段包括：
+
+- `prop`：设计器生成的控件 id（字符串），**业务侧若需固定字段名，应在加载配置后做映射或在二次开发设计器中改生成规则**。
+- `controlType`：与 `componentList[].type` / 全局组件名一致。
+- `controlConfig`：控件配置快照（含 `model-value` 等）。
+- `gridX` / `gridY` / `gridW` / `gridH`：栅格布局（默认 24 列）。
+
+运行时由 `flmDynamicForm` → `flmGridForm` 根据 `controlType` 渲染。
+
+---
+
+## 6. 自定义控件与 `flmGridForm` 的契约
+
+`flmGridForm` 对**大部分**控件采用统一方式（非 `flmInput`、`flmSearchSelect`、`flmDatePicker`、`flmImage`、`FlmEditor` 等特殊分支）：
+
+- 渲染为：`<YourComponent config={mergedConfig} />`
+- `mergedConfig` 在原有 `controlConfig` 基础上会注入：
+  - `modelValue`：来自 `controlConfig['model-value']`
+  - **`onChange`**：表单写入用（`flmInput` 类型使用 **`onInput`** 而非 `onChange`）
+
+因此，**推荐**自定义控件与内置 `flmSelect` 等保持一致：
+
+1. **Props**：声明 `config: Object`（或具体类型）。
+2. **取值**：从 `config['model-value']` 或 `config.modelValue` 读取当前值（以你方 `filterConfig` 习惯为准）。
+3. **改值**：用户操作后调用 **`config.onChange?.(newValue)`**（若为输入类且走 `flmInput` 分支则调用 **`config.onInput`**——自定义类型一般不会走 `flmInput` 分支，用 `onChange` 即可）。
+
+若控件需要 `isSearch` 等额外 props，需在 `flmGridForm` 增加分支或复用现有特殊类型模式；**默认动态分支不会传递 `isSearch`**。
+
+### 6.1 与 `flmSearchSelect` 对齐的特殊协议
+
+若 `controlType` 为 `flmSearchSelect`，`flmGridForm` 会单独传 `onUpdate`、合并 `ref` 等，**不能**仅靠通用 `config` 协议实现，需直接使用或封装 `flmSearchSelect`。
+
+---
+
+## 7. 表单设计器画布（设计态）限制
+
+设计区内预览使用 `FormDesignArea` 内置的 `controlComponents` 映射：**仅内置基础控件有真实预览**。未在映射表中的 `type` 会**回退为 `flmInput` 占位**，不影响已保存 JSON 在 **`flmGridForm` 运行态**的解析，但设计时视觉与内置控件不一致。
+
+可选改进方向（需改本库）：
+
+- 为 `flmSearchSelect` 等补充映射；或
+- 为 `FormDesignArea` 增加可选 prop，合并外部传入的 `type → 组件` 表。
+
+---
+
+## 8. 与 `flame-types` / `ControlTypes`
+
+消费端若使用 TypeScript 维护表单配置，内置枚举见包内 `ControlTypes`。**自定义 `controlType` 不会出现在枚举中**，可：
+
+- 使用 `string` 扩展类型；或
+- 在业务侧声明：`type ControlType = ControlTypes | 'FlmSysUserSelect' | …`。
+
+---
+
+## 9. 自检清单
+
+- [ ] 全局注册名与 `componentList[].type`、`items[].controlType` 一致  
+- [ ] 自定义组件实现 `config` + `onChange`（或对齐 `flmSearchSelect` 等特殊协议）  
+- [ ] 宿主已安装 `flame-request`、`element-plus` 等依赖（若组件内部使用）  
+- [ ] 接受设计器画布对非内置 `type` 可能显示为输入框占位  
+- [ ] 保存后的 `prop` 为设计器 id，业务落库字段映射方案已明确  
+
+---
+
+## 10. 相关源码位置（本仓库）
+
+| 内容 | 路径 |
+|------|------|
+| `componentList` prop 与 `componentWidgetList` | `src/packages/components/framework/framework.vue` |
+| 保存时 `controlType` / `controlConfig` 生成 | `buildFrameworkConfig`（同文件） |
+| 左栏「组件库」 | `src/packages/components/framework/components/WidgetPanel.vue` |
+| 设计区控件映射 | `src/packages/components/framework/components/FormDesignArea.vue` |
+| 运行时解析与事件注入 | `src/packages/components/complex/flmGirdForm/flmGridForm.vue` |
+| 全局注册合并 | `src/packages/index.ts` → `install` |