# 智慧停车管理系统功能缺失清单

> 更新日期：2026-08-13
> 评估范围：`lc_garage` 当前前端、后端、设备接入和自动化测试代码
> 状态说明：本文用于记录尚未完成的业务闭环和生产风险，不代表相关模块完全没有代码。
> 本次更新：基于全量代码复查（资金支付财务 / 设备通行告警 / 平台工程安全三个领域），新增安全漏洞小节与工程缺陷清单。

## 1. 总体结论

当前项目已经具备单机人工收费停车场的基础业务链路，包括停车场配置、车辆管理、统一进出场、停车会话、数字票、人工收费、支付流水、月卡、交接班、报表、道闸模拟、小票打印和异常处置闭环。

距离正式运营仍缺少的关键闭环：

1. POS、扫码、中央缴费机等真实资金交易（仅配置占位）。
2. 摄像头、道闸、地感、LED 屏的状态反馈和联动。
3. **权限安全**：操作员角色存在可提权通道（见 2.0），且操作日志无脱敏。

“存在支付方式配置”不等同于“已经接入真实支付”。当前非现金支付主要用于业务流程确认，尚未连接实际支付终端或支付网关。

## 2. P0：上线前必须解决

### 2.0 安全漏洞与权限缺陷（2026-08-13 新增，最高优先级）

1. **操作员（618）提权通道**：`seed.go` 授予 618 角色 `/user/admin_register` 权限，而注册接口（`internal/api/v1/system/sys_user.go:157-179`）直接使用请求体的 `AuthorityId` 建用户、不校验目标角色 → 618 可注册一个 888 管理员账号获得全部权限。数据库中 618 实际拥有 105 条 Casbin 规则（可改收费单价、删停车场、退月卡、黑名单 CRUD），角色粒度过粗。
2. **操作日志无脱敏**：`middleware/operation.go:78-87` 请求体原文入库（密码/token/支付字段明文），`/user/changePassword` 等接口的旧密码+新密码被完整记录；响应体无限增长入库（`respPool` 死代码，响应截断分支写错字段 `record.Body` 应为 `record.Resp`）。
3. **uploads 静态文件匿名可读**：`router.go:67` StaticFS 无鉴权，车牌抓拍图片可猜测 URL 访问。
4. `/dashboard/monitor`（CPU/内存信息）与 `/swagger/*` 公开免鉴权（`router.go:73,86`）。
5. **API 管理删除 API 后权限不一致**：删除清空所有角色 Casbin（`service/system/sys_api.go:39-48,124-139`），但路由仍静态注册；启动种子幂等重建 → “权限重启复活”。
6. 种子硬编码 3 个账号与 bcrypt hash（`seed.go:41-83`），源码公开默认凭据。
7. 摄像头密码明文存储（`dao/camera.go:12-13`，无加密 hook）。
8. 退卡接口授权含 618 普通操作员（`seed.go:443-444`），且无审批。

### 2.1 非现金支付没有真实交易能力

**当前情况**

- 已支持支付入口、支付方式及可用关系配置。
- POS 和外部扫码方式可以直接创建支付流水并把会话标记为已支付。
- 尚未实现支付订单、POS 驱动、扫码下单、支付网关、异步回调、主动查询和超时处理。
- `payment_record` 无渠道订单号、无支付状态字段；外部模式实收金额被丢弃（`payment/service/service.go:372-378`）；数字票 `payment_order_no` 出场时传空串（`vehicle.go:712`）。
- 退款、撤销、冲正完全不存在。

**业务影响**

- 操作员确认不能证明外部资金已经到账。
- 网络超时、支付成功但本地未更新等情况可能造成资金与业务状态不一致。
- **~~缴费后无限期免费离场（逃费路径）~~（2026-08-13 已修复）**：`FeeConfig.FreeExitMinutes`（默认 15，存量库经 DDL default 一次性迁移）——支付后超时限出场按实际时长全额重算差额，未补缴拒绝放行，补缴后刷新支付时间；`vehicle.go` paid 分支与预览接口已落地（`overtime`/`overtime_fee`/`overtime_diff` 字段），前后端交互与 10 个测试用例已完成。

**完成标准**

