AI Spec模式开发：基于OpenSpec订单库存物流系统

前置：OpenSpec规范驱动开发介绍

0.1 OpenSpec核心定义

OpenSpec是标准化规范驱动开发（Spec-Driven Development, SDD） 的落地落地标准，核心思想：先定规范、再写文档、最后生成代码，杜绝先写代码后补文档、接口不一致、前后端联调扯皮、业务逻辑模糊等开发痛点。区别于传统敏捷开发（先编码后补设计），OpenSpec强制以标准化设计文档为唯一数据源，所有代码、接口、数据库表、枚举、DTO全部由设计文档统一约束，保证前后端、测试、开发三方口径完全一致。

0.2 OpenSpec开发全流程（本项目落地流程）

1. 需求梳理：明确下单、库存扣减、物流轨迹、订单状态变更核心业务，剔除权限、支付等无关功能

1. 编写SDD详细设计文档：统一数据库表、枚举、状态机、接口入参出参、业务伪代码、异常规则（本文档即为最终唯一规范）

1. 规范校验：校验状态流转闭环、接口参数完整性、数据库字段和实体类一一对应、业务幂等规则

1. 一键代码生成：依托完整SDD规范，逆向生成后端Controller/Service/Mapper/Entity/DTO、前端Vue接口请求文件、页面基础模板

1. 少量业务补全：仅补充复杂业务逻辑代码，无需手写基础CRUD、接口定义、实体类

1. 测试联调：基于SDD内置测试用例，直接开展接口测试、前端页面联调

0.3 OpenSpec对比传统开发优势

• 消除前后端接口分歧：接口地址、请求方式、入参出参全部固化在SDD，无需口头沟通

• 开发效率提升60%以上：基础代码全自动生成，开发者只聚焦核心业务逻辑

• 文档和代码永远同步：SDD是唯一源头，代码修改必须同步更新设计文档

• 新人上手零成本：直接阅读SDD即可看懂全量业务、表结构、接口逻辑，无需翻阅代码

0.4 本项目OpenSpec落地核心约束

本项目100%以当前SDD文档为唯一开发规范，所有代码必须严格遵循文档内：包结构、接口定义、状态枚举、数据库字段、业务伪代码、事务规则，禁止私自新增接口、修改状态流转、新增数据表字段。

文档版本说明

|------|------------|-------|----------------------------------------------------------------------------|
| 版本号 | 修改日期 | 修改人 | 修改内容 |
| V1.0 | 2026-06-20 | 开发工程师 | 初始版本，完整输出可直接编码的详细设计，包含OpenSpec规范说明、分层代码结构、全部接口、状态机、枚举、SQL、入参出参、测试用例、代码生成方案 |

文档版本说明

|------|------------|-------|--------------------------------------------------------|
| 版本号 | 修改日期 | 修改人 | 修改内容 |
| V1.0 | 2026-06-20 | 开发工程师 | 初始版本，完整输出可直接编码的详细设计，包含分层代码结构、全部接口、状态机、枚举、SQL、入参出参、测试用例 |

1 引言

1.1 文档目的

本SDD详细设计文档用于指导开发人员直接编写前后端代码，明确系统每一层代码结构、方法逻辑、接口入参出参、数据库字段、状态流转、业务规则、异常定义，开发人员无需额外需求评审、无需补充设计，对照本文档即可完成全部编码。

1.2 项目范围

• 包含模块：商品模块、订单模块、库存扣减模块、物流模块、物流轨迹模块

• 核心流程：用户下单→库存锁定→订单创建→订单发货→真实库存扣减→物流状态逐级变更→订单完成

• 页面功能：订单列表、创建订单、取消订单、物流跟踪、物流状态更新

• 剔除内容：无登录权限、无支付流程、无消息推送、无分布式事务、仅本地基础业务流转

1.3 运行环境

• 后端：JDK17 + SpringBoot3.2.5 + Maven3.8 + Mybatis-Plus3.5.3.1 + MySQL8.0

