5.6 整理交付：README、测试报告与 v1.0¶

让他人能运行、理解并验证你的项目¶

交付不是把整个项目文件夹压缩后发出去

一个课程项目的价值，不只在于开发者电脑上能打开。教师、同学、未来的面试官或接手项目的人，应当能够快速知道：项目解决什么问题、具备什么功能、怎样启动、怎样测试、使用什么账号、哪些地方仍有限制。

第五篇前面的小节已经完成测试、缺陷修复和部署验证。本节把这些分散成果整理成可交付版本：完善 README、汇总测试报告与部署记录、清理无关文件和敏感信息、检查 Git 历史，并创建可定位的 v1.0 标签。

本节学习目标

建立清晰的项目 README，完成测试报告、部署说明与交付清单；确认源代码、配置模板、数据库脚本、文档和演示材料相互一致，创建一个可复现、可验证、可展示的 v1.0 课程项目版本。

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

成果	要求
项目 README	第一次接触项目的人能理解、启动、测试和查看项目
测试报告	汇总测试范围、执行结果、缺陷、回归与剩余风险
部署说明与验证记录	写清部署环境、命令、访问地址、账号和验证结果
数据库与配置材料	初始化/迁移脚本、配置模板、环境变量说明完整且无敏感信息
成果材料	系统截图、可选演示视频、项目文档链接或目录
最终交付清单	核对代码、文档、测试、部署与演示是否完整
Git `v1.0` 版本	工作区干净，创建可定位的提交、标签或 Release

README 是项目的一部分

没有启动说明、数据库脚本、测试账号和配置说明的项目，即使代码写得再多，其他人也难以验证。README 不是最后随便补几行文字，而是交付入口。

一、先冻结最终交付版本¶

整理交付前，应停止增加非必要功能。此时的任务是保证已有功能稳定、材料一致，而不是临时再加一个复杂特性。

1. 记录交付基线¶

项目名称：【填写】
交付版本：v1.0
代码分支：【填写】
交付提交：【填写】
需求版本：《需求分析说明书》V【填写】
设计版本：《系统设计说明书》V【填写】
测试版本：【填写】
部署版本：【填写】
交付日期：【填写】

2. 检查 Git 状态¶

git status
git log --oneline -10
git diff --check

交付前应确认：

工作区没有未提交的关键代码、文档或脚本；
没有把 target/、dist/、node_modules/、日志、备份或上传文件误提交；
没有把 .env、数据库密码、JWT 密钥和第三方 API Key 提交；
最新提交可以编译、启动并完成核心流程；
测试报告、README、部署说明引用的版本与当前代码一致；
已知未解决问题已记录，不通过口头方式隐藏。

3. 不要在交付前“最后大改一次”¶

交付前最常见的风险是：为了让页面更漂亮、增加一个功能或临时修复一个问题，进行大范围修改，却没有重新测试。

准备交付
→ 发现小问题
→ 判断是否影响启动、核心流程、数据或权限
→ 是：修复、测试、回归、提交
→ 否：记录到后续优化清单
→ 不要混入大重构或新功能

没有重新验证的最后修改，不属于稳定交付版本

每一项进入 v1.0 的修改，都应有对应的测试或回归证据。

二、第一步：写好项目 README¶

README 面向第一次接触项目的人。它不是开发日志，也不是课程作业流水账；它需要让读者快速判断项目价值，并在需要时复现运行。

1. README 应回答的核心问题¶

问题	README 应包含的内容
这是什么项目？	项目名称、背景、解决的问题、目标用户
项目能做什么？	核心角色、核心功能、特色功能、业务流程
用什么实现？	技术栈、运行环境、架构或目录说明
怎样启动？	环境要求、数据库初始化、配置、启动/部署命令
怎样验证？	测试账号、访问地址、关键测试方式
交付到什么程度？	部署状态、截图、演示视频、已知限制、后续计划

2. 推荐 README 目录¶

# 项目名称

> 一句话说明项目为谁解决什么问题。

