6.2 KiB
6.2 KiB
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 表单对应:
examples/baseline/<app>/<enCode>.sh- 复刻脚本tests/e2e/baseline/<app>/<enCode>.spec.ts- Playwright 测试
复刻流程 (每张):
# 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_assetvstds_asset_clone) - 时间戳 / 创建人
- 1-2 像素抗锯齿差异
5. 验收工具
5.1 一键回归 74 张
# 跑全部 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 单张验证
# 跑单张 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)
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 — 设计
- plan.md — 6 周路线
- api.md — 完整 API
- ../.claude/skills/dacli-ts/references/baseline/README.md — baseline 列表
- ../.claude/skills/dacli-ts/references/playwright.md — Playwright 指南
- ../.claude/skills/dacli-ts/examples/baseline/all.sh — 一键回归
- ../.claude/skills/dacli-ts/examples/baseline/template.sh — 复刻模板