Day 6 - 验收与交付

建议用时：180-210 分钟

你将学会什么

把功能清单变成可验收标准
整理交付目录结构
编写验收记录和交接说明
准备示例数据
判断一个版本是否真的可以交出去

验收不是“我觉得可以”。验收必须能逐条检查：执行了什么、期望看到什么、实际结果是什么、是否通过。

本页固定顺序

先学第一部分：弄懂今天最小、最重要的知识，并运行短例子。
再学第二部分：把刚学的知识组合成一个完整例子。
然后做第三部分：自己跟着敲，再完成重复训练和每日小测。
最后做第四部分：先独立完成作业，再用完整答案检查。

今天只抓住 3 件事

验收要写清操作、期望结果、实际结果，不能只写“正常”。
交付包要包含程序、文档、示例数据、检查记录。
一个版本能不能交出去，要看清单是否全部通过。

学习衔接

上一页学习的是“版本与发布”，今天继续学习“验收与交付”。先使用上一页已经会的写法，再只增加今天这个新知识点；如果前置内容还不能独立敲出，先回上一页复习，不要硬跳。

第一部分：先学原理和最小知识

这一部分只读，不敲代码。

验收是什么

验收就是按事先写好的标准检查软件是否满足要求。

它不是随便点几下界面，而是按固定清单检查：

正常流程能不能走通。
错误输入会不会被拦住。
空数据有没有提示。
数据能不能保存。
关闭后重新打开，数据还在不在。
文档能不能照着运行。

交付是什么

交付就是把“软件本体、文档、示例数据、检查结果”一起交出去。

只给一个可执行文件通常不够，因为接收方还会问：

这个版本号是多少？
怎么启动？
数据放在哪里？
出错怎么办？
这个版本检查过哪些功能？
还有哪些已知问题？

交付包要能回答这些问题。

常见名词

名词	直接解释	例子
RC	Release Candidate，发布候选版本	`1.0.0-rc.1`
验收标准	判断是否通过的具体条件	“价格小于等于 0 时显示错误”
交付物	交出去的文件集合	程序、文档、示例数据
验收记录	实际检查结果	A-001 通过，A-002 通过
交接说明	给接收方看的入口说明	目录结构、启动方式、联系人
回滚	新版本有问题时退回旧版本	从 `1.0.1` 退回 `1.0.0`

好的验收标准长什么样

好的验收标准必须具体。

不够具体：


新增商品功能正常。

具体写法：


输入名称 Keyboard、价格 199、库存 10 后点击保存，商品列表出现 Keyboard，价格显示 199，库存显示 10。

具体标准的好处是：不同的人照着测，结果应该一致。

为什么要准备示例数据

示例数据能让接收方快速验证功能，不需要自己临时编数据。

示例数据应该覆盖：

正常商品。
多个价格。
多个库存。
搜索能命中的关键词。

比如 Keyboard、Mouse、Monitor，可以测试列表、搜索、编辑、删除。

第二部分：把知识组合成完整例子

今天的目标不是新增功能，而是把项目整理成别人可以接收的版本。

一个完整交付包至少包含：


release/ProductManager-1.0.0/
  app/
  docs/
  sample-data/
  checks/

每个目录负责不同内容：

目录	放什么	作用
`app/`	Release 发布后的程序文件	真正运行的软件
`docs/`	README、用户手册、排错文档、发布说明	告诉别人怎么用、怎么排错
`sample-data/`	示例 JSON、示例 CSV	方便快速验证功能
`checks/`	验收清单、验收结果、交接说明	证明这个版本检查过

先看一个验收条目


编号：A-001
功能：新增商品
操作：输入名称 Keyboard、价格 199、库存 10，点击保存。
期望结果：列表出现 Keyboard，价格为 199，库存为 10。
实际结果：通过。

这个条目合格，因为它写清楚了：

测什么功能。
怎么操作。
期望看到什么。
实际是否通过。

第三部分：跟着整理交付包

从这里开始动手。下面按 ProductManager-1.0.0 版本整理交付材料。

第 1 步：整理目录结构

准备这个目录：


release/ProductManager-1.0.0/
  app/
  docs/
  sample-data/
  checks/

含义：

