vr-shopxo-plugin/docs/council-eval-backendarchitect.md

# Council 评估报告 — BackendArchitect（Round 3 更新）

> 评估日期：2026-05-26 | 角色：后端架构师 | Git: `0d6d20062`

---

## 一、现状评估（2026-05-26 现场核查）

### 1.1 Phase 4 Tree API 设计

**状态：📋 设计文档已提交，代码为零**

| 组件 | 状态 | 说明 |
|------|------|------|
| `docs/PHASE_4_API.md` | ✅ 存在（父仓库 commit `40a9b0ad1`） | Tree API 设计文档 |
| `docs/PLAN_TREE_API_IMPLEMENTATION.md` | ✅ 存在（父仓库 commit `40a9b0ad1`） | 实现计划 |
| `SeatMapService.php`（设计名） | ❌ **文件不存在** | 实际文件名为 `SeatSkuService.php` |
| `SeatSkuService.php`（实际） | ✅ 存在 | 但没有 `buildTree()` 方法 |
| `api/` 目录（Worktree） | ❌ **未纳入 Git 追踪** | 父仓库有 `api/Goods.php`，Worktree 为空 |
| `api/Goods.php::seatmap()` | ⚠️ 父仓库有，工作树无 | 调用不存在的 `SeatMapService::GetSeatMap()` |

**Round 3 修正**：`api/Goods.php` 在父仓库存在，有 `seatmap()` 方法，但父仓库 Worktree 隔离造成版本混淆。Tree API 设计完整，代码仅存在 `SeatSkuService::GetGoodsViewData()` 部分复用逻辑。

### 1.2 SeatMapService + seatmap API

**状态：⚠️ API 断裂，带运行时错误**

| 组件 | 状态 | 位置 |
|------|------|------|
| `index/Index.php::soldSeats` | ⚠️ 存在 | `index/Index.php:43` |
| `SeatSkuService::getSoldSeats()` | ❌ **完全缺失** | 被 `Index.php:43` 调用但方法不存在 |
| `index/Index.php::soldSeats` | ❌ **运行时崩溃** | PHP Fatal Error |
| `SeatSkuService::GetGoodsViewData()` | ✅ 完整 | 返

回 seatSpecMap + specTypeList |
| `SeatSkuService::buildSeatSpecMap()` | ✅ 完整 | `SeatSkuService.php:532` |
| `SeatSkuService::BatchGenerate()` | ✅ 完整 | 座位 SKU 批量生成 |

**严重性澄清**：Round 2 称 H5 绕过了 soldSeats API（正确），但忽略了 UniApp 的 `soldSeats` 端点调用会触发 PHP 致命错误。`ticket_detail.html` 自身正常，但所有直接调用 `soldSeats` API 的客户端都会崩溃。

**新增发现**：`api/Goods.php` 的 `seatmap()` 方法（父仓库）调用 `SeatMapService::GetSeatMap()`，但该类不存在（实际类名为 `SeatSkuService`，方法为 `GetGoodsViewData`）。这是 **命名混淆 Bug**。

### 1.3 seatSpecMap 注入商品详情 API

**状态：❌ Gap 仍成立**

| 组件 | 状态 | 说明 |
|------|------|------|
| `vr_goods_config` 表字段 | ✅ 存在 | `Event.php::Install()` 创建 |
| `SeatSkuService::GetGoodsViewData()` | ✅ 存在 | `SeatSkuService.php:369` |
| `Hook.php::plugins_service_goods_data` | ❌ **未注册** | `Hook.php:13-28` 无此 case |
| H5 `ticket_detail.html` | ✅ 工作正常 | 直接调用 `GetGoodsViewData()` |
| UniApp 商品详情 API | ❌ **Gap 1 成立** | Hook 不注册则无法触发 seatSpecMap 注入 |

**确认**：Gap 1 完全成立。H5 工作是因为 `ticket_detail.html` 是模板文件，在服务器端直接调用 `SeatSkuService::GetGoodsViewData()`。UniApp 走 API 层，`plugins_service_goods_data` Hook 不注册，则 ShopXO 的商品详情 API 不会触发 VR 座位数据注入。

### 1.4 CartSave extension_data 多座位链路

**状态：✅ H5 已验证，UniApp 只需复刻**

