# xhsaas

**Repository Path**: petplanet/xhsaas

## Basic Information

- **Project Name**: xhsaas
- **Description**: spring boot   saas 框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xhsaas

## 项目介绍

xhsaas 是一个基于 Spring Cloud Alibaba 的多租户 SaaS 微服务框架，通过 Maven 多模块方式组织，支持通过 APPID 实现租户隔离，提供平台级后台管理、租户级后台管理和终端 API 三级服务体系。

### 核心特性

- **微服务架构**：基于 Spring Cloud Alibaba + Nacos 的分布式微服务架构，各服务可独立部署运行
- **多租户架构**：通过 APPID 标识实现租户数据隔离，支持多租户共存
- **平台 + 租户双权限体系**：平台和租户各自拥有独立的 RBAC 权限系统，均支持三级权限点（目录→菜单→按钮）和数据权限控制
- **三级 API 体系**：平台管理 API（xh-admin）、租户管理 API（xh-tenant）、终端用户 API（xh-api）
- **统一配置中心**：基于 Nacos 实现配置管理和服务注册发现，各服务独立配置、统一管理
- **灵活配置**：支持系统级、租户级个性化配置（LOGO、背景图、系统名称等）
- **套餐与模块管理**：支持功能模块化和套餐订阅模式，租户权限范围受套餐约束
- **OpenAPI 规范**：基于 OpenAPI 提供标准接口文档

---

## 系统架构

### 架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                              客户端                                  │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────────────────────┐   │
│  │  终端 APP │  │ 租户后台管理  │  │        平台后台管理           │   │
│  │ (uniapp) │  │ (art-design) │  │        (art-design)           │   │
│  └────┬─────┘  └──────┬───────┘  └──────────┬───────────────────┘   │
└───────┼────────────────┼──────────────────────┼──────────────────────┘
        │                │                      │
        ▼                ▼                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     Spring Cloud 微服务层                              │
│                                                                     │
│  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐  │
│  │    xh-admin       │  │   xh-tenant       │  │     xh-api       │  │
│  │  平台管理服务      │  │  租户管理服务      │  │  终端API服务     │  │
│  │  Port: 8081       │  │  Port: 8082       │  │  Port: 8083     │  │
│  │  ┌─────────────┐  │  │  ┌─────────────┐  │  │  ┌─────────────┐  │  │
│  │  │ 平台权限体系 │  │  │  │ 租户权限体系 │  │  │  │ 业务API     │  │  │
│  │  │ 租户/套餐/  │  │  │  │ 用户/角色/  │  │  │  │ （需APPID） │  │  │
│  │  │ 模块CRUD    │  │  │  │ 配置CRUD   │  │  │  │             │  │  │
│  │  └─────────────┘  │  │  └─────────────┘  │  │  └─────────────┘  │  │
│  └────────┬──────────┘  └────────┬──────────┘  └────────┬────────┘  │
│           │                      │                      │          │
│           └──────────────┬───────┴──────────────────────┘          │
│                          │  OpenFeign 服务间调用                     │
│           ┌──────────────┴──────────────┐                          │
│           ▼                              ▼                          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              基础模块（jar 依赖）                            │    │
│  │  ┌──────────────────────────┐  ┌────────────────────────┐  │    │
│  │  │        xh-common         │  │     xh-framework        │  │    │
│  │  │  通用工具/常量/DTO/      │  │  多租户拦截器/权限校验/  │  │    │
│  │  │  统一响应/异常处理       │  │  AOP注解/数据权限/      │  │    │
│  │  │                          │  │  基础Entity/配置        │  │    │
│  │  └──────────────────────────┘  └────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
        │                │                      │
        ▼                ▼                      ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          基础设施层                                  │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Nacos（注册中心 + 配置中心）                                  │    │
