# xmeng

**Repository Path**: xm20/xmeng

## Basic Information

- **Project Name**: xmeng
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 如梦 · XMeng 企业级权限管理框架

如梦是一个面向 Java 企业应用的开源权限管理与企业级开发框架，目标是让企业项目开发如梦一样自由、丝滑、简单和快捷。

> **向猛而行，势如破竹；**
>
> **如梦而至，境若流云。**

## 当前版本

当前为 `0.1.0-SNAPSHOT`，已提供：

- Gradle 多模块后端工程；
- Spring Boot 3.3、Java 17；
- PostgreSQL 默认配置，Redis 会话存储；
- MyBatis-Plus-Join 持久层依赖；
- 登录、退出、Token 会话和当前用户接口；
- Token 会话按有效请求自动滑动续期，只有超过配置的空闲时间未操作才会失效；
- 统一附件表、实体注解业务归属以及 Local/MinIO 可切换存储策略；
- 参考 xm-boot 的个人中心，支持查看个人资料、修改显示名称和修改当前账号密码；
- 角色、菜单、组织、用户授权和组织数据权限；
- 登录日志、操作审计、字典、文件和站内消息；
- Quartz JDBC 集群定时任务，支持目录/任务树、Cron 可视化、集群并发控制、手动执行和执行日志；
- Ops 运维工具，支持服务器分组收藏、SSH 测试连接、浏览器交互终端、名称/说明固定字段与可扩展应用组件、多个 Git 仓库组件、用户名密码或 SSH 私钥认证、开发/测试/生产环境独立绑定组件与远程分支、Shell 高亮脚本编辑、按环境部署/回滚、发布说明审计和 Linux 基础资源监控；
- 禅道精简研发协作，支持卡片式项目、Git 仓库绑定与远程分支检测、任务、BUG、拖拽看板和数据权限一致的研发仪表盘；
- 统一响应、参数校验、异常处理和安全过滤器；
- 统一业务枚举注册中心，以及前端枚举选择、单选、标签和表格列组件；
- 雪花算法主键、Long 字符串传输，以及基于 `LocalDate`/`LocalDateTime` 的统一日期时间序列化；
- 统一审计字段自动记录创建人、更新人和数据所属组织；未显式指定组织时继承创建人的组织；
- Docker Compose、带完整中文注释的 PostgreSQL 初始化脚本；
- 参考 xm-boot 交互风格的 Vue 3 管理台，覆盖用户、角色、菜单、组织、字典、日志、文件和消息。
- 支持垂直、分栏、横向和混合布局；顶部菜单在可用区域居中展开，空间不足时自动收纳到“更多”。
- 导航菜单由 `/api/v1/users/me/menus` 动态构建，同级节点按菜单管理中的排序值展示；菜单管理支持拖曳调整同级顺序和父子层级，并通过 `/api/v1/menus/structure` 原子保存完整结构。
- 登录页不预填或展示默认账号密码，开发与部署环境的管理员凭据必须通过受控初始化流程配置。

## 快速启动

1. 启动基础设施：

```bash
docker compose up -d
```

2. 使用 Gradle Wrapper 启动后端：

```bash
./gradlew :xmeng-server:bootRun
```

Windows：

```powershell
.\gradlew.bat :xmeng-server:bootRun
```

3. 启动管理端：

```bash
cd xmeng-admin
pnpm install
pnpm dev
```

管理端默认地址为 `http://127.0.0.1:5173`，开发代理会将 `/api` 请求转发到后端 `8080` 端口。

管理端主题设置支持多组预设主题色和自定义主题色、纵向/分栏/横向/混合/通栏布局、浅色/深色/主题色导航，以及卡片/灵动/简约/圆角页签风格；用户选择会自动保存在当前浏览器中。页签栏按首次点击顺序记录已访问菜单，并按屏幕实际可用宽度自动淘汰最早的非活动页签，避免出现横向滚动条；支持点击任一页签返回对应菜单，以及关闭页签后跳转到相邻节点；右键页签可关闭当前、非当前、左边、右边或全部页签。

4. 初始化脚本不会创建固定密码的管理员账号。部署前请通过受控初始化流程创建管理员，并通过环境变量注入数据库、Redis 和初始管理员密码；不要把凭据写入仓库。

5. 登录接口：

```http
POST http://localhost:8080/api/v1/auth/login
Content-Type: application/json

{"username":"<your-admin-username>","password":"<your-admin-password>"}
```

