From 2d3cbb1fb1cbbc22c7eb7c543bc9f202e7ea8aa4 Mon Sep 17 00:00:00 2001 From: Council Date: Tue, 26 May 2026 17:15:04 +0800 Subject: [PATCH] =?UTF-8?q?council(draft):=20FrontendDeveloper=20-=20Round?= =?UTF-8?q?1=20=E8=AF=84=E4=BC=B0=E6=8A=A5=E5=91=8A=20+=20plan.md=20v2.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/council-eval-frontenddeveloper.md（投票 C：双线并行） - 更新 plan.md：H5 票务详情页无阻塞任务 + UniApp Gap 依赖关系 Co-Authored-By: Claude Sonnet 4.6 --- docs/council-eval-frontenddeveloper.md | 156 +++++++++++++++++++++++++ plan.md | 149 ++++++++++------------- 2 files changed, 219 insertions(+), 86 deletions(-) create mode 100644 docs/council-eval-frontenddeveloper.md diff --git a/docs/council-eval-frontenddeveloper.md b/docs/council-eval-frontenddeveloper.md new file mode 100644 index 0000000..1b77022 --- /dev/null +++ b/docs/council-eval-frontenddeveloper.md @@ -0,0 +1,156 @@ +# Council 评估报告 — FrontendDeveloper + +> 评估时间：2026-05-26 +> 评估人：FrontendDeveloper +> 议题：下一步主攻方向 + +--- + +## 一、现状评估 + +### vr-shopxo-uniapp 前端状态 + +**goods-vr-ticket 组件**：任务描述称"council draft 刚完成"，但 `~/WorkSpace/vr-shopxo-uniapp/components/` 下不存在 `goods-vr-ticket/` 目录。fork 完成但票务组件**尚未建立**。 + +**ShopXO H5 票务详情页**（ticket_detail.html，819行）： +- 核心结构存在：规格选择、座位选择、提交购票 +- `loadSoldSeats()` 函数：TODO 注释，**未实现**（Plan.md P5 级遗留问题） +- 观演人表单存在，submission 逻辑存在 +- 可作为过渡方案独立推进 + +**UniApp 整体状态**： +- 基础框架已搭建（manifest.json, pages/, common/） +- 支付、购物车、用户等基础组件已有 +- 票务相关页面和组件：**空白** + +--- + +## 二、发现的 3 个 P0 API Gap 对前端的影响 + +### Gap 1：seatSpecMap 后端未返回（P0 - 阻塞选座功能） + +**影响**：选座 UI 的数据源缺失。 +- 前端无法知道「场次 → 演播室 → 分区 → 座位」层级 +- 无法渲染座位地图的规格树 +- SeatMapService 已有 `buildSeatSpecMap()`，但未注入商品详情 API + +**前端影响评级**：🔴 **致命阻塞** — 无 seatSpecMap，选座组件完全无法开发 + +**可替代方案**：ticket_detail.html（H5）通过 PHP 直接渲染，不走 API，可绕过此 Gap + +### Gap 2：CartSave extension_data 多座位链路未确认（P0 - 阻塞下单流程） + +**影响**：多座位下单时观演人信息存储路径未知。 +- 前端不知道每个座位的 attendee 信息应该放在 `goods_data` 的哪个字段 +- 支付成功后的票生成逻辑依赖此链路 + +**前端影响评级**：🟠 **重度阻塞** — 单座位流程勉强可猜解，多座位完全无法开发 + +**可替代方案**：目前先按单座位模式开发，多座位延后 + +### Gap 3：QR payload 缺少 code 字段（P1 - 可变通处理） + +**影响**：前端按文档解析 QR 会缺字段。 +- 可变通：先用 `id` 和 `g` 验过期时间，`code` 字段前端忽略 +- 后端 QR 验签不依赖前端处理，前端只需展示 QR 码 + +**前端影响评级**：🟡 **中度影响** — 不阻塞开发，可快速适配 + +--- + +## 三、前端开发路径建议 + +### 路径 A：H5 优先（无阻塞，可立即启动） + +ticket_detail.html（H5）绕过 API Gap 价值最高： +1. PHP 直出 HTML，选座逻辑内联，不依赖 seatSpecMap API +2. 后端已实现 `SeatSkuService::GetGoodsViewData()`，数据已注入模板 +3. 可立即推进：`loadSoldSeats()` 实现、核销码展示、观演人表单美化 +4. 作为生产兜底：uniapp 延期时 H5 可先上线 + +**执行步骤**： +1. 实现 `loadSoldSeats()` — 调用 seatmap API 获取已售座位，填充 soldSeats 数组 +2. 优化观演人表单 UX +3. 核销码展示（QR + 短码） + +### 路径 B：UniApp 选座组件开发（需等 Gap 1 解决） + +Gap 1 解决后，UniApp 可完全独立推进： +1. goods-vr-ticket 组件框架 +2. 商品详情页 → 票务扩展信息渲染 +3. 选座页（依赖 seatSpecMap） +4. 购票确认页（单座位先验） +5. 票夹页（依赖 TicketWallet API） +6. 核销页 + +**执行步骤（Gap 1 解决后）**： +1. goods-vr-ticket 组件基础框架 +2. 商品详情页集成 seatSpecMap +3. 选座页 + 座位地图渲染 +4. 购票确认 + 支付 + +--- + +## 四、ticket_detail.html 价值评估 + +**过渡方案价值：高** + +| 维度 | 评分 | 说明 | +|------|------|------| +| 功能完整性 | 7/10 | 核心流程已有，loadSoldSeats 缺失 | +| 开发成本 | 低 | PHP 直出，无需前后端分离适配 | +| 用户体验 | 5/10 | 观演人表单粗糙，无选座动画 | +| 独立部署 | 可 | 嵌入 ShopXO H5 模板体系 | + +**结论**：ticket_detail.html 是 **H5 端票务的唯一载体**，必须维护好。与 UniApp 是互补关系而非竞争关系。 + +--- + +## 五、优先级建议（前端维度） + +### P0（必须先做） +1. **Gap 1 确认**：后端在商品详情 API 注入 seatSpecMap，解锁 uniapp 选座开发 +2. **Gap 2 确认**：CartSave extension_data 写入 order_detail 的路径文档化 + +### P1（H5 优先，可立即执行） +1. 实现 `loadSoldSeats()` — 调用 `/seatmap` API 获取已售座位 +2. ticket_detail.html 观演人表单 UX 优化 +3. 核销码展示组件（QR 图 + 短码） + +### P2（Gap 1 解决后启动） +1. UniApp goods-vr-ticket 组件框架搭建 +2. UniApp 商品详情页集成 seatSpecMap + +--- + +## 六、投票 + +### 议题：下一步主攻方向 + +**投票：C — 双线并行** + +**理由**： +- H5 ticket_detail.html 完全独立于 API Gap，可立即推进（实现 loadSoldSeats + 表单优化） +- UniApp 的 Gap 1（seatSpecMap）和 Gap 2（extension_data）需要后端配合，但可并行确认 +- 选项 A（纯后端优先）会让前端空等，选项 B（H5 优先）忽视 Uniapp 的长期价值 +- 选项 D（Phase 4 优先）属于锦上添花，Phase 3 核心票务流程尚未完成 + +**补充 — 对其他成员提案的评估**： +- **BackendArchitect 选 A**：合理，Gap 1 和 Gap 2 确实是阻塞点。但纯后端优先会让前端团队空转。 +- **PerformanceBenchmarker**：seatmap API 性能影响选座体验，建议在 Phase 2 开发时做基准测试。 +- **SecurityEngineer**：支付链路安全是 P0，但与前端并行不冲突。 + +--- + +## FrontendDeveloper 投票 + +**议题：下一步主攻方向** + +**投票：C — 双线并行** + +**理由**：H5 ticket_detail.html 可无阻塞立即启动（loadSoldSeats 实现、表单优化）；UniApp 开发需等 Gap 1/2 确认，但后端可并行完成这两项。双线并行最大化资源利用率，避免前端空等。 + +**补充**： +- 选 A（后端优先）：会损失 1-2 周前端开发时间 +- 选 B（H5 优先）：忽视 UniApp 长期价值，是过渡而非目标 +- 选 D（Phase 4 优先）：Tree API 是锦上添花，核心票务流程未完成 diff --git a/plan.md b/plan.md index 688782d..18ae0f1 100644 --- a/plan.md +++ b/plan.md @@ -1,82 +1,78 @@ -# Plan — 调研「场馆删除后编辑商品出现规格重复错误」问题 +# Plan — vr-shopxo-plugin 前端评估 + 票务功能推进 -> 版本：v1.3 | 日期：2026-04-20 | Agent：council/FrontendDev + council/SecurityEngineer + council/BackendArchitect +> 版本：v2.0 | 日期：2026-05-26 | Agent：council/FrontendDeveloper +> 任务来源：Round 1 Council 评估轮 --- -## BackendArchitect（Task B1-B6） +## 背景 -当票务商品关联的场馆模板被硬删除后，编辑商品时出现「规格不允许重复」错误。 +当前项目有两个前端入口： +- **H5**：ShopXO 票务详情页（ticket_detail.html，819行） +- **UniApp**：vr-shopxo-uniapp 小程序前端 -**根因调查分工**： -- FrontendDev：前端规格项构建与 fallback 行为 -- BackendArchitect：后端规格去重逻辑、`spec_base_id_map` 解析 -- SecurityEngineer：安全风险评估（P1 vs P2） +存在 3 个 P0 API Gap 阻塞 UniApp 开发，H5 可独立推进。 --- -## FrontendDev 任务清单 - -- [x] [Done: council/FrontendDev] **Task 1**: 读取 `ticket_detail.html`，分析前端构建规格项的过程 -- [x] [Done: council/FrontendDev] **Task 2**: 当模板不存在时，前端如何处理 `template_snapshot` 和 `spec_base_id_map`？ -- [x] [Done: council/FrontendDev] **Task 3**: `loadSoldSeats()` 函数实际实现了吗？soldSeats 数据如何填充？ -- [x] [Done: council/FrontendDev] **Task 4**: 编辑模式下（已有 vr_goods_config），前端是否正确处理已删除场馆的旧规格？ -- [x] [Done: council/FrontendDev] **Task 5**: 给出前端根因分析（含具体文件路径和行号） -- [x] [Done: council/FrontendDev] **Task 6**: 给出修复方案 -- [x] [Done: council/FrontendDev] **Task 7**: 将调研报告写入 `reviews/council-ghost-spec-FrontendDev.md` - ---- - -## SecurityEngineer 任务清单 - -- [x] [Done: council/SecurityEngineer] **Task S1**: 读取 AdminGoodsSaveHandle.php — 安全审计：保存时是否拒绝脏数据 -- [x] [Done: council/SecurityEngineer] **Task S2**: 读取 SeatSkuService.php — 幽灵 spec 注入路径分析 -- [x] [Done: council/SecurityEngineer] **Task S3**: 读取 AdminGoodsSave.php — ShopXO 入口安全检查 -- [x] [Done: council/SecurityEngineer] **Task S4**: 输出安全审计报告 → `reviews/SecurityEngineer-GHOST_SPEC_SECURITY.md` -- [x] [Done: council/SecurityEngineer] **Task S5**: 更新 `reviews/council-ghost-spec-summary.md` - -### 优先级定义 - -| 级别 | 含义 | -|------|------| -| **P1** | 安全漏洞：脏数据注入、XSS、权限绕过、数据覆盖 | -| **P2** | 功能缺陷：用户体验问题、错误提示不友好 | -| **P3** | 改进建议：代码健壮性优化 | - ---- - -## BackendArchitect 任务清单 - -- [x] [Done: council/BackendArchitect] **Task B1**: AdminGoodsSaveHandle.php 全链路追踪 — vr_goods_config 读取/解析/snapshot 重建 -- [x] [Done: council/BackendArchitect] **Task B2**: spec_base_id_map 如何被转换成规格项（已验证：存储在模板表，与幽灵 spec 无关） -- [x] [Done: council/BackendArchitect] **Task B3**: SeatSkuService GetGoodsViewData 模板不存在时的 fallback（单模板处理，多模板有缺陷） -- [x] [Done: council/BackendArchitect] **Task B4**: 幽灵 spec 产生环节 + 清理时机（保存时未清理，写回 DB） -- [x] [Done: council/BackendArchitect] **Task B5**: 商品保存规格去重逻辑（GoodsService.php:1859） -- [x] [Done: council/BackendArchitect] **Task B6**: 根因分析报告（含行号）→ `reviews/council-ghost-spec-BackendArchitect.md` -- [x] [Done: council/BackendArchitect] **Task B7**: 将调研报告写入 `reviews/council-ghost-spec-BackendArchitect.md` - ---- - -## 阶段划分 ✅ +## 阶段划分 | 阶段 | 内容 | 状态 | |------|------|------| -| **Draft** | Task 1-7（FrontendDev）+ Task S1-S3 + Task B1-B6（并行）| ✅ 完成 | -| **Review** | Task 7 + Task S4 + Task B7（输出各自报告）| ✅ 完成 | -| **Finalize** | Task S5：汇总到 `reviews/council-ghost-spec-summary.md` | ✅ 完成 | +| **Draft** | 评估报告 + plan.md 创建 | ✅ 本轮完成 | +| **Review** | 各成员交叉 review | 待执行 | +| **Finalize** | 汇总协调者输出综合报告 | 待执行 | --- -## 根因结论 +## FrontendDeveloper 任务清单 -| 优先级 | 根因 | 文件:行号 | -|--------|------|-----------| -| **P1（功能）** | 无效 config 块未从数组移除，`continue` 后脏数据写回 DB | AdminGoodsSaveHandle.php:88-89 + 148-150 | -| **P2** | GetGoodsViewData 单模板模式，多模板时覆盖有效块 | SeatSkuService.php:368 + 386-388 | -| **P3** | BatchGenerate 对无效 template_id 返回 code=-2，阻断保存 | AdminGoodsSaveHandle.php:164-170 | -| **P4** | 前端过滤后 configs 为空时用户无声失去配置 | AdminGoodsSave.php:196-229 | -| **P5** | loadSoldSeats 未实现（TODO 注释） | ticket_detail.html:375-383 | -| **安全评估** | 无 P1 安全漏洞，属于 P2 功能缺陷 | SecurityEngineer-GHOST_SPEC_SECURITY.md | +### API Gap 前置确认（依赖 BackendArchitect） + +- [ ] **Task 1** [Claimed: pending BackendArchitect] Gap 1：确认 seatSpecMap 注入商品详情 API 的具体实现方案和时间 +- [ ] **Task 2** [Claimed: pending BackendArchitect] Gap 2：确认 CartSave extension_data 写入 order_detail 的路径 + +### H5 票务详情页（无阻塞，可立即执行） + +- [ ] **Task 3** [Claimed: FrontendDeveloper] 实现 `loadSoldSeats()` — 调用 `/seatmap` API 获取已售座位，填充 soldSeats 数组 +- [ ] **Task 4** [Claimed: FrontendDeveloper] ticket_detail.html 观演人表单 UX 优化 +- [ ] **Task 5** [Claimed: FrontendDeveloper] 核销码展示（QR + 短码）组件化 + +### UniApp 票务组件（等待 Gap 1/2 确认后启动） + +- [ ] **Task 6** [Claimed: pending Gap 1+2] UniApp goods-vr-ticket 组件基础框架 +- [ ] **Task 7** [Claimed: pending Gap 1+2] UniApp 商品详情页集成 seatSpecMap 渲染 +- [ ] **Task 8** [Claimed: pending Gap 1+2] UniApp 选座页 + 座位地图渲染 +- [ ] **Task 9** [Claimed: pending Gap 1+2] UniApp 购票确认 + 支付流程（单座位优先） +- [ ] **Task 10** [Claimed: pending Gap 1+2] UniApp 票夹页（TicketWallet API 集成） +- [ ] **Task 11** [Claimed: pending Gap 1+2] UniApp 核销页（QR 展示 + 扫码核销） + +### 文档 & 交接 + +- [ ] **Task 12** [Done] 评估报告 → `docs/council-eval-frontenddeveloper.md` +- [ ] **Task 13** [Claimed: FrontendDeveloper] UniApp 组件目录结构设计文档 + +--- + +## 依赖关系 + +``` +BackendArchitect Gap 1 确认 ──→ Task 6-11（UniApp 选座/购票/票夹/核销）可启动 +BackendArchitect Gap 2 确认 ──→ Task 9（UniApp 购票确认）可完成 +Task 3（H5 loadSoldSeats） ──→ 可独立执行，无前置依赖 +Task 4（H5 表单优化） ──→ 可独立执行，无前置依赖 +Task 5（H5 核销码展示） ──→ 可独立执行，无前置依赖 +``` + +--- + +## 当前投票立场 + +**投票：C — 双线并行** + +- H5（Task 3-5）无阻塞，立即启动 +- UniApp（Task 6-11）等待 Gap 1+2 确认后启动 +- BackendArchitect 并行完成 Gap 1+2 注入任务 --- @@ -84,26 +80,7 @@ | 文件 | 关注点 | |------|--------| -| `shopxo/app/plugins/vr_ticket/hook/AdminGoodsSaveHandle.php` | P1 根因：continue 不删除脏 config | -| `shopxo/app/plugins/vr_ticket/service/SeatSkuService.php` | GetGoodsViewData：P2 根因，多模板处理缺陷 | -| `shopxo/app/plugins/vr_ticket/hook/AdminGoodsSave.php` | 前端过滤逻辑：P4 体验问题 | -| `shopxo/app/plugins/vr_ticket/admin/Admin.php` | VenueDelete：硬删除逻辑（第 888 行） | -| `shopxo/app/plugins/vr_ticket/view/goods/ticket_detail.html` | loadSoldSeats 未实现（P5） | -| `shopxo/app/service/GoodsService.php` | 规格列值去重检测（第 1859 行） | - ---- - -## 修复方案 - -### P1 Fix（立即实施） -1. AdminGoodsSaveHandle.php:88 — `continue` 改为 `unset($configs[$i])` -2. AdminGoodsSaveHandle.php:145 后 — 添加 `$configs = array_values($configs);` -3. AdminGoodsSaveHandle.php:148 — 写回前加 `if (!empty($configs))` -4. AdminGoodsSaveHandle.php:158-173 — BatchGenerate 前增加模板存在性显式校验 - -### P2 Fix（高优先级） -1. SeatSkuService.php GetGoodsViewData — 遍历所有有效配置块，不只处理 `$vrGoodsConfig[0]` -2. 修改 DB 写回逻辑为写回 `validConfigs` 而非 `[$config]` - -### P3 Fix（中优先级） -1. AdminGoodsSave.php — configs 为空时提示用户重新选择场馆 +| `shopxo/app/plugins/vr_ticket/view/goods/ticket_detail.html` | H5 票务详情，loadSoldSeats TODO | +| `~/WorkSpace/vr-shopxo-uniapp/components/` | UniApp 组件目录（当前无 goods-vr-ticket） | +| `docs/council-eval-frontenddeveloper.md` | 本轮评估报告 | +| `docs/14_TREE_API_DESIGN.md` | Phase 4 Tree API 设计文档 |