跳转至

4.2 改造工程：让脚手架匹配项目设计

保留能用的工程底座，逐步换成自己的项目

改造脚手架，不是把 scaffold 全局替换成项目名称

脚手架已经提供登录、权限、统一响应、异常处理和示例模块。真正需要改造的是项目说明、业务数据、模块规划和页面入口。

如果一开始就批量改包名、删除示例、重写权限或同时生成所有业务代码，项目很容易从“可以运行”变成“到处报错”。正确做法是：先建立设计对应关系，再小步修改，每一步都重新运行。

本节学习目标

根据《需求分析说明书》和《系统设计说明书》，把通用脚手架整理成符合自己项目的开发骨架：明确项目身份、整理文档、建立业务数据库、规划模块和页面，同时保留能够运行的登录与示例功能。

返回上一节：启动项目 返回第四篇导读 进入下一节：开发基础

🎯 本节完成后，你要交付

成果 要求
设计—工程对应表 说明角色、模块、页面、接口和数据准备放在哪里
项目身份信息 项目名称、简介、仓库说明和启动文档已经更新
项目开发文档 需求和设计成果已经整理到脚手架的 docs/ 目录
业务数据库骨架 使用增量脚本创建项目核心表，不破坏脚手架基础数据
项目级 AGENTS.md 在原规则基础上加入自己的业务范围、术语和禁止事项
改造验证记录 登录、示例查询、数据库和项目启动仍然正常

本节只搭建自己的项目骨架，不要求完成完整业务模块。下一节再选择一个功能，按照“数据库—后端—接口—页面—测试”逐步开发。

📄 第一步：准备设计基线

开始修改代码前，先把第三篇形成的材料放在手边：

  • 《项目选题立项书》；
  • 《需求分析说明书》；
  • 《系统设计说明书》；
  • 页面原型或页面流程图；
  • E-R 图、数据字典和数据库脚本；
  • 接口清单、权限矩阵和状态说明；
  • 系统设计评审记录。

先检查以下问题：

  • 项目名称和核心用户已经确认；
  • 本期必做、选做和不做内容已经区分；
  • 至少有一条完整核心业务流程；
  • 角色和数据权限基本明确；
  • 核心数据表和关系基本明确；
  • 技术路线与当前脚手架一致；
  • 阻断开发的设计问题已经处理。

设计还没定，不要让代码替你做决定

如果角色、业务流程或核心数据表仍然互相矛盾，应先返回第三篇修改设计。把不确定需求直接写进代码，只会让页面、接口和数据库一起返工。

🗺️ 第二步：建立设计到工程的对应关系

不要马上创建文件。先说明每项设计准备落到工程中的什么位置。

角色与权限

设计内容 脚手架已有能力 项目需要补充
登录用户 JWT 或 Session 登录 保留或调整用户字段
管理员 已有管理员示例 确认管理员能管理哪些数据
项目业务角色 暂无 明确角色名称、权限和数据范围

业务模块

模块编号 模块名称 对应需求 后端位置 页面位置 数据表 开发顺序
MOD-01 【填写】 FR-* 【填写】 【填写】 【填写】 1
MOD-02 【填写】 FR-* 【填写】 【填写】 【填写】 2

两条技术路线可以这样对应：

1
2
3
4
5
业务模块
→ backend/.../module/<业务名>/
→ frontend/src/views/<业务名>/
→ frontend/src/api/<业务名>.js
→ frontend/src/router/

1
2
3
4
5
业务模块
→ controller / service / dao / entity / dto
→ src/main/webapp/<业务名>/
→ src/main/webapp/js/
→ Filter 或业务代码中的权限检查

先完成一个模块，不要把所有模块同时建成空壳

对应表的作用是确定方向和顺序。真正创建代码时，先选择第一个业务模块，完成并验证后再继续下一个。

🏷️ 第三步：更新项目身份

先修改用户和评审者能够看到的信息，不急着改底层包名。

建议更新：

  • 根目录 README.md 中的项目名称和简介；
  • docs/04-项目README.md 中的项目背景、用户和运行方式；
  • 前端页面标题、首页说明和浏览器标题；
  • 后端 Maven 项目的 name 和 description；
  • Servlet 工程的展示名称和说明；
  • 数据库名称、接口集合名称和部署说明；
  • 仓库主页简介。

项目简介示例

1
2
3
4
5
6
7
# 校园报修管理系统

面向学生、维修人员和管理员的校园报修系统。
学生可以提交并查看报修，管理员负责分配任务，
维修人员处理后由学生确认结果。

