数字票（Digital Ticket）说明

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

1. 定位

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

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

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

2. 生命周期

车辆入场
  -> 创建停车会话
  -> 创建数字票（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. 一致性和幂等性

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

校验当前数字票和停车会话状态。
校验支付金额、支付入口和支付方式配置。
写入 payment_record。
更新停车会话支付摘要及数字票状态。
出场时保存出口通道/设备快照，关闭停车会话并将数字票更新为 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`	确认数字票对应车辆离场

支付请求示例：

{
  "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 作为幂等键，并保留网关原始流水号以便对账。

digital-ticket.md 4.9 KB Pysyvä linkki Historia Raaka