vr-shopxo-plugin/docs/PLAN_TREE_API_IMPLEMENTATION.md

# VR Tree API 实现计划

> 创建时间：2026-05-15
> 负责人：大头（代码实施）
> 参考文档：`docs/14_TREE_API_DESIGN.md`、`docs/TASK_TREE_API_IMPLEMENTATION.md`

---

## 一、设计确认

### 1.1 设计决策（已与大头确认）

| 决策项 | 结论 | 原因 |
|--------|------|------|
| spec_key 排序 | **字母顺序** | 未来扩展新维度时自动融入正确位置，无需修改排序逻辑 |
| tree 分组维度 | **4 层**（不含座位号） | 座位号是最底层扁平元素，与 SKU/库存绑定，通过 spec_key 前缀匹配查找 |
| inventory=0 | **保留并返回** | 便于前端座位图标记已售状态，与座位模板一一对应 |

### 1.2 spec_key 格式（已确定）

```
$vr-场次=15:00-16:59|$vr-场馆=鸟巢|$vr-演播室=主厅|$vr-分区=A|$vr-座位号=1排1座
   (按字母顺序排序)
```

> **重要**：前端生成 spec_key 时必须使用相同的字母排序规则。

---

## 二、实现任务清单

### Task 1: 创建 QueryManager 服务 ✅

**文件**: `service/QueryManager.php`（新建）

**核心方法**:
```php
class QueryManager
{
    /**
     * 主入口：生成层级树
     * @param int   $goodsId
     * @param array $groupBy  e.g. ['venue', 'session', 'room', 'section']
     * @param array $seatSpecMap
     * @return array ['tree' => [...], 'template_keys' => [...]]
     */
    public static function buildTree(int $goodsId, array $groupBy, array $seatSpecMap): array

    /**
     * 构建扁平 SKU 列表
     * @param array $seatSpecMap
     * @return array flat_inventory
     */
    public static function buildFlatInventory(array $seatSpecMap): array

    /**
     * 构建模板去重池
     * @param array $templateKeys
     * @return array seat_templates_flat
     */
    public static function buildTemplatePool(array $templateKeys): array
}
```

**分组维度映射**:
| group_by 值 | spec_key 前缀 | 对应维度 |
|-------------|---------------|----------|
| `venue` | `$vr-场馆=` | venueName |
| `session` | `$vr-场次=` | sessionName |
| `room` | `$vr-演播室=` | roomName |
| `section` | `$vr-分区=` | sectionName |

**层级树结构**（venue-first 示例）:
```php
[
    'tree' => [
        '鸟巢' => [
            'name' => '鸟巢',
            'min_price' => 280,
            'has_available' => true,
            'rooms' => [
                '主厅' => [
                    'name' => '主厅',
                    'min_price' => 380,
                    'has_available' => true,
                    'sections' => [
                        'A' => [
                            'template_key' => '鸟巢_主厅_A',
                            'price' => 680,
                            'inventory' => 12,
                            'has_available' => true
                        ],
                        // ...
                    ]
                ]
            ],
            'sessions' => [
                '15:00-16:59' => ['min_price' => 380, 'has_available' => true],
                '20:00-21:59' => ['min_price' => 280, 'has_available' => false]
            ]
        ]
    ]
]
```

---

### Task 2: 实现 tree() API 接口 ✅

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

**路由**:
```
GET /api.php?s=plugins/index&pluginsname=vr_ticket&pluginscontrol=goods&pluginsaction=tree&goods_id=118&group_by=venue,session,room,section
```

**实现**:
```php
public function tree()
{
    $goodsId = input('goods_id', 0, 'intval');
    $groupBy = input('group_by', 'venue,session,room,section', 'trim');
    $groupBy = array_filter(array_map('trim', explode(',', $groupBy)));

    if ($goodsId <= 0) {
        return self::error('goods_id 无效');
    }

    // 1. 缓存检查
    $cacheKey = 'vr_tree_' . $goodsId . '_' . md5(implode(',', $groupBy));
    $cached = \think\facade\Cache::get($cacheKey);
    if ($cached !== null) {
        $cached['meta']['cache_hit'] = true;
        return self::success($cached);
    }

    // 2. 读取数据源
    $seatMapData = SeatMapService::GetSeatMap($goodsId);
    $seatSpecMap = $seatMapData['seatSpecMap'] ?? [];

    // 3. 调用 QueryManager
    $treeData = QueryManager::buildTree($goodsId, $groupBy, $seatSpecMap);
    $flatInventory = QueryManager::buildFlatInventory($seatSpecMap);
    $templates = QueryManager::buildTemplatePool($treeData['template_keys'] ?? []);

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

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

    return self::success($result);
}
```

---

### Task 3: 处理缓存失效

**位置**: 订单支付成功回调

在 `SeatMapService::ClearCache()` 被调用时，同时清除 tree 缓存：
```php
// 清除所有 group_by 组合的 tree 缓存（可以存储一个 set 记录 key）
// 或简单清除带前缀的缓存
\think\facade\Cache::delete('vr_tree_' . $goodsId . '_');
```

---

## 三、实现顺序

| Step | 任务 | 文件 | 优先级 |
|------|------|------|--------|
| 1 | **创建 QueryManager** | QueryManager.php | 🔴 核心 |
| 2 | **实现 tree() API** | Goods.php | 🔴 核心 |
| 3 | 处理缓存失效 | 订单回调处 | 🟡 后续 |
| 4 | 前端适配 | ticket_detail.html | 🟡 后续 |

---

## 四、测试验证

### 4.1 修复验证（Step 1 后）
```bash
docker exec shopxo-php bash -c "php -r '
// 读取 goods_id=118 的 spec_key 样本
// 验证排序是否正确
'"
```

### 4.2 API 测试（Step 3 后）
```bash
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)
if d['code'] == 0:
    data = d['data']
    print('✅ flat_count:', data['meta']['flat_count'])
    print('✅ template_count:', data['meta']['template_count'])
    print('✅ venues:', list(data['tree'].keys()))
    print('✅ cache_hit:', data['meta']['cache_hit'])
else:
    print('❌ error:', d['msg'])
"
```

**预期结果**:
- `flat_count` > 0
- `template_count` << `flat_count`（模板去重生效）
- `cache_hit: false`（首次），`true`（后续请求）

---

## 五、风险评估

| 风险 | 概率 | 影响 | 缓解 |
|------|------|------|------|
| 前端 spec_key 生成逻辑不一致 | 中 | 高 | 前端必须使用与后端相同的字母排序规则 |
| 缓存失效时机 | 低 | 中 | 先实现缓存清除逻辑 |
| 大数据量性能 | 低 | 中 | 缓存 TTL=60s，定期失效 |

---

## 六、后续工作

1. **前端适配**: 修改 `ticket_detail.html` 的 spec_key 生成逻辑
2. **多模板支持**: 当前 design 支持多场馆×多模板，需要扩展
3. **inventory=0 处理**: 确认是否在 flat_inventory 中包含已售座位

---

*文档状态：规划完成，待实施*