## 1. 项目简介
## 2. 核心功能与角色
## 3. 系统截图或演示
## 4. 技术栈
## 5. 项目结构
## 6. 环境要求
## 7. 快速启动
## 8. Docker 部署
## 9. 测试账号
## 10. 测试与质量说明
## 11. 项目文档
## 12. 已知限制与后续计划
## 13. 开源许可（如适用）

3. 项目简介要写真实业务价值¶

不推荐：

1	`这是一个使用 Spring Boot 和 Vue 开发的管理系统。`

这只说明技术，不说明项目解决什么问题。

推荐：

1
2

校园失物招领平台面向失主、拾到者和管理员，解决失物信息分散、认领过程难追踪、虚假认领难审核的问题。
系统支持失物发布、线索匹配、认领申请、管理员审核和状态追踪，帮助校园用户完成可验证的失物归还流程。

4. 核心功能不只罗列菜单名称¶

建议按角色和业务结果说明：

角色	可完成的任务
普通用户	注册登录、发布信息、提交申请、查看个人记录与处理状态
管理员	审核内容、处理异常记录、维护基础数据、查看统计信息
【其他角色】	【填写】

可补充一条核心流程：

用户 A 发起【业务】
→ 角色 B 审核或处理
→ 系统校验【规则】
→ 角色 A 查看最终结果

5. 截图应说明“展示什么”¶

截图不是越多越好。选择能够证明核心能力的 3—6 张图：

截图	说明
首页或登录页	项目定位与基础访问入口
核心列表页	主要业务对象与查询能力
核心操作页	用户如何完成关键任务
管理或处理页	多角色协作与权限差异
最终结果页	核心流程完成后的状态
部署访问图（可选）	项目在 Docker/局域网环境可访问

每张图下加一句说明，例如：

![活动报名列表](docs/images/activity-list.png)

> 学生可以查看已发布活动、剩余名额和个人报名状态。

截图应来自最终版本

不要使用已经删除功能、旧配色、测试失败页面或含真实隐私信息的截图。截图中的数据应与 README、测试账号和系统当前状态可对应。

三、第二步：写清快速启动与部署步骤¶

README 的启动说明应让同学不依赖你的口头解释也能完成操作。

1. 环境要求写明确版本¶

组件	Spring Boot + Vue 路线示例	Servlet + HTML 路线示例
JDK	JDK 17	JDK 17
构建工具	Maven 3.9+、Node.js 18+	Maven 3.9+
Web 服务	Spring Boot 内嵌服务	IntelliJ IDEA + smart-tomcat + Tomcat 11
数据库	MySQL 8	MySQL 8
容器部署	Docker + Docker Compose	Docker + Docker Compose

不要只写“安装 Java、数据库”。应写清实际测试过的版本与必要插件。

2. 数据库初始化必须可执行¶

# 示例：从项目根目录执行，按实际路径替换
mysql -u root -p < sql/init.sql

说明：

创建的数据库名；
是否需要先创建数据库；
初始化脚本位置；
是否包含测试账号和演示数据；
重置数据的方法；
迁移脚本项目如何执行。

3. 本地开发启动示例¶

Spring Boot + VueServlet + HTML + CSS + JavaScript

# 后端
cd backend
mvn spring-boot:run

# 前端（新终端）
cd frontend
npm install
npm run dev

访问地址：http://localhost:5173

1. 在 IntelliJ IDEA 打开项目；
2. 安装并启用 smart-tomcat 插件；
3. 配置本地 Tomcat 11 路径与部署 context path；
4. 执行 SQL 初始化；
5. 通过 smart-tomcat 启动应用；
6. 浏览器访问 http://localhost:8080/【context-path】/。

4. Docker 部署示例¶

# 复制本机私有环境变量模板（若项目提供）
cp deploy/.env.example deploy/.env

# 编辑 deploy/.env，填写本机数据库密码和密钥

# 构建并后台启动
cd deploy
docker compose up -d --build

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

写清实际访问地址，例如：

1 2	`浏览器访问：http://localhost:8088 测试账号：admin / 【测试密码】`

命令必须在干净环境验证过

