# 前端版本冲突刷新与终止 preview（发布门禁 B4）测试报告

## 一、 测试背景 (Background)

发布门禁要求人工抽检：版本冲突后刷新再确认、终止 preview 可用。抽检中发现 HTTP 信封将领域码嵌套进 `error` JSON 字符串，前端若只读信封 `VERSION_CONFLICT` 会错过 `PLAN_FROZEN` / `ERR_CONCURRENT_SWITCH` 恢复路径。

## 二、 测试目标 (Test Objectives)

- 过期 `expected_selection_version` → 409 + 业务码 `ERR_CONCURRENT_SWITCH` → 恢复 `retry_after_switch`
- 激活后改规划 → 409 + `PLAN_FROZEN` → `refresh_and_freeze`
- `GET …/termination-preview` 返回 `can_terminate` 等字段
- 单元：信封嵌套解包；设置页冲突后 reload settings

## 三、 测试方案与环境 (Test Plan & Environment)

- live API：dev `:8080`，项目 `6363`
- 单测：`npx tsx --test src/api/projectSettingsError.test.ts`
- 代码：`web/src/api/projectSettingsError.ts`、`ProjectSettingsModal.tsx`

## 四、 预期结果 (Expected Results)

各用例 PASS；`npm test` 全绿。

## 五、 实际测试结果与判定 (Actual Results & Evaluation)

### 用例 1：版本冲突 409

- **输入**: SavePlan 后以 `expected_selection_version=999` 再 PUT
- **实际输出**: HTTP 409；嵌套业务码 `ERR_CONCURRENT_SWITCH`；recovery=`retry_after_switch`
- **判定**: PASS（[live.json](./assets/2026-09-16-frontend-gate-b4/live.json)）

### 用例 2：终止 preview

- **输入**: 激活实例后 `GET /api/v1/workflow-instances/{id}/termination-preview`
- **实际输出**: 200；keys 含 `can_terminate` / `pending_documents` / `in_progress_task_runs` / `impact`
- **判定**: PASS

### 用例 3：激活后冻结刷新

- **输入**: 激活后 PUT 旧 revision
- **实际输出**: 409；业务码 `PLAN_FROZEN`；recovery=`refresh_and_freeze`
- **判定**: PASS

### 用例 4：错误解包单测

- **输入**: projectSettingsError.test.ts（含信封嵌套用例）
- **实际输出**: 7 pass（[projectSettingsError-unit.txt](./assets/2026-09-16-frontend-gate-b4/projectSettingsError-unit.txt)）
- **判定**: PASS

## 六、 自动化测试套件汇总 (Test Suite Execution)

```text
cd web && npm test → 376 pass (tsx) + 32 pass (vitest) EXIT 0
```

## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)

- 发布门禁「前端：版本冲突刷新、终止 preview」可 ☑。
- 后续可将信封解包复用到其他 409 消费方，避免只认 `VERSION_CONFLICT`。