# sem

**Repository Path**: AndyWang66/sem

## Basic Information

- **Project Name**: sem
- **Description**: 智慧后端项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SEM — 智慧梯管管理系统

> Smart Elevator Management System  
> 基于 Spring Boot 的多模块电梯物联网管理平台

---

## 项目简介

智慧梯管管理系统（SEM）是一套面向电梯行业的综合管理平台，涵盖电梯台账管理、维保计划与任务、合同管理、配件仓库、报价订单、摄像头视频监控、企业微信集成、物联网数据采集（MQTT/EMQX）等核心业务功能。

- **项目版本**: 1.0.0
- **项目地址**: http://www.sem.vip

---

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| **基础框架** | Spring Boot | **2.5.15** |
| **编程语言** | Java / JDK | **1.8** |
| **构建工具** | Maven（多模块） | 3.x |
| **ORM 框架** | MyBatis-Plus | 3.4.2 |
| **分页插件** | PageHelper | 1.4.6 |
| **动态数据源** | dynamic-datasource (baomidou) | 3.5.2 |
| **数据库连接池** | Druid (Alibaba) | 1.2.16 |
| **关系数据库** | MySQL | 5.7+ |
| **缓存** | Redis (Lettuce 客户端 + commons-pool2) | — |
| **认证鉴权** | Spring Security + JWT | jjwt 0.9.1 |
| **密码加密** | BCryptPasswordEncoder | — |
| **权限校验** | Apache Shiro (辅助) | 1.7.1 |
| **API 文档** | SpringDoc OpenAPI (Swagger 3) | 1.7.0 |
| **定时任务** | Quartz Scheduler | — |
| **JSON 解析** | Fastjson2 (Alibaba) | 2.0.41 |
| **Excel 处理** | Apache POI | 4.1.2 |
| **PDF 导出** | iTextPDF + iText-Asian | 5.5.10 / 5.2.0 |
| **代码生成** | Apache Velocity | 2.3 |
| **工具库** | Hutool / Guava / Commons IO / Commons Lang3 | — |
| **系统监控** | OSHI | 6.4.6 |
| **验证码** | Kaptcha | 2.3.3 |
| **IoT 通信** | Eclipse Paho MQTT v5 | 1.2.5 |
| **流媒体** | ZLMediaKit | — |
| **企业微信** | qywx-spring-boot-starter | 4.3.0 |
| **Lombok** | Project Lombok | 1.18.26 |

### 核心依赖坐标速查

```xml
<!-- Spring Boot -->
<spring-boot.version>2.5.15</spring-boot.version>
<java.version>1.8</java.version>

<!-- 数据库与 ORM -->
<mybatis-plus-boot-starter.version>3.4.2</mybatis-plus-boot-starter.version>
<druid.version>1.2.16</druid.version>
<pagehelper.version>1.4.6</pagehelper.version>
<dynamic-datasource.version>3.5.2</dynamic-datasource.version>

<!-- 认证 -->
<jwt.version>0.9.1</jwt.version>
<shiro.version>1.7.1</shiro.version>

<!-- IoT -->
<mqttx.version>1.2.5</mqttx.version>
```

---

## 数据库配置

### 数据库类型

| 服务 | 地址 | 说明 |
|------|------|------|
| **MySQL** | `jdbc:mysql://localhost:3306/sem` | 主库，数据库名 `sem` |
| **Redis** | `localhost:6379` | 缓存 / Token 存储 / Session |
| **EMQX (MQTT)** | `tcp://transmit.zhitilvke.com:1883` | IoT 设备消息代理 |

### CDBC 连接参数

```
useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull
&useSSL=true&serverTimezone=Asia/Shanghai&allowMultiQueries=true
&noTimezoneConversionForDateType=true
```

### 读写分离（主从）

支持主从数据源（基于 `dynamic-datasource`），默认**从库关闭**：

```yaml
spring:
  datasource:
    druid:
      master:        # 主库（必配）
        url: ...
      slave:
        enabled: false  # 从库默认关闭
```

### 连接池参数（Druid）

| 参数 | 开发环境 | 生产环境 |
|------|----------|----------|
| initialSize | 5 | 10 |
| minIdle | 10 | 10 |
| maxActive | 20 | 50 |
| maxWait | 60s | 60s |