│  │  ├── 服务发现：xh-admin / xh-tenant / xh-api 自动注册         │    │
│  │  ├── 配置管理：各服务 bootstrap.yml / application.yml        │    │
│  │  └── 命名空间：dev / test / prod 隔离                        │    │
│  └─────────────────────────────────────────────────────────────┘    │
│  ┌──────────────────────────────────────────────────────────┐      │
│  │              MySQL（共享数据库 + 租户ID隔离）                │      │
│  └──────────────────────────────────────────────────────────┘      │
│  ┌──────────────────────────────────────────────────────────┐      │
│  │              Redis（会话存储 / 权限缓存 / 限流）             │      │
│  └──────────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────┘
```

### SaaS 模块总览

| 模块 | 类型 | 端口 | 职责说明 |
|------|------|------|----------|
| `xh-common` | jar（纯依赖） | — | 通用工具、常量、DTO、统一响应封装、异常处理、分页 |
| `xh-framework` | jar（纯依赖） | — | 多租户拦截器、权限校验 AOP、数据权限、操作日志、基础 Entity/Controller |
| `xh-admin` | 可运行服务 | 8081 | 平台管理：租户 CRUD、套餐管理、功能模块管理、平台权限体系、操作日志 |
| `xh-tenant` | 可运行服务 | 8082 | 租户管理：租户自身的用户/角色/权限/部门/配置管理，每个租客独立部署 |
| `xh-api` | 可运行服务 | 8083 | 终端 API：面向 App 端的业务接口，通过 OpenFeign 调用 admin/tenant 服务 |

**后续可扩展模块**（按需添加）：

| 模块 | 类型 | 建议端口 | 职责说明 |
|------|------|----------|----------|
| `xh-gateway` | 可运行服务 | 8080 | Spring Cloud Gateway 网关：统一入口、路由转发、限流、鉴权 |
| `xh-auth` | 可运行服务 | 8084 | 认证服务：登录、Token 签发与刷新、第三方登录 |
| `xh-order` | 可运行服务 | 8085 | 订单服务：订单创建、支付、退款 |
| `xh-message` | 可运行服务 | 8086 | 消息服务：站内信、短信、邮件通知 |

所有可运行模块均依赖 `xh-common` + `xh-framework`，通过 Nacos 注册发现实现服务间调用。

### 模块依赖关系

```
                    ┌─────────────┐
                    │  xh-common  │  (通用工具/常量/DTO/响应封装)
                    └──────┬──────┘
                           │ 依赖
                    ┌──────┴──────┐
                    │ xh-framework │  (多租户拦截器/权限/AOP/基础Entity)
                    └──────┬──────┘
                           │ 依赖
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │ xh-admin  │ │xh-tenant │ │  xh-api  │
       │(可运行)   │ │ (可运行)  │ │ (可运行) │
       │ Port:8081 │ │Port:8082 │ │Port:8083 │
       └──────────┘ └──────────┘ └──────────┘
