# 测试规范

**版本:** 2026-05-03
**适用范围:** CNC机床数据采集系统 — 前端管理后台 + 后端API

---

## 一、历史问题复盘与根因分析

### 1.1 问题清单（实际发生）

#### 前后端契约断裂（5起）

| # | 问题 | 现象 | 教训 |
|---|------|------|------|
| 1 | API返回 `{value, label}`，前端绑定 `{id, name}` | 车间/机床/工人下拉框全部无选项 | 前后端字段名必须对齐，不能各写各的 |
| 2 | DTO新增 `activeMachineCount` 等字段，Service未填充值 | 汇总卡片（运行机床/切削总时/平均产量）显示空 | DTO加字段 ≠ 数据会自动填上 |
| 3 | 采集状态API返回 `IsRunning`/`LastCollectTime`，前端期望 `status`/`uptimeSeconds` | 采集服务状态不显示 | 前后端命名风格（PascalCase vs camelCase）必须统一 |
| 4 | 车间API返回 `{data:{items:[...]}}` 分页格式 | 前端取不到选项列表 | 返回数据结构（数组 vs 分页对象）前后端必须确认 |
| 5 | 修正弹窗HTML模板缺失 | 弹窗打不开 | 前端组件完整性检查 |

#### 测试验证流于形式（2起）

| # | 问题 | 现象 | 教训 |
|---|------|------|------|
| 6 | Playwright 37项测试全通过，但所有功能都不能用 | 断言只检查"元素存在"，不检查"数据内容" | 必须验证数据值，不能只验证DOM结构 |
| 7 | 没有展开下拉框确认有选项 | 下拉框无数据但测试"通过" | 交互控件必须实际操作验证 |

#### 后端NULL占位符未填充（2起）

| # | 问题 | 现象 | 教训 |
|---|------|------|------|
| 8 | SQL直接写 `NULL AS TotalRunTime, NULL AS TotalCuttingTime` | 表格运行时间/切削时间全为空 | NULL不报错、不崩溃，隐蔽性极强 |
| 9 | `DailySummaryResponse.MachineCount` 硬编码为0 | 运行机床数永远为0 | 禁止用占位值应付编译 |

#### 配置/格式硬编码（3起）

| # | 问题 | 现象 | 教训 |
|---|------|------|------|
| 10 | Element Plus日期格式用 `yyyy-MM-dd`（错误），应为 `YYYY-MM-DD`（dayjs格式） | 日期选择器值无法解析 | 不同库的日期格式不同，必须查阅文档 |
| 11 | 采集服务serviceId为 `collector-service`，代码硬编码 `CncCollector` | 心跳匹配不上，采集状态显示未启动 | 关键配置项不能硬编码，必须与实际值一致 |
| 12 | 产量报表默认日期未设为今天 | 打开页面没有数据 | 页面初始化必须设置合理的默认值 |

#### 开发流程缺陷（3起）

| # | 问题 | 现象 | 教训 |
|---|------|------|------|
| 13 | 编译通过 = "测试通过" | 功能全部不可用 | 编译通过 ≠ 功能正确 |
| 14 | 改完代码不发布到IIS就宣称完成 | 用户看到的是旧版本 | 每次改动必须发布 |
| 15 | Playwright只访问页面不操作控件 | 控件功能全不可用但测试"通过" | 必须模拟真实用户操作 |

### 1.2 四大根因

#### 根因1：前后端接口契约断裂

**为什么反复出现：** 没有统一的接口契约文档。后端改字段名前端不知道，前端加绑定后端没实现。DTO只是C#类型定义，不等于运行时有数据。

**改进措施：**
- 每个API端点必须用PowerShell/脚本实际调用，确认返回的JSON字段名和结构
- 前端绑定字段名时，必须对照API实际返回值，不能凭假设
- 新增DTO字段后，必须追踪到Service层确认有填充逻辑

#### 根因2：测试断言停留在DOM结构层面

**为什么反复出现：** Playwright的 `toBeVisible()` 只检查元素是否渲染，不检查内容。元素渲染了但内容是空的、NULL的、占位符的，测试照样通过。