### Druid 监控

- **监控页面**: `/druid/*`
- **控制台用户名**: `sem`
- **生产环境**: 默认关闭 `webStatFilter` 和 `statViewServlet`（安全考虑）

---

## 整体架构

### 多模块结构

```
sem-master/
├── sem-admin/          # 🚀 Web 入口模块（Spring Boot 主启动类）
│   ├── web/controller/  # REST 控制器
│   │   ├── common/      # 公共接口（验证码、通用）
│   │   ├── ladderinfo/  # 业务接口（电梯、合同、维保、报价等）
│   │   ├── monitor/     # 监控接口（缓存、服务器、操作日志等）
│   │   ├── system/      # 系统接口（用户、角色、菜单、部门等）
│   │   └── tool/        # 工具接口
│   └── resources/       # 配置文件与 MyBatis XML
│
├── sem-framework/      # 🔧 核心框架模块
│   ├── config/          # Spring 配置（Security、Druid、Redis、线程池等）
│   ├── security/        # 安全认证（JWT Filter、认证处理等）
│   ├── aspectj/         # AOP 切面（日志、数据权限、数据源切换）
│   ├── interceptor/     # 拦截器（重复提交、数据源切换）
│   ├── web/service/     # 通用服务（权限、密码、注册）
│   └── manager/         # 管理器（异步任务、Shiro 会话）
│
├── sem-system/         # 🏗️ 系统模块（用户/角色/菜单/部门/字典/岗位）
│
├── sem-common/         # 📦 通用工具模块
│   ├── annotation/      # 自定义注解（@Log, @DataScope, @Anonymous 等）
│   ├── constant/        # 常量定义
│   ├── core/            # 核心类（BaseController, AjaxResult, RedisCache 等）
│   ├── enums/           # 枚举
│   ├── exception/       # 异常处理
│   ├── filter/          # 过滤器（XSS）
│   └── utils/           # 工具类
│
├── sem-quartz/         # ⏰ 定时任务模块（Quartz）
│
├── sem-generator/      # 🔨 代码生成模块（Velocity 模板）
│
├── sem-ladderInfo/     # 🏢 电梯业务模块（核心业务逻辑）
│   ├── config/          # EMQX/MQTT 客户端
│   ├── handle/          # 消息处理
│   ├── service/         # 业务服务
│   └── domain/          # 业务实体
│
└── sem-extension/      # 🧩 扩展模块（维修工单、报价审批等）
```

### 模块依赖拓扑

```
sem-admin（入口）
 ├─ sem-framework ────── Shiro 辅助鉴权
 │  ├─ sem-system ────── sem-common
 │  └─ sem-ladderInfo ── sem-common + sem-system
 ├─ sem-quartz ───────── sem-common + sem-ladderInfo
 ├─ sem-generator ────── sem-common
 ├─ sem-ladderInfo ──── 直接引用
 └─ sem-extension ────── sem-common + sem-framework
```

### 请求处理流程

```
客户端请求
  → CorsFilter（跨域）
  → JwtAuthenticationTokenFilter（Token 验证 + SecurityContext 设置）
  → UsernamePasswordAuthenticationFilter（Spring Security 认证链）
  → Controller（@Anonymous 可跳过认证）
  → AOP: LogAspect / DataScopeAspect / RepeatSubmitInterceptor
  → Service → Mapper → Database
  → AjaxResult / TableDataInfo 统一返回
```

### 认证体系

- **认证框架**: Spring Security（主）+ Apache Shiro（辅）
- **会话策略**: 无状态（`SessionCreationPolicy.STATELESS`）
- **Token 机制**: JWT（jjwt 0.9.1），Header: `Authorization`
- **密码加密**: BCryptPasswordEncoder
- **匿名访问**: `@Anonymous` 注解标记，配置文件中通过 `PermitAllUrlProperties` 管理

---

## 多环境配置

| Profile | 配置文件 | 激活方式 |
|---------|----------|----------|
| `dev`（默认） | `application-dev.yml` | `-P dev` 或默认 |
| `docker`（测试） | `application-docker.yml` | `-P test` |
| `docker-prod`（生产） | `application-docker-prod.yml` | `-P prod` |

