@microi.net/cli 5.5.9 → 5.6.1

package/skills/microi-form-engine/SKILL.md

@@ -44,6 +44,23 @@ MySQL 的 `ALTER COLUMN DROP DEFAULT` 会让可空列也在省略字段时报 13
 6. 绑定菜单后补齐/允许平台推断列表列、搜索列、隐藏列、排序列、移动端列和默认排序。
 7. 回读 `diy_field`、刷新 schema 缓存，再在真实新增/编辑/查看表单中验收。
 
+## 原生查询主库策略
+
+- 对不能接受副本延迟的权限关系等表，显式配置 `diy_table.ReadPrimary=1`；普通表保持
+  `NULL/0`。只能从可信表元数据选择连接，禁止让查询请求的 `ReadPrimary`、`TableModel`
+  或 `DataBaseId` 控制主库/副本。此配置不扩大菜单、表、记录或字段权限。
+- 原生 Get、List、Count/CountBatch、SUM 批量与回退、Tree 子计数和 Export 必须共用
+  目标表所属数据库的 writer 选择；扩展库不得误回租户基础库。主库不可用或配置非法必须
+  失败，不能以副本或0计数伪装成功。直接调用 `V8.DbRead` 的语义不变。
+- 显式 `DbTrans` 保留，不为主库策略跳出事务；父事务旧 RR 快照仍可能看见旧授权关系，
+  不能声称仅开启本字段就实现与撤权原子串行。需要实时授权时采用独立受控主库身份读取。
+- 标准 `microi_create_table`、`microi_update_table` 和 Manifest `tables[].readPrimary`
+  支持 `null/0/1`，省略保持已有配置，显式 `null` 清回缺省。先升级后端并安装正式表单
+  引擎字段，再配置；不通过定制 `.NET` 启动迁移或原始 SQL 补字段。
+- 元数据冷回源使用主库，写后清表缓存并回读。验收分别证明字段定义、可空物理列、配置值、
+  普通身份真实 Rows/Count/SUM/Tree/Export 与撤权边界；离线会话选择测试不能冒充复制延迟
+  或七种数据库实机测试。所有新普通表字段保持可空，不把已有表批量设为主库。
+
 ## 上传字段配置（AI 生成时强制）
 
 - 图片使用 `Config.ImgUpload`，至少明确 `Limit`、`Multiple`、`MaxCount`、`Preview`、
@@ -100,10 +117,17 @@ Drawer 只服务超长复杂表单，不能作为所有 CRUD 模块的模板默
 - 兼容旧模块 Hero 时仅迁移视觉、`Source=Field` 或显式记录作用域指标；列表总数、分类数量和
   未引用当前 `Form/RecordId` 的全局接口统计不得进入单记录 Banner，缺省时回到当前记录和
   授权 `TableChild` 的语义统计。
-- 未配置的存量表由运行时按字段类型智能推断，不能因为物理字段为空而隐藏或展示空壳。
-  只有 `FormBannerEnabled=0` 才隐藏。
+- 未配置的存量表由运行时按字段类型智能推断，不能因为物理字段为空而隐藏或展示空壳。
+  只有 `FormBannerEnabled=0` 才隐藏。
+- 字段绑定须区分省略/`NULL` 与显式空字符串：`titleField/subtitleField/imageField/backgroundField`
+  省略或 `NULL` 表示未选择，允许兼容推断；显式 `""` 表示不绑定该字段，不能被推断值或旧别名
+  覆盖。取消标题/图片字段后仍保留表单名称/默认图标回退。完整验收须同时使用包含该语义的 MCP
+  与平台前端，逐项回读空字符串并验证实际表单；不能只看到写入 `Code=1` 就宣称生效。
 - 完整系统 Manifest 使用 `tables[].formBanner`；未提供时 `microi_generate_system` 仍须写入
-  类型感知的默认值。逐步创建字段后调用 `microi_configure_form_banner` 并回读验证。
+  类型感知的默认值。逐步创建字段后调用 `microi_configure_form_banner` 并回读验证。
+- `microi_generate_system` 的最终验收与 `microi_validate_system` 必须逐表回读 Banner 语义字段；
+  写入返回成功、结构验收 `Code=1` 都不能代替已持久化配置，`Data.Passed=false` 仍视为失败。
+  旧库缺少 Banner 物理列时先完成平台正式升级，再配置和重新验收，不直接执行 SQL 补列。
 - 表单设计器验收必须覆盖有/无图片、有/无统计、子表完整聚合、接口失败回退、浅色、深色、
   PC 和窄屏，并检查文字对比度以及不存在技术字段伪统计。
 

package/skills/microi-form-engine/references/component-catalog.md

