Files

xqzp2026 515f1bec5b 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

4.3 KiB

Raw Permalink Blame History

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）

常用开发命令

前端

cd frontend/witcleansystem
npm install                    # 安装依赖
npm run dev                    # 启动开发服务 (端口 8079，代理 /api → 192.168.1.182:8095)
npm run build-test             # 构建测试环境包
npm run build                  # 构建生产环境包

后端

# 先安装公共模块到本地 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`

4.3 KiB Raw Permalink Blame History Unescape Escape