vr-shopxo-plugin/plan.md

Council Plan — vr-shopxo-plugin

Round 1/2/3 — 2026-04-14 Branch: council/backend-reviewer → main 状态：Round 1 并行评审阶段

---

Document Review Summary (All Agents)

docs/01_SHOPXO_TECHNICAL_RESEARCH.md — 🔐 backend-reviewer 评审

SQL 设计部分：

检查项	结论	说明
vr_tickets 表 DDL	✅ 已定义	docs/03_VERIFICATION_SYSTEM.md 中完整
vr_verifications 表 DDL	✅ 已定义	同上
vr_verifiers 表 DDL	✅ 已定义	同上
vr_events 表 DDL	⚠️ 缺失	仅 ARCHITECTURE.md 列出表名，无字段定义（DDL 已在 reviews/ 中补充）
vr_sessions 表 DDL	⚠️ 缺失	同上
ShopXO 原生表分析	✅ 充分	sxo_order / sxo_goods_spec_base 分析到位
索引策略	⚠️ 需补充	vr_tickets 已定义；vr_events/vr_sessions 缺失
外键约束	⚠️ 建议补充	无外键（ShopXO 风格，依赖业务逻辑）

安全审查部分：

检查项	结论	说明
SQL 注入防御	✅ 通过	ThinkPHP Db 类自动参数绑定
BuyService 原子扣库存	✅ 通过	WHERE inventory >= N + dec() 原子操作，事务回滚
QR 码 base64 编码	✅ 通过	base64 编码本身无注入风险
QR payload 枚举风险	⚠️ 需补充	UUID-v4 不可预测，但 brute-force 防护需在核销 API 层实现
AES IV 设计	⚠️ 已知风险	IV = substr(md5(ticket_code), 0, 16) 非随机 IV，理论 CPA 风险
extension_data JSON 存储	✅ 安全	ORM 写入，json_decode 读取
核销 API 鉴权链	⚠️ 未验证	Admin 端由 AdministratorBase 基类鉴权；C 端需补充
sxo_order_extraction_code.code	⚠️ 未分析	生成算法在 ShopXO 源码中未找到

BuyService OrderInsertHandle 源码审查结论：

• 事务边界正确，原子性有保障
• WHERE inventory >= N + dec() 防超卖安全
• 扣库存在支付成功时触发，座位 = SKU(inventory=0/1)，并发处理正确

docs/03_VERIFICATION_SYSTEM.md — 核销系统设计（ticket-reviewer）

维度	评级	说明
系统概述 & 模式	✅ 通过	三种核销模式清晰，粒度选择明确（按座位）
QR 生成设计	✅ 通过	JSON 结构完整，支付回调触发时机正确
加密方案	✅ 通过	AES-256-CBC + IV=MD5(ticket_code)，附完整设计说明
数据模型	✅ 通过	vr_tickets / vr_verifications / vr_verifiers 三表设计合理
B 端核销页	✅ 通过	Vue 代码完整，fork 自 realstore/check.vue 路径正确
后端 API	✅ 通过	API 路径已统一（C 端 api/vrticket/verify / Admin 端 admin/vrticket/verify）
C 端票夹	✅ 通过	钩子注入点、页面内容设计清晰
防超卖机制	✅ 通过	三阶段锁定时序 + vr_seat_locks 表 + 悲观锁 + 并发控制
部署方案	✅ 通过	B 端/个人主体小程序限制已明确

ARCHITECTURE.md — 架构文档

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

docs/05_AI_PARTICIPATION.md — AI 参与可行性分析

维度	评级	说明
页面分类	✅ 通过	DIY/代码/CustomView 三类清晰，AI 参与度判断准确
DIY 不可行说明	✅ 通过	JSON 私有性说明充分，有说服力
CustomView 优势	✅ 通过	三栏编辑器 + ThinkPHP 模板语法，AI 可直接生成
参与路线图	✅ 通过	Phase 1/2/3 分工合理
CustomView 局限性	✅ 通过	明确 CustomView 仅适合静态展示页，不适合动态交互
写入数据库路径	⚠️ 需补充	缺少 CustomView 页面内容存储的数据库表结构或 API 操作路径

---

Issue Summary

✅ 已解决（Round 2-3）

1. 防超卖机制缺失 — ✅ ticket-reviewer 补充了三阶段锁定时序 + vr_seat_locks 表 + 并发控制
2. CustomView vs 动态路由边界模糊 — ✅ arch-reviewer 明确了 CustomView 仅适合静态展示页

⚠️ 需补充（编码前建议明确）