环境变量占位符 `@profilesActive@` 在 Maven 打包时由对应 profile 注入。

---

## 打包与运行

### 1. 环境要求

| 组件 | 要求 |
|------|------|
| JDK | **1.8** 或以上 |
| Maven | **3.x** 或以上 |
| MySQL | **5.7+**（需先创建数据库 `sem` 并导入 SQL） |
| Redis | **5.0+** |
| EMQX | 可选（IoT 设备通信，如不需要可禁用） |
| ZLMediaKit | 可选（摄像头/视频监控，如不需要可禁用） |

### 2. 打包命令

```bash
# 开发环境打包（默认）
mvn clean package

# 测试环境打包（Docker 部署）
mvn clean package -P test

# 生产环境打包（Docker 部署，推荐）
mvn clean package -P prod

# 跳过测试打包
mvn clean package -P prod -DskipTests
```

**打包产物**: `sem-admin/target/sem-admin.jar`

### 3. 运行方式

#### 方式一：直接运行 JAR

```bash
java -jar sem-admin/target/sem-admin.jar

# 指定环境
java -jar sem-admin/target/sem-admin.jar --spring.profiles.active=dev

# 自定义端口
java -jar sem-admin/target/sem-admin.jar --server.port=9090
```

#### 方式二：Docker 部署（推荐生产环境）

使用 `application-docker-prod.yml`，通过环境变量传入敏感配置：

```bash
docker run -d \
  --name sem-app \
  -p 8080:8080 \
  -e MYSQL_URL="jdbc:mysql://mysql-host:3306/sem?..." \
  -e MYSQL_USER="sem_user" \
  -e MYSQL_PASSWORD="your_password" \
  -e REDIS_HOST="redis-host" \
  -e REDIS_PORT="6379" \
  -e REDIS_PASSWORD="your_redis_password" \
  -e TOKEN_SECRET="your-256-bit-secret" \
  -e WEIXIN_CP_CORPID="your-corp-id" \
  -e WEIXIN_CP_AGENTID="your-agent-id" \
  -e WEIXIN_CP_CORPSECRET="your-secret" \
  -e MINI_APPID="your-mini-appid" \
  -e MINI_APPSECRET="your-mini-appsecret" \
  -e SEM_H5_URL="https://your-h5-domain.com" \
  -e SEM_URL_ZHITILVKE="https://your-api-domain.com" \
  -v /data/sem/uploadPath:/app/uploadPath \
  -v /data/sem/logs:/app/logs \
  your-registry/sem-admin:1.0.0
```

### 4. 打包注意事项

> ⚠️ **以下事项在打包运行前请务必关注：**

1. **JDK 版本**: 项目必须使用 **JDK 1.8** 编译和运行。更高版本可能遇到兼容性问题（如 `javax.xml.bind` 在 JDK 11+ 中被移除）。

2. **数据库初始化**: 首次运行前必须先在 MySQL 中创建库 `sem` 并执行初始化 SQL 脚本（建表 + 基础数据）。

3. **Redis 必须可用**: 系统使用 Redis 存储 Token、缓存和会话信息，Redis 不可用将导致认证失败。

4. **文件上传路径**: 
   - 开发环境: `D:/sem/uploadPath`（Windows）或 `/sem/uploadPath`（Linux）
   - Docker 生产环境: `/app/uploadPath`
   - **必须确保路径存在且有写入权限**。

5. **Token 密钥**: 生产环境必须修改 `token.secret`，默认值 `abcdefghijklmnopqrstuvwxyz` **绝对不能用于生产**。

6. **企业微信配置**: 如使用企业微信审批功能，需正确配置 `corp-id`、`agent-id`、`secret`，生产环境通过环境变量传入。

7. **EMQX / MQTT**: 物联网功能依赖 EMQX Broker。如果不需要 IoT 功能，需确认 MQTT 连接失败不会阻塞应用启动。

8. **ZLMediaKit**: 视频监控功能依赖 ZLMediaKit 流媒体服务。如果不需要摄像头功能，确保相关接口做空值防护。

