vr-shopxo-plugin/plan.md

Council Plan — vr-shopxo-plugin

Round 1 Planning — 2026-04-14 Branch: council/ticket-reviewer → main

---

Document Review (Ticket Reviewer — docs/03_VERIFICATION_SYSTEM.md + ARCHITECTURE.md)

docs/03_VERIFICATION_SYSTEM.md — 核销系统设计

维度	评级	说明
系统概述 & 模式	✅ 通过	三种核销模式清晰，粒度选择明确（按座位）
QR 生成设计	✅ 通过	JSON 结构完整，支付回调触发时机正确
加密方案	⚠️ 需补充	AES-256-CBC 推荐，但 IV=MD5(ticket_code) 做法需明确说明（不是随机 IV，有理论风险但实际可接受）
数据模型	✅ 通过	vr_tickets / vr_verifications / vr_verifiers 三表设计合理
B 端核销页	✅ 通过	Vue 代码完整，fork 自 realstore/check.vue 路径正确
后端 API	⚠️ 需补充	VerifyTicket() PHP 实现完整，但 API 路径不统一（文档写 admin/vrticket/verify，Vue 写 ticket/verify），需对齐
C 端票夹	✅ 通过	钩子注入点、页面内容设计清晰
防超卖机制	❌ 缺失	核心缺陷：核销逻辑未涉及库存扣减/锁座机制，QR 生成和核销都依赖"支付成功"时间点，但无并发控制说明
部署方案	✅ 通过	B 端/个人主体小程序限制已明确

结论：整体清晰完整，但 防超卖机制缺失 是架构性缺陷，需在实现前补充。

ARCHITECTURE.md — 架构文档

维度	评级	说明
核心发现	✅ 通过	7 项技术发现均基于实测，有文件路径和代码片段
整体架构图	✅ 通过	PHP 后端 + uniapp 前端结构清晰
数据模型	✅ 通过	ShopXO 复用表 + 插件独立表对照清晰
目录结构	✅ 通过	插件目录设计规范
购票流程	✅ 通过	完整流程链路清晰
对比表	✅ 通过	与 vr-ticket-mp 对比有价值
技术栈	✅ 通过	栈选择合理
文档链接	✅ 通过	官方文档索引完整

结论：✅ 通过，架构文档质量高。

---

Issue Summary (ticket-reviewer)

1. [⚠️ API 路径不一致] docs/03_VERIFICATION_SYSTEM.md

   • Vue 代码调用：ticket/verify（app.globalData.get_request_url('verify', 'ticket', 'vrticket')）
   • PHP 后端定义：admin/vrticket/verify
   • 需统一，建议全部使用 vrticket/verify 并区分 admin/非admin 端点

2. [⚠️ AES IV 说明不足] docs/03_VERIFICATION_SYSTEM.md

   • IV = substr(md5($ticket_code), 0, 16) — 不是随机 IV
   • 实际安全影响有限（QR 内容本身含唯一 UUID），但需加注释说明设计意图

3. [❌ 防超卖机制缺失] docs/03_VERIFICATION_SYSTEM.md

   • 核销逻辑假设票已生成，但未说明：
     • 场次库存如何扣减（支付成功时？）
     • 座位选择与库存锁定的时序
     • 并发购买同一座位时的处理
   • 建议补充：座位锁定机制（Redis 锁 / 数据库锁）和库存原子扣减流程

---

Task Checklist

• T1: 补充防超卖机制章节到 docs/03_VERIFICATION_SYSTEM.md

  • 座位锁定时序（用户选座 → 锁定 → 支付 → 生成 QR）
  • 并发控制（数据库唯一索引 + 事务）
  • 锁定超时释放机制

• T2: 统一 API 路径（admin 端 vs C 端）

  • C 端核销 API：/?s=api/vrticket/verify
  • Admin 端核销 API：/?s=admin/vrticket/verify
  • 核销员权限验证逻辑

• T3: 补充 AES IV 设计说明注释

• T4: 生成票务核销系统完整设计文档（含防超卖、API 规范、数据库约束）

• T5: 审查其他 agent 的输出（跨评审）

---

Phase Breakdown

Phase	内容	负责人
Draft	T1 + T2 + T3：补充文档内容	[Claimed: council/ticket-reviewer]
Review	T5：跨评审 arch/backend/pm 输出	[Pending]
Finalize	合并到 main，投票	[Pending]

---

Dependencies

• T1（防超卖）依赖：backend-reviewer 的 SQL 迁移方案（库存扣减 SQL）
• T2（API 路径）依赖：pm-reviewer 的路由规范
• T4 需等 T1/T2/T3 完成

---

Voting

[CONSENSUS: NO] — 文档整体质量高，但防超卖机制缺失是编码前的阻断性问题。Round 2 优先补充 T1，再投票。

---