# baseline.md — 0 差错验证规范 > **位置**: `$ccWorkDir/dacli/doc/baseline.md` > **目标**: 74 张官方示例的 0 差错验证流程 ## 1. 0 差错定义 **0 差错 = API 0 错 + 浏览器 0 视觉差** | 层面 | 含义 | 验证工具 | |------|------|----------| | **API 0 错** | 所有 dacli 命令返回 200/业务成功 | vitest + 集成测试 | | **UI 0 视觉差** | 复刻的表单/菜单浏览器渲染与原版**像素级一致** | Playwright Node.js | **0 差错基线**: **74 张官方示例** - developSystem 21 张 - workSystem 53 张 ## 2. 验证金字塔 ``` ┌──────────────────┐ │ Playwright 0 视觉差 │ ← 浏览器层 │ (E2E 测试) │ ├──────────────────┤ │ dacli API 0 错 │ ← 集成层 │ (vitest + CLI) │ ├──────────────────┤ │ 单元测试 0 错 │ ← 函数层 │ (vitest unit) │ └──────────────────┘ ``` **每一层都必须 0 错**。 ## 3. baseline 复刻流程 每张 baseline 表单对应: 1. `examples/baseline//.sh` - 复刻脚本 2. `tests/e2e/baseline//.spec.ts` - Playwright 测试 **复刻流程** (每张): ```bash # 1. 切到源 app, 登录 dacli app switch --appCode=developSystem dacli app login --appCode=developSystem # 2. 找到目标 id (用 enCode 查) ORIGINAL_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="leaveApply") | .id') # 3. 导出原表单 JSON dacli form export $ORIGINAL_ID --out=/tmp/leaveApply-orig.json # 4. 切到 tds, 登录 dacli app switch --appCode=tds dacli app login --appCode=tds # 5. 导入 (改 enCode 避免冲突) dacli form import /tmp/leaveApply-orig.json --enCode=leaveApply_clone # 6. 拿克隆 id CLONE_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="leaveApply_clone") | .id') # 7. 发布 dacli form release $CLONE_ID # 8. API 层 0 差验证 (字段集对比) dacli form validate $CLONE_ID # 9. 浏览器层 0 视觉差验证 (Playwright) npx playwright test tests/e2e/baseline/developSystem/leaveApply.spec.ts ``` ## 4. 0 差错的精确含义 ### 4.1 API 层 0 错 | 检查项 | 0 错标准 | |--------|----------| | HTTP 状态码 | 200/业务成功 (无 4xx/5xx) | | 响应数据 | 重建后字段集与原版**完全一致** (允许 id/enCode/state 不同) | | 表单状态 | 发布后 state=1 | | 字段集 | 重建 form info 返回所有字段名/类型与原版一致 | | 关联控件 | popupTable/relationForm 配置完整 | | 字典 | 字典 ID 引用完整 | ### 4.2 UI 层 0 视觉差 | 检查项 | 0 错标准 | |--------|----------| | 字段渲染 | 浏览器看到的 input/select/textarea 数量、类型、默认值 0 差 | | 控件类型 | select 渲染成 select, input 渲染成 input (不能反) | | 字典数据 | 下拉框有选项 (不空白) | | 按钮位置 | 保存/取消/审批按钮位置 0 差 | | 列表列 | 列表页列数/列名/列宽 0 差 | | 工作流节点 | 流程图节点数/连线 0 差 | | 像素 | 截图与基准**像素级一致** (允许 1-2 像素抗锯齿) | ### 4.3 允许的差异 (不算错) - id / enCode 必然不同 - 物理表名前缀 (e.g. `tds_asset` vs `tds_asset_clone`) - 时间戳 / 创建人 - 1-2 像素抗锯齿差异 ## 5. 验收工具 ### 5.1 一键回归 74 张 ```bash # 跑全部 74 张 (API + UI) bash examples/baseline/all.sh # 仅 API 层 (快, 跳过 Playwright) SKIP_PLAYWRIGHT=1 bash examples/baseline/all.sh # 仅 API 层 CI 用 bash examples/baseline/all.sh --skip-visual ``` ### 5.2 单张验证 ```bash # 跑单张 baseline bash examples/baseline/developSystem/leaveApply.sh # 仅 Playwright 部分 npx playwright test tests/e2e/baseline/developSystem/leaveApply.spec.ts # 仅 API 部分 SKIP_PLAYWRIGHT=1 bash examples/baseline/developSystem/leaveApply.sh ``` ### 5.3 视觉对比 (pixelmatch) ```typescript import { PNG } from 'pngjs' import pixelmatch from 'pixelmatch' import { readFileSync, writeFileSync } from 'node:fs' const baseline = PNG.sync.read(readFileSync('screenshots/developSystem/leaveApply.png')) const current = PNG.sync.read(await page.screenshot()) const diff = new PNG({ width: baseline.width, height: baseline.height }) const numDiffPixels = pixelmatch( baseline.data, current.data, diff.data, baseline.width, baseline.height, { threshold: 0.1 } // 严格 ) expect(numDiffPixels).toBeLessThan(50) // < 50 像素 = 0 视觉差 ``` ## 6. 常见 bug 与修复 ### 6.1 字段缺失 **症状**: 浏览器缺一个 input **原因**: tables[].fields[] 缺 `autoIncrement/identity/columnName` **修复**: 用 baseline clone 拿完整 schema ### 6.2 控件类型错 **症状**: select 渲染成 input **原因**: __config__.tag 错 (应 `JnpfSelect` 不是 `JnpfInput`) **修复**: 检查 componentMap.ts 对应 ### 6.3 字典空白 **症状**: 下拉框没选项 **原因**: dictionaryTypeId 错或字典数据未导入 **修复**: 同步 baseline 应用的字典 ### 6.4 工作流节点缺 **症状**: 流程图节点缺失 **原因**: templateJson 不全 **修复**: 用 web 端配置完整工作流, 导出后 import ## 7. 何时重跑 | 触发 | 行为 | |------|------| | **JNPF 升级** | `bash examples/baseline/all.sh` 一键跑, 5 分钟看 regression | | **dacli FieldBuilder 改动** | 跑 baseline 验证 schema 兼容 | | **新增 baseline** | 写新 .sh + 新 .spec.ts | | **JNPF 厂商发版** | 必跑, 对比 diff | ## 8. 反向链接 - [architecture.md](architecture.md) — 设计 - [plan.md](plan.md) — 6 周路线 - [api.md](api.md) — 完整 API - [../.claude/skills/dacli-ts/references/baseline/README.md](../.claude/skills/dacli-ts/references/baseline/README.md) — baseline 列表 - [../.claude/skills/dacli-ts/references/playwright.md](../.claude/skills/dacli-ts/references/playwright.md) — Playwright 指南 - [../.claude/skills/dacli-ts/examples/baseline/all.sh](../.claude/skills/dacli-ts/examples/baseline/all.sh) — 一键回归 - [../.claude/skills/dacli-ts/examples/baseline/template.sh](../.claude/skills/dacli-ts/examples/baseline/template.sh) — 复刻模板