# 智慧停车进出场流程详解

> 更新日期：2026-08-07
> 本文档描述当前已实现的统一进出场主路径。

## 1. 核心原则

1. 所有触发方式先定位设备和通道，再进入统一通行服务。
2. 一辆车一次在场过程只能有一个未关闭的停车会话。
3. 入场原子创建停车会话和数字票；支付、出场均定位同一会话。
4. 支付事实写入支付流水，通道和设备事实写入停车会话快照。
5. 开闸是业务成功后的设备动作；闸机失败必须向操作员返回“业务已完成、设备动作失败”的明确状态。

## 2. 触发入口

| 来源 | 车辆标识 | 当前状态 | 进入方式 |
| --- | --- | --- | --- |
| UHF RFID | RFID，可带车牌 | 已实现 | 设备事件调用 `PassageService.HandlePassage` |
| 工作台人工操作 | 车牌或 RFID | 已实现 | `entryExit.vue` 调用 `/vehicle/passage` |
| 票机按钮 | 票机输入/临时车 | 已实现，待现场验收 | 创建入场会话、数字票并打印小票 |
| 摄像头识别 | 车牌 | 未实现 | 规划接入同一 `PassageService` |

## 3. 进场流程

```text
识别车辆
  -> 通过 device_code 查询 UHF 设备和绑定通道
  -> 校验设备启用、通道方向、停车场归属、黑名单、临停规则
  -> 按车牌/RFID 定位是否存在未关闭停车会话
  -> 不存在：创建会话 + 数字票
  -> 保存入口通道和设备快照
  -> 更新车辆最近入场时间
  -> 请求开闸
```

### 3.1 入场数据写入

| 对象 | 入场写入内容 |
| --- | --- |
| 停车会话 `vehicle_record` | 车牌、RFID、入场时间、停车场、停车位、入口图片、入口通道/设备 ID、编码、名称 |
| 数字票 `digital_ticket` | 票号、入场来源、会话 ID、`pending_payment` 状态、事件日志 |
| 车辆 `vehicle` | 最近入场时间 |

同一车牌或 RFID 已存在未关闭会话时，入场会被拒绝，不会重复建票。

## 4. 出场与结算流程

```text
识别车辆
  -> 定位未关闭停车会话和数字票
  -> 计算当前费用，返回出场预览
  -> 判断数字票是否已支付
     -> 已支付：直接进入出场确认
     -> 未支付且应收为零：免费放行确认
     -> 未支付且应收大于零：选择支付入口和支付方式完成结算
  -> 写支付流水、更新会话支付摘要、数字票 -> paid
  -> 保存出口通道和设备快照，关闭会话，数字票 -> exited
  -> 更新车辆最近出场时间、累计停车时长和费用
  -> 请求开闸
```

### 4.1 支付判断

| 场景 | 处理 |
| --- | --- |
| 已支付数字票 | 不再次收费，直接消费原支付记录并确认出场 |
| 零费用、白名单或免费放行 | 生成零金额结算记录后出场 |
| 人工现金 | 校验实收不低于应收，记录找零 |
| POS/扫码 | 由已配置支付入口和方式决定；真实设备或网关回调待接入时不得伪造成功 |
| 重复请求 | 已支付或已关闭会话会被拒绝，避免重复收费和重复出场 |

## 5. 通道与设备快照

停车会话保存下列字段：

| 阶段 | 字段 |
| --- | --- |
| 入场 | `entry_channel_id`、`entry_channel_code`、`entry_channel_name`、`entry_device_code`、`entry_device_name` |
| 出场 | `exit_channel_id`、`exit_channel_code`、`exit_channel_name`、`exit_device_code`、`exit_device_name` |

进出记录详情优先显示名称；编码为名称缺失或配置已删除时的回退值。ID 仅用于关联和查询，不直接作为运营页面的主要显示内容。

## 6. 状态关系

| 停车会话 | 数字票 | 含义 |
| --- | --- | --- |
| `exit_time IS NULL` + `payment_status=unpaid` | `pending_payment` | 在场待支付 |
| `exit_time IS NULL` + `payment_status=paid` | `paid` | 已支付待离场 |
| `exit_time IS NOT NULL` | `exited` | 已离场 |

`payment_record` 不承担状态机角色，它记录每次实际结算的金额和操作员，是财务对账依据。

## 7. 闸机处理

开闸和关闸由统一闸机控制服务封装。进出场业务先完成数据库事务，再下发开闸指令：

- 开闸成功：返回通行成功和闸机已开启。
- 开闸失败：返回业务已完成、闸机失败，避免操作员误以为可以重复收费或重新出场。
- 无真实设备时：可使用已启用的模拟设备完成工作台流程验证。

## 8. 异常与人工兜底

| 异常 | 当前处理 | 后续完善 |
| --- | --- | --- |
| 黑名单车辆 | 拦截通行 | 增加异常处置记录和审批 |
| 无未关闭会话的出场 | 拒绝出场 | 增加无票/丢票人工处理工作流 |
| 闸机失败 | 业务状态保留，返回设备失败 | 增加重试、告警和人工确认 |
| 设备离线 | 禁止使用该设备通行 | 增加离线事件和仪表盘告警 |
| 摄像头未识别 | 当前未接入 | 接入 OCR 后进入同一通行入口 |

## 9. 关键代码入口

| 节点 | 文件 | 关键方法 |
| --- | --- | --- |
| 统一通行 | `internal/service/parking/passage.go` | `HandlePassage` |
| 停车会话 | `internal/modules/parking-session/service/service.go` | `OpenSessionTx`、`ResolveActiveSessionTx`、`CloseSessionTx` |
| 车辆进出场 | `internal/service/vehicle/vehicle.go` | `VehicleEntry`、`ExitPreview`、`ExitConfirm` |
| 支付 | `internal/modules/payment/service/service.go` | `ProcessPaymentTxAtEntry` |
| 数字票 | `internal/modules/digital-ticket/service/service.go` | `CreateTx`、`MarkPaidAndExitedTx` |
| 闸机 | `internal/service/parking/gate.go` | 开闸、关闸、设备状态 |