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，再投票。

---