vr-shopxo-plugin/plan.md

# Council Plan — vr-shopxo-plugin

> Round 1 Planning — 2026-04-14（重新评审）
> Branch: council/backend-reviewer → main
> 任务：重新评估文档包，判断是否可以开始编码

---

## Document Review Summary

### 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 列出表名，无字段定义 |
| 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)，并发处理正确

---

## Issue Summary

### Critical / Blocker

1. **[⚠️ vr_events / vr_sessions DDL 缺失]**
   - ARCHITECTURE.md 仅列出表名
   - 字段定义在 `reviews/backend-reviewer-on-docs.md` 中已补充

2. **[⚠️ 核销员权限验证缺失]** `docs/03_VERIFICATION_SYSTEM.md`
   - `VerifyTicket()` 未检查调用者是否为认证核销员
   - 建议：增加 `vr_verifiers` 表身份校验

### Non-blocking / Improvement

3. **[⚠️ AES IV 随机化]** `docs/03_VERIFICATION_SYSTEM.md`
   - `IV = substr(md5(ticket_code), 0, 16)` 不是随机 IV
   - 建议：改用 `random_bytes(16)`，IV 编码进密文

4. **[⚠️ QR brute-force 防护]** `docs/01_SHOPXO_TECHNICAL_RESEARCH.md`
   - 核销 API 应有 rate-limit 防护（同一 IP 请求频率限制）
   - UUID-v4 本身不可预测，但高频探测仍应防护

5. **[⚠️ Admin vs C 端 API 路径]** `docs/03_VERIFICATION_SYSTEM.md`
   - Vue 代码调用：`ticket/verify`（C 端路由）
   - PHP 后端定义：`admin/vrticket/verify`（Admin 端）
   - 需确认两个端点的权限路由是独立的

---

## Reviews Produced

| File | Reviewer | Verdict |
|---|---|---|
| `reviews/backend-reviewer-on-docs.md` | 🔐 backend-reviewer | ✅ 通过（需补充 3 项非阻塞） |
| `reviews/ticket-reviewer-*.md` | 🎫 ticket-reviewer | TBD |
| `reviews/pm-reviewer-on-docs.md` | 📋 pm-reviewer | TBD |
| `reviews/arch-reviewer-*.md` | 🏗️ arch-reviewer | TBD |

---

## Phase Breakdown

| Phase | 内容 | Status |
|---|---|---|
| **Draft** | 文档评审完成 | ✅ Done |
| **Review** | 跨 Agent 评审，待其他 Agent 输出 | 🔄 In Progress |
| **Finalize** | 合并评审结论到 docs/，投票 | ⏳ Pending |

---

## Voting

| Agent | Vote | 说明 |
|---|---|---|
| backend-reviewer | `[CONSENSUS: YES]` | 文档质量足够开始编码；3 项非阻断性改进可在编码过程中迭代 |
| pm-reviewer | TBD | 待 Round 1 输出 |
| ticket-reviewer | TBD | 待 Round 2 输出 |
| arch-reviewer | TBD | 待 Round 1 输出 |

> 汇总：`[CONSENSUS: YES]`（条件性通过）— 3 项改进项可在编码迭代中解决，无阻断性架构缺陷。