# 观影权益核销（票包兑换码）

## 页面信息

- 页面名称：核销输入（观影权益）
- 路由：`/pages/ticket-package-confirm/ticket-package-confirm`
- 源码：`pages/ticket-package-confirm/ticket-package-confirm.uvue`
- 入口：商家端「扫码核销」扫到用户出示的观影权益二维码（`credentialType=TICKET_PACKAGE_CODE`）。
- 业务链路：后台批量生成兑换码并绑到影城 → 发到票包 → 人才端领取（出示二维码）→ 影城店员扫码 → 确认核销 → 后台实时可见核销记录。

## 功能点

| 功能 | 说明 | 状态 |
| --- | --- | --- |
| 扫码识别 | `POST /api/merchant/verification/scan` 识别票包兑换码，服务端校验：码存在、属于当前商户、状态 `ISSUED`、未过期；不满足时直接给出原因（已核销/已过期/不属于当前商户）。 | 已接入 |
| 核销确认页 | 展示脱敏持卡人、人才卡等级、票包名称与有效期，底部「确认核销」。 | 已接入 |
| 核销 | `POST /api/merchant/benefit-verifications/verify`（`benefitType=MOVIE_TICKET` + 兑换码），服务端把票包码池（`ticket_package_code`）与领取记录（`ticket_package_claim`）一起置为 `USED`，并写入核销记录 `benefit_verify_record`。 | 已接入 |
| 核销成功 | 跳转核销成功页（`credentialType=TICKET_PACKAGE_CODE`）。 | 已接入 |

## 异常处理

| 场景 | 表现 |
| --- | --- |
| 码已核销 | 服务端返回「该观影权益已核销或已失效」，扫码页提示失败。 |
| 码已过期 | 服务端返回「该观影权益已过期」。 |
| 码不属于当前商户 | 扫码统一返回「二维码已失效、不可核销或不属于当前商户」。 |
| 兑换码缺失（参数异常） | 确认页提示「核销凭证无效，请返回重新扫码」，按钮不可用。 |
| 核销接口失败 | toast 展示服务端原因（如「电影票核销码已使用或已过期」），可重新扫码。 |

## 后台可见性

- 管理后台「电影票管理 → 领取记录」展示领取状态与核销时间（`ticket_package_claim.status/used_at`）。
- 管理后台「电影票管理 → 核销记录」（`GET /api/admin/ticket-packages/verifications`）只列已核销记录，可按票包、持卡人、卡片等级、领取时间、核销时间和核销商家筛选与导出。
- 商家端在「订单管理 → 团购」里能看到这条观影券，点开的核销详情见 `24-观影券核销详情.md`。