```

> 后续可按需新增更多业务模块（如 `xh-order`、`xh-message` 等），均依赖 `xh-common` 和 `xh-framework`。

### 多租户隔离策略

本项目采用**共享数据库 + 租户ID字段隔离**的方式实现多租户：

- **隔离层级**：所有业务数据表包含 `app_id` 字段作为租户标识
- **拦截机制**：通过 MyBatis 拦截器或 AOP 切面，在查询时自动追加 `app_id` 条件
- **路由方式**：请求需携带 APPID（Header `X-App-Id` 或请求参数 `appid`），由拦截器解析并注入当前租户上下文

### 三级 API 体系

| API 层级 | 所属服务 | 路径前缀 | 认证方式 | 使用场景 |
|----------|----------|----------|----------|----------|
| 平台管理 API | `xh-admin` (8081) | `/api/v1/platform/` | 平台管理员 Token + 权限校验 | 管理所有租户、套餐、功能模块、平台用户 |
| 租户管理 API | `xh-tenant` (8082) | `/api/v1/tenant/` | 租户 Admin Token + APPID | 管理租户自身的用户、角色、权限、配置 |
| 终端用户 API | `xh-api` (8083) | `/api/v1/app/` | 用户 Token + APPID | 终端业务接口，需携带 APPID 参数 |

服务间调用通过 **OpenFeign** 实现，统一在 Nacos 注册中心完成服务发现。

---

## 功能模块需求

### 1. 平台后台管理（所属服务：`xh-admin`，端口 8081）

#### 1.1 系统配置

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 系统名称配置 | 设置平台全局显示名称 | `system_name`：系统展示名称（必填，max:50） |
| 登录背景图 | 配置登录页面背景图片 | `login_bg_image`：图片URL或上传文件路径 |
| LOGO 配置 | 配置平台 LOGO 图标 | `logo_image`：图片URL或上传文件路径 |
| 系统描述 | 平台简介信息 | `system_desc`：富文本描述（max:500） |
| 备案信息 | ICP备案号等 | `icp_number`：备案号（可选） |

#### 1.2 租户管理

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 租户列表 | 分页查询所有租户 | 支持按租户名称、状态、创建时间筛选 |
| 新增租户 | 创建新租户并生成 APPID | `tenant_name`、`contact_email`、`contact_phone`、`plan_id` |
| 租户详情 | 查看租户详细信息 | 关联套餐信息、到期时间、功能模块 |
| 租户启用/禁用 | 控制租户状态变更 | `status`：启用/禁用 |
| 租户删除 | 逻辑删除租户 | 需二次确认，记录操作日志 |
| 租户配额 | 管理用户数、存储空间上限 | `max_users`、`max_storage` |

#### 1.3 套餐管理

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 套餐列表 | 展示所有可用套餐 | 按套餐价格、功能模块排序 |
| 新增套餐 | 定义套餐及包含的功能模块 | `plan_name`、`price`、`duration_days`、`module_ids[]` |
| 套餐详情 | 查看套餐包含的功能模块 | 关联功能模块列表 |
| 套餐启停 | 上架/下架套餐 | `status`：上架/下架 |

#### 1.4 功能模块管理

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 模块列表 | 展示所有功能模块 | 支持按模块分类、状态筛选 |
| 新增模块 | 定义功能模块元信息 | `module_name`、`module_key`（唯一标识）、`category`、`icon`、`description` |
| 模块启停 | 启用/禁用功能模块 | `status`：启用/禁用 |
| 模块依赖 | 配置模块间依赖关系 | `depends_on[]`：依赖模块key列表 |

#### 1.5 平台权限体系

平台后台拥有独立的权限系统，用于控制平台运营人员对租户、套餐、功能模块等平台级资源的操作权限。与租户权限体系不同，平台权限**不受套餐约束**，直接对应平台管理功能。

##### 1.5.1 平台菜单与权限点

权限点三级结构：**目录（一级分组）→ 菜单（页面/功能）→ 按钮（操作权限）**。权限点与平台功能模块（1.1~1.4）一一对应，由系统初始化时预置。

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 权限树查询 | 查询完整平台权限树（三级递归） | 返回 `List<PlatformPermissionTreeVO>` |
| 权限点查看 | 查看权限点详情 | 显示 `name`、`code`、`type`、`category`、`status` |
| 权限点启停 | 启用/禁用权限点 | `status`：启用/禁用 |
| 权限排序调整 | 调整同级权限点排序 | `sort`：数值越小越靠前 |

**平台权限点映射表**（与 1.1~1.4 功能模块对应）：

| 目录 | 菜单 | 按钮 | code |
|------|------|------|------|
| 系统管理 | 系统配置 | — | `system:config` |
| | | 修改系统配置 | `system:config:update` |
| | | 上传登录背景图 | `system:config:upload-bg` |
| | | 上传 LOGO | `system:config:upload-logo` |
| 租户管理 | 租户列表 | — | `tenant:list` |
| | | 新增租户 | `tenant:create` |
| | | 查看租户详情 | `tenant:detail` |
| | | 修改租户 | `tenant:update` |
| | | 启用/禁用租户 | `tenant:toggle-status` |
| | | 删除租户 | `tenant:delete` |
| | | 管理租户配额 | `tenant:manage-quota` |
| 套餐管理 | 套餐列表 | — | `plan:list` |
| | | 新增套餐 | `plan:create` |
| | | 修改套餐 | `plan:update` |
| | | 删除套餐 | `plan:delete` |
| | | 套餐启停 | `plan:toggle-status` |
| 功能模块管理 | 模块列表 | — | `module:list` |
| | | 新增模块 | `module:create` |
| | | 修改模块 | `module:update` |
| | | 删除模块 | `module:delete` |
| | | 模块启停 | `module:toggle-status` |
| | | 配置模块依赖 | `module:depends` |
| 权限管理 | 权限点管理 | — | `platform:permission` |
| | | 角色管理 | — | `platform:role` |
| | | 操作日志 | — | `platform:log` |

##### 1.5.2 平台角色管理

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 角色列表 | 平台所有角色 | 支持按角色名、状态筛选 |
| 新增角色 | 创建自定义角色 | `role_name`、`role_code`、`description`、`data_scope`（可管理租户范围） |
| 角色详情 | 查看角色信息及已分配权限 | 关联权限树勾选状态 |
| 权限分配 | 为角色分配平台权限点 | 树形勾选，保存 `permission_ids[]` |
| 角色启停 | 启用/禁用角色 | `status`：启用/禁用 |
| 角色删除 | 删除自定义角色 | 仅允许删除自定义角色，预置角色不可删除 |
| 角色复制 | 复制已有角色及其权限 | 快速创建相似角色 |

**预置角色**（系统初始化时创建，不可删除）：

| 角色 | 说明 | 权限范围 |
|------|------|----------|
| 平台超级管理员 | 平台最高权限 | 所有平台权限点 + 全部租户数据权限 |
| 运营管理员 | 日常运营角色 | 租户管理、套餐管理、功能模块管理 |
| 财务专员 | 财务相关角色 | 套餐管理（只读+调整）、租户配额管理 |
| 审计员 | 只读审计角色 | 所有模块只读权限 + 操作日志查看 |

##### 1.5.3 平台数据权限

平台数据权限控制运营人员**能管理哪些租户**，而非部门维度。

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 数据权限范围 | 配置角色可管理的租户范围 | `data_scope`：枚举值（全部/自定义/仅本人创建） |
| 租户分组 | 按业务属性对租户分组 | `group_name`、`group_code`、租户关联 |
| 数据权限分配 | 为角色指定可管理的租户范围 | `tenant_ids[]`（当 `data_scope` 为自定义时） |

**数据权限范围枚举**：

| 枚举值 | 说明 | SQL 过滤逻辑 |
|--------|------|--------------|
| `ALL` | 全部租户 | 无额外过滤（仅限超级管理员） |
| `CUSTOM` | 自定义租户范围 | `id IN (角色配置的租户ID列表)` |
| `SELF` | 仅本人创建的租户 | `create_by = 当前用户ID` |

##### 1.5.4 平台权限体系 API 端点

平台权限相关 API 使用 `/api/v1/platform/` 前缀，需携带平台管理员 Token。

**权限点管理接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/platform/permission/tree` | 获取平台完整权限树（三级） |
| GET | `/api/v1/platform/permission/{id}` | 获取权限点详情 |
| PUT | `/api/v1/platform/permission/{id}/status` | 启停权限点 |
| PUT | `/api/v1/platform/permission/{id}/sort` | 调整权限点排序 |

