# 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` |