• 前端：Node18 + Vite + Vue3 + Element Plus + Axios

• 数据库：MySQL8.0，字符集utf8mb4

2 总体设计（极简，仅代码相关）

2.1 系统架构

前后端分离架构，后端标准三层架构：Controller(请求接收) → Service(业务逻辑) → Mapper(数据库操作)，全局统一返回结果、全局异常捕获。

2.2 核心业务总流程（代码对照版）

1. 前端提交下单请求，传入商品ID、购买数量、收货地址

1. 后端校验商品库存是否充足

1. 锁定库存（冻结库存，不可售卖）

1. 生成唯一订单号，创建订单主表、订单明细表

1. 订单状态：已创建 → 待发货

1. 后台发起发货：生成物流单号，创建物流单

1. 真实扣减库存，释放锁定库存

1. 物流状态逐级变更：待揽件→已揽件→运输中→已送达→已签收

1. 物流签收后，订单自动变更为已完成

1. 支持取消订单：仅待发货订单可取消，取消后库存自动回滚

2.3 全局公共设计（所有代码统一规范）

2.3.1 统一返回实体 R.java

全局所有接口固定返回格式，禁止自定义返回值

|------------------------------------------------|
| java code：200成功 / 500业务异常 msg：提示信息 data：业务返回数据 |

2.3.2 全局异常处理

• 自定义业务异常：BusinessException，手动抛出业务错误

• 全局异常拦截：统一封装为R返回前端，不返回原生报错堆栈

2.3.3 全局时间规范

所有数据库时间字段：create_time、update_time，自动填充，后端使用LocalDateTime

2.3.4 逻辑删除

全部数据表统一逻辑删除：is_deleted 0未删除 1已删除，Mybatis-Plus自动接管

3 数据库详细设计（可直接复制执行SQL）

共6张业务表，下方为完整建表语句+字段说明，开发直接执行即可

