# Agent 任务卡 — vr-shopxo-plugin

> 每次派 agent 任务前，先读本文件和 `DEVELOPMENT_GUIDELINES.md`。
> 每次任务以一个小目标为限，做完汇报，不要一次塞太多。

---

## 当前项目状态

**分支**: `feat/phase4-ticket-wallet`
**主分支**: `main`（干净，无 ShopXO 核心修改）
**已验证可用**: Docker 环境 + ShopXO 后台

**已完成的文件（可直接引用/继续开发）：**
- `service/WalletService.php` — 票夹查询 + QR JWT 签名 + 短码编码（HMAC-XOR）
- `service/TicketService.php` — 发票/核销逻辑
- `view/goods/ticket_card.html` — 票卡 UI 片段
- `view/goods/ticket_wallet.html` — C端票夹整页
- `service/AuditService.php` — 核销审计日志
- `database/migrations/001_vr_tables.sql` — 表结构（tickets/verifiers/verifications/audit_log）
- `tests/phase4_1_feistel_test.php` — 单元测试（HMAC-XOR + QR 签名）

**Phase 4 待完成（优先级从高到低）：**

| # | 任务 | 难度 | 约束 |
|---|------|------|------|
| 1 | **C端票夹 API** + 挂载到 ShopXO 用户中心 | 中 | 改动在插件内，ShopXO 核心不动 |
| 2 | **B端核销 API** `/?s=api/vr_ticket/verify` | 低 | 已有 AuditService，只需写 API 控制器 |
| 3 | **B端核销页面** admin 侧边栏入口 + 核销操作页 | 中 | 复用 ShopXO Layui 风格 |
| 4 | **出票链路闭环** `order.paid` 事件 → `issueTicket()` | 中 | 参考 Phase 4 Plan §5 |
| 5 | **Migration 002** `002_ticket_wallet.sql` | 低 | 无需存 short_code（实时编码），检查 001 是否完整 |

---

## 任务卡 1：C端票夹 API + 前端挂载

**目标**：用户访问票夹页 `/?s=user/wallet` 时展示 vr_ticket 票。

### Step 1 — API 端点

文件：`shopxo/app/plugins/vr_ticket/api/Ticket.php`

参考 Phase 4 Plan §3.3，新增两个方法：

```php
// GET /?s=api/vr_ticket/tickets
// 返回：当前用户所有票（已购、未核销）
public function tickets()
{
    // 1. 取当前登录用户 $userId
    // 2. 调用 WalletService::getUserTickets($userId)
    // 3. 返回 JSON: { code: 0, data: [...] }
}
```

### Step 2 — 页面挂载

文件：`view/goods/ticket_wallet.html`

在 ShopXO 用户中心挂载点（找 `ModuleInclude('模块名')`）渲染此页面。
参考 ShopXO 现有用户中心模板路径：`app/index/view/default/user/wallet.html`

**约束**：
- 不要新建路由，只在现有用户中心挂载
- 使用 `{module_include('vr_ticket/wallet')}` 方式挂载（先查 ShopXO 是否支持此语法）
- 如不支持，改为在 `User.php` 控制器渲染时 include 票夹片段

### Step 3 — 验证

Docker 内 curl 测试：
```bash
curl "http://localhost:10000/?s=api/vr_ticket/tickets&uid=1"
```
预期：返回 JSON（含 code、data 数组）

---

## 任务卡 2：B端核销 API

**目标**：`POST /?s=api/vr_ticket/verify` — 核销一张票。

### 文件

`shopxo/app/plugins/vr_ticket/api/Ticket.php`

### 接口规范

```
POST /?s=api/vr_ticket/verify
Body: { "ticket_id": 482815 }
    或 { "short_code": "7J4F9X2M" }
    或 { "qr_payload": "eyJpZCI6NDgyODE1L..." }

Response:
  成功: { "code": 0, "msg": "核销成功", "data": { "ticket_id": 482815, "verified_at": "..." } }
  失败: { "code": 1, "msg": "票不存在/已核销/无权核销" }
```

### 实现

```php
public function verify()
{
    // 1. 解析请求（支持 ticket_id / short_code / qr_payload 三种入口）
    // 2. 短码解码: ShortCodeService::decode($short_code) → [goods_id, ticket_id]
    // 3. QR payload 验签: WalletService::verifyQrPayload($qr_payload) → ticket_id
    // 4. TicketService::verifyTicket($ticketId, $verifierId)
    // 5. AuditService::log() 记录
    // 6. 返回结果
}
```

