# 智慧停车管理系统项目进度

> 更新日期：2026-08-11
> 状态说明：`已完成` 指功能已接入前后端；`已验证` 指自动化测试或构建已通过；`待验收` 指需在真实设备或现场流程继续验证。

## 1. 当前完成度

| 领域 | 状态 | 当前能力 |
| --- | --- | --- |
| 基础权限与系统管理 | 已完成 | 用户、角色、菜单、API、Casbin、字典、操作日志、登录 |
| 停车场基础配置 | 已完成并验证 | 停车场、岗亭、通道、UHF 设备，容量、占用数、余位及满位准入策略 |
| 车辆与名单 | 已完成 | 车辆、车主、车型、黑白名单、包月车 |
| 统一进出场 | 已完成 | 手动和 UHF 统一经过 `PassageService`，支持入场、出场、计费、开闸 |
| 停车会话 | 已完成并验证 | 防止重复在场、统一定位、支付与离场状态更新、入口/出口通道设备快照 |
| 数字票 | 已完成并验证 | 创建、待支付、已支付、已离场、事件日志、列表、详情、汇总、支付和离场页面 |
| 支付 | 已完成并验证 | 支付入口与支付方式分离配置，现金、POS、扫码等可配置方式，支付流水与找零 |
| 交接班与收入报表 | 已完成 | 交接班记录、收费记录、收入汇总与查询 |
| 仪表盘与车辆监控 | 已完成 | 在场车辆、进出统计、收入及设备状态展示 |
| 闸机控制 | 已完成，待现场验收 | 统一开闸/关闸封装，支持真实设备和模拟在线设备 |
| 小票打印 | 已完成，待真实打印验收 | 串口 ESC/POS 与 USB CSN SDK，二维码与票据排版测试 |
| 异常处置闭环 | 已完成并验证 | 异常事件表、四状态处置流转、自动埋点（通行失败/人工抬杆/设备离线）、指令流水、前端页面与权限分级 |
| 摄像头识别 | 未完成 | 已有摄像头实体，尚未接入 RTSP、OCR 和进出场事件 |
| LED 车位屏 | 未完成 | 尚未接入硬件协议和余位推送 |

## 2. 本轮已完成工作

### 2.0 停车场容量与满位准入

- 停车场新增实际占用数，并根据总容量和占用数维护剩余车位。
- 入场占位、停车会话创建和数字票创建处于同一事务；出场关闭会话时在同一事务释放车位。
- 服务启动时根据未出场停车会话自动校准各停车场占用数和余位。
- 车位满时支持分别配置是否允许临时车、有效月租车和有效 VIP 车继续入场。
- 超容车辆入场后余位保持为零，直到实际占用数重新低于停车场容量。
- 停车场详情显示总车位、已占用、剩余车位和满位准入策略。
- 仪表盘按全部未删除停车场汇总容量和实际占用数，与停车场详情使用相同统计口径。
- 停车场存在未出场会话时禁止删除，避免继续产生无法归属的在场记录。
- 已关闭已删除停车场遗留的 48 条测试会话；修复前数据库已备份到 `backups/lc_garage-before-orphan-fix-20260811-112552.db`。

### 2.1 停车会话统一化

- 以 `vehicle_record` 作为停车会话持久化载体。
- 入场时原子创建停车会话和数字票，避免只有入场记录或只有数字票的半成品数据。
- 出场、支付、数字票操作都通过会话编号、票号、车牌或 RFID 定位同一在场会话。
- 旧出场路径已收敛至 `ExitConfirm` 和统一通行入口。

### 2.2 支付与数字票解耦

- 数字票不再绑定“停车小票”这一单一场景，所有车辆入场均创建数字票。
- 支付入口和支付方式分别配置：入口决定在哪里完成支付，方式决定如何收款。
- 支付成功写入 `payment_record`，同步更新停车会话和数字票；出场只消费已完成的结算结果，避免重复收费。
- 已补充负金额、零金额、重复支付、并发结算、事务回滚等测试。

### 2.3 设备、通道和会话可追溯

- `HandlePassage` 根据设备编码定位 UHF 设备及绑定通道。
- 入场保存入口通道和入口设备快照；出场保存出口通道和出口设备快照。
- 快照包含 ID、编码和名称。进出记录详情页面优先显示名称。
- 历史记录若没有名称快照，会根据当前通道 ID、设备编码补全；无法补全时保留编码兜底。

### 2.4 小票打印

- 支持串口 ESC/POS 与 USB CSN DLL 直连两种打印链路。
- USB 票据按实际纸张出纸方向输出，并包含二维码、切纸前走纸和短写失败处理。
- 已完成打印命令与版式自动测试；最终字号、物理偏移和二维码密度仍以现场纸张为准。

### 2.5 票机统一通行与调试接口收口

- 票机按钮通过通道编码定位停车场和绑定设备，并统一调用 `PassageService` 完成准入、会话、数字票、入口快照和开闸。
- 删除停车场 ID、车位 ID 和测试通道的硬编码；同一通道存在多个启用设备时要求明确传入设备编码。
- 入场响应直接返回 `session_id`、`ticket_id` 和 `ticket_no`，打印不再按车牌查询最新票据。
- 无牌取票生成唯一 `TKT...` 会话身份，打印票面仍保持车牌为空。
- 调试路由由 `system.debug-routes` 显式控制，默认关闭；开启后仍要求 JWT、管理员或开发角色权限，并记录操作日志。
- 打印任务持久化、失败重试、重打和作废仍列为后续 P0 工作。

