@epoint-testtech/ep-stage-skill 0.0.4-alpha.1 → 0.0.5

package/codex-skill/ep-stage/glue-run-test/scripts/generate-crud-spec.mjs

@@ -1,149 +1,149 @@
-#!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const skillRoot = path.resolve(__dirname, '..');
-const packageRoot = path.resolve(skillRoot, '../..');
-const repoRoot = path.resolve(packageRoot, '../..');
-
-function help() {
-  console.log(`Usage:
-  node scripts/generate-crud-spec.mjs \\
-    --module-id <module-id> \\
-    --docs <docs-dir> \\
-    --code-list <code-list-md> \\
-    --webapp <html-dir> \\
-    --java-actions <java-action-dir> \\
-    --hints <module-hints-json> \\
-    --contract-out <package-output-json> \\
-    --spec-out <glue-project-spec-ts> \\
-    --menu <menu-path>
-
-Notes:
-  - Relative upstream paths are resolved from the repository root.
-  - The contract path is passed to @epoint-testtech/ep-stage-skill relative to its package root.
-  - The script fails when unresolvedSlots is non-empty.
-`);
-}
-
-function parseArgs(argv) {
-  const args = {};
-  for (let index = 0; index < argv.length; index += 2) {
-    const key = argv[index];
-    const value = argv[index + 1];
-    if (key === '--help' || key === '-h') {
-      help();
-      process.exit(0);
-    }
-    if (!key?.startsWith('--') || !value) {
-      throw new Error(`Invalid argument near ${key ?? '<empty>'}`);
-    }
-    args[key.slice(2)] = value;
-  }
-  return args;
-}
-
-function resolveFromRepo(value) {
-  return path.isAbsolute(value) ? value : path.resolve(repoRoot, value);
-}
-
-function requirePath(label, value) {
-  if (!value) throw new Error(`Missing --${label}`);
-  const resolved = resolveFromRepo(value);
-  if (!existsSync(resolved)) throw new Error(`Path for --${label} does not exist: ${resolved}`);
-  return resolved;
-}
-
-function run(commandArgs) {
-  const result = spawnSync('pnpm', commandArgs, {
-    cwd: repoRoot,
-    stdio: 'inherit',
-    shell: false
-  });
-  if (result.status !== 0) {
-    process.exit(result.status ?? 1);
-  }
-}
-
-const args = parseArgs(process.argv.slice(2));
-const moduleId = args['module-id'];
-if (!moduleId) throw new Error('Missing --module-id');
-const docs = requirePath('docs', args.docs);
-const codeList = requirePath('code-list', args['code-list']);
-const webapp = requirePath('webapp', args.webapp);
-const javaActions = requirePath('java-actions', args['java-actions']);
-const hints = requirePath('hints', args.hints);
-const contractOut = args['contract-out'] ?? `packages/ep-stage-skill/output/${moduleId}.crud.contract.json`;
-const specOut = args['spec-out'];
-const menu = args.menu;
-if (!specOut) throw new Error('Missing --spec-out');
-if (!menu) throw new Error('Missing --menu');
-
-const contractAbs = resolveFromRepo(contractOut);
-const contractForPackage = path.relative(packageRoot, contractAbs);
-mkdirSync(path.dirname(contractAbs), { recursive: true });
-
-run([
-  '--filter',
-  '@epoint-testtech/ep-stage-skill',
-  'generate:crud-contract',
-  '--',
-  '--module-id',
-  moduleId,
-  '--docs',
-  docs,
-  '--code-list',
-  codeList,
-  '--webapp',
-  webapp,
-  '--java-actions',
-  javaActions,
-  '--hints',
-  hints,
-  '--out',
-  contractForPackage
-]);
-
-const contract = JSON.parse(readFileSync(contractAbs, 'utf8'));
-if (contract.unresolvedSlots?.length) {
-  console.error(JSON.stringify({
-    error: 'Contract has unresolvedSlots; update ModuleHints before generating a final spec.',
-    unresolvedSlots: contract.unresolvedSlots.map(({ slotId, reason, suggestedFormat }) => ({
-      slotId,
-      reason,
-      suggestedFormat
-    }))
-  }, null, 2));
-  process.exit(2);
-}
-
-const specAbs = resolveFromRepo(specOut);
-mkdirSync(path.dirname(specAbs), { recursive: true });
-
-run([
-  '--filter',
-  '@epoint-testtech/ep-stage-skill',
-  'generate:playwright-tests',
-  '--',
-  '--contract',
-  contractForPackage,
-  '--out',
-  specAbs,
-  '--menu',
-  menu
-]);
-
-console.log(JSON.stringify({
-  module: contract.module,
-  searchConditions: contract.searchConditions?.map(({ field, label, component, value }) => ({
-    field,
-    label,
-    component,
-    value
-  })),
-  contract: contractAbs,
-  spec: specAbs
-}, null, 2));
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const packageRoot = path.resolve(skillRoot, '../..');
+const repoRoot = path.resolve(packageRoot, '../..');
+
+function help() {
+  console.log(`Usage:
+  node scripts/generate-crud-spec.mjs \\
+    --module-id <module-id> \\
+    --docs <docs-dir> \\
+    --code-list <code-list-md> \\
+    --webapp <html-dir> \\
+    --java-actions <java-action-dir> \\
+    --hints <module-hints-json> \\
+    --contract-out <package-output-json> \\
+    --spec-out <glue-project-spec-ts> \\
+    --menu <menu-path>
+
+Notes:
+  - Relative upstream paths are resolved from the repository root.
+  - The contract path is passed to @epoint-testtech/ep-stage-skill relative to its package root.
+  - The script fails when unresolvedSlots is non-empty.
+`);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    if (key === '--help' || key === '-h') {
+      help();
+      process.exit(0);
+    }
+    if (!key?.startsWith('--') || !value) {
+      throw new Error(`Invalid argument near ${key ?? '<empty>'}`);
+    }
+    args[key.slice(2)] = value;
+  }
+  return args;
+}
+
+function resolveFromRepo(value) {
+  return path.isAbsolute(value) ? value : path.resolve(repoRoot, value);
+}
+
+function requirePath(label, value) {
+  if (!value) throw new Error(`Missing --${label}`);
+  const resolved = resolveFromRepo(value);
+  if (!existsSync(resolved)) throw new Error(`Path for --${label} does not exist: ${resolved}`);
+  return resolved;
+}
+
+function run(commandArgs) {
+  const result = spawnSync('pnpm', commandArgs, {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    shell: false
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const moduleId = args['module-id'];
+if (!moduleId) throw new Error('Missing --module-id');
+const docs = requirePath('docs', args.docs);
+const codeList = requirePath('code-list', args['code-list']);
+const webapp = requirePath('webapp', args.webapp);
+const javaActions = requirePath('java-actions', args['java-actions']);
+const hints = requirePath('hints', args.hints);
+const contractOut = args['contract-out'] ?? `packages/ep-stage-skill/output/${moduleId}.crud.contract.json`;
+const specOut = args['spec-out'];
+const menu = args.menu;
+if (!specOut) throw new Error('Missing --spec-out');
+if (!menu) throw new Error('Missing --menu');
+
+const contractAbs = resolveFromRepo(contractOut);
+const contractForPackage = path.relative(packageRoot, contractAbs);
+mkdirSync(path.dirname(contractAbs), { recursive: true });
+
+run([
+  '--filter',
+  '@epoint-testtech/ep-stage-skill',
+  'generate:crud-contract',
+  '--',
+  '--module-id',
+  moduleId,
+  '--docs',
+  docs,
+  '--code-list',
+  codeList,
+  '--webapp',
+  webapp,
+  '--java-actions',
+  javaActions,
+  '--hints',
+  hints,
+  '--out',
+  contractForPackage
+]);
+
+const contract = JSON.parse(readFileSync(contractAbs, 'utf8'));
+if (contract.unresolvedSlots?.length) {
+  console.error(JSON.stringify({
+    error: 'Contract has unresolvedSlots; update ModuleHints before generating a final spec.',
+    unresolvedSlots: contract.unresolvedSlots.map(({ slotId, reason, suggestedFormat }) => ({
+      slotId,
+      reason,
+      suggestedFormat
+    }))
+  }, null, 2));
+  process.exit(2);
+}
+
+const specAbs = resolveFromRepo(specOut);
+mkdirSync(path.dirname(specAbs), { recursive: true });
+
+run([
+  '--filter',
+  '@epoint-testtech/ep-stage-skill',
+  'generate:playwright-tests',
+  '--',
+  '--contract',
+  contractForPackage,
+  '--out',
+  specAbs,
+  '--menu',
+  menu
+]);
+
+console.log(JSON.stringify({
+  module: contract.module,
+  searchConditions: contract.searchConditions?.map(({ field, label, component, value }) => ({
+    field,
+    label,
+    component,
+    value
+  })),
+  contract: contractAbs,
+  spec: specAbs
+}, null, 2));

package/codex-skill/ep-stage/page-element-scan/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: page-element-scan
+description: 基于 Playwright 实时渲染识别页面中的可操作元素（按钮、表单字段、列表行操作、标签页、链接等），输出带定位符和可见/可用状态的元素清单（JSON + Markdown）。可与页面源 html 交叉比对，标注「静态有渲染无」「渲染有静态无」的差异证据。当用户想盘点页面元素、摸清页面有哪些按钮和字段、生成页面元素清单、为自动化测试/用例编写摸清页面结构时使用，即使用户只给了一个 URL 也应主动使用本技能。
+---
+
+# page-element-scan — 页面可操作元素识别
+
+## 用途
+
+对指定页面做一次「可操作元素盘点」：用 Playwright 真实渲染页面，提取所有用户可操作的元素，并为每个元素给出 Playwright 可用的定位符。
+
+与静态读 html 源码的区别：运行时渲染才能回答「这个元素用户到底看不看得到、点不点得动」。 MiniUI 等框架会把声明式标记渲染成复杂 DOM，权限控制会让部分元素渲染时隐藏，脚本会动态创建新元素——这些只有渲染结果能告诉我们。如果用户同时提供了页面源 html，本技能会做双证据比对：
+
+- `both`：源码声明且渲染确认 —— 最可信
+- `runtime-only`：渲染时才出现（脚本动态创建）—— 静态分析会漏掉
+- `source-only`：源码声明但渲染时不可见（权限隐藏/逻辑移除）—— 对最终用户不可操作
+
+## 输入收集
+
+开始扫描前，向用户确认以下信息（能从上下文推断就不要再问）：
+
+1. **目标 URL**（必填）。本地 html 文件用 `file:///` 绝对路径。
+2. **登录方式**（如需要）：账号密码，或已有的 Playwright storage-state 文件。若当前目录是胶水/e2e 项目且有 `.env`（含 `LOGIN_SYSTEM_URL` / `LOGIN_USERNAME` / `LOGIN_PASSWORD`），直接读取复用，不要问用户要密码。
+3. **源 html 路径**（可选）：有就给 `--source`，触发双证据比对。
+4. **输出位置**：默认 `./page-elements/` 下，`<页面名>.json` + `<页面名>.md`。
+
+## 执行步骤
+
+1. 确定一个安装了 playwright 的工作目录作为 `--project-dir`：当前项目根、或 `e2e-test/` 下任一胶水项目（它们的 node_modules 里有 playwright）。脚本用 `createRequire` 从该目录解析依赖。
+
+2. 运行扫描脚本（路径相对于本技能目录）：
+
+```bash
+node <技能目录>/scripts/scan-page.mjs \
+  --url "<目标URL>" \
+  --out "<输出>.json" --md "<输出>.md" \
+  --project-dir "<含playwright的目录>"
+```
+
+按需追加：
+- 登录：`--login-url <登录页> --login-user <账号> --login-pass <密码>`（启发式填用户名密码框）；启发式失败时用 `--login-user-selector` / `--login-pass-selector` / `--login-submit-selector` 显式指定。
+- 登录态复用：`--storage-state <state.json>`。
+- 双证据：`--source <页面源html>`。
+- 渲染不充分时加大 `--wait 3000`；调试时 `--headed` 看浏览器实际行为。
+
+3. 脚本默认扫描主 frame 和所有子 frame（epoint 页面常嵌 iframe），每个元素的 `frame` 字段标注来源；跨域 frame 会自动跳过。
+
+## 结果呈现
+
+扫描完成后读 JSON，向用户汇报：
+
+1. **概览**：元素总数、可操作数、按类型分布（button / field / grid / tab / link）。
+2. **值得注意的发现**（这是盘点的价值所在，不要只报数字）：
+   - 渲染时隐藏或禁用的元素（可能受权限/状态控制）
+   - `runtime-only` 元素（动态创建，静态分析发现不了）
+   - `source-only` 元素（声明了但用户看不到）
+   - grid 的行操作和列信息
+3. 文件路径，提示 JSON 里的 `locator` 可直接用于 Playwright 脚本。
+
+## 输出格式
+
+JSON 结构：
+
+```json
+{
+  "url": "...", "title": "...", "scannedAt": "...",
+  "summary": { "total": 42, "byType": {"button": 8, "field": 12}, "actionable": 35,
+               "hiddenAtRuntime": 2, "runtimeOnly": 3, "sourceOnly": 1 },
+  "dialogs": [{"trigger": "openChild", "title": "新增窗口", "pagePath": "xxx.html"}],
+  "elements": [
+    { "type": "button", "label": "新增", "locator": "xpath=//a[contains(@class,'mini-button')]...",
+      "visible": true, "enabled": true, "evidence": "both", "frame": "main" }
+  ]
+}
+```
+
+`dialogs` 仅 `--source` 模式产出（从 script 中解析 openTopDialog 调用）。
+
+## 边界与须知
+
+- 「可操作」判定 = 可见（非 display:none、有尺寸）且可用（非 disabled）。默认输出过滤不可见元素，`--include-hidden` 可保留。
+- 脚本不做交互（不点按钮、不开弹窗）。弹窗/二级页面内的元素需把对应 URL 再扫一遍，或先用 `--headed` 观察交互路径。
+- 登录启发式覆盖常见登录页；复杂登录（验证码、SSO 跳转）失败时，让用户手动登录后用 `--storage-state` 重试。
+- 元素去重键是 `type|label|locator`，同 label 不同类型控件不会合并。
+- **已知覆盖范围**（已验证于真实 epoint MiniUI 页面）：
+  - 按钮：MiniUI `a.mini-button`、epoint `a.cond-srh-btn`（搜索按钮）、原生 `button`、`[role=button]`
+  - 字段：`div[label]` 包装的 MiniUI 控件（textbox/combobox/buttonedit/datepicker/spinner）、原生 `input/select/textarea`
+  - Grid：`mini-datagrid` 的 `.mini-grid-headertxt` 列名 + `[data-tooltip]` 行操作图标
+  - 标签页：`.mini-tabs li`
+  - 噪音过滤：无 label 的分页跳页输入框（`pagination-number`）等无业务意义输入不输出
+- **双证据实现说明**：源码侧使用 `DOMParser` 解析 HTML（不执行脚本），得到纯声明态 DOM；运行时侧用 Playwright 渲染；两者按 type+label 比对后标注 `both / runtime-only / source-only`。`setContent` 方案会执行内联脚本导致 evidence 误标，已废弃。

package/codex-skill/ep-stage/page-element-scan/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill_name": "page-element-scan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "我手里有一个页面的 html 文件：F:\\001-Proj\\ep-stage\\.claude\\skills\\page-element-scan\\evals\\fixtures\\sample-list-page.html。想搞清楚这个页面上有哪些可以操作的元素（按钮、输入框、列表操作之类的），最好能给我可以直接用在 Playwright 脚本里的定位方式。另外注意区分一下哪些元素是页面上实际能看到的、哪些是被隐藏或禁用的。结果输出成文件给我（放 F:\\001-Proj\\ep-stage\\.claude\\skills\\page-element-scan-workspace\\ 下，json 和 markdown 各一份）。",
+      "expected_output": "产出 JSON + Markdown 元素清单：识别出查询/新增/导出/审核按钮（审核标记为禁用），批量删除因 display:none 被过滤或标记隐藏；4 个查询字段带控件类型和 label 定位符；datagrid1 含列信息和行操作（查看/编辑）；标签页和链接；弹窗触发器 新增窗口→gxhzwplaceadd.html。",
+      "files": ["F:\\001-Proj\\ep-stage\\.claude\\skills\\page-element-scan\\evals\\fixtures\\sample-list-page.html"],
+      "assertions": [
+        "产出 JSON 和 Markdown 两份元素清单文件",
+        "识别出按钮：查询、新增、导出，且标记为可见可用",
+        "「审核」按钮被识别且标记为禁用/不可操作",
+        "「批量删除」（display:none）不出现在可操作清单中，或被明确标记为隐藏",
+        "识别出 4 个查询字段：场所名称、场所分类、状态、服务时间",
+        "识别出数据列表及其行操作：查看、编辑",
+        "识别出标签页：待办场所、已办场所",
+        "元素带有非空的 Playwright 定位符",
+        "识别出弹窗触发器：新增窗口 → gxhzwplaceadd.html"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "帮我盘点一下我们测试环境「场所窗口信息管理」列表页上有哪些可操作元素。登录页是 http://192.168.203.46:8100/epoint-web/frame/pages/login/login，业务管理员账号 yz，密码 Ep@2024Better，登录后列表页地址是 http://192.168.203.46:8100/epoint-web/perpage/zwplace/gxhzwplacelist.html。我想知道查询区有哪些筛选项、工具栏有哪些按钮、列表里每行能做什么操作，输出的定位符要能直接拿去写 Playwright 用例。结果存成 json 和 markdown 文件。",
+      "expected_output": "产出 JSON + Markdown：工具栏按钮（新增场所信息管理、删除选定、导出、同步窗口管理系统）、查询区字段（场所名称、场所分类、状态）、列表行操作（修改、查看）；元素带基于运行时渲染 DOM 的可用 locator；登录成功完成。",
+      "files": [],
+      "assertions": [
+        "产出 JSON 和 Markdown 两份元素清单文件",
+        "登录成功并扫描到真实列表页（元素总数 ≥ 8，非登录页残留）",
+        "识别出工具栏按钮：新增场所信息管理、删除选定、导出、同步窗口管理系统",
+        "识别出查询区字段：场所名称、场所分类、状态",
+        "识别出列表行操作：修改、查看",
+        "元素带有非空的 Playwright 定位符",
+        "定位符基于运行时渲染 DOM（含 mini- 等渲染后类名或等价结构），而非静态声明式标记"
+      ]
+    }
+  ]
+}

package/codex-skill/ep-stage/page-element-scan/evals/fixtures/sample-list-page.html

@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>场所窗口信息管理（评估用模拟页）</title>
+<style>
+  .hidden-btn { display: none; }
+  .mini-disabled { color: #999; cursor: not-allowed; }
+</style>
+</head>
+<body>
+
+<!-- 标签页 -->
+<ul class="mini-tabs">
+  <li class="mini-tabs-active">待办场所</li>
+  <li>已办场所</li>
+</ul>
+
+<!-- 查询条件区 -->
+<div class="fui-condition">
+  <div label="场所名称" role="control">
+    <input class="mini-textbox mini-textbox-input" bind="query.name" maxLength="50" />
+  </div>
+  <div label="场所分类" role="control">
+    <input class="mini-combobox" bind="query.category" />
+  </div>
+  <div label="状态" role="control">
+    <select class="mini-combobox" bind="query.status">
+      <option>请选择</option><option>草稿</option><option>在用</option><option>停用</option>
+    </select>
+  </div>
+  <div label="服务时间" role="control">
+    <input class="mini-datepicker" bind="query.serviceDate" />
+  </div>
+</div>
+
+<!-- 工具栏按钮 -->
+<div class="mini-toolbar">
+  <a class="mini-button" id="btnQuery" onclick="doQuery()">查询</a>
+  <a class="mini-button" id="btnAdd" onclick="openChild()">新增</a>
+  <a class="mini-button" id="btnExport" onclick="doExport()">导出</a>
+  <a class="mini-button hidden-btn" id="btnBatchDelete" onclick="doBatchDelete()">批量删除</a>
+  <a class="mini-button mini-disabled" id="btnAudit" aria-disabled="true">审核</a>
+</div>
+
+<!-- 数据列表 -->
+<div id="datagrid1" class="mini-datagrid" allowCellEdit="true">
+  <div property="columns">
+    <div type="indexcolumn">序号</div>
+    <div field="name" class="mini-grid-headerText">场所名称</div>
+    <div field="category" class="mini-grid-headerText">场所分类</div>
+    <div field="status" class="mini-grid-headerText">状态</div>
+    <div type="actioncolumn" class="mini-grid-headerText">操作
+      <i type="action" data-tooltip="查看" onclick="viewRow()"></i>
+      <i type="action" data-tooltip="编辑" onclick="editRow()"></i>
+    </div>
+  </div>
+</div>
+<div class="mini-grid-pager">共 128 条</div>
+
+<!-- 普通链接 -->
+<a href="/help/manual.html">查看操作手册</a>
+
+<!-- 弹窗触发器（供源代码侧提取） -->
+<script>
+function openChild() { epoint.openTopDialog('新增窗口', 'gxhzwplaceadd.html'); }
+function doQuery() {}
+function doExport() {}
+function doBatchDelete() {}
+function viewRow() {}
+function editRow() {}
+
+// 运行时动态创建的按钮：静态分析看不到它的渲染结果
+document.addEventListener('DOMContentLoaded', function () {
+  var bar = document.querySelector('.mini-toolbar');
+  var btn = document.createElement('a');
+  btn.className = 'mini-button';
+  btn.id = 'btnDynamicHelp';
+  btn.textContent = '动态帮助';
+  bar.appendChild(btn);
+});
+</script>
+
+</body>
+</html>

package/codex-skill/ep-stage/page-element-scan/references/pagination-controls.md

@@ -0,0 +1,153 @@
+# MiniUI 分页控件识别规则
+
+本文件定义 `scan-page.mjs` / `extract-page-elements.mjs` 对 MiniUI 分页控件的采集规范。
+
+## 分页控件结构
+
+```
+.mini-grid-pager                    ← 分页容器（采集入口）
+└── .mini-pagination                ← 分页主体
+    ├── .pagination-pagerinfo       ← 总条数文本（如"共536条"）
+    ├── .pagination-buttons         ← 按钮组
+    │   ├── a.pagination-button[action=prev]    ← 上一页
+    │   ├── a.pagination-button[action=next]    ← 下一页
+    │   ├── a.pagination-button.pagination-current  ← 当前页（数字按钮）
+    │   ├── a.pagination-button               ← 其他页码数字按钮
+    │   └── a.pagination-button-ellipsis[action=none] ← 省略号
+    ├── span.mini-buttonedit（页面尺寸下拉）
+    │   └── input[type=hidden]         ← 实际值（选中项的 value）
+    └── .pagination-pagerchange      ← 跳转区
+        └── input.pagination-number   ← 页码输入框
+```
+
+## 采集条件
+
+同时满足以下条件时才采集分页控件：
+1. 源码静态包含 `.mini-grid-pager` 或运行时 DOM 存在 `.mini-grid-pager`
+2. 页面类型为列表页（有 mini-datagrid），非详情/编辑页
+3. 分页控件数量 ≤ 2（列表页 1 个，子表最多 1 个；超过则可能是误判）
+
+## 采集规则
+
+### 1. 分页容器
+- **type**: `pagination`
+- **label**: 父级 grid 的 id（如 `datagrid`）或 `grid`
+- **locator**: `#${gridId} .mini-grid-pager` 或 `.mini-grid-pager`
+
+### 2. 上一页按钮
+- **运行时选择器**: `a[action=prev]`（在 `.pagination-buttons` 内）
+- **locator 规则**:
+  - 有 gridId：`#${gridId} .pagination-buttons a[action=prev]`
+  - 无 gridId：`.pagination-buttons a[action=prev]`
+- **enabled 判定**: `!a.classList.contains('disabled')`
+
+### 3. 下一页按钮
+- **运行时选择器**: `a[action=next]`（在 `.pagination-buttons` 内）
+- **locator 规则**: 同上一页，`action=next`
+
+### 4. 首页按钮
+- 首页在"上一页"按钮存在 `.disabled` 类时可用
+- 无独立元素，通过"上一页"按钮的 disabled 状态判断
+
+### 5. 末页按钮
+- 末页在"下一页"按钮存在 `.disabled` 类时可用
+- 无独立元素，通过"下一页"按钮的 disabled 状态判断
+
+### 6. 当前页码
+- **运行时选择器**: `.pagination-current`
+- **locator**: `#${gridId} .pagination-current`
+- **label**: 页码数字文本（如 "1"、"2"）
+- **可见性**: 始终可见
+
+### 7. 其他页码数字按钮
+- **运行时选择器**: `.pagination-buttons a.pagination-button:not([action])`
+- **locator**: `#${gridId} .pagination-buttons a.pagination-button`
+- **注意**: 省略号 `a.pagination-button-ellipsis` 除外
+  ```js
+  selector += ':not(.pagination-button-ellipsis)';
+  ```
+
+### 8. 省略号按钮
+- **运行时选择器**: `a.pagination-button-ellipsis`
+- **locator**: `#${gridId} .pagination-button-ellipsis`
+- **特征**: `action=none`，用于跳过中间页码
+
+### 9. 页面尺寸下拉（可选用，通常不操作）
+- **运行时选择器**: `.mini-pagination > span.mini-buttonedit`
+- **实际值**: `span.mini-buttonedit input[type=hidden]`
+- **locator**: `#${gridId} .mini-pagination > span.mini-buttonedit`
+
+### 10. 页码跳转输入框
+- **运行时选择器**: `input.pagination-number`
+- **locator**: `#${gridId} .pagination-pagerchange input.pagination-number`
+- **特征**: `type=text`，`class=pagination-number`
+
+### 11. 总条数文本
+- **运行时选择器**: `.pagination-pagerinfo`
+- **locator**: `#${gridId} .pagination-pagerinfo`
+- **label**: 文本内容（如 "共536条"）
+
+## 数据结构输出示例
+
+```json
+{
+  "type": "pagination",
+  "label": "datagrid",
+  "locator": "#datagrid .mini-grid-pager",
+  "visible": true,
+  "enabled": true,
+  "controls": {
+    "totalInfo": {
+      "label": "共536条",
+      "locator": "#datagrid .pagination-pagerinfo"
+    },
+    "prev": {
+      "label": "上一页",
+      "locator": "#datagrid .pagination-buttons a[action=prev]",
+      "enabled": false
+    },
+    "next": {
+      "label": "下一页",
+      "locator": "#datagrid .pagination-buttons a[action=next]",
+      "enabled": true
+    },
+    "currentPage": {
+      "label": "1",
+      "locator": "#datagrid .pagination-current"
+    },
+    "pageNumbers": [
+      { "label": "1", "locator": "#datagrid .pagination-buttons a.pagination-button:nth-child(2)" },
+      { "label": "2", "locator": "#datagrid .pagination-buttons a.pagination-button:nth-child(3)" }
+    ],
+    "pageSize": {
+      "label": "条/页",
+      "locator": "#datagrid .mini-pagination > span.mini-buttonedit",
+      "valueLocator": "#datagrid .mini-pagination > span.mini-buttonedit input[type=hidden]"
+    },
+    "pageJump": {
+      "label": "跳至页",
+      "locator": "#datagrid .pagination-pagerchange input.pagination-number"
+    }
+  }
+}
+```
+
+## 实现检查清单（scan-page.mjs）
+
+- [ ] 入口：`document.querySelectorAll('.mini-grid-pager')`
+- [ ] 每个 pager 按 `gridId`（父级 `.mini-datagrid` 的 id）区分
+- [ ] 子表 grid 的分页：父元素是 `#windowGrid` 等子表 id
+- [ ] 页码按钮过滤：`a.pagination-button:not(.pagination-button-ellipsis)`
+- [ ] enabled 状态：`!el.classList.contains('disabled')`
+- [ ] 总条数从 `.pagination-pagerinfo` 文本提取
+- [ ] 页面尺寸值从 `span.mini-buttonedit input[type=hidden]` 获取
+- [ ] 采集结果写入 `elements[]`，`type='pagination'`
+
+## 已知干扰项
+
+| 干扰 | 排除规则 |
+|------|---------|
+| 子表内重复的分页结构 | 以所属 grid id 区分，label 加 grid 前缀 |
+| `.pagination-number` 被 `div[label]` 错误包装 | 在 `fieldLabel()` 中跳过，单独在分页采集逻辑中处理 |
+| 省略号按钮 | `a.pagination-button-ellipsis` 单独识别，不归入页码数字 |
+| 分页不可用时（无数据/只有一页）| `.disabled` 类标记，enabled=false |