**角色管理接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/platform/role/list` | 获取平台角色列表 |
| GET | `/api/v1/platform/role/{id}` | 获取角色详情及已分配权限 |
| POST | `/api/v1/platform/role` | 新增角色 |
| PUT | `/api/v1/platform/role/{id}` | 修改角色信息 |
| DELETE | `/api/v1/platform/role/{id}` | 删除角色（仅自定义角色） |
| POST | `/api/v1/platform/role/{id}/permissions` | 为角色分配权限点 |
| POST | `/api/v1/platform/role/{id}/copy` | 复制角色 |

**操作日志接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/platform/log/list` | 获取操作日志列表（支持按操作人、模块、时间筛选） |

### 2. 租户后台管理（所属服务：`xh-tenant`，端口 8082）

#### 2.1 租户系统配置（通过 APPID 区分）

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 租户名称 | 租户显示名称 | `tenant_name`（可修改） |
| 租户 LOGO | 租户独立 LOGO | `tenant_logo` |
| 登录背景图 | 租户独立登录背景图 | `tenant_login_bg` |
| 主题颜色 | 租户主题色配置 | `theme_color`（十六进制色值） |
| 功能开关 | 租户级功能启用/关闭 | JSON 配置，key 为 module_key，value 为开关状态 |

#### 2.2 用户管理（通过 APPID 区分）

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 用户列表 | 租户下所有用户 | 支持按用户名、手机号、状态筛选 |
| 新增用户 | 创建租户用户 | `username`、`password`、`phone`、`email`、`role_id` |
| 用户详情 | 查看用户信息及权限 | 关联角色、功能模块 |
| 用户启用/禁用 | 控制用户状态 | `status`：启用/禁用 |
| 用户角色分配 | 分配用户角色 | `role_ids[]`：支持多角色 |
| 密码重置 | 重置用户密码 | 管理员操作，记录日志 |

#### 2.3 租户权限体系

租户拥有**独立完整的权限系统**，通过 APPID 与其他租户完全隔离。权限采用 **RBAC 模型（角色-权限绑定）**，支持三级权限点结构（目录 → 菜单 → 按钮）和数据权限控制。