@@ -1,218 +1,218 @@
-# 表单组件目录
-
-控件名称以
-`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`
-为当前事实源；物理类型以服务器/MCP 允许类型为准。
-
-## 基础输入
-
-| Component | 用途 | 推荐物理类型 |
-|---|---|---|
-| `Text` | 单行文本 | `varchar(200)` |
-| `Guid` | GUID/只读标识 | `varchar(50)` |
-| `Textarea` | 多行文本 | `mediumtext` |
-| `NumberText` | 整数/金额/小数 | `int` 或 `decimal(18,2)` |
-| `DateTime` | 日期时间选择 | `varchar(25)` |
-| `Select` | 下拉单选 | `varchar(50)` |
-| `MultipleSelect` | 下拉多选 | `varchar(500)` 或 `mediumtext` |
-| `Radio` | 单选 | `varchar(50)` |
-| `Checkbox` | 多选 | `varchar(500)` 或 `mediumtext` |
-| `Switch` | 0/1 开关 | `int` |
-| `Rate` | 评分 | `int` |
-| `Progress` | 进度展示/输入 | `int` |
-| `Slider` | 滑块 | `int` 或 `decimal(18,2)` |
-| `ColorPicker` | 颜色 | `varchar(50)` |
-| `AutoNumber` | 自动编号 | `varchar(200)` |
-| `Button` | 表单动作按钮 | 通常 `varchar(50)`，不承载核心业务值 |
-
-## 布局与内容
-
-| Component | 用途 | 规则 |
-|---|---|---|
-| `Divider` | 分割线 | 布局字段，不进入关键查询 |
-| `CollapseGroup` | 局部分组折叠 | 先读 `microi-form-layout` |
-| `Tabs` | 字段级页签布局 | 整体多分区优先 `diy_table.Tabs` |
-| `Alert` | 提示说明 | 不承载业务状态 |
-| `StaticText` | 静态文本 | 不承载业务状态 |
-| `Html` | 可信 HTML 展示 | 必须净化，不拼接不可信内容 |
-| `RichText` | 富文本 | `mediumtext`；输出需净化 |
-| `CodeEditor` | 代码/JSON/SQL 编辑 | `mediumtext`；通常 `FormWidth=24`；长配置表单使用 `Config.CodeEditor.DisplayMode=Dialog`，默认只渲染“编辑代码（N字）”按钮；代码工作台可用 `Inline` |
-| `JsonTable` | JSON 表格 | `mediumtext`；定义结构与大小上限 |
-
-## 文件与高级输入
-
-| Component | 用途 | 推荐物理类型 |
-|---|---|---|
-| `ImgUpload` | 图片上传 | `mediumtext` |
-| `FileUpload` | 文件上传 | `mediumtext` |
-| `Autocomplete` | 自动完成 | `varchar(200)` |
-| `TagInput` | 标签集合 | `varchar(500)` 或 `mediumtext` |
-| `Transfer` | 穿梭框多选 | `mediumtext` |
-| `Cascader` | 级联选择 | `varchar(500)` |
-| `Address` | 省市区地址 | `varchar(500)` |
-| `Department` | 部门选择 | `varchar(50)` |
-| `SelectTree` | 树形选择 | `varchar(50)` 或 `varchar(500)` |
-| `TreeCheckbox` | 树形权限多选 | `mediumtext` |
-
-## 关联、地图与扩展
-
-| Component | 用途 | 关键约束 |
-|---|---|---|
-| `OpenTable` | 弹出列表选择 | 配置保存字段、显示字段和固定查询范围 |
-| `JoinTable` | 关联集合展示 | 查询与权限在服务端完成 |
-| `JoinForm` | 嵌入一个独立记录的完整表单 | 主表字段保存一个目标 Id；目标表不能与当前表相同 |
-| `TableChild` | 主表内嵌 0..N 条明细列表 | 独立子表、子表真实外键、隐藏子菜单、回查索引 |
-| `Map` | 点位 | 高德/百度/腾讯；`Config.MapCompany=System/AMap/Baidu/Tencent`；凭据只进租户“安全与服务接入”，不得写字段配置或公开 SysConfig |
-| `MapArea` | 区域 | 与 `Map` 共用供应商安全配置；`mediumtext` 保存 `Paths`，限制路径、点数和体积 |
-| `Qrcode` | 二维码卡片展示 | 优先 `IsVirtual=1`；扫码原文另存普通 `varchar` 字段 |
-| `FontAwesome` | 图标选择 | `varchar(200)` |
-| `DevComponent` | 主前端定制 Vue 控件 | 仅用于长期复用且标准控件无法满足的场景 |
-
-### `Map / MapArea` 运行时与安全边界
-
-- 渲染事实源是 `Microi.Client/src/views/form-engine/diy-field-component/diy-map.vue`；公共错误分类与安全配置请求在同目录 `map-runtime.js`。
-- 字段只保存 `Config.MapCompany`，值为 `System / AMap / Baidu / Tencent`。禁止把 Key、securityJsCode、Secret 或代理凭据写入 `diy_field.Config`、V8 前端事件、公开 `sys_config` 投影或前端构建变量。
-- 租户凭据使用 `mci_system_setting` 的 `Map.*` 模板，在“系统设置 → 安全与服务接入”由超级管理员维护。运行时由可信后端按 DiyToken 租户和当前供应商做白名单投影，只返回一家的 `ClientKey`，必须 `no-store` 并拒绝访问密钥会话。
-- 旧 `sys_config.AMapKey / AMapSecret / BaiduAK` 仅在对应新设置未启用时兼容回退。不要为迁移直接重新公开这些字段。
-- 旧字段 `Config` 中的 `MapKey / MapSecret / AMapKey / AMapSecret / BaiduAK / TencentMapKey` 等明文属性不属于运行时配置；设计器保存地图配置时必须清除。迁移顺序固定为“先写入并启用租户 `Map.*` Secret，再清理字段元数据”。
-- 浏览器 JS Key 天然可见，必须配置供应商域名/Referer 白名单；高德生产环境优先配置 `Map.AMap.ServiceHost`，存在代理时不得再返回 `SecurityJsCode`。
-- 加载中、缺少 Key、运行时接口不匹配、SDK 网络/超时/鉴权/域名/WebGL/容器尺寸错误必须在控件区域显示明确原因码和重试入口，禁止只 `console.warn/error` 后留下空白地图。
-- `Map` 保持 `{Name}_Lng / {Name}_Lat / {Name}.{Address,Center,Zoom}`；`MapArea` 保持 `{Name}.{Paths,Center,Zoom}`。三家供应商切换不得改变持久化格式。
-
-### `JoinForm` 不是子表
-
-- `JoinForm` 渲染 `diy-form`，通过 `Config.JoinForm.JoinFieldName` 从当前表单取出一个
-  目标记录 Id（也可用固定 `Id` / `_SearchEqual`），因此表达的是“这一条记录关联哪一条
-  独立记录”。当前表和目标表相同会被组件判为无效并拒绝渲染。
-- `TableChild` 渲染 `diy-table`，通过 `Config.TableChildFkFieldName` 把子表列表限定在
-  当前父记录，并依赖 `TableChildTableId` 与 `TableChildSysMenuId` 完成列表和行级增删改。
-- `TableChild` 控件字段通常不承担关系存储；真正的关系列位于子表，例如
-  `order_detail.OrderId`。不得创建主表 `DetailId` 后用 `JoinForm` 冒充明细。
-- 生成前先问“一个父记录最多有几条目标记录”：答案可能大于 1 就选 `TableChild`；只有
-  明确恰好一个目标 Id 且需要嵌入完整目标表单时才选 `JoinForm`。不确定时先询问，不写入。
-
-### `Qrcode` 的数据契约
-
-- 字段 `Config.Qrcode` 只保存 `DisplayWidth`、`ShowDownload`、`DownloadText` 等外观项，
-  不指定扫码内容。表单运行态必须通过
-  `V8.FieldSet('<字段名>', 'DataAppend', payload)` 提供数据。
-- `payload.Code` 为必填扫码原文，兼容小写 `code`；可选 `title`、`titleValue`、
-  `fields:[{Label,Value}]`（或旧版 `DataConfig:[{label,key}]`）、`Color`、
-  `CardColor`、`FileName/fileName`、`createTime`。
-- 在 `InFormV8` 中设置时必须跳过 `V8.LoadMode === 'Design'`，否则设计器保存可能把
-  运行态 `DataAppend` 固化到字段模型。
-- 表单控件会生成 PNG Data URL 并回写控件值以兼容旧页面。纯展示字段优先设
-  `IsVirtual=1`；若历史表已有物理字段，则通过 `V8.NotSaveField` 排除保存。不要把 Base64
-  图片写入短 `varchar`。需要持久化时保存原始 URL/编号，再把它传给 `Code`。
-- 列表二维码列直接渲染原始字段值；表单二维码卡片读取 `DataAppend.Code`，两种场景不得
-  混为同一输入协议。
-- 二维码中的 URL 仍需服务端鉴权，不得嵌入 DiyToken、访问密钥或长期业务秘密。
-
-```js
-if (V8.LoadMode !== 'Design') {
-  V8.FieldSet('Qrcode116', 'DataAppend', {
-    Code: V8.Form.OrderNo || V8.Form.Id || 'https://microi.net',
-    title: '订单二维码',
-    titleValue: V8.Form.OrderNo || '',
-    fields: [{ Label: '客户：', Value: V8.Form.CustomerName || '' }],
-    FileName: '订单-' + (V8.Form.OrderNo || '二维码')
-  });
-}
-```
-
-## 官网历史名称
-
-中文官网可能仍展示 `PhoneSMS`、`Timeline` 等历史/业务扩展控件。生成新字段前
-必须在当前 `diy-component-list.json`、目标租户 `diy_field.Component` 和实际客户端
-中核对；未出现在当前控件清单的名称不得仅凭旧文档直接生成。
-
-## 常用配置键
-
-这些是 `diy_field.Config` 内的配置路径，不是可调用函数；保存后必须回读
-`Config` 并刷新 Schema 缓存：
-
-| 组件族 | 常用配置路径 |
-|---|---|
-| Textarea | `Textarea.DefaultRows` |
-| TagInput | `TagInput.Placeholder`、`TagInput.Options`、`TagInput.MaxCount` |
-| Transfer | `Transfer.LeftTitle`、`Transfer.RightTitle`、`Transfer.Filterable`、`Transfer.Options` |
-| AutoNumber | `AutoNumber.DataRule`、`AutoNumber.CreateRule`，以及 `AutoNumberFixed`、`AutoNumberLength`、`AutoNumberFields` |
-| Button | `Button.Type`、`Button.Icon`、`Button.Size`、`Button.PreviewCanClick`、`Button.RefreshTableAfterClick`、`Button.Loading`（`V8.FieldSet` 时使用 `Config.Button.Loading`） |
-| Divider / StaticText | `Divider.Icon`、`StaticText.Content` |
-| OpenTable | `OpenTable.BtnName`、`OpenTable.MultipleSelect`、`OpenTable.BeforeOpenV8`、`OpenTable.SubmitV8` |
-| CodeEditor / JsonTable | `CodeEditor.Height`、`JsonTable.Columns`、`JsonTable.Columns[].Config` |
-| JoinForm | `JoinForm.TableId`、`JoinForm.TableName`、`JoinForm.JoinFieldName`、`JoinForm.FormMode`、`JoinForm.Id`、`JoinForm._SearchEqual` |
-| TableChild | Config 根节点的 `TableChildTableId`、`TableChildSysMenuId`、`TableChildFkFieldName`；`TableChild.PrimaryTableFieldName`（默认 `Id`）及分页/导入选项 |
-| ImgUpload | `ImgUpload.Limit/Multiple/MaxCount/Tips/Preview/MaxSize/SaveFullPath`；`ImgUpload.Crop.Enabled` 仅表示默认开启，另有 `Mode=free/fixed/select`、`Ratio`、`CustomWidth/CustomHeight`、`AllowZoom/AllowRotate/AllowFlip`；运行时在上传面板内提供裁剪开关，裁剪弹层提供“不裁剪直接上传”；导出时会按最大图片数展开列 |
-| FileUpload | `FileUpload.Limit/Multiple/MaxCount/Tips/MaxSize/SaveFullPath`，以及 Office 预览/编辑/版本配置；文件不使用 `ImgUpload.Preview/Crop` |
-| RichText | `RichText.Limit`；`Image.Enabled/MaxSize/MaxCount/Preview/CompressMaxSize/CompressMaxWidth`；`Video.Enabled/MaxSize/MaxCount`；`File.Enabled/MaxSize/MaxCount/Accept`；私有正文存稳定标识而不是临时 URL |
-| Qrcode | `Qrcode.DisplayWidth`、`Qrcode.ShowDownload`、`Qrcode.DownloadText`；扫码内容使用运行态 `DataAppend.Code` |
-
-其余选择、树、上传、关联和布局选项以当前字段设计器和
-`microi-db-schema/references/form-component-options.md` 为事实源；不要凭旧截图
-发明配置键。
-
-### `ImgUpload / FileUpload` 生成与运行时规则
-
-```json
-{
-  "ImgUpload": {
-    "Limit": true,
-    "Multiple": true,
-    "MaxCount": 6,
-    "Tips": "支持 JPG、PNG、WebP",
-    "Preview": true,
-    "MaxSize": 10,
-    "SaveFullPath": false,
-    "Crop": {
-      "Enabled": true,
-      "Mode": "select",
-      "Ratio": "16:9",
-      "CustomWidth": 1,
-      "CustomHeight": 1,
-      "AllowZoom": true,
-      "AllowRotate": true,
-      "AllowFlip": true
-    }
-  }
-}
-```
-
-- `Limit=true` 表示字段配置为私有桶，`false` 表示配置为公有桶。普通用户有当前表单新增/编辑权限时也按此权威配置执行；运行时提交表、字段、菜单、记录上下文，后端回读 `diy_field.Config`，不得信任客户端 `Limit/Path`，也不得按用户等级统一强制私有。
-- `Multiple=true` 时 `MaxCount` 必须是正整数；`MaxSize` 单位为 MB。`Preview` 未配置时按 `true` 压缩，普通列表、卡片、商品图不要关闭。
-- `Crop.Enabled` 只决定运行时裁剪开关的初始状态；`false` 或缺失时用户仍可在紧凑上传面板主动开启。裁剪前原图始终进入 HDFS 私有桶，业务字段只保存展示图元数据。
-- 图片和文件都把拖放提示、存储范围、单/多文件、最大数量、处理方式和最大体积合并到同一个紧凑面板；不要在字段外再生成重复说明卡片。
-
-### `RichText` 生成与运行时规则
-
-```json
-{
-  "RichText": {
-    "EditorProduct": "WangEditor",
-    "Limit": true,
-    "Image": {
-      "Enabled": true,
-      "MaxSize": 20,
-      "MaxCount": 10,
-      "Preview": true,
-      "CompressMaxSize": 500,
-      "CompressMaxWidth": 1920
-    },
-    "Video": { "Enabled": true, "MaxSize": 200, "MaxCount": 3 },
-    "File": { "Enabled": true, "MaxSize": 100, "MaxCount": 10, "Accept": "" }
-  }
-}
-```
-
-- 公开公告、商品详情等匿名网页内容显式用 `Limit=false`；内部公告、合同说明等用 `true`。旧字段缺失时默认私有，不能由 AI 猜成公有。
-- 普通用户经当前表单新增/编辑授权后可以发布公有 RichText；后端按字段权威配置选择桶。缺少 `FormEngineKey/FieldId` 等可验证上下文的普通上传仍保持私有，不能用裸 `Limit=false` 代替授权。
-- `MaxSize` 单位 MB，`CompressMaxSize` 单位 KB。图片压缩开启时原图仍先进入 HDFS 私有桶，正文只引用展示图。
-- 私有正文只保存 `/__microi_richtext_private__/...` 稳定标识；运行时携带当前菜单、表、记录和字段上下文换取短效代理 URL，禁止把临时 Token/Ticket 回写字段。
-- 普通文件通过富文本工具栏附件入口插入 `a.href`；私有授权只接受真实 `img/video/source.src` 与 `a.href` 的精确路径，不接受正文文字、`data-*` 或脚本标签。
-- RichText 通常使用 `FormWidth=24`，配置摘要保持单行紧凑，不要再生成独立的大说明卡。
-
-## 宽度与重字段
-
-- 普通 Text、Select、NumberText、DateTime 默认不写 `FormWidth`。
-- Textarea、RichText、CodeEditor、JsonTable、上传、子表、地图、布局和定制组件通常 `FormWidth=24`。
-- 列表默认隐藏上传、富文本、地图、子表、布局等重字段；按需在详情中加载。
+# 表单组件目录
+
+控件名称以
+`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`
+为当前事实源；物理类型以服务器/MCP 允许类型为准。
+
+## 基础输入
+
+| Component | 用途 | 推荐物理类型 |
+|---|---|---|
+| `Text` | 单行文本 | `varchar(200)` |
+| `Guid` | GUID/只读标识 | `varchar(50)` |
+| `Textarea` | 多行文本 | `mediumtext` |
+| `NumberText` | 整数/金额/小数 | `int` 或 `decimal(18,2)` |
+| `DateTime` | 日期时间选择 | `varchar(25)` |
+| `Select` | 下拉单选 | `varchar(50)` |
+| `MultipleSelect` | 下拉多选 | `varchar(500)` 或 `mediumtext` |
+| `Radio` | 单选 | `varchar(50)` |
+| `Checkbox` | 多选 | `varchar(500)` 或 `mediumtext` |
+| `Switch` | 0/1 开关 | `int` |
+| `Rate` | 评分 | `int` |
+| `Progress` | 进度展示/输入 | `int` |
+| `Slider` | 滑块 | `int` 或 `decimal(18,2)` |
+| `ColorPicker` | 颜色 | `varchar(50)` |
+| `AutoNumber` | 自动编号 | `varchar(200)` |
+| `Button` | 表单动作按钮 | 通常 `varchar(50)`，不承载核心业务值 |
+
+## 布局与内容
+
+| Component | 用途 | 规则 |
+|---|---|---|
+| `Divider` | 分割线 | 布局字段，不进入关键查询 |
+| `CollapseGroup` | 局部分组折叠 | 先读 `microi-form-layout` |
+| `Tabs` | 字段级页签布局 | 整体多分区优先 `diy_table.Tabs` |
+| `Alert` | 提示说明 | 不承载业务状态 |
+| `StaticText` | 静态文本 | 不承载业务状态 |
+| `Html` | 可信 HTML 展示 | 必须净化，不拼接不可信内容 |
+| `RichText` | 富文本 | `mediumtext`；输出需净化 |
+| `CodeEditor` | 代码/JSON/SQL 编辑 | `mediumtext`；通常 `FormWidth=24`；长配置表单使用 `Config.CodeEditor.DisplayMode=Dialog`，默认只渲染“编辑代码（N字）”按钮；代码工作台可用 `Inline` |
+| `JsonTable` | JSON 表格 | `mediumtext`；定义结构与大小上限 |
+
+## 文件与高级输入
+
+| Component | 用途 | 推荐物理类型 |
+|---|---|---|
+| `ImgUpload` | 图片上传 | `mediumtext` |
+| `FileUpload` | 文件上传 | `mediumtext` |
+| `Autocomplete` | 自动完成 | `varchar(200)` |
+| `TagInput` | 标签集合 | `varchar(500)` 或 `mediumtext` |
+| `Transfer` | 穿梭框多选 | `mediumtext` |
+| `Cascader` | 级联选择 | `varchar(500)` |
+| `Address` | 省市区地址 | `varchar(500)` |
+| `Department` | 部门选择 | `varchar(50)` |
+| `SelectTree` | 树形选择 | `varchar(50)` 或 `varchar(500)` |
+| `TreeCheckbox` | 树形权限多选 | `mediumtext` |
+
+## 关联、地图与扩展
+
+| Component | 用途 | 关键约束 |
+|---|---|---|
+| `OpenTable` | 弹出列表选择 | 配置保存字段、显示字段和固定查询范围 |
+| `JoinTable` | 关联集合展示 | 查询与权限在服务端完成 |
+| `JoinForm` | 嵌入一个独立记录的完整表单 | 主表字段保存一个目标 Id；目标表不能与当前表相同 |
+| `TableChild` | 主表内嵌 0..N 条明细列表 | 独立子表、子表真实外键、隐藏子菜单、回查索引 |
+| `Map` | 点位 | 高德/百度/腾讯；`Config.MapCompany=System/AMap/Baidu/Tencent`；凭据只进租户“安全与服务接入”，不得写字段配置或公开 SysConfig |
+| `MapArea` | 区域 | 与 `Map` 共用供应商安全配置；`mediumtext` 保存 `Paths`，限制路径、点数和体积 |
+| `Qrcode` | 二维码卡片展示 | 优先 `IsVirtual=1`；扫码原文另存普通 `varchar` 字段 |
+| `FontAwesome` | 图标选择 | `varchar(200)` |
+| `DevComponent` | 主前端定制 Vue 控件 | 仅用于长期复用且标准控件无法满足的场景 |
+
+### `Map / MapArea` 运行时与安全边界
+
+- 渲染事实源是 `Microi.Client/src/views/form-engine/diy-field-component/diy-map.vue`；公共错误分类与安全配置请求在同目录 `map-runtime.js`。
+- 字段只保存 `Config.MapCompany`，值为 `System / AMap / Baidu / Tencent`。禁止把 Key、securityJsCode、Secret 或代理凭据写入 `diy_field.Config`、V8 前端事件、公开 `sys_config` 投影或前端构建变量。
+- 租户凭据使用 `mci_system_setting` 的 `Map.*` 模板，在“系统设置 → 安全与服务接入”由超级管理员维护。运行时由可信后端按 DiyToken 租户和当前供应商做白名单投影，只返回一家的 `ClientKey`，必须 `no-store` 并拒绝访问密钥会话。
+- 旧 `sys_config.AMapKey / AMapSecret / BaiduAK` 仅在对应新设置未启用时兼容回退。不要为迁移直接重新公开这些字段。
+- 旧字段 `Config` 中的 `MapKey / MapSecret / AMapKey / AMapSecret / BaiduAK / TencentMapKey` 等明文属性不属于运行时配置；设计器保存地图配置时必须清除。迁移顺序固定为“先写入并启用租户 `Map.*` Secret，再清理字段元数据”。
+- 浏览器 JS Key 天然可见，必须配置供应商域名/Referer 白名单；高德生产环境优先配置 `Map.AMap.ServiceHost`，存在代理时不得再返回 `SecurityJsCode`。
+- 加载中、缺少 Key、运行时接口不匹配、SDK 网络/超时/鉴权/域名/WebGL/容器尺寸错误必须在控件区域显示明确原因码和重试入口，禁止只 `console.warn/error` 后留下空白地图。
+- `Map` 保持 `{Name}_Lng / {Name}_Lat / {Name}.{Address,Center,Zoom}`；`MapArea` 保持 `{Name}.{Paths,Center,Zoom}`。三家供应商切换不得改变持久化格式。
+
+### `JoinForm` 不是子表
+
+- `JoinForm` 渲染 `diy-form`，通过 `Config.JoinForm.JoinFieldName` 从当前表单取出一个
+  目标记录 Id（也可用固定 `Id` / `_SearchEqual`），因此表达的是“这一条记录关联哪一条
+  独立记录”。当前表和目标表相同会被组件判为无效并拒绝渲染。
+- `TableChild` 渲染 `diy-table`，通过 `Config.TableChildFkFieldName` 把子表列表限定在
+  当前父记录，并依赖 `TableChildTableId` 与 `TableChildSysMenuId` 完成列表和行级增删改。
+- `TableChild` 控件字段通常不承担关系存储；真正的关系列位于子表，例如
+  `order_detail.OrderId`。不得创建主表 `DetailId` 后用 `JoinForm` 冒充明细。
+- 生成前先问“一个父记录最多有几条目标记录”：答案可能大于 1 就选 `TableChild`；只有
+  明确恰好一个目标 Id 且需要嵌入完整目标表单时才选 `JoinForm`。不确定时先询问，不写入。
+
+### `Qrcode` 的数据契约
+
+- 字段 `Config.Qrcode` 只保存 `DisplayWidth`、`ShowDownload`、`DownloadText` 等外观项，
+  不指定扫码内容。表单运行态必须通过
+  `V8.FieldSet('<字段名>', 'DataAppend', payload)` 提供数据。
+- `payload.Code` 为必填扫码原文，兼容小写 `code`；可选 `title`、`titleValue`、
+  `fields:[{Label,Value}]`（或旧版 `DataConfig:[{label,key}]`）、`Color`、
+  `CardColor`、`FileName/fileName`、`createTime`。
+- 在 `InFormV8` 中设置时必须跳过 `V8.LoadMode === 'Design'`，否则设计器保存可能把
+  运行态 `DataAppend` 固化到字段模型。
+- 表单控件会生成 PNG Data URL 并回写控件值以兼容旧页面。纯展示字段优先设
+  `IsVirtual=1`；若历史表已有物理字段，则通过 `V8.NotSaveField` 排除保存。不要把 Base64
+  图片写入短 `varchar`。需要持久化时保存原始 URL/编号，再把它传给 `Code`。
+- 列表二维码列直接渲染原始字段值；表单二维码卡片读取 `DataAppend.Code`，两种场景不得
+  混为同一输入协议。
+- 二维码中的 URL 仍需服务端鉴权，不得嵌入 DiyToken、访问密钥或长期业务秘密。
+
+```js
+if (V8.LoadMode !== 'Design') {
+  V8.FieldSet('Qrcode116', 'DataAppend', {
+    Code: V8.Form.OrderNo || V8.Form.Id || 'https://microi.net',
+    title: '订单二维码',
+    titleValue: V8.Form.OrderNo || '',
+    fields: [{ Label: '客户：', Value: V8.Form.CustomerName || '' }],
+    FileName: '订单-' + (V8.Form.OrderNo || '二维码')
+  });
+}
+```
+
+## 官网历史名称
+
+中文官网可能仍展示 `PhoneSMS`、`Timeline` 等历史/业务扩展控件。生成新字段前
+必须在当前 `diy-component-list.json`、目标租户 `diy_field.Component` 和实际客户端
+中核对；未出现在当前控件清单的名称不得仅凭旧文档直接生成。
+
+## 常用配置键
+
+这些是 `diy_field.Config` 内的配置路径，不是可调用函数；保存后必须回读
+`Config` 并刷新 Schema 缓存：
+
+| 组件族 | 常用配置路径 |
+|---|---|
+| Textarea | `Textarea.DefaultRows` |
+| TagInput | `TagInput.Placeholder`、`TagInput.Options`、`TagInput.MaxCount` |
+| Transfer | `Transfer.LeftTitle`、`Transfer.RightTitle`、`Transfer.Filterable`、`Transfer.Options` |
+| AutoNumber | `AutoNumber.DataRule`、`AutoNumber.CreateRule`，以及 `AutoNumberFixed`、`AutoNumberLength`、`AutoNumberFields` |
+| Button | `Button.Type`、`Button.Icon`、`Button.Size`、`Button.PreviewCanClick`、`Button.RefreshTableAfterClick`、`Button.Loading`（`V8.FieldSet` 时使用 `Config.Button.Loading`） |
+| Divider / StaticText | `Divider.Icon`、`StaticText.Content` |
+| OpenTable | `OpenTable.BtnName`、`OpenTable.MultipleSelect`、`OpenTable.BeforeOpenV8`、`OpenTable.SubmitV8` |
+| CodeEditor / JsonTable | `CodeEditor.Height`、`JsonTable.Columns`、`JsonTable.Columns[].Config` |
+| JoinForm | `JoinForm.TableId`、`JoinForm.TableName`、`JoinForm.JoinFieldName`、`JoinForm.FormMode`、`JoinForm.Id`、`JoinForm._SearchEqual` |
+| TableChild | Config 根节点的 `TableChildTableId`、`TableChildSysMenuId`、`TableChildFkFieldName`；`TableChild.PrimaryTableFieldName`（默认 `Id`）及分页/导入选项 |
+| ImgUpload | `ImgUpload.Limit/Multiple/MaxCount/Tips/Preview/MaxSize/SaveFullPath`；`ImgUpload.Crop.Enabled` 仅表示默认开启，另有 `Mode=free/fixed/select`、`Ratio`、`CustomWidth/CustomHeight`、`AllowZoom/AllowRotate/AllowFlip`；运行时在上传面板内提供裁剪开关，裁剪弹层提供“不裁剪直接上传”；导出时会按最大图片数展开列 |
+| FileUpload | `FileUpload.Limit/Multiple/MaxCount/Tips/MaxSize/SaveFullPath`，以及 Office 预览/编辑/版本配置；文件不使用 `ImgUpload.Preview/Crop` |
+| RichText | `RichText.Limit`；`Image.Enabled/MaxSize/MaxCount/Preview/CompressMaxSize/CompressMaxWidth`；`Video.Enabled/MaxSize/MaxCount`；`File.Enabled/MaxSize/MaxCount/Accept`；私有正文存稳定标识而不是临时 URL |
+| Qrcode | `Qrcode.DisplayWidth`、`Qrcode.ShowDownload`、`Qrcode.DownloadText`；扫码内容使用运行态 `DataAppend.Code` |
+
+其余选择、树、上传、关联和布局选项以当前字段设计器和
+`microi-db-schema/references/form-component-options.md` 为事实源；不要凭旧截图
+发明配置键。
+
+### `ImgUpload / FileUpload` 生成与运行时规则
+
+```json
+{
+  "ImgUpload": {
+    "Limit": true,
+    "Multiple": true,
+    "MaxCount": 6,
+    "Tips": "支持 JPG、PNG、WebP",
+    "Preview": true,
+    "MaxSize": 10,
+    "SaveFullPath": false,
+    "Crop": {
+      "Enabled": true,
+      "Mode": "select",
+      "Ratio": "16:9",
+      "CustomWidth": 1,
+      "CustomHeight": 1,
+      "AllowZoom": true,
+      "AllowRotate": true,
+      "AllowFlip": true
+    }
+  }
+}
+```
+
+- `Limit=true` 表示字段配置为私有桶，`false` 表示配置为公有桶。普通用户有当前表单新增/编辑权限时也按此权威配置执行；运行时提交表、字段、菜单、记录上下文，后端回读 `diy_field.Config`，不得信任客户端 `Limit/Path`，也不得按用户等级统一强制私有。
+- `Multiple=true` 时 `MaxCount` 必须是正整数；`MaxSize` 单位为 MB。`Preview` 未配置时按 `true` 压缩，普通列表、卡片、商品图不要关闭。
+- `Crop.Enabled` 只决定运行时裁剪开关的初始状态；`false` 或缺失时用户仍可在紧凑上传面板主动开启。裁剪前原图始终进入 HDFS 私有桶，业务字段只保存展示图元数据。
+- 图片和文件都把拖放提示、存储范围、单/多文件、最大数量、处理方式和最大体积合并到同一个紧凑面板；不要在字段外再生成重复说明卡片。
+
+### `RichText` 生成与运行时规则
+
+```json
+{
+  "RichText": {
+    "EditorProduct": "WangEditor",
+    "Limit": true,
+    "Image": {
+      "Enabled": true,
+      "MaxSize": 20,
+      "MaxCount": 10,
+      "Preview": true,
+      "CompressMaxSize": 500,
+      "CompressMaxWidth": 1920
+    },
+    "Video": { "Enabled": true, "MaxSize": 200, "MaxCount": 3 },
+    "File": { "Enabled": true, "MaxSize": 100, "MaxCount": 10, "Accept": "" }
+  }
+}
+```
+
+- 公开公告、商品详情等匿名网页内容显式用 `Limit=false`；内部公告、合同说明等用 `true`。旧字段缺失时默认私有，不能由 AI 猜成公有。
+- 普通用户经当前表单新增/编辑授权后可以发布公有 RichText；后端按字段权威配置选择桶。缺少 `FormEngineKey/FieldId` 等可验证上下文的普通上传仍保持私有，不能用裸 `Limit=false` 代替授权。
+- `MaxSize` 单位 MB，`CompressMaxSize` 单位 KB。图片压缩开启时原图仍先进入 HDFS 私有桶，正文只引用展示图。
+- 私有正文只保存 `/__microi_richtext_private__/...` 稳定标识；运行时携带当前菜单、表、记录和字段上下文换取短效代理 URL，禁止把临时 Token/Ticket 回写字段。
+- 普通文件通过富文本工具栏附件入口插入 `a.href`；私有授权只接受真实 `img/video/source.src` 与 `a.href` 的精确路径，不接受正文文字、`data-*` 或脚本标签。
+- RichText 通常使用 `FormWidth=24`，配置摘要保持单行紧凑，不要再生成独立的大说明卡。
+
+## 宽度与重字段
+
+- 普通 Text、Select、NumberText、DateTime 默认不写 `FormWidth`。
+- Textarea、RichText、CodeEditor、JsonTable、上传、子表、地图、布局和定制组件通常 `FormWidth=24`。
+- 列表默认隐藏上传、富文本、地图、子表、布局等重字段；按需在详情中加载。