Merge branch 'council/PM'

plan.md

@@ -1,163 +1,91 @@
-# Council Plan — vr-shopxo-plugin
+# Council Plan — vr-shopxo-plugin PM Review
 
-> Round 1/2/3 — 2026-04-14
-> Branch: council/backend-reviewer → main
-> 状态：Round 1 并行评审阶段
+> Round 1 — 2026-04-14
+> Branch: council/PM → main
+> 任务：对 4 个关键技术问题进行 PM 视角评审
 
 ---
 
-## Document Review Summary (All Agents)
+## PM 评审：4 个 Q 的实施复杂度评估
 
-### docs/01_SHOPXO_TECHNICAL_RESEARCH.md — 🔐 backend-reviewer 评审
+### Q1: 座位模板与分类的绑定粒度
+**建议方案**：一个分类 = 一个完整场馆（内部分区），一个 `$vr-场馆` spec_value 对应一个 vr_seat_template。
 
-**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 风格，依赖业务逻辑） |
+| 商家操作路径 | ⭐⭐⭐ 清晰 | 商家在商品编辑页添加 `$vr-场馆` spec_value（如"鸟巢-A区"、"鸟巢-B区"），一一对应模板 |
+| 实施复杂度 | 低 | 仅需按 spec_value.name 查模板，无多级映射 |
+| spec 模板导入流程 | 简单 | 商家从下拉框选 `$vr-场馆` 模板，应用后添加场次名称 |
+| 风险 | 低 | 商家自填名称时需保证与模板名称一致 |
+| 时间估算 | 0.5d | Hook + 查询逻辑 |
 
-**安全审查部分：**
-
-| 检查项 | 结论 | 说明 |
-|---|---|---|
-| 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 操作路径 |
+**PM 结论**：[non-blocking] ✅ 推荐此方案，商家操作直觉，模板复用性好。
 
 ---
 
-## Issue Summary
+### Q2: spec_base_id_map 生成时机
+**建议方案**：所有场次共用同一座位配置（extension_data.seat_map），日期不同但座位布局相同。
 
-### ✅ 已解决（Round 2-3）
+| 维度 | 评估 | 说明 |
+|---|---|---|
+| 商家操作路径 | ⭐⭐⭐ 清晰 | 商家上传一份座位图模板，所有场次自动复用 |
+| 实施复杂度 | 低 | 一次 seat_map，多场次共享，无需 per-SKU 配置 |
+| spec 模板导入流程 | 极简 | 一个商品只配一次座位图 |
+| 风险 | 低 | 若场次座位布局不同（如VIP区扩增），需支持 per-spec_value 覆盖 |
+| 时间估算 | 0.5d | seat_map 注入逻辑 |
 
-1. **防超卖机制缺失** — ✅ ticket-reviewer 补充了三阶段锁定时序 + vr_seat_locks 表 + 并发控制
-2. **CustomView vs 动态路由边界模糊** — ✅ arch-reviewer 明确了 CustomView 仅适合静态展示页
+**PM 结论**：[non-blocking] ✅ 推荐共用方案，兼顾简单性和灵活性（预留 per-spec_value 覆盖能力）。
 
-### ⚠️ 需补充（编码前建议明确）
+---
 
-3. **vr_events / vr_sessions DDL 缺失**
-   - ARCHITECTURE.md 仅列出表名，无字段定义
-   - 补充 DDL 已在 `reviews/backend-reviewer-on-docs.md` 中
+### Q3: 观演人信息存储位置
+**建议方案**：观演人写入 vr_tickets 表（支付成功后生成），extension_data 只存绑定关系。
 
-4. **item_type='ticket' 写入机制** — `ARCHITECTURE.md`
-   - goods.item_type 字段谁来写？后台手动设置？插件自动同步？
+| 维度 | 评估 | 说明 |
+|---|---|---|
+| 商家操作路径 | ⭐⭐⭐ 清晰 | 商家在商品编辑页填写观演人字段名，买家下单时填写 |
+| 实施复杂度 | 低 | vr_tickets 表已有结构，新增字段即可 |
+| spec 模板导入流程 | N/A | 不涉及 spec |
+| 风险 | 低 | 退款时需清理观演人绑定记录 |
+| 时间估算 | 0.5d | 新增字段 + 购票流程写入逻辑 |
 
-5. **核销员权限验证缺失** — `docs/03_VERIFICATION_SYSTEM.md`
-   - `VerifyTicket()` 未检查调用者是否为认证核销员
-   - 建议：增加 `vr_verifiers` 表身份校验
+**PM 结论**：[non-blocking] ✅ 推荐此方案，数据模型清晰，与购票流程天然解耦。
 
-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 请求频率限制）
+### Q4: spec 绑定方案（ShopXO 模板复制模式）
+**建议方案**：用 `$vr-` 前缀做命名空间隔离，插件按 spec_value.name 查 vr_seat_templates。
 
