vr-shopxo-plugin/docs/PHASE2_PLAN.md

# Phase 2 — 计划与当前状态

> 版本：v2.0 | 日期：2026-04-20 | 状态：执行中
> 关联提交：c894e7018（模板渲染已通）、1b0ac3276（精简 footer）
> 关联文档：`docs/VR_GOODS_CONFIG_SPEC.md`（新 JSON 格式规格）

---

## ⚠️ 重大更新（v2.0）

**vr_goods_config JSON 格式已重新设计。**

旧格式依赖 `vr_seat_templates` 表实时查询，新格式在商品发布时将 `rooms` 快照存入商品表，前端不再跨表查询。

详见 `docs/VR_GOODS_CONFIG_SPEC.md`。

---

## 一、Phase 2 当前状态

### ✅ 已完成

| 任务 | 提交 | 说明 |
|------|------|------|
| 模板渲染 | c894e7018 | ThinkTemplate → PHP ModuleInclude，渲染正常 |
| 票务专用 footer | 1b0ac3276 | 精简 footer，移除 ShopXO 默认导航 |
| Goods.php 改法 | 7bd896764 | item_type=ticket → ticket_detail.html |
| onOrderPaid() 修复 | 7bd896764 | sxo_order_detail + JSON spec 解析 |

### ⚠️ 进行中

| 任务 | 说明 | 依赖 |
|------|------|------|
| GetGoodsViewData() 重写 | 适配新 vr_goods_config JSON 格式 | VR_GOODS_CONFIG_SPEC.md 已确认 |
| 前端 JS 更新 | 适配 rooms[] 结构渲染 | GetGoodsViewData() 输出格式确定后 |
| loadSoldSeats() 实现 | 查询 vr_tickets，标记已售座位 | vr_tickets 表有数据后 |

### ❌ 未开始

| 任务 | 说明 |
|------|------|
| AdminGoodsSaveHandle SKU 生成 | 根据 selected_rooms 生成 goods_spec_base 条目 |
| 后台 4 控制器联调 | SeatTemplate/Ticket/Verifier/Verification |
| 核销 API | POST /api/vr_ticket/verify |

---

## 二、vr_goods_config 新格式（已确认）

```json
[
  {
    "template_id": 4,
    "selected_rooms": ["room_id_xxx"],
    "selected_sections": { "room_id_xxx": ["A", "B"] },
    "rooms": [
      {
        "id": "room_id_xxx",
        "name": "1号放映室VV",
        "map": ["AAAAB__BBB_BAAAA", "AAAAB__BBB_BAAAA"],
        "sections": [
          { "char": "A", "name": "VIP区",  "price": 100, "color": "#f06292" },
          { "char": "B", "name": "看台区", "price": 50,  "color": "#4fc3f7" }
        ],
        "seats": {
          "A": { "char": "A", "name": "VIP区",  "price": 100, "color": "#f06292" },
          "B": { "char": "B", "name": "看台区", "price": 50,  "color": "#4fc3f7" }
        }
      }
    ],
    "sessions": [
      { "start": "15:00", "end": "16:59" },
      { "start": "18:00", "end": "21:59" }
    ]
  }
]
```

**核心变化**：
- `rooms[]` 包含完整座位图+sections+seats，不再查 `vr_seat_templates` 表
- `selected_sections` 控制每个房间内渲染哪些分区
- `spec_base_id_map` 格式：`{room_id}_{row}_{colNum}` → `spec_base_id`

完整规格见 `docs/VR_GOODS_CONFIG_SPEC.md`。

---

## 三、下一步工作

### Step 1（立即）：重写 GetGoodsViewData()

**目标**：适配新 JSON 格式，从 `goods.vr_goods_config` 直接读取 rooms[]，注入前端模板。

**新输出格式**：
```php
[
  'vr_seat_template' => [
    'rooms' => [...],              // 直接透传 vr_goods_config[0].rooms
    'sessions' => [...],          // 直接透传 vr_goods_config[0].sessions
    'selected_sections' => {...}, // 直接透传 vr_goods_config[0].selected_sections
  ],
  'goods_spec_data' => [...],    // 场次+价格（用于前端卡片）
  'goods_config' => {...}        // 原始 vr_goods_config[0]
]
```

**降级兼容**：若 `vr_goods_config` 中无 `rooms` 字段，按旧逻辑查 `vr_seat_templates` 表。

### Step 2（立即）：更新 ticket_detail.html JS

**目标**：适配 `rooms[]` 结构，多房间支持。

**改动点**：
1. `seatMap` → `rooms[]`（数组，每个房间一个座位图）
2. `renderSeatMap()` → `renderRoom(roomIndex)`（按房间渲染）
3. `specBaseIdMap` 格式变为 `{room_id}_{row}_{colNum}` → `spec_base_id`
4. `loadSoldSeats()` 实现：查 `vr_tickets.seat_info` 格式为 `room_id/rowLabel/colNum`

### Step 3：AdminGoodsSaveHandle SKU 生成

**目标**：用户选择房间后，在商品保存时自动生成 `goods_spec_base` SKU 条目。

**逻辑**：展开 rooms[].map，生成每个座位的 SKU，存入 `spec_base_id_map`。

---

## 四、模板渲染当前状态

| 项目 | 状态 |
|------|------|
| 模板渲染 | ✅ 正常（PHP ModuleInclude 方案） |
| 票务 footer | ✅ 已精简 |
| 场次显示 | ❌ 待适配新 JSON 格式 |
| 座位图渲染 | ❌ 待适配 rooms[] 结构 |
| 已售座位标记 | ❌ 待实现 loadSoldSeats() |

---

## 五、数据库表结构（当前）

| 表名 | 用途 | 状态 |
|------|------|------|
| `vrt_vr_seat_templates` | 场馆模板（rooms 母版） | ✅ |
| `vrt_vr_tickets` | 电子票 | ✅ |
| `vrt_vr_verifiers` | 核销员 | ✅ |
| `vrt_vr_verifications` | 核销记录 | ✅ |
| `goods.vr_goods_config` | 商品配置快照（新 JSON 格式） | ⚠️ 待适配 |
| `goods_spec_base` | SKU 库存（ShopXO 原生平表） | ⚠️ 待自动生成 |

---

## 六、已知风险

| 风险 | 影响 | 缓解 |
|------|------|------|
| vr_goods_config 仍是旧格式 | 场次/座位图不显示 | AdminGoodsSaveHandle 生成新格式后可解决 |
| 旧版 GetGoodsViewData 未适配新格式 | 前端无数据 | Step 1 完成后解决 |
| spec_base_id_map 格式变化 | 已选座位提交逻辑需同步更新 | Step 2 中同步更新 JS |