| 组件 | 状态 | 说明 |
|------|------|------|
| `ticket_detail.html:762` 订单提交 | ✅ 已实现 | `extension_data` 嵌套在 `order_base` |
| `TicketService::onOrderPaid()` | ✅ 已实现 | 逐行生成票（多座位支持） |
| UniApp CartSave | ✅ 与 H5 相同 JSON 格式 | Gap 2 已消除，只要后端提供端点即可 |

**Round 2 修正确认**：Gap 2 已验证可工作，核心问题变为"UniApp 需要相同的 API 端点格式"。

---

## 二、发现问题（Round 3 修正）

### P0（运行时崩溃，直接阻塞）

| # | 问题 | 位置 | 严重度 | Round 2 对比 |
|---|------|------|--------|-------------|
| P0-1 | `SeatSkuService::getSoldSeats()` **方法缺失** | `SeatSkuService.php`（末行为 `buildSeatSpecMap`，无此方法） | **致命** — `Index.php:43` 触发 PHP Fatal Error | 确认：Round 2 误判为"H5 绕过" |
| P0-2 | `plugins_service_goods_data` Hook **未注册** | `Hook.php:13-28`（无对应 case） | **致命** — UniApp 商品详情无法获取 seatSpecMap | 与 Round 2 一致 |

### P1（影响扩展性）

| # | 问题 | 位置 | 严重度 | Round 2 对比 |
|---|------|------|--------|-------------|
| P1-1 | `api/Goods.php::seatmap()` 引用不存在的 `SeatMapService` | `shopxo/app/plugins/vr_ticket/api/Goods.php:241` | **高** — 命名混淆，实际方法在 `SeatSkuService::GetGoodsViewData` | 新发现 |
| P1-2 | `api/` 目录未纳入 Git 追踪（Worktree） | 工作树 `shopxo/app/plugins/vr_ticket/api/` | **高** — 无法部署 / 无法协作 | 新发现 |
| P1-3 | Phase 4 Tree API 代码为零 | 无 `buildTree()` 方法 | **中** — 设计完备，代码未开始 | 与 Round 2 一致 |

---

## 三、技术方案建议

### P0-1 Fix：`getSoldSeats()` 实现

**文件**：`SeatSkuService.php`（追加到文件末尾）

```php
/**
 * 获取已售座位列表（seatKey 数组）
 *
 * 已售座位定义：inventory = 0 的 GoodsSpecBase 记录
 * seatKey 格式：roomId_rowLabel_colNum（如 "room_0_A_3"）
 *
 * @param int  $goodsId
 * @param int  $specBaseId  可选，限定查询
 * @return string[]
 */
public static function getSoldSeats(int $goodsId, int $specBaseId = 0): array
{
    if ($goodsId <= 0) return [];

    $query = \think\facade\Db::name('goods_spec_base')
        ->where('goods_id', $goodsId)
        ->where('inventory', 0);

    if ($specBaseId > 0) {
        $query->where('id', $specBaseId);
    }

    $soldSpecs = $query->select()->toArray();
    if (empty($soldSpecs)) return [];

    // 从 extends.seat_key 提取
    $seatKeys = [];
    foreach ($soldSpecs as $spec) {
        $extends = json_decode($spec['extends'] ?? '{}', true);
        $seatKey = $extends['seat_key'] ?? '';
        if (!empty($seatKey)) {
            $seatKeys[] = $seatKey;
        }
    }

    return $seatKeys;
}
```

**触发点**：`index/Index.php:43` 现有调用无需修改。

### P0-2 Fix：`plugins_service_goods_data` Hook 注册

**文件**：`Hook.php:13` 追加 case：

```php
case 'plugins_service_goods_data':
    $goodsId = $params['goods_id'] ?? 0;
    if ($goodsId > 0) {
        TicketService::InjectGoodsDetailData($params['data'], $goodsId);
    }
    break;
```

**新增方法**：`TicketService.php`（追加到文件末尾）：

