口令码与队列规则说明（迭代2 · Java版）

初稿：周到（产品经理），2026-10-07；v2.0修订2026-10-20；2026-10-22按已合入671ae63同步。迭代1规则仍见口令码与队列规则说明，本页只描述当前Java实现。

1 买家身份与旧码兼容

新意向必须登录买家账号，写入buyer_id及姓名、电话、交易地点快照。token_code为NULL，不生成或展示32位口令码；TimeUtils中保留的随机码工具不等于提交入口仍在调用它。同一买家同一商品最多一条pending/trading，由服务校验和部分唯一索引共同约束。

旧接口POST /intents/cancel保留tokenCode参数，仅精确命中pending意向才置cancelled，并填写finished_at。其他状态返回相同无效提示；买家页面无凭码撤销入口。token_code非空记录由部分唯一索引uq_intent_token约束，不在这里承诺旧匿名库迁移后一定保留全部旧码；迁移边界见数据库设计-迭代2。

2 排队与交易

动作	意向变化	商品和库存
买家提交	新pending，按created_at、id先到先得	要求on_sale、库存>0；不扣库存
卖家确认	仅队首pending可转trading，同商品不能已有trading	freeze：on_sale转frozen，不扣库存
标成功	trading转success，填写trade_result与finished_at	原子扣1，归零自动off_shelf/auto并结束其余pending
标失败并作废	trading转failed，记录原因与时间	不扣库存，release只释放frozen
标失败并重排	trading回pending、刷新created_at	不扣库存；下一位仍需人工确认
旧码撤销	pending转cancelled	不扣库存，实时队列自然前移

位次不落库。队列按created_at ASC、id ASC读取；重排队尾刷新created_at。交易失败不会自动递补下一位为trading，这与旧Python流程不同。

stateDiagram-v2
    [*] --> pending: 登录后提交
    pending --> trading: 卖家确认队首
    trading --> success: 成交扣1
    trading --> failed: 失败作废
    trading --> pending: 失败重排队尾
    pending --> failed: 库存归零
    pending --> cancelled: 仅旧码兼容

3 冻结、下架与补货

整件商品冻结，同一时刻一笔交易。frozen详情可查看但不再接收新意向，列表仅显示on_sale。成功后仍有库存，release恢复在售；库存0时自动下架，剩余pending失败并带原因。一次成交不必结束整个商品生命周期。

手动下架写off_shelf/manual，已有交易仍可完成，其他pending保留。release不覆盖手动下架。调整库存为0会自动下架并结束pending，但存在trading时禁止调0。补货不会自动上架；手动重新上架时若仍有trading，恢复frozen，否则on_sale。

4 数据与验证

intent状态允许pending/trading/success/failed/cancelled；新买家订单与客户购买历史只显示success/failed，按finished_at倒序。buyer_id是逻辑关联，不写成已有数据库外键。

PortalFlowTest14项、SellerTradeFlowTest9项、MyOrdersFlowTest3项，均包含在2026-10-21 23:19已记录的全量83项中。商品库存与回滚场景另见ProductCenterTest和ProductMigrationTest。本次只同步文档，未复跑业务测试或生成录屏。

详见买家门户与交易模块-迭代2、商品中心模块-迭代2、商品中心测试记录-迭代2。原始PM澄清记录保留原文；文档描述当前实现不等于需求方已批准所有差异。