council(draft): FrontendDeveloper - Round1 评估报告 + plan.md v2.0

- 新增 docs/council-eval-frontenddeveloper.md（投票 C：双线并行） - 更新 plan.md：H5 票务详情页无阻塞任务 + UniApp Gap 依赖关系 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-26 17:15:04 +08:00 · 2026-05-26 17:15:04 +08:00 · 2d3cbb1fb1
parent 40a9b0ad1d
commit 2d3cbb1fb1
2 changed files with 219 additions and 86 deletions
--- a/docs/council-eval-frontenddeveloper.md
+++ 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 是锦上添花，核心票务流程未完成
--- 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 设计文档 |