- 增加独立支付订单和明确的待支付、处理中、成功、失败、不确定、已退款状态。
- 外部支付只能由可信终端结果、回调或主动查询确认成功。
- 支付回调、重复通知和主动查询必须幂等。
- 实现退款、撤销、冲正、失败补偿和财务对账。
- ~~缴费后免费离场时限（如 15 分钟），超时按实际时长重新计费并补缴差额~~（2026-08-13 已完成，见上）。

### 2.2 异常报表和异常处置（核心闭环已完成，扩展点待接入）

**当前情况（2026-08-12 更新）**

- 已实现 `incident_record` 异常事件表 + `internal/modules/incident/` 模块，详见 `doc/异常处置设计.md`。
- 自动埋点已接入：统一通行五类（开闸失败、重复入场、黑名单拦截、满位拒绝、无入场记录出场）、人工抬杆/关闸（`reason` 可选参数）、设备离线（在线→离线转换，重连自动关闭）。
- 支持待处理、处理中、已解决、已关闭四状态流转（CAS 条件更新）、处理方式与备注、`event_log` 时间线审计。
- 权限分级：查看/上报面向全部角色；处置仅 888/9527；强制免费仅 888（前后端双校验）。
- `device_command_log` 指令流水已实现；前端页面已重写；自动化测试已覆盖。

**仍待接入的异常类型（埋点为预留扩展点）**

- 无牌车独立分类、车牌识别冲突（依赖摄像头 OCR）、票据打印失败（`print_failed` 已定义零调用，待打印任务持久化后接线）、支付失败/不确定（待支付订单层）、余位为负/会话与票状态不一致（待对账任务）。

### 2.3 票机打印失败补偿未完成

**当前情况**

- 票机已接入统一通行入口；无牌取票生成唯一会话身份。
- 打印仍是同步硬件调用：无持久化任务、自动重试、重打和作废机制。
- **串口 write 错误被丢弃**（`printer/service/service.go:75` 闭包内不检查 `srl.Write` 返回）；打印失败不标设备 offline、不落 incident。

**完成标准**

- 打印任务持久化，支持失败重试、重打、作废和操作审计。
- 会话创建、开闸和打印失败之间有明确的补偿规则。

## 3. P1：已有基础实现但业务闭环不足

### 3.1 计费引擎能力不足

- ~~超过 24 小时仍只应用一次日封顶，多日停车计费不正确~~（2026-08-13 已修复：日封顶按跨天数累计，跨天向上取整）。
- ~~未配置收费规则时按每分钟 0.1 隐式收费，可能造成错误收费~~（2026-08-13 已修复：无配置返回明确错误；种子为“临时车”建全零占位配置=显式免费；存量脏配置启动时自动补正）。
- ~~收费配置缺少负值、折扣范围、时间单位和封顶金额等完整校验~~（2026-08-13 已修复：前后端双校验）。
- ~~停留时长向下取整（不足一分钟不计费）~~（2026-08-13 已修复：向上取整）。
- 缺少自然日或滚动 24 小时规则、跨日分段、夜间价、节假日、阶梯计费和不同停车场费率。
- 缺少缴费后免费离场时限及超时重新计费（见 2.1）。

### 3.2 月卡办理、续费和退卡不是完整事务

- ~~创建月卡、写白名单和写支付流水没有放在同一事务中，部分错误被忽略~~（2026-08-13 已修复：三操作均事务化，错误逐层返回）。
- ~~过期卡续费从过期日续期，导致续费后立即失效~~（2026-08-13 已修复：未过期卡从原到期日顺延，过期卡从今天起算）。
- 月卡收费固定记为收费岗亭现金，不能选择支付入口和支付方式（`monthly/service/service.go:75,124`）。
- 退卡只标记 `refunded` 并删除白名单，没有退款金额、退款流水和审批；且 `Unscoped().Delete` 会物理删除该车辆所有“白名单”记录，误伤管理员手动添加的永久白名单（`monthly/service/service.go:149-151`）。
- 月、季、年按 30、90、365 天计算，不是自然月、自然季度和自然年。
- 并发办理无防护（“已有有效月卡”检查在事务外，`monthly/service/service.go:38-44`）。
- 缺少过期清理、提前续费、冻结、转车、退款计算等业务规则。

### 3.3 交接班只覆盖现金

