本文档为《在线购物系统 MVP》后端完整设计说明，在 Wiki 初稿基础上补充了状态机、事务、并发、鉴权与全量接口定义。可直接替换 Wiki 中《后端商品模块设计文档》初稿页面。

对应分工：杜美芳（后端商品模块：商品表、status 字段、发布/冻结/恢复/成交接口 + SOW 技术部分），并与 李炫苇（意向表/卖家表/图片上传）协作联调。

本模块负责在线购物系统中商品与交易状态流转的核心后端逻辑，包括：

• 商品状态管理（在售 / 手动冻结 / 交易中冻结 / 已下架）
• 发布 / 冻结 / 解冻 / 开始交易 / 成交 / 失败递补 / 手动下架接口
• 排队队列（先到先得）与口令码机制
• 并发控制、事务一致性、幂等

边界：本项目仅 Web 端，单卖家、买家免注册，不做支付/物流/评价/推送。

关键依赖：spring-boot-starter-web、mybatis-plus-spring-boot3-starter、mysql-connector-j、spring-security-crypto、jjwt、springdoc-openapi-starter-webmvc-ui。

单活跃商品约束：active_flag 为 MySQL 生成列，加 UNIQUE KEY uk_product_active(active_flag)。MySQL 唯一索引忽略 NULL，故同一时刻至多一行 active_flag=1（至多一件未下架商品）。并发发布第二件由数据库直接拒绝，应用层捕获 DuplicateKeyException 返回 40901。

关键索引：UNIQUE(code_hash)、INDEX(product_id, status, queued_at)、INDEX(product_id, phone)。

[*] --> 在售(0)                 : 卖家发布商品
在售(0) --> 手动冻结(1)          : 卖家手动冻结
手动冻结(1) --> 在售(0)          : 卖家手动解冻（交易中禁止）
在售(0) --> 交易中冻结(2)        : 卖家开始交易，队首进入交易
交易中冻结(2) --> 已下架(3)      : 交易成功
交易中冻结(2) --> 交易中冻结(2)   : 交易失败 + 队列有下一位（自动递补）
交易中冻结(2) --> 在售(0)        : 交易失败 + 队列为空（恢复在售）
在售(0)/手动冻结(1) --> 已下架(3) : 卖家手动下架
已下架(3) --> [*]                : 终态

权限要点：交易中冻结（status=2）禁止手动解冻（40908）、禁止手动下架（40909），只能由卖家标记交易结果。

排队中(0) --> 交易中(1)   : 轮到队首
排队中(0) --> 已撤销(4)   : 买家撤销
交易中(1) --> 交易成功(2) : 卖家标记成功
交易中(1) --> 已作废(3)   : 卖家标记失败 + 作废(VOID)
交易中(1) --> 重新排队中(5): 卖家标记失败 + 重新排队(REQUEUE)
重新排队中(5) --> 交易中(1): 再次轮到
重新排队中(5) --> 已撤销(4): 买家撤销
(0/1/5) --> 最终失败(6)   : 商品下架 / 交易成功关闭队列 / 被挤掉

统一前缀 /api，统一响应结构：

{ "code": 0, "message": "success", "data": {} }

金额以字符串返回，ID 以字符串返回（Long 转 String），时间 ISO 8601。

disposition 取值：VOID（作废）/ REQUEUE（重新排队）。

发布商品：

// 请求
{ "name": "二手书", "description": "九成新", "price": 99.90, "imageUrl": "/uploads/xxx.jpg" }
// 响应 data（卖家当前商品视图）
{
  "id": "1", "name": "二手书", "price": "99.90", "status": 0, "statusText": "在售",
  "canFreeze": true, "canUnfreeze": false, "canStartTrade": false,
  "canOffShelf": true, "canConfirmTrade": false, "currentIntent": null, "intentCount": 0
}

提交意向（买家），响应含一次性口令码（仅此一次返回）：

{ "code": 0, "message": "success",
  "data": { "code": "K7XQ2N9MZR4P", "intent": { "id": "3", "status": 0, "statusText": "排队中", "queuePosition": 1, "canModify": true, "canCancel": true } } }

所有写操作在事务内完成，通过 SELECT ... FOR UPDATE 锁定商品行串行化状态流转。

关键保证：

1. 单活跃商品：数据库生成列 + 唯一索引兜底，应用层前置校验友好提示。
2. 队列排序统一：queued_at ASC, id ASC；重新排队更新 queued_at 排到队尾，且不立即再次进入交易（递补查询排除当前意向）。
3. CAS 乐观更新：状态流转用 UPDATE ... WHERE status = 旧值 校验影响行数，防止并发状态错乱。
4. 幂等：写接口支持 requestId，服务端以 操作+requestId 缓存首次结果；处理中重复请求返回 40901。

前端仅依据 code 展示提示；后端返回可操作标志（canFreeze / canStartTrade / canSubmitIntent / canModify / canCancel 等）。

• 端口：后端 8080，前端 5173/5174，CORS 已放行。
• 启动：mvn spring-boot:run；建表自动执行（幂等）。
• Swagger：/swagger-ui.html。
• 默认卖家：seller / seller123456。

由 胡芷源 负责 Dockerfile、CI、Postman 集合；本模块提供标准 REST 接口与 Swagger 定义供其生成联调产物。