口令码与队列规则说明

项目	内容
项目名称	在线购物系统（挑战升级）· MVP 基线版本 · 第 5 组
文档名称	口令码与队列规则说明（设计补充文档）
编制人	周到（产品经理）
编制日期	2026-10-07
版本	v1.1
编制依据	需求规格说明书 FR-04 待细化项（第 8 节待确认事项 1「口令码的生成、存储、校验规则与有效期」的落地）；需求澄清结论第五节（排队撤销）、第六节（冻结恢复）
覆盖模块	队列与冻结模块（FR-04 / FR-06，Backlog D/F）

文档说明：本文档是 FR-04 需求条目中标注「待细化」内容的正式设计定义， 与 services_state.py 现有实现一一对应，供评审老师对照代码查验。

---

一、口令码规则

#	规则项	设计定义	对应依据
1	生成算法	secrets.token_hex(4)，生成 8 位十六进制字符串（如 a3f9c2e1）	FR-04 待细化项
2	随机性保证	secrets 模块基于操作系统密码学安全随机源（CSPRNG），不可预测、不可枚举，满足 NFR-05「口令码不可被他人猜测或枚举」	NFR-05
3	唯一性保证	生成后先查 intent 表 token_code 字段去重，撞码则循环重新生成，入库码全局唯一	FR-03-7
4	绑定关系	口令码与单条意向一一唯一绑定：每次提交都是独立意向记录，各配独立口令码；不按买家电话号码复用或合并	FR-03-6 / FR-03-7
5	存储方式	随 intent 表持久化存储（sqlite），服务重启不丢失	NFR-04
6	展示时机	提交成功后当场显示给买家，仅展示一次，系统不留买家侧查询入口	FR-03-8
7	使用场景	仅用于买家凭码撤销自己的意向（FR-04-4，对应自测 D-3）。「凭码查询意向状态」「凭码修改意向信息」经第 1 次评审助教点评后，已在需求规格说明书 v1.1 显式划为本版本范围外（FR-04-9/10），列入第 2 次迭代候选	FR-04-4 / FR-04-9/10
8	校验规则	撤销时按 token_code 精确匹配 + 意向状态 pending 双重校验；任一不满足即返回「口令码无效，或该意向不可撤销」	FR-04-4 / FR-04-5
9	失效时机	口令码不设时间有效期，随意向生命周期；意向到达终态 success / failed / cancelled 后即失效（进入 trading 亦失效，见第三节对照表），不可再凭码操作	FR-04-5 / FR-04-8
10	冻结期有效性	冻结期口令码仍然有效——冻结不是交易结束，排队中的意向还「活着」，买家仍可凭码撤销（撤销后队列实时前移）	澄清结论第五、六节
11	下架后失效	商品下架（标记「成功」转入历史）时，队首意向转 success、其余 pending 意向全部转 failed，所有口令码随之到达终态失效	FR-07-5

---

二、队列规则

#	规则项	设计定义	对应依据
1	排序键	created_at（毫秒精度时间文本，字典序 = 时间序）+ 自增 id 兜底：同毫秒并发提交时按入库顺序稳定排序	FR-04-2 / NFR-03
2	队列容量	不限制人数，可挂多个有效意向	FR-04-1 / 澄清结论第五节
3	有效意向	仅 pending 状态进入队列展示与排序；trading 为队首交易位，success/failed/cancelled 均出队	澄清结论第五节
4	位次设计	位次不落库、实时计算（查询时 ORDER BY created_at ASC, id ASC），避免撤销/递补时批量 UPDATE 位次字段，消除多字段状态不同步的一致性风险	NFR-02
5	交易入口	同一时间仅队首可进入线下交易；进入交易接口做队首校验，非队首直接拒绝（自测 D-2/D-4 验证）	FR-04-3
6	递补触发点 ①：撤销	买家凭码撤销 → 意向转 cancelled 出队 → 因位次实时计算，其后所有意向位次自动前移，无需额外处理	FR-04-5 / FR-04-6
7	递补触发点 ②：交易失败	队首被标记「失败」→ 转 failed 出队 → 队列下一位 pending 自动转 trading，商品保持冻结（自测 D-5 验证）	FR-04-7 / FR-07-7
8	队列为空 · 失败路径	队首失败且队列已无 pending → 商品恢复「在售」，重新接收新意向	FR-07-6
9	队列为空 · 展示路径	无交易进行且无 pending 意向 → 后台显示「暂无有效意向」，不渲染队列表格	FR-05-1
10	冻结与队列的关系	冻结只拦截新意向（FR-06-4），不终止已有意向——排队意向的口令码在冻结期仍有效（见口令码规则 #10）	FR-06-4 / 澄清结论第六节
11	交易中保护	存在 trading 意向时不允许手动解冻，防止破坏「仅队首进入交易」的队列语义	FR-04-3

---

三、口令码状态与意向状态对照

意向状态	口令码是否有效	说明
pending（排队中）	✅ 有效	可凭码撤销；冻结期亦有效
trading（交易中）	❌ 失效	队首已进入线下交易，不可凭码撤销
success（成交）	❌ 失效	终态
failed（失败）	❌ 失效	终态（含商品下架时的批量转失败）
cancelled（已撤销）	❌ 失效	终态，撤销动作本身已完成

---

四、自测验证

以上规则的自动化验证见 卖家后台/test_d_module.py（D-1D-5、F-1F-5 共 10 项边界用例）， 运行方式：python test_d_module.py，期望输出 周到模块自测：10 通过 / 0 失败。

---

五、变更记录

版本	日期	变更内容	修订人
v1.0	2026-10-07	首版创建：定义口令码生成/绑定/失效规则与队列排序/递补规则	周到
v1.1	2026-10-07	依据第 1 次评审助教点评对齐：#7 使用场景补「凭码查询/修改已显式划为范围外（规格书 FR-04-9/10）」；#9 失效时机补「不设时间有效期」表述，与规格书 FR-04-8 一致	周到