@epoint-testtech/ep-stage-skill 0.0.10 → 0.0.12

package/codex-skill/ep-stage/code-list-generate/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: code-list-generate
+description: 使用时机：当用户（上游研发/出码方）要「生成 / 编写 / 产出 code_list.json5（出码总结、测试输入物料清单）」、交付需求给下游胶水测试流程、或显式触发 `/code-list-generate <源码根路径>` 时使用。即使用户只说「帮我把这个需求的源码整理成下游测试要的输入文件」「code_list 怎么写」，也应主动使用本 skill。本 skill 引导从 epoint 系源码（perpage/*.html + *Action.java + Entity.java）和 PRD 中提取事实，产出符合下游契约的 code_list.json5。
+version: 2026-08-17+delete-scope-fix
+argument-hint: "<源码根路径>（可选；不给则打印输入引导逐项询问）"
+---
+
+# code-list-generate：辅助上游生成 code_list.json5
+
+`code_list.json5` 是「上游出码总结」：下游 `glue-generate-testcase` 用它生成测试用例。你是上游（出码方），职责是**把本需求真实实现的页面、按钮、字段、后端逻辑、业务规则写成静态可溯源的事实清单**。
+
+先建立三个心智，再动手：
+
+1. **无来源不写入**。下游有条铁律"无来源不入契约"：你写的每个非平凡字段都应能指出出处（源码文件#锚点 或 PRD#章节），所以提取时顺手记 `evidence`。静态扫描看不到的运行时值（字典首选项、真实环境 origin）**不要编**，写进 `downstreamRuntimeNeeds` 说明"运行时才可确认"即可。
+2. **语义分类是锚点，比原文照抄更重要**。下游不靠中文按钮名猜功能，靠 `pages[].role`、`buttons[].action` 这些枚举值定位入口、生成用例。分类错一个，下游就少一类用例或定位错按钮。分类规则见下文「按钮 action 分类」。
+3. **留空优于编造**。账号、密码、运行态 URL（loginUrl/directUrl）上游不确定就留空，下游有交互补齐机制；但结构事实（页面、按钮、字段、规则）不能空。
+
+## 禁区（写了会污染下游，宁可缺）
+
+- 账号、密码、真实凭据 —— 那是环境侧数据，进下游 `credentials.json5`
+- 最终 Playwright locator / xpath —— 你只提供 HTML/MiniUI 元素线索，locator 由下游生成器产出
+- 测试用例、generationStrategy、执行结果、修补结论 —— 都是下游产物，不反向上灌
+
+## 调用方式
+
+```text
+/code-list-generate F:/knowledge-project/epoint-web-v9.5.2   # 给源码根 → 校验通过后继续收集其余输入
+/code-list-generate                                          # 无参数 → 打印输入引导，逐项询问
+帮我把 zwplace 模块整理成 code_list.json5，源码在 …           # 自然语言 → 同样进入本流程
+```
+
+入参按「源码根路径」理解：必须是能覆盖 `src/main/webapp/perpage/<模块>/` 与 `src/main/java/com/epoint/<模块>/` 的源码目录。路径不存在或结构不吻合时，不猜，直接向用户确认。
+
+## 执行流程
+
+**任务清单协议**：load 后**最先**单行展示技能版本（取本 SKILL.md frontmatter 的 `version` 字段），格式 `技能版本：code-list-generate <version>`；随后立即打印初始任务清单（Step 0）；每完成一步输出单行 `第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 6 输出全勾选终态清单。
+
+### Step 0 — 打印任务清单
+
+```markdown
+**生成 code_list.json5 任务清单**
+
+- [ ] 第 1 步 — 收集输入（源码根 / 需求目录 / 需求文档）
+- [ ] 第 2 步 — 定位模块边界并确认
+- [ ] 第 3 步 — 提取页面、后端、规则事实
+- [ ] 第 4 步 — 组装 code_list.json5
+- [ ] 第 5 步 — 自校验
+- [ ] 第 6 步 — 交付与人审提示
+```
+
+### Step 1 — 收集输入
+
+从用户消息 / args 抽取源码根路径并绝对化，校验存在性与 epoint 结构（含 `src/main/webapp/perpage/` 与 `src/main/java/com/epoint/`）。四样输入的齐全度决定问什么：
+
+- **源码根**（必须）：包含本需求出码的源码目录。缺失 / 路径不存在 / 结构不吻合 → 不猜，free text 询问
+- **需求目录**（建议）：决定落盘位置。**落盘契约是硬性的**：必须写到 `<需求名目录>/_docs/code_list.json5`——下游按"code_list.json5 父目录的父目录的 basename"推导需求名，父目录必须叫 `_docs`。注意 `_docs/<需求名>/code_list.json5` 这类布局会让需求名被算成 `_docs`，是错误落盘。若源码根里能定位到需求目录结构则推断并告知用户，否则询问
+- **需求文档**（可选但推荐）：PRD / 需求确认单。缺失时明确告知"将按纯源码出稿，requirement 节标待补"，然后继续
+- **需求 ID / 名称**（可选）：写入 `requirement.id/name`；缺失时用需求目录名兜底并在注释里说明
+
+**无参数调用时**，先打印输入引导再收集：
+
+> **生成 code_list.json5 需要这些输入：**
+>
+> 1. **源码根路径**（必须）——包含 `src/main/webapp/perpage/<模块>/` 和 `src/main/java/com/epoint/<模块>/` 的源码目录，如 `F:/knowledge-project/epoint-web-v9.5.2`
+> 2. **需求目录**（建议）——code_list.json5 会写到 `<需求目录>/_docs/` 下
+> 3. **PRD / 需求文档路径**（可选）——有它需求事实、业务角色和 PRD 缺口对照才完整；没有就先按源码出稿
+> 4. **需求 ID / 名称**（可选）——如 REQ0011 / 014-测试需求10
+>
+> 直接把路径发我即可（可一次给全）。
+
+### Step 2 — 定位模块边界
+
+从需求名/PRD 推模块英文标识：找 `src/main/webapp/perpage/<module>/` 目录和 `src/main/java/com/epoint/<module>/` 包。把找到的页面 HTML、Action、Service、Entity 文件列给用户确认："我识别到模块 `<module>`，包含这 N 个页面、M 个 Action，对吗？"——模块边界圈错，后面全错。
+
+### Step 3 — 提取事实
+
+按 `references/epoint-extraction.md` 的方法逐类提取：页面四角色、查询字段、按钮、行操作、表单字段、子表、后端方法、数据模型、实体、业务规则。该文件含每类事实在 epoint 源码里的具体位置和抠取方法。
+
+### Step 4 — 组装文件
+
+1. 拷贝 `assets/code_list.template.json5` 为底稿，逐节替换占位内容
+2. 拿不准某节的写法时，对照 `assets/example-zwplace.json5`（一份真实需求的完整实例）
+3. 字段含义、必填性、下游消费点查 `references/field-contract.md`
+
+### Step 5 — 自校验
+
+```bash
+node <skill目录>/scripts/validate-code-list.mjs <需求目录>/_docs/code_list.json5
+```
+
+脚本校验：JSON5 可解析、必填字段齐全、action 枚举合法、源码路径真实存在、无凭据泄漏。脚本全绿后再人工过一遍「交付前对照清单」（本文件末节）。
+
+### Step 6 — 交付与人审提示
+
+写入 `<需求目录>/_docs/code_list.json5`，然后中文提示用户：
+
+> code_list.json5 已生成。请重点人工复核：
+> 1. 按钮 action 分类（create/delete/export/custom）是否与页面实际一致
+> 2. businessRules 是否漏了源码里的校验/阻断文案
+> 3. prdMentionedButNotImplemented 是否如实反映了 PRD 有但未做的部分
+>
+> 交付下游后即可运行 `/glue-generate-testcase <需求目录>/_docs/code_list.json5`。
+
+## 按钮 action 分类（下游效果的直接来源）
+
+`pages[].buttons[].action` 只允许这几个值，每个值直接决定下游生成什么：
+
+| action | 用在哪 | 下游效果 |
+|---|---|---|
+| `create` | 列表页"新增xx"按钮；新增页"保存并关闭" | 生成新增用例入口；label 用于拼定位表达式 |
+| `delete` | 列表页"删除选定" | 生成删除用例；配合 businessRules 决定删除断言 |
+| `export` | 列表页导出（mini-dataexport 组件） | 生成导出用例 |
+| `custom` | 列表页其他业务按钮（如"同步窗口管理系统"） | 进入 AI 候选用例，须补 `customAction` + `backendMethod` |
+| `save` | 新增/编辑页"保存"（草稿） | 须补 `customAction`（如 saveDraft）|
+| `update` | 编辑页"保存并关闭" | 生成更新用例的提交动作 |
+| `cancel` | "关闭"按钮 | 不生成用例，仅记录 |
+
+行操作 `rowActions[]`：列表行内"修改"用 `actionName: 'openEdit'` 或 `action: 'edit'`（下游按此找编辑入口）；"查看"用 `actionName: 'openDetail'`。
+
+**businessRules 的放大效应**：`scope` 含 `'delete'` 的规则会让下游把删除用例断言改为"阻断"，并把 `assertionHint`（如"在用数据不可删除！"）作为预期提示文案。源码里 Action 方法中的校验消息、必填提示都是业务规则，不要漏。
+
+**`scope: ['delete']` 的纪律**：只有「记录状态/条件阻断删除」的规则（如"在用数据不可删除"）才配 `scope: ['delete']` + `assertionHint`。「未勾选拦截」（如"请选择要删除的数据！"）、「二次确认文案」这类**操作前置提示不标 delete scope**（可标 `scope: ['ui']` 或并入其他规则的 description）——下游把 scope 含 delete 的规则当作删除断言策略来源（装配器虽有"优先阻断语义文案"的自愈，但只是兜底，不应依赖）。若确有多条 delete scope 规则，记录级阻断规则必须排最前。
+
+## 查询字段与数据主键
+
+- `pages[role=list].queryFields[]`：`component: 'mini-textbox'` → 输入框；`'mini-combobox'` → 下拉。带 `bind: 'dataBean.xxx'` 时下游能推出字段名。
+- 查询字段若同时出现在新增页 `formFields[]`，下游会为它生成完整 增/查/改/删 四条用例；只在列表页出现的只生成查询用例。
+- `entities[].fields[]` 里标 `dataKey: true` 的字段是业务主键（如场所名称），下游用它做测试数据的种子值。
+
+## 角色（凭据模板的行数来源）
+
+角色有三个承载位置，**语义不同，不要混用**：
+
+| 位置 | 语义 | 放什么 |
+|---|---|---|
+| `requirement.businessRoles[]` | PRD 角色**事实** | PRD 提到的全部角色，如实写全（含无实现入口的）——这是需求事实，不删 |
+| **顶层 `roles[]`** | 本次交付**需要登录执行**的角色 | 只放有实现入口、要跑用例的角色（如 业务管理员）。**下游凭据模板/requiredRoles 的直接事实源** |
+| `testAccess.systems[].roles[]` | 登录访问模板骨架 | 与顶层 `roles[]` 同一角色集，username/password 留空 |
+
+**实测教训（假修复）**：只精简 testAccess 是不够的——下游消费优先级是 `顶层 roles[]` > `requirement.businessRoles` > `testAccess`。businessRoles 里的 PRD 角色删不得（是需求事实），不写顶层 roles[] 圈定，凭据模板就会按 businessRoles 全量生成，给用不到的角色造出凭据行。**凡是 PRD 角色 ≠ 需登录角色，就必须写顶层 roles[]**（每项：`systemName` / `role` / `permission` / `description` / `menuPath` 可选）。
+
+## 系统名与模块名取源
+
+- `systems[].name`：最终用户登录的那个系统的**正式中文全称**（须与下游 credentials.json5 的 systemName 严格一致）。取源优先级：PRD/需求文档写明的业务系统名 > 运行系统登录页/标题 > project_context 的 products[].name。**产品/项目代号不是系统名**（如实测中误取「综管」而真实系统名是「集成受理平台」）；只有代号可用时，填代号并在 `downstreamRuntimeNeeds` 登记"系统名待确认"。
+- `moduleName`：取需求/PRD 的**模块中文业务名**（如"场所窗口信息管理"），不取单个页面的 title（"场所信息管理列表"这类进 `pages[].title`）。
+
+## 交付前对照清单
+
+- [ ] 顶层 `module` / `moduleName` / `systems` / `pages` 齐全
+- [ ] 落盘位置是 `<需求名目录>/_docs/code_list.json5`（父目录必须叫 `_docs`，否则下游需求名推导出错）
+- [ ] `sourceRoot.root` 是绝对路径，所有 `pages[].path`、`sourceFiles` 路径在其下真实存在
+- [ ] `pages[role=list]` 有 `queryFields`、`buttons`、`rowActions`；`directUrl` 已知则填，不知留空
+- [ ] 每个按钮的 `action` 分类与上表一致，`custom` 按钮带 `customAction` + `backendMethod`
+- [ ] 子表列的 `component` 只写了 `input` / `listbox`（或直接省略），没有写 MiniUI 组件名
+- [ ] `businessRules` 覆盖源码里所有校验/阻断文案；删除类规则带 `assertionHint`（一条规则一个主文案），且只有记录级阻断规则标 `scope: ['delete']`（拦截提示标 `ui`）
+- [ ] `systems[].name` 是系统正式中文全称（非产品代号）；`moduleName` 是模块业务名（非单页 title）
+- [ ] PRD 角色与需登录角色不一致时，已写顶层 `roles[]` 圈定；`testAccess` 角色集与之对齐
+- [ ] `routeHints.contextPathHint` 有来源才写，无来源则留空并登记 `downstreamRuntimeNeeds`
+- [ ] 运行态才能确认的值都进了 `downstreamRuntimeNeeds`，没有编造的静态事实
+- [ ] 全文无账号密码、无最终 locator
+- [ ] validate 脚本全绿
+
+## 按需加载
+
+- `references/field-contract.md` — 逐字段契约：含义、必填性、下游消费点、枚举值
+- `references/epoint-extraction.md` — epoint 系源码提取方法（MiniUI 组件、Action 注解、实体映射）
+- `assets/code_list.template.json5` — 带注释的空模板（组装的起点）
+- `assets/example-zwplace.json5` — 完整真实实例（写法拿不准时对照）

package/codex-skill/ep-stage/code-list-generate/assets/code_list.template.json5

@@ -0,0 +1,325 @@
+/**
+ * code_list.json5 模板 —— 上游出码总结
+ *
+ * 用法：拷贝本文件到 <需求目录>/_docs/code_list.json5，逐节替换 <尖括号> 占位内容，
+ * 删除用不到的节（如无子表删 childGrids、无 custom 按钮删对应条目）。
+ * 完整实例参考同目录 example-zwplace.json5；字段契约见 references/field-contract.md。
+ *
+ * 三条铁律：无来源不写入（带 evidence）；语义分类是锚点（role/action 枚举）；
+ * 留空优于编造（账号密码、运行态 URL 可留空，结构事实不能空）。
+ */
+{
+  schemaVersion: 'ep-stage-code-list/v1-draft',
+
+  /* ─────── 需求事实（从 PRD 提取）─────── */
+  requirement: {
+    id: '<需求ID，如 REQ0011；缺失时用需求目录名兜底并注释说明>',
+    name: '<需求名称>',
+    type: '<新增功能/功能优化/缺陷修复>',
+    priority: '<高/中/低>',
+    targetEnds: ['<PC-管理端/H5-移动端/...>'],
+    businessRoles: [
+      {
+        label: '<角色名，如 业务管理员>',
+        targetEnd: '<所属端>',
+        responsibilities: ['<职责描述>'],
+        evidence: ['<PRD文件名>#<章节锚点>'],
+      },
+    ],
+  },
+
+  /* ─────── 源码根（下游解析 pages[].path 的依据）─────── */
+  sourceRoot: {
+    root: '<源码根绝对路径，如 F:/project/epoint-web-v9.5.2>',
+    pathBase: 'knowledgeRoot',
+    sourceFilesAreRelativeTo: 'sourceRoot.root',
+  },
+
+  /* ─────── 模块标识（CLI 四大必填之二）─────── */
+  module: '<模块英文标识，取 perpage 目录名/java 包名>',
+  moduleName: '<模块中文名>',
+  description: '<一句话概括本次出码覆盖范围>',
+
+  /* ─────── 业务系统（CLI 四大必填之三）─────── */
+  systems: [
+    {
+      // 系统正式中文全称（最终用户登录的那个系统），非产品/项目代号；
+      // 取源优先级：PRD > 登录页标题 > project_context products[].name；只有代号可用时登记 downstreamRuntimeNeeds
+      name: '<系统中文全称；须与下游 credentials.json5 的 systemName 严格一致>',
+      version: '<平台版本>',
+      frameVersion: '<框架版本>',
+      targetEnd: '<目标端>',
+      defaultLoginUrl: '<登录地址样板；不确定可留空>',
+      evidence: ['<出处>'],
+    },
+  ],
+
+  /* ─────── 顶层 roles[]：本次交付需要登录执行的角色（下游凭据模板/requiredRoles 的事实源）─────── */
+  /* 下游优先级：roles[] > requirement.businessRoles > testAccess。PRD 角色 ≠ 需登录角色时必须写本节圈定，
+     否则凭据模板会按 businessRoles 全量生成。两者一致时本节可省略。 */
+  roles: [
+    {
+      systemName: '<与 systems[].name 一致>',
+      role: '<角色名>',
+      permission: '<权限说明>',
+      description: '<角色业务描述>',
+    },
+  ],
+
+  /* ─────── 登录访问模板骨架（账号密码一律留空；角色集与顶层 roles[] 对齐）─────── */
+  testAccess: {
+    systems: [
+      {
+        systemName: '<与 systems[].name 一致>',
+        loginUrl: '',
+        roles: [
+          {
+            role: '<角色名>',
+            username: '',
+            password: '',
+            permissions: ['<权限点，如 新增/修改/删除/导出/查看>'],
+          },
+        ],
+      },
+    ],
+  },
+
+  moduleInfo: {
+    id: '<同 module>',
+    name: '<同 moduleName>',
+    packagePath: 'com.epoint.<module>',
+    frontendBasePath: 'src/main/webapp/perpage/<module>',
+    backendBasePath: 'src/main/java/com/epoint/<module>',
+    deriveRule: '<如何归纳出模块标识的一句话>',
+  },
+
+  /* ─────── 实现范围与 PRD 缺口（双向对照，只写静态可证实的）─────── */
+  implementedScope: [
+    {
+      featureId: 'F001',
+      featureName: '<功能点名>',
+      implementedBy: ['pages.list', 'backend.actions.<XxxAction>'],
+    },
+  ],
+  prdMentionedButNotImplemented: [
+    {
+      featureIds: ['F0xx'],
+      featureName: '<PRD 有但未实现的功能>',
+      reason: '<PRD 描述了…，但 sourceFiles 中未发现对应页面或实现文件>',
+    },
+  ],
+
+  /* ─────── 出码文件清单（页面 evidence 的引用目标）─────── */
+  sourceFiles: {
+    frontend: [
+      { role: 'list', path: 'src/main/webapp/perpage/<module>/<x>list.html', title: '<页面标题>' },
+      // 按需补 add / edit / detail
+    ],
+    actions: [
+      { name: '<XxxListAction>', path: 'src/main/java/com/epoint/<module>/action/<XxxListAction>.java', restController: '<xxxlistaction>' },
+    ],
+    services: [
+      { name: '<IXxxService>', path: '.../api/<IXxxService>.java', kind: 'interface' },
+      { name: '<XxxServiceImpl>', path: '.../impl/<XxxServiceImpl>.java', kind: 'serviceImpl' },
+      { name: '<XxxService>', path: '.../impl/<XxxService>.java', kind: 'dao' },
+    ],
+    entities: [
+      { name: '<XxxEntity>', path: '.../api/entity/<XxxEntity>.java', table: '<表名>' },
+    ],
+  },
+
+  /* ─────── 页面事实（CLI 四大必填之四）─────── */
+  pages: [
+    /* ─── 列表页 ─── */
+    {
+      pageId: '<x>list',
+      role: 'list',
+      title: '<页面标题>',
+      path: 'src/main/webapp/perpage/<module>/<x>list.html',
+      initAction: '<xxxlistaction>',
+      directUrl: '<待测列表页直达链接；不确定留空，下游交互补齐>',
+      description: '<页面能力一句话>',
+      queryFields: [
+        // mini-textbox → 输入框；mini-combobox → 下拉（补 modelRef）
+        { label: '<查询字段中文标签>', bind: 'dataBean.<field>', component: 'mini-textbox' },
+        { label: '<下拉查询字段>', bind: 'dataBean.<field>', component: 'mini-combobox', modelRef: '<field>Model' },
+      ],
+      toolbarActions: [
+        { label: '<按钮原文>', actionName: '<JS函数名>', opens: 'pages.add' },
+      ],
+      // action 枚举：create/delete/export/custom/save/update/cancel —— 分类决定下游生成什么用例
+      buttons: [
+        { label: '<新增xx>', action: 'create', backendMethod: null },
+        { label: '<删除选定>', action: 'delete', backendMethod: '<deleteSelect>' },
+        { label: '<导出>', action: 'export', backendMethod: '<getExportModel>' },
+        // 其他业务按钮：action: 'custom' + customAction + backendMethod → 进入 AI 候选用例
+      ],
+      rowActions: [
+        { label: '修改', actionName: 'openEdit', opens: 'pages.edit' },
+        { label: '查看', actionName: 'openDetail', opens: 'pages.detail' },
+      ],
+      dataGrid: {
+        id: 'datagrid',
+        idField: '<主键字段，如 rowguid>',
+        backendMethod: '<getDataGridData>',
+        columns: [{ field: '<field>', label: '<列头中文>' }],
+      },
+      backendMethods: ['<该页 Action 的方法名清单>'],
+      evidence: ['sourceFiles.frontend[role=list]', 'sourceFiles.actions[name=<XxxListAction>]'],
+    },
+
+    /* ─── 新增页 ─── */
+    {
+      pageId: '<x>add',
+      role: 'add',
+      title: '<页面标题>',
+      path: 'src/main/webapp/perpage/<module>/<x>add.html',
+      initAction: '<xxxaddaction>',
+      description: '<页面能力一句话>',
+      formFields: [
+        { label: '<字段中文>', bind: 'dataBean.<field>', component: 'mini-textbox', required: true, maxLength: 50 },
+      ],
+      toolbarActions: [
+        { label: '保存', actionName: 'save', backendMethod: '<saveDraft>' },
+        { label: '保存并关闭', actionName: 'saveAndClose', backendMethod: '<add>' },
+        { label: '关闭', actionName: "epoint.closeDialog('close')" },
+      ],
+      buttons: [
+        { label: '保存', action: 'save', customAction: '<saveDraft>', backendMethod: '<saveDraft>' },
+        { label: '保存并关闭', action: 'create', backendMethod: '<add>' },
+        { label: '关闭', action: 'cancel', backendMethod: null },
+      ],
+      rowActions: [],
+      // 有内嵌子表时取消注释；无子表整节删除
+      // 注意：columns[].component 只能写 'input'/'listbox'（下游门禁强校验），拿不准就不写该键
+      // childGrids: [
+      //   {
+      //     id: '<grid的DOM id>',
+      //     label: '<子表中文名>',
+      //     actions: [{ label: '<添加xx>', actionName: '<addXxx>' }],
+      //     columns: [{ field: '<field>', label: '<列头>', required: true, component: 'input', modelRef: '<下拉时补>' }],
+      //   },
+      // ],
+      backendMethods: ['<方法名清单>'],
+      evidence: ['sourceFiles.frontend[role=add]', 'sourceFiles.actions[name=<XxxAddAction>]'],
+    },
+
+    /* ─── 编辑页（字段/子表与新增页相同可用 same_as 引用）─── */
+    {
+      pageId: '<x>edit',
+      role: 'edit',
+      title: '<页面标题>',
+      path: 'src/main/webapp/perpage/<module>/<x>edit.html',
+      initAction: '<xxxeditaction>',
+      description: '<页面能力一句话>',
+      formFields: ['same_as_pages.add.formFields'],
+      childGrids: ['same_as_pages.add.childGrids'],
+      toolbarActions: [
+        { label: '保存', actionName: 'save', backendMethod: '<saveDraft>' },
+        { label: '保存并关闭', actionName: 'saveAndClose', backendMethod: '<save>' },
+        { label: '关闭', actionName: "epoint.closeDialog('close')" },
+      ],
+      buttons: [
+        { label: '保存', action: 'save', customAction: '<saveDraft>', backendMethod: '<saveDraft>' },
+        { label: '保存并关闭', action: 'update', backendMethod: '<save>' },
+        { label: '关闭', action: 'cancel', backendMethod: null },
+      ],
+      rowActions: [],
+      backendMethods: ['<pageLoad 等方法清单>'],
+      evidence: ['sourceFiles.frontend[role=edit]', 'sourceFiles.actions[name=<XxxEditAction>]'],
+    },
+
+    /* ─── 详情页（只读；无则整节删除）─── */
+    {
+      pageId: '<x>detail',
+      role: 'detail',
+      title: '<页面标题>',
+      path: 'src/main/webapp/perpage/<module>/<x>detail.html',
+      initAction: '<xxxdetailaction>',
+      description: '<只读展示说明>',
+      buttons: [{ label: '关闭', action: 'cancel', backendMethod: null }],
+      rowActions: [],
+      backendMethods: ['<pageLoad 等>'],
+      evidence: ['sourceFiles.frontend[role=detail]'],
+    },
+  ],
+
+  /* ─────── 后端事实 ─────── */
+  backend: {
+    callChain: '前端页面 -> Action -> I<Xxx>Service -> <Xxx>ServiceImpl -> <Xxx>Service(DAO) -> 数据库',
+    actions: [
+      {
+        name: '<XxxListAction>',
+        restController: '<xxxlistaction>',
+        methods: [
+          { name: '<方法名>', description: '<一句话说明，含校验/阻断行为>' },
+        ],
+      },
+    ],
+    services: [
+      { name: '<XxxService>', kind: 'dao', methods: ['<insert>', '<deleteByGuid>'] },
+    ],
+  },
+
+  /* ─────── 下拉数据模型（有下拉才保留）─────── */
+  dataModels: [
+    {
+      ref: '<field>Model',
+      label: '<中文名>',
+      sourceKind: 'dictionary_runtime', // dictionary_runtime / static_options / db_runtime
+      actionMethods: ['<XxxAction.getXxxModel>'],
+      dictionaryCode: '<字典code>',      // dictionary_runtime 时填；static_options 改用 options: [...]
+      optionsKnownAtStaticTime: false,   // 运行态才知道选项时务必 false，不要把猜的选项写进来
+    },
+  ],
+
+  /* ─────── 实体（业务主键标 dataKey: true，下游用它做测试数据种子）─────── */
+  entities: [
+    {
+      name: '<XxxEntity>',
+      table: '<表名>',
+      description: '<实体说明>',
+      fields: [
+        { name: '<field>', type: 'String(50)', label: '<中文>', dataKey: true },
+      ],
+    },
+  ],
+
+  /* ─────── 业务规则（源码里的校验/阻断文案，删除类规则直接决定下游删除断言）─────── */
+  businessRules: [
+    {
+      ruleId: 'delete.<xxx>',
+      description: '<如：仅草稿状态可删除，非草稿删除被阻断>',
+      scope: ['delete'],
+      sourceKind: 'static_scan',
+      assertionHint: '<阻断提示原文，如 在用数据不可删除！>',
+      evidence: ['src/main/java/com/epoint/<module>/action/<XxxListAction>.java#<deleteSelect>'],
+    },
+  ],
+
+  /* ─────── 集成点（无则整节删除）───────
+  integrations: [
+    {
+      integrationId: '<id>',
+      label: '<名称>',
+      trigger: '<触发入口>',
+      currentImplementation: '<service_stub / 已实现 / ...>',
+      evidence: ['<出处>'],
+    },
+  ],
+  ─────── */
+
+  /* ─────── 路由线索 ─────── */
+  routeHints: {
+    // 有来源才写（真实部署 context path / loginUrl 反推）；无来源留空字符串并登记 downstreamRuntimeNeeds
+    contextPathHint: '/epoint-web',
+    rule: '运行环境 origin + contextPathHint + 页面 path 去掉 src/main/webapp 后的路径。',
+    pages: [{ pageId: '<x>list', routePath: '/perpage/<module>/<x>list.html' }],
+    runtimeOriginRequired: true,
+  },
+
+  /* ─────── 运行态待补（静态扫不到的值登记在这里，不编造）─────── */
+  downstreamRuntimeNeeds: [
+    { needId: 'runtime.origin', description: '真实运行环境 origin 由运行配置或人工交互提供。' },
+  ],
+}