# 晓雪企业快速开发平台（Java）

**Repository Path**: iteachyou/xiaoxue-feplatform

## Basic Information

- **Project Name**: 晓雪企业快速开发平台（Java）
- **Description**: 晓雪企业快速开发平台（Java）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaoxue-feplatform

晓雪前端平台后端服务：基于 Spring Boot 3 的多模块单体应用，提供系统管理、工作流（Flowable）、文件上传、定时任务（XXL-JOB）等能力，面向前后端分离场景。

## 技术栈

| 类别 | 技术 |
|------|------|
| 基础 | Java 17、Spring Boot 3.2.5、Maven 多模块 |
| 安全 | Spring Security、JWT（请求头 `XIAOXUE-TOKEN`） |
| 持久化 | MyBatis-Plus、MySQL 8、Druid |
| 缓存 | Redis（Lettuce） |
| 搜索 | Elasticsearch 8.10.x（默认关闭，客户端随 Spring Boot 3.2.5） |
| 工作流 | Flowable 7.1 |
| 任务调度 | XXL-JOB 3.x（默认可关闭执行器） |
| 文档 | SpringDoc OpenAPI / Swagger UI |
| 对象存储 | 本地 / 腾讯云 COS / 阿里云 OSS / 七牛云 / MinIO |

## 模块说明

```
xiaoxue-feplatform
├── xiaoxue-feplatform-dependencies   # 依赖版本 BOM
├── xiaoxue-feplatform-common         # 通用工具、统一响应、异常、注解等
├── xiaoxue-feplatform-model          # 实体、DTO、VO
├── xiaoxue-feplatform-elasticsearch  # Elasticsearch 客户端封装（按需依赖）
├── xiaoxue-feplatform-system         # 系统管理聚合
│   ├── xiaoxue-feplatform-system-core # 系统核心（Mapper / Service / Aspect）
│   └── xiaoxue-feplatform-system-pc   # 系统 PC 端接口（Controller）
├── xiaoxue-feplatform-workflow       # 工作流（Flowable）聚合
│   ├── xiaoxue-feplatform-workflow-core # 工作流核心（Mapper / Service）
│   └── xiaoxue-feplatform-workflow-pc   # 工作流 PC 端接口（Controller）
├── xiaoxue-feplatform-wms            # 仓储管理（WMS）聚合
│   ├── xiaoxue-feplatform-wms-core   # WMS 核心（Mapper / Service）
│   ├── xiaoxue-feplatform-wms-pc     # WMS PC 端接口（Controller）
│   └── xiaoxue-feplatform-wms-app    # WMS App 端接口（预留）
├── xiaoxue-feplatform-quality        # 质量管理聚合
│   ├── xiaoxue-feplatform-quality-core # 质量核心（Mapper / Service）
│   └── xiaoxue-feplatform-quality-pc   # 质量 PC 端接口（Controller）
├── xiaoxue-feplatform-quartz         # XXL-JOB 执行器与示例任务
├── xiaoxue-feplatform-pc             # PC 端启动入口、登录/验证码/个人中心/文件上传
├── xiaoxue-feplatform-app            # 手持端 App 启动入口
├── sql                               # 补充 SQL 脚本
└── docs                              # 文档
```

启动类：`cc.iteachyou.xiaoxue.Application`  
- PC：`xiaoxue-feplatform-pc`（依赖 `system-pc`、`workflow-pc`、`wms-pc`、`quality-pc`）  
- App：`xiaoxue-feplatform-app`（依赖 `system-core`、`workflow-core`、`wms-app`）

## 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8.x
- Redis 6+

可选：

- Elasticsearch 8.10.x（启用搜索时）
- XXL-JOB Admin（使用定时任务时）
- 云存储账号（非本地上传时）

## 快速开始

### 1. 准备数据库与 Redis

1. 创建数据库（默认名：`xiaoxue-platform`）。
2. 执行项目表结构及 [`sql/`](sql/) 下相关脚本。
3. 启动 Redis，并按配置修改密码、库号。

### 2. 修改配置

编辑 PC 配置 [`xiaoxue-feplatform-pc/src/main/resources/application.yml`](xiaoxue-feplatform-pc/src/main/resources/application.yml)，或 App 配置 [`xiaoxue-feplatform-app/src/main/resources/application.yml`](xiaoxue-feplatform-app/src/main/resources/application.yml)：