**核心约束**：租户可用的权限范围受限于其**套餐包含的功能模块**，平台未授权的模块对租户不可见、不可配置。

**权限点来源规则**：
- 权限点由**平台在功能模块中预先定义**（如用户管理模块包含"用户列表"、"新增用户"等权限点）
- 租户创建时，系统根据其购买的套餐**自动生成权限点副本**到租户权限体系
- 租户**不可新增或删除权限点**，只能对已有权限点进行**启停控制**和**角色绑定**

##### 2.3.0 权限初始化流程

新租户创建后，权限体系自动初始化：

```
创建租户 → 分配套餐 → 解析套餐包含的功能模块
                              │
                              ▼
              遍历每个模块，将其关联的权限点（目录→菜单→按钮）
              作为副本写入租户权限体系（带 tenant_id 隔离）
                              │
                              ▼
              自动创建预置角色：
              ├── 租户超级管理员（绑定所有启用的权限点）
              ├── 租户管理员（绑定管理类权限点）
              └── 普通用户（无权限点，需管理员分配）
                              │
                              ▼
              为租户创建初始管理员账号（绑定超级管理员角色）
```

##### 2.3.1 菜单与权限点管理

权限点以树形结构组织，共三级：**目录（一级分组）→ 菜单（页面/功能）→ 按钮（操作权限）**。

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 权限树查询 | 查询完整权限树（三级递归） | 返回 `List<PermissionTreeVO>`，包含 children 递归结构 |
| 权限点查看 | 查看权限点详情 | 显示 `name`、`code`、`type`、`module_key`、`status` |
| 权限点启停 | 启用/禁用权限点 | `status`：启用/禁用，禁用后前端不展示、后端接口拒绝 |
| 权限排序调整 | 调整同级权限点排序 | `sort`：数值越小越靠前 |

> **注意**：租户不可新增、删除、编辑权限点的核心属性（code、path、component 等），这些由平台功能模块定义。租户仅可控制 `status` 和 `sort`。

**权限点数据结构示例**：
```json
{
  "id": 1,
  "name": "用户管理",
  "code": "user",
  "type": "catalog",
  "icon": "User",
  "sort": 1,
  "module_key": "user_module",
  "children": [
    {
      "id": 2,
      "name": "用户列表",
      "code": "user:list",
      "type": "menu",
      "path": "/tenant/user/list",
      "component": "tenant/user/list",
      "sort": 1,
      "children": [
        {
          "id": 3,
          "name": "新增用户",
          "code": "user:create",
          "type": "button",
          "sort": 1
        },
        {
          "id": 4,
          "name": "删除用户",
          "code": "user:delete",
          "type": "button",
          "sort": 2
        }
      ]
    }
  ]
}
```

##### 2.3.2 角色管理

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 角色列表 | 租户下所有角色 | 支持按角色名、状态筛选 |
| 新增角色 | 创建自定义角色 | `role_name`、`role_code`、`description`、`data_scope`（数据权限范围） |
| 角色详情 | 查看角色信息及已分配权限 | 关联权限树勾选状态 |
| 权限分配 | 为角色分配三级权限点 | 树形勾选，保存 `permission_ids[]` |
| 角色启停 | 启用/禁用角色 | `status`：启用/禁用 |
| 角色删除 | 删除自定义角色 | 仅允许删除自定义角色，预置角色不可删除 |
| 角色复制 | 复制已有角色及其权限 | 快速创建相似角色 |

**预置角色**（系统自动生成，不可删除）：

| 角色 | 说明 | 权限范围 |
|------|------|----------|
| 租户超级管理员 | 租户最高权限 | 所有可用模块的全部权限点 + 全部数据权限 |
| 租户管理员 | 租户管理角色 | 管理用户、角色、配置等管理类权限 |
| 普通用户 | 基础用户角色 | 仅终端业务操作权限 |

##### 2.3.3 数据权限

数据权限控制用户能看到的数据范围，通过 `data_scope` 字段配置。

| 功能项 | 说明 | 字段级需求 |
|--------|------|------------|
| 数据权限范围 | 配置角色可访问的数据范围 | `data_scope`：枚举值（全部/自定义/本部门/本部门及以下/仅本人） |
| 部门管理 | 租户独立的组织架构 | `dept_name`、`parent_id`、`sort` |
| 数据权限分配 | 为角色指定可访问的部门 | `dept_ids[]`（当 `data_scope` 为自定义时） |

