4.6 集成验收：形成完整业务演示版本¶

把“分别能用”的功能，整理成一个可以连续展示的项目¶

验收不是再演示一次成功页面

开发者每天都在自己的电脑上使用项目，很容易忽略缺失配置、测试数据、权限错误和只能靠手工操作才能继续的流程。

本节要暂时停止增加功能，从一个相对干净的环境重新启动项目，按照需求走查核心业务，记录问题并形成一个可复现、可演示的阶段版本。

本节学习目标

对项目骨架、登录权限、第一个模块、核心业务流程和特色功能进行集成检查，验证正常、失败和越权场景，整理文档与演示材料，形成 v0.5 完整业务演示版本。

🎯 本节完成后，你要交付¶

成果	要求
可运行集成版本	项目能够根据 README 从数据库初始化到页面访问
核心业务验收记录	正常、业务失败和权限失败流程具有实际证据
特色功能验收记录	正常结果和失败降级均已验证
集成问题清单	每个问题有位置、影响、等级、状态和处理计划
演示脚本	能够在限定时间内连续展示项目价值和核心流程
阶段版本	Git 工作区干净，提交清楚，并创建 `v0.5` 标签

本节是第四篇的阶段门，不要求把一般优化全部做完，但影响启动、核心流程、权限、数据和演示的问题必须解决。

🧊 第一步：冻结本次验收范围¶

验收开始后暂停增加新功能。先记录本次要检查的版本和范围：

验收版本：【分支、提交编号或版本】
需求基线：《需求分析说明书》V__
设计基线：《系统设计说明书》V__
技术路线：【Spring Boot + Vue / Servlet + 原生前端】
核心流程：【开始 → 处理 → 最终结果】
特色功能：【名称；没有则写不适用】
明确不在本次范围：【填写】

验收前检查工作区¶

git status
git log --oneline -5

确认：

没有忘记提交的关键代码；
没有混入本机配置和调试文件；
当前检查的是准备演示的分支；
需求、设计和代码属于同一个版本；
团队成员知道验收期间暂停合并无关修改。

验收时不要顺便增加功能

发现新想法时放入“后续优化清单”。验收阶段频繁加入新功能，会让已经通过的流程重新变得不稳定。

🧹 第二步：从可重复环境重新启动¶

不要只使用已经运行多天、手工改过数据的开发环境。至少重新执行一次项目标准启动流程。

1. 核对 README¶

一个没有参与开发的人，应能从 README 找到：

环境版本；
数据库初始化方法；
配置文件或环境变量；
后端和前端启动命令；
访问地址；
测试账号；
常见限制。

如果实际命令与 README 不一致，先更新文档。

2. 重新初始化数据库¶

使用项目提交的 SQL 或迁移脚本创建数据库和测试数据。检查：

脚本能够从空库执行；
表、字段和约束完整；
初始化账号可以登录；
初始化数据能够支持核心流程；
不依赖开发者手工补字段或改状态；
不包含真实用户隐私。

3. 执行构建检查¶

Spring Boot + VueServlet + 原生前端

后端：

cd backend
mvn test
mvn clean package

前端：

cd frontend
npm install
npm run build

macOS 或 Linux：

./mvnw test
./mvnw clean package

Windows：

mvnw.cmd test
mvnw.cmd clean package

构建失败时不要使用“跳过测试”掩盖问题。先记录完整错误，判断是代码、测试、依赖还是环境问题。

4. 按 README 启动¶

启动后记录：

项目	实际结果
数据库初始化命令	【填写】
后端或 Tomcat 启动方式	【填写】
前端启动方式	【填写】
页面地址	【填写】
接口地址	【填写】
测试账号	【填写】
启动耗时和异常	【填写】

🚦 第三步：先做冒烟检查¶

冒烟检查用于快速判断项目是否具备继续验收的基本条件。

冒烟检查未通过，先停止完整验收

如果项目不能启动、登录或访问数据库，继续演示更多页面没有意义。先记录阻断问题并恢复基本运行状态。

🔗 第四步：验收核心业务闭环¶

按照需求中的核心场景，从发起角色开始连续操作到最终结果。

核心流程追踪表¶

步骤	操作角色	页面操作	接口	预期状态或数据变化	实际结果	证据
1	【填写】	【填写】	【填写】	【填写】	【填写】	页面/接口/数据库
2	【填写】	【填写】	【填写】	【填写】	【填写】	页面/接口/数据库
3	【填写】	【填写】	【填写】	【填写】	【填写】	页面/接口/数据库

每一步检查：

