lc_garage/doc/项目进度.md

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

更新日期：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. 核心业务闭环

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

4. 自动化验证记录

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

最近一次相关验证命令：

$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 时，文档应说明旧数据的兼容与回退策略。