### 约束

- 不写死 `$verifierId = 1` — 从 `$_POST['verifier_id']` 或 Session 读取
- 验签失败的 QR payload 返回 code=1（不暴露内部错误）
- 日志必须写入 `vr_audit_log` 表

---

## 任务卡 3：B端核销页面

**目标**：在 ShopXO 后台 admin 侧边栏新增「票务核销」菜单项。

### 文件

- 控制器：`shopxo/app/plugins/vr_ticket/admin/Admin.php` — 新增 `Verify()` 方法
- 视图：`shopxo/app/plugins/vr_ticket/view/admin/verify.html`

### 实现要点

1. **侧边栏入口**：通过 `event.php` 的 `plugins_service_admin_menu_data` hook（如已注册则跳过此步）
2. **核销页面**：两个入口
   - 扫码抢扫入 → 输入 QR payload 或 ticket_id
   - 手动输入短码
3. **UI 风格**：复用 ShopXO Layui（`am-btn`、`am-form` 等 class）
4. **核销结果展示**：成功后显示票面信息（场次/座位/观演人姓名），并更新数据库状态

### 参考文件

- 已有后台视图：`shopxo/app/plugins/vr_ticket/view/admin/setup.html`
- 已有后台控制器风格：`shopxo/app/plugins/vr_ticket/admin/Admin.php`

---

## 任务卡 4：出票链路闭环（支付成功 → 发票）

**目标**：ShopXO 订单支付成功后，自动触发 `TicketService::issueTicket()`。

### 现状分析

1. ShopXO 订单表 `vrt_orders` 有 `order_status` 字段
2. `vrt_vr_tickets` 表已存在（001_migration），字段完整
3. `TicketService::issueTicket()` 已实现（需要确认参数格式）

### 需要做的事

找到 ShopXO 支付成功的事件钩子：
```
plugins_service_order_pay_success_handle_end
```
（在 `event.php` 的 vr_ticket hooks 中已注册，需要确认是否在运行）

1. 确认此 hook 能否收到 `$params['order_id']`
2. 确认 `$params` 中有哪些可用数据（收货地址、观演人信息等）
3. 如 hook 数据不足，改为监听更早的事件（如 `plugins_service_orders_save_thing_end`）

### 参考

Phase 4 Plan §5：「支付回调链路」

---

## 任务卡 5：Migration 002 — 补全票夹所需表/字段

**目标**：检查 001_migration 是否缺少票夹必要的字段，补全。

### 需要确认的字段

```
vrt_vr_tickets
  ✅ id (BIGINT PK)
  ✅ order_id (BIGINT)
  ✅ goods_id (BIGINT)
  ✅ user_id (BIGINT)
  ✅ seat_info (JSON) — 场次/座位信息
  ✅ verify_status (TINYINT) — 0=未核销 1=已核销
  ✅ verified_at (DATETIME, NULL)
  ✅ created_at
  ❓ user_name (VARCHAR) — 观演人姓名，从哪来？
  ❓ user_phone (VARCHAR) — 观演人电话，从哪来？
```

### 执行方式

1. 写 `database/migrations/002_ticket_wallet.sql`
2. 确认每个字段的来源（订单表？商品表？支付回调参数？）
3. **不要直接执行** — 提交 SQL 文件，用户在本地 Docker 验证后再执行

---

## 约束提醒（必读）

1. **ShopXO 核心文件禁止修改** — `shopxo/app/`、`shopxo/config/` 等禁止改动，插件代码放在 `shopxo/app/plugins/vr_ticket/`
2. **数据库操作必须以 migration SQL 文件提交** — 不要直接 docker exec mysql 执行
3. **Docker 操作尽量避免** — 优先在宿主机写文件，重启容器验证
4. **commit 前必须自检** — `git status`，确认没有意外改动 ShopXO 核心文件
5. **任务完成后汇报格式**：
   - ✅ 完成：做了XX
   - ⚠️ 阻塞：缺少XX，需要用户确认
   - ❌ 失败：XX 报错，尝试了YY未能解决

---

*最后更新：2026-04-24 by 西莉雅*