当前阶段：项目骨架已运行，正在开发第一个业务模块。

暂时不要做的全局重命名

  • 不要一次修改所有 Java 包名；
  • 不要批量替换公共类和配置类中的 scaffold；
  • 不要修改脚手架统一响应和异常处理结构；
  • 不要删除登录、权限和 DemoItem 示例；
  • 不要同时更换框架、依赖版本和数据库方案。

包名和制品名称是否需要调整，可以根据教师要求决定。课程项目首先保证能够运行和解释，不以“所有地方都换了名字”作为验收标准。

📚 第四步：整理项目文档与规则

脚手架的 docs/ 目录已经提供文档位置。把前面完成的成果整理进去：

1
2
3
4
5
docs/
├── 01-需求分析说明书.md
├── 02-系统设计说明书.md
├── 03-测试报告.md
└── 04-项目README.md

本节重点更新：

  • 01-需求分析说明书.md：放入已经评审的需求版本；
  • 02-系统设计说明书.md：放入当前设计基线；
  • 04-项目README.md：写清项目简介、技术路线和当前启动方式；
  • 03-测试报告.md：暂时保留结构，后续记录真实测试结果。

不要只把外部文档路径写进去，也不要继续保留全部“待补充”。项目仓库中的开发者应该能够直接找到当前需求和设计依据。

改造项目级 AGENTS.md

保留脚手架原有技术栈、目录约定和改动禁区，再补充自己的项目事实：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 项目 AI 协作补充规则

## 项目范围
- 项目名称：
- 核心用户：
- 核心业务流程：
- 本期必做：
- 本期不做：

## 业务术语
- 【术语】：【唯一含义】
- 【状态】：【允许的取值】

## 开发顺序
1. 【第一个模块】
2. 【第二个模块】
3. 【核心业务流程】

## 项目红线
- 不增加需求文档之外的功能；
- 不修改已确认的业务状态和权限规则；
- 不信任前端提交的当前用户身份；
- 不提交密码、密钥和本机配置；
- 修改数据库前先说明对已有数据和代码的影响。

AGENTS.md 不是项目介绍

只写会影响 AI 修改代码的事实、规则和禁区。不要复制整份需求说明书，也不要写“代码要优雅”这类无法执行的空话。

🗃️ 第五步：建立项目业务数据库

脚手架数据库只包含用户和示例数据，不能直接代替你的数据库设计。

采用增量方式

保留脚手架已有表，先添加自己的核心业务表：

1
2
3
4
5
脚手架用户与权限数据
        +
项目核心业务表
        +
必要的初始化数据

等第一个业务模块已经成功运行，再决定是否删除 demo_item 示例表和代码。

不要修改已经发布的：

1
backend/src/main/resources/db/migration/V1__init_schema.sql

新建后续迁移文件，例如：

1
2
V2__create_project_tables.sql
V3__insert_project_seed_data.sql

文件编号只能递增，不要重复使用已经执行过的版本。

可以在 sql/ 下新增项目脚本，例如：

1
2
3
4
sql/
├── init.sql
├── project-schema.sql
└── project-seed.sql

先在空数据库或测试数据库执行新增脚本，确认没有依赖手工修改才能运行。

数据库改造检查

  • 表名、字段名与《系统设计说明书》一致；
  • 每张表都有明确主键；
  • 必填、唯一和关联规则有相应约束；
  • 状态字段的取值已经说明；
  • 初始化数据不含真实个人信息；
  • SQL 可以重复从空环境完成初始化；
  • 没有把本机数据库密码写进正式脚本；
  • 修改后登录和示例功能仍然可用。

本节只要求核心表能够创建，不要求马上完成所有业务接口。

🧩 第六步：规划第一个业务模块

从项目核心流程中选择一个范围小、容易验证的入口模块。

适合作为第一个模块的功能：

  • 图书查询；
  • 活动发布或活动查询；
  • 商品管理；
  • 报修提交；
  • 预约项目管理；
  • 个人信息查看。

暂时不适合作为第一个任务：

  • 一次实现整条跨角色流程；
  • 同时开发多个相互依赖的模块；
  • 接入支付、大模型、地图或短信；
  • 重写登录和权限基础设施；
  • 实现复杂统计和推荐算法。

第一模块任务卡

项目 内容
模块名称 【填写】
对应需求 FR-*
使用角色 【填写】
需要的数据表 【填写】
后端入口 【计划位置】
页面入口 【计划位置】
成功结果 【可观察结果】
失败或边界情况 【至少一个】
验证方式 页面 / 接口 / 数据库

