# 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 | 操作员 | 停车管理 + 报表 + 统计 |

## 项目规范

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

## 常用命令

```bash
# 开发
cd lc_garage && wails dev

# 构建
cd lc_garage && wails build

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