# 智慧停车管理系统项目说明

> 项目：`lc_garage`
> 更新日期：2026-08-07
> 形态：Wails 单进程 Windows 桌面应用

## 1. 项目定位

智慧停车管理系统用于停车场的基础配置、车辆进出场、收费结算、数字票、交接班、报表和本地设备联动。

系统以**停车会话**作为一辆车一次停车过程的事实载体，以**数字票**作为支付和离场状态载体，以**支付流水**作为资金事实载体。三者职责分离，但在进出场事务中保持一致。

## 2. 技术架构

| 层级 | 技术 |
| --- | --- |
| 桌面容器 | Wails v2.13 + WebView2 |
| 后端 | Go 1.25、Gin、GORM、Casbin、JWT |
| 前端 | Vue 3、Vite 4、Element Plus、Pinia、ECharts |
| 数据库 | SQLite，默认 `%APPDATA%/smart-parking/lc_garage.db` |
| 设备 | UHF 读卡器、模拟/真实闸机、串口或 USB 小票打印机 |

```text
Wails 桌面程序
├─ Gin API（默认 :8888）
├─ Vue 3 WebView2 前端
│  └─ /api/* 由 Wails 反向代理至 Gin
└─ SQLite 本地数据库
```

## 3. 当前代码结构

```text
lc_garage/
├─ main.go                         # Wails 入口与 API 反向代理
├─ internal/
│  ├─ api/v1/                      # 既有 API 控制器
│  ├─ service/                     # 既有业务与设备服务
│  ├─ router/                       # 既有路由组
│  ├─ dao/                          # GORM 实体
│  ├─ model/                        # 通用、请求与响应模型
│  ├─ initialize/                   # 数据库、种子数据、路由、设备初始化
│  └─ modules/                      # 新领域模块
│     ├─ parking-session/           # 停车会话
│     ├─ digital-ticket/            # 数字票
│     ├─ payment/                   # 支付入口、方式和支付流水
│     ├─ monthly/                   # 包月车
│     ├─ shift/                     # 交接班
│     ├─ report/                    # 收入报表
│     └─ printer/                   # 串口/USB 小票打印
├─ frontend/src/
│  ├─ view/parking/                 # 进出场、数字票、支付配置、包月车、交接班
│  ├─ view/report/                  # 进出记录、支付记录、收入报表
│  └─ view/dashboard/               # 仪表盘与车辆监控
└─ doc/                             # 项目、流程、进度和测试文档
```

## 4. 核心领域模型

| 对象 | 表/模块 | 职责 |
| --- | --- | --- |
| 停车会话 | `vehicle_record` / `parking-session` | 一次停车的入场、出场、停车场、通道设备快照和结算摘要 |
| 数字票 | `digital_ticket` / `digital-ticket` | 会话的支付和离场状态、票号、事件日志 |
| 支付流水 | `payment_record` / `payment` | 实际收款、实收、找零、支付入口、支付方式、操作员 |
| 通道设备 | `channel`、`uhf_reader` | 通道方向、停车场归属、设备绑定与在线状态 |

### 停车会话的通道设备快照

入场和出场分别保存通道 ID、通道编码、通道名称、设备编码、设备名称。名称用于业务查看，编码和 ID 用于追踪；通道或设备后续改名不会影响新记录的历史可读性。

对于旧记录，查询时会根据已保存的通道 ID、设备编码补全当前名称；若关联配置已删除，则回退显示编码。

## 5. 启动与构建

```powershell
# 首次安装前端依赖
cd frontend
npm install
cd ..

# 开发模式
wails dev

# 前端生产构建校验
cd frontend
npm run build

# 构建 Windows 应用
cd ..
wails build
```

构建产物为 `build/bin/smart-parking.exe`。首次启动会执行 SQLite 自动迁移和系统种子数据初始化。

## 6. 默认账户

首次初始化后可使用：

- 管理员：`admin` / `123456`
- 操作员权限标识：`618`
- 管理员权限标识：`888`

## 7. 相关文档

- [项目进度](项目进度.md)
- [进出场流程详解](进出场流程详解.md)
- [数字票说明](digital-ticket.md)
- [收费流程](收费流程.md)
- [测试用例编写规范](测试用例编写规范.md)
- [目标代码规划](代码规划.md)