vr-shopxo-plugin/plan.md

# vr-shopxo-plugin 架构决策评议 — plan.md

> 版本：v1.0 | 制定日期：2026-04-15 | Agent：council/BackendArchitect
> 关联：Issue #9

---

## 任务背景

Phase 0/1/2 已完成基础骨架，暴露了一个 P0 架构问题：VR 演唱会票务商品中 ShopXO SPEC 与 SKU 的绑定方案。

**已知事实：**
- ShopXO `goods_spec_base`（SKU表）当前为空，商品 112 的 `is_exist_many_spec=0`
- `spec_base_id_map` 中的 ID（如 1001/1002/1003）在 DB 中不存在
- ShopXO 防超卖机制（原子扣 inventory）完全未启用

**两种架构方向：**
- **方案 A**：每个座位 = 一个 SKU（stock=1），ShopXO 原生防超卖
- **方案 B**：每个 Zone = 一个 SKU（stock=Zone座位数），自建 FOR UPDATE 防超卖

---

## 阶段划分

| 阶段 | 内容 | 负责 |
|------|------|------|
| Round 1 | 独立评议 + plan.md 合并 | 所有成员 |
| Round 2 | 各成员深入分析（后台实现路径、安全评估、前端方案） | 所有成员 |
| Round 3 | 综合推荐 + 输出最终决策报告 | 所有成员 |

---

## Agent 任务分配

| Agent | 主要评议方向 |
|-------|------------|
| BackendArchitect | Q1（Plan A 后台批量 SKU 生成可行性）+ Q4（最终推荐） |
| SecurityEngineer | Q3（$vr- 前缀安全风险）+ Q4（安全性维度） |
| FrontendDev | 前端方案 A/B 的实现差异 + Q4（前端实现成本） |

---

## 任务清单

### Q1 — Plan A 后台批量生成 SKU 路径评估 `[Pending: BackendArchitect]`
- [ ] 分析 ShopXO spec_base 表写入路径
- [ ] 确认是否需要修改 ShopXO 核心代码还是通过插件可完成
- [ ] 评估批量生成的性能（上万座位场景）
- [ ] 给出可行性结论

### Q2 — 商品 112 broken 状态紧急修复 `[Pending: BackendArchitect]`
- [ ] 评估 is_exist_many_spec=0 + spec_base 空的实际影响
- [ ] 确定最小修复集（是否需要立即修复）
- [ ] 制定修复方案

### Q3 — $vr- 前缀安全评估 `[Pending: SecurityEngineer]`
- [ ] 检查 ShopXO 对带 $ 字符 spec name 的处理逻辑
- [ ] 识别潜在冲突或注入风险
- [ ] 给出安全结论

### Q4 — 方案 A vs 方案 B 最终推荐 `[Pending: all]`
- [ ] BackendArchitect：从实现成本、ShopXO 原生机制利用角度评议
- [ ] SecurityEngineer：从防超卖安全性角度评议
- [ ] FrontendDev：从前端复杂度角度评议

### 最终输出
- [ ] `council-output/ARCHITECTURE_DECISION.md` — 汇总三方推荐 + 最终结论（Round 3）

---

## 依赖关系

- Q1（BackendArchitect）先完成，后 Q4 才能给出完整推荐
- Q3（SecurityEngineer）可与 Q1 并行
- Q2 可独立完成，紧急程度由 BackendArchitect 判定

---

## Claim 状态

| 任务 | Claim 状态 |
|------|-----------|
| Q1 | [Pending: BackendArchitect] |
| Q2 | [Pending: BackendArchitect] |
| Q3 | [Pending: SecurityEngineer] |
| Q4 | [Pending: all] |
| 最终输出 | [Pending: all] |

---

## 本轮（Round 1）初判（BackendArchitect）

**Q1 初步判断**：Plan A 后台批量生成 SKU **可行**。ShopXO 的 `goods_spec_base` 是标准 MySQL 表，插件可直接 INSERT。但需要确认：
- ShopXO 商品保存时是否校验 spec_base 的 referential integrity
- 上万座位时批量 INSERT 的性能
- spec_base_id_map 中的 ID 是否需要与 ShopXO 内部 ID 对齐

**Q2 初步判断**：当前 broken 状态**暂不需要立即修复**。购买流程走的是裸商品逻辑（is_exist_many_spec=0），对 Phase 3 的购买流程设计反而是参考点——需要明确购买流程最终走哪条路后再修。

**Q4 初步判断**：倾向 **方案 A**。ShopXO 原生防超卖机制比自建锁更可靠（DB 层面原子操作），且不破坏 ShopXO 生态完整性。

---

### Task S2 — SQL 注入风险审计 ✅ 无注入风险

**审查范围**：Phase 2 所有控制器 + TicketService

