199 lines
6.2 KiB
Markdown
199 lines
6.2 KiB
Markdown
# 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 测试
|
|
|
|
**复刻流程** (每张):
|
|
|
|
```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) — 复刻模板
|