vr-shopxo-plugin/docs/TASK_TREE_API_IMPLEMENTATION.md

# Task Brief：VR Tree API 实现

> 目标：实现参数化层级生成器 API
> 参考文档：`docs/14_TREE_API_DESIGN.md`
> 状态：规划完成，待实现

---

## 背景

当前 `SeatMapService::GetSeatMap()` 返回扁平 `seatSpecMap`，前端需要 O(n²) 重建层级，且 session 作为顶层不符合业务逻辑。

新 API `/api/goods/tree` 返回：
1. **层级树**（按 `group_by` 参数动态生成，叶节点含 `template_key`）
2. **模板去重池**（`seat_templates_flat`，每个模板只存一份）
3. **扁平 SKU 列表**（用于前端本地 spec_key 前缀匹配）

---

## 实现步骤

### Step 1：验证现有数据结构

**验证文件**：
- `service/SeatSkuService.php` — 确认 `SPEC_DIMS` 顺序和 `makeSpecKey` 算法
- `service/SeatMapService.php` — 确认 `buildSeatSpecMap` 输出结构

**验证内容**：
1. `spec_key` 格式：维度按固定顺序排序，用 `|` 连接
2. `template_key` 生成：当前代码中是否有 venue+room+section 组合的模板 key？格式是什么？
3. seat_specMap 中的 `inventory=0` 座位是否被过滤？

```php
// 在 ShopXO Docker 容器里验证
docker exec shopxo-php bash -c "php -r '
// 读取 goods_id=118 的 seatSpecMap
// 打印前 3 条记录的 spec_key 格式
// 打印 template_snapshot 的 venue+rooms 结构
'"
```

### Step 2：实现 QueryManager 服务

**文件**：`service/QueryManager.php`

**核心方法**：
```php
class QueryManager
{
    // 主入口：生成层级树
    public static function buildTree(int $goodsId, array $groupBy): array

    // 分组聚合（核心逻辑）
    private static function aggregate(array $flatInventory, array $groupBy): array

    // 生成模板去重池
    private static function buildTemplatePool(array $flatInventory, array $tree): array

    // 生成扁平 SKU 列表（用于前端本地筛选）
    private static function buildFlatInventory(array $seatSpecMap): array
}
```

**聚合逻辑**：
```
输入：flatInventory (seatSpecMap), groupBy = ['venue', 'session', 'room', 'section']
输出：层级树

遍历每个 SKU：
  1. 解析 spec_key，提取各维度值
  2. 按 groupBy 顺序构建嵌套路径（如 tree[venue][session][room][section]）
  3. 累加 inventory，计算 min_price
  4. 生成 template_key = venue_venueName_room_roomName_section_sectionChar
  5. 标记 has_available = 累计 inventory > 0

模板去重：
  每个 section 节点只存 template_key，不存完整模板
  模板池在最后统一挂载（从 vr_seat_templates 表读取，或从 seatMap 数据提取）
```

### Step 3：实现 API 接口

**文件**：`api/Goods.php`

```php
/**
 * 获取层级树（含模板去重池 + 扁平 SKU）
 * GET /api.php?s=plugins/index&pluginsname=vr_ticket&pluginscontrol=goods&pluginsaction=tree&goods_id=118&group_by=venue,session,room,section
 */
public function tree()
{
    $goodsId = input('goods_id', 0, 'intval');
    $groupBy = input('group_by', 'venue,session,room,section', 'trim');  // 默认 venue-first
    $groupBy = array_filter(array_map('trim', explode(',', $groupBy)));

    if ($goodsId <= 0) {
        return ['code' => -1, 'msg' => 'goods_id 无效'];
    }

    // 缓存 key：goods_id + group_by 组合
    $cacheKey = 'vr_tree_' . $goodsId . '_' . md5(implode(',', $groupBy));
    $cached = \think\facade\Cache::get($cacheKey);
    if ($cached !== null) {
        $data = $cached;
        $data['meta']['cache_hit'] = true;
        return ['code' => 0, 'msg' => 'success', 'data' => $data];
    }

    // 1. 读取现有 seatSpecMap（复用 SeatMapService）
    $seatSpecMap = SeatMapService::GetSeatMap($goodsId)['seatSpecMap'] ?? [];

    // 2. 调用 QueryManager 构建树
    $tree = QueryManager::buildTree($goodsId, $groupBy, $seatSpecMap);

    // 3. 构建模板去重池
    $templates = QueryManager::buildTemplatePool($goodsId, $tree);

    // 4. 构建扁平 SKU 列表
    $flatInventory = QueryManager::buildFlatInventory($seatSpecMap);

    // 5. 组装响应
    $data = [
        'goods_id' => $goodsId,
        'group_by' => $groupBy,
        'tree' => $tree,
        'seat_templates_flat' => $templates,
        'flat_inventory' => $flatInventory,
        'meta' => [
            'flat_count' => count($flatInventory),
            'template_count' => count($templates),
            'cache_hit' => false,
            'computed_at' => time(),
        ],
    ];

    // 6. 写入缓存（TTL = 60s）
    \think\facade\Cache::set($cacheKey, $data, 60);

    return ['code' => 0, 'msg' => 'success', 'data' => $data];
}
```

