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 工作。

3. 核心业务闭环

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

4. 自动化验证记录

范围	已覆盖的关键场景
parking-session	会话创建、重复入场拒绝、身份冲突、支付、关闭、通道设备快照、余位事务、满位准入、超容离场
payment	负金额、零金额、金额不足、重复结算、并发结算、事务回滚、缺失会话
vehicle	车辆入场创建会话和数字票、RFID 定位、预览、免费出场、重复支付回滚
parking	统一通行和闸机相关服务回归
system	仪表盘只汇总有效停车场，忽略已删除停车场的孤立历史会话
printer	USB 票据顺序、文字方向、二维码、切纸走纸、短写和二维码失败
票机适配层	统一通行请求、无牌唯一身份、通道设备解析、多设备歧义拒绝、打印部分失败、调试路由隔离
前端	npm run build 生产构建通过

最近一次相关验证命令：

$env:GOCACHE='D:\lq\Smart Parking\lc_garage\.gocache'
go test ./internal/service/system ./internal/service/parking ./internal/modules/parking-session/service ./internal/service/vehicle ./internal/initialize

cd frontend
npm run build

5. 待办与优先级

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

6. 文档维护规则

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