AI 概念图｜模块由菜单、数据、展示和动作组成，非产品实机截图。

✦ 01｜从“一张表”到“一个业务模块”

假设 AI 刚做完一张采购申请表。采购员需要“我发起的申请”，主管需要“待我审批”，财务需要“待付款”，移动端只看最关键的状态和金额。四种入口可能读同一张业务表，却不能共用一套不加区分的列表。

表单引擎定义数据和字段；模块引擎决定某个菜单、角色、终端如何查询、展示和操作这些数据。它的核心配置实体是 `sys_menu`，表与字段仍属于 `diy_table / diy_field`。复杂后端动作交给接口引擎，而不是在每个页面复制业务代码。

结构解释图（确定性渲染）｜表单元数据、菜单配置、权限与终端视图共同决定运行结果。

✦ 02｜六种打开方式：菜单不只通向 CRUD

模块引擎提供六种打开方式。Diy 绑定表单引擎，形成标准列表和表单；Component 打开主前端已注册组件；Iframe 嵌入受控外部页面；SecondMenu 只承载子菜单；Report 打开报表；MicroService 指向已发布的前端微服务页面。

• Diy 适合客户、合同、工单等结构化业务表，通常优先使用现成增删改查。
• Component 适合平台主前端里已有、经过构建验证的专用组件。
• Iframe 适合已受控的外部系统；不要把长期 Token、密码或连接串塞进 URL。
• Report 与 MicroService 分别负责报表场景和复杂交互场景，后端权限与写入仍沿平台可信边界。

AI 配置 MicroService 菜单时，要把微服务 Key、路由与运行时页面绑定齐全；只写一个前端地址，不代表菜单可以安装、授权和升级。菜单图标使用 `IconClass`，应选业务相关且前端真实注册的图标，保存后在侧栏实看。

✦ 03｜一张列表背后有十种选择

绑定表的菜单至少要想清可用字段、实际查询列、搜索列、排序列、隐藏列、统计列、移动端字段、卡片标签和默认排序。`TableDiyFieldIds`、`SelectFields`、`SearchFieldIds`、`SortFieldIds`、`N

otShowFields`、`StatisticsFields`、`MobileListFields`、`CardTitleTagFields`、`CardBottomTagFields`、`DefaultOrderBy` 共同决定列表行为。

这里最容易犯的错，是 AI 只写 `Name` 和 `DiyTableId`：页面也许能打开，却会把 Id、外键、富文本或大附件塞进首屏；搜索与排序不合理，移动端卡片挤满字段，金额汇总甚至没有口径。

// Manifest 思路：字段名由 MCP 映射到目标租户字段 Id
modules: [{
  name: '待付款采购单', openType: 'Diy',
  listFields: ['OrderNo', 'Supplier', 'Amount', 'Status'],
  searchFields: ['OrderNo', 'Supplier', 'Status'],
  sortFields: ['CreateTime', 'Amount'],
  hiddenFields: ['Id', 'Attachment'],
  statFields: ['Amount'],
  mobileFields: ['OrderNo', 'Supplier', 'Amount', 'Status']
}]

这段是设计示意，不是可直接提交的完整 Manifest。真实写入前要读实时 Schema、父菜单和角色范围；AI 应让统计只覆盖当前用户有权看到的记录，并在真实列表的 `DataAppend.StatisticsFields` 中核对结果。

结构解释图（确定性渲染）｜列表、搜索、排序、统计与移动端各自有配置边界。

✦ 04｜把列表设计成工作台，而不是数据库浏览器

跨端 `ViewSchema` 让同一张表按菜单呈现不同信息层级。PC 列表可以配置 Hero 标题、副标题、真实指标，再用 `Layout.List.Columns` 把主字段、次要行和右侧状态组成复合列；移动端 `Layout.Card` 可以定义头像或图片、标题、顶部标签、副标题、右侧金额、正文、元信息和底部操作。

指标来源可选当前筛选的 `DataCount`、本页 `PageCount`、字段汇总或同一个接口引擎批量返回的业务指标。待办、逾期、金额、预警都应有清楚口径。不能用随机数装饰工作台，也不能把本页金额冒充全表金额。

`EnableViewSchema` 只控制 Detail/Edit 自定义表单视图；已配置的 List/Card 展示不依赖该开关。视图项还能按 Scene、Device、RoleIds、Priority 选择。配置损坏时要回退到标准菜单、表和字段视图，而不是白屏。

