Files
dacli/doc/baseline.md
T

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 表单对应:

  1. examples/baseline/<app>/<enCode>.sh - 复刻脚本
  2. 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_asset vs tds_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. 反向链接