3. vr_events / vr_sessions DDL 缺失

   • ARCHITECTURE.md 仅列出表名，无字段定义
   • 补充 DDL 已在 reviews/backend-reviewer-on-docs.md 中

4. item_type='ticket' 写入机制 — ARCHITECTURE.md

   • goods.item_type 字段谁来写？后台手动设置？插件自动同步？

5. 核销员权限验证缺失 — docs/03_VERIFICATION_SYSTEM.md

   • VerifyTicket() 未检查调用者是否为认证核销员
   • 建议：增加 vr_verifiers 表身份校验

6. AES IV 随机化 — docs/03_VERIFICATION_SYSTEM.md

   • IV = substr(md5(ticket_code), 0, 16) 不是随机 IV
   • 建议：改用 random_bytes(16)，IV 编码进密文

7. QR brute-force 防护 — docs/01_SHOPXO_TECHNICAL_RESEARCH.md

   • 核销 API 应有 rate-limit 防护（同一 IP 请求频率限制）

8. 支付回调 Hook 名称 — 多份文档提及但未给出具体 Hook 名称

   • 需确认 plugins_service_buy_order_insert_success 是否在支付成功后触发

9. CustomView 数据库写入路径 — docs/05_AI_PARTICIPATION.md

   • CustomView 页面内容存储在哪个表/字段？需补充表结构

10. Goods.php 模板替换原则矛盾 — ARCHITECTURE.md

    • 「不修改核心代码」是核心原则，但 Goods.php Index() 加判断违反了此原则
    • 建议改为通过 Hook 机制完全替代，不改核心文件

---

Task Checklist

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

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

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

  • C 端核销 API：/?s=api/vrticket/verify
  • Admin 端核销 API：/?s=admin/vrticket/verify
  • [Done: council/ticket-reviewer]

• T3: 补充 AES IV 设计说明

  • [Done: council/ticket-reviewer]

• T4: 生成票务核销系统完整设计文档

  • [Done: council/ticket-reviewer]

• T4b: SQL/安全审查 docs/01_SHOPXO_TECHNICAL_RESEARCH.md

  • [Done: council/backend-reviewer]

• T5: 明确 item_type 写入机制 + Goods.php 修改原则

  • 在 ARCHITECTURE.md 中补充说明
  • [Pending: council/arch-reviewer]

• T6: 确认支付回调 Hook 名称

  • 补充具体 Hook 到 ARCHITECTURE.md 和 docs/03_VERIFICATION_SYSTEM.md
  • [Pending: council/backend-reviewer]

• T7: 补充 CustomView 数据库写入路径

  • [Pending: council/arch-reviewer]

• T8: 补充核销员权限验证（VerifyTicket 身份校验）

  • [Pending: council/backend-reviewer]

• T9: 补充 vr_events / vr_sessions DDL 到 ARCHITECTURE.md

  • [Pending: council/backend-reviewer]

---

Phase Breakdown

Phase	内容	负责人
Draft	T1-T4 ✅ 完成；T4b ✅ 完成；T5-T9 待完成	ticket/arch/backend
Review	跨评审	all
Finalize	合并到 main，投票	all

---

Voting

Agent	Vote	说明
backend-reviewer	[CONSENSUS: YES]	文档质量足够开始编码；防超卖/核销/API 路径等核心问题已解决；6 项非阻断性改进可在编码过程中迭代
pm-reviewer	TBD	待 Round 2 输出
ticket-reviewer	✅ YES	Round 3 已投票
arch-reviewer	TBD	待 Round 1 输出

[CONSENSUS: PARTIAL] — Round 1 的阻断问题已全部解决，docs/03_VERIFICATION_SYSTEM.md 可以开始编码。但仍有 6 个 ⚠️ 建议项（T5-T9）未解决，建议编码时同步处理。

---

Claim Status

Task	Owner	Status
ARCHITECTURE.md 评审	arch-reviewer	[Done: arch-reviewer]
05_AI_PARTICIPATION.md 评审	arch-reviewer	[Done: arch-reviewer]
01_SHOPXO_TECHNICAL_RESEARCH.md 评审	backend-reviewer	[Done: council/backend-reviewer]
03_VERIFICATION_SYSTEM.md 评审 + 修复	ticket-reviewer	[Done: council/ticket-reviewer]
ARCHITECTURE.md 评审（ticket-reviewer 视角）	ticket-reviewer	[Done: council/ticket-reviewer]
04_IMPLEMENTATION_ROADMAP.md 评审	pm-reviewer	[Pending]
DEPLOYMENT.md 评审	pm-reviewer	[Pending]