**改进措施：**
- 断言必须检查具体文本内容（`toHaveText()`、`textContent()`）
- 数值断言必须排除空字符串、`-`、`--`、`undefined`、`null`、`0`（除非业务确认）
- 下拉框必须展开确认有选项，不能只检查select元素存在

#### 根因3：NULL占位符滥用

**为什么反复出现：** 开发时用 `NULL AS 字段名` 占位，编译不报错、API返回200、不崩溃。NULL是"合法的空值"，不会被任何自动检查发现。

**改进措施：**
- 禁止SQL中写 `NULL AS 字段名` 作为占位符
- 如果字段暂时无法计算，应抛出 NotImplementedException 而非返回NULL
- Code Review时重点检查SELECT列表中的NULL

#### 根因4：缺少强制验证门禁

**为什么反复出现：** 开发完成后没有"必须通过"的验证步骤。编译成功就认为完成了，没有实际操作验证。

**改进措施：**
- 建立4层验证流程（编译→API→浏览器→发布），每层必须通过才能进入下一层
- Playwright测试脚本覆盖所有交互控件和数据展示
- 每次改动后立即验证，不累积到"全部改完"

---

## 二、测试原则（6条铁律）

### 铁律1：接口先验证

**为什么：** 后端改了API返回格式，前端不知道就白改。先验证API再写前端，避免返工。

**怎么做：**
- 改了任何API端点，立即用PowerShell脚本调用
- 检查返回的JSON：字段名、字段值、数据结构、非空字段
- 把实际返回值和前端绑定对比，逐字段确认一致

```powershell
# 登录获取token
$loginRes = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/login" -Method Post -ContentType "application/json" -Body '{"username":"admin","password":"admin123"}'
$token = $loginRes.data.token
$headers = @{ Authorization = "Bearer $token" }

# 调用目标API
$result = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/production/daily-summary?date=2026-05-03" -Headers $headers
$result.data | ConvertTo-Json  # 逐字段检查
```

### 铁律2：数据断言必须具体

**为什么：** `toBeVisible()` 只能证明元素渲染了，不能证明数据正确。空值、占位符、错误值都能通过。

**怎么做：**
- 禁止只检查元素存在
- 必须检查元素的文本内容
- 数值必须是非空、非占位符的具体数字

```typescript
// ❌ 错误：只检查元素存在
await expect(page.locator('.card-value')).toBeVisible()

// ✅ 正确：检查具体数值
const value = await page.locator('.card-value').textContent()
expect(value).toBeTruthy()
expect(value).not.toBe('')
expect(value).not.toBe('-')
expect(value).not.toBe('--')
```

### 铁律3：下拉框必须展开验证

**为什么：** 下拉框渲染了不代表有选项。API返回空数组时select元素照样显示，只是展开后没有选项。

**怎么做：**
1. 点击下拉框展开
2. 等待下拉选项出现
3. 断言选项数量 >= 1
4. 选择一个选项
5. 确认输入框显示选中值
6. 点查询，确认筛选生效

```typescript
// ❌ 错误：只检查select元素存在
await expect(page.locator('.el-select')).toBeVisible()

// ✅ 正确：展开→确认有选项→选择→验证
await page.locator('.el-select').click()  // 点击外层wrapper展开
const options = page.locator('.el-select-dropdown__item:visible')
await expect(options.first()).toBeVisible()
const count = await options.count()
expect(count).toBeGreaterThan(0)
await options.first().click()
await page.getByRole('button', { name: '查询' }).click()
```

### 铁律4：表格必须检查数据列

**为什么：** 表格渲染了不代表有数据。后端返回空数组时表格只显示表头，但"表格可见"的断言照样通过。

**怎么做：**
- 检查表格有数据行（`.el-table__row` 数量 > 0）
- 取第一行，逐列检查文本内容不为空

```typescript
const rows = page.locator('.el-table__body-wrapper .el-table__row')
const rowCount = await rows.count()
expect(rowCount).toBeGreaterThan(0)

// 检查第一行的关键列
const firstRow = rows.first()
const cells = firstRow.locator('td .cell')
const dateText = await cells.nth(0).textContent()
expect(dateText).toBeTruthy()
expect(dateText).not.toBe('')
```

### 铁律5：卡片/统计必须检查数值

**为什么：** 卡片渲染了但数值是空、0、undefined、NaN，用户看到的是空白或错误。

