91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
**智慧清洁 SaaS 平台（SmartClean）** — 物业/市政清洁行业的后台管理系统，涵盖基础信息管理、用户与权限管理、任务调度（保洁/巡检/设备维护）、打卡考勤、人效分析等核心业务。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端 | Vue 3 + Vite 2 + Element Plus + Vuex + Vue Router (Hash 模式) |
|
||
| 后端 web | Spring Boot 2.4.8 (Java 8) + MyBatis-Plus 3.4 + MySQL + Druid 连接池 |
|
||
| 后端 task | Spring Boot 2.4.8 + XXL-Job 2.3 + MQTT (Paho) + 个推推送 |
|
||
| 公共模块 | Lombok + Hutool + FastJSON + Swagger 2 |
|
||
| 缓存/搜索 | Redis (Lettuce) + Elasticsearch (BBoss 6.3) |
|
||
| 日志 | Log4j (排除了 Spring Boot 默认 Logback) |
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
smartclean/
|
||
├── frontend/witcleansystem/ # Vue 3 前端 SPA
|
||
│ ├── src/
|
||
│ │ ├── Apis/api.js # 所有 REST API 端点集中定义
|
||
│ │ ├── ApiService/ # 按业务域封装的 API 调用服务
|
||
│ │ ├── Components/ # 业务组件 + public/ 下全局公共组件
|
||
│ │ ├── Page/ # 页面组件，按业务模块分子目录
|
||
│ │ ├── Router/ # 路由定义，module/ 下按业务拆分
|
||
│ │ ├── Store/ # Vuex 状态管理
|
||
│ │ ├── Utils/ # 工具函数（请求封装、通用方法）
|
||
│ │ └── Hooks/ # 组合式逻辑
|
||
│ └── .env.* # 环境配置（develop/test/production）
|
||
├── backend/
|
||
│ ├── xiaoqu-intellectual-public/ # 公共模块（实体、工具类），被其他模块依赖
|
||
│ ├── xiaoqu-intellectual-web/ # Web API 主服务，打包为 WAR (ROOT.war)
|
||
│ └── xiaoqu-intellectual-task/ # 定时任务服务（XXL-Job + MQTT）
|
||
```
|
||
|
||
## 常用开发命令
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd frontend/witcleansystem
|
||
npm install # 安装依赖
|
||
npm run dev # 启动开发服务 (端口 8079，代理 /api → 192.168.1.182:8095)
|
||
npm run build-test # 构建测试环境包
|
||
npm run build # 构建生产环境包
|
||
```
|
||
|
||
### 后端
|
||
|
||
```bash
|
||
# 先安装公共模块到本地 Maven 仓库
|
||
cd backend/xiaoqu-intellectual-public
|
||
mvn clean install
|
||
|
||
# 构建 Web 服务
|
||
cd backend/xiaoqu-intellectual-web
|
||
mvn clean package # 输出 ROOT.war
|
||
mvn spring-boot:run # 本地运行
|
||
|
||
# 构建 Task 服务
|
||
cd backend/xiaoqu-intellectual-task
|
||
mvn clean package
|
||
mvn spring-boot:run
|
||
|
||
# 运行单个测试
|
||
mvn test -pl xiaoqu-intellectual-web -Dtest=TestClassName
|
||
```
|
||
|
||
## 关键架构要点
|
||
|
||
- **API 端点集中管理**：所有 REST 端点在 `frontend/src/Apis/api.js` 中集中定义，`ApiService/` 下按业务域（如 `taskCenterService.js`、`basicInfoService.js`）封装具体调用逻辑。
|
||
- **动态权限体系**：页面字段（列）和按钮均由后端权限组动态控制，通过 Vuex Store 的 `fetchFields` / `fetchButtons` actions 加载，前端根据权限组配置动态渲染表格列和操作按钮。
|
||
- **全局公共组件**：`qu-table`、`qu-tree`、`qu-button-group`、`district-screen`、`qu-time-select` 已全局注册，直接在模板中使用。
|
||
- **请求签名机制**：`Utils/requestUtils.js` 中 axios 拦截器自动添加 UUID 签名头（`$common.getSignature()`），自动清除空值参数，并注入当前页面 `webId`。
|
||
- **登录态管理**：后端返回 code 104 自动跳转登录页，code 113 表示指纹无效需重新登录，登录信息存于 `sessionStorage`。
|
||
- **后端多模块依赖**：`public` 模块是基础依赖，`web` 和 `task` 模块均依赖 `public`，修改 `public` 后需先 `mvn install` 再构建上层模块。
|
||
- **WAR 部署**：web 模块打包为 WAR（warName=ROOT），排除了内嵌 Tomcat，部署到外部 Tomcat 容器。
|
||
|
||
## 环境配置
|
||
|
||
| 环境 | 前端 API 地址 | 对应 .env 文件 |
|
||
|------|--------------|---------------|
|
||
| 开发 | `http://192.168.1.182:8095`（通过 Vite proxy） | `.env.develop` |
|
||
| 测试 | `http://192.168.1.182:8095` | `.env.test` |
|
||
| 生产 | `https://b.ququsearch.com` | `.env.production` |
|