将返回的 `accessToken` 放入请求头：

```http
Authorization: Bearer <accessToken>
```

Token 默认空闲超时时间为 2 小时。携带有效 Token 调用受保护 API 时，后端会原子刷新
Redis 会话 TTL，因此持续操作不会因首次登录时间过久而退出；只有连续 2 小时没有有效请求才会失效。
可通过 `XMENG_TOKEN_IDLE_TIMEOUT` 调整，例如 `30m`、`2h` 或 `1d`，配置值必须为正数。
续期使用 Lua 原子执行 `GET` 和 `PEXPIRE`，兼容不支持 `GETEX` 的旧版 Redis。
管理端未读消息等自动轮询会携带 `X-XMeng-Background-Request: true`，此类请求只认证、不续期，
避免页面长时间开着但无人操作时会话被后台任务永久维持。

当前用户接口：`GET /api/v1/users/me`。个人中心接口：`GET/PUT /api/v1/users/me/profile`、`PUT /api/v1/users/me/password`。健康检查：`GET /actuator/health`。

主要管理接口：

| 模块 | API |
|---|---|
| 用户/授权 | `/api/v1/users`、`/api/v1/users/{id}/password` |
| 角色 | `/api/v1/roles`、`/api/v1/roles/{id}/relations`、`/api/v1/roles/{id}/menus` |
| 菜单 | `/api/v1/menus`、`/api/v1/users/me/menus` |
| 组织 | `/api/v1/orgs` |
| 字典 | `/api/v1/dict-types`、`/api/v1/dict-data` |
| 日志 | `/api/v1/logs/login`、`/api/v1/logs/operation` |
| 文件 | `/api/v1/files` |
| 消息 | `/api/v1/messages`、`/api/v1/messages/unread-count`、`/api/v1/messages/read-all`（含查询、发送、已读和删除） |
| 定时任务 | `/api/v1/jobs`、`/api/v1/jobs/cron/preview`、`/api/v1/job-logs` |
| Ops 工具 | `/api/v1/ops/servers`、`/api/v1/ops/applications`、`/api/v1/ops/deployments`、`/api/v1/ops/servers/{id}/monitor` |
| 禅道精简 | `/api/v1/zentao/projects`、`/api/v1/zentao/tasks`、`/api/v1/zentao/bugs`、`/api/v1/zentao/kanban`、`/api/v1/zentao/dashboard` |
| 业务枚举 | `/api/v1/enums`、`/api/v1/enums/{type}` |

业务中取值集合稳定、可穷举的字段统一使用枚举，不再散落字符串或数字常量。新增和使用方式参见[枚举开发规范](docs/枚举开发规范.md)。

### 文件附件与 MinIO

文件内容通过 `StorageProvider` 策略保存，`StorageProviderRegistry` 按附件记录中的 `storage`
字段路由历史文件，当前新增文件则使用 `xmeng.storage.active` 指定的策略。统一附件表通过
`business_table + business_id + business_type` 关联业务记录及附件用途；先上传后保存业务的场景允许短暂为空，业务事务
成功后必须调用 `AttachmentService.bind` 完成绑定。

可关联附件的业务实体需要显式声明注解，表名不接受客户端输入：

```java
@AttachmentOwner(table = "biz_order", description = "业务订单", types = {
        @AttachmentOwner.Type(value = "contract", description = "合同附件"),
        @AttachmentOwner.Type(value = "invoice", description = "发票附件")
})
public class BizOrder extends BaseModel {
}
```

```text
attachmentService.upload(file, order, "contract");
// 或先上传暂存附件，再在业务保存后绑定：attachmentService.bind(attachmentId, order, "contract");
```

启用 MinIO 时配置以下环境变量；Access Key 和 Secret Key 没有生产默认值：

```powershell
$env:XMENG_STORAGE_ACTIVE = 'minio'
$env:XMENG_MINIO_ENABLED = 'true'
$env:XMENG_MINIO_ENDPOINT = 'http://127.0.0.1:9000'
$env:XMENG_MINIO_ACCESS_KEY = '<access-key>'
$env:XMENG_MINIO_SECRET_KEY = '<secret-key>'
$env:XMENG_MINIO_BUCKET = 'xmeng'
docker compose up -d
```

MinIO Console 默认映射到 `http://127.0.0.1:9001`。存储桶保持私有，文件下载统一经过
`GET /api/v1/files/{id}` 的权限校验。

