lc_garage/doc/项目问题分析与修复方案.md

智慧停车项目问题分析与修复方案

分析日期：2026-09-07
分析范围：lc_garage 实际源码、配置、前端构建、项目文档与 Git 历史
结论性质：代码与配置静态审查 + 可执行构建验证，不替代真实闸机、打印机、摄像头和支付终端的现场验收。

1. 结论摘要

项目已经完成从旧的 GIN-VUE-ADMIN 服务端形态向 Wails 单进程桌面应用的主要迁移，并具备停车场配置、停车会话、数字票、支付流水、月卡、交接班、报表、打印和异常处置等基础模块。当前代码也已经出现 internal/modules 领域模块化结构，说明迁移正在持续进行。

距离可稳定交付仍有三类问题：

1. 生产安全边界不够明确：上传、Swagger、监控和中央缴费机入口的公开性需要逐项确认；默认账号、敏感配置和调试能力仍应纳入发布安全策略。
2. 设备和资金业务闭环不足：真实支付、道闸反馈、打印失败补偿、摄像头识别、LED 余位屏、备份恢复和对账仍有明显缺口。
3. 文档和工程入口存在漂移：根目录 AGENTS.md、旧版 PROJECT.md、lc_garage/README.md、doc/PROJECT.md 和 doc/功能缺失.md 的架构、数据库和完成状态描述不完全一致。

2. 已验证现状

2.1 结构与入口

• 实际应用目录为 lc_garage/，根目录是项目文档工作区。
• Wails 入口为 lc_garage/main.go，通过 //go:embed all:frontend/dist 嵌入前端，并将 /api/* 反向代理到 Gin :8888。
• 后端实际代码位于 lc_garage/internal/，不存在文档中曾描述的 lc_garage/server/ 主目录。
• 前端同时存在 frontend/ 和 web/ 两套目录；Wails 配置明确使用 frontend，web 更像历史遗留或兼容目录。
• 新模块已实际存在：parking-session、digital-ticket、payment、monthly、shift、report、printer、incident、central-payment、deviceprovisioning 等。

2.2 验证结果

• frontend: npm run build 成功，Vite 生成生产包；构建有 Sass 弃用提示及两个超过 500 KB 的 chunk 警告。
• go test ./...: 当前环境失败在 Go 构建缓存目录 C:\Users\longc\AppData\Local\go-build 的访问权限，输出为 Access is denied，不能视为代码测试失败。
• 项目进度文档声称的模块级测试命令应使用项目可写的 GOCACHE，并在 CI 中固定执行，避免环境权限造成误判。

3. 问题清单

P0：上线前必须处理

P0-1 公开路由和敏感数据访问边界需要收紧

证据：internal/initialize/router.go:70-92。