| 控制器 | 查询点 | 输入处理 | 结论 |
|--------|--------|----------|------|
| SeatTemplate::list | `name` like, `status` | `null` + `intval()` | ✅ 安全 |
| Ticket::list | `keywords` multi-field like | `trim()` + 查询构造器绑定 | ✅ 安全 |
| Ticket::verify | `ticket_code`, `verifier_id` | `trim()` + `intval()` | ✅ 安全 |
| Verification::list | date range | `strtotime()` 绑定 | ✅ 安全 |

**无原始 SQL 执行，无字符串拼接注入。**

⚠️ **P1 Bug（已修复）**：`Verifier.php:45` ThinkPHP `column()` 不支持直接传 CONCAT SQL，已改用 `select()` + PHP 拼接

---

### Task S3 — XSS / CSRF 防护检查 ✅ 通过

| 方面 | 状态 |
|------|------|
| CSRF Token (POST) | ✅ ShopXO 保护 |
| XSS（存储型） | ✅ 低风险（admin 上下文） |
| 关键操作 guard | ✅ `delete()` / `verify()` / `export()` 均有 `IS_AJAX_POST` 检查 |

---

### Task S5 — IDOR 水平越权检查 ✅ 通过

Admin 上下文（所有控制器需登录 admin + 插件菜单权限）下访问控制正确。

---

### 安全任务更新

- [x] **Task S1** — Admin 鉴权覆盖完整性 — `[Done: council/SecurityEngineer]`
- [x] **Task S2** — SQL 注入风险审计 — `[Done: council/SecurityEngineer]`
- [x] **Task S3** — XSS / CSRF 防护检查 — `[Done: council/SecurityEngineer]`
- [x] **Task S5** — IDOR / 水平越权测试用例编写 — `[Done: council/SecurityEngineer]`
- [x] **Task S4** — 敏感操作审计日志设计 — `[Done: council/BackendArchitect]`

---

## Task S4 — 敏感操作审计日志设计 ✅ 设计完成

**表结构**：`vr_audit_log` 已在 `EventListener.php` 中定义（第99-121行），字段如下：

| 字段 | 类型 | 说明 |
|------|------|------|
| `action` | VARCHAR(60) | 操作类型：verify/export/refund/disable/enable/delete |
| `operator_id` | BIGINT | 操作用户ID（admin） |
| `operator_name` | VARCHAR(90) | 操作用户名（冗余） |
| `target_type` | VARCHAR(60) | 对象类型：ticket/verifier/seat_template |
| `target_id` | BIGINT | 对象ID |
| `target_desc` | VARCHAR(255) | 对象描述（冗余，便于查询） |
| `client_ip` | VARCHAR(45) | 客户端IP（支持IPv6） |
| `user_agent` | VARCHAR(512) | User-Agent |
| `request_id` | VARCHAR(64) | 请求追踪ID（UUID） |
| `extra` | LONGTEXT | 附加数据JSON（变更前后快照） |
| `created_at` | INT UNSIGNED | 操作时间戳 |

**索引**：`idx_action` / `idx_operator_id` / `idx_target(target_type,target_id)` / `idx_created_at`

**AuditService 接口设计**（待 Phase 3 实现）：

```php
// service/AuditService.php
class AuditService
{
    // 记录操作
    public static function log($action, $target_type, $target_id, $extra = []);

    // 自动从 Common 控制器获取 admin 上下文
    private static function getAdminContext();

    // 生成请求追踪ID
    private static function makeRequestId();
}
```

**集成点**（Phase 3 实现）：

| 控制器 | 方法 | action 值 | extra 快照 |
|--------|------|-----------|-----------|
| Ticket | `verify()` | `verify` | verify_status=0→1, verifier_id |
| Ticket | `export()` | `export` | goods_id, count |
| Ticket | `refund()` | `refund` | verify_status=0→2 |
| Verifier | `delete()` | `disable_verifier` | verifier_id, name |
| Verifier | `save()` | `enable_verifier` | verifier_id, name |
| SeatTemplate | `save()` | `edit_template` | template_id, name |
| SeatTemplate | `delete()` | `disable_template` | template_id, name |

> **防篡改策略**：表为 append-only，不提供 UPDATE/DELETE 接口；`operator_name` 冗余存储防止审计日志与 admin 表不同步时丢失身份。

---

## BackendArchitect Round 4 — P1 Bug Fix

### Verification.php:55 — `column()` 多字段映射 Bug（P1 已修复）

**问题**：`ThinkPHP column()` 不支持多字段映射，`column('seat_info,real_name,goods_id', 'id')` 返回结构与代码预期不符，导致核销记录列表页 `seat_info` / `real_name` / `goods_id` 为空。

**修复**：改用 `select()` + PHP foreach 拼接为 `$tickets[id] => row` 关联数组。

