# 数字票（Digital Ticket）说明

> 版本：2.0
> 更新日期：2026-08-07

## 1. 定位

数字票是一次停车会话的**支付与离场状态凭证**，不是纸质小票的替代品，也不绑定某一种支付入口。

- 每次车辆入场都会创建一张数字票，无论来源是 RFID、人工录入、票机还是后续接入的车牌识别。
- 数字票关联一条停车会话（`vehicle_record`），但不复制会话的通道、设备、车辆图片等事实数据。
- 支付流水（`payment_record`）是资金事实；数字票和停车会话保存用于业务查询的结算摘要和状态。
- 纸质小票可打印数字票票号或二维码，但只是数字票的物理凭证之一。

```text
停车会话 vehicle_record
  ├─ 入场/出场时间、停车场、通道设备快照、结算摘要
  └─ 1 : 1 数字票 digital_ticket
       ├─ ticket_no、状态、支付摘要、事件日志
       └─ 关联结算支付流水 payment_record
            └─ 实际金额、实收、找零、入口、方式、操作员
```

## 2. 生命周期

```text
车辆入场
  -> 创建停车会话
  -> 创建数字票（pending_payment）
  -> 支付成功（paid）
  -> 确认离场（exited）
```

| 状态 | 含义 | 可执行操作 |
| --- | --- | --- |
| `pending_payment` | 已入场、等待支付或免费放行判断 | 支付、出场确认（仅零费用/免费） |
| `paid` | 已完成支付、尚未出场 | 出场确认 |
| `exited` | 会话已关闭、车辆已离场 | 只读 |
| `expired` | 已过期或业务终止 | 只读，需按异常流程处理 |

`created` 仅作为创建过程中的内部初始状态，创建完成后会进入 `pending_payment`。

## 3. 与支付入口、支付方式的关系

### 支付入口

支付入口回答“在哪里完成支付”，例如：

- `counter`：收费岗亭
- `ticket`：停车小票/扫码入口
- `central_payment_machine`：中央缴费机

### 支付方式

支付方式回答“如何完成支付”，例如：

- `cash`：人工现金
- `pos`：POS 机
- `ticket_qr`：小票扫码支付
- `free`：免费放行

入口和方式通过 `payment_entry_method` 配置关联。关闭入口会阻止从该入口发起新支付；关闭方式会从该入口可选方式中移除。二者都不改变历史数字票或历史支付流水。

## 4. 一致性和幂等性

支付和离场均在事务内完成：

1. 校验当前数字票和停车会话状态。
2. 校验支付金额、支付入口和支付方式配置。
3. 写入 `payment_record`。
4. 更新停车会话支付摘要及数字票状态。
5. 出场时保存出口通道/设备快照，关闭停车会话并将数字票更新为 `exited`。

系统会拒绝负金额、金额不足、重复支付和已关闭会话再次离场。并发结算使用会话状态条件更新保证只有一个请求成功；事务失败不会遗留部分支付流水。

## 5. 核心字段

| 字段 | 说明 |
| --- | --- |
| `ticket_no` | 数字票唯一票号，用于二维码、查询和外部支付回调关联 |
| `vehicle_record_id` | 关联的停车会话 ID |
| `trigger_mode` | 入场来源，如 `rfid`、`manual`、`camera` |
| `state` | 当前数字票状态 |
| `fee` / `paid_amount` | 应收与实收摘要 |
| `payment_entry` / `payment_method` | 实际完成支付的入口与方式 |
| `payment_order_no` | 外部支付订单号，可选 |
| `event_log` | 票据状态变化事件日志 |

票号是面向业务和外部凭证的随机唯一标识；停车会话 ID 是内部数据库流水编号，两者不应混用。

## 6. API

以下路径会叠加系统 API 前缀（开发环境通常为 `/api`）：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/digital-ticket/summary` | 按筛选条件获取待支付、已支付、已离场等汇总 |
| GET | `/digital-ticket/list` | 数字票分页列表 |
| GET | `/digital-ticket/:ticketNo` | 数字票详情 |
| POST | `/digital-ticket/:ticketNo/pay` | 支付数字票 |
| POST | `/digital-ticket/:ticketNo/exit` | 确认数字票对应车辆离场 |

支付请求示例：

```json
{
  "payment_entry": "counter",
  "payment_method": "cash",
  "payment_order_no": "OPTIONAL-ORDER-NO",
  "paid_amount": 20.0
}
```

## 7. 前端页面

`frontend/src/view/parking/digitalTicket.vue` 提供：

- 票据状态汇总和分页筛选
- 票号复制、票据详情、状态事件展示
- 基于可用支付入口和支付方式的结算操作
- 已支付票据的离场确认

进出场工作台 `entryExit.vue` 使用同一会话和数字票逻辑，不会创建另一套支付状态。

## 8. 扩展方式

新增中央缴费机、POS 或线上支付时，应新增或启用一个支付入口、配置可用支付方式，并在支付成功回调中调用已有支付服务。不得绕开数字票、停车会话和支付流水分别修改状态。

建议外部支付回调以 `ticket_no + payment_order_no` 作为幂等键，并保留网关原始流水号以便对账。