17 KiB
17 KiB
商品详情扩展字段数据字典与前端使用说明
日期：2026-04-21 用途：前端 agent（antigravity / cursor）拿到商品详情页时，扩展字段里有哪些可用数据？如何用？
一、核心数据结构全貌
商品详情页加载时，PHP 后端向模板注入以下变量：
| 模板变量名 | 来源 | 说明 |
|---|---|---|
$goods |
ShopXO GoodsService | ShopXO 原生商品数据（id/title/price/content/images 等） |
$vr_seat_template |
SeatSkuService::GetGoodsViewData() |
票务插件扩展数据 |
$goods_spec_data |
SeatSkuService::GetGoodsViewData() |
场次列表 |
二、vr_goods_config（goods 表扩展字段）
存储位置：goods.vr_goods_config（JSON 字段）
这是商品发布时由管理员配置的数据快照，前端只能读，不能写。
完整 JSON 示例（商品 118，VR 演唱会）
[
{
"version": 3.0,
"template_id": 4,
"selected_rooms": ["room_001", "room_002"],
"selected_sections": {
"room_001": ["A", "B"],
"room_002": ["A"]
},
"sessions": [
{ "start": "15:00", "end": "16:59" },
{ "start": "18:00", "end": "20:59" }
],
"template_snapshot": {
"venue": {
"name": "VR 体验馆",
"address": "北京市朝阳区建国路88号",
"location": { "lng": "116.45792", "lat": "39.90745" },
"images": [
"/static/attachments/202603/venue_001.jpg",
"/static/attachments/202603/venue_002.jpg"
]
},
"rooms": [
{
"id": "room_001",
"name": "1号演播厅",
"map": [
"AAAAA_____BBBBB",
"AAAAA_____BBBBB",
"AAAAA_____BBBBB",
"CCCCCCCCCCCCCCC",
"CCCCCCCCCCCCCCC"
],
"sections": [
{ "char": "A", "name": "VIP区", "price": 380, "color": "#f06292" },
{ "char": "B", "name": "看台区", "price": 180, "color": "#4fc3f7" },
{ "char": "C", "name": "普通区", "price": 80, "color": "#81c784" }
],
"seats": {
"A": { "char": "A", "name": "VIP区", "price": 380, "color": "#f06292" },
"B": { "char": "B", "name": "看台区", "price": 180, "color": "#4fc3f7" },
"C": { "char": "C", "name": "普通区", "price": 80, "color": "#81c784" }
}
},
{
"id": "room_002",
"name": "2号演播厅（副厅）",
"map": [
"DDDDDDD",
"DDDDDDD",
"EEEEEEE"
],
"sections": [
{ "char": "D", "name": "互动区", "price": 280, "color": "#ffb74d" },
{ "char": "E", "name": "站票区", "price": 50, "color": "#90a4ae" }
],
"seats": {
"D": { "char": "D", "name": "互动区", "price": 280, "color": "#ffb74d" },
"E": "char": "E", "name": "站票区", "price": 50, "color": "#90a4ae" }
}
}
]
}
}
]
字段说明表
顶层字段
| 字段 | 类型 | 前端可用性 | 说明 |
|---|---|---|---|
version |
float | ⚪ 不需要 | 协议版本，用于兼容判断 |
template_id |
int | ⚪ 不需要 | 关联的座位模板 ID，内部使用 |
selected_rooms |
string[] | ✅ 可用 | 用户在后台选中的房间 ID 列表 |
selected_sections |
object | ✅ 可用 | key=房间ID，value=该房间选中的分区字符数组 |
sessions |
object[] | ✅ 可用（重要） | 场次列表，每个场次有 start/end/price |
template_snapshot |
object | ✅ 可用（核心） | 座位图的完整快照，前端渲染数据来源 |
template_snapshot.venue
| 字段 | 前端可用性 | 说明 |
|---|---|---|
name |
✅ 可用 | 场馆名称（用于展示） |
address |
✅ 可用 | 场馆地址（用于展示） |
location.lng/lat |
⚠️ 可选 | 经纬度，用于地图展示 |
images |
✅ 可用 | 场馆图片列表（用于顶部 Banner） |
template_snapshot.rooms[]（每个房间）
| 字段 | 前端可用性 | 说明 |
|---|---|---|
id |
✅ 可用（重要） | 房间唯一 ID，用于前端 seatKey 构造 |
name |
✅ 可用 | 房间名称（用于场馆切换选择器） |
map |
✅ 可用（核心） | 座位图字符矩阵，用于渲染座位行 |
sections[] |
✅ 可用 | 分区列表（char→name/price/color，用于图例 + 分区切换） |
seats |
✅ 可用 | char→座位属性映射，用于查找座位详情 |
template_snapshot.rooms[].map 格式说明
map 是一个字符串数组，每行对应座位图的一行：
["AAAAA_____BBBBB", "AAAAA_____BBBBB"]
- 字符
'A'/'B'/'C'= 座位（char），通过seats[char]查到座位属性（分区/价格/颜色） - 字符
'_'= 空位（不渲染座位元素） - 字符
'-'= 空位（不渲染座位元素） - 其他非字母字符 = 不渲染
如何从 map 渲染座位：
// map = ["AAAAA_____BBBBB", "AAAAA_____BBBBB"]
map.forEach(function(rowStr, rowIndex) {
var rowLabel = String.fromCharCode(65 + rowIndex); // 0→A, 1→B, ...
var chars = rowStr.split(''); // ['A','A','A','A','A','_',...,'B','B','B','B','B']
chars.forEach(function(char, colIndex) {
if (char === '_' || char === '-') return; // 跳过空位
var seatInfo = rooms[i].seats[char]; // 查到座位属性
// colIndex + 1 = colNum（列号，从1开始）
});
});
注意：PHP mb_str_split() 在某些环境不可用，用 split('') 即可（座位字符都是 ASCII）。
三、GetGoodsViewData() 注入的模板数据
这是后端处理后注入到模板的变量，前端可以直接使用。
3.1 注入变量总览
// Goods.php 票务判断块
$viewData = \app\plugins\vr_ticket\service\SeatSkuService::GetGoodsViewData($goods_id);
MyViewAssign([
'vr_seat_template' => $viewData['vr_seat_template'], // 座位图数据
'goods_spec_data' => $viewData['goods_spec_data'], // 场次列表
// 【待新增】
'seatSpecMap' => $viewData['seatSpecMap'] ?? [], // 座位→规格映射
]);
3.2 vr_seat_template（注入后模板中访问 $vr_seat_template）
// PHP 模板输出（JSON 注入）
var vrSeatTemplate = <?php echo json_encode($vr_seat_template ?? [], JSON_UNESCAPED_UNICODE); ?>;
var seatSpecMap = <?php echo json_encode($seatSpecMap ?? [], JSON_UNESCAPED_UNICODE); ?>;
var goodsSpecData = <?php echo json_encode($goods_spec_data ?? [], JSON_UNESCAPED_UNICODE); ?>;
vr_seat_template 数据结构
{
// === 直接透传 template_snapshot（来源：goods.vr_goods_config）===
venue: {
name: "VR 体验馆",
address: "北京市朝阳区建国路88号",
location: { lng: "116.45792", lat: "39.90745" },
images: ["/static/attachments/202603/venue_001.jpg"]
},
rooms: [
{
id: "room_001",
name: "1号演播厅",
map: ["AAAAA_____BBBBB", "AAAAA_____BBBBB", "AAAAA_____BBBBB", "CCCCCCCCCCCCCCC", "CCCCCCCCCCCCCCC"],
sections: [
{ char: "A", name: "VIP区", price: 380, color: "#f06292" },
{ char: "B", name: "看台区", price: 180, color: "#4fc3f7" },
{ char: "C", name: "普通区", price: 80, color: "#81c784" }
],
seats: {
A: { char: "A", name: "VIP区", price: 380, color: "#f06292" },
B: { char: "B", name: "看台区", price: 180, color: "#4fc3f7" },
C: { char: "C", name: "普通区", price: 80, color: "#81c784" }
}
},
{
id: "room_002",
name: "2号演播厅（副厅）",
map: ["DDDDDDD", "DDDDDDD", "EEEEEEE"],
sections: [
{ char: "D", name: "互动区", price: 280, color: "#ffb74d" },
{ char: "E", name: "站票区", price: 50, color: "#90a4ae" }
],
seats: {
D: { char: "D", name: "互动区", price: 280, color: "#ffb74d" },
E: { char: "E", name: "站票区", price: 50, color: "#90a4ae" }
}
}
],
sessions: [
{ start: "15:00", end: "16:59" },
{ start: "18:00", end: "20:59" }
],
// === 来自 goods.vr_goods_config 的原始选择数据 ===
selectedRooms: ["room_001", "room_002"],
selectedSections: {
"room_001": ["A", "B"],
"room_002": ["A"]
}
}
goods_spec_data（场次列表）
// 来源：goods.vr_goods_config.sessions + GoodsSpecBase.price
[
{ spec_id: 2001, spec_name: "15:00-16:59", price: 380, start: "15:00", end: "16:59" },
{ spec_id: 2002, spec_name: "18:00-20:59", price: 280, start: "18:00", end: "20:59" }
]
// ⚠️ 注意：spec_id 是 GoodsSpecBase ID（场次级别，非座位级别）
// 前端不需要直接使用 spec_id，直接使用 sessions 数组即可
3.3 seatSpecMap（待新增：GetGoodsViewData 返回的核心数据）
来源：GetGoodsViewData() 查询 GoodsSpecBase + GoodsSpecValue + GoodsSpecBase.extends，动态构建
用途：前端选中座位后，查表获取该座位的完整 4 维 spec 数组 + 对应 spec_base_id
// key 格式：{roomId}_{rowLabel}_{colNum}
// 例如：room_001_A_3 = room_001 的 A排 第3列
{
"room_001_A_1": {
spec_base_id: 10001,
price: 380,
inventory: 1,
rowLabel: "A",
colNum: 3,
roomId: "room_001",
section: { char: "A", name: "VIP区", color: "#f06292" },
// === 4维 spec 数组（submit() 时直接使用）===
spec: [
{ type: "$vr-场馆", value: "VR 体验馆" },
{ type: "$vr-分区", value: "VR 体验馆-1号演播厅-VIP区" },
{ type: "$vr-座位号", value: "VR 体验馆-1号演播厅-VIP区-A-1排3座" },
{ type: "$vr-场次", value: "15:00-16:59" }
]
},
"room_001_A_2": { spec_base_id: 10002, price: 380, inventory: 1, /* ... */ },
"room_001_A_3": { /* 同上，A排第3座 */ },
"room_001_B_8": { spec_base_id: 10025, price: 180, inventory: 0, /* 已售 */ },
"room_002_D_1": { spec_base_id: 20001, price: 280, inventory: 1, /* ... */ },
// ... 每个可购座位一行
}
seatSpecMap 生成逻辑（GetGoodsViewData 中实现）
// 1. 查询所有有效 GoodsSpecBase（含 extends.seat_key）
$specs = Db::name('GoodsSpecBase')
->where('goods_id', $goodsId)
->where('inventory', '>', 0) // 只取有库存的
->select();
// 2. 查询对应的 GoodsSpecValue（4个维度的值）
$specIds = array_column($specs->toArray(), 'id');
$specValues = Db::name('GoodsSpecValue')
->whereIn('goods_spec_base_id', $specIds)
->select();
// 3. 按 spec_base_id 分组，构建 4维 spec 数组
$specByBaseId = [];
foreach ($specValues as $sv) {
$specByBaseId[$sv['goods_spec_base_id']][] = [
'type' => $sv['type'], // "$vr-场馆" / "$vr-分区" / "$vr-座位号" / "$vr-场次"
'value' => $sv['value'], // 完整路径字符串
];
}
// 4. 构建 seatSpecMap
$seatSpecMap = [];
foreach ($specs as $spec) {
$extends = json_decode($spec['extends'] ?? '{}', true);
$seatKey = $extends['seat_key'] ?? ''; // "room_001_A_3" 格式
if (empty($seatKey)) continue;
$seatSpecMap[$seatKey] = [
'spec_base_id' => intval($spec['id']),
'price' => floatval($spec['price']),
'inventory' => intval($spec['inventory']),
'spec' => $specByBaseId[$spec['id']] ?? [],
];
}
四、前端数据使用对照表
4.1 渲染座位图（使用 vr_seat_template）
数据来源：vr_seat_template.rooms[].map
↓
渲染流程：
rooms[i].map.forEach((rowStr, rowIndex) => {
chars = rowStr.split('') // 逐字符
chars.forEach((char, colIndex) => {
if (char === '_') → 跳过（空位）
seatInfo = rooms[i].seats[char] // 通过 char 查座位属性
seatKey = rooms[i].id + '_' + rowLabel + '_' + (colIndex+1)
// rowLabel = String.fromCharCode(65 + rowIndex) // A/B/C...
});
});
前端关键变量：
- rooms[i].id → roomId（用于 seatKey 构造）
- rooms[i].map → 座位行渲染数据
- rooms[i].seats[char] → 座位属性（name/price/color）
- rooms[i].sections → 图例 + 分区切换
- vrSeatTemplate.selectedRooms → 当前选中的房间列表
- vrSeatTemplate.selectedSections → 当前选中的分区
4.2 构建 spec 数组（使用 seatSpecMap）
数据来源：seatSpecMap[seatKey]
↓
选中座位后：
seatKey = clickedEl.dataset.rowLabel + '_' + clickedEl.dataset.colNum
= "room_001_A_3"
seatInfo = seatSpecMap[seatKey]
submit() 时使用：
goods_data[i].spec = seatInfo.spec // 4维完整 spec 数组！
goods_data[i].stock = 1
ShopXO BuyService 匹配：
→ GoodsSpecValue WHERE type="$vr-场馆" AND value="VR 体验馆"
AND type="$vr-分区" AND value="VR 体验馆-1号演播厅-VIP区"
AND type="$vr-座位号" AND value="VR 体验馆-1号演播厅-VIP区-A-1排3座"
AND type="$vr-场次" AND value="15:00-16:59"
→ 返回 spec_base_id → 拿到 inventory=1, price=380
4.3 spec 选择器联动过滤（使用 seatSpecMap）
数据来源：seatSpecMap（所有座位的完整信息）
↓
filterSeatMap(currentSession, currentVenueId, currentSectionChar):
seatSpecMap 的每一个 entry：
seatInfo.spec 是一个4元素数组
判断逻辑（某座位是否在当前选择分支内）：
hasSession = spec.some(s => s.type==='$vr-场次' && s.value===currentSessionValue)
hasVenue = spec.some(s => s.type==='$vr-场馆' && s.value.includes(currentVenueName))
hasSection = !currentSectionChar || spec.some(s => s.type==='$vr-分区' && s.value.includes(currentSectionChar))
isAvailable = seatInfo.inventory > 0
结果：
hasSession && hasVenue && hasSection && isAvailable → 可选（正常显示）
hasSession && hasVenue && hasSection && !isAvailable → 已售（灰色+sold class）
否则 → 不在分支内（灰色+disabled class）
4.4 加载已售座位（使用 seatSpecMap.inventory）
数据来源：seatSpecMap[seatKey].inventory
↓
页面初始化时，遍历 seatSpecMap：
Object.entries(seatSpecMap).forEach(([seatKey, seatInfo]) => {
if (seatInfo.inventory <= 0) {
// 该座位已售
document.querySelector(`[data-seat-key="${seatKey}"]`).classList.add('sold');
}
});
⚠️ 注意：inventory 字段来自 GoodsSpecBase，库存扣减由 ShopXO 原生处理。
这是当前座位的实时库存，优先于任何前端缓存。
五、前端完整数据流图
后端 GetGoodsViewData()
│
├── vr_seat_template.venue ──────────────────→ 顶部 Banner / 场馆信息
├── vr_seat_template.rooms[].map ─────────────────→ 座位图渲染
├── vr_seat_template.rooms[].sections ────────────→ 图例 + 分区选择器
├── vr_seat_template.selectedSections ────────────→ 默认选中的分区（用于高亮）
├── goods_spec_data / vr_seat_template.sessions ──→ 场次选择器
└── seatSpecMap (新增) ─────────────────────────────→ 核心！
│
├── seatSpecMap[seatKey].spec ────────→ submit() 构造 goods_data.spec
├── seatSpecMap[seatKey].inventory ──→ 标记已售 / 灰色
├── seatSpecMap[seatKey].price ──────→ 计算总价
└── filterSeatMap() ─────────────────→ spec 选择器联动过滤
六、注意事项
6.1 roomId 从哪里来？
rooms[i].id（来自 template_snapshot.rooms）就是 roomId。这是 UUID 或字符串 ID。
前端构造 seatKey 时必须使用这个 ID：
// 正确：从 rooms[i].id 取
var roomId = rooms[i].id; // "room_001"
// 错误：硬编码或自行生成
var roomId = "room_001"; // ❌ 如果 rooms 结构变了就错了
6.2 colNum 从哪里来？
colNum 是列号（从 1 开始），不是数组索引：
// 正确
var colNum = colIndex + 1; // 0-based 数组索引 → 1-based 列号
// seatKey 格式：{roomId}_{rowLabel}_{colNum}
// 例如：room_001_A_3 = room_001 的 A排 第3列
6.3 同一个 char 在不同房间代表不同分区
room_001 的 "A" 是 VIP区（红色），room_002 的 "D" 是互动区（橙色）。
分区信息在 rooms[i].sections 里，不要直接用 char 本身判断分区。
6.4 map 中下划线数量的处理
"AAAAA_____BBBBB" 中有 5 个下划线。座位图渲染时：
chars.forEach(function(char, colIndex) {
if (char === '_' || char === '-') {
// 渲染一个空白格子（不绑定座位）
return;
}
// 渲染座位，colNum = colIndex + 1
});