管理端统一使用 `XmUpload` 组件：10MB 及以下文件直接上传，超过 10MB 后按 5MiB 分片，
最大支持 1GB，并显示总体上传进度。分片协议依次调用 `/api/v1/files/uploads`、
`/api/v1/files/uploads/{uploadId}/chunks/{index}` 和完成接口。个人中心头像支持 JPEG、PNG、GIF，
最大 10MB；后端会校验当前上传人、实体附件类型白名单并实际解码图片内容。

### 消息通道扩展

消息发送采用 Strategy + Router + Gateway SPI：

- 管理端顶部提供“我的站内信”铃铛入口，未读数量大于零时显示角标，点击后进入消息中心；
- 未读数量在登录后、窗口重新聚焦及每 60 秒自动刷新，消息已读或删除后同步更新；
- `MessageSenderRouter` 按 `MessageChannel` 自动选择唯一发送策略；
- `IN_APP`、`EMAIL`、`SMS`、`WEBHOOK` 分别对应独立 `MessageSender`；
- 邮件、短信和 Webhook 通过 `EmailMessageGateway`、`SmsMessageGateway`、`WebhookMessageGateway` 对接厂商；
- 未安装外部通道适配器时不会静默降级，消息记录状态为 `FAILED` 并保存不含敏感信息的失败摘要；
- 外部目标仅保存脱敏值，Webhook 只接收配置中心维护的端点编码，不允许直接提交 URL。

## 工程结构

```text
xmeng-api                 # 对外接口契约聚合工程
├─ xmeng-api-common       # 统一响应、分页等公共契约
├─ xmeng-api-system       # 用户目录等系统公开契约
├─ xmeng-api-message      # 消息发送公开契约
└─ xmeng-api-job          # 定时任务处理器扩展契约
xmeng-domain              # 领域模型聚合工程
├─ xmeng-domain-common    # 公共枚举等稳定领域类型
├─ xmeng-domain-system    # 用户、权限领域模型
└─ xmeng-domain-message   # 消息、通道和状态领域模型
xmeng-framework           # Web、安全、缓存、异常和通用配置
xmeng-module/xmeng-module-system
                           # 用户和系统核心模块
xmeng-module/xmeng-module-file
                           # 统一附件、业务归属与对象存储模块
xmeng-module/xmeng-module-message
                           # 消息查询、发送和已读状态模块
xmeng-module/xmeng-module-job
                           # Quartz 集群调度、任务树和执行日志模块
xmeng-module/xmeng-module-ops
                           # 服务器纳管、应用发布、回滚审计和资源监控模块
xmeng-module/xmeng-module-zentao-lite
                           # 项目、任务、BUG、看板和研发仪表盘模块
xmeng-server              # 可运行服务
xmeng-admin               # Vue 管理端
sql/postgresql             # PostgreSQL 初始化脚本
```

## 构建

```bash
./gradlew clean build
```

后端默认使用 PostgreSQL 16+。可通过 `XMENG_DB_URL`、`XMENG_DB_USERNAME`、`XMENG_DB_PASSWORD`、`XMENG_REDIS_HOST` 等环境变量覆盖配置。

## 数据传输约定

- 业务实体主键统一由 MyBatis-Plus 雪花算法生成；
- 后端所有 `Long/long` 字段在 JSON 中序列化为字符串，前端使用 `Identifier = string` 接收和传输，禁止转换为 JavaScript `number`；
- 逻辑删除字段使用 `bigint`：`0` 表示有效数据，删除时回填记录自身 ID；需要支持删除后重建的业务唯一键必须与 `deleted` 建立联合唯一索引；
- 纯日期默认格式为 `yyyy-MM-dd`；
- 日期时间默认按 `Asia/Shanghai` 时区输出，格式为 `yyyy-MM-dd HH:mm:ss`。

## 列表与分页查询约定

列表接口统一接收查询模型参数：`page`（页码，从 1 开始）、`limit`（每页条数，最大 500）、`order`（Java 属性名排序字段）和 `asc`（是否升序）。公共数据范围由 `QDataScope` 提供，通用关键字由 `KeywordQuery` 提供；角色、菜单、组织等资源分别使用独立的 `Q...` 模型扩展业务筛选字段并实现 `toWrapper()`。该继承结构、`toPage()` 和 Service 调用方式参照 xm-boot example。

Controller 只负责接收 Query、权限校验和调用 Service；查询条件、数据权限、排序、分页及响应转换统一在 Service 处理。