✦ 05｜按钮、页签和数字角标，让操作跟着业务走

模块的动作不只有“新增、编辑、删除”。`MoreBtns` 是行操作，`FormBtns` 在表单底部，`BatchSelectMoreBtns` 面向批量选择，`PageBtns` 是页面级动作，`ExportMoreBtns` 扩展导出，`PageTabs` 表达当前业务入口下的状态或关联模块。

按钮可配置稳定 Id、排序、图标、显隐条件、V8 前端交互或调用接口引擎。内置详情、删除、导入、导出也有显隐 V8 条件；显示条件不是授权，服务端仍必须重查菜单、表、行、角色和状态。超过请求时长的导入、批量处理应改为可靠后台任务。

`PageTabs` 有两种模式：不关联菜单时，在当前模块执行筛选 V8；关联 `TargetSysMenuId` 时，在同一页面实例内切换目标模块的数据表、字段、查询和按钮，入口路由与模块 Hero 保持稳定。隐藏目标菜单仍必须给角色授权，不能借页签绕过权限。

// 页面多 Tab：筛选逻辑仅改变当前列表条件
V8.SearchSet({ Status: 'Pending' });

// 前端动作只负责交互；最终状态转换交给后端接口引擎
var result = await V8.ApiEngine.Run('purchase_approve', { Id: V8.Form.Id });
if (result.Code === 1) V8.RefreshTable({ _PageIndex: 1 });

菜单、页签和按钮可显示待办数量等角标。相同页面的一组数字应由一个聚合接口批量返回，不要对每行每按钮发一次请求。失败时角标可降级，导航和主操作不能被数字接口拖死。

结构解释图（确定性渲染）｜动作位于行、表单、批量、页面与页签多个层级。

✦ 06｜接口替换、树表布局与复杂场景

普通单表 CRUD 已由 Diy 模块和表单引擎提供，不必为每张表再造一组接口。当查询涉及跨表授权、复杂聚合或外部系统，模块允许替换查询、新增、更新、删除、导入、导入进度和导出接口。替换后仍要保持平台返回契约、分页、统计、错误码、租户隔离与数据权限。

组织树、分类树加右侧列表的场景，可使用树形加表格布局；复杂页面可交给 MicroService，打开方式仍由模块菜单承载。模块还可通过后端 `V8.ModuleEngine.GetTableData` 按 `ModuleEngineKey` 读取关联查询配置；标准前端 V8 不挂载这个后端对象。

✦ 07｜用 AI 配模块时，怎样提需求才不会“看起来能用”

可以把任务交给 WorkBuddy、Codex 或 DeepSeek Harness，但提示词要给出角色、记录范围、首屏字段、状态动作、统计口径和终端差异。下面的写法让 AI 先读当前元数据，再形成可审查配置。

请先读取当前租户的 diy_table、diy_field、sys_menu 和角色权限。
为“采购申请”设计三个模块：我的申请、待我审批、待付款。
逐模块说明查询范围、列表/搜索/排序/隐藏/统计字段、PC 复合列、
移动端卡片、PageTabs、按钮显隐与服务端授权。
先输出配置方案和 dry-run，不写库；给出普通用户和无权限用户的验收步骤。

实施时优先使用 `microi_create_module`、`microi_update_module` 或 Manifest，写后通过 `microi_get_module` 回读字段映射、按钮 JSON、路由、图标、ViewSchema 和统计配置。应用交付时应把菜单、按钮及相关接口作为同一版本资源发布，避免页面有按钮、后台没有接口。

✦ 08｜完成标准：真实用户看到的才算模块完成

• 有权限用户能从侧栏进入，刷新、直达路由、切换 PageTabs 都正常；无权限用户不能改 URL 或 `_SysMenuId` 越权。
• 列表列、搜索、排序、统计和移动卡片展示的是预期字段；复合列引用的字段确实进入查询结果。
• 指标、角标和汇总按当前用户数据范围计算，零值、接口失败、角色撤销后不泄露总数。
• 导入、导出、批量按钮有服务端授权和幂等；大任务有真实进度、断点和恢复。
• PC 与移动端分别目视验收；概念图、数据库字符串、HTTP 200 都不能代替运行页面。

文中 AI 概念图与图文卡底图由 AI 生成；结构示意图依据当前源码与配置确定性绘制。概念图不是产品实机截图，功能以项目版本、配置和权限为准。