Initial commit: SmartClean SaaS platform

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 15:53:34 +09:30
commit 515f1bec5b
1023 changed files with 123798 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,90 @@
+# 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` |