|
|
@@ -0,0 +1,181 @@
|
|
|
+# CLAUDE.md
|
|
|
+
|
|
|
+本项目是智慧停车管理系统 (Smart Parking)，基于 Wails v2 构建的单进程桌面应用（Go 后端 + Vue 3 前端内嵌 WebView2）。
|
|
|
+
|
|
|
+## 技术栈
|
|
|
+
|
|
|
+| 层级 | 技术 |
|
|
|
+| ---------- | ------------------------------------------ |
|
|
|
+| 桌面框架 | **Wails v2.13**（WebView2 运行时） |
|
|
|
+| 后端 | Go 1.25 + Gin + GORM + Casbin + JWT |
|
|
|
+| 前端 | Vue 3 + Vite 4 + Element Plus + Pinia |
|
|
|
+| 数据库 | **SQLite**（`%APPDATA%/smart-parking/lc_garage.db`） |
|
|
|
+
|
|
|
+## 项目结构
|
|
|
+
|
|
|
+```
|
|
|
+lc_garage/
|
|
|
+├── main.go # Wails 入口（反向代理 /api → Gin :8888）
|
|
|
+├── go.mod / go.sum # 根模块 (wails-app)
|
|
|
+├── wails.json # Wails 项目配置
|
|
|
+├── config.yaml # 后端配置文件
|
|
|
+├── server_backup.tar.gz # 旧 server/ 备份（67MB，已归档）
|
|
|
+│
|
|
|
+├── internal/ # ★ Go 后端（所有代码）
|
|
|
+│ ├── main.go # InitBackend() 入口
|
|
|
+│ ├── api/v1/ # API 控制器层
|
|
|
+│ │ ├── system/ # 系统管理（用户/角色/菜单/API/Casbin/字典）
|
|
|
+│ │ ├── parking/ # 停车管理（停车场/岗亭/通道）
|
|
|
+│ │ ├── uhf/ # UHF 读卡器管理
|
|
|
+│ │ ├── vehicle/ # 车辆管理（车辆/收费/记录/类型/名单）
|
|
|
+│ │ ├── owner/ # 车主管理
|
|
|
+│ │ └── example/ # 示例（文件上传/断点续传）
|
|
|
+│ ├── service/ # 业务逻辑层
|
|
|
+│ │ ├── system/ # 系统服务（11 文件，含 Casbin）
|
|
|
+│ │ ├── parking/ # 停车服务（booth/channel/lot）
|
|
|
+│ │ ├── uhf/ # UHF 服务（TCP/串口读写器驱动）
|
|
|
+│ │ ├── vehicle/ # 车辆服务（进出场+计费）
|
|
|
+│ │ ├── owner/ # 车主服务
|
|
|
+│ │ └── enter.go # ServiceGroupApp 全局注册中心
|
|
|
+│ ├── router/ # 路由定义（与 api 一一对应）
|
|
|
+│ │ └── enter.go # RouterGroupApp 全局注册中心
|
|
|
+│ ├── model/ # 数据模型（Request / Response DTO）
|
|
|
+│ │ ├── common/ # 通用模型（分页/响应结构）
|
|
|
+│ │ ├── system/ # 系统模型
|
|
|
+│ │ ├── parking/ # 停车模型
|
|
|
+│ │ ├── uhf/ # UHF 模型
|
|
|
+│ │ ├── vehicle/ # 车辆模型
|
|
|
+│ │ └── owner/ # 车主模型
|
|
|
+│ ├── dao/ # 数据访问层（GORM 实体，25 张表）
|
|
|
+│ ├── middleware/ # 中间件（JWT/CORS/Casbin/操作日志）
|
|
|
+│ ├── config/ # 配置结构体定义
|
|
|
+│ ├── core/ # 核心（Viper/Zap/Server 启动）
|
|
|
+│ ├── global/ # 全局变量（GVA_DB/GVA_CONFIG/GVA_LOG）
|
|
|
+│ ├── initialize/ # 初始化（GORM/Redis/Seed/Timer/UHF）
|
|
|
+│ ├── plugin/ # 插件（email/ws/plugin-tool）
|
|
|
+│ ├── utils/ # 工具函数（upload/captcha/AST/定时器）
|
|
|
+│ └── pkg/ # 工具函数副本（部分 core 文件引用）
|
|
|
+│
|
|
|
+├── frontend/ # Vue 3 前端
|
|
|
+│ ├── vite.config.js # Vite 配置（dev :5173 → proxy :8888）
|
|
|
+│ └── src/
|
|
|
+│ ├── api/ # API 封装（24 文件，117 接口）
|
|
|
+│ ├── view/ # 业务页面（37 个 .vue 文件）
|
|
|
+│ │ ├── parking/ # 停车管理（含 Tab 联动）
|
|
|
+│ │ ├── dashboard/ # 仪表盘
|
|
|
+│ │ ├── report/ # 报表查询
|
|
|
+│ │ ├── statistics/ # 统计分析
|
|
|
+│ │ ├── superAdmin/ # 系统管理
|
|
|
+│ │ ├── person/ # 个人中心
|
|
|
+│ │ └── login/ # 登录页
|
|
|
+│ ├── pinia/ # 状态管理（user + parkArea）
|
|
|
+│ └── router/ # 路由（Hash 模式 + 动态菜单）
|
|
|
+│
|
|
|
+├── build/bin/ # 构建输出
|
|
|
+│ └── smart-parking.exe # 最终产物（需与 config.yaml 同目录）
|
|
|
+│
|
|
|
+└── doc/ # 文档
|
|
|
+ ├── PROJECT.md
|
|
|
+ └── 代码规划.md # 目标架构蓝图
|
|
|
+```
|
|
|
+
|
|
|
+## 代码组织规范
|
|
|
+
|
|
|
+### 旧代码 (internal/api, internal/service, ...)
|
|
|
+
|
|
|
+现有的 `api/` `service/` `router/` `model/` `dao/` 目录保持不动，所有现有功能继续维护在原有位置。
|
|
|
+
|
|
|
+### 新模块 (internal/modules/)
|
|
|
+
|
|
|
+新功能按领域模块开发，放在 `internal/modules/<module>/` 下。每个模块内部自包含三层结构：
|
|
|
+
|
|
|
+```
|
|
|
+internal/modules/<module>/
|
|
|
+├── api.go # 对外暴露给 Wails/路由的方法
|
|
|
+├── service/ # 业务逻辑
|
|
|
+│ ├── service.go # 核心逻辑
|
|
|
+│ └── ...
|
|
|
+├── repository/ # 数据访问（替代 dao/）
|
|
|
+│ └── repo.go # GORM 查询封装
|
|
|
+└── model/ # 数据模型
|
|
|
+ ├── request/ # 请求 DTO
|
|
|
+ └── response/ # 响应 DTO
|
|
|
+```
|
|
|
+
|
|
|
+**模块间通信规则**：
|
|
|
+- 模块之间通过 `internal/service/enter.go` 中的 `ServiceGroupApp` 引用其他模块的服务
|
|
|
+- 避免模块间直接 import，防止循环依赖
|
|
|
+- 共享类型（如分页、统一响应）放在 `internal/model/common/` 下
|
|
|
+
|
|
|
+**注册新模块路由**：
|
|
|
+1. 在 `internal/modules/<module>/api.go` 中定义 Handler 方法
|
|
|
+2. 在 `internal/router/` 下新增路由文件注册路由组
|
|
|
+3. 在 `internal/initialize/router.go` 中调用路由注册
|
|
|
+
|
|
|
+### pkg vs utils
|
|
|
+
|
|
|
+- `internal/utils/` — 旧工具函数（api 层引用）
|
|
|
+- `internal/pkg/` — 新工具函数（core/initialize 层引用）
|
|
|
+- 两者内容相同但 import 路径不同，暂不合并
|
|
|
+
|
|
|
+## 配置说明
|
|
|
+
|
|
|
+```yaml
|
|
|
+system:
|
|
|
+ addr: 8888 # 后端监听端口
|
|
|
+ db-type: sqlite # 数据库类型
|
|
|
+sqlite:
|
|
|
+ path: "" # 空 = %APPDATA%/smart-parking/lc_garage.db
|
|
|
+ db-name: lc_garage
|
|
|
+cors:
|
|
|
+ mode: allow-all # 桌面应用，允许所有跨域
|
|
|
+```
|
|
|
+
|
|
|
+## 启动方式
|
|
|
+
|
|
|
+### 环境要求
|
|
|
+
|
|
|
+- Go >= 1.25 / Node.js >= 16
|
|
|
+- Wails CLI：`go install github.com/wailsapp/wails/v2/cmd/wails@latest`
|
|
|
+- Windows 10 build 1809+（WebView2）
|
|
|
+
|
|
|
+### 开发模式
|
|
|
+
|
|
|
+```bash
|
|
|
+cd lc_garage
|
|
|
+cd frontend && npm install && cd .. # 首次
|
|
|
+wails dev # 热更新 + DevTools
|
|
|
+```
|
|
|
+
|
|
|
+### 生产构建
|
|
|
+
|
|
|
+```bash
|
|
|
+cd lc_garage
|
|
|
+wails build
|
|
|
+# 产物：build/bin/smart-parking.exe
|
|
|
+```
|
|
|
+
|
|
|
+## 管理员账户
|
|
|
+
|
|
|
+- 账号：`admin` / 密码：`123456`（首次启动自动创建）
|
|
|
+
|
|
|
+## 角色菜单
|
|
|
+
|
|
|
+| Authority | 角色 | 可见菜单 |
|
|
|
+|-----------|------|---------|
|
|
|
+| 888 | 管理员 | 全部 |
|
|
|
+| 618 | 操作员 | 停车管理 + 报表 + 统计 |
|
|
|
+
|
|
|
+## 常用命令
|
|
|
+
|
|
|
+```bash
|
|
|
+# 开发
|
|
|
+cd lc_garage && wails dev
|
|
|
+
|
|
|
+# 构建
|
|
|
+cd lc_garage && wails build
|
|
|
+
|
|
|
+# 前端
|
|
|
+cd lc_garage/frontend && npm install
|
|
|
+cd lc_garage/frontend && npm run build
|
|
|
+```
|
