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

package/codex-skill/ep-stage/code-list-generate/evals/grade-code-list.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * code-list-generate eval 断言评分脚本
+ *
+ * 用法：node grade-code-list.mjs <code_list.json5路径> <evalId:0|1> <grading.json输出路径>
+ *
+ * 产出 grading.json：{ expectations: [{ text, passed, evidence }] }（viewer 依赖这三个字段名）
+ * 只评可程序化断言；qualitative 断言由人工/grader 补充合并。
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+function findJson5Entry() {
+  let dir = scriptDir;
+  while (true) {
+    const plain = path.join(dir, 'node_modules', 'json5', 'lib', 'index.js');
+    if (existsSync(plain)) return plain;
+    const pnpmStore = path.join(dir, 'node_modules', '.pnpm');
+    if (existsSync(pnpmStore)) {
+      const hit = readdirSync(pnpmStore).find((d) => d.startsWith('json5@'));
+      if (hit) {
+        const p = path.join(pnpmStore, hit, 'node_modules', 'json5', 'lib', 'index.js');
+        if (existsSync(p)) return p;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+let JSON5;
+try {
+  ({ default: JSON5 } = await import('json5'));
+} catch {
+  ({ default: JSON5 } = await import(pathToFileURL(findJson5Entry()).href));
+}
+
+const [codeListPath, evalId, outPath] = process.argv.slice(2);
+const expectations = [];
+const check = (text, passed, evidence) => expectations.push({ text, passed: Boolean(passed), evidence: String(evidence ?? '') });
+
+/* ──────── 解析 ──────── */
+let data = null;
+if (!existsSync(codeListPath)) {
+  check('产物文件存在且 JSON5 可解析', false, `文件不存在：${codeListPath}`);
+} else {
+  try {
+    data = JSON5.parse(readFileSync(codeListPath, 'utf-8'));
+    check('产物文件存在且 JSON5 可解析', true, '解析成功');
+  } catch (e) {
+    check('产物文件存在且 JSON5 可解析', false, `解析失败：${e.message}`);
+  }
+}
+
+if (data && typeof data === 'object') {  /* ──────── 通用断言 ──────── */
+  const missing = ['module', 'moduleName', 'systems', 'pages'].filter((k) => !data[k]);
+  check('四大必填字段齐全（module/moduleName/systems/pages）', missing.length === 0, missing.length ? `缺：${missing.join(',')}` : '齐全');
+
+  const expectedModule = evalId === '0' ? 'zwplace' : 'schemeresource';
+  check(`module 标识正确（${expectedModule}）`, data.module === expectedModule, `实际：${data.module}`);
+
+  const roles = new Set((data.pages ?? []).map((p) => p?.role));
+  const needRoles = ['list', 'add', 'edit', 'detail'];
+  check('pages 覆盖 list/add/edit/detail 四角色', needRoles.every((r) => roles.has(r)), `实际角色：${[...roles].join(',') || '无'}`);
+
+  const listPage = (data.pages ?? []).find((p) => p?.role === 'list');
+  const listActions = new Set((listPage?.buttons ?? []).map((b) => b?.action));
+
+  if (evalId === '0') {
+    const hasCore = ['create', 'delete', 'export'].every((a) => listActions.has(a));
+    const syncBtn = (listPage?.buttons ?? []).find((b) => /同步/.test(b?.label ?? ''));
+    check('list 页按钮分类：含 create/delete/export', hasCore, `实际 action：${[...listActions].join(',') || '无'}`);
+    check('「同步窗口管理系统」分类为 custom', syncBtn?.action === 'custom', `实际：${syncBtn ? syncBtn.action : '未找到该按钮'}`);
+
+    const qf = listPage?.queryFields ?? [];
+    const byLabel = (s) => qf.find((f) => (f?.label ?? '').includes(s));
+    const isInput = (f) => ['mini-textbox', 'input'].includes(f?.component ?? f?.type ?? '');
+    const isListbox = (f) => ['mini-combobox', 'listbox'].includes(f?.component ?? f?.type ?? '');
+    check(
+      'queryFields ≥3 且输入框/下拉区分正确（场所名称=textbox；场所分类/状态=combobox）',
+      qf.length >= 3 && isInput(byLabel('场所名称')) && isListbox(byLabel('场所分类')) && isListbox(byLabel('状态')),
+      `实际：${qf.map((f) => `${f?.label}=${f?.component ?? f?.type ?? '?'}`).join('，') || '无 queryFields'}`,
+    );
+
+    const addPage = (data.pages ?? []).find((p) => p?.role === 'add');
+    const grids = addPage?.childGrids ?? [];
+    const winGrid = grids.find?.((g) => JSON.stringify(g).includes('window'));
+    check(
+      'add 页含窗口信息子表（≥2 列且含 windowname 字段）',
+      Boolean(winGrid) && (winGrid.columns ?? []).length >= 2 && JSON.stringify(winGrid.columns).includes('windowname'),
+      winGrid ? `子表列：${(winGrid.columns ?? []).map((c) => c?.field).join(',')}` : '未找到子表',
+    );
+
+    const deleteRule = (data.businessRules ?? []).find((r) => (r?.scope ?? []).includes('delete'));
+    const hint = deleteRule?.assertionHint ?? deleteRule?.assertion ?? deleteRule?.description ?? '';
+    check('businessRules 含删除阻断规则且提示含「不可删除」', Boolean(deleteRule) && hint.includes('不可删除'), deleteRule ? `hint：${hint}` : '未找到 delete 规则');
+
+    const tables = (data.entities ?? []).map((e) => e?.table);
+    check('entities 覆盖 gxh_zw_place 与 gxh_zw_window', ['gxh_zw_place', 'gxh_zw_window'].every((t) => tables.includes(t)), `实际：${tables.join(',') || '无'}`);
+
+    const kinds = new Set((data.dataModels ?? []).map((m) => m?.sourceKind));
+    check('dataModels 区分 dictionary_runtime 与 static_options', kinds.has('dictionary_runtime') && kinds.has('static_options'), `实际 sourceKind：${[...kinds].join(',') || '无 dataModels'}`);
+
+    const editPage = (data.pages ?? []).find((p) => p?.role === 'edit');
+    const saveClose = (editPage?.buttons ?? []).find((b) => (b?.label ?? '').includes('保存并关闭'));
+    check('edit 页「保存并关闭」action=update 且 backendMethod=save', saveClose?.action === 'update' && saveClose?.backendMethod === 'save', saveClose ? `action=${saveClose.action}, backendMethod=${saveClose.backendMethod}` : '未找到该按钮');
+  }
+
+  if (evalId === '1') {
+    check('list 页按钮含 create/delete/export 分类', ['create', 'delete', 'export'].every((a) => listActions.has(a)), `实际 action：${[...listActions].join(',') || '无'}`);
+    const qf = listPage?.queryFields ?? [];
+    const labels = qf.map((f) => f?.label ?? '');
+    check('list 页 queryFields ≥2 且 label 来自源码（名称/类型/简介）', qf.length >= 2 && ['名称', '类型'].every((s) => labels.some((l) => l.includes(s))), `实际：${labels.join('，') || '无 queryFields'}`);
+  }
+
+  /* sourceRoot 与路径解析 */
+  const root = data.sourceRoot?.root;
+  if (!root) {
+    check('sourceRoot.root 提供且 pages[].path 全部可解析', false, '未提供 sourceRoot.root');
+  } else if (!existsSync(path.resolve(root))) {
+    check('sourceRoot.root 提供且 pages[].path 全部可解析', false, `root 不存在：${root}`);
+  } else {
+    const bad = (data.pages ?? []).filter((p) => p?.path && !existsSync(path.resolve(root, p.path))).map((p) => p.path);
+    check('sourceRoot.root 提供且 pages[].path 全部可解析', bad.length === 0, bad.length ? `不可解析：${bad.join(',')}` : '全部可解析');
+  }
+
+  /* 凭据禁区 */
+  const secrets = [];
+  (function scan(obj, trail) {
+    if (!obj || typeof obj !== 'object') return;
+    for (const [k, v] of Object.entries(obj)) {
+      if (/password|passwd|secret|token/i.test(k) && typeof v === 'string' && v.trim()) secrets.push(trail ? `${trail}.${k}` : k);
+      scan(v, trail ? `${trail}.${k}` : k);
+    }
+  })(data, '');
+  check('无明文凭据（password 类字段全部留空）', secrets.length === 0, secrets.length ? `泄漏：${secrets.join(',')}` : '无');
+
+  /* evidence 溯源 */
+  const hasEvidence =
+    (data.pages ?? []).some((p) => Array.isArray(p?.evidence) && p.evidence.length) ||
+    (data.businessRules ?? []).some((r) => Array.isArray(r?.evidence) && r.evidence.length);
+  check('关键事实带 evidence 溯源（pages 或 businessRules）', hasEvidence, hasEvidence ? '有 evidence' : '全文无 evidence');
+} else {
+  // 解析失败：本 eval 其余程序化断言全部判不通过（产物不可消费，无法评估）
+  const rest =
+    evalId === '0'
+      ? [
+          '四大必填字段齐全（module/moduleName/systems/pages）',
+          'module 标识正确（zwplace）',
+          'pages 覆盖 list/add/edit/detail 四角色',
+          'list 页按钮分类：含 create/delete/export',
+          '「同步窗口管理系统」分类为 custom',
+          'queryFields ≥3 且输入框/下拉区分正确（场所名称=textbox；场所分类/状态=combobox）',
+          'add 页含窗口信息子表（≥2 列且含 windowname 字段）',
+          'businessRules 含删除阻断规则且提示含「不可删除」',
+          'entities 覆盖 gxh_zw_place 与 gxh_zw_window',
+          'dataModels 区分 dictionary_runtime 与 static_options',
+          'edit 页「保存并关闭」action=update 且 backendMethod=save',
+          'sourceRoot.root 提供且 pages[].path 全部可解析',
+          '无明文凭据（password 类字段全部留空）',
+          '关键事实带 evidence 溯源（pages 或 businessRules）',
+        ]
+      : [
+          '四大必填字段齐全（module/moduleName/systems/pages）',
+          'module 标识正确（schemeresource）',
+          'pages 覆盖 list/add/edit/detail 四角色',
+          'list 页按钮含 create/delete/export 分类',
+          'list 页 queryFields ≥2 且 label 来自源码（名称/类型/简介）',
+          'sourceRoot.root 提供且 pages[].path 全部可解析',
+          '无明文凭据（password 类字段全部留空）',
+          '关键事实带 evidence 溯源（pages 或 businessRules）',
+        ];
+  for (const text of rest) check(text, false, '产物不可解析，无法评估');
+}
+
+mkdirSync(path.dirname(outPath), { recursive: true });
+writeFileSync(outPath, JSON.stringify({ expectations }, null, 2), 'utf-8');
+const passed = expectations.filter((e) => e.passed).length;
+console.log(`${passed}/${expectations.length} 通过 → ${outPath}`);

package/codex-skill/ep-stage/code-list-generate/references/epoint-extraction.md

@@ -0,0 +1,106 @@
+# epoint 系源码提取方法
+
+本文件说明每类 code_list 事实在 epoint 系源码（MiniUI 前端 + Java Action/Service/Entity 后端）里的位置和抠取方法。提取时始终记住：你是给下游测试流程写「事实清单」，每个结论都要能在源码里指出来处。
+
+## 模块定位
+
+- 前端：`src/main/webapp/perpage/<module>/*.html`
+- 后端：`src/main/java/com/epoint/<module>/`，典型分层 `action/`（*Action.java）、`api/`（接口 + entity/）、`impl/`（Service 实现 + DAO）
+
+模块标识 `module` 取 perpage 目录名 / java 包名（通常一致，如 `zwplace`）。
+
+## 页面四角色（pages[].role）
+
+按文件名与页面行为分类：
+
+| role | 文件名特征 | 行为特征 |
+|---|---|---|
+| `list` | `*list.html` | 含 mini-datagrid + 查询区 + 工具栏 |
+| `add` | `*add.html` | 空表单，保存走 `add` 方法 |
+| `edit` | `*edit.html` | 带 guid 加载（pageLoad），保存走 `save` 方法 |
+| `detail` | `*detail.html` | 只读，无保存按钮 |
+
+`pageId` 取文件名去 `.html`（如 `gxhzwplacelist`）；`initAction` 取页面对应 Action 的 restController 名（见下）。
+
+## 按钮（buttons[] / toolbarActions[]）
+
+在 HTML 里找这两类来源：
+
+1. **mini-button**：`<a class="mini-button" ...>按钮文字</a>`，看 `onclick` 调的 JS 函数（`actionName`），再追该函数里 Ajax 调的 Action 方法（`backendMethod`）
+2. **mini-dataexport**：导出组件（`<div id="dataexport" ...>` 或类似），固定归类 `action: 'export'`，`backendMethod` 一般是 `getExportModel`
+
+行操作在 datagrid 列定义里找 renderer（如 `actionRenderer`）生成的链接/图标，常见「修改」「查看」，对应 JS 函数 `openEdit` / `openDetail`。
+
+**action 语义分类判断顺序**：导出组件 → `export`；调删除方法（deleteSelect 等）→ `delete`；打开新增页 → `create`；新增页提交到 `add` 方法 → `create`；编辑页提交到 `save` 方法 → `update`；草稿保存 → `save`（补 customAction）；关闭 → `cancel`；其余业务按钮 → `custom`（必须补 `customAction` + `backendMethod`）。
+
+## 查询字段（queryFields[]）
+
+列表页查询区的表单控件：
+
+- `mini-textbox` → 输入框。`label` 取控件旁的中文标签或控件自身 `label` 属性；`bind` 取 `name`/`bind` 属性里的 `dataBean.xxx`
+- `mini-combobox` → 下拉。额外记 `modelRef`：看 `action`/`url` 属性指向的 Action 方法（如 `getPlacecategoryModel` → ref 取名 `placecategoryModel`），或 `dataOptions` 里的字典 code
+
+## 表单字段（formFields[]）
+
+新增/编辑页表单区控件，同 queryFields 的抠法，另外从控件属性抠 `required: true`（`required="true"`）和 `maxLength`。
+
+edit 页与 add 页字段完全相同时，写 `formFields: ['same_as_pages.add.formFields']` 引用，避免重复维护——下游会解析这个引用。
+
+## 子表（childGrids[]）
+
+表单页内嵌的 mini-datagrid（如窗口信息子表）：
+
+- `id`：grid 的 DOM id（如 `windowGrid`）
+- `columns[]`：列定义的 `field` / 表头中文 `label`；列带编辑器且必填标 `required: true`；下拉列标 `modelRef`
+- `component`：**只写 `input` 或 `listbox`**（文本编辑器列 / 下拉编辑器列），这不是 MiniUI 组件名——写 `mini-textbox` 之类会被下游契约门禁直接拒绝（有实锤）。拿不准就整列省略 component，下游会读 HTML 的 editor.type 自行推导
+- `actions[]`：子表工具条按钮（添加窗口/删除选中 → actionName 取 JS 函数名）
+- `editMode` 可省（下游从 HTML 信号推断）；推断不对时用 `cell_edit` / `row_button_dialog` / `none` 覆盖
+
+## 系统名与模块名（取源纪律）
+
+- **系统名**（`systems[].name`）：最终用户登录系统的正式中文全称。找它的顺序：PRD/需求文档里的业务系统名 → 运行系统登录页/标题 → plan/project_context 的 products[].name。**警惕产品/项目代号**（如「综管」这类内部简称）——它不是系统名，实测中被误取过。只有代号可用时填代号，并在 downstreamRuntimeNeeds 登记待确认。
+- **模块名**（`moduleName`）：需求/PRD 里的模块业务名。不要用单个页面的 `<title>`（那是页面名，进 `pages[].title`）。
+
+## 落盘位置（下游需求名推导契约）
+
+产物必须写到 `<需求名目录>/_docs/code_list.json5`。下游按「code_list.json5 父目录的父目录的 basename」推导需求名——父目录必须是 `_docs`。**`_docs/<需求名>/code_list.json5` 这类布局是错的**（需求名会被算成 `_docs`）。
+
+## 数据模型（dataModels[] 的 sourceKind 判断）
+
+| 情况 | sourceKind |
+|---|---|
+| combobox 数据来自代码项/字典（`dataOptions: "{code:'场所分类'}"` 或 Action 方法读代码项表） | `dictionary_runtime`，记 `dictionaryCode`，标 `optionsKnownAtStaticTime: false` |
+| 选项写死在 HTML/JS 里（如是/否、固定区划列表） | `static_options`，`options[]` 全量列出 |
+| 来自业务库表查询（如按区划查街道） | `db_runtime`，记 `dependency`（级联字段） |
+
+**判断要点**：找到给 combobox 供数的 Action 方法，读它的实现——查代码项表是 dictionary_runtime；return 字面量数组是 static_options；查业务表是 db_runtime。选项值运行态才知道时，绝不把猜的选项写进 `options`。
+
+## 业务规则（businessRules[]）
+
+在 Action 方法里找这些信号：
+
+- **校验/阻断消息**：`throw new ...Exception("...")`、`return "...不可..."`、前端 `alert("...")`。每条消息就是一条规则，`assertionHint` 填消息原文
+- **状态约束**：如删除前判断 `status != DRAFT` → `scope: ['delete']` 规则（这条对下游删除用例断言起决定作用，务必抠全）
+- **唯一性校验**：`checkXxxUnique` 类方法 → `scope: ['create', 'update']`
+- **副作用事实**：如"保存并关闭时版本号+1、归档历史" → `scope: ['update']` 规则
+
+前端 JS 里的校验（如子表行必填 `"第N行窗口名称不能为空！"`）同样是规则，scope 带上子表 id。
+
+## 实体（entities[]）
+
+`api/entity/*.java`：类名 → `name`；类/注解上的表名 → `table`；字段 → `fields[]`（name/类型+长度/中文注释 label）。业务主键（列表页按它查询定位数据、唯一性校验针对它）标 `dataKey: true`。
+
+## requirement 与对照缺口
+
+从 PRD/需求文档提取：`id/name/type/priority/targetEnds/businessRoles[]`（角色配 `label/targetEnd/responsibilities`，evidence 指 PRD 章节）。
+
+然后做**双向对照**：
+
+- `implementedScope[]`：源码里真实存在的功能点（有页面/方法支撑），`implementedBy` 指到具体页面和后端方法
+- `prdMentionedButNotImplemented[]`：PRD 写了但源码找不到对应页面/实现的，`reason` 写明"未在 sourceFiles 中发现对应文件"。只能写静态扫描可证实的缺口，不揣测
+
+## evidence 写法
+
+- 源码：`相对源码根路径#方法或锚点`，如 `src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java#deleteSelect`
+- 需求文档：`文件名#章节号`，如 `场所窗口信息管理及各端统计检索查看_prd.md#2.1 核心用户角色`
+- 内部引用：`sourceFiles.frontend[role=list]` 形式

package/codex-skill/ep-stage/code-list-generate/references/field-contract.md

@@ -0,0 +1,122 @@
+# code_list.json5 逐字段契约
+
+本文档是 `code_list.json5`（schemaVersion: `ep-stage-code-list/v1-draft`）的完整字段说明。每个字段标注：**必填性**、**下游消费点**（下游 CLI 拿它做什么）。标注「下游硬消费」的字段缺失或错误会直接让用例生成缺斤短两；标注「事实记录」的字段主要供人审与溯源。
+
+校验权威：下游硬校验只看 `module` / `moduleName` / `systems[]` / `pages[]` 四项存在性（`extractors/code-list-json5.ts`），其余靠本契约自律。
+
+## 顶层字段
+
+| 字段 | 必填 | 消费点 | 说明 |
+|---|---|---|---|
+| `schemaVersion` | 推荐 | 事实记录 | 固定 `ep-stage-code-list/v1-draft` |
+| `module` | **是** | 下游硬消费 | 模块英文标识（kebab/lower-case），作 moduleId、用例 ID 前缀 |
+| `moduleName` | **是** | 下游硬消费 | 模块中文**业务名**（取需求/PRD 的模块名，如"场所窗口信息管理"），不取单页 title——页面 title 进 `pages[].title` |
+| `description` | 推荐 | 事实记录 | 一句话概括本次出码覆盖范围 |
+| `requirement` | 推荐 | 角色回退来源 | 需求事实：`id/name/type/priority/targetEnds/businessRoles[]`。**`businessRoles[]` 是 PRD 角色事实全量**（含无实现入口的角色，如实记录不删）；下游只在顶层 `roles[]` 缺失时才拿它当凭据角色来源。**`requirement.id` 缺失时用需求目录名兜底**（如 `014-测试需求10-20260622`），并在注释说明兜底来源 |
+| `sourceRoot` | 推荐 | 下游硬消费 | `root`（源码根绝对路径）+ `pathBase` + `sourceFilesAreRelativeTo`。下游用它把 `pages[].path` 解析成真实文件做核验 |
+| `systems` | **是** | 下游硬消费 | 业务系统清单，见下 |
+| `testAccess` | 可选 | 角色来源 | 测试访问数据模板，见下 |
+| `moduleInfo` | 推荐 | 事实记录 | `id/name/packagePath/frontendBasePath/backendBasePath/deriveRule` |
+| `implementedScope` | 推荐 | 事实记录 | 本次实现的功能点清单：`featureId/featureName/implementedBy[]`，`implementedBy` 指向页面与后端方法 |
+| `prdMentionedButNotImplemented` | 推荐 | 事实记录 | PRD 有但未实现的部分：`featureIds/featureName/reason`。只能写静态扫描可证实的缺口 |
+| `sourceFiles` | 推荐 | 事实记录+证据锚 | 出码文件清单：`frontend/actions/services/entities` 四类，页面 `evidence` 引用这里 |
+| `pages` | **是** | 下游硬消费 | 页面事实，见下 |
+| `backend` | 推荐 | 事实记录 | `callChain` + `actions[].methods[]` + `services[].methods[]` |
+| `dataModels` | 可选 | 下游硬消费(有下拉时) | 下拉数据模型，见下 |
+| `entities` | 可选 | 下游硬消费(dataKey) | 实体与表字段，见下 |
+| `businessRules` | 推荐 | 下游硬消费 | 业务规则，见下 |
+| `integrations` | 可选 | 事实记录 | 第三方集成点，含 `currentImplementation`（如 `service_stub`）与 PRD 期望 |
+| `routeHints` | 可选 | 事实记录 | 直达链接推导规则：`contextPathHint` + 各页 `routePath`。**`contextPathHint` 有来源才写**（如真实部署的 context path、loginUrl 反推）；无来源时留空并登记 `downstreamRuntimeNeeds`，不要沿用模板默认值顶包 |
+| `downstreamRuntimeNeeds` | 推荐 | 事实记录 | 运行时才可确认的信息清单，防止把运行时值编造成静态事实 |
+
+## systems[]
+
+| 字段 | 说明 |
+|---|---|
+| `name` | 系统**正式中文全称**（最终用户登录的那个系统）。**须与下游 credentials.json5 的 systemName 严格一致**。取源优先级：PRD/需求文档写明的业务系统名 > 运行系统登录页/标题 > project_context 的 products[].name。**产品/项目代号不是系统名**（实测坑：误取代号「综管」，真实系统名是「集成受理平台」）；只有代号可用时填代号，并在 `downstreamRuntimeNeeds` 登记"系统名待确认" |
+| `version` / `frameVersion` | 平台与框架版本 |
+| `targetEnd` | 目标端（PC-管理端 / H5-移动端） |
+| `defaultLoginUrl` | 登录地址样板。知道就填；下游用它推导业务页直达链接的 contextPath |
+
+## testAccess.systems[].roles[]
+
+登录访问模板骨架。每行：`role`、`username`、`password`、`permissions[]`。**username/password 一律留空**，由下游交互补齐。角色集与顶层 `roles[]` 对齐。
+
+## 顶层 roles[]（凭据角色的事实源）
+
+下游 `listRequiredRoles` 的消费优先级：**顶层 `roles[]` > `requirement.businessRoles[]` > `testAccess.systems[].roles[]`**——命中即停。凭据模板行数与 `requiredRoles` 由命中的那一级决定。
+
+因此：**PRD 角色（businessRoles）≠ 需登录角色时，必须写顶层 `roles[]` 圈定**（如 PRD 有业务管理员/领导/群众三角色，但领导用统计大屏、群众用 H5，本次均未出码——顶层 roles[] 只写业务管理员）。不写顶层 roles[] 而只精简 testAccess 是无效的（实测假修复：凭据模板仍按 businessRoles 全量生成）。
+
+每项字段：`systemName`（须在 systems[].name 中存在）/ `role`（角色中文名）/ `loginMethod` / `permission` / `description` / `menuPath`（均可选，role 必填）。
+
+## pages[]
+
+每页必填：`path`（相对 sourceRoot.root）、`role`、`description`、`buttons[]`、`rowActions[]`。
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `pageId` | 推荐 | 页面标识（文件名去后缀），下游拼 iframe src 关键字 |
+| `role` | **是** | `list` / `add` / `edit` / `detail` / `custom` |
+| `title` | 推荐 | HTML `<title>` 原文 |
+| `path` | **是** | 相对源码根路径，如 `src/main/webapp/perpage/zwplace/gxhzwplacelist.html` |
+| `initAction` | 推荐 | 页面初始化的 restController 名 |
+| `directUrl` | 可留空 | 待测页面直达链接。只有 list 页真正关键；留空时下游交互补齐 |
+| `queryFields[]` | list 页应有 | 查询条件，见下 |
+| `toolbarActions[]` | 推荐 | 工具栏按钮完整事实（label/actionName/opens/backendMethod/elementHints） |
+| `buttons[]` | **是** | 按钮语义摘要，action 枚举见 SKILL.md 分类表 |
+| `rowActions[]` | **是** | 行内操作；没有就空数组 |
+| `dataGrid` | list 页应有 | `id/idField/backendMethod/columns[]`（field/label/renderer/dataOptions） |
+| `formFields[]` | add/edit 页应有 | 表单字段，见下；edit 与 add 相同可写 `['same_as_pages.add.formFields']` |
+| `childGrids[]` | 有子表时必填 | 子表，见下；edit 可用 `same_as_pages.add.childGrids` 引用 |
+| `backendMethods[]` | 推荐 | 该页面对应 Action 的方法名清单 |
+| `evidence[]` | 推荐 | 证据引用，如 `sourceFiles.frontend[role=list]` |
+
+### queryFields[] / formFields[]
+
+| 字段 | 说明 |
+|---|---|
+| `label` | **必填**，中文标签（下游按 label 生成定位表达式） |
+| `bind` | `dataBean.<field>`，下游据此推英文字段名 |
+| `component` | `mini-textbox`（输入框）/ `mini-combobox`（下拉）/ 其他 MiniUI 组件原名 |
+| `modelRef` | 下拉时必填，指向顶层 `dataModels[].ref` |
+| `required` / `maxLength` | 表单字段的校验事实 |
+| `elementHints` | 元素线索（attr/value 对），供下游拼 locator，非最终 locator |
+
+> 已知边界（实测观察）：下游 create 用例对"必填但不是查询条件"的表单字段依赖内置「默认填充」假设，无法从 code_list 落约具体填值。上游能做的是**把 formFields 的 required/component 标全标准**——必填事实越准，下游默认填充的命中面越清楚。
+
+### childGrids[]
+
+`id` / `label` / `actions[]`（label+actionName）/ `columns[]`（field/label/required/modelRef/component）。可选 `editMode: 'cell_edit' | 'row_button_dialog' | 'none'` 覆盖推断。
+
+**columns[].component 枚举硬约束**（实测踩坑）：只能写 `'input'`（文本编辑器列）或 `'listbox'`（下拉编辑器列）——这不是 MiniUI 组件名，是下游契约门禁的合法值（`validation/contract.ts` 会对 childGrids 列 component 强校验，写 `mini-textbox` 之类会被直接拒绝）。也可以**整列省略 component**，下游会读 HTML 的 editor.type 自行推导；前提是该页 HTML 在 sourceRoot 下真实可用。
+
+## dataModels[]
+
+| 字段 | 说明 |
+|---|---|
+| `ref` | 模型标识，与 queryFields/formFields 的 `modelRef` 对应 |
+| `label` | 中文名 |
+| `sourceKind` | `dictionary_runtime`（运行态字典，配 `dictionaryCode` + `optionsKnownAtStaticTime: false`）/ `static_options`（配 `options[]` 全量列出）/ `db_runtime`（库表查询，配 `dependency` 说明级联） |
+| `actionMethods[]` | 提供该模型的 Action 方法（`XxxAction.getXxxModel`） |
+
+## entities[]
+
+`name` / `table` / `description` / `fields[]`（name/type/label）。业务主键字段标 `dataKey: true`——下游用它做测试数据种子（时间戳前缀策略）。
+
+## businessRules[]
+
+| 字段 | 说明 |
+|---|---|
+| `ruleId` | 规则标识，如 `delete.onlyDraftAllowed` |
+| `description` | 规则中文描述 |
+| `scope` | **关键**。作用域数组：`create`/`update`/`delete`/`ui`/子表 id 等。**含 `delete` 的规则会把下游删除用例断言改为「阻断」，下游取阻断语义最明确的一条作为策略来源（装配器优先选 assertionHint 含"不可删除"类文案的规则，兜底取第一条）**——因此只有「记录状态/条件阻断删除」的规则才标 `delete`；「未勾选拦截」「二次确认」等操作前置提示标 `ui`，不要混入 delete scope |
+| `sourceKind` | 通常 `static_scan` |
+| `assertionHint` | 阻断/校验提示**主文案**（如"在用数据不可删除！"），下游直接用作预期断言值。**一条规则只放一个主文案**（下游只消费单值）；同规则的其余文案写进 `description`，不要塞数组 |
+| `evidence[]` | 源码相对路径#方法锚点 |
+
+## 留空与省略约定
+
+- 可留空：`directUrl`、`loginUrl`、`username`、`password`（下游交互补齐）
+- 可省略：无子表则省 `childGrids`；无行操作则 `rowActions: []`；无自定义按钮则不写 action=custom
+- 不可省：`pages[].path/role/description/buttons/rowActions`，顶层四大必填字段

package/codex-skill/ep-stage/code-list-generate/scripts/validate-code-list.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * code_list.json5 自校验脚本（code-list-generate skill 配套）
+ *
+ * 用法：node validate-code-list.mjs <code_list.json5路径>
+ *
+ * 校验分两级：
+ *   错误（exit 1）——下游 CLI 会失败或生成错误用例的问题
+ *   警告（exit 0）——建议补齐但不阻断的问题
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/* ──────── json5 依赖解析：bare specifier → 向上找 node_modules（含 pnpm store）──────── */
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+function findJson5Entry() {
+  let dir = scriptDir;
+  while (true) {
+    const plain = path.join(dir, 'node_modules', 'json5', 'lib', 'index.js');
+    if (existsSync(plain)) return plain;
+    const pnpmStore = path.join(dir, 'node_modules', '.pnpm');
+    if (existsSync(pnpmStore)) {
+      const hit = readdirSync(pnpmStore).find((d) => d.startsWith('json5@'));
+      if (hit) {
+        const p = path.join(pnpmStore, hit, 'node_modules', 'json5', 'lib', 'index.js');
+        if (existsSync(p)) return p;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+let JSON5;
+try {
+  ({ default: JSON5 } = await import('json5'));
+} catch {
+  const entry = findJson5Entry();
+  if (entry) {
+    ({ default: JSON5 } = await import(pathToFileURL(entry).href));
+  } else {
+    console.error('缺少 json5 依赖。请先运行：npm install json5（或在含 json5 的工程内运行本脚本）');
+    process.exit(2);
+  }
+}
+
+const filePath = process.argv[2];
+if (!filePath) {
+  console.error('用法：node validate-code-list.mjs <code_list.json5路径>');
+  process.exit(2);
+}
+
+const absPath = path.resolve(filePath);
+if (!existsSync(absPath)) {
+  console.error(`文件不存在：${absPath}`);
+  process.exit(2);
+}
+
+const errors = [];
+const warnings = [];
+
+/* ──────── 解析 ──────── */
+let data;
+try {
+  const { readFileSync } = await import('node:fs');
+  data = JSON5.parse(readFileSync(absPath, 'utf-8'));
+} catch (e) {
+  console.error(`JSON5 解析失败：${e.message}`);
+  process.exit(1);
+}
+if (!data || typeof data !== 'object' || Array.isArray(data)) {
+  console.error('顶层必须是对象');
+  process.exit(1);
+}
+
+/* ──────── 顶层必填（对齐下游 extractors/code-list-json5.ts 硬校验）──────── */
+for (const key of ['module', 'moduleName']) {
+  if (!data[key]) errors.push(`缺少必填字段：${key}`);
+}
+if (!Array.isArray(data.systems) || data.systems.length === 0) errors.push('缺少必填字段：systems（非空数组）');
+if (!Array.isArray(data.pages) || data.pages.length === 0) errors.push('缺少必填字段：pages（非空数组）');
+
+/* ──────── 源码路径真实性 ──────── */
+const sourceRoot = data.sourceRoot?.root;
+if (!sourceRoot) {
+  warnings.push('未提供 sourceRoot.root，下游无法用源码核验 pages[].path');
+} else if (!existsSync(path.resolve(sourceRoot))) {
+  errors.push(`sourceRoot.root 不存在：${sourceRoot}`);
+}
+
+function checkSourcePath(relPath, where) {
+  if (!sourceRoot || !relPath) return;
+  const p = path.resolve(sourceRoot, relPath);
+  if (!existsSync(p)) errors.push(`${where}：路径在 sourceRoot 下不存在 → ${relPath}`);
+}
+
+/* ──────── 落盘位置契约（下游按「父目录的父目录 basename」推导需求名）──────── */
+if (path.basename(path.dirname(absPath)) !== '_docs') {
+  errors.push(`落盘位置不符契约：code_list.json5 的父目录必须是 _docs（即 <需求名目录>/_docs/code_list.json5），否则下游需求名会被算成「${path.basename(path.dirname(path.dirname(absPath)))}」。当前：${absPath}`);
+}
+
+/* ──────── pages 逐页校验 ──────── */
+const PAGE_ROLES = new Set(['list', 'add', 'edit', 'detail', 'custom']);
+const BUTTON_ACTIONS = new Set(['create', 'delete', 'export', 'custom', 'save', 'update', 'cancel']);
+const CHILDGRID_COL_COMPONENTS = new Set(['input', 'listbox']);
+const rolesSeen = new Set();
+
+for (const [i, page] of (data.pages ?? []).entries()) {
+  const where = `pages[${i}](${page?.pageId ?? page?.path ?? '?'})`;
+  for (const key of ['path', 'role', 'description']) {
+    if (!page?.[key]) errors.push(`${where} 缺少必填字段：${key}`);
+  }
+  if (page?.role && !PAGE_ROLES.has(page.role)) errors.push(`${where} role 非法：${page.role}（应为 ${[...PAGE_ROLES].join('/')}）`);
+  if (page?.role) rolesSeen.add(page.role);
+  if (page?.path) checkSourcePath(page.path, where);
+  if (!Array.isArray(page?.buttons)) errors.push(`${where} 缺少 buttons 数组`);
+  if (!Array.isArray(page?.rowActions)) errors.push(`${where} 缺少 rowActions 数组（无行操作也要给空数组）`);
+
+  for (const btn of page?.buttons ?? []) {
+    if (!btn?.label) errors.push(`${where} 有按钮缺 label`);
+    if (!btn?.action) {
+      errors.push(`${where} 按钮「${btn?.label}」缺 action 分类`);
+    } else if (!BUTTON_ACTIONS.has(btn.action)) {
+      errors.push(`${where} 按钮「${btn.label}」action 非法：${btn.action}（应为 ${[...BUTTON_ACTIONS].join('/')}）`);
+    }
+    if (btn?.action === 'custom' && !btn?.customAction) {
+      warnings.push(`${where} custom 按钮「${btn.label}」建议补 customAction，否则下游 AI 用例缺少标识`);
+    }
+  }
+
+  if (page?.role === 'list') {
+    if (!Array.isArray(page.queryFields) || page.queryFields.length === 0) warnings.push(`${where} 列表页无 queryFields，下游无法生成查询相关用例`);
+    if (!page.directUrl) warnings.push(`${where} directUrl 为空，下游生成用例时会交互询问`);
+  }
+  if ((page?.role === 'add' || page?.role === 'edit') && !page.formFields) {
+    warnings.push(`${where} ${page.role} 页无 formFields，下游无法判断查询字段是否可写`);
+  }
+
+  // 子表列 component 枚举（下游契约门禁强校验 input/listbox；same_as 引用跳过）
+  for (const grid of page?.childGrids ?? []) {
+    if (typeof grid === 'string') continue; // same_as_pages.* 引用
+    for (const col of grid?.columns ?? []) {
+      if (col?.component !== undefined && !CHILDGRID_COL_COMPONENTS.has(col.component)) {
+        errors.push(`${where} 子表 ${grid.id ?? '?'} 列「${col.label ?? col.field}」component 非法：${col.component}（只接受 input/listbox，或省略该键由下游推导）`);
+      }
+    }
+  }
+}
+
+if (!rolesSeen.has('list')) errors.push('pages 中缺少 role=list 的列表页（下游 CRUD 用例的入口）');
+
+/* ──────── 角色（凭据模板行数来源：顶层 roles[] > businessRoles > testAccess）──────── */
+const topRoles = Array.isArray(data.roles) ? data.roles.length : 0;
+const prdRoles = data.requirement?.businessRoles?.length ?? 0;
+const accessRoles = (data.testAccess?.systems ?? []).flatMap((s) => s.roles ?? []).length;
+if (!topRoles && !prdRoles && !accessRoles) {
+  warnings.push('未提供任何角色信息（roles / requirement.businessRoles / testAccess.systems[].roles），下游凭据模板将为空');
+} else if (!topRoles && prdRoles > accessRoles) {
+  warnings.push(`顶层 roles[] 缺失：下游将按 requirement.businessRoles 全量（${prdRoles} 个）生成凭据模板，而 testAccess 只有 ${accessRoles} 个需登录角色。若 PRD 角色含无实现入口者，请写顶层 roles[] 圈定需登录角色`);
+}
+
+/* ──────── 禁区与占位符检查 ──────── */
+function scanValues(obj, trail) {
+  if (!obj || typeof obj !== 'object') return;
+  for (const [k, v] of Object.entries(obj)) {
+    const here = trail ? `${trail}.${k}` : k;
+    if (/password|passwd|secret|token/i.test(k) && typeof v === 'string' && v.trim()) {
+      errors.push(`疑似凭据泄漏：${here} 非空。code_list 禁止写账号密码（应留空由下游交互补齐）`);
+    }
+    // 模板占位符形如 <模块中文名>；真实值一般不含 <...> 包裹的整段中文/占位词
+    if (typeof v === 'string' && /^<[^<>]+>$/.test(v.trim())) {
+      warnings.push(`疑似未替换的模板占位符：${here} = ${v}`);
+    }
+    scanValues(v, here);
+  }
+}
+scanValues(data, '');
+
+/* ──────── 质量建议 ──────── */
+if (!Array.isArray(data.businessRules) || data.businessRules.length === 0) {
+  warnings.push('无 businessRules：若源码存在删除阻断/唯一性校验等规则，缺失会让下游删除断言退化为「删除成功」');
+} else {
+  const hasDeleteRule = data.businessRules.some((r) => Array.isArray(r?.scope) && r.scope.includes('delete'));
+  if (!hasDeleteRule) warnings.push('businessRules 中没有 scope 含 delete 的规则；若删除有状态约束请补上（含 assertionHint）');
+}
+if (!Array.isArray(data.entities) || !data.entities.some((e) => (e.fields ?? []).some((f) => f.dataKey))) {
+  warnings.push('entities 中未标 dataKey 字段，下游将用默认种子值（建议给业务主键标 dataKey: true）');
+}
+
+/* ──────── 输出 ──────── */
+for (const w of warnings) console.warn(`警告：${w}`);
+for (const e of errors) console.error(`错误：${e}`);
+
+if (errors.length) {
+  console.error(`\n校验未通过：${errors.length} 个错误，${warnings.length} 个警告`);
+  process.exit(1);
+}
+console.log(`校验通过（${warnings.length} 个警告）`);