这一任务卡会成为下一节的开发依据。内容不确定时回到需求和设计文档，不让 AI 自行补业务规则。

🤖 第七步：让 AI 辅助制定改造计划

先让 AI 阅读和分析，不要直接下达“把脚手架改成我的项目”的模糊命令。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
请先完整阅读项目根目录的 AGENTS.md、README、
docs/01-需求分析说明书.md、docs/02-系统设计说明书.md，
以及脚手架目录、数据库脚本和 DemoItem 示例。

当前任务仅是“让脚手架匹配项目设计”，
不要开发完整业务功能，不要删除脚手架示例，
不要修改 AGENTS.md 中列出的基础设施和禁区文件。

请先输出：
1. 项目设计与现有脚手架的对应关系；
2. 可以直接复用的基础能力；
3. 需要新增或调整的文档、配置、数据库和模块位置；
4. 建议的最小改造步骤；
5. 每一步准备修改的文件和验证方式；
6. 仍需人工确认的问题。

没有读取到的目录、接口和业务规则不要猜测。

审核计划时重点检查：

  • 是否保留当前可运行基线；
  • 是否修改了脚手架禁区；
  • 是否擅自增加需求之外的功能；
  • 是否准备一次修改大量文件；
  • 是否覆盖数据库、文档和验证；
  • 是否明确每一步如何回退和检查。

确认计划后，一次只执行一个小步骤。例如先更新项目说明并重新启动，再添加数据库脚本并验证，不要把所有改造一次交给 AI。

✅ 第八步：重新运行并检查改造成果

改造完成后，按照上一节的启动方式重新运行项目。

至少验证：

  1. 项目能够编译或构建；
  2. 数据库能够从脚本初始化；
  3. 后端或 Servlet 应用能够启动；
  4. 前端或静态页面能够访问；
  5. 默认管理员仍能登录；
  6. 当前用户身份能够正常获取；
  7. 示例查询和数据操作仍然可用；
  8. 新增业务表已经创建；
  9. README 中的启动方式与实际一致；
  10. Git 中没有密码、密钥、依赖缓存和构建产物。

改造记录

改造内容 修改位置 验证方法 结果
项目名称和简介 【填写】 查看 README 和页面 通过 / 未通过
项目文档 docs/ 检查版本和内容 通过 / 未通过
业务数据库 sql/ 或迁移文件 空库执行脚本 通过 / 未通过
项目规则 AGENTS.md 检查范围和禁区 通过 / 未通过
原有功能 登录和 DemoItem 浏览器实际操作 通过 / 未通过

改造后不能运行，就不要继续开发新功能

先查看 git diff，定位本节修改了哪些文件，再根据启动日志逐项排查。不要在未恢复运行的情况下继续增加业务代码。

💾 第九步：提交项目骨架版本

先检查改动范围：

1
2
git status
git diff

确认改动只包含项目说明、文档、规则、配置和已经验证的数据库脚本后，再提交：

1
2
git add .
git commit -m "chore: customize scaffold for project"

如果本次改动较多，可以拆成几个容易解释的提交：

1
2
3
docs: add project requirements and design documents
chore: update project identity and development rules
feat: add initial project database schema

不要把尚未运行的批量生成代码混入“项目骨架完成”的提交。

✅ 本节验收清单

  • 已准备最新的需求和系统设计材料；
  • 已建立设计到工程的对应表；
  • 项目名称、简介和 README 已更新；
  • docs/ 中包含当前需求与设计基线；
  • AGENTS.md 保留原有技术规则并补充项目事实；
  • 没有修改脚手架明确规定的基础设施禁区；
  • 已使用增量脚本建立核心业务表；
  • Spring Boot 路线没有覆盖已发布的 V1 迁移；
  • 示例模块仍然保留，可供下一节参考；
  • 已确定第一个业务模块及其验收方式；
  • 改造后项目能够重新启动；
  • 登录、权限和示例数据操作仍然正常；
  • 项目文档和启动方式与实际一致；
  • 已创建范围清楚的 Git 提交。

📝 总结

  • 先映射，再改代码：把需求、模块、页面和数据对应到工程位置。
  • 保留工程底座：登录、权限、统一响应和示例模块是可以复用的基础。
  • 使用增量改造：新增迁移和项目脚本，不破坏已经验证的初始版本。
  • 项目规则要真实：让 AGENTS.md 反映当前范围、术语、顺序和禁区。
  • 每一步重新运行：改造后的项目仍能登录和操作，才进入业务开发。

返回上一节：启动项目 进入下一节：开发基础