VibeCoding 实战：用 Qoder 从零开发 Java Spring Boot WMS 系统（四）
第3章 系统设计：架构、数据库、API 三件套
本章目标：基于第2章的 PRD，用 Qoder 完成三项核心设计产出——① 技术架构与分层设计、② 数据库表结构设计（含可直接执行的建表 SQL）、③ 后端 RESTful API 接口清单。设计好了，第4~8章的编码就是"按图施工"，AI 会跑得又快又稳。
学习目标
- 理解"分层架构"和"模块划分"，能让 AI 画出系统架构图
- 能设计出一份规范、可执行的数据库表结构（DDL）
- 能产出统一的 RESTful API 接口清单，作为前后端契约
- 养成"设计先行、评审后再编码"的工程习惯
3.0 开始前的准备：把 PRD 变成 AI 的"记忆"
本章所有提示词都建立在一个前提上：Qoder 已经知道你的需求。有两种方式确保这点：
- 方式A（推荐）：每次对话时用
#引用第2章产出的docs/需求规格说明书.md，让 AI 基于它工作。 - 方式B：让 AI 读完 PRD 后，把关键约定"记住"（写入项目记忆/Memory），后续章节自动带出。
先在对话框输入这句，建立本章的工作基线：
请先阅读我工作区里的 docs/需求规格说明书.md（用 # 引用它）。
读完后，用 3~5 句话向我复述：系统的模块划分、核心业务对象、以及 M1 要做的功能范围。
确认你理解正确后我们再开始系统设计。这一轮不要写代码、不要生成文件。
看到复述正确，再继续。
3.1 技术架构与分层设计
提示词
基于 PRD，为我们的「轻量版 WMS」设计技术架构，要求：
1. 技术选型（我已定，你别改，只需补充理由）：
- 后端：Java 17 + Spring Boot 3 + MyBatis-Plus + MySQL 8 + JWT
- 前端：Vue 3 + Element Plus + Vite（管理后台）
- 部署：Docker Compose（Nginx + 后端 + MySQL）
2. 后端采用经典分层：Controller / Service / Mapper / Entity / DTO(QueryDTO、FormVO、ResultVO)
请说明每一层的职责，以及统一返回体 Result<T>、全局异常处理、参数校验放在哪层。
3. 按业务模块划分包结构：auth（登录）、basedata（仓库/库区/储位/商品）、
inbound（入库）、outbound（出库）、inventory（库存/流水）、stocktake（盘点）。
给出目录树（package 结构）示例。
4. 画一张系统架构图（用 Mermaid）。
把以上设计写入文件 docs/系统设计.md 的「## 1 技术架构」章节。不要写业务代码。
预期结果
docs/系统设计.md出现「技术架构」章节，含分层职责说明、包结构目录树、Mermaid 架构图。- 后端包结构大致是：
com.yjoffer.miniwms
├── common // Result<T>、异常、工具、基类
├── config // MyBatis-Plus、Web、安全配置
├── auth // 登录鉴权
├── basedata // 仓库/库区/储位/商品
├── inbound // 入库
├── outbound // 出库
├── inventory // 库存/流水
└── stocktake // 盘点
注意事项
- ⚠️ 技术选型这一章由你拍板，别让 AI 自由发挥。教学项目要"可控、够用"，避免它给你上微服务、Redis、MQ 把复杂度拉满。想加进阶组件，放到第10章"进阶方向"。
- 💡 如果 AI 给的分层里混用了
VO/DTO/PO又没说明，追一句："请明确定义 Entity / DTO / VO 各自用途和转换位置，避免后面每个模块各写一套。"
3.2 数据库设计（本章重点）
数据库是整个 WMS 的骨架，值得花最多时间。先让 AI 出表结构设计（字段、类型、关系、索引），评审通过后再让它生成可执行 DDL。 分两步，是因为一步到位时字段错了改起来更麻烦。
第一步：表结构设计
提示词
基于 PRD 的业务对象，为 WMS 设计数据库表结构（MySQL 8，utf8mb4，所有表带 create_time/update_time/deleted 逻辑删除字段）。
请覆盖这些表（命名用 wms_ 前缀）：
- wms_user 用户（登录，含角色字段 admin/warehouse）
- wms_warehouse 仓库
- wms_zone 库区（属于仓库）
- wms_location 储位（属于库区，编码唯一，如 A-01-02）
- wms_category 商品分类
- wms_goods 商品（编码、名称、规格、单位、分类外键）
- wms_inventory 库存（goods_id + location_id 唯一，记录数量）
- wms_inventory_log 库存流水（每次变动一条：商品、储位、变动类型、变动数量、变动前后数量、关联单号）
- wms_inbound_order 入库单主表（单号、仓库、状态、制单人、审核人、时间）
- wms_inbound_item 入库单明细（商品、计划数量、已入库数量）
- wms_inbound_record 入库执行记录（入库单、商品、储位、实际入库数量）
- wms_outbound_order 出库单主表
- wms_outbound_item 出库单明细
- wms_outbound_record 出库执行记录（拣货：商品、储位、实际拣货数量）
- wms_stocktake_order 盘点单主表 / wms_stocktake_item 盘点明细（M2 可先建表）
对每张表，用表格输出：字段名 / 类型 / 是否必填 / 默认值 / 说明 / 索引。
并单独说明：
1. 单据状态字段的取值枚举（草稿/待审核/已审核/已完成/已作废 等）
2. 表与表之间的关系（主外键），用文字或 Mermaid ER 图表达
3. 库存变动的一致性：为什么出库要防超卖、加什么约束/校验
先只输出设计，写入 docs/系统设计.md 的「## 2 数据库设计」章节，不要生成 SQL。
评审清单（务必人工核对，这是最容易埋坑的地方）
拿到设计后，逐条检查：
- 库存唯一性：
wms_inventory是否有(goods_id, location_id)唯一索引？没有会出现同商品同储位多条库存。 - 流水完整性：库存流水是否记录了"变动前数量、变动后数量、关联单号"？少了就没法对账。
- 单据明细与执行记录分离：入库"计划数量"在 item，实际"入库动作"在 record——这个分离决定了能否"部分入库"。确认 AI 没把两者混在一张表。
- 状态枚举清晰：单据状态取值是否和 PRD 的流程一致（草稿→待审核→已审核→已完成）。
- 防超卖：出库扣库存是否有校验（可用库存 ≥ 出库数量）。看 AI 的方案说明是否合理。
- 逻辑删除：主数据（商品/仓库）用了
deleted，但库存流水不应被删除——确认 AI 没给流水表加逻辑删除。
对不满意的点，直接说："第X张表的Y字段改成…… / 库存流水表请去掉 deleted 字段"，让它改到通过为止。
第二步：生成可执行 DDL
设计评审通过后：
提示词
数据库表结构设计已确认。现在请生成完整可执行的 MySQL 8 建表脚本：
- 文件写到 db/schema.sql
- 包含 CREATE DATABASE（库名 mini_wms，字符集 utf8mb4）+ USE + 所有 CREATE TABLE
- 每个字段带中文 COMMENT，主键、索引、唯一约束齐全，引擎 InnoDB
- 末尾追加一段初始化数据 db/data.sql 或在本文件里 INSERT：
1 个管理员账号（用户名 admin，密码先用明文占位并注释说明后续章节会改为 BCrypt 加密）、
1 个仓库、2 个库区、4 个储位、2 个分类、3 个示例商品
- 生成后，用一句话告诉我如何在命令行导入这个 SQL
注意：密码字段、外键是否真建（教学项目可用逻辑外键不建物理外键，请说明你的选择）。
预期结果
- 工作区出现
db/schema.sql（和可选的db/data.sql） - 文件开头有建库语句，每张表结构完整、带注释
立刻验证 SQL 能跑通
别把没验证过的 SQL 带到下一章。 打开终端，实际导入一次：
mysql -uroot -p < db/schema.sql
- 报错就把错误原文贴回给 Qoder："这段 SQL 导入报错：
<粘贴错误>，请修正 schema.sql"。 - 成功后，用
SHOW TABLES;确认表都建出来了，抽查wms_inventory的唯一索引：
SHOW INDEX FROM wms_inventory;
注意事项
- ⚠️ AI 生成的 SQL 有语法错误是常态，尤其是索引/约束写法。不要假设它一定对，导入验证这一步不能省。
- 💡 让 AI 用"逻辑外键（不建物理外键）"通常更省事，避免测试数据插入顺序导致的约束报错；本教程推荐逻辑外键。
3.3 RESTful API 接口设计
接口是前后端的契约，也是第5~8章每个模块的"任务清单"。先出一份统一规范，后面每个模块照着填。
提示词
基于 PRD 和刚设计的数据库，为 WMS 设计后端 RESTful API 接口清单，要求：
1. 统一规范先定义清楚：
- 基础路径 /api，模块前缀（/api/auth、/api/goods、/api/inbound ...）
- 统一返回体 Result<T>：{ code, message, data }
- 分页统一用查询参数 pageNum/pageSize，返回 { total, list }
- 命名风格：RESTful（GET 查、POST 增/复杂查、PUT 改、DELETE 删）
2. 按模块列出接口清单，每行：接口名 / 方法 / 路径 / 入参要点 / 出参要点 / 所属里程碑(M1/M2)。
重点覆盖：登录、商品/仓库/储位的增删改查+分页、入库单(创建/提交审核/审核/执行入库/分页详情)、
出库单(创建/审核/拣货执行/分页详情)、库存查询、库存流水查询。
3. 挑 2 个最复杂的接口（执行入库、出库拣货）给出详细示例：
请求 JSON 结构 + 成功/失败响应 JSON 结构。
写入 docs/系统设计.md 的「## 3 API 设计」章节，并额外单独生成一份 docs/api.md 接口表，
方便第4~8章开发时引用。不要写后端代码。
预期结果
docs/api.md有一份按模块整理的接口表格，标注了 M1/M2。- 执行入库、出库拣货两个接口有完整请求/响应 JSON 示例。
评审要点
- 状态流转接口是否齐全：入库单不能只有"创建"，要有"提交/审核/执行"这几个动作接口。
- 分页与查询条件：列表接口是否支持按状态、单号、时间筛选。
- 入参校验：数量字段是否明确"必须为正整数"等约束（第4章会在全局做参数校验）。
3.4 把设计"钉死"：写一份项目规则（Rules）
本章产出了三份文档（PRD、系统设计、api.md）。为了让第4~8章每次生成代码都自动遵守这些约定（包名、返回体、字段规范），我们写一份项目级规则文件，Qoder 会在后续编码时读取它。
提示词
请把本项目的关键工程约定，整理成一份规则文件，写入 .qoder/rules.md（若该路径不被识别，
就同时写一份 docs/开发规范.md 作为等效备份）。内容包含：
- 包名根：com.yjoffer.miniwms；模块分包见 docs/系统设计.md
- 后端分层与各层职责；统一返回体 Result<T>；全局异常处理
- 数据库：表前缀 wms_、逻辑删除字段 deleted、create_time/update_time 必填、逻辑外键
- MyBatis-Plus：主键策略、公共字段自动填充
- API：路径规范、分页参数 pageNum/pageSize、参数校验用 jakarta validation
- 代码风格：关键方法要有中文注释；不引入 PRD 未约定的中间件（Redis/MQ）除非明确要求
- 前端：Vue3 <script setup> + Element Plus，接口统一封装在 src/api 下
写完后告诉我文件路径，后续开发请始终以这份规则和 docs/ 下三份文档为准。
注意事项
- 💡 不同 Qoder 版本，项目规则的存放位置/格式可能不同（有的用
.qoder/下规则、有的用AGENTS.md、有的用 Memory 记忆）。找不到确切位置时，让 AI 自己说："你的项目规则应该放在哪个文件？请写到正确位置。" 保底用docs/开发规范.md也能通过每章引用达到同样效果。 - ⚠️ 规则不是越多越好，聚焦"每个模块都必须统一的东西"（包名、返回体、字段规范），业务细节留给各章再讲。
本章检查清单
- [ ]
docs/系统设计.md含技术架构（分层 + 包结构 + 架构图） - [ ] 数据库表结构设计完成并通过"评审清单"6 项核对
- [ ]
db/schema.sql已生成，且本地实际导入成功 - [ ]
docs/api.md接口清单产出，复杂接口有 JSON 示例 - [ ] 项目规则文件（
.qoder/rules.md或docs/开发规范.md）已写入
设计阶段完成。带着这三份文档进入 第4章 工程脚手架，我们开始"按图施工"。
常见问题
Q：数据库一定要 15 张表吗？能不能简化？
A：可以。如果你想更快跑通，M1 可先合并：去掉 zone（库区，储位直接挂仓库）、去掉盘点两表（M2 再说）。但"库存按商品+储位、流水单独记录、单据主表+明细+执行记录"这三个结构强烈建议保留——它们是 WMS 的精髓，砍了项目就没味道了。
Q：AI 生成了物理外键，导入时报外键约束错误怎么办？ A：这是初始化数据插入顺序问题。让 AI："改用逻辑外键（不建 FOREIGN KEY 约束），仅保留索引。" 然后重新导入。
Q：设计文档和后面代码不一致了怎么办？
A：以"先改文档、再改代码"为原则。文档是唯一事实来源，发现要改设计时，回到 docs/ 更新，再让 AI 按新设计改代码。这能训练你"设计驱动开发"的习惯。