**数据权限范围枚举**：

| 枚举值 | 说明 | SQL 过滤逻辑 |
|--------|------|--------------|
| `ALL` | 全部数据权限 | 无额外过滤（仅限超级管理员） |
| `CUSTOM` | 自定义数据权限 | `dept_id IN (角色配置的部门列表)` |
| `DEPT` | 本部门数据权限 | `dept_id = 当前用户部门ID` |
| `DEPT_AND_BELOW` | 本部门及以下 | `dept_id IN (当前部门及所有子部门ID)` |
| `SELF` | 仅本人数据权限 | `create_by = 当前用户ID` |

##### 2.3.4 权限校验机制

```
请求 → Token 解析用户 → 获取用户角色 → 获取角色权限点集合 → 匹配请求路径 → 放行/拒绝
                                                                                  │
                                                                                  ▼
                                                                         数据权限过滤（MyBatis 拦截器自动追加数据范围条件）
```

- **前端**：根据用户权限点集合动态生成菜单树和按钮可见性
- **后端**：通过注解 `@RequiresPermission("user:create")` 声明接口所需权限，由 AOP 切面校验
- **缓存**：用户权限信息使用 Redis 缓存，登录时刷新，权限变更时主动清除

##### 2.3.5 权限体系 API 端点

租户权限相关 API 统一使用 `/api/v1/tenant/` 前缀，需携带 APPID 和租户管理员 Token。

**权限管理接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tenant/permission/tree` | 获取当前租户的完整权限树（三级） |
| GET | `/api/v1/tenant/permission/{id}` | 获取权限点详情 |
| PUT | `/api/v1/tenant/permission/{id}/status` | 启停权限点 |
| PUT | `/api/v1/tenant/permission/{id}/sort` | 调整权限点排序 |

**角色管理接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tenant/role/list` | 获取角色列表 |
| GET | `/api/v1/tenant/role/{id}` | 获取角色详情及已分配权限 |
| POST | `/api/v1/tenant/role` | 新增角色 |
| PUT | `/api/v1/tenant/role/{id}` | 修改角色信息 |
| DELETE | `/api/v1/tenant/role/{id}` | 删除角色（仅自定义角色） |
| POST | `/api/v1/tenant/role/{id}/permissions` | 为角色分配权限点（传 permission_ids[]） |
| POST | `/api/v1/tenant/role/{id}/copy` | 复制角色 |

**部门管理接口**：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tenant/dept/tree` | 获取部门树 |
| POST | `/api/v1/tenant/dept` | 新增部门 |
| PUT | `/api/v1/tenant/dept/{id}` | 修改部门 |
| DELETE | `/api/v1/tenant/dept/{id}` | 删除部门 |

### 3. 终端 API 接口（所属服务：`xh-api`，端口 8083）

终端 API 接口统一通过参数 `appid` 标识租户，请求需携带用户认证 Token。

#### 请求规范

```
GET  /api/v1/app/{module}/{action}?appid={APPID}
POST /api/v1/app/{module}/{action}?appid={APPID}

Headers:
  Authorization: Bearer {user_token}
  X-App-Id: {APPID}   // 也可通过 Header 传递 APPID
