# mate

**Repository Path**: tangsm-demo/mate

## Basic Information

- **Project Name**: mate
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mate-Modulith

以开源项目 **MateCloud**（Gitee `matevip/matecloud`）业务能力为蓝本、基于 **Spring Modulith** 重做的**模块化单体（Modular Monolith）后台管理基座**，含配套前端 `mate-ui`（Vue 3 + Element Plus）。

> 单体部署 + 模块化边界。每个业务模块同时是一个 Spring Modulith 应用模块，**模块边界即未来微服务的拆分线**——单体可直接演化为微服务，无需重写业务代码。

---

## 系统说明

**一句话定位**：对标 MateCloud 核心管理能力的 Spring Modulith 模块化单体基座——保留「一个可执行应用」的部署简单性，同时获得「可自动校验的模块边界」。

核心卖点：

- **可自动校验的模块边界**：`ApplicationModules.of(MateApplication.class).verify()` 在测试期强制校验依赖方向、封装与无环（`MateModulithTest`）；启动期亦可开启结构校验。
- **模块感知 Flyway**：各业务模块自带 `db/migration/<module>/` 迁移脚本，独立版本线、独立跟踪表（`flyway_schema_history_<module>`），启动自动执行。
- **多租户行级隔离**：`TenantLineInnerInterceptor` 自动注入 `tenant_id`，业务代码零侵入；预留 Schema / 独立数据源隔离 SPI。
- **事件注册表解耦**：Spring Modulith Event Publication Registry（JDBC 持久化），事务性业务事件（`@ApplicationModuleListener`）与旁路审计事件（`@Async @EventListener`）双模式。
- **模块内四层（DDD 血统打包结构）**：`trigger / application / domain / infrastructure`，跨模块只允许调用对方 `api/` 命名接口；领域层现状贫血、按需演进。
- **统一响应与错误码**：`Result<T>` / `PageResult<T>` / `BizException` + 分段错误码枚举，全局异常兜底。
- **审计旁路**：`@AuditLog` AOP 发布事件 → audit 模块异步落库，失败不影响主流程。

---

## 架构全景

采用 **Maven 模块 ↔ Modulith 应用模块「同一份边界，两种强制」的混合形态**：

- **Maven 模块**提供编译期物理边界（一个模块一个 jar，依赖配置独立）；
- **Spring Modulith 应用模块**提供运行期/测试期领域边界（所有业务模块包名为 `vip.mate.<module>`，作为 `vip.mate` 的直接子包被自动识别；`@ApplicationModule` + `@NamedInterface("api")` 声明约束）。

模块依赖图（实线 = 同步 API 依赖，虚线 = 领域事件）：

```mermaid
graph TD
    common["common（共享内核 · OPEN）"]
    identity["identity（认证）"]
    user["user（用户）"]
    rbac["rbac（授权）"]
    tenant["tenant（多租户）"]
    org["org（部门/岗位）"]
    dict["dict（字典/参数）"]
    audit["audit（审计）"]
    file["file（文件服务）"]
    notice["notice（通知）"]

    identity -->|"user :: api"| user
    identity -->|"rbac :: api"| rbac
    identity -->|"tenant :: api"| tenant
    user -->|"rbac :: api"| rbac

    identity --> common
    user --> common
    rbac --> common
    tenant --> common
    org --> common
    dict --> common
    audit --> common
    file --> common
    notice --> common

    identity -.->|UserLoggedInEvent| audit
    user -.->|UserChangedEvent| audit
    rbac -.->|PermissionChangedEvent| identity
    user -.->|UserDisabledEvent| identity
    tenant -.->|TenantCreatedEvent| rbac
```

更多设计细节：

- 架构设计文档：[docs/architecture.md](docs/architecture.md)
- 核心类图：[docs/class-diagram.mermaid](docs/class-diagram.mermaid)
- 关键时序图：[docs/sequence-diagram.mermaid](docs/sequence-diagram.mermaid)

---

## 快速开始

### 环境要求

| 组件 | 版本要求 |
| --- | --- |
| JDK | 25+ |
| Maven | 3.9+ |
| MySQL | 5.7+ / 8.0（设计基线 8.0，5.7 已实测可用） |
| Node.js | 18+（前端） |

### 1. 准备数据库

只需创建数据库（`utf8mb4`），**无需手动导任何 SQL**——Flyway 启动时自动按模块执行迁移建表：

