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/ 下

注册新模块路由：

在 internal/modules/<module>/api.go 中定义 Handler 方法
在 internal/router/ 下新增路由文件注册路由组
在 internal/initialize/router.go 中调用路由注册

pkg vs utils

internal/utils/ — 旧工具函数（api 层引用）
internal/pkg/ — 新工具函数（core/initialize 层引用）
两者内容相同但 import 路径不同，暂不合并

配置说明

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）

开发模式

cd lc_garage
cd frontend && npm install && cd ..   # 首次
wails dev                              # 热更新 + DevTools

生产构建

cd lc_garage
wails build
# 产物：build/bin/smart-parking.exe

管理员账户

账号：admin / 密码：123456（首次启动自动创建）

角色菜单

Authority	角色	可见菜单
888	管理员	全部
618	操作员	停车管理 + 报表 + 统计

项目规范

Git 提交备注：使用中文，格式 类型: 简要描述，如 feat: 新增停车场信息菜单、fix: 修复字典查询 EOF

常用命令

# 开发
cd lc_garage && wails dev

# 构建
cd lc_garage && wails build

# 前端
cd lc_garage/frontend && npm install
cd lc_garage/frontend && npm run build

CLAUDE.md 7.5 KB Permalink Histórico Raw