不要复制网上命令或写“理论上可用”的步骤。README 中的每一条启动命令都应由你或同学实际执行并记录结果。

四、第三步：完成测试报告¶

测试报告不是测试用例的复制，而是对最终质量状态的总结。它让读者知道：测了什么、结果如何、有哪些问题、项目是否达到交付要求。

1. 测试报告建议结构¶

# 【项目名称】测试报告

## 1. 测试基本信息
## 2. 测试目标与范围
## 3. 测试环境
## 4. 测试策略与测试用例概况
## 5. 测试执行结果
## 6. 缺陷统计与修复情况
## 7. 部署验证结果
## 8. 质量结论与已知限制

2. 必须汇总的内容¶

内容	应说明什么
测试版本	对应哪个提交、分支或标签
测试环境	操作系统、数据库、浏览器、部署方式、地址
覆盖范围	冒烟、登录、核心功能、核心流程、异常、权限、部署
用例结果	总数、通过、失败、阻塞、不适用数量
缺陷情况	P0/P1/P2 缺陷数量、已修复与暂缓情况
回归结果	修复后原用例和关联场景是否通过
部署验证	Docker 启动、浏览器访问、核心流程、重启持久化结果
最终结论	是否达到课程交付要求，仍有哪些限制

3. 测试结果汇总表示例¶

类别	用例数	通过	失败	阻塞	不适用	结论
冒烟与启动	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
认证与权限	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
核心功能	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
核心业务流程	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
异常与边界	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
部署验证	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】
合计	【填写】	【填写】	【填写】	【填写】	【填写】	【填写】

4. 结论要真实、有边界¶

不推荐：

1	`所有功能均正常，系统没有问题。`

推荐：

1
2
3

当前 v1.0 版本已完成启动、登录、角色权限、【核心流程】、异常处理和本机 Docker 部署验证。
P0 缺陷均已修复并回归通过；剩余 2 个 P2 体验问题已记录在后续优化清单中，不影响核心业务、数据正确性和课程演示。
当前版本的已知限制包括：【填写】。

测试报告允许有已知限制

一个诚实说明范围和风险的项目，比声称“完全没有问题”但无法复现的项目更专业。

五、第四步：整理部署说明与可访问证据¶

测试报告说明质量，部署说明帮助他人运行，两者不要混为一份只有截图的文档。

部署说明至少包含¶

项目	内容
部署版本	Git 提交、标签、日期
部署目标	本机 Docker、局域网或云服务器
环境要求	Docker/Compose、JDK、数据库等版本
私有配置	`.env`、环境变量、配置文件如何准备
启动命令	构建、启动、停止、查看日志、重启命令
访问地址	浏览器、接口、数据库工具（如允许）地址
测试账号	各角色账号及仅限测试的说明
数据管理	初始化、备份、恢复、重置方式
验证步骤	登录、核心流程、重启与持久化验证
已知限制	未部署公网、无 HTTPS、仅支持指定浏览器等

部署证据建议¶

deployment-evidence/
├── docker-compose-ps.png
├── backend-startup-log.txt
├── browser-home.png
├── deployed-core-workflow.png
├── restart-data-persisted.png
└── deployment-record.md

如果项目只有本机部署，不要伪造公网地址。可以真实写：

1 2	`部署状态：已完成本机 Docker 部署与验证。访问范围：部署电脑本机；局域网/公网部署未纳入本课程版本。`

六、第五步：清理交付包与敏感信息¶

交付前的清理不是删除所有文件，而是保留可复现材料，移除无关、隐私和危险内容。

1. 应提交的内容¶

源代码
→ README
→ .gitignore
→ 配置模板 / .env.example
→ 数据库初始化或迁移脚本
→ Dockerfile / docker-compose.yml / Nginx 配置
→ 接口测试集合
→ 需求、设计、测试、部署文档
→ 必要系统截图与演示材料
→ LICENSE（如使用）

2. 不应提交的内容¶

node_modules/
target/
dist/
*.jar / *.war（除非课程明确要求）
logs/
backup/
uploads/ 中的真实文件
.idea/、.vscode/（项目团队另有约定除外）
.env、application-local.yml
真实数据库密码、JWT 密钥、API Key
真实用户、隐私数据、支付信息

