Files
dacli/doc/baseline.md
T

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) — 复刻模板