diff --git a/plan.md b/plan.md index 51d3ba5..86dee4b 100644 --- a/plan.md +++ b/plan.md @@ -1,6 +1,6 @@ # vr-shopxo-plugin Phase 2 — 后台管理开发计划 -> 版本:v1.1 | 制定日期:2026-04-15 | Agent:council/FrontendDev + council/SecurityEngineer 合并 +> 版本:v2.0(合并版)| 制定日期:2026-04-15 | Agent:council/FrontendDev + council/SecurityEngineer + council/BackendArchitect ## 概述 @@ -57,6 +57,12 @@ Phase 2 目标:完成后台管理页面开发,涵盖座位模板管理、电 - [ ] 鉴权中间件验证 - [ ] 敏感操作日志审计 +### 后端 API 任务 +- [ ] **Task B1** — 座位模板管理 CRUD — API + Controller `[Pending]` +- [ ] **Task B2** — 电子票列表 / 详情 / 导出 — API + Controller `[Pending]` +- [ ] **Task B3** — 核销员管理(增删改查)— API + Controller `[Pending]` +- [ ] **Task B4** — 核销记录查询 — API + Controller `[Pending]` + ### 安全任务 - [ ] **Task S1** — 审查 ShopXO 后台鉴权机制,确认 Phase 2 Base 控制器鉴权覆盖完整性 `[Pending]` - [ ] **Task S2** — SQL 注入风险审计,覆盖所有 Phase 2 数据查询 `[Pending]` @@ -181,15 +187,68 @@ Key Questions: --- +### 后端研究方向(BackendArchitect) + +#### BR-1: 后台 API 设计 — ThinkPHP 8 控制器层规范 +**背景**:ShopXO 基于 ThinkPHP 8,后台控制器需遵循其 Request/Response 约定,否则无法与现有 auth middleware 配合。 + +Key Questions: +- [ ] ShopXO Admin 控制器基类是什么?是否有统一的 `BaseAdmin` 或 `AdminController`? +- [ ] ThinkPHP 8 的 `Request` 对象如何获取当前登录 admin id / role? +- [ ] API 返回格式是统一 JSON 还是沿用 ShopXO 的 `Json` 渲染器? +- [ ] 分页参数命名规范:ShopXO 默认用 `page`/`limit` 还是 `page`/`pageSize`? +- [ ] 新增 controller 是否需要在某个注册处声明(路由/菜单)? + +#### BR-2: 权限模型 — 多角色鉴权设计 +**背景**:核销员(vr_verifiers)与超级管理员属于不同角色,后台功能需要细粒度权限控制。 + +Key Questions: +- [ ] ShopXO admin 用户表(`sx_admin`)的 role 字段结构是怎样的?是 RBAC 吗? +- [ ] 核销员是否复用 admin 表,还是独立表(`vr_verifiers`)?各自权限如何隔离? +- [ ] 座位模板编辑 / 电子票导出 / 核销记录查看是否需要分开授权? +- [ ] 是否有现成的权限中间件可以复用,还是需要自行实现? + +#### BR-3: 数据库查询优化 — 大数据量导出场景 +**背景**:电子票列表 + 核销记录在数据量大时有分页和内存压力。 + +Key Questions: +- [ ] `vr_tickets` / `vr_verifications` 当前预估数据规模?是否需要游标分页? +- [ ] 导出功能(CSV/Excel)PHP 侧是否需要流式输出避免 OOM? +- [ ] `vr_verifications` 的 `verified_at` 字段是否建索引? +- [ ] 是否需要读写分离?ShopXO 数据层是否支持? +- [ ] 是否有批量查询 N+1 问题(如查询票时重复查 holder info)? + +#### BR-4: 事务一致性 — 核销操作的原子性 +**背景**:核销涉及两张表(`vr_verifications` 写入 + `vr_tickets.status` 更新),若并发核销同一票会导致重复核销。 + +Key Questions: +- [ ] ThinkPHP 8 Db facade 的事务写法(`Db::transaction()`)如何与 Model 层配合? +- [ ] 是否需要悲观锁(`SELECT ... FOR UPDATE`)防止并发核销? +- [ ] 乐观锁(version 字段)是否适用于高并发核销场景? +- [ ] 核销失败后的补偿逻辑如何设计? + +#### BR-5: 存储过程 / 事件驱动 — 核销通知异步化 +**背景**:核销操作可能触发通知(站内信/微信),同步执行会阻塞核销响应。 + +Key Questions: +- [ ] ShopXO 是否有事件/队列机制(Redis/DB queue)? +- [ ] ThinkPHP 8 的 `Queue::later()` 或 `event()` 是否可用? +- [ ] 若无队列,核销通知是否可以降级为同步日志+后台任务补偿? +- [ ] 是否需要记录核销操作的 event log 供后续审计? + +--- + ## 依赖关系 -- FR-1、FR-2 优先完成,决定技术栈选型 -- FR-3 依赖 FR-1 的选型结论 -- FR-4 可在 Phase 3 后端 API 确定后并行进行 -- FR-5 与 SecurityEngineer 协同,需要等 BackendArchitect 输出权限模型 -- Task S1(鉴权审查)需在 BackendArchitect 完成 API 设计初稿后进行交叉评审 -- Task S2(SQL 审计)可与 BackendArchitect 的数据库设计并行 -- Task S4(审计日志)依赖最终的数据模型设计 +- **FR-1、FR-2** 优先完成,决定前端技术栈选型 +- **FR-3** 依赖 FR-1 的选型结论 +- **FR-4** 可在 Phase 3 后端 API 确定后并行进行 +- **FR-5** 与 SecurityEngineer 协同,需要等 BackendArchitect 输出权限模型 +- **Task S1**(鉴权审查)需在 BackendArchitect 完成 API 设计初稿后进行交叉评审 +- **Task S2**(SQL 审计)可与 BackendArchitect 的数据库设计并行 +- **Task S4**(审计日志)依赖最终的数据模型设计 +- **BR-1**(ThinkPHP 控制器规范)与 **FR-1** 交叉确认 API 返回格式 +- **BR-2**(权限模型)与 **FR-5** 协同,需 BackendArchitect 和 SecurityEngineer 共同输出 ---