页面入口是否容易找到；
当前角色是否允许操作；
接口请求和响应是否正确；
页面提示是否能说明结果；
数据库状态和关联数据是否正确；
下一角色是否能够看到更新后的任务；
最终用户是否获得预期结果。

连续演示要求¶

登录角色 A
→ 发起核心业务
→ 切换角色 B
→ 完成处理
→ 必要时切换角色 C
→ 回到发起人查看最终结果

流程中不得：

手工修改数据库状态；
临时修改代码；
依赖未提交的本机文件；
使用只有开发者电脑才存在的数据；
跳过失败但继续声称流程完成。

🧪 第五步：补充失败、权限和边界验收¶

核心流程成功还不够，至少检查下面三类场景。

业务失败¶

根据项目选择一个最重要的失败条件：

库存不足；
名额已满；
重复报名；
当前状态不允许；
数据已经删除；
输入不完整或格式错误。

预期结果：

操作被拒绝
→ 页面显示明确原因
→ 数据库没有错误变化
→ 用户知道下一步怎么办

权限失败¶

至少验证：

未登录直接访问受限接口；
普通用户调用管理员接口；
用户修改对象 ID 尝试访问他人数据；
非负责人处理未分配给自己的任务。

后端必须拒绝越权请求，不能只依赖页面隐藏按钮。

边界与重复操作¶

根据项目选择：

空列表；
第一页和最后一页；
最小值和最大值；
连续点击提交；
重复确认、取消或归还；
登录过期后提交；
最后一个库存或名额。

验收记录¶

编号	场景	初始条件	操作	预期结果	实际结果	结论
AT-01	核心成功流程	【填写】	【填写】	【填写】	【填写】	通过/未通过
AT-02	业务失败	【填写】	【填写】	拒绝且数据不变	【填写】	通过/未通过
AT-03	权限失败	【填写】	【填写】	返回 401/403	【填写】	通过/未通过
AT-04	重复或边界	【填写】	【填写】	不产生错误数据	【填写】	通过/未通过

✨ 第六步：验收特色功能及降级¶

如果本项目没有特色功能，本步骤标记为“不适用”，不要临时增加。

先验证正常场景：

功能入口与核心业务相关；
输入和输出符合任务卡；
使用真实项目数据；
结果能够帮助用户完成任务；
页面具有加载、成功和空结果状态。

再验证失败场景：

外部服务超时或不可用；
输入为空或信息不足；
返回格式错误；
当前用户无权限；
API Key 未配置；
用户取消或重新尝试。

特色功能失败时应明确提示或降级，核心业务仍然能够运行。

不要为了演示偷偷使用个人密钥

演示所需配置应通过安全方式准备，并在 README 中说明配置项。不要把真实密钥写入代码、截图、测试记录或 Git 提交。

🧽 第七步：清理临时代码和不一致内容¶

集成后检查项目中是否仍有开发阶段遗留内容：

静态模拟数据；
写死的用户 ID、角色、端口或地址；
console.log、临时弹窗和调试接口；
失效页面和无效路由；
已废弃但仍可访问的接口；
重复组件和重复请求封装；
注释掉的大段旧代码；
示例名称残留；
本机绝对路径；
真实密码、密钥或隐私数据；
node_modules/、target/、日志和 IDE 缓存。

不要在验收阶段大规模重构¶

只处理影响正确性、安全、构建和演示的问题。纯粹为了代码“更漂亮”的大范围重构放入后续计划，避免引入新的错误。

📚 第八步：同步代码、接口和文档¶

文档必须描述当前真实项目，而不是最初计划。

至少检查：

材料	需要一致的内容
需求说明书	已实现范围、角色和验收条件
系统设计说明书	技术方案、模块、数据库、接口、权限和状态
数据库脚本	实际表、字段、约束和初始化数据
接口文档或 Postman	实际路径、参数、响应、权限和错误结果
README	环境、配置、启动、账号和访问地址
测试记录	真实执行结果和未通过问题

不要为了让文档“看起来全部完成”而修改需求。如果某项功能暂未实现，应明确记录当前状态和后续计划。

🐞 第九步：建立集成问题清单¶

验收发现问题时，先记录再修复。

编号	问题位置	复现步骤	影响	等级	处理结果	状态
BUG-001	【页面/接口】	【填写】	【填写】	阻断/重要/一般/建议	【填写】	待处理/已关闭/暂缓

问题等级¶

阻断：项目无法启动、登录或完成核心流程；
重要：出现数据错误、越权、严重异常或核心结果错误；
一般：不阻断核心流程，但影响主要操作和一致性；
建议：不影响阶段演示，可以后续优化。

形成 v0.5 前：