## 环境配置

配置按运行环境拆分：

- `application.yml`：公共配置，默认启用 `dev`；
- `application-dev.yml`：本地开发环境；
- `application-test.yml`：自动化测试环境，使用独立数据库、Redis DB 1 和文件目录；
- `application-prod.yml`：生产环境，敏感配置必须由环境变量注入。

指定环境：

```bash
./gradlew :xmeng-server:bootRun --args='--spring.profiles.active=test'
java -jar xmeng-server.jar --spring.profiles.active=prod
```

### 开发测试数据

`dev` 环境启动时会在基础结构初始化完成后幂等加载 `sql/postgresql/dev-data.sql`，其中包含集团总部、研发、销售、交付、财务等组织，以及相互关联的角色和虚构用户。测试账号统一使用密码 `RuMeng@2026`，仅用于本地开发和接口联调，禁止导入生产环境；生产部署前必须删除测试账号或强制重置密码。

详细需求见：[项目需求文档](docs/权限管理开源框架-项目需求文档.md)。

定时任务的并发语义、处理器扩展方式、数据库迁移和运维约束见：[定时任务模块设计](docs/定时任务模块设计.md)。
\n### 角色授权菜单选择

管理端角色授权中的菜单权限以目录、菜单、按钮的树结构展示，支持按层级勾选并保留菜单权限 ID 提交格式。

管理端登录后进入当前用户菜单中的第一个可访问页面，不再固定进入首页；直接访问未授权的菜单路由时，
前端路由守卫会回退到首个授权页面。没有任何导航菜单的账号仍可进入个人中心。
首页使用“看板”和“统计”两个子菜单，访问首页默认进入看板。两个页面共用独立的
`sys:dashboard:read` 权限，工作台统计统一由 `GET /api/v1/dashboard/statistics` 提供，
不要求账号额外拥有用户、角色、组织或菜单管理权限。页面设计和指标口径见
[首页看板与统计设计](docs/首页看板与统计设计.md)。
后台权限按照查询、新增、修改、删除、授权和业务执行动作分别编码；用户特权、角色授权及 AI
模块不再使用同时覆盖读写接口的复合权限。升级脚本会把历史复合权限等价迁移为细粒度权限，
管理员可在迁移后进一步收紧角色能力。

## AI 助手

独立的 `xmeng-module-ai` 提供模型配置、智能问答和 Markdown 智能文档。模型供应商统一采用
OpenAI-Compatible 协议，内置 OpenAI、DeepSeek、通义千问、Moonshot、智谱 AI 模板，也可填写
自定义兼容地址。供应商 API Key 使用 AES-GCM 加密入库，生产环境必须通过
`XMENG_AI_MASTER_KEY` 配置至少 24 个字符的独立主密钥。模型选择列表统一将 DeepSeek V4 Pro
置于首位并作为新会话的默认选择，其余模型按名称稳定排列。

智能问答保存当前用户的会话与最近消息记忆，可选择模型，并随消息附加不超过10MB的临时文件。
临时附件不会写入 `sys_attachment`、MinIO或本地对象存储；后端直接提取 Word、Excel、PDF、RTF、
Markdown、TXT 等常见文档文本，PNG、JPEG、BMP、GIF和TIFF图片通过Tesseract OCR提取文字，
仅将原文件名和提取文本保存到消息记录以支持后续会话记忆。OCR默认使用 `chi_sim+eng`，部署环境
需通过 `XMENG_TESSDATA_PATH` 提供包含对应语言包的tessdata目录。模型回答通过 NDJSON 实时流式输出，支持用户主动停止；
前端直接消费供应商Token增量，避免人为逐字延迟造成长回答背压。后端会校验供应商
`finish_reason` 与流结束标记并记录消息完整性；遇到长度截断、内容过滤或连接提前关闭时，
界面会标记“回答未完整结束”并允许基于会话记忆继续生成，残缺的文档修改不会写回正文。
Spring MVC 异步响应和上游模型读取默认允许持续 15 分钟，可通过 `XMENG_AI_STREAM_TIMEOUT`
调整；用户停止生成、关闭弹窗或客户端断开会按正常流取消处理，不记录为系统异常。
首轮回答完成后由当前模型自动生成会话标题，也允许用户手动重命名。会话支持置顶、取消置顶以及同组拖曳排序，
并可在确认后删除会话及其全部消息。消息区独立滚动并保证输入框固定在聊天面板底部，
聊天消息按安全 Markdown 渲染。
前端通过 `MarkdownRenderer` 组件统一封装Markdown解析、标题锚点和展示样式，支持标题、列表、
引用、代码块、链接、删除线、分隔线和GFM表格；原始HTML默认转义，`<!-- -->` 注释在预览中
隐藏，表格过宽时在内容区域内横向滚动。

