商品中心模块（迭代 2）

更新日期：2026-10-21。负责人：黄程宇。对应 T2-08～T2-12，14故事点。

商品中心已完成分支交付及本地验证：PR #1，目标分支为 iter2-java，已于2026-10-21 23:33（北京时间）合入，合并提交671ae635ceee6131a451ef946970c846a071432b。代码版本：793dc62。

任务与成果

任务	完成内容	成果
T2-08 两级分类	固定两级，同父级不重名；支持新增、停用和删除空分类；有子类或商品引用时禁止删除；停用父级隐藏子类	CategoryQueryService、分类维护页
T2-09 多商品发布	连续发布多件；名称必填、价格大于0且最多两位小数、二级分类必填；发布前确认；不提供商品编辑或删除	ProductService、ProductController、发布页
T2-10 库存与上下架	非负库存、条件UPDATE扣减、归零自动下架及pending队列失败；手动下架、补货、显式重新上架；release不覆盖下架状态	StockService、ProductQueueAdapter
T2-11 多图	发布时最多9张，排序及选择主图；扩展名、5MiB、文件头及完整解码检查；缺省占位图；失败清理新文件	product_image、上传与预览、详情图集
T2-12 富文本	分段、加粗、图片、受信视频iframe；保存前白名单过滤，删除script、事件属性和非白名单iframe；提供渲染片段	RichTextSanitizer、编辑区、description片段

完整路由、入参和交接约束：商品中心契约。

团队联调

• 卖家入口：/admin/products、/admin/products/new、/admin/categories。
• 分类树、商品详情、库存和图片通过正式服务接入门户的 CategoryPort / ProductPort；移除已覆盖的临时商品探针及无限库存降级。common 包无改动。
• 库存归零通过 IntentQueuePort 通知交易模块，商品模块不写 intent 表；ProductQueueAdapter 只调用交易 owner 已有的队列能力。
• 后台入口继承已有卖家鉴权，商品操作校验卖家所有权。其他成员的账号、订单及交易成果保持原归属。

动作	库存	商品状态
发布库存>0 / =0	发布时指定	on_sale / off_shelf，后者off_reason=auto
提交意向、确认交易	不扣	确认交易后frozen
交易成功	原子扣1	有库存时解冻；归零自动下架，pending队列置failed
交易失败	不变	由交易模块记录失败或重新排队，并调用release
手动下架	不变	off_shelf / manual；后续release不能覆盖
补货	按输入调整	保持下架，需要手动重新上架

交易未结束时不允许把库存调成0；交易中手动下架后若重新上架，仍有交易则恢复frozen。这是实现约束，需在团队联调时确认。

数据与需求口径

本次按用户提供的v4任务表采用 off_shelf/off_reason、product_image.file_path/sort_no/is_primary 和富文本保存前过滤。Wiki澄清记录中的部分旧默认值（delisted、path、不做白名单）与任务表不同，这些差异在契约中明确列出，未改写原始澄清记录。

新库直接按四份schema初始化。旧Java商品表升级前先生成SQLite一致性备份，保留商品编号、分类、主图及订单关联；原一级分类或未分类商品转入迁移二级分类，旧商品默认库存1。升级失败回滚。商品迁移不代替交易模块原有匿名订单迁移的核对。

验证与展示

团队商品中心测试记录：全量83项通过，新增16项；包括库存3并发扣5次、归零队列处理、异常回滚、旧表备份迁移。外站视频已验证过滤与嵌入输出，尚无实际播放成功证据。

以下为本地隔离环境实际页面。9图使用占位图测试文件，验证上传、数量和布局。

交接事项

PR #1已合入。后续在团队Java17环境回归并补实际演示/录屏；确认上述实现约束及需求文本差异。教师意见、基线验收门控和延期报备以真实记录为准，本次没有代发群消息或提交验收。