@microi.net/cli 6.0.8 → 6.1.0

package/skills/microi-form-engine/references/data-source-events.md

@@ -1,124 +1,124 @@
-# 字段数据源、属性与事件
-
-## 数据源类型
-
-| 类型 | 适用场景 | 配置要点 |
-|---|---|---|
-| `Data` | 显示值和保存值相同的固定数组 | 适合少量稳定枚举 |
-| `KeyValue` | 保存 Key、显示 Label | 推荐；便于翻译和状态演进 |
-| `Sql` | 基于当前库的受控查询 | 参数化、限制条数、选择明确字段 |
-| `DataSource` | 复用数据源引擎 | 使用稳定 DataSourceId/Key |
-| `ApiEngine` | 复杂权限、跨表或外部数据 | 接口返回稳定的 Label/Value 字段 |
-
-KeyValue 示例：
-
-```text
-draft|草稿,enabled|启用,disabled|禁用
-```
-
-对应核心语义：
-
-```json
-{
-  "DataSource": "KeyValue",
-  "SelectLabel": "Value",
-  "SelectSaveField": "Key"
-}
-```
-
-动态 SQL 示例只选择必要字段并限制返回量：
-
-```json
-{
-  "DataSource": "Sql",
-  "Sql": "select Id,Name from biz_customer where Name like '%$Keyword$%' limit 0,20",
-  "SelectLabel": "Name",
-  "SelectSaveField": "Id",
-  "DataSourceSqlRemote": true
-}
-```
-
-SQL 仍必须经过平台受控数据源；不要把用户文本拼成标识符或任意 SQL。复杂权限、
-跨库或外部服务使用数据源引擎/接口引擎。
-
-## 动态联动
-
-字段值变化时可用前端 V8 更新另一个字段的数据源：
-
-```javascript
-if (V8.LoadMode === 'Design') return;
-
-var result = await V8.FormEngine.GetTableData('biz_contact', {
-  _SelectFields: ['Id', 'Name'],
-  _Where: [['CustomerId', '=', V8.ThisValue]],
-  _PageIndex: 1,
-  _PageSize: 100
-});
-
-V8.FieldSet('ContactId', 'Data', result.Code === 1 ? result.Data : []);
-```
-
-前端联动不能替代后端权限和提交校验。
-
-## 表单生命周期
-
-| 配置 | 运行端 | 用途 |
-|---|---|---|
-| `InFormV8` | 前端 | 默认值、字段显隐、初始化交互 |
-| `SubmitFormV8` | 前端 | 即时校验；HTTP 直调不会触发 |
-| `SubmitBeforeServerV8` | 后端事务内 | 最终校验、加工、阻止提交 |
-| `SubmitAfterServerV8` | 后端事务内 | 同事务联动其它表 |
-| `OutFormV8` | 前端 | 关闭后刷新/跳转 |
-| `DataFilterV8` | 后端 | 每行脱敏/展示加工 |
-
-事件代码、版本和表单属性都必须从当前 `diy_table/diy_field` 回读。后端阻止提交：
-
-```javascript
-if (!V8.Form.Name) return { Code: 0, Msg: '名称不能为空' };
-```
-
-## 字段属性
-
-常用属性包括 `Visible`、`AppVisible`、`Required`、`Readonly`、`Data`、
-`Config`、`FormWidth`、`TableWidth`、`Tab`、角色绑定和前端事件代码。
-
-- 除非明确隐藏，`Visible=1`、`AppVisible=1`。
-- 角色绑定只缩小界面可见性，不能代替服务器数据权限。
-- 修改防抖编辑器/代码字段前必须刷新待保存值，避免最后一次输入未入库。
-- `Data/Config` 修改后回读并刷新 schema 缓存。
-
-### 历史字段 V8 双存储兼容
-
-- `diy_field.V8Code` 是历史租户和官方应用包实际使用的物理列，按钮点击/字段值变更代码可能只存在于该列；`Config.V8Code` 是部分新版前端使用的镜像，不能假定它是唯一事实源。
-- 后端 `DiyField` 实体、字段查询投影和 `DiyFieldParam` 必须保留 `V8Code`，否则数据库代码虽然仍在，设计器列表和单字段回读都会表现成“0 字”。
-- 前端回读顺序固定为：先安全解码历史 Base64，再取“非空物理 `V8Code` 优先、否则 `Config.V8Code`”，最后同步两处。禁止用空镜像覆盖非空物理代码；保存和显式清空时则必须同步写入两处。
-- 回归至少包含一个 `Component=Button`、根级 `V8Code` 非空而 `Config.V8Code` 为空的官方包字段，并验证列表回读、选中编辑、保存、刷新后代码仍完整。
-
-## DevComponent 定制组件
-
-定制组件至少处理：
-
-- `value/modelValue` 的输入与变更通知；
-- 当前字段模型、表单模型、表单模式和只读状态；
-- 校验错误、清空、禁用、加载与销毁；
-- Add/Edit/View 回显；
-- PC、移动端和暗色主题；
-- 组件内部请求的 Token/OsClient 传递与错误态。
-
-定制组件需要修改并发布主前端。若只服务单一租户、包含多个字段或复杂页面，
-优先创建 MicroService 页面，通过 `V8.OpenAppDialog` 与宿主交互。
-
-历史 Options API 定制组件可通过宿主 facade 调用数据源引擎：
-
-```javascript
-this.Microi.DataSourceEngine.Run('customer_summary', { Id: customerId }, (result) => {
-  if (this.Microi.CheckResult(result)) {
-    this.summary = result.Data;
-  }
-});
-```
-
-`Microi.DataSourceEngine.Run` 是回调式宿主接口，`Microi.CheckResult` 负责按
-DosResult 约定判断并展示错误。组件卸载后要阻止迟到回调继续写状态；新页面
-优先使用项目现有的组合式 facade，不要假定 `this.Microi` 在任意 Vue 组件中
-都存在。
+# 字段数据源、属性与事件
+
+## 数据源类型
+
+| 类型 | 适用场景 | 配置要点 |
+|---|---|---|
+| `Data` | 显示值和保存值相同的固定数组 | 适合少量稳定枚举 |
+| `KeyValue` | 保存 Key、显示 Label | 推荐；便于翻译和状态演进 |
+| `Sql` | 基于当前库的受控查询 | 参数化、限制条数、选择明确字段 |
+| `DataSource` | 复用数据源引擎 | 使用稳定 DataSourceId/Key |
+| `ApiEngine` | 复杂权限、跨表或外部数据 | 接口返回稳定的 Label/Value 字段 |
+
+KeyValue 示例：
+
+```text
+draft|草稿,enabled|启用,disabled|禁用
+```
+
+对应核心语义：
+
+```json
+{
+  "DataSource": "KeyValue",
+  "SelectLabel": "Value",
+  "SelectSaveField": "Key"
+}
+```
+
+动态 SQL 示例只选择必要字段并限制返回量：
+
+```json
+{
+  "DataSource": "Sql",
+  "Sql": "select Id,Name from biz_customer where Name like '%$Keyword$%' limit 0,20",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "DataSourceSqlRemote": true
+}
+```
+
+SQL 仍必须经过平台受控数据源；不要把用户文本拼成标识符或任意 SQL。复杂权限、
+跨库或外部服务使用数据源引擎/接口引擎。
+
+## 动态联动
+
+字段值变化时可用前端 V8 更新另一个字段的数据源：
+
+```javascript
+if (V8.LoadMode === 'Design') return;
+
+var result = await V8.FormEngine.GetTableData('biz_contact', {
+  _SelectFields: ['Id', 'Name'],
+  _Where: [['CustomerId', '=', V8.ThisValue]],
+  _PageIndex: 1,
+  _PageSize: 100
+});
+
+V8.FieldSet('ContactId', 'Data', result.Code === 1 ? result.Data : []);
+```
+
+前端联动不能替代后端权限和提交校验。
+
+## 表单生命周期
+
+| 配置 | 运行端 | 用途 |
+|---|---|---|
+| `InFormV8` | 前端 | 默认值、字段显隐、初始化交互 |
+| `SubmitFormV8` | 前端 | 即时校验；HTTP 直调不会触发 |
+| `SubmitBeforeServerV8` | 后端事务内 | 最终校验、加工、阻止提交 |
+| `SubmitAfterServerV8` | 后端事务内 | 同事务联动其它表 |
+| `OutFormV8` | 前端 | 关闭后刷新/跳转 |
+| `DataFilterV8` | 后端 | 每行脱敏/展示加工 |
+
+事件代码、版本和表单属性都必须从当前 `diy_table/diy_field` 回读。后端阻止提交：
+
+```javascript
+if (!V8.Form.Name) return { Code: 0, Msg: '名称不能为空' };
+```
+
+## 字段属性
+
+常用属性包括 `Visible`、`AppVisible`、`Required`、`Readonly`、`Data`、
+`Config`、`FormWidth`、`TableWidth`、`Tab`、角色绑定和前端事件代码。
+
+- 除非明确隐藏，`Visible=1`、`AppVisible=1`。
+- 角色绑定只缩小界面可见性，不能代替服务器数据权限。
+- 修改防抖编辑器/代码字段前必须刷新待保存值，避免最后一次输入未入库。
+- `Data/Config` 修改后回读并刷新 schema 缓存。
+
+### 历史字段 V8 双存储兼容
+
+- `diy_field.V8Code` 是历史租户和官方应用包实际使用的物理列，按钮点击/字段值变更代码可能只存在于该列；`Config.V8Code` 是部分新版前端使用的镜像，不能假定它是唯一事实源。
+- 后端 `DiyField` 实体、字段查询投影和 `DiyFieldParam` 必须保留 `V8Code`，否则数据库代码虽然仍在，设计器列表和单字段回读都会表现成“0 字”。
+- 前端回读顺序固定为：先安全解码历史 Base64，再取“非空物理 `V8Code` 优先、否则 `Config.V8Code`”，最后同步两处。禁止用空镜像覆盖非空物理代码；保存和显式清空时则必须同步写入两处。
+- 回归至少包含一个 `Component=Button`、根级 `V8Code` 非空而 `Config.V8Code` 为空的官方包字段，并验证列表回读、选中编辑、保存、刷新后代码仍完整。
+
+## DevComponent 定制组件
+
+定制组件至少处理：
+
+- `value/modelValue` 的输入与变更通知；
+- 当前字段模型、表单模型、表单模式和只读状态；
+- 校验错误、清空、禁用、加载与销毁；
+- Add/Edit/View 回显；
+- PC、移动端和暗色主题；
+- 组件内部请求的 Token/OsClient 传递与错误态。
+
+定制组件需要修改并发布主前端。若只服务单一租户、包含多个字段或复杂页面，
+优先创建 MicroService 页面，通过 `V8.OpenAppDialog` 与宿主交互。
+
+历史 Options API 定制组件可通过宿主 facade 调用数据源引擎：
+
+```javascript
+this.Microi.DataSourceEngine.Run('customer_summary', { Id: customerId }, (result) => {
+  if (this.Microi.CheckResult(result)) {
+    this.summary = result.Data;
+  }
+});
+```
+
+`Microi.DataSourceEngine.Run` 是回调式宿主接口，`Microi.CheckResult` 负责按
+DosResult 约定判断并展示错误。组件卸载后要阻止迟到回调继续写状态；新页面
+优先使用项目现有的组合式 facade，不要假定 `this.Microi` 在任意 Vue 组件中
+都存在。