app/ 放 dotnet publish 生成的文件。
docs/ 放 Day 4 和 Day 5 写好的文档。
sample-data/ 放示例数据。
checks/ 放验收清单、验收结果、交接说明。

第 2 步：写示例 JSON 数据

创建 sample-data/products.json。


[
  {
    "id": 1,
    "name": "Keyboard",
    "price": 199,
    "stock": 10
  },
  {
    "id": 2,
    "name": "Mouse",
    "price": 99,
    "stock": 20
  },
  {
    "id": 3,
    "name": "Monitor",
    "price": 899,
    "stock": 5
  }
]

这份数据可以验证：

列表能显示多行。
搜索 key 能找到 Keyboard。
搜索 mo 能找到 Mouse 和 Monitor。
编辑和删除有明确对象。

第 3 步：写示例 CSV 数据

创建 sample-data/products.csv。


Id,Name,Price,Stock
1,Keyboard,199,10
2,Mouse,99,20
3,Monitor,899,5

这份 CSV 可以用于验证导入功能。

第 4 步：写验收清单

创建 checks/ACCEPTANCE_TEST.md。


# ProductManager 1.0.0 验收清单
 
验收日期：2026-06-12
 
## A. 启动和基础界面
 
- [ ] A-001 应用能从发布目录启动。
- [ ] A-002 首次打开时，空列表有提示。
- [ ] A-003 主窗口能看到商品列表区域。
 
## B. 商品新增
 
- [ ] B-001 输入名称 Keyboard、价格 199、库存 10 后点击保存，列表出现 Keyboard。
- [ ] B-002 名称为空时点击保存，显示“商品名称不能为空”。
- [ ] B-003 价格为 0 时点击保存，显示价格错误。
- [ ] B-004 库存为 -1 时点击保存，显示库存错误。
- [ ] B-005 保存中按钮不可重复点击。
 
## C. 商品编辑和删除
 
- [ ] C-001 选中商品后修改价格，保存后列表显示新价格。
- [ ] C-002 未选中商品时，删除操作不可执行或给出提示。
- [ ] C-003 删除已选中商品后，商品从列表消失。
 
## D. 搜索和筛选
 
- [ ] D-001 搜索 Keyboard 时，只显示名称包含 Keyboard 的商品。
- [ ] D-002 搜索不存在的关键词时，显示无结果提示。
- [ ] D-003 清空搜索框后，列表恢复显示全部商品。
 
## E. 数据保存
 
- [ ] E-001 新增商品后关闭应用，再打开，商品仍然存在。
- [ ] E-002 JSON 文件损坏时，应用显示可理解的错误提示。
- [ ] E-003 保存失败时，日志记录失败原因。
 
## F. 导入导出
 
- [ ] F-001 导入 products.csv 后，列表出现 CSV 中的商品。
- [ ] F-002 CSV 中有错误行时，显示成功数量和失败数量。
- [ ] F-003 导出 CSV 后，文件包含标题行和商品数据。
 
## G. 文档和发布
 
- [ ] G-001 README 能说明怎么启动项目。
- [ ] G-002 用户手册能说明新增、编辑、删除、搜索。
- [ ] G-003 排错文档包含启动失败、保存失败、导入失败。
- [ ] G-004 发布说明包含版本号、发布日期、已知问题。

第 5 步：写验收结果记录

创建 checks/ACCEPTANCE_RESULT.md。


# ProductManager 1.0.0 验收结果
 
验收日期：2026-06-12
验收版本：1.0.0
验收结论：待确认
 
## 通过项
 
- A-001 应用能从发布目录启动。
- B-001 新增商品成功。
- D-001 搜索 Keyboard 成功。
 
## 未通过项
 
- 暂无。
 
## 需要复测项
 
- E-002 JSON 文件损坏时的错误提示。
- F-002 CSV 中有错误行时的成功数量和失败数量。
 
## 备注
 
如果未通过项不为空，本版本不能作为正式版本交付。需要修复后重新发布，并更新版本号或发布说明。

第 6 步：写交接说明

创建 checks/HANDOFF.md。


# ProductManager 1.0.0 交接说明
 
## 交付内容
 
- `app/`：Release 发布产物。
- `docs/`：运行说明、用户手册、排错文档、发布说明。
- `sample-data/`：示例 JSON 和 CSV 数据。
- `checks/`：验收清单、验收结果、交接说明。
 