- `spring.datasource.*`：MySQL 连接
- `spring.data.redis.*`：Redis 连接
- `spring.elasticsearch.uris`：Elasticsearch 地址（默认 `http://127.0.0.1:9200`）
- `xiaoxue.elasticsearch.enabled`：未启动 ES 时请保持 `false`
- `xxl.job.executor.enabled`：未启动调度中心时请保持 `false`
- `flowable.*`：流程引擎表结构自动更新等

### 3. 编译与启动

```bash
# 在项目根目录
mvn clean package -DskipTests

# 运行 PC 端
mvn -pl xiaoxue-feplatform-pc -am spring-boot:run

# 运行手持端 App
mvn -pl xiaoxue-feplatform-app -am spring-boot:run
```

或运行打包后的 jar：

```bash
java -jar xiaoxue-feplatform-pc/target/xiaoxue-feplatform-pc-0.0.1-SNAPSHOT.jar
java -jar xiaoxue-feplatform-app/target/xiaoxue-feplatform-app-0.0.1-SNAPSHOT.jar
```

默认端口：PC `8080`，App `8081`。

### 4. 接口文档

启动后访问：

- Swagger UI：<http://127.0.0.1:8080/swagger-ui.html>
- OpenAPI JSON：<http://127.0.0.1:8080/v3/api-docs>

## 认证说明

1. 获取验证码：`GET /captcha/image`
2. 登录：`POST /u/loginByJson`
3. 后续请求在 Header 中携带：

```http
XIAOXUE-TOKEN: <登录返回的 JWT>
```

接口权限通过 `@PreAuthorize("@permission.hasPermission('模块:资源:动作')")` 控制；超级管理员拥有 `*:*:*`。

## 主要功能

### 系统管理（`/system/**`）

- 用户、角色、菜单、机构、岗位
- 字典、系统变量
- 登录日志、操作日志
- 上传存储配置（本地 / 多云，同时仅一条启用）

### 个人中心（`/personal/**`）

- `getInfo`：当前用户、角色、岗位、权限等
- `getRouters`：前端动态路由

### 文件上传（`/upload/**`）

- `POST /upload`：multipart 上传
- `POST /upload/base64`：Base64 上传
- 按 `system_upload_config` 当前启用配置选择存储方式
- 本地存储：按配置的 `domain` 路径映射 `uploadDir`，并跳过 Security；非当前前缀或不存在时返回 404

### 工作流（`/workflow/**`）

- 流程定义：创建（BPMN + 表单）、分页、详情、挂起/激活、删除、流程图
- 流程身份：处理人、候选用户、候选组（基于系统用户/角色）
- 创建时将表单写入 `system_form`（含 `procdef_id`、`category`）

### 定时任务

- 模块：`xiaoxue-feplatform-quartz`
- 默认关闭执行器注册，避免调度中心未启动时报错

### Elasticsearch

- 模块：`xiaoxue-feplatform-elasticsearch`（业务模块按需依赖）
- 客户端版本：随 Spring Boot 3.2.5 BOM，为 **8.10.4**；服务端建议安装 **8.10.x**
- 默认 `xiaoxue.elasticsearch.enabled=false`，关闭时排除 ES 自动配置，不影响本地启动
- 启用后注入 `cc.iteachyou.xiaoxue.elasticsearch.service.ElasticsearchService`（索引 CRUD、文档存取、简单 match 查询），或直接使用 `ElasticsearchClient`
- 连接配置：`spring.elasticsearch.uris`（及可选 `username` / `password`）

业务模块使用示例（以 WMS 为例，在对应 `pom.xml` 增加依赖）：

```xml
<dependency>
    <groupId>cc.iteachyou.xiaoxue</groupId>
    <artifactId>xiaoxue-feplatform-elasticsearch</artifactId>
</dependency>
```

## 统一响应

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

常见业务码见 `cc.iteachyou.xiaoxue.common.ResultCode`（如令牌缺失 `4006`、资源不存在 `404` 等）。

## 开发约定

- 包名根：`cc.iteachyou.xiaoxue`
- 控制器返回 `Result` / `PageResult`
- 业务异常使用 `BusinessException`
- Mapper 扫描：`cc.iteachyou.xiaoxue.**.mapper`
- 权限码格式：`模块:资源:动作`（如 `system:user:page`、`workflow:definition:create`）

## 目录速查

| 路径 | 说明 |
|------|------|
| `xiaoxue-feplatform-pc/src/main/resources/application.yml` | PC 主配置 |
| `xiaoxue-feplatform-app/src/main/resources/application.yml` | App 主配置 |
| `sql/` | 增量 / 初始化 SQL |
| `docs/` | 补充文档 |
| `logs/` | 运行日志（本地） |

## License

本项目基于 [MIT License](LICENSE) 开源。