- 只统计 `payment_method='cash'`（`shift/service/service.go:41-43` 裸 SQL），POS、扫码、月卡等流水漏计。
- 支付流程没有要求操作员必须处于当班状态（不开班也能收款，ShiftService 无外部调用点）。
- 开班、收款和交班缺少统一事务约束；Start/End 无并发防护（可并发开出两个 active 班次）。
- 缺少管理者复核、差异审批、交班单打印和交班后锁定。
- 页面缺少完整分页、筛选、备注管理和审核能力。

### 3.4 收入报表维度和财务口径不足

- 当前主要按日期和停车场汇总，只单独展示现金和免费（`report/service/service.go:16-33`）。
- 缺少支付入口、支付方式、操作员、班次、车型、通道等维度。
- 缺少退款、撤销、冲正、月卡收入（当前月卡流水 record_id=0，混入现金列）和交班差异。
- 缺少明细追溯、日结、月结、导出和打印（后端无导出接口，前端无导出按钮）。
- 财务对账缺失：`payment_record` 与 `digital_ticket` 金额无交叉校验。

### 3.5 数字票过期状态没有自动执行机制

- 已定义 `expired` 状态和状态流转规则，但 `ExpireAt` 字段从未被赋值，无定时任务把票转 expired（定时任务仅 ClearDB，`timer.go:17-22`）；Summary 的 expired 统计恒为 0。
- 需要明确待支付票、已支付未离场票分别在何种条件下过期，以及过期后的恢复策略。

### 3.6 道闸和设备模型不够独立（2026-08-13 补充实测缺陷）

- 当前工作台从 `UHFReader` 获取道闸设备，读卡器和道闸控制器共用设备模型；无法完整表达通道多设备拓扑。
- **模拟道闸配置当前即为 true**（`config.yaml:191`）：开启时停用全部 UHF/RFID，开闸“永远成功”，生产误开无任何代码级校验/告警。
- **道闸指令只发不验**：串口写错误被 `_ =` 吞掉（`serial_reader.go:115`）；响应帧内容丢弃不校验 ACK（`reader.go:401-405`）；`SendAndRecv` 与主读循环共享无锁 buffer 存在竞态（`serial_reader.go:16,91-98`）。
- **离线判定误报**：串口空闲 1s 超时、TCP 分片 <25 字节均被判离线 → 空载设备 status 抖动、反复断连重连；首次 Connect 失败无重试（`reader.go:219-221`）。
- **设备状态四套并存矛盾**：DB status / DeviceManager（断线不注销）/ ConnManager（死代码双轨）/ GetGateRuntimeStatus；前端两个接口数据源不一致。
- passage 只发 OpenGate 无落杆指令流水（延时落杆无确认无审计）。
- 缺少闸杆状态反馈、地感、防砸、落杆确认、失败重试和指令流水。

### 3.7 停车场基础配置约束不足

- 已修复按 `LotId` 查询条件、容量低于当前在场车辆数校验，以及存在未出场会话时禁止删除。
- 删除停车场前仍未检查岗亭、通道和设备关联。
- 历史停车会话所属停车场被软删除后，历史页面名称展示需统一处理。
- 余位为负无检测：写入端 CASE 钳制静默生效，启动校准 `reconcileParkingLotOccupancy` 发现漂移不埋点不告警。

### 3.8 操作审计和敏感数据保护不足

- 操作日志保存请求体和响应体，未见密码、令牌、支付字段统一脱敏（详见 2.0）。
- 摄像头账号密码缺少加密存储方案。
- 设备失败主要写日志，尚未进入业务告警和异常处置中心。
- `fmt.Printf` 直出 20+ 处（passage/uhf/shift/timer），自定义 GinRecovery 中间件未启用。

## 4. P2：完全缺失或只有模型