## 启动方式
 
1. 打开 `app/` 目录。
2. 运行发布产物中的可执行文件。
3. 如果无法启动，先查看 `docs/TROUBLESHOOTING.md`。
 
## 重点验证
 
- 新增商品。
- 编辑商品。
- 删除商品。
- 搜索商品。
- 保存后重新打开。
- CSV 导入导出。
 
## 数据说明
 
- 示例 JSON：`sample-data/products.json`
- 示例 CSV：`sample-data/products.csv`
- 实际运行数据位置以应用配置或代码中的仓储路径为准。
 
## 回滚说明
 
如果 `1.0.0` 运行出现严重问题，保留旧版本发布目录，不要覆盖旧版本。回滚时重新使用上一个已验证版本的 `app/` 目录。
 
## 已知问题
 
已知问题见 `docs/KNOWN_ISSUES.md`。

第 7 步：检查交付包是否完整

最终目录应该类似：


release/ProductManager-1.0.0/
  app/
  docs/
    README.md
    USER_GUIDE.md
    TROUBLESHOOTING.md
    RELEASE_NOTES_1.0.0.md
    KNOWN_ISSUES.md
  sample-data/
    products.json
    products.csv
  checks/
    ACCEPTANCE_TEST.md
    ACCEPTANCE_RESULT.md
    HANDOFF.md

检查时不要只看有没有文件，还要打开文件确认内容是不是最新版本。

验收交付常用操作速查

需求	文件或目录	作用
放程序	`release/ProductManager-1.0.0/app/`	存放发布产物
放文档	`release/ProductManager-1.0.0/docs/`	存放 README、手册、排错
放示例数据	`release/ProductManager-1.0.0/sample-data/`	快速验证导入导出
放检查记录	`release/ProductManager-1.0.0/checks/`	存放验收结果
写验收项	`ACCEPTANCE_CHECKLIST.md`	操作、期望、实际、结果
写交接说明	`HANDOVER.md`	交付内容、启动方式、回滚说明
写验收结果	`ACCEPTANCE_RESULT_版本.md`	证明检查过哪些内容

常见错误和修法

错误	为什么错	修法
验收项只写“功能正常”	不同的人无法按同一标准检查	写清输入、点击、期望看到什么
只交程序文件	接收方不知道怎么运行和排错	同时交文档、示例数据、检查记录
示例数据为空	无法快速验证导入导出	准备一份正常数据和一份错误数据
已知问题不写	交付后容易产生误解	在交接说明里写清影响和处理办法
没有回滚说明	新版本出问题时无法退回	写清旧版本位置和恢复步骤

小白重复敲写训练

验收不是只打勾，要准备数据并亲手验证结果。

训练 1：准备边界数据


var samples = new[]
{
    new Product { Name = "Normal", Price = 10m, Stock = 1 },
    new Product { Name = "ZeroPrice", Price = 0m, Stock = 0 },
    new Product { Name = "Large", Price = 999999m, Stock = 100000 }
};

训练 2：自动检查关键条件


foreach (Product product in samples)
{
    bool valid = !string.IsNullOrWhiteSpace(product.Name)
        && product.Price >= 0
        && product.Stock >= 0;
 
    Console.WriteLine($"{product.Name}: {valid}");
}

训练 3：生成简单验收结果


var results = new List<string>
{
    "[PASS] 程序可以启动",
    "[PASS] 可以新增商品",
    "[FAIL] 错误文件提示不清楚"
};
 
await File.WriteAllLinesAsync("acceptance-result.txt", results);

第三遍把失败项修复后改成 PASS，并记录复测时间。

每日小测

做完本页后，用这 5 题检查是否真的掌握。

1. 判断题

本页的目标不是只把代码运行起来，还要能说清楚“为什么这样写”。

答案：对。能运行只是第一步，能解释原理、常用操作和常见错误，才说明本页内容进入了可复用能力。

2. 填空题

本页主题是：验收与交付。今天至少要掌握的 3 个点是：


1. 把功能清单变成可验收标准
2. 整理交付目录结构
3. 编写验收记录和交接说明