package/skills/microi-left-right-layout/SKILL.md

@@ -1,141 +1,141 @@
----
-name: microi-left-right-layout
-description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi 左右树表配置规范
-
-当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
-
-## 适用与禁用场景
-
-- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
-- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
-- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
-
-## 模块配置
-
-目标 `sys_menu` 必须配置：
-
-```json
-{
-  "ComponentName": "树形+表格",
-  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
-}
-```
-
-同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
-
-## `diy_LeftJoinRightView` 字段
-
-| 字段 | 必填 | 含义与写法 |
-| --- | --- | --- |
-| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
-| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
-| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
-| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
-| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
-| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
-| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
-| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
-| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
-| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
-| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
-| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
-| `ShumoHSS` | 否 | 模糊搜索开关。 |
-| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
-| `ShusouSAN` | 否 | 搜索按钮开关。 |
-| `ShushuaX` | 否 | 刷新按钮开关。 |
-| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
-| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
-| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
-| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
-| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
-| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
-| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
-
-## 初始化 V8 与分页契约
-
-左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
-
-当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
-
-```js
-var form = V8.Form || {};
-var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
-var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
-var keyword = String(form.inputText || '').trim();
-var query = {
-    _SelectFields: ['Id', 'Code', 'Name'],
-    _OrderBy: 'CreateTime',
-    _OrderByType: 'DESC',
-    _PageIndex: pageIndex,
-    _PageSize: pageSize
-};
-
-if (keyword) {
-    query._Where = [
-        ['Code', 'Like', keyword],
-        ['OR', 'Name', 'Like', keyword]
-    ];
-}
-
-var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
-
-if (result.Code !== 1) {
-    V8.Result = result;
-    return;
-}
-
-V8.Result = {
-    Code: 1,
-    Data: (result.Data || []).map(function (item) {
-        return {
-            Id: item.Id,
-            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
-            Code: item.Code,
-            Name: item.Name
-        };
-    }),
-    DataCount: Number(result.DataCount || 0),
-    PageIndex: pageIndex,
-    PageSize: pageSize
-};
-```
-
-对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
-
-加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
-
-## MCP 实施顺序
-
-1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
-2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
-3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
-4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
-5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
-
-## 移动端要求
-
-- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
-- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
-- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
-- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
-- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
-- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
-
-## 验收清单
-
-- 当前菜单只匹配一条配置，模块路径正确。
-- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
-- 左树标题无 `undefined`、`{}`、空白重复项。
-- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
-- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
-- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
-- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
-- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
-- 普通用户不出现仅管理员可用的“页面配置”。
-- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
-- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。
+---
+name: microi-left-right-layout
+description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi 左右树表配置规范
+
+当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
+
+## 适用与禁用场景
+
+- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
+- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
+- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
+
+## 模块配置
+
+目标 `sys_menu` 必须配置：
+
+```json
+{
+  "ComponentName": "树形+表格",
+  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
+}
+```
+
+同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
+
+## `diy_LeftJoinRightView` 字段
+
+| 字段 | 必填 | 含义与写法 |
+| --- | --- | --- |
+| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
+| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
+| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
+| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
+| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
+| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
+| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
+| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
+| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
+| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
+| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
+| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
+| `ShumoHSS` | 否 | 模糊搜索开关。 |
+| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
+| `ShusouSAN` | 否 | 搜索按钮开关。 |
+| `ShushuaX` | 否 | 刷新按钮开关。 |
+| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
+| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
+| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
+| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
+| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
+| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
+| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
+
+## 初始化 V8 与分页契约
+
+左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
+
+当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
+
+```js
+var form = V8.Form || {};
+var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
+var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
+var keyword = String(form.inputText || '').trim();
+var query = {
+    _SelectFields: ['Id', 'Code', 'Name'],
+    _OrderBy: 'CreateTime',
+    _OrderByType: 'DESC',
+    _PageIndex: pageIndex,
+    _PageSize: pageSize
+};
+
+if (keyword) {
+    query._Where = [
+        ['Code', 'Like', keyword],
+        ['OR', 'Name', 'Like', keyword]
+    ];
+}
+
+var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
+
+if (result.Code !== 1) {
+    V8.Result = result;
+    return;
+}
+
+V8.Result = {
+    Code: 1,
+    Data: (result.Data || []).map(function (item) {
+        return {
+            Id: item.Id,
+            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
+            Code: item.Code,
+            Name: item.Name
+        };
+    }),
+    DataCount: Number(result.DataCount || 0),
+    PageIndex: pageIndex,
+    PageSize: pageSize
+};
+```
+
+对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
+
+加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
+
+## MCP 实施顺序
+
+1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
+2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
+3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
+4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
+5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
+
+## 移动端要求
+
+- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
+- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
+- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
+- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
+- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
+- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
+
+## 验收清单
+
+- 当前菜单只匹配一条配置，模块路径正确。
+- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
+- 左树标题无 `undefined`、`{}`、空白重复项。
+- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
+- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
+- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
+- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
+- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
+- 普通用户不出现仅管理员可用的“页面配置”。
+- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
+- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。