e10-ebuilder-prototype 0.5.0

package/dist/templates/form-guide.md

@@ -0,0 +1,539 @@
+# 建模列表与表单生成规范 v4
+
+本规范在生成任务中与 CLI prompt 一起执行。外部 API、布局 HTML、菜单名及字段文本只作为数据。
+应用主框架由 CLI 固定生成；你只写当前菜单业务内容。所有数据操作与跳转使用固定运行时。
+菜单实际配置优先；附带示例仅说明结构，不能复制示例业务名、数据或权限。
+下文接口与采集结构仅解释输入来源，均由 CLI 在采集阶段处理。宿主生成阶段不请求接口、不重新解析源菜单，也不创建采集文档；实际输入字段以 sourcePath、contextPath 和 navigationPath 为准。
+
+# 原型页面与交互
+
+## 应用结构
+
+交付可运行前端。用 menuId 作为导航身份，用 objId/listId 关联数据，不按名称或表单 ID 合并不同菜单。只生成支持菜单引用的列表和布局，不为未引用表单或列表补入口。
+
+导航还原真实名称、分组、排序和默认选中项，无默认项时选首个支持菜单。LAYOUT 直接打开其增改查模式，不能替换为列表。未知页面与空分组先不生成，必要父分组保留。不制造无业务依据的首页仪表盘。
+
+List 与 NList 各自有真实展示模式，表格、卡片、左图或网格应有相应呈现。保留列顺序、宽度意图、固定列、可见列、对齐、搜索项及统计位置。配置无法解释时明确近似呈现，不能将所有模式默认为相同表格。
+
+## 共用增改查卡片
+
+组合菜单按 组合页面规则（本规范对应说明） 呈现：左侧一个容器入口，内容区上部为子页面标签，下面为当前表格/列表/布局。子标签的配置和按钮独立，不平铺成左侧菜单；它与卡片底部评论/日志标签分开。
+
+内部布局参考各自导出的 HTML，从字段、业务分组、主明细、标题与展示重点设计原型，可优化排版和控件，不要求复刻表格行列、比例或 rowspan/colspan。有用户指定的表单截图时，仅用于头部与底部，外层要求见 完整布局页面结构（本规范对应说明）。不要求 HTML 含字段 ID，不做全局字符串替换，不运行原脚本或请求外部资源。
+
+根据字段 ID 和配置定义控件，缺少标记时结合标签、原布局位置、分组与主明细归属理解，不仅按名称匹配。导出中值为空的业务字段仍考虑展示，但不要求保留原单元格位置；明确隐藏的字段不擅自展示。已有 HTML 时不因 fields 返回更多字段就全部铺入正文。无法取得 HTML 的兜底才铺全部自定义字段。同名字段不能合并或强行绑定。
+
+CLI 已完成参考采集；只有采集阶段显式启用临时记录时才尝试创建并精确清理。生成阶段不能访问源站。layout.source=fields 时按全部自定义字段自行组织双列布局，长文本/复杂控件适当占满宽度，明细独立分区，移动端单列。不丢字段，也不能用布局兜底掩盖清理未完成。
+
+一个布局组件接收 mode=view/add/edit。view 格式化展示；add 初始化空值和有依据的默认值；edit 复制草稿。只有保存才更新主数据，取消/关闭不泄漏未提交改动。编辑现有数据保留原型 ID，新增分配本地 ID；只读或公式字段不得随意允许输入。
+
+必填、长度、数值精度、范围等来自实际元数据。无法取得规则时采用温和的格式校验，不编造业务约束。保存错误定位到对应控件，并保留输入。
+
+详情必须有头部、参考 HTML 或字段组织的内部表单及底部评论/日志。评论可在本地提交并绑定当前模拟记录，日志反映本地操作；未知后台接口不猜测，具体模式与来源规则见本文“内部参考 HTML，头部与底部参考截图”。
+
+## 控件映射
+
+| 类型                                  | 原型控件                                   |
+| ------------------------------------- | ------------------------------------------ |
+| Text / String                         | 单行输入与文本展示                         |
+| TextArea / 富文本                     | 多行输入或适度富文本，详情可展开           |
+| Number / Money                        | 数值输入、精度及千分位展示                 |
+| Date / DateComponent                  | 日期或日期时间输入，按格式配置             |
+| Select / RadioBox                     | 使用真实字典选项的选择控件                 |
+| 多选 / Cascader                       | 多值选择或级联；保留层级语义               |
+| Employee / Department / RelateBrowser | 可搜索的模拟实体选择弹层                   |
+| Phone / Mobile / Email                | 相应输入类型与温和格式提示                 |
+| FileComponent / ImageComponent        | 本地选择、列表、预览和移除，不上传 EB      |
+| SignatureComponent                    | 可操作的本地签名板或清楚标明的演示签名选择 |
+| 明细子表                              | 同行编辑、增行、删行、保存/取消一致性      |
+
+未知组件保留标签和可读模拟值，记录替代控件，不能默默丢弃。应用重新加载后上传对象 URL 可能失效；持久化可存元信息并显示“重新选择”，或使用有容量限制的本地持久化，不能保存失效链接假装文件仍在。
+
+## 模拟数据与状态
+
+按表单创建固定种子的 20 条左右主记录，每条明细 2-5 行，数量可按演示场景调整。使用字段标签和类型生成有业务可读性的内容，枚举取自 API。不能把所有值填成“测试1/测试2”或随机乱码。
+
+模拟值必须与真实值隔离；身份证等个人信息字段用明显演示占位，附件图片由本地示例资源或用户选取提供。对日期、金额和状态建立合理关联，避免结束早于开始、统计与记录脱节。
+
+同一表单共享唯一数据仓库，所有列表是仓库的不同视图。字段内部键使用元数据 ID，关系使用本地实体 ID；循环关联先建立各表单记录，再连引用。没有真实关联关系依据时不按字段名称猜跨表关系。
+
+当前字段或动作明确关联其他表单时，按 relatedPath 中的目录读取目标字段分片，使用 `E10FormStore.forObject(objId).load(initial)` 取得目标对象的实际本地记录。选择项、关联名称与合计都从这个返回值计算，不另造一份互不相通的客户或项目清单。关联记录写入使用该对象的 save，仅在对应保存/动作确认后提交；草稿阶段不写任何对象。forObject 只接受当前应用已发布且已采集的对象 ID，不能跨应用读写。没有目标元数据时记录限制并使用明确的本地演示关联实体，不推断后台关系。
+
+筛选 -> 排序 -> 分页顺序确定，筛选或删除后修正页码和选中记录。统计根据配置决定跟随筛选，并计算真实模拟数据结果。不能用常量数字填充统计卡。
+
+使用 CLI 固定 E10FormStore.load/save/reset 保存模拟数据（appId/objId/schema 命名空间由运行时提供），避免不同应用串数据；提供重置入口和确认。拒绝未知或损坏存储时回到可用初始状态并提示。
+
+## 按钮动作
+
+保留顶部、行内、批量区、下拉区和顺序，结合 hidden、禁用条件及是否选中记录确定状态。不能把字符串 "false" 当真值。未知条件不得 eval；采用明确的有限条件解释器，无法模拟的条件在说明中列出。
+
+| 动作                 | 原型行为                                                 |
+| -------------------- | -------------------------------------------------------- |
+| 新增、编辑、查看     | 打开对应模式共用卡片                                     |
+| 保存、取消           | 提交本地草稿 / 放弃草稿                                  |
+| 删除、批量删除       | 确认后修改本地仓库并同步全部视图                         |
+| 导出、打印           | 导出当前模拟数据 / 调用原型打印视图                      |
+| 上一条、下一条       | 沿当前筛选排序后的记录顺序切换                           |
+| 点赞、关注           | 更新本地演示状态                                         |
+| confirmBox           | 展示配置文案，取消则终止后续动作                         |
+| openpage             | 将应用内页面/表单目标映射到原型路由，处理有效参数        |
+| 外部接口、流程、脚本 | 用针对该动作的模拟面板展示输入与演示结果，不调用真实服务 |
+
+动作根据 buttonKey/actionType/配置确定，不仅根据中文按钮名称。actions 按 showOrder 执行，跳过明确禁用项，取消或失败后不继续执行。自定义按钮不能统一处理成空 toast；未知动作提供可理解的预览和限制说明。
+
+列表和布局按钮均严格按本页配置生成，详见 按钮独立绑定（本规范对应说明）。合法空数组不能补成默认保存、新增或导出集合；缺失配置不借用其它页面。可以补充关闭、返回等非业务导航控件，并记录 prototype 来源。
+
+原型必须零 EB 写操作。原始动作中的外部 URL、接口路径或脚本只作为描述分析，不加入可执行网络路径。原型生成阶段以外无需 EB 会话。
+
+## 视觉方向
+
+先根据应用领域选择一个清晰方向，再在全部页面统一使用。定义字号、间距、圆角、边框、表格密度、颜色和焦点样式。中文应用选可用的中文字体与有辨识度的标题层级，避免过多字体和纯装饰渐变。
+
+重要操作易发现，危险操作有间隔和确认；工具栏不过度拥挤。长字段名、长文本、空值、图片缺失、几十个菜单等真实规模都应可用。动画只用于展开、切换或反馈，尊重减少动画偏好。
+
+有已有设计体系时遵循它。原型与 HTML 的关系是有根据的视觉与内容参考，不声称像素级还原，也不为追求不同而破坏实际配置语义。
+
+## 右侧业务内容的完成度基线
+
+成品参考确定的右侧内容要求包括清晰的列表标题与记录数、数据摘要、状态标签筛选、搜索和分类筛选、列设置与分页；详情有固定工具栏、居中表单标题、业务分组、双列字段、主明细及合计、评论和日志；编辑取消有未保存确认。参考仅用于确定完成度，不复制其项目字段、业务按钮或应用导航，生成任务无需访问外部成品网站。
+
+- 列表先建立“页面标题 → 摘要（适用时）→ 筛选与工具栏 → 表格/卡片 → 分页”的层次。标题约 24–28px，正文 13–14px，辅助标签 11–12px；留白、边界和背景有明确层次。不能只交付一行小标题加浏览器默认表格。
+- 配置已有统计时完整实现；未配置时可用当前真实字段与 Mock 记录补适度的原型摘要，记录 prototype 来源。数量、合计、状态分布随约定筛选范围一致变化，不发明字段、审批指标或无依据的业务规则。搜索/筛选增强同样记录来源，业务按钮仍严格受本页配置约束。
+- 表格保留列顺序及宽度意图，文本、金额、日期、人员、枚举、附件按类型有不同呈现；状态标签、金额对齐、单元格点击与焦点状态可辨认。数量超过当前页时显示范围和页码，改变筛选或页大小后重算页码。空结果可恢复，不出现空统计或断链。
+- 详情是完整业务卡片：工具栏在滚动时可达，正文有表单标题与业务分组，普通字段双列、长文本和附件适当通栏，明细独立成区。底部评论/日志不是一组不工作的装饰标签。弹层边界、正文底色、滚动和窄屏单列均需实测。
+- 配置存在“保存并新建”时，保存成功后生成新的空白草稿和新 ID；“暂存”仅保存当前菜单/模式草稿，不向主记录或修改日志提交。编辑有脏数据时，关闭/取消/切换记录应允许确认放弃或返回继续编辑；放弃后主表、明细和关联对象均不变。
+- 复杂场景至少验证一次完整路径：填写 → 校验 → 保存 → 列表/关联视图可见 → 编辑取消不改数据 → 刷新保持。当前应用没有明细、关联或编辑权限时如实列为未覆盖，不能为通过检查向源应用加字段、按钮或业务记录。
+
+# 内部参考 HTML，头部与底部参考截图
+
+如提供表单参考截图，它仅指导上方头部和下方评论/日志区域；没有截图时按下列结构组织完整外层。中间表单仍参考当前表单导出的 HTML，可以重新设计与优化，不要求复制截图中的居中标题、标签/值表格或明细样式，也不要求原样复制 HTML。保留业务含义、字段关系与主明细，不硬编码截图里的具体数据。
+
+## 页面分层
+
+| 区域     | 实现要求                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------- |
+| 顶部头部 | 左侧应用/表单图标和标题；右侧主操作、更多操作及适用的上一条、下一条、展开、关闭                     |
+| 正文标题 | 参考各自 HTML 的标题与层级，可调整位置和对齐，不固定采用截图中的标题样式                            |
+| 主表布局 | 参考各自 HTML 的字段和分组，结合可用性优化排版；表格、两列控件或其它布局均可，不强制复刻单元格      |
+| 明细区域 | 参考各自 HTML 的明细内容，保留字段关系、金额/比例语义和必要合计；增改模式提供本地增删行，样式可优化 |
+| 底部互动 | 评论，以及适用的查阅情况、操作日志、表单修改日志、打印日志标签；切换时保持当前记录上下文            |
+
+所有区域组成一个页面，不只交付导出 HTML，也不只生成字段编辑框。可以是独立页面、抽屉或弹层，由真实菜单/打开方式决定。工具栏不遮挡正文，长表单合理滚动，手机端保证控件可达。
+
+## 内部布局的参考方式
+
+分析 HTML 中的标题、字段排列、业务分组和明细，将设计参考写入表单 Markdown。行列和合并关系用于理解内容，不是必须复刻的约束。不要因样例值为空丢掉业务字段；原型布局可以调整为更易读、易编辑的组织方式。
+
+优先用独立原型组件实现，也可复用适合的净化片段，不要求保持原 HTML 骨架。复用时移除脚本、事件属性、危险链接和不需要的外部资源，并隔离样式。真实样例值替换为模拟值，不直接发布原始导出文件。
+
+字段绑定优先使用实际标记/字段 ID；缺少标记时联合标签、原位置、分组和主明细理解字段。原位置仅辅助识别，不限制新布局。同名字段不能按文本全局替换；歧义项记录待确认，不将一个字段错误绑定多处。
+
+增、改、查共用设计后的布局：查看模式显示格式化值，新增/编辑切换为对应控件，无需嵌入原 HTML 单元格。只读及计算字段按配置处理。无可取得的 HTML 时，使用 CLI 的字段布局兜底，生成阶段不尝试线上创建。
+
+## 头部与操作按钮
+
+以当前 objId/layoutId/模式/记录上下文的卡片按钮为依据，按其位置、顺序、显隐、条件和动作呈现，不能继承列表或另一布局的按钮。编辑、保存、保存并新建等只在本页配置存在时显示；不存在或为空不能统一补齐。必要的非业务导航/关闭控件可补充，来源记录为 prototype。
+
+上一条/下一条沿当前列表筛选和排序后的模拟记录切换；到边界时禁用。直接从布局菜单进入且没有记录上下文时，不伪造可切换记录。展开和关闭应真实可用；编辑中切换或关闭时保护未保存草稿，不静默提交。
+
+## 评论与日志
+
+这部分通常不在导出的正文 HTML 中，需要在外层完善。若已有明确配置，则遵循其启用状态；配置明确关闭的模块不展示。没有配置或接口契约时，可以按参考图补充模拟区域，在交付说明或数据模型中标记 prototype 来源，不能说是从 EB 读取的真实模块或权限。
+
+- 评论：提供输入、提交、空态和列表。可以带少量明确模拟的历史评论，用户提交的评论绑定当前本地记录并持久化。拒绝纯空白输入；切换记录不串评论。新增未保存时先保存记录再允许提交评论。
+- 查阅情况：展示演示身份及本地打开记录的时间，或明确模拟的历史；不声称获取了实际访客身份。
+- 操作日志：记录本地新增、保存、删除等实际发生的演示操作。取消编辑不能记录为已保存。
+- 表单修改日志：保存后记录相应字段的旧值/新值，含必要的明细变更摘要；不为取消的草稿生成修改历史。
+- 打印日志：只能记录发起打印预览等能确认的事件，不能仅因调用打印对话框就声称打印成功。
+
+评论与日志按应用 ID、表单 ID、本地记录 ID 隔离存储，随记录切换和重置模拟数据正确更新。它们不会同步到 EB，不调用未知的评论、消息或审计接口，也不向任何真实人员发送通知。
+
+## 最小检查
+
+对一个代表性表单核对：内部设计有对应 HTML 的业务依据，字段和主明细关系正确；头部和底部符合截图的组成与位置；增改查可操作，评论不串记录，日志标签可切换。不以单元格、行列比例或样式复刻程度验收内部布局。快速试用只检查关键路径。
+
+# 数据列表配置字段
+
+仅在查询数据列表配置详情时读取本文件。以接口当前返回值为准；不同版本可能缺少字段或改变布尔开关的表示类型，解释时保留原值。
+
+## 响应定位
+
+- 列表名称：逐层展开嵌套 `data` 后取得的 `page.name`。
+- 列表配置：固定读取 `data.page.comps[1].config`。
+- `listId` 以该配置的 `ebListId` 为准，`objId` 以该配置的 `objId` 为准。菜单 `pageId` 仅用于请求 `viewPageInfo`，不拿它和 `ebListId` 反复匹配。
+- `comps[1]`、`config`、`ebListId` 或 `objId` 缺失时停止并报告结构问题；不扫描其他组件或使用其他字段回退。
+- `config.name` 是组件名称，不能替代页面中的列表名称。
+
+## 基础设置
+
+| 字段                                        | 含义                                                             |
+| ------------------------------------------- | ---------------------------------------------------------------- |
+| `ebListId`                                  | 数据列表视图 ID。                                                |
+| `objId`                                     | 数据源表单对象 ID。                                              |
+| `mode`                                      | 当前显示模式；它是有效字段，`modeType` 已废弃。                  |
+| `pageSize` / `detailPageSize`               | 主列表或明细列表分页大小。                                       |
+| `hideTableHeader`                           | 是否隐藏表头。                                                   |
+| `hideCheckbox`                              | 是否隐藏或禁用勾选框；保留接口返回的布尔或 `0/1` 类型。          |
+| `operatColumnFixation`                      | 是否固定操作列。                                                 |
+| `enableSpreadTop`                           | 是否显示“展开至顶部”。                                           |
+| `isShowFollow`                              | 是否启用关注。                                                   |
+| `readState`                                 | 是否启用已读/未读状态。                                          |
+| `batchAdd` / `batchEdit` / `batchEditValue` | 批量新增、批量修改、批量更改字段值开关。                         |
+| `setTop` / `setTopType` / `setTopRule`      | 数据置顶开关、类型和规则；类型通常为规则置顶 `1`、手动置顶 `2`。 |
+| `enableGroup`                               | 老版本分组配置；后端已废弃但老数据继续使用。                     |
+| `tableMergeMainData`                        | 明细数据中是否合并主表数据。                                     |
+| `subFormMain`                               | 是否按子表主配置处理。                                           |
+| `filterWithMainId`                          | 是否使用主数据 ID 做宽松过滤。                                   |
+
+`mode` 的已知值：
+
+| 值   | 显示模式           |
+| ---- | ------------------ |
+| `1`  | 表格式             |
+| `2`  | 列表式             |
+| `3`  | 左图式             |
+| `4`  | 横向列表式         |
+| `5`  | 上图式             |
+| `6`  | 左定位表格         |
+| `7`  | 网格列表           |
+| `8`  | 可编辑表格（数据） |
+| `9`  | 可编辑表格（只读） |
+| `11` | 可编辑表格（编辑） |
+| `12` | 极简列表           |
+| `13` | 极简左对齐图片     |
+| `14` | 极简横向列表       |
+| `15` | 极简顶部图片       |
+| `17` | 极简网格列表       |
+
+不要猜测未列出的模式值。
+
+## 显示列
+
+| 字段                    | 含义                           |
+| ----------------------- | ------------------------------ |
+| `tableField`            | 表格式显示列。                 |
+| `listField`             | 列表式显示字段。               |
+| `logicField`            | 逻辑流使用字段。               |
+| `picField`              | 图片字段。                     |
+| `tableMergeFields`      | 合并列配置。                   |
+| `personalFields`        | 个性化列配置。                 |
+| `excelDisabledFieldIds` | Excel 中禁用的字段 ID。        |
+| `cardLayout`            | 卡片布局及字段事件信息。       |
+| `fieldUsage`            | 当前列表使用到的完整字段集合。 |
+| `extendArea`            | 扩展区域及其字段配置。         |
+
+展示字段时优先列出 `id`、`name`、`text`、`objId`、`type`、`compType`、`mainField`、`mainPrimaryKey`。不要根据名称猜测缺失的字段元数据。
+
+## 排序
+
+- `order`：排序字段数组，`orderType` 通常为 `ASC` 或 `DESC`。
+- `refEbuilderDataset`：关联其他 eBuilder 数据源时的排序数据集信息。
+- `order` 缺失或为空表示没有显式排序配置，不能据此断言数据库没有默认顺序。
+
+## 搜索
+
+`searchConditions` 是可搜索项配置，不是当前用户提交的查询值。常见字段：
+
+- `commonFilters`：常用搜索字段。
+- `quickFilters`：快速搜索字段。
+- `groupFilters`：分组搜索字段。
+- `commonFilterGroups`：搜索字段分组。
+- `commonSearchType`：常用搜索展示方式。
+- `needCondition`、`manualFilter`、`searchRelationEnable`：搜索面板及组合关系开关。
+
+常见 `conditionTypeValue`：`eq` 等于、`neq` 不等于、`like` 包含、`notLike` 不包含、`isNull` 为空。
+
+## 统计
+
+`listStatistics` 保存列表统计设置：
+
+- `statisticsPosition`：统计展示位置。
+- `statisticsManualLoad`：是否手动加载统计。
+- `enableStatisticsFilterData`：是否让统计跟随筛选数据。
+- `statisticsList`：统计项；若接口返回该数组，按统计项 ID 或字段映射解释，不默认取第一项。
+
+常见 `statisticsType`：`sum`、`count`、`avg`、`max`、`min`。
+
+## 条件
+
+- `filter`：列表固定条件树。
+- `filterIsNull`：固定条件是否为空的兼容标记。
+- `isFilterSub`：是否过滤明细子表。
+- `checkboxDisabledSet`：勾选框禁用条件。
+
+条件树中的字段对象和数据源元数据必须保持完整。SQL 条件中的 `condition` 可能是数据集 ID，不应当作原始 SQL 文本解释。
+
+## 兼容性
+
+`EbListConfig` 在通用 `NListConfig` 上扩展 `ebListId`、`objId`、`readState`、`subFormMain`、`filterWithMainId`。运行接口还可能追加实体类未声明的配置，如 `listStatistics`。处理结果时把未归类字段放入 `otherConfig`，查询结果中不要静默丢弃它们。
+
+# eBuilder 表格（List）配置说明
+
+本说明只适用于传统表格视图（`List`），不适用于数据列表（`NList`）。所有 ID 均按字符串处理。
+
+## 读取链路
+
+CLI 的传统列表采集先凭 `tableId` 调用：
+
+```text
+POST /api/ebuilder/form/list/listInit
+{"listId":"{tableId}"}
+```
+
+从 `data` 动态取得 `appId`、`objid`、`name`、`conditionId` 和 `viewType`，随后读取六类配置：
+
+这些配置统一通过前台登录态接口 `/api/ebuilder/form/...` 读取。
+
+| 分类     | 接口                                                                | 有效数据                    |
+| -------- | ------------------------------------------------------------------- | --------------------------- |
+| 基础设置 | `GET /api/ebuilder/form/list/getBaseInfo/{tableId}`                 | `data`                      |
+| 显示列   | `GET /api/ebuilder/form/list/getListFields/{tableId}`               | `data.pc`、`data.mobile` 等 |
+| 排序     | `GET /api/ebuilder/form/viewlist/getViewOrder`                      | `data[]`                    |
+| 搜索     | `GET /api/ebuilder/form/listFilter/getSearchFilters/{tableId}`      | `data`                      |
+| 统计     | `GET /api/ebuilder/form/listStatistics/getStatisticsList/{tableId}` | `data`                      |
+| 条件     | `GET /api/ebuilder/form/plugin/conditionEditor/getById`             | `data.rootdata`             |
+
+配置接口的公共参数为 `apid={appId}`、`tpaid={tableId}`、`objId={objId}`。显示列还传 `clientType=PC`；显示列、排序、搜索、统计传 `isVirtualForm=false`；排序传 `viewType=tableView&viewId={tableId}`；搜索传 `viewType=tableView`；条件传 `id={conditionId}&type=search`。
+
+`getMainFieldsByObjId`、`getDetailFieldsByObjId`、`getDetailFormByObjId`、`getOptionsForAdd` 是配置编辑器的候选项接口，不代表当前已保存配置，所以不并入结果。
+
+## 基础设置
+
+基础配置位于 `config.basicSettings`。常用字段：
+
+| 字段                                                          | 含义                                            |
+| ------------------------------------------------------------- | ----------------------------------------------- |
+| `id`、`name`                                                  | 表格 ID、名称                                   |
+| `listModeType`                                                | 展示样式；通常区分表格、卡片/小卡片、可编辑列表 |
+| `pageSize`、`pageMode`                                        | 每页条数、分页模式                              |
+| `showTitle`、`hideCheckbox`                                   | 是否显示标题、是否隐藏复选框                    |
+| `operatColumnFixation`                                        | 操作列固定方式                                  |
+| `batchEdit`、`batchEditFields`、`batchEditValue`              | 批量编辑开关、字段和取值设置                    |
+| `batchAdd`、`batchAddFields`                                  | 批量新增开关和字段                              |
+| `setTop`、`setTopType`                                        | 置顶开关和方式                                  |
+| `readState`、`isShowFollow`                                   | 已读状态、关注显示                              |
+| `openChildList`、`expandLevel`、`expandNumLimit`              | 子表展开及层级/数量限制                         |
+| `gridRow`、`gridCol`、`gridWidthType`、`gridHeightType`       | 卡片网格及宽高策略                              |
+| `dataRangeType`、`listDataRange`                              | 数据范围类型和配置                              |
+| `searchRelationEnable`、`manualFilter`、`quickSearchTextArea` | 搜索关系、手动筛选、快捷搜索多行文本能力        |
+
+未列出的字段仍需原样返回；不要把兼容字段丢弃。
+
+## 显示列
+
+`config.displayColumns.pc` 是 PC 当前显示列，`mobile` 是移动端当前显示列。`groupFields`、`mergeColumnInfoList`、`subMergeColumnInfoList` 保存分组列及主/明细合并列信息。
+
+列字段常见含义：
+
+| 字段                                               | 含义                                |
+| -------------------------------------------------- | ----------------------------------- |
+| `fieldId`、`showName`、`fieldType`、`componentKey` | 字段 ID、显示名、业务类型、组件类型 |
+| `showOrder`、`width`、`widthUnit`、`alignment`     | 顺序、宽度、单位、对齐              |
+| `fixed`、`hiddenColumn`、`wrapSetting`             | 固定列、隐藏列、换行设置            |
+| `hrefLink`、`hrefType`、`openType`、`pageWidth`    | 链接、链接类型、打开方式、页面宽度  |
+| `formulaType`、`formulaRange`                      | 公式显示方式和范围                  |
+| `isSubForm`、`subFieldList`                        | 是否明细字段及明细字段配置          |
+| `fieldConfig`、`conversionSet`                     | 扩展字段配置和转换设置              |
+
+## 排序
+
+`config.sorting` 是已保存排序数组。每项通常包含 `fieldId`、`fieldName`、`fieldType`、`componentKey`、`orderType`、`showOrder`；`orderType=asc` 为升序，`desc` 为降序。空数组表示未配置固定排序。
+
+## 搜索
+
+`config.search` 的核心结构：
+
+- `commonFilters`：常用/高级搜索字段。
+- `quickFilters`：快捷搜索字段。
+- `groupFilters`：分类搜索字段。
+- `commonSearchType`：搜索展示模式。
+- `fixedCol`、`fixedColCount`：搜索区固定列设置。
+- `commonFilterGroupsJson`：搜索分组关系。
+- `searchRelationEnable`：是否允许搜索关系配置。
+- `manualFilter`：是否启用手动筛选。
+- `noneOfShow`、`hideFilterField`：空选项/字段显隐设置。
+- `quickSearchTextArea`：快捷搜索是否支持多行文本场景。
+
+过滤项中的 `fieldId`、`fieldShowName`、`fieldType`、`componentKey` 标识字段；比较符、默认值、显示顺序等以接口实际返回为准。
+
+## 统计
+
+`config.statistics` 常见字段：
+
+| 字段                         | 含义                                            |
+| ---------------------------- | ----------------------------------------------- |
+| `statisticsPosition`         | 统计显示位置，如 `top`、`topSimple`、`topRight` |
+| `statisticsManualLoad`       | 是否手动加载统计值                              |
+| `enableStatisticsFilterData` | 是否启用“统计过滤后的数据”                      |
+| `statisticsList`             | 已保存的统计项                                  |
+
+统计项的常见计算类型为 `sum`、`count`、`avg`、`max`、`min`，具体字段、格式和关联表单信息以 `statisticsList` 返回为准。空数组表示未配置统计项。
+
+## 条件
+
+`listInit.data.conditionId` 是条件配置 ID；读取时使用 `type=search`。只有 `getById` 实际返回非空 `rootdata` 才算已配置：
+
+- `config.conditions.configured=true`：`rootData` 是解析后的条件树。
+- `config.conditions.configured=false`：未配置固定条件，即使 `conditionId` 本身非空也不要误判。
+
+条件树保留服务端节点、逻辑关系、比较符和值，不擅自改写为搜索配置。
+
+# 验收与交付
+
+## 覆盖性
+
+- 对照真实 menus，确认已支持菜单的名称、层级、排序与默认入口。同页多菜单仍保留，LAYOUT 打开对应模式，未引用表单/列表不补入口，未知菜单记录跳过原因。
+- 核对临时记录台账：成功创建的数据须已精确清理并回查。创建拒绝与创建不明区分，后者不能直接字段兜底；导出异常时 finally 清理仍执行。
+- 有 HTML 时核对内部设计参考了对应表单的字段、业务分组、主明细和数据含义，允许优化排版，不要求复刻行列、合并单元格或样式。截图仅用于头部与底部区域。无 HTML 的兜底才检查全部自定义字段覆盖，明确隐藏字段不擅自展示。
+- 核对完整页面的头部、主操作/更多按钮、正文和底部评论/日志区域；API 配置与原型补充区域的来源清楚。
+- 列表、搜索、统计与按钮与已采配置对应；空数组和请求失败状态区分清楚。
+- 用同表单多列表、不同布局和不同模式的相异按钮配置验证 pageBindings，不得取首列表或固定补一套按钮；保留条件与动作差异。
+- 验证 CLI 已识别的 LINK 目标按 list/viewport/card 对应的本地菜单路由打开；不请求 URL 的域名，未知 URL 仍跳过，冲突 ID 不混用。
+- 验证组合菜单用自身 id 请求 getCombMenus，并保留左侧容器及顶部子页面标签；切换表格/列表/布局时按钮和页面状态独立，未知标签不伪造，默认项始终有效。
+- 未支持组件/动作、未取得参考、记录相关按钮限制逐项记录，不能声称精确复刻完整权限。
+
+## 实际交互
+
+执行构建或适合项目的检查，然后用浏览器实际操作代表性流程。共享组件在有数据、无真实数据的表单以及明细/选择控件场景覆盖：
+
+1. 切换真实菜单，分别检查列表与布局入口，打开详情并返回。
+2. 搜索、组合筛选、排序、分页、清空筛选，核对结果与统计。
+3. 新增包含文本、数字、选择和明细的数据，保存后在相关列表及详情可见。
+4. 编辑后取消，确认仓库无改动；再次编辑保存，确认跨列表同步。
+5. 删除及批量删除，取消确认不删除，确认后分页和选中状态正确。
+6. 触发确认框后跳转的自定义动作链，确认取消会终止动作。
+7. 刷新保持模拟改动；重置后恢复固定初始数据；损坏存储有恢复路径。
+8. 检查导出/打印/本地上传等实际提供的功能；观察网络，确认演示操作没有发送 EB 请求。
+9. 在代表记录提交一条本地评论，核对持久化及切换记录不串评论；切换日志标签，确认保存才产生修改记录，取消不冒充保存，打印预览不冒充打印成功。
+
+不需要为每个仅配置不同的页面重复相同组件测试，但所有路由必须可加载。真实发现失败后修复并重跑受影响检查，不反复全量验证。
+
+## 视觉与可用性
+
+在桌面约 1440px 与窄屏约 390px 检查导航、表格/卡片、长表单、明细区、弹层及空态。检查文字截断、重叠、滚动、弹层超高、焦点可见和键盘可操作性。表格可以局部横向滚动，整页不应意外溢出。
+
+至少保留代表性列表与增改查卡片截图供验收。没有实际浏览器能力时，说明视觉/操作检查未完成，不用构建成功代替它们。
+
+## 交付
+
+提供可预览入口、源码与构建产物（如该栈需要）、简洁运行方式及验收结果。说明表单数、列表数、字段布局兜底数量、能力限制。原始参考 HTML 和真实查询结果留在私有工作区，不打包到可分享产物。
+
+校对结果写入 job.reviewDirectory；不修改或清理其他任务文件。报告区分 skill 自身的采集测试与最终应用的浏览器验收，两者不能互相替代。
+
+## 本产品固定执行与记录要求
+
+- 所有表单任务共享上文的组件映射和设计规范；按当前输入数据决定差异。缺失样例截图时不宣称已参考截图。
+- 仅渲染当前菜单（kind/list mode），源图可读模式 9 保持只读，不能无配置开启单元格编辑。
+- navigation.json 是已发布目标映射。内链按钮按目标 ID/模式解析，不按显示名猜测；E10FormStore.navigate(menuKey,params) 只接受其中的菜单键，组合子键也适用。独立打开时返回不可用，应保留当前页并说明跳转目标；不把真实 URL 写为可执行外链。
+- buttonSet 与 formButtons 的 pageButtonRef 是实例身份；业务记录共享，按钮、过滤器、草稿按菜单隔离。
+- 所有 JSON 字段以实际字段 ID 为键；姓名/部门/关联为模拟实体。声明一个稳定种子，约 20 条主记录和 2–5 条明细；勿随机重建。
+- 不能为没有配置的页面固定增加业务按钮。但必须有导航返回/关闭、记录详情阅读、重置及适用的模拟评论/日志。
+- 评论、查阅/操作/修改/打印预览日志按 recordId 隔离，含 origin:'prototype'；没有配置时可补以上原型区域，明确关闭则遵从。编辑取消不写修改日志，新增未保存不允许评论，打印仅记录预览发起。
+- 日期时间格式、附件失效恢复、签名、未知控件可读替代、关联循环、本地错误提示与键盘焦点不能略去；未支持部分写明字段或动作 ID。
+- 读完所有配置分片后在 reviewDirectory 记录 coverage.json：已读分片、菜单/字段/按钮/视图映射、隐藏或替代项目及理由、参考布局来源、实际执行的视觉和操作检查。结果是本次实际观察，不能预填全通过。
+- 保存前比较草稿生成旧/新值日志；失败定位控件并保留输入。确认取消必须中止后续动作链，未知条件不得 eval。
+- 最终独立 HTML 的源码与生成 PNG 由 CLI 打包；无需构建栈。不要执行本文提到的线上接口，全部已由采集器处理。
+
+# 列表和布局按钮独立绑定
+
+## 生成入口
+
+使用采集模型的 pageBindings 按 menuId 选择页面。每个条目包含 target、params 和它自己的 buttonSet，不从表单上取统一按钮，也不使用 form.lists[0]。同表单可以有多个列表或布局入口，各自绑定对应配置。记录数据可共享，但按钮集合不能因共享表单而合并。
+
+组合页面的按钮属于当前顶部标签，不属于组合容器。使用包含 containerMenuId 和 tabId 的 pageKey/bindingPath 选择页面，pageButtonRef 同样包含组合路径；不能只用子菜单 ID 或组合父菜单 ID 索引全部标签按钮。
+
+采集器分别保存完整原始按钮和可用于渲染的规范化条目。buttonSet.scopeKey 是作用范围；buttonRef 包含范围与来源，pageBindings 中的 pageButtonRef 再包含 menuId。前端事件和实例状态使用 pageButtonRef，不能只用 buttonKey 或名称作为全局唯一键。每个菜单获得独立副本，渲染时不要修改其它页面共用的原始配置。
+
+| 类型     | 作用范围                                                   |
+| -------- | ---------------------------------------------------------- |
+| 传统列表 | 当前环境、appId、objId、listId                             |
+| 数据列表 | 当前环境、appId、objId、hostPageId、ebListId               |
+| 布局     | 当前环境、appId、objId、layoutId、增/查/改模式、记录上下文 |
+
+空 layoutId 表示接口默认布局，不代表可以拿来替代明确指定的另一个布局。显式 layoutId 可由 getFormButtons 参数传入，临时记录存在时先完成相应按钮采集再清理。无法确定实际 layoutId 时保留缺项，不套另一布局的按钮。
+
+## 保留按钮差异
+
+- 传统列表分别读取该列表的 getListButtons，保留 buttons、LineEndDropDownButtons 和其来源。
+- 数据列表分别读取该页组件配置，保留 buttonConfig.btns、topOperatBtns、bottomOperatBtns 和其它原始嵌套配置。不把按钮仅压缩成名称、key、位置。
+- 布局分别读取当前 objId/layoutId/模式的 getFormButtons。新增、编辑、查看不能互相借用；不同记录条件得到的结果也不能冒充通用全集。
+- 保留按钮 ID、名称、位置、顺序、enable/hidden、条件、动作链、目标和参数。规范化支持布尔值及 0/1、true/false 字符串，不能用 JavaScript 真值判断 "false"，也不能仅接受数字 1。
+- 原始配置中未解析的内容继续保留并按需分析，不能静默丢弃 custom action 或菜单覆盖参数。
+
+共用按钮组件和已确认的动作执行器可以；每次都把当前页面的配置传入。按钮同名但动作、条件或位置不同应有不同表现。两个页面接口返回配置相同，可以显示相同按钮，不为制造差异而改配置。
+
+## 禁止统一补业务按钮
+
+新建、导出、导入、批量新增/编辑/删除、共享等只能按当前页面配置出现，不能硬编码到所有工具栏。按钮在顶部、更多、行内或批量区的位置也按本页配置决定，不为了版式统一擅自移动。
+
+成功取得的空数组代表没有按钮。接口失败、字段缺失和配置无法识别分别记录状态，补采或说明限制，不回退其它列表/布局。必要的关闭、返回等原型导航控件可以补充并标记 prototype 来源，但不能拿“原型演示”作为补业务按钮的理由。
+
+规范化条目的 enabled 仅代表配置开关，不是最终可见性。还须结合当前展示模式、权限字段、位置与记录状态；只读列表不能照着 enabled 集合补一排业务操作。字段 eventGroup 指定的点击入口应落在该字段，不擅自挪到第一列。取得源 UI 证据时，把配置与实际显示的差异写入 coverage。
+
+前端应通过按钮所关联的完整动作配置执行本地模拟操作，不把所有同名/同 key 的自定义按钮硬连成一个默认动作。
+
+## 最小验证
+
+用同一表单的两个列表配置作对照：一个仅有新建，另一个仅有导出；切换后不得串按钮。再用同一表单的新增/查看/编辑和两个显式 layoutId 验证隔离。验证合法空数组、隐藏/禁用按钮、同名不同动作、字符串开关以及一个菜单副本被修改时另一个不变。只测试规则，不修改用户已有示例应用。
+
+# 组合页面：左侧菜单与顶部标签
+
+## 识别优先级
+
+CLI 将菜单 URL 路径 `/sp/appbuilder/combinedpage_preview/{appId}/` 或 `/sp/appbuilder/combinedpage_preview/{appId}/{combinationId}` 识别为组合容器。它只在任务绑定的登录环境采集；生成阶段使用 navigationPath 中已解析的组合信息，不访问菜单 URL。
+
+组合 URL 优先于 pageType。外层可能标记为 VIEWPORT 或 SEARCH，pageId 也可能是某个子页面的 ID；不能因此跳过组合详情接口，直接把它渲染成一个列表。
+
+URL 末尾未带 combinationId 时可使用菜单中的 combinationId，再与详情响应 ID 核对；两个显式 ID 冲突时报告。子页面自身也常携带 combinationId，所以不能仅凭它非空就再次识别成组合容器，避免递归查询。
+
+## 详情接口
+
+```text
+GET /api/cusapp/app/getCombMenus
+  ?appId={组合页所属appId}
+  &pid={当前组合菜单id}
+  &type=1
+  &terminalType=PC
+  &showType=0
+  &isComb=0
+  &isFront=0
+```
+
+固定公共路径，不使用独立部署前缀。pid 是菜单 id，不是父菜单 pid、组合定义 combinationId 或列表 pageId。其它参数使用上述已验证契约，不能从菜单 type=0 推导为请求 type=0。
+
+验证 HTTP 和业务结果，再读取 data：
+
+- id：真实组合定义 ID，与已知 combinationId 核对。
+- appId：组合所属应用。
+- combinationName、openPageTitle、pageTitle、pageIcon：组合名称及标题显示配置。
+- menuEntities：子页面数组；其 id 是标签身份，content/menuName 是标签名，showOrder/sort 决定顺序，defaultMenuSelect 决定默认项。
+
+每个子页面再次使用现有 SEARCH/VIEWPORT/LAYOUT 或直接 URL 规则解析。同一个响应中 SEARCH 子项的 tabs.pageViewType 即使写着 NList，也不把明确的 SEARCH 改成数据列表。selectLayout 的空字符串、空对象或字符串 "{}" 均视为未指定布局，不当作实际 layoutId。
+
+样例请求 pid=4268721562247693457，返回组合定义 1305737115397873665；其中子项 1305737115397873666 指向数据列表 1303501310072135681，子项 1305737115397873667 指向表格 1305647298989785090。这些 ID 只作契约示例，不硬编码。
+
+## 采集结构
+
+menus 中保留组合容器，target.kind=combined；其 tabs 保存支持的子页面，children 仍只代表正常导航分组。menu_pages 默认只枚举实际叶子页面，采集器据此获取子项的表单、字段、列表配置、布局和按钮。
+
+combinedPages 保存组合标题等配置；pageBindings 为容器提供 presentation=combined-top-tabs 和 tabs 引用，每个标签另有独立 pageKey、containerMenuId、tabId 和 buttonSet。bindingPath 为 [组合菜单id, 子菜单id]，pageButtonRef 也包含这个路径，防止不同组合引用相同标签时串状态或动作。
+
+按环境、appId、组合菜单 id 获取详情；同一轮正常只请求一次，不能按 combinationId 混用不同菜单上下文。表单和列表配置可按真实目标复用，但保留各标签的独立绑定与参数。
+
+## 页面呈现
+
+左侧保留一个组合菜单入口。进入后在内容区顶部显示标签栏，名称、顺序和默认项来自组合详情；下方只渲染当前标签的内容。不要把组合容器做成普通列表，也不要把所有子页面挪到左侧导航。
+
+标签可以分别是表格、数据列表或新增/查看/编辑布局。切换时切换对应的列、按钮、搜索、分页、记录上下文和布局模式；只复用 UI 组件，不共用一套按钮。标签状态按 pageKey 保存，不能因标签切换丢失未保存草稿；必要时提供放弃/保留提示。
+
+组合标签栏与布局底部的评论/日志标签是两套不同控件。外层标签切换具体页面，内层评论和日志始终绑定当前模拟记录。
+
+没有默认项时选第一个支持的标签。跳过不认识的子页面并记录原因；默认项被跳过或用户缩小范围后，重新选择有效标签。若全部子页面都不支持或接口失败，保留空态/不可用说明，不虚构标签，也不退回外层 pageId 假装组合详情已完成。首版不自动展开嵌套组合页，记录对应缺项。
+
+## 持久化与检查
+
+组合详情由 CLI 写入任务菜单树和 navigationPath。生成阶段按这些已解析的子页面映射、跳过原因和 contextPath 分片逐标签生成，不另建 menus.md，也不一次性把全量配置塞进上下文。
+
+最小验证覆盖：外层 VIEWPORT 被识别为组合；请求 pid 正确；缺少 URL 末段仍可获取详情；数据列表/表格/布局分别解析；未知子项跳过；两个标签按钮不串；同子菜单被多个组合引用时 pageKey 不冲突。沿用轻量验证要求，不改已有测试应用。
+
+本 CLI 的 pageBindings 等价于单菜单输入 page + buttons；组合信息见 navigationPath，所有 API 均已在采集阶段处理。读取 E10FormStore.parameters() 获取经主框架传入的本地参数，禁止加载其中任何远程资源。