3. 交付前敏感信息检查¶

# 查看待提交文件
git status

# 查看本次改动
git diff
git diff --cached

# 在当前工作目录中搜索常见敏感字段
# macOS / Linux
grep -R "password\|secret\|apiKey\|token" . \
  --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=target

发现真实敏感信息时：

停止提交
→ 替换为环境变量或示例值
→ 加入 .gitignore
→ 若已经提交或推送，立即轮换密钥
→ 记录处理结果

删除文件不等于删除 Git 历史

已经推送过的密码或密钥，可能仍存在于 Git 历史或他人克隆中。正确处理是立即在相关平台更换密码/密钥，并评估是否需要清理历史。

七、第六步：整理最终交付清单¶

交付前不靠记忆检查。逐项对照清单，确认所有材料属于同一个版本。

1. 代码与配置¶

项目可以从当前分支或提交构建；
Git 工作区干净；
.gitignore 正确排除构建产物、日志、备份和私有配置；
.env.example、配置模板和 README 一致；
数据库初始化/迁移脚本可执行；
Dockerfile、docker-compose.yml、Nginx 配置已实际验证；
代码中没有开发机绝对路径、真实密码、密钥或 API Key；
已删除无关调试代码、临时接口和无效测试数据。

2. 功能与质量¶

登录、退出、认证与角色权限正确；
至少一个完整核心流程可连续演示；
正常、失败、权限和边界场景已有测试证据；
P0 缺陷已修复并完成回归；
P1 未修复问题有明确说明；
部署环境下重新完成了核心流程；
服务重启后数据行为符合说明；
已知限制未被写成“已支持”。

3. 文档与成果材料¶

README 完整且在干净环境中验证；
《需求分析说明书》与最终实现没有明显冲突；
《系统设计说明书》已反映主要实现变更；
测试计划、测试用例、缺陷清单、测试报告已整理；
部署说明与部署验证记录已整理；
系统截图来自最终版本；
演示视频（如要求）能够展示核心流程；
所有文件命名清晰、目录可理解、链接可打开。

4. 交付版本记录¶

写清交付分支、提交编号和标签；
标签建立在已经通过测试和部署验证的提交上；
推送到远程仓库（如课程要求）；
远程仓库页面可访问，README 正确显示；
如有部署地址，已确认链接可访问或明确其访问范围；
已准备好交给教师检查的仓库地址与必要账号说明。

八、第七步：创建 `v1.0` Git 标签¶

版本标签可以固定“最终交付对应哪一次代码”，避免后续继续开发后无法找到答辩或验收使用的版本。

1. 创建标签前确认¶

git status
git log --oneline -5
git diff --check

只有下列条件满足时再打标签：

工作区干净；
当前提交已通过构建、测试和部署验证；
测试报告和 README 已更新；
没有未记录的 P0/P1 问题；
准备交付的分支正确。

2. 创建并查看标签¶

# 创建带说明的附注标签
git tag -a v1.0 -m "课程项目最终交付版本"

# 查看标签
git tag

# 查看标签对应提交
git show v1.0

如使用远程仓库：

# 推送当前分支
git push origin main

# 推送标签
git push origin v1.0

如果使用的默认分支不是 main，请替换为实际分支名。

3. 版本标签不代表永远不改¶

v1.0 是当前课程交付的稳定基线。交付后仍可继续开发：

v1.0：课程最终交付版本
→ 修复小问题：v1.0.1
→ 增加兼容功能：v1.1
→ 毕业设计或竞赛重构：v2.0

但任何后续修改都不应覆盖或破坏已经用于验收的 v1.0 标签。

九、README 最小模板¶

将以下模板复制到项目根目录的 README.md，并替换全部占位内容。

# 【项目名称】

> 【一句话说明：为谁解决什么问题。】

## 1. 项目简介

【说明项目背景、目标用户和核心问题。】

## 2. 核心功能