### Step 4：模板去重池生成逻辑

```php
private static function buildTemplatePool(int $goodsId, array $tree): array
{
    $pool = [];

    // 遍历 tree，找到所有 template_key
    // 从 vr_seat_templates 表读取对应模板数据
    // key = template_key（如 "鸟巢_主厅_A"）
    // value = 模板的 map + sections + seats

    // 或者从 seatMap 数据直接提取（如果模板数据已在 seatMap 中）
    // 取决于当前数据结构中模板数据的存储位置

    return $pool;
}
```

**关键**：模板只按 `venue + "_" + room + "_" + section` 存储一份，不管有多少个 session。

### Step 5：前端适配（ticket_detail.html）

**改动点**：
1. 初始请求改用 `/api/goods/tree`（替换现有的 `GetGoodsViewData` PHP 渲染）
2. 从返回中提取 `tree` + `seat_templates_flat` + `flat_inventory`
3. 用 `tree` 渲染选择器（venue → session → room → section）
4. 用户选到 section 时：
   - 查 `tree[venue][session][room][section]['template_key']`
   - 查 `seat_templates_flat[template_key]` 获取座位图
   - 用 `flat_inventory` 做 spec_key 前缀匹配，标记可选座位

**spec_key 前缀匹配（前端 JS）**：
```javascript
function filterSeatsBySpec(flatInventory, selections) {
    // selections = { venue: '鸟巢', session: '15:00-16:59', room: '主厅', section: 'A' }
    // 构造前缀
    const prefix = '$vr-场馆=' + selections.venue +
                   '|$vr-场次=' + selections.session +
                   '|$vr-演播室=' + selections.room +
                   '|$vr-分区=' + selections.section + '|';

    return flatInventory.filter(sku =>
        sku.spec_key.startsWith(prefix) && sku.inventory > 0
    );
}
```

---

## 验证清单

实现完成后，用 curl 测试：

```bash
# 测试 venue-first（Joery 的场景）
curl "http://localhost:10000/api.php?s=plugins/index&pluginsname=vr_ticket&pluginscontrol=goods&pluginsaction=tree&goods_id=118&group_by=venue,session,room,section" \
  -H "X-Requested-With: XMLHttpRequest" | python3 -c "
import json,sys
d = json.load(sys.stdin)['data']
print('flat_count:', d['meta']['flat_count'])
print('template_count:', d['meta']['template_count'])
print('venues:', list(d['tree'].keys()))
"

# 测试 session-first
curl "http://localhost:10000/api.php?s=plugins/index&pluginsname=vr_ticket&pluginscontrol=goods&pluginsaction=tree&goods_id=118&group_by=session,venue,room,section" ...
```

---

## 注意事项

1. **不要删除现有代码**（SeatMapService / SeatSkuService），它们是数据源，新 API 依赖它们
2. **模板去重**：确保同一个 venue+room+section 的模板只出现一次在 `seat_templates_flat` 里
3. **缓存失效**：订单支付成功后调用 `SeatMapService::ClearCache()` 时，同时清除 tree 缓存
4. **inventory=0 的座位**：需要确认是否包含在 `flat_inventory` 里（前端的座位图需要知道哪些是已售的）
5. **spec_key 排序**：必须与前端使用的排序规则一致，否则前缀匹配失败