| 功能 | 当前状态 | 目标能力 |
| --- | --- | --- |
| 车牌摄像头接入 | 只有 `camera` 数据实体 | 摄像头配置、RTSP/SDK、OCR 回调、置信度、抓拍、防重复识别、通道绑定 |
| 中央缴费机 | 只有支付入口概念 | 终端注册、心跳、订单查询、支付、出场校验、远程配置 |
| LED 余位屏 | 未实现 | 屏幕配置、协议适配、余位推送、离线重试 |
| 线上支付 | 未实现 | 微信/支付宝等下单、回调、查询、退款和对账 |
| 设备告警中心 | 未实现 | 在线状态、故障事件、告警等级、确认和恢复 |
| 远程设备诊断 | 未实现 | 设备参数、连通性测试、指令测试、诊断审计 |
| 数据备份恢复 | 未实现 | SQLite 备份、校验、恢复、保留策略和恢复演练（当前无 WAL、`busy_timeout=0` 并发写锁风险） |
| 数据归档清理 | 未实现 | 历史会话、日志、抓拍图片的归档和容量管理（仅 ClearDB 清 2 张表） |
| 报表导出打印 | 未实现 | Excel/PDF 导出、日结单、月报和打印 |
| 打印任务管理 | 未实现 | 打印机配置、任务队列、状态、失败重试和重打权限 |
| 短信/邮件验证 | 模拟实现 | 服务商配置、发送限制、验证码校验和审计 |
| 通道事件持久化 | 内存 50 条队列 | 落库、重启恢复、与异常/指令流水联动 |

## 5. 工程与部署缺陷（2026-08-13 新增）

1. gin 恒为 debug 模式（无 release 配置，`core` 从未调用 `gin.SetMode(gin.ReleaseMode)`）；`os.Exit(0)` 用成功码退出（`gorm.go:74`）；`ListenAndServe` 失败仅 log 进程不退（`server.go:44`）。
2. SQLite 无 WAL（实测 `journal_mode=delete`）、无 `busy_timeout`，多协程并发写有锁冲突风险；无自动备份。
3. `deploy/` 全套与项目布局脱节（gva 原版遗留，引用不存在的 server/ 目录）。
4. 双入口不一致：Wails 入口 embed 前端 dist 并剥离 `/api` 前缀；`cmd_backend_only` 不托管前端，前端 env 写死 `VITE_BASE_API=/api`，直接部署时 404。
5. 前端 bug：`view/report/enter.vue:212` 引用未定义的 `t`，列表加载失败时 ReferenceError。
6. LoginOut 失败不清理本地 token（`pinia/modules/user.js:91-98`）；`request.js` 401 处理依赖用户点击“重新登录”，取消则不登出。
7. i18n 不完整：statistics/vehicle.vue 14 处、login 13 处硬编码中文。
8. 配置零校验：无端口冲突预检、路径存在性、取值范围校验。

## 6. 测试覆盖缺口

现有自动化测试覆盖停车会话、数字票、支付金额边界、重复和并发支付、事务回滚、道闸接口、USB 票据版式、异常处置（状态机/埋点/权限）、月卡事务、计费引擎与收费配置校验。以下范围仍缺少完整测试：

- 票机打印任务持久化、失败补偿、重打和作废权限。
- 月卡退款的跨表事务和退款金额计算。
- 交接班、收入报表和多支付方式对账。
- 多日计费、跨日规则、缴费后超时和收费配置异常（多日封顶已覆盖，跨日规则未实现）。
- 异常事件的生成、处置、权限和审计（已基本覆盖）。
- 摄像头、地感、真实道闸、LED 屏的集成和现场测试。
- 数据备份、恢复和故障恢复演练。
- **安全面：api 层、middleware（JWT/Casbin/操作日志脱敏）、登录、越权（618 提权）零测试**。

## 7. 推荐实施顺序

1. **安全修复**：封堵 `admin_register` 提权（AuthorityId 校验 + 撤销 618 权限）、操作日志脱敏、uploads 鉴权、种子默认凭据处理。
2. 建立支付订单层，接入 POS、扫码和中央缴费机；缴费后离场时限与超时补缴。
3. 生产防护：gate-simulator 运行时告警、道闸指令只发不验修复、`os.Exit` 与 release 模式。
4. 月卡退款/自然月季年/并发防护，交接班全方式对账与审批。
5. 接入摄像头、地感、道闸反馈和 LED 余位屏。
6. 报表导出、打印任务、备份恢复（WAL + 定期快照）、数据归档和部署包。

## 8. 维护规则

- 功能开始开发时，在对应条目中补充负责人、计划版本和关联任务。
- 功能完成后必须同时满足代码实现、权限控制、自动化测试和业务验收，不能仅因页面或配置存在就标记完成。
- 已完成条目从本文移除前，应同步更新 `项目进度.md`、相关流程文档和测试报告。