| 角色 | 功能 |
| :--- | :--- |
| 【角色】 | 【功能】 |
| 【角色】 | 【功能】 |

核心流程：

```text
【角色 A 操作】
→ 【角色 B 处理】
→ 【系统校验规则】
→ 【最终结果】

3. 技术栈¶

后端：【填写】
前端：【填写】
数据库：【填写】
部署：【填写】

4. 项目结构¶

1	`【按实际项目填写核心目录】`

5. 环境要求¶

工具	版本
JDK	【填写】
数据库	【填写】
Node / Tomcat / Docker	【填写】

6. 快速启动¶

6.1 初始化数据库¶

1	`【填写实际命令】`

6.2 本地启动¶

1	`【填写实际命令或 IDEA/smart-tomcat 操作】`

6.3 Docker 部署（如适用）¶

1	`【填写实际命令】`

访问地址：【填写】

7. 测试账号¶

角色	账号	密码	用途
管理员	【填写】	【仅测试账号】	【填写】
普通用户	【填写】	【仅测试账号】	【填写】

8. 测试与部署¶

测试报告：【文档位置或链接】
部署说明：【文档位置或链接】
项目版本：v1.0

9. 系统截图¶

【插入 3—6 张核心流程截图并加说明。】

10. 已知限制与后续计划¶

【填写真实限制】

【填写后续优化方向】

---

## 十、填写最终交付记录模板

将以下内容复制到 `docs/最终交付清单.md` 或课程要求的交付文档中。

```markdown
# 【项目名称】最终交付记录

## 1. 版本信息

| 项目 | 内容 |
| :--- | :--- |
| 项目名称 | 【填写】 |
| 交付版本 | v1.0 |
| Git 分支 | 【填写】 |
| Git 提交 | 【填写】 |
| Git 标签 | v1.0 |
| 仓库地址 | 【填写】 |
| 交付日期 | 【填写】 |

## 2. 交付材料

| 材料 | 位置或链接 | 完成情况 |
| :--- | :--- | :--- |
| 项目源代码 | 【填写】 | 已完成/待补充 |
| 项目 README | 【填写】 | 已完成/待补充 |
| 数据库脚本 | 【填写】 | 已完成/待补充 |
| 需求分析说明书 | 【填写】 | 已完成/待补充 |
| 系统设计说明书 | 【填写】 | 已完成/待补充 |
| 测试计划与测试用例 | 【填写】 | 已完成/待补充 |
| 缺陷与回归记录 | 【填写】 | 已完成/待补充 |
| 测试报告 | 【填写】 | 已完成/待补充 |
| 部署说明与验证记录 | 【填写】 | 已完成/待补充 |
| 系统截图或演示视频 | 【填写】 | 已完成/待补充 |

## 3. 质量结论

- 核心流程：【通过 / 不通过，说明】
- 登录与权限：【通过 / 不通过，说明】
- 测试结论：【通过 / 有条件通过 / 不通过】
- 部署结论：【通过 / 有条件通过 / 不通过】
- P0 缺陷：【数量与状态】
- P1 未解决问题：【填写；没有则写无】
- 已知限制：【填写】

## 4. 交付确认

- [ ] 源代码、脚本和配置模板完整
- [ ] README 可指导他人启动项目
- [ ] 测试与部署证据可追溯
- [ ] 敏感信息未提交
- [ ] 当前提交已打 `v1.0` 标签
- [ ] 仓库地址和访问范围已确认

十一、提交前自查¶

本节小结¶

最终交付的核心不是“文件越多越好”，而是让成果相互一致、可被他人验证：

冻结稳定版本 → 写清 README → 汇总测试与部署证据 → 清理敏感和无关文件 → 对照交付清单 → 打 v1.0 标签 → 提供可访问、可复现的项目入口。

完成本节后，你已经拥有一个可运行、可部署、可测试、可说明的课程项目 v1.0。下一篇将围绕项目展示、答辩与成长复盘，帮助你把项目成果讲清楚、展示好，并转化为毕业设计、竞赛或求职经历。

返回第五篇：测试、部署与成果交付返回上一节：部署验证