7.5 KiB

Raw Permalink Blame History

Task Brief：VR Tree API 实现

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

背景

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

新 API /api/goods/tree 返回：

层级树（按 group_by 参数动态生成，叶节点含 template_key）
模板去重池（seat_templates_flat，每个模板只存一份）
扁平 SKU 列表（用于前端本地 spec_key 前缀匹配）

实现步骤

Step 1：验证现有数据结构

验证文件：

service/SeatSkuService.php — 确认 SPEC_DIMS 顺序和 makeSpecKey 算法
service/SeatMapService.php — 确认 buildSeatSpecMap 输出结构

验证内容：

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

// 在 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

核心方法：

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

/**
 * 获取层级树（含模板去重池 + 扁平 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：模板去重池生成逻辑

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）

改动点：

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

spec_key 前缀匹配（前端 JS）：

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 测试：

# 测试 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" ...

注意事项

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

7.5 KiB Raw Permalink Blame History Unescape Escape