**文件**：`admin/controller/Verification.php` 第51-63行

---

## FrontendDev Round 4 — P1 Bug Fix

### ticket/list.html — 导出按钮 IS_AJAX_POST 不匹配 Bug（P1）

**问题**：`ticket/list.html:35` 导出按钮为 `<a>` 链接（GET 请求），但 `Ticket.php:export()` 要求 `IS_AJAX_POST`，导致点击"导出CSV"按钮返回"非法请求"错误。

**修复**：
- 视图：`ticket/list.html` 第35行 → `<a>` 链接改为 `<button type="button" id="export-btn">`，JS 动态创建 `<form method="post">` 提交
- 控制器：`Ticket.php:export()` 保留 `IS_AJAX_POST` 检查不变（保持安全），注释更新说明 POST-only 设计

**文件**：`admin/view/ticket/list.html` 第35行 + 第92-98行

---

## Issue #9 — 架构决策：票务 SKU 方案评议

> 核心问题：VR 演唱会票务"每个座位一个 SKU"（方案 A）vs "每个 Zone 一个 SKU"（方案 B）

### 评议问题清单

| # | 问题 | 优先级 |
|---|------|--------|
| Q1 | 方案 A 后台批量生成 SKU 路径是否可行？ShopXO 是否有批量 API？ | P0 |
| Q2 | 当前商品 112 的 broken 状态（is_exist_many_spec=0 + spec_base 空）是否需要紧急修复？最小修复集？ | P0 |
| Q3 | $vr- 前缀方案是否有隐患？ShopXO 内部是否对 $ 有特殊处理？ | P1 |
| Q4 | 方案 A vs 方案 B 最终推荐（实现成本 / 安全性 / 可维护性） | P0 |

### 任务分配

| Agent | 负责问题 | 行动项 |
|-------|---------|--------|
| SecurityEngineer | Q2/Q3/Q4 | 安全评估 + 最终推荐 |
| BackendArchitect | Q1 | SKU 生成路径分析 |
| FrontendDev | Q4 | 前端实现成本评估 |

### 阶段计划

- [ ] **Round 1**（本轮）：各 Agent 独立分析 → 更新 plan.md → 合并到 main
- [ ] **Round 2**：执行研究（代码探索 + 分析）→ 输出分析报告到 plan.md
- [ ] **Round 3**：Cross-review → 汇总 → 写入 `council-output/ARCHITECTURE_DECISION.md`

### 安全工程师分析（SecurityEngineer）

#### Q2：紧急修复优先级

**当前状态**：商品 112 的 broken 状态（is_exist_many_spec=0 + spec_base 空）
- ShopXO 防超卖机制完全未启用
- spec_base_id_map 指向不存在的 DB 记录

**最小修复集**：必须立即修复，但需确认走方案 A 还是 B
- [ ] **Pending** — 方案确定后，填充 spec_base 表（每个 SKU 一行）
- [ ] **Pending** — 设置 is_exist_many_spec = 1
- [ ] **Pending** — 关联 spec_base_id_map 与实际 seat 数据

**结论**：Q2 依赖 Q1/Q4 的输出，暂标记为 blocked。

#### Q3：$vr- 前缀安全隐患

**已知事实**：
- ShopXO spec name 允许特殊字符（$、-、中文均无过滤）
- ThinkPHP 模板引擎（View）可能对 $ 有变量插值行为

**风险点**：
- [ ] View 层：Tpl 模板中 `{:$spec_name}` 是否会解析 $vr- 作为 PHP 变量？
- [ ] DB 层：spec name 入库是否经过转义？
- [ ] API 层：spec name 作为 JSON key 时是否安全？

**结论**：需要代码验证（Round 2 执行）。

#### Q4：方案 A vs B 最终推荐

**初步倾向**：方案 A（每个座位一个 SKU）

**理由**：
1. 安全性：ShopXO 原生原子扣库存，无需自建锁，超卖风险最低
2. 正确性：与 ShopXO SPEC 机制对齐，is_exist_many_spec=1 时原生防超卖生效
3. 可追溯性：每个 SKU 独立订单项，核销链路清晰

**需 Round 2 验证**：
- 方案 A 后台 SKU 批量生成是否可行（BackendArchitect 输出）
- $vr- 前缀在 View 层是否安全（SecurityEngineer 验证）

### 行动项（优先级排序）

1. **[Claimed: council/SecurityEngineer]** Q3 — 验证 $vr- 前缀在 ThinkPHP View 层是否安全（Round 2）
2. **[Claimed: council/SecurityEngineer]** Q2 — 方案确定后给出最小修复集（Round 3）
3. **[Pending]** Q4 — 综合输出最终推荐报告（Round 3）

---

## 共识投票

[CONSENSUS: NO] — Phase 2 收尾；Issue #9 架构决策研究待 Round 2 执行