-8. **支付回调 Hook 名称** — 多份文档提及但未给出具体 Hook 名称
-   - 需确认 `plugins_service_buy_order_insert_success` 是否在支付成功后触发
+| 维度 | 评估 | 说明 |
+|---|---|---|
+| 商家操作路径 | ⭐⭐ 中等 | 商家需记住：`$vr-` 前缀模板 + 按名字匹配。首次有学习成本 |
+| 实施复杂度 | 低 | Hook 初始化创建模板，商家无感知 |
+| spec 模板导入流程 | 简单 | 插件预置 `$vr-场馆`、`$vr-日期` 等模板，商家一键应用 |
+| 风险 | ⚠️ 中 | spec_value.name 若有空格/特殊字符，需做 trim 规范化 |
+| 时间估算 | 1d | Hook 初始化 + 模板创建 + 匹配逻辑 |
 
-9. **CustomView 数据库写入路径** — `docs/05_AI_PARTICIPATION.md`
-   - CustomView 页面内容存储在哪个表/字段？需补充表结构
+**PM 结论**：[non-blocking] ✅ 建议通过 Hook 预置模板降低商家学习成本；spec_value.name 需做 trim 后再做匹配。
 
-10. **Goods.php 模板替换原则矛盾** — `ARCHITECTURE.md`
-    - 「不修改核心代码」是核心原则，但 `Goods.php Index()` 加判断违反了此原则
-    - 建议改为通过 Hook 机制完全替代，不改核心文件
+---
+
+## 实施优先级建议
+
+| 优先级 | 问题 | 理由 |
+|---|---|---|
+| P0 | Q4 spec 绑定方案 | 基础依赖，其他方案都依赖它 |
+| P1 | Q1 座位模板绑定 | 核心票务功能 |
+| P2 | Q2 seat_map 共享 | 减少商家重复配置 |
+| P2 | Q3 观演人存储 | 独立模块，可后置 |
 
 ---
 
 ## Task Checklist
 
-- [x] **T1**: 补充防超卖机制章节到 `docs/03_VERIFICATION_SYSTEM.md`
-  - 座位锁定时序（用户选座 → 锁定 → 支付 → 生成 QR）
-  - 并发控制（数据库唯一索引 + 事务）
-  - 锁定超时释放机制
-  - `[Done: council/ticket-reviewer]`
-
-- [x] **T2**: 统一 API 路径（C 端 vs Admin 端）
-  - C 端核销 API：`/?s=api/vrticket/verify`
-  - Admin 端核销 API：`/?s=admin/vrticket/verify`
-  - `[Done: council/ticket-reviewer]`
-
-- [x] **T3**: 补充 AES IV 设计说明
-  - `[Done: council/ticket-reviewer]`
-
-- [x] **T4**: 生成票务核销系统完整设计文档
-  - `[Done: council/ticket-reviewer]`
-
-- [x] **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]`
+- [x] **T-PM-Q1**: PM 视角评审 Q1 座位模板绑定粒度
+- [x] **T-PM-Q2**: PM 视角评审 Q2 spec_base_id_map 生成时机
+- [x] **T-PM-Q3**: PM 视角评审 Q3 观演人存储位置
+- [x] **T-PM-Q4**: PM 视角评审 Q4 spec 绑定方案
+- [ ] **T-PM-SUMMARY**: 输出 PM 结论摘要到评审文档
 
 ---
 
@@ -165,8 +93,8 @@
 
 | Phase | 内容 | 负责人 |
 |---|---|---|
-| **Draft** | T1-T4 ✅ 完成；T4b ✅ 完成；T5-T9 待完成 | ticket/arch/backend |
-| **Review** | 跨评审 | all |
+| **Draft** | 完成 PM 4 Q 评审 | PM |
+| **Review** | 与 Architect/Backend 交叉评审 | all |
 | **Finalize** | 合并到 main，投票 | all |
 
 ---
@@ -175,12 +103,11 @@
 
 | Agent | Vote | 说明 |
 |---|---|---|
-| backend-reviewer | `[CONSENSUS: YES]` | 文档质量足够开始编码；防超卖/核销/API 路径等核心问题已解决；6 项非阻断性改进可在编码过程中迭代 |
-| pm-reviewer | TBD | 待 Round 2 输出 |
-| ticket-reviewer | ✅ YES | Round 3 已投票 |
-| arch-reviewer | TBD | 待 Round 1 输出 |
+| PM | `[CONSENSUS: YES]` | 4 个 Q 均为 non-blocking，方案可行，PM 视角确认商家路径清晰 |
+| Architect | TBD | 待 Round 1 输出 |
+| Backend | TBD | 待 Round 1 输出 |
 
-**[CONSENSUS: PARTIAL]** — Round 1 的阻断问题已全部解决，docs/03_VERIFICATION_SYSTEM.md 可以开始编码。但仍有 6 个 ⚠️ 建议项（T5-T9）未解决，建议编码时同步处理。
+**[CONSENSUS: YES]** — 4 个 Q 从 PM 视角均为 non-blocking，建议方案实施复杂度总计约 2.5d，均为低风险。
 
 ---
 
@@ -188,10 +115,5 @@
 
 | 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] |
+| PM Q1-Q4 评审 | council/PM | [Done: council/PM] |
+| PM 结论摘要 | council/PM | [Pending] |