**怎么做：**
- 每个卡片取数值部分
- 断言不为空字符串、不为 `-`、不为 `--`、不为 `undefined`、不为 `null`
- 如果业务上允许为0，需要明确注释说明

### 铁律6：改完即验证，不等批量

**为什么：** 改了10处再一起验证，出问题时无法定位是哪一处改坏的。而且累积到后面容易漏验证。

**怎么做：**
- 每改一处 → 编译 → API验证 → 浏览器验证
- 全部通过后再改下一处
- 如果改动互相关联，最多合并2-3处一起验证

---

## 三、验证层级（4层）

### L1 编译验证

**执行时机：** 每次代码改动后
**命令：**
```bash
dotnet build src\CncWebApi\CncWebApi.csproj   # 0错误
cd frontend && npm run build                    # 0错误
```
**通过标准：** 两个命令都返回退出码0
**注意：** 编译通过 ≠ 功能正确，这只是最基本的大门

### L2 API验证

**执行时机：** 改了后端代码后
**方法：** 用PowerShell调用改动过的API端点
**检查项：**
- HTTP状态码200
- 返回JSON的 `code` 字段为0
- 返回 `data` 不为null
- 关键字段值不为空/NULL
- 字段名和前端绑定一致

**PowerShell模板：**
```powershell
# 登录
$loginRes = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/login" -Method Post -ContentType "application/json" -Body '{"username":"admin","password":"admin123"}'
$token = $loginRes.data.token
$headers = @{ Authorization = "Bearer $token" }
$today = Get-Date -Format "yyyy-MM-dd"

# 示例：验证产量汇总
$sum = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/production/daily-summary?date=$today" -Headers $headers
echo "总产量: $($sum.data.totalQuantity)"        # 应有值
echo "运行机床: $($sum.data.activeMachineCount)"  # 应 > 0
echo "切削总时: $($sum.data.totalCuttingTime)"    # 应有值
echo "平均产量: $($sum.data.avgQuantityPerMachine)" # 应有值

# 示例：验证下拉选项
$ws = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/workshop/list" -Headers $headers
echo "车间数量: $($ws.data.items.Count)"          # 应 > 0
```

### L3 浏览器验证

**执行时机：** 改了前端代码后、或需要验证用户交互时
**方法：** Playwright打开页面，实际操作每个交互控件
**检查项：** 见第五节"Playwright E2E测试断言标准"

**运行命令：**
```bash
cd frontend
npx playwright test e2e/smoke-iis.spec.ts --project=chromium
```

### L4 发布验证

**执行时机：** 所有改动完成后、正式交付前
**步骤：**
1. 回收AppPool：`appcmd recycle apppool "haoliang"`
2. 重复L2（API验证）
3. 重复L3（浏览器验证）
4. 确认 `http://192.168.1.202/admin/` 局域网可访问

---

## 四、前后端接口契约验证

### 4.1 字段名对齐检查

每次新增或修改API返回字段时，必须执行以下检查：

| 检查项 | 方法 | 通过标准 |
|--------|------|----------|
| 后端DTO字段名 vs API实际返回JSON | PowerShell调用API，查看返回值 | JSON key名与DTO属性名一致（考虑camelCase序列化） |
| API返回字段名 vs 前端绑定 | 对比Vue模板中的 `prop`/`:key`/`:label`/`:value` | 完全一致或兼容（支持 `??` 回退） |
| 返回数据结构 | 查看JSON嵌套层级 | 前端取值路径正确（`res.data.items` vs `res.data`） |
| 空值处理 | 构造空数据场景 | 前端显示合理的占位符（`-` 或 `暂无数据`），不报错 |

### 4.2 常见陷阱

- **Newtonsoft.Json camelCase序列化**：C#的 `TotalQuantity` → JSON的 `totalQuantity`，前端绑定要对应
- **分页格式**：部分API返回数组 `[{...}]`，部分返回分页对象 `{items:[], total:0}`，前端必须区分
- **枚举值**：后端枚举可能序列化为整数或字符串，前端必须处理两种情况
- **DateTime序列化**：可能为 `"2026-05-03T00:00:00"` 或 `"2026-05-03"`，前端日期解析要兼容