```php
/**
 * 注入商品详情 VR 票务数据（通过 plugins_service_goods_data Hook）
 *
 * @param array &$data  ShopXO 商品详情数据（引用传递）
 * @param int    $goodsId
 */
public static function InjectGoodsDetailData(array &$data, int $goodsId): void
{
    if ($goodsId <= 0) return;

    $vrConfig = \think\facade\Db::name('goods')
        ->where('id', $goodsId)
        ->value('vr_goods_config');

    if (empty($vrConfig)) return;

    $viewData = SeatSkuService::GetGoodsViewData($goodsId);
    if (empty($viewData['vr_seat_template'])) return;

    $seatTemplate = $viewData['vr_seat_template'];

    // seatSpecMap：seat_key → 完整规格（含 row/col/room/section/price）
    $data['seatSpecMap'] = $viewData['seatSpecMap'] ?? [];
    // goods_spec_data：场次列表（含价格）
    $data['goods_spec_data'] = $viewData['goods_spec_data'] ?? [];
    // specTypeList：5维规格维度定义
    $data['specTypeList'] = $viewData['specTypeList'] ?? [];
    // seatMap：座位图渲染数据
    $data['seatMap'] = $seatTemplate['seat_map'] ?? null;
    // goods_config：当前生效的配置块
    $data['goods_config'] = $viewData['goods_config'] ?? null;
}
```

### P1 Fix：命名统一（SeatSkuService vs SeatMapService）

| 当前引用 | 应改为 | 位置 |
|---------|-------|------|
| `use app\plugins\vr_ticket\service\SeatMapService` | `use app\plugins\vr_ticket\service\SeatSkuService` | `shopxo/app/plugins/vr_ticket/api/Goods.php:12` |
| `SeatMapService::GetSeatMap` | `SeatSkuService::GetGoodsViewData` | `shopxo/app/plugins/vr_ticket/api/Goods.php:241` |

**注意**：此修复应在 `api/` 目录重新纳入 Git 追踪后执行。

---

## 四、优先级建议

| 优先级 | 任务 | 预计工时 | 收益 |
|--------|------|---------|------|
| **P0-1** | 实现 `getSoldSeats()` | 30min | 修复 soldSeats API 崩溃 |
| **P0-2** | Hook 注册 + `InjectGoodsDetailData()` | 1h | 解锁 UniApp 完整票务链路 |
| **P1-A** | `api/` 目录纳入 Git 追踪 + 命名修复 | 30min | 可部署、可协作 |
| **P1-B** | Phase 4 Tree API 实现（`buildTree()`） | 待定 | Phase 4 功能完成 |

**决策路径**：
1. 先修 P0-1 + P0-2（2h 内可完成）
2. 再推进 `api/` 目录规范化
3. Phase 4 在 P0/P1 稳定后作为独立任务启动

---

## 五、投票（Round 3）

**议题：下一步主攻方向**

**投票：A — 后端优先**

**理由**：

1. **最小改动最大收益**：`getSoldSeats()` 实现（30 行）+ Hook 注册（10 行）= 约 40 行代码，修复后 UniApp 票务链路全部解锁。这是最低成本的最高收益修复。

2. **运行时崩溃是根本阻塞**：Round 2 的"H5 已绕过"分析正确，但忽略了 `Index.php:soldSeats` 对所有直接调用 API 的客户端（UniApp / 第三方）都会触发 PHP 致命错误。必须修复。

3. **Hook 注册是 UniApp 的唯一入口**：Gap 1 对 H5 无影响（H5 走模板层直接调用），但对 UniApp 来说是唯一入口。没有 Hook 注册，UniApp 永远无法通过标准 API 获取 seatSpecMap。

4. **Gap 2（CartSave）已消除**：Round 2 确认 H5 已验证 extension_data 链路正确，UniApp 只需复刻同样的 JSON 结构，不存在后端缺口。

5. **Phase 4 不应前置**：Tree API 是体验增强，不是购买流程的基础设施，在核心票务链路（P0）未稳定前启动 Phase 4 是资源浪费。

**补充：对其他提案的评估**

- **B（前端优先）**：不可行。UniApp 选座组件需要 seatSpecMap 数据，但 Gap 1 不修则数据不可得。前端等 Hook 注册后再开发效率更高。
- **C（双线并行）**：在 P0 明确可修复的前提下，"双线并行"是浪费：前端等待期间无所事事，不如后端一次性修完再解锁前端。
- **D（Phase 4 优先）**：Phase 4 是锦上添花，不是基础设施。Tree API 失败不影响用户购票核心流程。

---

*报告人：BackendArchitect | 2026-05-26 | Round 3*