### 2.6 异常处置闭环

- 新增 `incident_record` 异常事件表与 `internal/modules/incident/` 模块（api + service + repository），详见 `doc/异常处置设计.md`。
- 状态机：待处理 → 处理中 → 已解决 → 已关闭，支持重新打开；CAS 条件更新防并发覆盖；`event_log` 记录流转时间线。
- 自动埋点（best-effort，不影响业务主流程）：
  - 统一通行（`PassageService`）：开闸失败（critical）、重复入场、黑名单拦截、满位拒绝、无入场记录出场。
  - 人工抬杆/关闸：`/parking/gate/open|close` 新增可选 `reason` 参数，成功生成已解决的 `manual_raise` 记录，失败生成待处置的 `gate_failed` 记录。
  - 设备离线：UHF 读卡器在线→离线转换时生成（同设备未关闭不重复），恢复在线自动关闭。
- 新增 `device_command_log` 指令流水：每次道闸开/关命令（来源/操作员/会话/结果/耗时），开闸失败时关联异常事件。
- 权限分级：查看/上报 618/888/9527；处置 888/9527；强制免费仅 888（前端隐藏 + 后端强制校验）。
- 前端：`view/report/sheet.vue` 重写为异常处置页面（统计行 + 筛选 + 分页 + 详情时间线 + 处置表单 + 人工上报），新增 `api/incident.js`；复用菜单 27"异常报表"。
- 自动化测试：状态机合法/非法流转、强制免费权限与金额校验、CAS 并发、best-effort（DB 故障不阻塞）、设备离线去重与自动关闭、编号生成、统计、开闸失败埋点集成（指令流水 + 异常关联）、路由鉴权（未登录 401）。

## 3. 核心业务闭环

```text
设备/人工识别车辆
  -> 定位设备和通道
  -> 定位在场停车会话
  -> 无会话：创建会话 + 数字票 + 入场快照 + 开闸
  -> 有会话：预览费用
  -> 通过支付入口选择支付方式完成结算
  -> 支付流水 + 会话支付摘要 + 数字票同步更新
  -> 保存出场通道设备快照 + 关闭会话 + 数字票离场 + 开闸
```

## 4. 自动化验证记录

| 范围 | 已覆盖的关键场景 |
| --- | --- |
| `parking-session` | 会话创建、重复入场拒绝、身份冲突、支付、关闭、通道设备快照、余位事务、满位准入、超容离场 |
| `payment` | 负金额、零金额、金额不足、重复结算、并发结算、事务回滚、缺失会话 |
| `vehicle` | 车辆入场创建会话和数字票、RFID 定位、预览、免费出场、重复支付回滚 |
| `parking` | 统一通行和闸机相关服务回归 |
| `system` | 仪表盘只汇总有效停车场，忽略已删除停车场的孤立历史会话 |
| `printer` | USB 票据顺序、文字方向、二维码、切纸走纸、短写和二维码失败 |
| 票机适配层 | 统一通行请求、无牌唯一身份、通道设备解析、多设备歧义拒绝、打印部分失败、调试路由隔离 |
| `incident` | 异常状态机合法/非法流转、强制免费权限与金额、CAS 并发、best-effort（DB 故障不阻塞）、设备离线去重与自动关闭、编号生成、统计、指令流水关联 |
| 埋点集成 | 开闸失败 → `gate_failed` 异常 + `failed` 指令流水并回填关联；人工抬杆（带原因）生成已解决记录；成功开闸不产生异常 |
| 路由安全 | `/incident/*` 全部要求 JWT（未登录 401） |
| 前端 | `npm run build` 生产构建通过 |

最近一次相关验证命令：

```powershell
$env:GOCACHE='D:\lq\Smart Parking\lc_garage\.gocache'
go test ./internal/service/... ./internal/modules/... ./internal/initialize

cd frontend
npm run build
```

## 5. 待办与优先级

| 优先级 | 项目 | 状态 | 说明 |
| --- | --- | --- | --- |
| P0 | 真实闸机联调 | 待验收 | 开闸、关闸、设备离线、超时和人工兜底 |
| P0 | 小票打印现场验收 | 待验收 | 真实 USB/串口打印机的方向、物理偏移、二维码大小和切纸 |
| P0 | 摄像头车牌识别 | 未开始 | RTSP/SDK 抓拍、OCR、车牌置信度和统一通行入口接入 |
| P1 | 异常处置扩展点 | 预留 | 打印失败/支付不确定埋点、无牌车独立分类、余位为负与状态不一致自动检测（核心闭环已完成，见 2.6） |
| P1 | LED 车位屏 | 未开始 | 余位计算、设备协议、定时/事件推送 |
| P1 | 现场数据与权限验收 | 待验收 | 角色菜单、操作日志、数据归属、交接班对账 |
| P2 | POS 真机支付 | 待接入 | 以已配置的 POS 支付方式为基础接入交易请求和异步回调 |
| P2 | 中央缴费机 | 待接入 | 作为支付入口接入，复用数字票和支付流水，不创建独立业务主线 |
| P2 | 线上支付 | 待接入 | 小程序/App 扫码支付与回调幂等处理 |

## 6. 文档维护规则

- 业务行为变化时，同时更新本文件和对应流程文档。
- “已完成”不等于真实硬件已验收；涉及闸机、打印机、POS 的功能必须保留现场验收记录。
- 数据库字段新增依赖 `AutoMigrate` 时，文档应说明旧数据的兼容与回退策略。