---

## 五、Playwright E2E测试断言标准

### 5.1 交互控件测试矩阵

每个页面的每个交互控件，都必须按此矩阵验证：

| 控件类型 | 验证动作 | 通过标准 | 禁止做法 |
|----------|----------|----------|----------|
| **下拉框** | 1.点击展开 2.等待选项渲染 | 选项数量 ≥ 1 | 只检查select元素可见 |
| **下拉框** | 选择某项 | 输入框文本变为选中项的label | 不验证选择后的显示值 |
| **下拉框** | 选择后点查询 | 表格数据变化（筛选生效） | 不验证筛选是否实际生效 |
| **日期选择器** | 打开选择日期 | 输入框显示 `YYYY-MM-DD` 格式 | 不验证日期格式 |
| **查询按钮** | 点击 | 表格刷新（loading出现或数据变化） | 只检查按钮可见 |
| **重置按钮** | 点击 | 所有筛选恢复默认值 | 不验证筛选是否清空 |
| **分页** | 切换页码 | 表格数据变化，页码高亮正确 | 只检查分页组件可见 |
| **弹窗-打开** | 点击触发按钮 | 弹窗可见，标题正确 | 不验证弹窗标题 |
| **弹窗-表单** | 查看表单字段 | 各字段有合理初始值 | 不检查表单初始值 |
| **弹窗-提交** | 填写并提交 | 返回成功提示，列表刷新 | 不验证提交后的状态 |
| **导出** | 点击导出 | 触发下载或显示提示 | 不验证导出行为 |

### 5.2 数据展示验证矩阵

| 展示元素 | 验证标准 | 非法值（不通过） |
|----------|----------|------------------|
| **汇总卡片** | 每个数值：非空 ∧ ≠ `""` ∧ ≠ `"-"` ∧ ≠ `"--"` ∧ ≠ `"undefined"` ∧ ≠ `"null"` | 空字符串、`-`、`--`、`undefined`、`null` |
| **表格数据列** | 每列至少第一行有实际文本值 | 空单元格、`NULL` |
| **状态标签** | 显示正确的中文文案（正常/离线/缺失/告警等） | 空标签、英文文本 |
| **时间列** | 有值且格式正确（`YYYY-MM-DD` 或 `HH:mm:ss`） | 空值、格式错误 |
| **空状态** | 无数据时显示"暂无数据"或类似提示 | 空白页面、报错 |

### 5.3 断言红黑榜

#### ✅ 正确的断言（数据层面）

```typescript
// 检查文本不为空且非占位符
const text = await locator.textContent()
expect(text).toBeTruthy()
expect(text!.trim()).not.toBe('')
expect(text!.trim()).not.toBe('-')
expect(text!.trim()).not.toBe('--')

// 检查下拉框有选项
const options = page.locator('.el-select-dropdown__item')
await expect(options.first()).toBeVisible()
const count = await options.count()
expect(count).toBeGreaterThan(0)

// 检查表格有数据行
const rows = page.locator('.el-table__body-wrapper .el-table__row')
expect(await rows.count()).toBeGreaterThan(0)

// 检查卡片数值
const cardValue = await page.locator('.card-value').textContent()
expect(parseFloat(cardValue!)).not.toBeNaN()
```

#### ❌ 错误的断言（结构层面，太宽松）

```typescript
// 这些断言无法发现数据为空的问题
await expect(page.locator('.card')).toBeVisible()        // 卡片可见但值可能为空
await expect(page.locator('table')).toBeVisible()        // 表格可见但可能没数据
await expect(page.locator('select')).toBeVisible()       // 下拉框可见但可能没选项
await expect(page.locator('.el-dialog')).toBeVisible()   // 弹窗可见但内容可能错误
```

---

## 六、API验证方法

### 6.1 PowerShell验证脚本模板