智能文档左侧采用目录和文档两类节点组成的目录树，支持重命名、同级拖曳排序及跨目录拖曳挂靠。
上传入口支持一次选择多个文件，浏览器逐项上传并展示批次总体进度；单个文件失败不会中断批次中的
其余文件，完成后会汇总成功和失败数量。
文档通过文件模块的独立文档存储服务保存，不写入 `sys_attachment`；上传时同时保存原始文件和
UTF-8 文本镜像，并将提取文本写入 `ai_document.content` 以支持高效编辑与检索。当前支持 Word、
Excel、PDF、RTF、Markdown、TXT、CSV、JSON、XML、HTML、YAML、Properties 和 SQL 等格式。
智能文档单文件默认上限为 50MB，可通过 `XMENG_MAX_FILE_SIZE` 和 `XMENG_MAX_REQUEST_SIZE`
同步调整 Spring Multipart 限制。
在线编辑后会同步文本镜像，Markdown、TXT 等文本原生格式还会同步原文件；Word、Excel、PDF 等
二进制原件保持不变，避免文本回写破坏原格式。右侧通过受文档查看权限保护的原文件预览接口展示全文：
DOCX 按原页面尺寸、字体、表格和图片版式渲染，并从Word标题样式生成默认全部展开、可点击跳转的文档导航；旧版DOC
保留标题层级并提供默认全部展开的结构化文本导航；XLS/XLSX 按工作表分页签展示，保留合并单元格、列宽、行高、
格式化值及常用文字样式；PDF 通过浏览器原生引擎显示原文件，以兼容嵌入字体和中文CID字体，不生成文档导航，
也不执行OCR。没有文本层的PDF仍会保存原文件供在线预览，不再因提取文本为空导致上传失败。Markdown 正文通过统一安全组件渲染，
导入内容若使用覆盖整篇正文的 `markdown`/`md` 代码围栏会在预览时自动解除外层包装，并提供默认全部展开的标题导航；文档问答通过
登录后所有业务页面均显示的可拖曳全局悬浮按钮进入；按钮直接复用 XMeng 渐变 X 品牌图标，
通过品牌光环和 AI 徽标区分智能助手入口，位置保存在浏览器本地缓存。全局助手打开时默认进入
“智能文档”模块，可切换“智能问答”“智能写作”和“智能分析”，后三个入口当前统一展示待开发占位。
智能文档弹窗左侧统一管理文档会话，支持上下文记忆、
发送问题后会立即展示“思考中”动态状态，并在收到首段流式回答后自动替换为回答内容，
流式输出、主动停止、置顶、重命名和删除；新会话默认选择外部当前文档，也可在目录树中多选文档，
选择父目录时后端会递归纳入其全部下级文档。普通智能问答与文档问答使用独立会话范围，避免历史记录
相互混入。会话详情弹窗支持拖动标题栏改变位置，并可从右下角调整宽度和高度，消息区会随弹窗尺寸
自适应；会话列表与聊天区之间的分隔条支持左右拖动，并会保存会话列表宽度。调整后的位置、尺寸
和会话列表宽度保存在浏览器本地缓存，下次打开自动恢复；
浏览器窗口变小时会自动修正越界布局。AI 修改入口仅在“编辑文本”状态显示，固定于编辑器底部；
执行时显示不可交互的全局进度层，并按保存草稿、准备上下文、AI流式生成、完整性校验和准备审阅的
真实后端阶段更新说明；生成阶段同时展示已生成字符数。任务会先同步人工编辑草稿，再生成不直接写回的
AI候选正文。候选生成完成后打开类似IDE冲突解决器的全屏差异审阅界面，左右高亮修改前与AI候选内容，
支持逐块或全部保留原文、采用AI结果、变化导航以及手动编辑最终正文；只有用户确认后才同步数据库和
文件服务。流式任务会安全继承发起请求的登录用户上下文，并在任务结束后清理，确保异步线程中的文档
归属校验和审计字段正常生效。删除文档时会同步清理其专属会话和消息。