```

#### 响应规范

```json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "timestamp": 1699000000000
}
```

---

## 技术栈

### 后端技术栈

| 技术 | 版本 | 用途说明 |
|------|------|----------|
| Java | 17+ | 开发语言 |
| Spring Boot | 3.2.x | 应用基础框架 |
| Spring Cloud | 2023.0.x | 微服务框架 |
| Spring Cloud Alibaba | 2023.0.x | Nacos 适配、服务注册与发现 |
| Spring Web | 6.x | Web 服务、REST API |
| MyBatis Framework | 3.5.x | ORM 框架（支持拦截器实现租户隔离） |
| MySQL Driver | 8.0+ | 关系型数据库驱动 |
| Spring Data Redis | 3.2.x | 缓存、会话存储、分布式锁、接口限流 |
| OpenFeign | 4.x | 服务间 HTTP 调用 |
| Nacos | 2.3.x | 服务注册中心 + 配置中心 |
| Lombok | 1.18.x | 简化实体类代码 |
| OpenAPI / Swagger | 2.3.x | API 文档自动生成 |

### 前端技术栈

- **管理后台**：基于 [art-design-pro](https://github.com/Daymychen/art-design-pro) 框架
- **移动端 APP**：基于 uniapp 框架

---

## 项目结构规划

```
xhsaas/
├── pom.xml                              # 根 POM（packaging: pom，版本管理 + modules 聚合）
│   # modules: xh-common, xh-framework, xh-admin, xh-tenant, xh-api
│   # 统一管理 Spring Boot / Spring Cloud / MyBatis / Redis 等版本号
│
├── xh-common/                           # 通用模块（jar，纯依赖，无启动类）
│   ├── pom.xml
│   └── src/main/java/com/xh/common/
│       ├── result/                      # 统一响应封装（Result<T>）
│       ├── exception/                   # 通用异常定义
│       ├── constants/                   # 系统常量
│       ├── dto/                         # 通用DTO（分页、ID等）
│       ├── enums/                       # 通用枚举
│       ├── utils/                       # 工具类
│       └── page/                        # 分页封装
│
├── xh-framework/                        # 框架模块（jar，纯依赖，无启动类）
│   ├── pom.xml                          # parent: xhsaas, 依赖 xh-common
│   └── src/main/java/com/xh/framework/
│       ├── base/                        # BaseEntity / BaseController / BaseService
│       ├── tenant/                      # 多租户拦截器/上下文
│       │   ├── TenantContextHolder.java
│       │   └── TenantInterceptor.java
│       ├── permission/                  # 权限基础设施
│       │   ├── RequiresPermission.java  # 注解
│       │   └── PermissionAspect.java    # AOP 切面
│       ├── datascope/                   # 数据权限拦截器
│       │   └── DataPermissionInterceptor.java
│       ├── log/                         # 操作日志切面
│       │   └── OperationLogAspect.java
│       ├── config/                      # 通用自动配置
│       │   ├── MybatisPlusConfig.java
│       │   ├── RedisConfig.java
│       │   └── SwaggerConfig.java
│       └── filter/                      # 认证过滤器
│           └── AuthFilter.java
│
├── xh-admin/                            # 平台管理服务（可运行，Port: 8081）
│   ├── pom.xml                          # parent: xhsaas, 依赖 xh-framework
│   └── src/
│       ├── main/java/com/xh/admin/
│       │   ├── XhAdminApplication.java  # 启动类
│       │   ├── controller/
│       │   │   ├── PlatformPermissionController.java
│       │   │   ├── PlatformRoleController.java
│       │   │   ├── TenantController.java
│       │   │   ├── PlanController.java
│       │   │   ├── ModuleController.java
│       │   │   ├── SystemConfigController.java
│       │   │   └── OperationLogController.java
│       │   ├── service/
│       │   │   ├── PlatformPermissionService.java
│       │   │   ├── PlatformRoleService.java
│       │   │   └── OperationLogService.java
│       │   ├── mapper/
│       │   └── entity/                  # 平台级实体
│       │       ├── PlatformPermission.java
│       │       ├── PlatformRole.java
│       │       └── OperationLog.java
│       └── main/resources/
│           ├── bootstrap.yml           # Nacos 配置
│           ├── application.yml
│           ├── mapper/                  # MyBatis XML
│           └── schema.sql
│
├── xh-tenant/                           # 租户管理服务（可运行，Port: 8082）
│   ├── pom.xml                          # parent: xhsaas, 依赖 xh-framework
│   └── src/
│       ├── main/java/com/xh/tenant/
│       │   ├── XhTenantApplication.java # 启动类
│       │   ├── controller/
│       │   │   ├── PermissionController.java
│       │   │   ├── RoleController.java
│       │   │   ├── DeptController.java
│       │   │   ├── UserController.java
│       │   │   └── TenantConfigController.java
│       │   ├── service/
│       │   │   ├── PermissionService.java
│       │   │   ├── RoleService.java
│       │   │   ├── DataPermissionService.java
│       │   │   └── TenantInitService.java  # 租户初始化
│       │   ├── mapper/
│       │   └── entity/                  # 租户级实体（含 app_id 隔离）
│       │       ├── SysPermission.java
│       │       ├── SysRole.java
│       │       ├── SysRolePermission.java
│       │       ├── SysUserRole.java
│       │       ├── SysDept.java
│       │       ├── SysUser.java
│       │       └── TenantConfig.java
│       └── main/resources/
│           ├── bootstrap.yml
│           ├── application.yml
│           ├── mapper/
│           └── schema.sql
│
├── xh-api/                              # 终端API服务（可运行，Port: 8083）
│   ├── pom.xml                          # parent: xhsaas, 依赖 xh-framework
│   └── src/
│       ├── main/java/com/xh/api/
│       │   ├── XhApiApplication.java   # 启动类
│       │   ├── controller/
│       │   │   ├── AppUserController.java
│       │   │   └── BusinessController.java
│       │   ├── service/
│       │   └── client/                  # OpenFeign 调用其他服务
│       │       ├── TenantClient.java   # 调用 xh-tenant
│       │       └── AdminClient.java    # 调用 xh-admin
│       └── main/resources/
│           ├── bootstrap.yml
│           ├── application.yml
│           └── schema.sql
│
└── (后续可扩展模块)
    ├── xh-order/                        # 订单服务（可运行，Port: 8084）
    ├── xh-message/                      # 消息服务（可运行，Port: 8085）
    └── ...