```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 登录获取Token
$loginRes = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/login" -Method Post -ContentType "application/json" -Body '{"username":"admin","password":"admin123"}'
$token = $loginRes.data.token
$headers = @{ Authorization = "Bearer $token" }
$today = Get-Date -Format "yyyy-MM-dd"

# === 产量模块 ===
echo "--- 产量汇总 ---"
$sum = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/production/daily-summary?date=$today" -Headers $headers
echo "总产量: $($sum.data.totalQuantity)（应有值）"
echo "运行机床: $($sum.data.activeMachineCount)（应>0）"
echo "切削总时: $($sum.data.totalCuttingTime)（应有值）"
echo "平均产量: $($sum.data.avgQuantityPerMachine)（应有值）"

echo "--- 产量列表（前3条） ---"
$prod = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/production/daily?startDate=$today&endDate=$today&page=1&pageSize=3" -Headers $headers
echo "总数: $($prod.data.total)"
foreach ($item in $prod.data.items) {
    echo "  机床=$($item.machineName) 产量=$($item.totalQuantity) 运行=$($item.totalRunTime)h 切削=$($item.totalCuttingTime)h"
}

# === 下拉选项 ===
echo "--- 车间选项 ---"
$ws = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/workshop/list" -Headers $headers
echo "数量: $($ws.data.items.Count)（应>0）"

echo "--- 机床选项 ---"
$mc = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/machine/list" -Headers $headers
echo "数量: $($mc.data.items.Count)（应>0）"

echo "--- 工人选项 ---"
$wr = Invoke-RestMethod -Uri "http://127.0.0.1/api/admin/worker/list" -Headers $headers
echo "数量: $($wr.data.items.Count)（应>0）"
```

### 6.2 非空字段验证清单

每个API端点返回后，以下字段**必须非空**：

| API端点 | 必须非空字段 |
|----------|-------------|
| `/admin/production/daily-summary` | `totalQuantity`, `activeMachineCount`, `totalCuttingTime`, `avgQuantityPerMachine` |
| `/admin/production/daily` | `items[].machineName`, `items[].totalQuantity`, `items[].date` |
| `/admin/workshop/list` | `items[].value`, `items[].label` |
| `/admin/machine/list` | `items[].value`, `items[].label` |
| `/admin/worker/list` | `items[].value`, `items[].label` |
| `/admin/dashboard/statistics` | 各统计卡片字段 |
| `/admin/collector/status` | `status` |

---

## 七、发布前Checklist（强制全部打勾）

每次交付前必须完成以下所有检查项：

### 编译
- [ ] `dotnet build src\CncWebApi\CncWebApi.csproj` → 0错误
- [ ] `cd frontend && npm run build` → 0错误

### 发布
- [ ] 前端build输出已复制到 `src\CncWebApi\admin\`
- [ ] 回收AppPool：`appcmd recycle apppool "haoliang"`

### API验证
- [ ] 改动过的API端点用PowerShell调用，返回值正确
- [ ] 新增/修改的字段有实际值（非NULL、非空）

### 浏览器验证
- [ ] Playwright冒烟测试通过：`cd frontend && npx playwright test e2e/smoke-iis.spec.ts --project=chromium`
- [ ] 下拉框展开有选项、选择后筛选生效
- [ ] 表格数据列有值
- [ ] 汇总卡片数值正确
- [ ] 弹窗能打开且有内容

### Git
- [ ] `git add` + `git commit -m "中文描述"` + `git push`

---

## 八、反模式清单（禁止做法）

| # | 反模式 | 正确做法 |
|---|--------|----------|
| 1 | 编译通过 = 测试通过 | 编译通过只说明语法正确，必须验证功能 |
| 2 | 只检查 `toBeVisible()` 不检查内容 | 必须检查文本值，排除空/占位符 |
| 3 | SQL写 `NULL AS 字段名` 占位 | 禁止占位，要么实现要么抛异常 |
| 4 | DTO加字段不填充值 | 加字段必须追踪到Service层实现填充 |
| 5 | 改完代码不发布到IIS | 每次改动必须发布后验证 |
| 6 | Playwright不操作控件只看页面 | 必须模拟用户操作：点击、选择、输入 |
| 7 | 累积改动到"全部完成"再验证 | 改完一处立即验证 |
| 8 | 前端凭假设绑定字段名 | 必须对照API实际返回值 |
| 9 | 硬编码配置值（serviceId、端口等） | 从配置文件读取或与实际部署保持一致 |
| 10 | 不检查Element Plus组件库的日期/格式要求 | 查阅文档确认格式（如 dayjs 的 `YYYY-MM-DD`） |