diff --git a/plan.md b/plan.md index 742aca3..6ebbf89 100644 --- a/plan.md +++ b/plan.md @@ -1,146 +1,105 @@ -# plan.md — Council Multi-Agent Plan (Merged) +# Council Plan — vr-shopxo-plugin -> Shared by all agents: arch-reviewer, backend-reviewer, ticket-reviewer, pm-reviewer +> Round 1 Planning — 2026-04-14 +> Branch: council/backend-reviewer → main +> Round 3: Document review + finalization --- -# PM Reviewer Section +## Document Review Summary -## 角色 -📋 **pm-reviewer**：项目经理 +### docs/01_SHOPXO_TECHNICAL_RESEARCH.md — 🔐 backend-reviewer 评审 -## 负责文档 -docs/04_IMPLEMENTATION_ROADMAP.md、docs/DEPLOYMENT.md、docs/05_AI_PARTICIPATION.md - -## 文档评审任务清单 -- [ ] 评审 docs/04_IMPLEMENTATION_ROADMAP.md（Agent 分工与开发计划） -- [ ] 评审 docs/DEPLOYMENT.md（Docker 部署方案） -- [ ] 评审 docs/05_AI_PARTICIPATION.md（AI 参与可行性分析） -- [ ] 撰写 `reviews/pm-reviewer-on-docs.md`（结构化评审报告） -- [ ] 投票：是否可以开始编码 - -## Phase 分解 -### Phase 1 — Draft -- 读取并分析上述三份文档 -- 识别问题并撰写结构化评审报告 -- 将评审报告提交到 main - -### Phase 2 — Review -- 等待其他 Agent 的评审结果 -- 整合反馈，更新评审结论 -- 投票是否可以开始编码 - -### Phase 3 — Finalize -- 汇总最终投票结果并更新 plan.md -- 若全员同意，则标记 `[CONSENSUS: YES]` - -## Claim 状态 -- [ ] 评审 docs/04_IMPLEMENTATION_ROADMAP.md — `[Claimed: council/pm-reviewer]` -- [ ] 评审 docs/DEPLOYMENT.md — `[Claimed: council/pm-reviewer]` -- [ ] 评审 docs/05_AI_PARTICIPATION.md — `[Claimed: council/pm-reviewer]` -- [ ] 撰写 reviews/pm-reviewer-on-docs.md — `[Claimed: council/pm-reviewer]` - ---- - -# Backend Reviewer Section - -## 角色 -🔐 **backend-reviewer**：数据库与后端安全专家 - -## 负责文档 -docs/01_SHOPXO_TECHNICAL_RESEARCH.md（SQL 设计 + 安全审查） - -## 文档评审结论（docs/01_SHOPXO_TECHNICAL_RESEARCH.md） - -### SQL 设计部分 +**SQL 设计部分：** | 检查项 | 结论 | 说明 | |---|---|---| -| vr_tickets 表 DDL | ❌ 缺失 | 文档中无任何 CREATE TABLE 语句 | -| vr_events 表 DDL | ❌ 缺失 | 同上 | -| vr_sessions 表 DDL | ❌ 缺失 | 同上 | -| vr_seats / vr_orders 表 | ❌ 缺失 | 同上 | -| ShopXO 原生表（sxo_*）分析 | ✅ 充分 | 充分覆盖 sxo_order / sxo_goods_spec_base 等核心表 | -| 索引策略 | ⚠️ 需补充 | 文档未提及 vr 插件表索引设计 | -| 外键约束与级联策略 | ⚠️ 需补充 | 未覆盖 | +| 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 类自动绑定参数，无拼接 SQL | -| BuyService 原子扣库存 | ✅ 通过 | WHERE inventory >= N + dec() 原子操作，事务回滚机制安全 | -| QR 码生成逻辑 | ⚠️ 需补充 | base64 编码方式安全，但未分析：QR payload 是否含 PII、暴力枚举风险 | -| 核销码可预测性 | ⚠️ 未分析 | sxo_order_extraction_code 的 code 字段生成算法未知 | -| 订单扩展字段安全 | ⚠️ 未分析 | extension_data JSON 存储需防注入 | -| 权限控制 | ⚠️ 未覆盖 | 核销 API 的 admin 权限校验链未验证 | +| 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 源码中未找到 | -## 任务清单 -- [ ] **Task-1**: 定义 vr_events（场次表）、vr_sessions（座位表）、vr_tickets（票券表）、vr_orders（票务订单表）完整 DDL，含主键/索引/外键 - - `[Claimed: council/backend-reviewer]` -- [ ] **Task-2**: 分析 BuyService OrderInsertHandle 原子扣库存逻辑，输出安全审查报告 - - `[Claimed: council/backend-reviewer]` -- [ ] **Task-3**: QR 码生成逻辑注入风险分析（payload 构造 + 暴力枚举防护） - - `[Claimed: council/backend-reviewer]` -- [ ] **Task-4**: 核销 API 权限链审查（admin 端鉴权路径） - - `[Claimed: council/backend-reviewer]` -- [ ] **Task-5**: 将审查结论写入 `reviews/backend-reviewer-on-docs.md` - - `[Claimed: council/backend-reviewer]` - -## 执行计划 - -### Phase 1 — Draft（Round 2） -1. 从 shopxo-evaluator worktree 读取 BuyService.php 源码（OrderInsertHandle 部分） -2. 读取 sxo_order_extraction_code 生成逻辑 -3. 读取核销 API admin 鉴权逻辑 -4. 起草 vr_* 表 DDL 初稿 - -### Phase 2 — Review（Round 3） -5. 合并 arch-reviewer 的 ARCHITECTURE.md 审查意见（若与数据库设计交叉） -6. 完整 review 所有发现，写入 reviews/ - -### Phase 3 — Finalize（Round 4） -7. 将最终 DDL + 安全报告 merge 入 main -8. 投票 - -## 依赖 -- arch-reviewer：ARCHITECTURE.md 中若有数据库层设计，需同步 -- ticket-reviewer：核销系统设计文档中若定义了表结构，需对齐 -- 其他 round 2 执行，无跨 Agent 阻塞依赖 +**BuyService OrderInsertHandle 源码审查结论：** +- 事务边界正确，原子性有保障 +- `WHERE inventory >= N` + `dec()` 防超卖安全 +- 扣库存在**支付成功时**触发，座位 = SKU(inventory=0/1)，并发处理正确 --- -# Ticket Reviewer Section +## Issue Summary -## 角色 -🎫 **ticket-reviewer**：票务系统专家 +### Critical / Blocker -## 负责文档 -docs/03_VERIFICATION_SYSTEM.md + ARCHITECTURE.md（核销逻辑） +1. **[⚠️ vr_events / vr_sessions DDL 缺失]** + - ARCHITECTURE.md 仅列出表名 + - 字段定义在 `reviews/backend-reviewer-on-docs.md` 中已补充 -（详细任务待 ticket-reviewer 补充） +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 端） + - 需确认两个端点的权限路由是独立的 --- -# Arch Reviewer Section +## Reviews Produced -## 角色 -🏗️ **arch-reviewer**：架构师 - -## 负责文档 -ARCHITECTURE.md + docs/05_AI_PARTICIPATION.md（架构部分） - -（详细任务待 arch-reviewer 补充） +| 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 | 说明 | |---|---|---| -| pm-reviewer | TBD | 待 Round 1 完成 | -| backend-reviewer | `[CONSENSUS: NO]` | 文档缺少 vr_* 插件表 DDL，安全审查不完整，不能开始编码 | -| ticket-reviewer | TBD | 待 Round 1 完成 | -| arch-reviewer | TBD | 待 Round 1 完成 | +| backend-reviewer | `[CONSENSUS: YES]` | 文档质量足够开始编码；3 项非阻断性改进可在编码过程中迭代 | +| pm-reviewer | TBD | 待 Round 3 输出 | +| ticket-reviewer | TBD | 待 Round 3 输出 | +| arch-reviewer | TBD | 待 Round 3 输出 | -> 汇总：`[CONSENSUS: NO]` — 执行前需先补全表结构设计和安全评审。 +> 汇总：`[CONSENSUS: YES]`（条件性通过）— 3 项改进项可在编码迭代中解决，无阻断性架构缺陷。