• Router.StaticFS(global.GVA_CONFIG.Local.StorePath, ...) 直接提供本地上传目录；车牌抓拍、头像等文件可通过可预测路径访问。
• Swagger 在 :swagger/*any 直接注册，未看到生产环境开关。
• dashboardRouter.InitDashboardRouter(PublicGroup) 将监控接口放在公开组；CPU、内存等运行信息不应默认匿名暴露。
• PublicGroup.POST("/device-images/upload", deviceimage.Upload) 公开注册，上传接口应明确鉴权、文件类型、大小、路径和访问权限。
• 中央缴费机公开接口是设备对接需要，但必须只允许设备令牌、来源网络或签名请求，不能按普通公开 API 处理。

修复方案：

1. 将上传改为受 JWT/Casbin 保护的下载接口，或使用短时签名 URL；禁止目录遍历和原始文件名落盘。
2. 增加 system.expose-swagger、system.expose-monitor 等显式配置，生产默认关闭。
3. 设备图片上传和中央缴费机接口分别使用设备认证中间件；记录设备 ID、请求摘要和失败原因。
4. 为公开路由增加路由安全测试：匿名访问必须只允许健康检查和明确的设备协议接口。

P0-2 默认凭据和密钥管理不适合生产

证据：internal/initialize/seed.go 包含固定 bcrypt 密码和 README.md:32-35 公开写出 admin/123456；config.yaml 还保留对象存储示例密钥字段。

修复方案：

• 首次启动进入初始化向导，强制设置管理员密码；发布包不再预置可直接登录的通用密码。
• 将 JWT secret、设备 token、摄像头密码和第三方支付密钥移出仓库，使用系统凭据存储或受保护配置文件。
• 对历史数据库提供管理员密码轮换迁移；启动时检测默认密码并阻止生产模式继续运行。

P0-3 SQLite 并发写、备份和恢复策略缺失

证据：internal/initialize/gorm_sqlite.go:47-53 只设置连接池，没有设置 WAL、busy_timeout 或备份策略；config.yaml:185-199 允许 max-open-conns: 100。

风险：设备事件、支付、操作日志和定时任务并发写入时可能出现 database is locked；进程或磁盘损坏会导致本地运营数据丢失。

修复方案：

1. SQLite 初始化后执行 PRAGMA journal_mode=WAL、PRAGMA busy_timeout=5000、合理的 synchronous 设置，并将写并发控制在可验证范围。
2. 增加在线一致性备份或安全快照，备份文件校验、保留周期和恢复演练。
3. 对支付、停车会话、月卡和交接班增加恢复后校验任务，发现跨表不一致时生成异常事件。
4. 增加并发写压力测试和断电恢复测试，测试不依赖用户目录下不可写的 Go 缓存。

P0-4 服务启动失败处理不可靠

证据：internal/core/server.go:34-40 调用 s.ListenAndServe().Error()；internal/initialize/gorm.go:77-84 在迁移失败时使用 os.Exit(0)。

风险：监听失败可能触发 nil error 解引用；数据库迁移失败却以成功码退出，Windows 启动器和发布脚本无法正确识别失败。

修复方案：

• 保存 err := s.ListenAndServe()，对 http.ErrServerClosed 单独处理，其余错误记录并以失败状态退出或通知 Wails 主进程。
• 将 os.Exit(0) 改为错误返回/受控退出码 1，并在启动错误日志中写明迁移步骤和恢复建议。
• 启动前执行端口、数据库路径和配置值校验，失败时不要启动前端窗口。

P0-5 真实资金交易尚未形成可审计闭环

证据：doc/功能缺失.md 和 internal/modules/payment 的现状说明；当前 payment_record 主要记录本地业务结果，POS、扫码和中央缴费机仍需真实设备或网关确认。

修复方案：

• 建立支付订单状态机：待支付、处理中、成功、失败、不确定、已退款、已撤销。
• 为支付记录增加渠道订单号、幂等键、回调时间、原始渠道状态和退款/冲正关联。
• 外部支付只能在可信回调、主动查询或设备签名结果确认后标记成功；重复回调必须幂等。
• 交接班和收入报表按支付入口、支付方式、操作员、班次、退款和差异统一对账。

P1：应在近期完成

P1-1 道闸和读卡器状态模型仍然混杂

现状记录见 doc/功能缺失.md:117-139。读卡器、闸机控制器、连接管理器和运行时状态存在多套来源；串口/TCP 的 ACK、分片、超时、重连和落杆反馈还需要现场验证。

修复方案：拆分设备类型与通道拓扑，统一 DeviceRuntime 状态源；所有开闸/关闸命令落 device_command_log，校验 ACK、超时和重试，增加地感、防砸、落杆确认和人工兜底测试。

P1-2 模拟道闸必须具备不可误用的运行保护

config.yaml:210 当前为 gate-simulator: false，默认值正确；但仍应在启动时显示运行模式，并在生产构建或生产配置中拒绝开启模拟模式。模拟模式下的“开闸成功”不能被当作真实硬件确认。

修复方案：增加 environment=production 与 gate-simulator 互斥校验；模拟模式所有指令标记 simulated=true，前端和审计记录明确显示。

P1-3 打印失败没有持久化补偿任务

现状：票机打印仍以同步硬件调用为主，失败重试、重打、作废和异常处置尚未形成完整任务模型。

修复方案：新增打印任务表和状态机，先创建任务再执行硬件动作；记录短写、串口错误、设备离线和重试次数，允许受权限控制的重打/作废，并与数字票和停车会话建立补偿规则。

P1-4 月卡、交接班和收入报表的财务口径仍不完整

现状：月卡退款缺少完整退款流水和审批；自然月/季/年、并发办理、人工白名单保护需要继续完善；交接班和报表还需要覆盖所有支付方式、退款和差异。

修复方案：

• 月卡办理、续费、退款、白名单变更和支付流水使用同一事务及幂等键。
• 用日历月/季度/年度计算有效期，明确过期、冻结、转车和退款规则。
• 交接班增加唯一 active 约束、收款前当班校验、管理者复核和锁定机制。
• 报表提供明细追溯、导出、打印和支付记录对账。

P1-5 数字票过期任务和跨表对账不足

doc/功能缺失.md 指出 ExpireAt 自动执行和状态不一致检测仍不完整。应明确待支付票、已支付未离场票的过期规则，并由定时任务执行状态迁移和异常告警。

P2：产品能力和工程质量提升

• 摄像头 RTSP/SDK、OCR 置信度、防重复识别和通道绑定。
• LED 余位屏协议、推送、离线重试和恢复同步。
• 远程设备诊断、设备告警中心和现场运维审计。
• 历史会话、日志和抓拍图片归档清理；上传文件容量配额。
• 短信/邮件验证从模拟实现升级为真实供应商适配，并增加频率限制。
• 通道事件从内存队列升级为持久化队列，支持重启恢复。
• 前端 bundle 拆分，处理 ECharts 约 1 MB chunk；清理 Sass @import/legacy API 弃用警告。
• 增加 API、JWT、Casbin、操作日志脱敏、登录登出、越权和配置校验测试。

4. 文档与结构问题

4.1 架构描述互相冲突

• 根目录 PROJECT.md 仍描述 server/ 独立后端、MySQL 和旧 Electron 结构，与实际 Wails + SQLite 代码不符。
• AGENTS.md、lc_garage/README.md 和 doc/PROJECT.md 对结构的描述不一致：前者较旧，后两者基本反映当前布局。
• doc/功能缺失.md 中部分安全问题已在提交 8cca42f 修复，例如注册角色层级校验、操作日志脱敏、模拟闸机告警，但文档仍把它们写成当前漏洞。
• doc/项目进度.md 更新日期早于最近代码提交，完成状态与后续新增的中央缴费机、设备接入模块没有完全同步。

修复方案：

1. 以 lc_garage/doc/PROJECT.md 作为唯一项目说明，以 lc_garage/README.md 作为快速开始文档。
2. 将根目录 PROJECT.md 标记为历史文档或删除，避免新成员误用 MySQL/server 启动方式。
3. 给 doc/功能缺失.md 增加“已修复/仍存在”分栏、代码版本和验证命令；删除已完成项的当前时态描述。
4. 每次领域功能合并时同步更新 项目进度.md、流程文档和测试记录，并在 CI 检查文档中的路径是否存在。

4.2 双前端目录需要明确归属

Wails 使用 frontend，但 web 仍保留完整 Vue 源码和 Vite 配置。双目录会导致修复只落在一处、构建结果与开发结果不一致。

修复方案：短期在 README 和 wails.json 中明确 frontend 为唯一构建源；中期归档或删除 web，若必须兼容则用脚本从唯一源生成，不允许手工双写。

5. 前端已确认缺陷

5.1 报表异常处理引用未定义变量

frontend/src/view/report/enter.vue:222-224 的异常处理调用 t.value.getListFail，文件中没有对应的 t 定义。接口失败时会再次触发 ReferenceError，原始错误信息被覆盖。

修复方案：改为已有的 $t/语言包访问方式，或定义统一的 useI18n 实例；补充请求失败分支测试。

5.2 登出失败时本地凭据清理策略不统一

frontend/src/pinia/modules/user.js:91-98 只有黑名单接口返回成功才清理 token；而 frontend/src/utils/request.js:147-162 的 401 处理依赖用户确认。

修复方案：登出无论服务端结果如何都清理本地 token；401 统一立即清理并跳转登录，弹窗只用于提示，不应让失效凭据继续留存。

6. 推荐实施顺序

顺序	优先级	工作包	完成标准
1	P0	路由、上传、Swagger、监控和设备接口安全边界	匿名访问测试通过；上传不可猜测读取；生产 Swagger/监控默认关闭
2	P0	默认凭据、密钥和配置校验	首次启动强制改密；仓库不含可用生产密钥；非法端口/路径拒绝启动
3	P0	SQLite WAL、锁等待、备份恢复	并发写压测通过；备份可校验；恢复演练有记录
4	P0	启动失败和进程退出语义	迁移/监听失败返回非零并写清晰诊断，不出现 nil error panic
5	P0	支付订单、回调幂等和财务对账	成功/失败/不确定/退款/冲正可追溯，重复通知不重复收费
6	P1	道闸、读卡器、打印机现场闭环	ACK、超时、重试、离线、落杆和打印补偿均有集成测试
7	P1	月卡、交接班、报表和数字票过期	事务、并发、退款、班次和跨表对账规则明确并覆盖测试
8	P1	摄像头、设备告警和 LED	设备状态、事件、恢复和余位推送可在现场验收
9	P2	文档收敛、双前端归档和前端性能	唯一开发入口，文档路径与状态可由 CI 校验

7. 验收与持续检查

发布前至少执行：

cd D:\lq\Smart Parking\lc_garage
$env:GOCACHE = "D:\lq\Smart Parking\lc_garage\build\gocache-ci"
go test ./... -count=1

cd frontend
npm run build

另外需要单独保留以下验收记录：真实闸机开/关及断网、真实打印机短写和重打、摄像头重复识别、POS/中央缴费机回调幂等、SQLite 备份恢复、管理员和操作员越权测试。只有代码、权限、自动化测试和现场流程同时通过，相关功能才应标记为“已完成”。