本文档是杜美芳（后端）交付给前端童昕祺（买家）、陈泽英（卖家）与后端李炫苇的联调对接基准。所有字段以 Swagger 为准（http://localhost:8080/swagger-ui.html），本文列出的就是后端已实现并编译通过的接口。

---

项	值
后端地址	http://localhost:8080
Swagger	http://localhost:8080/swagger-ui.html
卖家账号	seller / seller123456
买家前端	5173（后端已放行 CORS）
卖家前端	5174（后端已放行 CORS）

---

1. 响应结构统一：{ "code": 0, "message": "success", "data": {...} }，code=0 成功，非 0 失败。
2. 前端只按 code 弹提示，不自己判断业务状态。
3. 金额是字符串（如 "99.90"），禁止用 JS number 直接算。
4. 所有 ID 是字符串（后端 Long 转 String）。
5. 时间 ISO 8601（带 +08:00）。
6. 卖家接口统一带头：Authorization: Bearer <token>。
7. 买家口令码：提交意向时返回一次，之后查询/修改/撤销都传 code。
8. 写接口可传 requestId 做幂等（防重复点击），后端已支持。

接口	方法	地址	入参	返回
当前商品	GET	/api/buyer/product/current	无	ProductView（含 canSubmitIntent）
提交意向	POST	/api/buyer/intent	name, phone, requestId?	{ code, intent }，code 只显示一次
查询意向	GET	/api/buyer/intent?code=	code	BuyerIntentView
修改意向	PUT	/api/buyer/intent	code, name?, phone?	BuyerIntentView
撤销意向	POST	/api/buyer/intent/cancel	code	无

关键点：

• 商品无数据时 current 返回 data=null，前端展示"暂无商品在售"。
• canSubmitIntent=true 才可提交；商品冻结/交易中时返回 false 且提交会得到 40902。
• 提交成功拿到 code 后必须引导用户保存（只显示一次）。
• 查询时 queuePosition 是当前排队位次；canModify / canCancel 决定按钮是否可点（后端返回，前端别自己推）。

接口	方法	地址	入参
登录	POST	/api/seller/login	username, password
改密码	POST	/api/seller/change-password	oldPassword, newPassword（>=8位）
发布商品	POST	/api/product/publish	name, description?, price, imageUrl?, requestId?
手动冻结	POST	/api/product/freeze	productId, requestId?
手动解冻	POST	/api/product/unfreeze	productId, requestId?
开始交易	POST	/api/product/start-trade	productId, requestId?
确认成功	POST	/api/product/confirm-sold	productId, intentId, requestId?
确认失败	POST	/api/product/confirm-failed	productId, intentId, disposition(VOID/REQUEUE), requestId?
手动下架	POST	/api/product/off-shelf	productId, requestId?
当前商品	GET	/api/seller/product/current	无
意向列表	GET	/api/seller/intents?productId=	productId
历史商品	GET	/api/seller/history/products?page=&pageSize=	分页
历史意向	GET	/api/seller/history/products/{id}/intents	id
图片上传	POST	/api/upload/image	multipart 字段 file

关键点：

• 登录拿 token 后，所有接口带 Authorization: Bearer 。
• 卖家当前商品视图（SellerProductView）里带 5 个按钮标志：canFreeze / canUnfreeze / canStartTrade / canOffShelf / canConfirmTrade，前端按这些标志控制按钮显隐和禁用，别自己判断状态。
• 发布商品前先调 /api/upload/image 传图，拿到 /uploads/xxx 填进 imageUrl。
• confirm-failed 必须带 disposition，值只能是 VOID 或 REQUEUE。

---

你负责意向表、卖家表、图片上传、SQL、API 联调。现状：杜美芳为了让后端能跑通，已临时把这三块一并实现了。你们二选一：

方案一（推荐）：杜美芳保持现状，李炫苇专注出 SQL 脚本和组织联调测试；Postman 集合、Dockerfile 由胡芷源负责。 方案二：李炫苇接管 intent/seller/上传三块的代码维护，杜美芳移交。

无论哪个方案，必须沿用以下已定的表结构与枚举（否则联调必炸）：

• product 表：status TINYINT（0 在售 / 1 手动冻结 / 2 交易中冻结 / 3 已下架）、current_intent_id、price DECIMAL(10,2)、active_flag 生成列 + 唯一索引（单活跃商品约束）
• intent 表：status TINYINT（0 排队中 / 1 交易中 / 2 成功 / 3 作废 / 4 撤销 / 5 重新排队中 / 6 最终失败）、code_hash CHAR(64)、queued_at DATETIME(3)、fail_count
• seller 表：username 唯一、password_hash（BCrypt）
• 完整 DDL 见 src/main/resources/schema.sql

---

1. 杜美芳启动后端，确认 Swagger 可开、schema.sql 建表成功。
2. 李炫苇组织按第 2/3 节接口逐个过一轮；Postman 集合由胡芷源汇总产出。
3. 童昕祺接买家端：先做"浏览商品 + 提交意向 + 拿口令码"，再做查询/修改/撤销。
4. 陈泽英接卖家端：先做"登录 + 发布商品"，再做冻结/解冻/开始交易/成交/下架。
5. 全员联调一条完整链路：发布 -> 3 个买家提交意向 -> 开始交易 -> confirm-failed 递补 -> confirm-sold 下架 -> 历史记录。
6. 出问题时，前端把响应里的 traceId（X-Request-Id 头）报给后端排查。

• 卖家登录/改密/发布/冻结/解冻/下架
• 商品发布后不可修改
• 买家匿名浏览、提交、拿口令码、查询/修改/撤销
• 先到先得，提交意向不冻结商品
• 撤销不影响商品状态、不触发递补
• 交易失败同事务递补/恢复，无中间态
• 重新排队排到队尾，不立即再次进入交易
• 交易成功商品下架、其余意向最终失败
• 手动下架仅限在售/手动冻结
• 交易中禁止解冻/下架（40908/40909）
• 状态流转匹配数据字典
• 历史只读持久化、重启不丢
• 异常场景有拦截无状态错乱
• 并发提交无插队、无乱序