```

### Nacos 配置管理

所有服务通过 Nacos 统一管理配置，配置文件加载顺序为：

```
bootstrap.yml（本地） → Nacos 远程配置 → application.yml（本地）
```

**Nacos 命名空间规划**：

| 命名空间 | 用途 | DataID 命名规则 |
|----------|------|----------------|
| `xhsaas-dev` | 开发环境 | `{service-name}.yml` |
| `xhsaas-test` | 测试环境 | `{service-name}.yml` |
| `xhsaas-prod` | 生产环境 | `{service-name}.yml` |

**各服务 bootstrap.yml 示例**：

```yaml
spring:
  application:
    name: xh-admin          # xh-tenant / xh-api
  cloud:
    nacos:
      server-addr: 127.0.0.1:8848
      discovery:
        namespace: xhsaas-dev
      config:
        namespace: xhsaas-dev
        file-extension: yaml
```

---

## 安装与部署

### 环境要求

| 环境 | 版本要求 | 说明 |
|------|----------|------|
| JDK | 17+ | 开发语言 |
| Maven | 3.8+ | 构建工具 |
| MySQL | 8.0+ | 数据库 |
| Redis | 6.0+ | 缓存 |
| Nacos | 2.3.x+ | 注册中心 + 配置中心 |

### 快速开始

1. **启动 Nacos**
   ```bash
   # 下载 Nacos Server
   wget https://github.com/alibaba/nacos/releases/download/2.3.0/nacos-server-2.3.0.tar.gz
   tar -xzf nacos-server-2.3.0.tar.gz
   cd nacos/bin
   # 单机模式启动
   startup.sh -m standalone
   # 访问 http://localhost:8848/nacos
   ```

2. **克隆并构建项目**
   ```bash
   git clone <repository-url>
   cd xhsaas
   mvn clean install -DskipTests
   ```

3. **初始化数据库**
   ```bash
   # 在 MySQL 中执行各服务的 schema.sql
   mysql -u root -p < xh-admin/src/main/resources/schema.sql
   mysql -u root -p < xh-tenant/src/main/resources/schema.sql
   ```

4. **在 Nacos 中创建配置**
   
   在 Nacos 控制台（`http://localhost:8848/nacos`）的 `xhsaas-dev` 命名空间中，创建以下 DataID：
   
   - `xh-admin.yml`：平台管理服务配置（含数据源、Redis 连接信息）
   - `xh-tenant.yml`：租户管理服务配置
   - `xh-api.yml`：终端 API 服务配置

   每个配置文件示例：
   ```yaml
   server:
     port: 8081             # 各服务使用不同端口
   spring:
     datasource:
       url: jdbc:mysql://localhost:3306/xhsaas?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
       username: root
       password: your_password
     data:
       redis:
         host: localhost
         port: 6379
   ```

5. **启动各微服务**
   ```bash
   # 分别在各服务目录下启动
   cd xh-admin && mvn spring-boot:run
   cd xh-tenant && mvn spring-boot:run
   cd xh-api && mvn spring-boot:run
   ```

6. **访问服务**
   - Nacos 控制台：`http://localhost:8848/nacos`
   - 平台管理 API：`http://localhost:8081/swagger-ui/index.html`
   - 租户管理 API：`http://localhost:8082/swagger-ui/index.html`
   - 终端 API：`http://localhost:8083/swagger-ui/index.html`

---

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

---

## 许可证

MIT License