lc_garage/doc/进出场流程详解.md

智慧停车进出场流程详解

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

1. 核心原则

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

2. 触发入口

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

3. 进场流程

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

3.1 入场数据写入

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

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

4. 出场与结算流程

识别车辆
  -> 定位未关闭停车会话和数字票
  -> 计算当前费用，返回出场预览
  -> 判断数字票是否已支付
     -> 已支付：直接进入出场确认
     -> 未支付且应收为零：免费放行确认
     -> 未支付且应收大于零：选择支付入口和支付方式完成结算
  -> 写支付流水、更新会话支付摘要、数字票 -> 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	开闸、关闸、设备状态