3.1 数据库初始化SQL

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sql CREATE DATABASE IF NOT EXISTS order_demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE order_demo; -- 1.商品表 CREATE TABLE products ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键id', spu_name VARCHAR(100) NOT NULL COMMENT '商品名称', spu_value VARCHAR(100) NOT NULL COMMENT '商品规格', spu_price DECIMAL(10,2) NOT NULL COMMENT '商品单价', product_sales INT DEFAULT 0 COMMENT '销量', state TINYINT DEFAULT 0 COMMENT '0上架1下架', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品表'; -- 2.库存表（核心：锁定库存+真实库存，乐观锁防超卖） CREATE TABLE inventory ( id BIGINT AUTO_INCREMENT PRIMARY KEY, product_id BIGINT NOT NULL COMMENT '关联商品id', stock_num INT NOT NULL DEFAULT 0 COMMENT '真实可售库存', locked_stock INT NOT NULL DEFAULT 0 COMMENT '锁定库存（下单冻结）', version INT DEFAULT 0 COMMENT '乐观锁版本号', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='库存表'; -- 3.订单主表 CREATE TABLE orders ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(32) NOT NULL UNIQUE COMMENT '唯一订单号', user_id BIGINT NOT NULL COMMENT '用户id', total_amount DECIMAL(10,2) NOT NULL COMMENT '订单总金额', status VARCHAR(20) NOT NULL COMMENT '订单状态枚举', delivery_address TEXT NOT NULL COMMENT '收货地址', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单主表'; -- 4.订单明细表 CREATE TABLE order_detail ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_id BIGINT NOT NULL COMMENT '订单id', product_id BIGINT NOT NULL COMMENT '商品id', quantity INT NOT NULL COMMENT '购买数量', price DECIMAL(10,2) NOT NULL COMMENT '下单时单价', total_price DECIMAL(10,2) NOT NULL COMMENT '小计金额', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单明细表'; -- 5.物流单主表 CREATE TABLE logistics_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_id BIGINT NOT NULL UNIQUE COMMENT '关联订单id', tracking_no VARCHAR(50) NOT NULL UNIQUE COMMENT '物流单号', carrier VARCHAR(20) COMMENT '快递公司', status VARCHAR(20) NOT NULL COMMENT '物流状态枚举', estimated_delivery_time DATETIME COMMENT '预计送达时间', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='物流单主表'; -- 6.物流轨迹明细表 CREATE TABLE logistics_trace ( id BIGINT AUTO_INCREMENT PRIMARY KEY, logistics_order_id BIGINT NOT NULL COMMENT '物流单id', trace_time DATETIME NOT NULL COMMENT '轨迹发生时间', status VARCHAR(20) NOT NULL COMMENT '当前轨迹状态', description VARCHAR(255) COMMENT '轨迹描述', location VARCHAR(255) COMMENT '所在地点', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='物流轨迹明细表'; -- 测试初始化数据 INSERT INTO products(spu_name,spu_value,spu_price) VALUES('华为手机','12G+256G',3999.00); INSERT INTO inventory(product_id,stock_num,locked_stock) VALUES(1,100,0); |

3.2 系统全部枚举类（代码直接复制）

3.2.1 订单状态枚举 OrderStatusEnum

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java // 订单全部状态，禁止新增其他状态 public enum OrderStatusEnum { CREATED("已创建"), PAID("待发货"), SHIPPED("已发货"), COMPLETED("已完成"), CANCELLED("已取消"); private final String desc; } |

3.2.2 物流状态枚举 LogisticsStatusEnum

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java // 物流固定流转状态，严格按顺序流转 public enum LogisticsStatusEnum { WAITING_PICKUP("待揽件"), PICKED_UP("已揽件"), IN_TRANSIT("运输中"), DELIVERED("已送达"), SIGNED("已签收"); private final String desc; } |

4 后端工程分层详细设计（包结构+每层代码职责，1:1对照编码）

4.1 后端完整包结构（严格按照此结构建包）

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| text com.orderdemo ├── OrderApplication.java //启动类 ├── config //配置类 │ ├── CorsConfig //跨域配置 │ ├── MybatisPlusConfig //mp配置 │ └── GlobalExceptionConfig //全局异常 ├── controller //控制层：只接收参数、返回结果，无业务逻辑 │ ├── ProductController │ ├── InventoryController │ ├── OrderController │ └── LogisticsController ├── dto //入参、出参实体 │ ├── req //前端请求入参 │ └── resp //后端返回出参 ├── entity //数据库实体，和表一一对应 ├── mapper //数据库DAO层 ├── service //业务层接口 │ └── impl //业务层实现类（核心业务全部写在这里） ├── enums //全部枚举 ├── exception //自定义异常 ├── result //统一返回结果R └── utils //工具类：订单号生成工具 |

4.2 每层代码强制开发规范

1. Controller层：参数校验、接收请求、调用service、返回R结果，禁止写任何业务判断

1. Service层：所有业务判断、库存联动、状态变更、数据组装全部写在这里

1. Mapper层：只做数据库增删改查，禁止业务逻辑

1. 事务说明：创建订单、发货扣库存、取消订单三个方法添加@Transactional本地事务

5 模块详细设计（核心，逐模块方法定义+伪代码）

5.1 商品模块

5.1.1 功能说明

仅提供商品列表查询、商品详情查询，无新增修改删除

5.1.2 接口清单

|-------------------|------|--------|------------------|--------|
| 接口地址 | 请求方式 | 功能 | 入参 | 出参 |
| /product/list | GET | 分页商品列表 | pageNum、pageSize | 分页商品集合 |
| /product/get/{id} | GET | 商品详情 | 商品id | 商品实体信息 |

5.2 库存模块（核心防超卖）

5.2.1 三个核心方法（固定不可修改）

1. lockStock() 锁定库存：下单时调用，真实库存减少，锁定库存增加，防止超卖，乐观锁控制并发

1. confirmStock() 确认扣减库存：发货时调用，清空锁定库存，彻底扣减库存

1. rollbackStock() 库存回滚：取消订单调用，释放锁定库存，恢复可售库存

5.2.2 库存业务伪代码（直接照着写）

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java //锁定库存逻辑 1.根据商品id查询当前库存 2.判断真实库存是否大于等于购买数量，不足直接抛出异常：库存不足 3.执行update：stock_num-数量，locked_stock+数量，version+1（乐观锁） 4.返回锁定结果 //确认扣减逻辑 1.锁定库存-数量 2.真实库存不再变动（已经下单扣减过） //回滚库存逻辑 1.锁定库存-数量 2.真实库存+数量 |

5.2.3 库存接口清单

|---------------------|------|--------|
| 接口地址 | 请求方式 | 功能 |
| /inventory/lock | POST | 锁定库存 |
| /inventory/confirm | POST | 确认扣减库存 |
| /inventory/rollback | POST | 库存回滚 |

5.3 订单模块（核心主流程）

5.3.1 订单状态流转规则（硬性约束，代码必须判断）

• 已创建 → 自动变为待发货（下单成功）

• 待发货 → 已发货（发货生成物流单）

• 已发货 → 已完成（物流签收）

• 仅待发货订单允许取消，其他状态禁止取消订单

5.3.2 创建订单完整业务逻辑（带事务）

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java @Transactional(rollbackFor = Exception.class) public String createOrder(OrderCreateReq req){ //1.调用库存服务锁定库存 boolean lock = inventoryService.lockStock(req.getProductId(),req.getQuantity()); if(!lock){ throw new BusinessException("库存不足，下单失败"); } //2.生成唯一订单号 String orderNo = OrderNoUtil.generateOrderNo(); //3.新增订单主表 //4.新增订单明细表 //5.返回订单号 } |

5.3.3 取消订单业务逻辑

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java @Transactional public Boolean cancelOrder(Long orderId){ //1.查询订单 Order order = orderMapper.selectById(orderId); //2.判断状态：非待发货直接报错 if(!order.getStatus().equals(OrderStatusEnum.PAID.name())){ throw new BusinessException("当前订单不可取消"); } //3.更新订单状态为已取消 //4.调用库存回滚接口 //5.返回结果 } |

5.3.4 订单全部接口

|-------------------------|------|----------|---------------------------|-------------|
| 接口地址 | 请求方式 | 功能 | 入参 | 出参 |
| /order/create | POST | 创建订单（下单） | 商品ID、购买数量、收货地址、用户ID | 订单号、订单基础信息 |
| /order/list | GET | 分页查询订单列表 | pageNum、pageSize、订单状态（可选） | 分页订单数据、商品明细 |
| /order/cancel/{orderId} | PUT | 取消订单 | 订单ID | 取消结果提示 |
| /order/get/{orderId} | GET | 查询订单详情 | 订单ID | 订单全量信息+商品明细 |

5.3.5 订单状态流转状态机图（OpenSpec强制闭环）

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| stateDiagram-v2 \* --> CREATED : 下单请求发起 CREATED --> PAID : 库存锁定成功,订单创建完成 PAID --> SHIPPED : 后台发货,生成物流单 SHIPPED --> COMPLETED : 物流签收完成 PAID --> CANCELLED : 用户取消订单,库存回滚 note right of PAID : 仅待发货状态支持取消订单 note right of SHIPPED : 已发货后不允许取消/回滚库存 |

5.4 物流模块（物流单+物流轨迹核心）

5.4.1 模块功能说明

包含物流单生成、物流状态逐级更新、物流轨迹录入、物流轨迹查询四大功能；物流状态必须单向流转，禁止逆向变更（已签收无法退回运输中），物流签收后自动回调修改订单状态为已完成。

5.4.2 物流业务核心伪代码

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java //1.订单发货-生成物流单 @Transactional public void createLogistics(Long orderId,String carrier){ //1.校验订单必须为待发货状态 Order order = orderMapper.selectById(orderId); if(!OrderStatusEnum.PAID.name().equals(order.getStatus())){ throw new BusinessException("订单状态异常，无法发货"); } //2.生成唯一物流单号 String trackingNo = TrackingNoUtil.generateTrackingNo(); //3.新增物流单，初始状态：待揽件 //4.新增第一条物流轨迹：订单已发货，等待快递揽收 //5.调用库存服务，确认真实扣减库存 //6.修改订单状态：待发货 → 已发货 } //2.更新物流轨迹（逐级变更物流状态） public void updateLogisticsTrace(Long logisticsId,LogisticsStatusEnum status,String desc,String location){ //1.校验物流状态流转合法性，禁止逆向流转 //2.新增一条物流轨迹记录 //3.更新物流单最新状态 //4.如果当前状态为已签收，自动更新订单为已完成 } |

5.4.3 物流模块接口清单

|--------------------------------|------|--------------|--------------------|--------------|
| 接口地址 | 请求方式 | 功能 | 入参 | 出参 |
| /logistics/create | POST | 订单发货，创建物流单 | 订单ID、快递公司 | 物流单号 |
| /logistics/trace/update | POST | 更新物流轨迹 | 物流单ID、物流状态、轨迹描述、地点 | 更新结果 |
| /logistics/trace/get/{orderId} | GET | 根据订单查询物流全程轨迹 | 订单ID | 物流单信息+全量轨迹列表 |

6 全量DTO入参出参完整定义（可直接复制代码）

6.1 前端请求入参DTO（dto.req）

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java //创建订单入参 @Data public class OrderCreateReq { //用户ID private Long userId; //商品ID private Long productId; //购买数量 private Integer quantity; //收货地址 private String deliveryAddress; } //分页查询订单入参 @Data public class OrderPageReq { private Long userId; private Integer pageNum; private Integer pageSize; //可选：订单状态筛选 private String orderStatus; } //物流轨迹更新入参 @Data public class LogisticsTraceUpdateReq { private Long logisticsOrderId; //物流状态枚举值 private String logisticsStatus; //轨迹描述 private String description; //当前地点 private String location; } |

6.2 后端返回出参DTO（dto.resp）

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java //订单分页返回 @Data public class OrderPageResp { private Long id; private String orderNo; private String status; private String statusDesc; private BigDecimal totalAmount; private LocalDateTime createTime; //关联商品名称 private String productName; private Integer quantity; } //物流轨迹返回 @Data public class LogisticsTraceResp { private String trackingNo; private String carrier; private String currentStatus; //全量轨迹时间线 private List<TraceItemResp> traceList; } //轨迹明细 @Data public class TraceItemResp { private LocalDateTime traceTime; private String status; private String description; private String location; } |

7 全局公共基础类完整代码（直接复制生成）

7.1 统一返回结果 R.java

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java @Data public class R<T> { private Integer code; private String msg; private T data; //成功返回 public static <T> R<T> ok(T data){ R<T> r = new R<>(); r.setCode(200); r.setMsg("请求成功"); r.setData(data); return r; } //失败返回 public static <T> R<T> fail(String msg){ R<T> r = new R<>(); r.setCode(500); r.setMsg(msg); return r; } } |

7.2 自定义业务异常 BusinessException.java

|-----------------------------------------------------------------------------------------------------------------------------|
| java public class BusinessException extends RuntimeException{ public BusinessException(String message){ super(message); } } |

7.3 全局异常处理器 GlobalExceptionConfig.java

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| java @RestControllerAdvice public class GlobalExceptionConfig { //捕获自定义业务异常 @ExceptionHandler(BusinessException.class) public R<Void> businessException(BusinessException e){ return R.fail(e.getMessage()); } } |

8 基于SDD规范 一键生成前后端代码方案（OpenSpec核心落地步骤）

依托本文完整SDD文档，无需手动编写基础代码，使用MyBatis Generator + Vue代码生成器，以SDD为唯一数据源一键生成全量代码，步骤如下：

8.1 后端SpringBoot3代码生成（MyBatis Generator）

1. 导入SDD中提供的MySQL建表SQL，初始化6张数据表

1. 配置生成规则：严格匹配SDD包结构、实体类字段、逻辑删除、时间自动填充、乐观锁版本号

1. 一键生成：Entity、Mapper、MapperXML、Service、Controller基础CRUD代码

1. 对照SDD伪代码，补充订单、库存、物流核心业务逻辑即可

8.2 前端Vue3代码生成（基于SDD接口规范）

1. 导入SDD全部接口地址、请求方式、入参出参

1. 自动生成axios接口请求文件（api/order.js、api/logistics.js、api/product.js）

1. 自动生成页面基础模板：商品列表页、订单创建页、订单列表页、物流轨迹跟踪页

1. 页面状态下拉框、状态文字回显直接绑定SDD枚举，保证前后端状态完全一致

8.3 代码生成约束（OpenSpec强制要求）

• 生成代码后，禁止私自新增接口、修改字段、变更状态值

• 所有代码修改必须同步更新SDD文档，保证文档与代码100%一致

• 前后端枚举值完全复用SDD定义，不允许前端自定义状态文案

9 测试用例设计（基于SDD规范，直接用于Postman/JUnit测试）

9.1 后端JUnit单元测试用例

|------------|---------------|----------------------|
| 测试场景 | 入参 | 预期结果（SDD规范） |
| 正常下单（库存充足） | 商品ID=1，数量=1 | 库存锁定成功，订单创建成功，状态=待发货 |
| 库存不足下单 | 商品ID=1，数量=200 | 抛出异常：库存不足，下单失败 |
| 待发货订单取消 | 有效待发货订单ID | 订单状态改为已取消，库存回滚成功 |
| 已发货订单取消 | 已发货订单ID | 抛出异常：当前订单不可取消 |
| 物流逆向状态更新 | 已签收订单改为运输中 | 拦截报错，禁止逆向变更物流状态 |

9.2 前端页面功能测试用例

• 订单列表：正常展示不同状态订单，状态文案和SDD枚举完全匹配

• 创建订单：提交后自动展示订单号，库存数据同步变化

• 取消订单：仅待发货订单展示取消按钮，其他状态按钮置灰

• 物流跟踪：时间线按照轨迹时间倒序展示，状态流转和状态机一致

10 开发落地步骤总览（从工程创建到项目运行）

1. 前置：阅读OpenSpec开发理念与全量SDD规范，确认业务无疑问

1. 步骤1：IDEA创建SpringBoot3 Maven工程，匹配文档JDK17、依赖版本

1. 步骤2：执行SDD内置MySQL建表语句，初始化数据库

1. 步骤3：按照SDD包结构创建目录，粘贴全局基础类、枚举类

1. 步骤4：基于SDD数据表一键生成后端CRUD代码

1. 步骤5：对照SDD业务伪代码，补全订单、库存、物流核心业务

1. 步骤6：Vite创建Vue3工程，基于SDD接口生成前端api与页面

1. 步骤7：对照SDD测试用例，完成单元测试与前后端联调

1. 步骤8：最终验收：代码、接口、业务、状态流转完全贴合SDD规范

11 附录：依赖版本清单（严格遵循，禁止升级降级）

11.1 后端pom.xml核心依赖

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| xml <dependencies> <!--SpringBoot3 Web--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--Mybatis-Plus--> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency> <!--MySQL驱动--> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <!--Lombok--> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies> |

11.2 前端package.json核心依赖

|----------------------------------------------------------------------------------------------|
| json { "dependencies": { "vue": "^3.4.0", "element-plus": "^2.4.0", "axios": "^1.6.0" } } |