9. **生产环境安全**:
   - Druid 监控页面默认关闭（`docker-prod`），如需开启应加 IP 白名单
   - Spring Boot Actuator 端点生产环境仅暴露 `health, info`
   - Swagger/OpenAPI 建议在生产环境关闭（`swagger.enabled: false`）

10. **端口**: 开发环境默认端口 **8084**，Docker 环境默认 **8080**。部署时注意防火墙策略。

11. **日志路径**: Docker 环境下日志写入 `/app/logs`，需挂载卷或确保容器内有写入权限。

12. **Excel 模板文件**: 资源目录中的 `.xlsx` 文件不会被 Maven resource filtering 处理（防止二进制损坏），确保这些文件存在于打包后的 classpath 中。

---

## 内置功能模块

| 模块 | 说明 |
|------|------|
| 用户管理 | 系统用户 CRUD、角色分配、密码重置 |
| 角色管理 | 角色 CRUD、菜单权限、数据权限分配 |
| 菜单管理 | 动态菜单树、按钮权限 |
| 部门管理 | 组织架构树 |
| 字典管理 | 数据字典维护 |
| 岗位管理 | 岗位维护 |
| 参数配置 | 系统参数键值对 |
| 通知公告 | 系统通知发布 |
| 操作日志 | 操作日志记录与查询 |
| 登录日志 | 登录日志记录与查询 |
| 在线用户 | 在线用户踢出 |
| 定时任务 | Quartz 定时任务管理（在线增删改、立即执行、暂停/恢复） |
| 代码生成 | 数据库表 → 前端/后端 CRUD 代码一键生成 |
| 数据监控 | Druid SQL 监控面板 |
| 服务监控 | 服务器 CPU/内存/磁盘/JVM 监控 |
| 缓存监控 | Redis 缓存查看与清理 |
| 电梯台账 | 电梯设备 CRUD、年检记录 |
| 维保计划 | 维保计划编制与执行跟踪 |
| 维保任务 | 维保工单流转 |
| 维保模式 | 维保项模板配置 |
| 合同管理 | 合同、费用、维保梯关联 |
| 配件仓库 | 配件库存与出入库 |
| 报价订单 | 报价单生成、PDF 导出、企业微信审批 |
| 摄像头管理 | 电梯摄像头绑定与 ZLMediaKit 视频推流 |
| 物联网接入 | MQTT 协议设备数据采集与指令下发 |
| 企业微信 | 企业微信 OAuth 登录、消息推送、审批回调 |
| 小程序 | 微信小程序登录授权 |
| 维修工单 | 故障报修、维修派工、完工确认（扩展模块） |

---

## 常用启动参数

```bash
# 开发环境热部署启动（已配置 spring-boot-devtools）
java -jar sem-admin.jar --spring.profiles.active=dev

# 跳过企业微信/MQTT 等外部依赖（开发调试用）
java -jar sem-admin.jar \
  --emqx.broker= \
  --zlm.mediaKit-Url= \
  --spring.profiles.active=dev

# JVM 调优
java -Xms512m -Xmx1024m -XX:+UseG1GC -jar sem-admin.jar
```

---

## 项目结构速查

```
src/main/resources/
├── application.yml              # 主配置（公共 + Profile 切换）
├── application-dev.yml          # 开发环境（本地 MySQL/Redis）
├── application-docker.yml       # 测试环境（Docker，环境变量注入）
├── application-docker-prod.yml  # 生产环境（Docker，安全加固）
├── mybatis/
│   └── mybatis-config.xml       # MyBatis 全局配置
├── i18n/
│   └── messages.properties      # 国际化资源
└── META-INF/
    └── spring-devtools.properties
```

---

## 相关链接

- **Spring Boot 2.5.x**: https://docs.spring.io/spring-boot/docs/2.5.x/reference/html/
- **MyBatis-Plus**: https://baomidou.com/
- **Druid**: https://github.com/alibaba/druid
- **EMQX**: https://www.emqx.io/
- **ZLMediaKit**: https://github.com/ZLMediaKit/ZLMediaKit

---

> 📄 *本文档由项目分析自动生成，请根据实际部署情况补充 SQL 初始化步骤、Dockerfile 构建、CI/CD 流程等运维信息。*