阻断问题必须关闭；
重要问题原则上关闭；
未关闭问题必须说明影响和处理计划；
一般与建议问题可以进入下一阶段缺陷清单。

修复后要重新执行相关场景以及一条完整核心流程，不能只检查修改位置。

🎬 第十步：准备并彩排演示¶

演示不是逐个点击所有菜单，而是证明项目解决了什么问题。

建议的 5～8 分钟结构¶

时间	内容
30 秒	介绍目标用户、问题和项目价值
1 分钟	说明角色、技术方案和主要模块
3～4 分钟	连续演示核心业务流程
1 分钟	演示一个失败、越权或边界场景
1 分钟	展示特色功能及其价值
30 秒	说明当前限制和下一步计划

演示前准备¶

固定测试账号和数据；
按顺序写出演示步骤；
提前打开需要的页面和工具；
清除会影响演示的旧数据；
检查网络和外部服务；
准备特色功能失败时的说明；
保留接口、日志或数据库证据；
不在现场修改代码或数据库。

演示一个失败场景更能证明项目真实

例如普通用户调用管理员接口被拒绝、重复报名得到明确提示。这比只展示多个成功页面更能说明权限和业务规则已经实现。

🤖 第十一步：让 AI 做一次独立检查¶

可以让 AI 以验收者身份重新检查，而不是继续生成新功能：

请以课程项目验收者身份工作。

先阅读 AGENTS.md、README、需求分析说明书、系统设计说明书、
数据库脚本、接口材料、测试记录，以及当前项目代码。

不要修改文件，不要增加功能。

请检查：
1. 新环境是否能按 README 初始化和启动；
2. 核心需求是否能够追踪到页面、接口和数据；
3. 核心业务是否可以跨角色连续完成；
4. 失败、未登录、越权和重复操作是否得到处理；
5. 页面、接口、权限、状态和数据库是否一致；
6. 特色功能失败时核心业务是否仍可用；
7. 是否残留模拟数据、调试代码、真实密钥或无效接口；
8. 文档是否与实际代码一致。

对每个问题给出位置、证据、影响和等级。
区分“从代码确认”和“尚未实际运行验证”，不要虚构测试结果。

人工复核 AI 结果：

是否引用了真实代码或文档；
是否把个人偏好当成严重问题；
是否建议了超出课程范围的改造；
是否错误理解业务状态和角色；
是否把未运行内容说成已经通过。

🏷️ 第十二步：形成阶段版本¶

完成修复和复核后，进行最终检查：

git status
git log --oneline -10

工作区应保持干净。必要时提交最后的验收修复和文档：

1
2
3

fix: resolve integration acceptance issues
docs: update README and acceptance records
test: add core workflow acceptance evidence

创建阶段标签：

git tag -a v0.5 -m "complete core workflow demo"
git tag

如果课程使用远程仓库，按教师要求推送当前分支和标签。推送前再次确认没有密钥、密码、隐私数据和本机配置。

阶段结论¶

结论	判断标准
通过	项目可启动，核心流程、权限和数据正确，阻断与重要问题关闭
修改后通过	核心流程基本可用，仍有明确问题需要在限定时间内复核
不通过	无法稳定启动、核心流程中断、存在严重越权或数据错误

“通过”不表示项目以后不再修改，而是当前版本已经能够作为下一阶段测试、优化和部署的基础。

📋 阶段验收记录模板¶

# 项目集成验收记录

## 1. 基本信息
- 项目名称：
- 验收版本：
- Git 提交：
- 技术路线：
- 验收环境：
- 验收日期：

## 2. 启动与构建
- 数据库初始化：
- 后端构建：
- 前端构建：
- 启动结果：

## 3. 核心流程
- 流程名称：
- 参与角色：
- 操作步骤：
- 最终结果：
- 验收证据：

## 4. 异常与权限
- 业务失败场景：
- 越权场景：
- 重复或边界场景：

## 5. 特色功能
- 功能名称：
- 正常结果：
- 失败或降级结果：

## 6. 问题统计
- 阻断：
- 重要：
- 一般：
- 建议：
- 未关闭问题：

## 7. 验收结论
- 通过 / 修改后通过 / 不通过
- 结论说明：
- 下一步：

✅ 本节验收清单¶

📝 总结¶

先冻结版本，再开始验收：验收期间不继续增加新功能。
从干净环境证明可运行：README、脚本和配置必须能够复现。
用完整流程证明项目价值：跨角色连续演示，不依赖手工改库。
成功与失败都要有证据：业务失败、越权和边界场景同样重要。
形成可继续迭代的阶段版本：记录问题、同步文档并保存 v0.5。

返回上一节：增加特色返回第四篇导读