```sql
CREATE DATABASE mate DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

### 2. 构建并启动后端

```bash
mvn clean install
cd mate-boot
mvn spring-boot:run
```

> ⚠️ 若本机 PATH 默认是 JDK 8，须先设置 `JAVA_HOME` 指向 JDK 25 并使用 Maven 3.9+，否则无法构建 Spring Boot 4 工程。

**端口说明**：`mate-boot/src/main/resources/application.yml` 中 `server.port` 默认为 **8080**；而 `mate-ui` 的开发代理默认指向 **http://localhost:18080**（见 `mate-ui/.env.development` 的 `VITE_API_TARGET`）。本机联调惯例以 **18080** 启动后端（本机 8080 常被其他 Java 进程占用）：

```bash
java -jar mate-boot/target/mate-boot-*.jar --server.port=18080
```

后端与前端代理目标**必须一致**：要么改后端端口为 18080，要么在 `.env.development` / 环境变量 `VITE_API_TARGET` 中将代理改指后端实际端口。

### 3. 启动前端

```bash
cd mate-ui
npm install
npm run dev
```

前端开发服务器运行在 `http://127.0.0.1:5173`，统一以 `/api` 前缀请求，由 Vite 代理转发（剥前缀）到后端。

### 4. 访问入口

| 入口 | 地址 |
| --- | --- |
| 前端管理后台 | http://127.0.0.1:5173 |
| 后端 Swagger UI | http://localhost:18080/swagger-ui.html（按后端实际端口） |
| OpenAPI JSON | http://localhost:18080/v3/api-docs |
| 健康检查 | http://localhost:18080/actuator/health |

### 5. 默认账号

```
admin / admin123
```

（由 `mate-module-user` 的 Flyway 种子脚本写入，BCrypt 加密。）

---

## 核心依赖

| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| JDK | 25 | Temurin HotSpot |
| Spring Boot | 4.1.1 | Spring Framework 7，Jackson 3（`tools.jackson`） |
| Spring Modulith | 2.1.1 | 模块边界校验 / 事件注册表 / 模块感知 Flyway |
| Sa-Token | 1.45.0 | `sa-token-spring-boot4-starter`，认证鉴权 |
| MyBatis-Plus | 3.5.17 | `mybatis-plus-spring-boot4-starter` + `mybatis-plus-jsqlparser` |
| Flyway | Boot 4 管理 | 模块感知迁移（`flyway-mysql` 12.4.0 实测） |
| 连接池 | HikariCP | Boot 默认 |
| 本地缓存 | Caffeine 3.x | 权限双层缓存（rbac / identity） |
| 接口文档 | springdoc-openapi 3.1.1 | Boot 4 系必须 v3 |
| Excel | EasyExcel 4.0.3 | `mate-starter-excel` |
| 对象存储 | MinIO SDK 8.5.17 | 文件服务 MINIO 模式 |
| 前端 | Vue 3.5 / Element Plus 2.9 / Vite 6 / TypeScript 5.8 / Pinia 2 / vue-router 4.5 | `mate-ui` |

> 版本唯一真源：`mate-dependencies/pom.xml`（独立 BOM）+ 根 `pom.xml`。Redis 本期未接入会话/缓存链路（Sa-Token Redis 依赖 Jackson 2，与 Boot 4 的 Jackson 3 冲突，详见 [docs/architecture.md](docs/architecture.md) §12），本机无 Redis 也可启动。

---

## 功能特性

以下均为**已实现**的能力（实现以代码为准；对照 [docs/matecloud-parity-check.md](docs/matecloud-parity-check.md) 已复刻清单及后续补齐项）：