答案：以上 3 点必须能用自己的代码跑通，不能只停留在阅读。

3. 流程题

遇到本页相关功能时，先按什么顺序处理？

答案：先看完整例子，确认最终效果；再读原理和名词；然后跟着第三部分从空项目敲代码；最后对照作业答案检查。

4. 找错误题

如果本页代码运行失败，第一步应该做什么？

答案：先看终端或 IDE 里的第一条错误，找到文件名和行号；不要同时改很多地方。再回到本页的“常见错误和修法”表格，对照错误类型逐项排查。

5. 改需求题

在本页完整例子跑通后，至少改一个小需求。

可选改法：

改一个字段名称。
多加一个校验条件。
多输出一行结果。
把固定数据改成用户输入。
把一次处理改成多条数据处理。

答案标准：修改后能重新运行，并能说明这次修改影响了哪一段逻辑。重点检查：把功能清单变成可验收标准。

上位机专项练习

最终验收要按真实操作流程执行，包含正常场景、异常场景、重启恢复和长时间运行。

下面 3 个例子都要亲手敲。先运行原代码，再完成每个例子后面的改动任务。

专项例子 1：正常流程验收


1. 启动程序
2. 加载 3 台模拟设备
3. 开始采集
4. 数值持续更新
5. 产生并确认报警
6. 导出报警 CSV

运行结果或界面效果：


完整主流程无中断

改动任务： 为每一步记录通过、失败和截图。

专项例子 2：异常流程验收


1. 使用错误 IP
2. 确认显示连接失败
3. 修正 IP
4. 点击重连
5. 确认数据恢复
6. 检查日志包含失败与恢复

运行结果或界面效果：


故障可见、可处理、可追踪

改动任务： 再测试配置文件损坏。

专项例子 3：重启恢复验收


关闭前:
- 选择 PLC-02
- 设置采集周期 500 ms
- 使用深色主题

重启后:
- 三项设置全部恢复

运行结果或界面效果：


持久化结果能被实际验证

改动任务： 增加窗口大小恢复。

第四部分：作业完整答案

作业要求

给 1.0.1 修复版本写一份完整交付结果，要求包含：

交付包内容。
已通过验收项。
未通过验收项。
是否允许交付。
后续处理。

完整答案：checks/ACCEPTANCE_RESULT_1.0.1.md


# ProductManager 1.0.1 验收结果
 
验收日期：2026-06-12
验收版本：1.0.1
验收结论：允许交付
 
## 交付包内容
 
- `app/`：ProductManager 1.0.1 Release 发布产物。
- `docs/README.md`：项目入口说明。
- `docs/USER_GUIDE.md`：用户操作说明。
- `docs/TROUBLESHOOTING.md`：常见问题处理。
- `docs/RELEASE_NOTES_1.0.1.md`：发布说明。
- `docs/KNOWN_ISSUES.md`：已知问题。
- `sample-data/products.json`：示例 JSON 数据。
- `sample-data/products.csv`：示例 CSV 数据。
- `checks/ACCEPTANCE_TEST.md`：验收清单。
- `checks/HANDOFF.md`：交接说明。
 
## 已通过验收项
 
- A-001 应用能从发布目录启动。
- A-002 首次打开时，空列表有提示。
- B-001 新增商品成功。
- B-002 名称为空时显示错误提示。
- B-003 价格为 0 时显示错误提示。
- B-004 库存为 -1 时显示错误提示。
- D-001 搜索 Keyboard 成功。
- D-003 清空搜索后，列表恢复。
- G-001 README 能说明启动方式。
- G-004 发布说明包含版本号、发布日期、已知问题。
 
## 未通过验收项
 
- 暂无。
 
## 需要后续优化
 
- CSV 导入失败时，后续显示失败行号。
- 删除商品后，后续增加撤销能力。
- 多设备数据同步后续再设计。
 
## 是否允许交付
 
允许交付。
 
原因：
 
- 主流程已经通过。
- 关键错误输入已经被拦截。
- 文档和发布说明已经补齐。
- 已知问题不阻塞当前版本使用。

正确结果

完成后，交付材料应该能回答：

软件放在哪里。
文档放在哪里。
示例数据放在哪里。
哪些功能已经验收。
哪些问题还存在。
这个版本能不能交付。