| 能力域 | 功能 | 说明 |
| --- | --- | --- |
| 认证 | 密码 + 图片验证码登录 | `/auth/captcha`、`/auth/login` |
| 认证 | 短信验证码登录 | `/auth/sms/code`（60s 频控）+ `/auth/sms-login` |
| 认证 | 登出 / 会话信息 | `/auth/logout`、`/auth/me` |
| 个人中心 | 改密码 / 改资料 | `/auth/password`、`/auth/profile` |
| RBAC | 用户 / 角色 / 菜单管理 | 三级绑定（用户-角色-菜单），权限标识如 `system:user:add` |
| RBAC | 接口级鉴权 | `@SaCheckPermission` 注解，无权限 403 |
| 多租户 | 租户管理 + 行级隔离 | 租户 CRUD、`X-Tenant-Id` 解析、SQL 自动注入 `tenant_id` |
| 多租户 | 隔离策略 SPI | 默认 `ROW`；`SCHEMA` / `DATASOURCE` 为预留扩展点 |
| 组织 | 部门树 / 岗位 | `/dept`、`/post` |
| 配置 | 字典 / 系统参数 | `/dict`、`/config` |
| 审计 | 操作日志 / 登录日志 | `@AuditLog` 事件驱动异步落库；`/oper-log`、`/login-log` |
| 会话 | 在线用户 / 强制下线 | `/online` |
| 文件 | 上传 / 下载 | `/file`，LOCAL 本地磁盘 / MINIO 双实现 |
| Excel | 用户导出 / 导入 | `mate-starter-excel`（EasyExcel），`/user/export`、`/user/import` |
| 通知 | 通知渠道适配器 | `NoticeChannelSender` SPI + Mock 短信/邮件（落日志） |
| 开放 API | 接口签名 | `@ApiSign`（appId + timestamp + nonce + secret），`/open` |
| 数据权限 | `@DataPermission` 逐表数据权限 | 注解驱动（如 `@DataPermission(table="mate_user")`），`DataPermissionAspect`（starter-web）+ `MateDataPermissionHandler`（MybatisPlusConfig 注册） |
| 幂等防重 | `@Idempotent` 写接口防重 | Redis SETNX + 无 Redis 回退进程内，interval 可配（如 `@Idempotent(interval=5)`） |
| 架构 | 模块边界校验 | `MateModulithTest`（`verify()`）强制校验模块依赖 |
| 架构 | Flyway 模块级迁移 | 各模块独立迁移目录与版本线 |
| 前端 | 管理后台 | 登录 / 仪表盘 / 用户 / 角色 / 菜单 / 租户 / 字典 / 登录日志 / 在线用户，动态路由 + 按钮级守卫 + 租户切换 |

**预留 / 本期未实现**（不阻塞启动与使用）：

| 项 | 状态 |
| --- | --- |
| Redis L2 缓存 / Sa-Token Redis 会话 | 预留（Jackson 2/3 冲突，本期会话走内存 DAO，重启即下线） |
| Schema / 独立数据源租户隔离 | SPI 扩展点预留 |
| MQ / Seata / 网关 / Nacos / Dubbo | 单体形态不需要（见「与 MateCloud 的差异」） |

---

## 模块说明

```
mate/                                   # 根 POM（packaging=pom）：聚合 + pluginManagement
├── pom.xml
├── docs/                               # 设计文档（PRD / 架构 / 对齐核查 / Mermaid 图）
├── mate-dependencies/                  # 【BOM】统一依赖版本管理，独立 POM（不继承根 POM）
├── mate-common/                        # 【共享内核 · OPEN】Result/ErrorCode/BizException/
│                                       #   TenantContextHolder/PageQuery/事件契约/通用注解
├── mate-starters/                      # 【基础设施 starter 聚合】
│   ├── mate-starter-web/               #   Web 装配：统一响应、全局异常、Jackson3、OpenAPI、CORS、@ApiSign、@AuditLog 切面
│   ├── mate-starter-datasource/        #   数据源装配：MyBatis-Plus、租户插件、分页、审计填充、BaseEntity
│   ├── mate-starter-security/          #   安全装配：Sa-Token 拦截器、注解鉴权
│   ├── mate-starter-cache/             #   缓存装配：Caffeine 抽象
│   ├── mate-starter-excel/             #   Excel 装配：EasyExcel 导入导出
│   └── mate-starter-test/              #   测试支撑装配：MateIntegrationTest / ModulithGuardTest
├── mate-modules/                       # 【业务能力 = Modulith 应用模块聚合】
│   ├── mate-module-identity/           #   认证身份：登录/登出/验证码/短信登录/个人中心/在线用户
│                                       #     + StpInterface 实现 + 开放接口 /open（vip.mate.identity）
│   ├── mate-module-user/               #   用户管理：账户 CRUD、状态、Excel 导入导出（vip.mate.user）
│   ├── mate-module-rbac/               #   授权：角色/菜单/权限标识/权限解析与缓存（vip.mate.rbac）
│   ├── mate-module-tenant/             #   多租户：租户 CRUD + 上下文解析 + 行级隔离（vip.mate.tenant）
│   ├── mate-module-org/                #   组织：部门树/岗位（vip.mate.org）
│   ├── mate-module-dict/               #   配置：字典类型/字典数据/系统参数（vip.mate.dict）
│   ├── mate-module-audit/              #   审计：操作日志/登录日志，事件驱动异步落库（vip.mate.audit）
│   ├── mate-module-file/               #   文件服务：上传/下载，LOCAL/MINIO 双实现（vip.mate.file）
│   └── mate-module-notice/             #   通知：渠道发送 SPI + Mock 短信/邮件（vip.mate.notice）
├── mate-boot/                          # 【可执行启动模块】MateApplication + application.yml
│                                       #   + Flyway 全局基线 db/migration/__root（基路径仍为 classpath:db/migration）
│                                       #   + MateModulithTest
└── mate-ui/                            # 【前端】Vue 3.5 + Element Plus + Vite 6 + TS + Pinia（npm 管理）
```

---

## 配置说明

全部配置集中在 [`mate-boot/src/main/resources/application.yml`](mate-boot/src/main/resources/application.yml)，关键项摘要：

| 配置项 | 说明 |
| --- | --- |
| `server.port` | 后端端口，默认 `8080`（联调惯例 `--server.port=18080`，与前端代理对齐） |
| `spring.datasource.*` | MySQL 连接与 HikariCP 连接池 |
| `spring.data.redis.*` | Redis 连接（本期仅配置存在；Sa-Token 会话与 L2 缓存未接入 Redis） |
| `spring.flyway.locations` | **固定为基路径 `classpath:db/migration`**——Modulith 在此之上自动追加模块标识，错写子路径（如 `__root`）会静默不建表 |
| `spring.modulith.*` | 模块检测策略（`direct-sub-packages`）、模块感知 Flyway、启动期校验、事件注册表自动建表 |
| `spring.jackson.*` | Jackson 3 全局行为（日期格式 `yyyy-MM-dd HH:mm:ss`）；**不可写 `write-dates-as-timestamps`**（Jackson 3 已移除该键，绑定即启动失败） |
| `mybatis-plus.*` | 雪花主键、逻辑删除、驼峰映射 |
| `sa-token.*` | Token 名称/有效期/并发登录/风格等 |
| `mate.file.*` | 文件存储：`LOCAL`（默认，`base-dir`）/ `MINIO`（endpoint/ak/sk/bucket） |
| `mate.notice.*` | 通知渠道 provider（默认 `mock`，仅落日志） |
| `mate.tenant.isolation-mode` | 租户隔离模式，默认 `ROW` |
| `mate.api-sign.*` | 开放接口签名开关、时间窗、appId/secret 清单 |
| `management.endpoints` | Actuator 暴露 `health,info,prometheus` |

---

## 文档索引

| 文档 | 内容 |
| --- | --- |
| [docs/prd.md](docs/prd.md) | 产品需求文档：定位、FR 清单、非功能需求 |
| [docs/architecture.md](docs/architecture.md) | 架构设计：模块划分、依赖约束、包结构、数据结构、踩坑记录 |
| [docs/matecloud-parity-check.md](docs/matecloud-parity-check.md) | 与 MateCloud 的能力对齐核查：已复刻清单与未复刻项 |
| [docs/class-diagram.mermaid](docs/class-diagram.mermaid) | 核心类图 |
| [docs/sequence-diagram.mermaid](docs/sequence-diagram.mermaid) | 关键时序图 |

## Agent / 编码约定

AI Agent 与编码规范入口：

- **[AGENTS.md](AGENTS.md)** —— Agent 工作指南总入口（项目速览、命令、目录导航、硬性红线、验收口径），Agent 进入仓库首先阅读。
- **[.codebuddy/rules/](.codebuddy/rules/)** —— CodeBuddy 项目规则（`.codebuddy/rules/<规则名>/RULE.mdc`）：核心边界 Always 生效，其余按需自动加载（模块边界、后端编码、Flyway、安全租户、POM 依赖、前端 Vue）。

二者分工：`AGENTS.md` 管「怎么在这个仓库里干活」，`.codebuddy/rules/` 管「改到哪类文件必须遵守哪些硬约束」。

## 与 MateCloud 的差异

| 维度 | MateCloud v5.0.8 | 本项目 |
| --- | --- | --- |
| 架构形态 | 微服务 + 单体双形态 | 仅模块化单体（Modulith 边界即拆分线） |
| 注册/配置中心 | Nacos | 无（单体直连，配置走 application.yml） |
| 网关 | Spring Cloud Gateway | 无（单体不需要，拆微服务时引入） |
| 模块间通信 | Dubbo RPC + MQ | 公开 API（`::api` 命名接口）+ 领域事件（Event Publication Registry） |
| 事务性发件箱 | MQ 事务消息 | Modulith 事件注册表（JDBC 持久化） |
| 模块边界表达 | Maven 模块 + RPC 接口 | Maven 模块 + `@ApplicationModule` / `@NamedInterface`（可 `verify()` 自动校验） |
| 限流 / 灰度 / 分布式事务 / 分库分表 | Sentinel / Gray / Seata / ShardingSphere | 本期不做（单体形态，见 parity-check A 类取舍） |
| AI / MCP / 代码生成 | Spring AI 2 + mate-cli | P2 预留模块位 |

---

## 开源协议

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