# much-service

**Repository Path**: chenhang0612/much-service

## Basic Information

- **Project Name**: much-service
- **Description**: Much Service 是一个基于 Spring Cloud 微服务架构的企业级应用服务平台，提供了完整的用户认证、权限管理、系统管理和会员管理等核心功能。项目采用模块化设计，具有高可扩展性和可维护性。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Much Service（much-service）

基于 **Spring Boot 2.7** 与 **Spring Cloud 2021** 的多模块微服务项目，提供统一网关、认证、系统管理（RBAC）与会员/积分等业务能力。服务注册与配置默认对接 **Nacos**，数据层使用 **MySQL 8** + **MyBatis-Plus**，缓存与令牌相关能力使用 **Redis**。

---

## 目录

- [1. 仓库结构](#1-仓库结构)
- [2. 模块说明](#2-模块说明)
- [3. 技术栈与版本](#3-技术栈与版本)
- [4. 运行时拓扑](#4-运行时拓扑)
- [5. 网关与对外 URL](#5-网关与对外-url)
- [6. 各服务端口与配置要点](#6-各服务端口与配置要点)
- [7. 构建与质量检查](#7-构建与质量检查)
- [8. 本地启动建议顺序](#8-本地启动建议顺序)
- [9. 安全与权限](#9-安全与权限)
- [10. 公共能力（much-common）](#10-公共能力much-common)
- [11. 主要 HTTP 接口（经网关前缀）](#11-主要-http-接口经网关前缀)
- [12. 配置与环境](#12-配置与环境)
- [13. 已知配置注意点](#13-已知配置注意点)
- [14. 许可证](#14-许可证)
- [15. 项目文档](#15-项目文档)

---

## 1. 仓库结构

Maven 聚合工程，根 `pom.xml` 的 `<packaging>` 为 `pom`，子模块如下：

| 目录 | Maven `artifactId` | 说明 |
|------|-------------------|------|
| `much-common` | much-common | 公共组件：统一返回体、异常、AOP、MyBatis 插件、Redis、工具类等 |
| `much-gateway` | much-gateway | Spring Cloud Gateway，统一入口、鉴权与白名单等 |
| `much-auth` | much-auth | 认证服务：登录/登出/刷新令牌、SSO 等；通过 **OpenFeign** 调用系统服务 |
| `much-system-service` | much-system-service | 系统域：用户、角色、权限/菜单、部门、字典、登录/操作日志等 |
| `much-member-service` | much-member-service | 会员与会员积分（含 springdoc OpenAPI / Swagger UI） |

根工程版本：**1.0.0**（`groupId`: `com.much`）。

---

## 2. 模块说明

### 2.1 much-gateway

- **Spring Cloud Gateway**（模块内显式依赖 `spring-cloud-starter-gateway` **3.1.8**）。
- **Nacos**：服务发现 + Config。
- **Redis**：与 `AuthFilter` 中令牌校验等逻辑配合。
- **排除** `DataSourceAutoConfiguration`：网关进程不初始化 JDBC。
- 过滤器工厂类位于 `com.much.gateway.filter`：`AuthFilter`、`LoggingFilter`、`RateLimitFilter`、`WhitelistFilter` 等；另有 `RequestLogFilter` 实现，是否在路由中使用以实际 `application*.yml` / Nacos 配置为准。
- `com.much.gateway.config` 下为白名单等配置；`WhitelistController` 用于白名单调试/更新相关能力。

### 2.2 much-auth

- **Spring Web** + **Nacos** + **Redis** + **OpenFeign**。
- **排除数据源自动配置**（`DataSourceAutoConfiguration`）：主应用不将认证服务作为直连库写模型；用户校验、注册等通过 **Feign** 调用 `much-system-service` 暴露的接口（如 `UserFeignClient`）。
- **JWT**：`much-auth` 使用 **JJWT 0.11.5**（`jjwt-api` + `jjwt-impl` + `jjwt-jackson`）；网关仅依赖 Redis + AES 解密会话，**不**依赖 jjwt 组件。
- 入口类：`com.much.auth.MuchAuthApplication`。

### 2.3 much-system-service

- **Spring Web** + **Nacos** + **MyBatis-Plus** + **MySQL**（`mysql-connector-java` **8.0.33**）+ **Redis** + **OpenFeign**。
- `@MapperScan("com.much.system.mapper")`，实体包等见各 `application*.yml` 中 `mybatis-plus` 配置。
- 权限注解与切面：`PermissionAnnotation`、`PermissionAspect`；操作日志：`OperationLog`、`OperationLogAspect` 等。
- 包结构：`controller` → `service` → `service.impl` → `mapper`；Controller/Service 层方法均含 JavaDoc，详见 [15. 项目文档](#15-项目文档)。

### 2.4 much-member-service

- 与系统服务类似的技术栈，增加 **springdoc-openapi-ui**（OpenAPI 3，与 Spring Boot 2.7 适配的 1.7.x）。
- Controller 根路径为 **`/api/member`** 与 **`/api/member/point`**（经网关访问时需带上网关的 `/member` 前缀，见下文）。

### 2.5 much-common

- 被网关、认证、系统、会员等模块依赖；包含 **Web、AOP、Validation、OpenFeign、MyBatis-Plus、Redis、Actuator、Mail** 等依赖。
- 工具与第三方：**Jackson**（`spring-boot-starter-web` 自带）、**Hutool 5.8.20**、**Commons Lang3 3.12.0**、**Commons Collections4 4.4**、**jBCrypt 0.4**。
- MyBatis 插件注册见 `com.much.common.config.MyBatisConfig`（注册 `GlobalSqlInterceptor`、`SqlLogInterceptor` 等）。

---

## 3. 技术栈与版本

以下以各模块 `pom.xml` 及根 `pom.xml` 为准（若与历史文档不一致，以代码为准）。

| 类别 | 技术 | 版本/说明 |
|------|------|-----------|
| 语言 | Java | **1.8**（`java.version`） |
| 基础框架 | Spring Boot | **2.7.15**（父 POM） |
| 微服务 | Spring Cloud | **2021.0.8** |
| 阿里云生态 | Spring Cloud Alibaba | **2021.0.4.0**（BOM） |
| 注册/配置 | Nacos Discovery + Config | 随 Alibaba BOM |
| 网关 | Spring Cloud Gateway | **3.1.8**（`much-gateway` 显式版本） |
| 负载均衡 | Spring Cloud LoadBalancer | 随 Cloud BOM |
| RPC | Spring Cloud OpenFeign | 随 Cloud BOM |
| ORM | MyBatis-Plus | **3.5.3.1** |
| 数据库驱动 | MySQL Connector/J | **8.0.33**（系统/会员服务） |
| 缓存 | spring-boot-starter-data-redis | 根 POM 中 `redis.version` 为 **3.0.1**（覆盖父工程管理版本，以仓库配置为准） |
| JWT | JJWT | **0.11.5**（`jjwt-api` / `jjwt-impl` / `jjwt-jackson`，由父 POM `${jjwt.version}` 管理）；仅 **much-auth** 引用；`jwt.secret` 经 **SHA-256 派生**为 HMAC-SHA256 密钥以满足长度要求 |
| API 文档 | springdoc-openapi-ui | **1.7.0**（仅 `much-member-service`，OpenAPI 3） |
| 其他 | Lombok | **1.18.30** |

**JSQLParser**：`GlobalSqlInterceptor` 源码使用 `net.sf.jsqlparser` 包名，一般由 **MyBatis-Plus** 等传递依赖引入，根 POM 未单独声明 `jsqlparser` 版本。

---

## 4. 运行时拓扑

```mermaid
flowchart LR
  Client[客户端]
  GW[much-gateway]
  Auth[much-auth]
  Sys[much-system-service]
  Mem[much-member-service]
  Nacos[Nacos]
  Redis[(Redis)]
  DB[(MySQL)]

  Client --> GW
  GW --> Auth
  GW --> Sys
  GW --> Mem
  Auth -->|OpenFeign| Sys
  Auth --> Redis
  GW --> Redis
  Sys --> DB
  Sys --> Redis
  Mem --> DB
  Mem --> Redis
  Auth --> Nacos
  GW --> Nacos
  Sys --> Nacos
  Mem --> Nacos
```

---

## 5. 网关与对外 URL

### 5.1 路由意图（逻辑前缀）

| 网关路径前缀 | 下游服务（Nacos `spring.application.name`） | 典型用途 |
|-------------|-----------------------------------------------|----------|
| `/auth/**` | `auth` | 登录、SSO、令牌刷新等 |
| `/system/**` | `system` | 用户、角色、权限、部门、字典、日志等 |
| `/member/**` | `member` | 会员与积分 API |

### 5.2 路由约定（全环境一致）

所有网关路由（`application.yml`、`application-{test,uat,prod}.yml` 与 `nacos-configs/gatewayService.yml`）均采用同一套规则：

| 项 | 说明 |
|----|------|
| **路径** | `Path=/auth/**`、`/system/**`、`/member/**` |
| **过滤器顺序** | `AuthFilter` → **`StripPrefix=1`**（去掉首段 `/auth`、`/system`、`/member` 再转发；**不使用 RewritePath**，避免与自定义 `AuthFilter` 工厂混用两套语义） |
| **默认过滤器** | `default-filters` 含 **`LoggingFilter`** |
| **URI** | 本地默认 `application.yml` 使用 **`http://localhost:{8081,8082,8083}`**（不依赖注册中心）；`test` / `uat` / `prod` 与 Nacos 示例使用 **`lb://auth`、`lb://system`、`lb://member`**（须与下游 `spring.application.name` 一致） |

外部请求与下游 Controller 对应关系示例（网关端口 8080）：

| 客户端请求 | 转发到下游的路径 |
|-----------|-----------------|
| `POST /auth/user/login` | `POST .../user/login` |
| `POST /system/user/list` | `POST .../user/list` |
| `POST /member/api/member/page` | `POST .../api/member/page`（JSON Body：`MemberRequest`） |

### 5.3 Nacos 配置对齐

将 `nacos-configs/gatewayService.yml` 作为网关在 Nacos 中的路由模板时，应与上述 **filters / default-filters** 保持一致；仅 **`uri`**（及 `redis`、`jwt`、`gateway.whitelist` 等）按环境修改。若 Nacos 中历史配置缺少 `StripPrefix=1`，会出现把 `/auth/xxx` 原样转发到下游、与 Controller 路径不一致的问题。

### 5.4 白名单（鉴权放行路径）

根网关 `application.yml` 中 `gateway.whitelist.paths` 与 `AuthFilter` 默认规则一致：**使用客户端访问网关时的完整路径**（含 `/auth`、`/system`、`/member` 首段），例如 `/auth/user/login`、`/system/user/login`、`/member/swagger-ui/**` 等；`AuthFilter` 在 `StripPrefix` 之前执行，故白名单不可写下游去掉首段后的路径。**生产环境务必按业务收紧白名单。**

**说明**：`/api/whitelist/**` 为网关进程内置的运维接口，**不再**放入 `gateway.whitelist.paths`；由独立开关与口令保护（见下节）。

### 5.5 白名单管理接口（`/api/whitelist/**`）

| 配置项 | 说明 |
|--------|------|
| `gateway.whitelist-management.enabled` | 默认 **`false`**：所有 `/api/whitelist/**` 返回 **404**（隐藏能力面）。 |
| `gateway.whitelist-management.admin-token` | 仅当 `enabled=true` 时生效且**不能为空**；请求头须携带 **`X-Gateway-Admin-Token`**，值与之完全一致才进入 Controller。 |
| 环境变量 | 可用 **`GATEWAY_WHITELIST_ADMIN_TOKEN`** 注入 `admin-token`（见 `application.yml`）。 |

错误响应：`admin-token` 未配置时为 **503**；口令不匹配为 **403**（JSON）。

---

## 6. 各服务端口与配置要点

以下端口来自各模块默认 `application.yml`（可被 profile 或 Nacos 覆盖）。

| 服务 | 默认端口 | 说明 |
|------|----------|------|
| much-gateway | **8080** | 对外统一入口 |
| much-auth | **8081** | 无默认数据源；JWT 相关配置见 `jwt.*` |
| much-system-service | **8082** | 默认库 `much_system`；`tenant.id` 默认 **10001** |
| much-member-service | **8083** | 默认库 `much_system`；`tenant.id` 默认 **10001** |

**JWT 与会话**：`much-auth` 登录后生成 **32 位短 token**，Redis 键为 **`token:<token>`**，值为 **AES(JSON(UserVo))** Base64 密文（与 `jwt.aes-key` 一致）。客户端请求头使用 **`token`**（可带 `Bearer ` 前缀）。网关 `AuthFilter` 校验 Redis 并解密，将用户上下文写入 `X-User-*` 转发头；Redis **expire** 与 **`jwt.expire`（秒）** 对齐。兼容路径仍可使用传统 **JWT 字符串**（`generateToken` / `parseToken`）。`refreshToken` 依赖解密后的会话再换发新 token。

**监控**：各服务 `management.endpoints.web.exposure.include` 默认包含 `health,info,metrics`。

---

## 7. 构建与质量检查

```bash
mvn clean install
```

- **默认激活** Maven profile：`test`（`profile.active` 默认 `test`）。
- **Spring Boot 打包输出目录**：根 POM 将 `spring-boot-maven-plugin` 的 `outputDirectory` 设为 `${project.build.directory}/${profile.active}`（例如 `target/test`），便于按环境区分产物目录。
- **PMD**：绑定在 `verify` 阶段，`failOnError` 为 **true**；若规则违反会导致构建失败。
- **Checkstyle / SpotBugs**：插件存在且当前配置为 **skip**，不参与失败判定。

---

## 8. 本地启动建议顺序

1. 启动 **MySQL**、**Redis**、**Nacos**（若使用服务发现/远程配置）。
2. 启动 **much-system-service**（认证与其它服务依赖其用户等接口）。
3. 启动 **much-auth**、**much-member-service**（顺序一般可互换，视调用关系而定）。
4. 启动 **much-gateway**。

**数据库**：仓库内未附带 `.sql` 初始化脚本；需自行准备与 `spring.datasource.url` 一致的库表结构。

---

## 9. 安全与权限

- **网关**：`AuthFilter` 校验 Token，并结合 **Redis** 做会话/过期等处理（细节以源码为准）。当配置了 **`much.internal.trust-secret`**（建议与环境变量 `MUCH_INTERNAL_TRUST_SECRET` 一致）时，转发至 system / member / auth 的请求会携带请求头 **`X-Much-Internal-Token`**，供下游校验「是否经网关或受信任 Feign」。
- **系统 / 会员服务入站**：`much.internal.inbound-trust-enabled=true` 且 **`trust-secret` 非空** 时，`InboundGatewayTrustFilter` 要求上述内部头与密钥一致（`/actuator/**`、`/error` 除外）；本地默认 `inbound-trust-enabled: false` 不启用。生产建议与 **安全组 / 网络策略**（仅网关网段可访问 8082/8083）叠加使用。
- **认证服务 Feign**：`much-auth` 在调用 system 的 Feign 上自动附加同一 **`X-Much-Internal-Token`**（与 `much.internal.trust-secret` 一致），避免仅网关带密钥而登录 Feign 被拒。
- **用户上下文**：`UserContextInterceptor` 对 `X-User-Id` 等头做格式校验，非法头返回 **403**，避免空指针与简单伪造。
- **系统服务**：接口级权限通过 `@PermissionAnnotation` + `PermissionAspect` 实现 RBAC；部分接口使用 `@PreventDuplicateSubmit` 防重复提交。
- **密码**：公共模块含 **jBCrypt** 等工具类（具体策略以 `UserService` 等实现为准）。

---

## 10. 公共能力（much-common）

| 能力 | 说明 |
|------|------|
| 统一响应 | `Result`、`PageResult` 等 |
| 全局异常 | `GlobalExceptionHandler` 及自定义异常体系；可选邮件/短信等通知扩展（`exception` 相关包） |
| 用户上下文 | `UserContextHolder` 等 |
| 防重复提交 | `@PreventDuplicateSubmit` + AOP |
| **GlobalSqlInterceptor** | MyBatis 拦截器：对 **SELECT** 在 `WHERE` 中合并 `tenant_id = <有效租户>`，并在未显式包含 `is_deleted` 条件时合并 `is_deleted = 0`；无 `LIMIT` 时追加 **`LIMIT 4096`**；**UPDATE/DELETE** 在 `WHERE` 中合并租户条件。有效租户由 **`TenantResolutionHelper`** 按 `tenant.resolution` 解析（默认 **`context-first`**：优先 `UserContextHolder` / 网关头 `X-User-GTenant`，否则 `tenant.id`；**`config-only`** 等同旧行为仅用配置）。租户码仅允许 `[a-zA-Z0-9_.-]{1,64}`。解析失败时回退执行原始 SQL。 |
| **TenantResolutionHelper** | 与 **GlobalSqlInterceptor**、**MyBatisPlusMetaObjectHandler** 插入填充共用；`tenant.saas.strict-missing-tenant=true` 时，已登录用户无租户上下文则使用 `missing-tenant-sentinel` 拼条件，避免误用部署默认租户跨租访问。 |
| **SqlLogInterceptor** | SQL 与耗时等日志输出（见类上注释与实现） |
| **MyBatisPlusMetaObjectHandler** | 填充创建/修改时间、操作人、**租户 ID**（与 `TenantResolutionHelper` 一致）等（见源码注释） |

若表结构无 `tenant_id` / `is_deleted` 等列，拦截器可能导致 SQL 异常，需与表设计一致或调整拦截范围。

---

## 11. 主要 HTTP 接口（经网关前缀）

下列为**下游 Controller 路径**；经网关访问时，请在前面加上 **`/auth`**、**`/system`** 或 **`/member`**，并遵守 **5.2** 节的 `StripPrefix` 规则（以你实际启用的网关配置为准）。

### 11.1 认证服务（`much-auth`，根路径 `/user` 与 `/sso`）

| 方法 | 路径               | 说明 |
|------|------------------|------|
| POST | `/user/login`    | 登录（内部再 Feign 系统服务） |
| POST | `/user/register` | 注册 |
| POST | `/user/logout`   | 登出 |
| POST | `/user/refresh`  | 刷新令牌 |
| GET | `/user/user-info` | 当前用户信息 |
| POST | `/sso/login`     | SSO 登录 |
| GET | `/sso/getUserInfo` | SSO 当前用户信息 |
| POST | `/sso/logout` | SSO 登出 |
| POST | `/sso/validate` | SSO token 校验 |
| GET | `/sso/test` | SSO 连通性测试 |

**经网关示例**（对应根目录 `application.yml` + `StripPrefix=1`）：`POST http://localhost:8080/auth/user/login`。

### 11.2 系统服务（`much-system-service`）

Controller 前缀（下游路径，**驼峰**）：`/user`、`/role`、`/permission`、`/dept`、`/dict`、`/loginLog`、`/operationLog`。

**用户（`/user`）**：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/user/login` | 系统侧登录（Feign/白名单） |
| POST | `/user/register` | 创建用户（`user:create`）；需 `roleIdList`、`deptIdList` |
| POST | `/user/list` | 用户分页（`user:list`）；直接返回 `PageResult<userDto>` |
| GET | `/user/{userId}` | 按流通用户 ID 查询（`user:view`） |
| POST | `/user/changePassword` | Query：`userId`、`oldPassword`、`newPassword` |
| POST | `/user/resetPassword` | Query：`userId` |
| POST | `/user/update` | 更新用户及角色/部门关联（`user:update`） |
| POST | `/user/delete` | Query：`id`（表主键）；逻辑删除 `is_deleted=1` |

**角色（`/role`）**：`POST pageList`、`save`、`update`、`POST delete/{id}`、`saveRolePermission`。

**菜单/权限（`/permission`）**：`getPermissionTree`、`getUserPermissionList`、`create`、`update`、`POST delete/{id}`。

**部门（`/dept`）**：`pageList`、`tree`、`list`、`GET listByParent`、`GET {id}`、`create`、`update`（POST/PUT）、`POST delete/{id}`。

**字典（`/dict`）**：`/dict/type/*` 类型 CRUD；`/dict/data/*` 及兼容路径 `/dict/create|update|delete/{id}`；关联字段 `dictCode`。

**登录日志（`/loginLog`）**：`POST /loginLog/list` 分页；`POST /loginLog/insert` 写入（auth Feign 调用，无 `Result` 包装）。

**操作日志（`/operationLog`）**：`POST /operationLog/list` 分页。

**经网关示例**：`POST http://localhost:8080/system/user/list`、`POST http://localhost:8080/system/loginLog/list`。

**代码生成器（`/codegen`）**：`GET /codegen/databases` → `GET /codegen/tables` → `POST /codegen/preview` 或 `POST /codegen/generate`（`targetModule`: `system` | `member`，多表一键生成 Entity/Mapper/Service/Controller）。详见 [docs/API-Admin-Frontend.md](docs/API-Admin-Frontend.md) 第 8 节。

> 完整路径、权限码、请求字段与示例：**[docs/API-Admin-Frontend.md](docs/API-Admin-Frontend.md)**

### 11.3 会员服务（`much-member-service`）

| 前缀 | 说明 |
|------|------|
| `/api/member` | 会员分页、详情、创建/更新/删除（`member:create/update/delete`） |
| `/api/member/point` | 积分查询、`add`/`reduce`/`init`（`memberPoint:update/create`） |

**经网关示例**：`POST http://localhost:8080/member/api/member/page`；`POST http://localhost:8080/member/api/member/create`。

详见 **docs/API-Admin-Frontend.md** 第 **3.8** 节。

**OpenAPI / Swagger UI**：直连会员服务端口时在根路径访问 **`/swagger-ui.html`**；经网关时在 **`http://{网关}:{端口}/member/swagger-ui.html`**（由 `StripPrefix=1` 转发到下游 `/swagger-ui.html`）。OpenAPI JSON：`/member/v3/api-docs`（对应下游 `/v3/api-docs`）。上述路径已列入网关鉴权白名单示例，可按环境删减。

---

## 12. 配置与环境

### 12.1 Maven / Spring Profile

根 POM 定义 Maven profile：`test`（默认）、`uat`、`prod`，对应属性 `profile.active`。

### 12.2 Spring Cloud Nacos

各服务默认 `spring.cloud.nacos.discovery.server-addr: localhost:8848`，`namespace`、`group` 等随环境 YAML 变化（如 UAT/生产使用独立 `namespace`）。

### 12.3 租户与操作日志

系统与会员服务示例配置中包含：

- `tenant.id`：单租户部署默认租户，或 **SaaS** 下无用户上下文时的回退值。
- `tenant.resolution`：`context-first`（默认，用户上下文租户优先）或 `config-only`（始终 `tenant.id`）。
- `tenant.saas.strict-missing-tenant` / `tenant.saas.missing-tenant-sentinel`：多租户下已登录但缺少租户头时的隔离策略（见 **`TenantResolutionHelper`**）。
- `operation.log.*`：操作日志开关、存储方式（`console` / `database`）、排除路径等。

**SaaS 建议**：登录态用户须在 **`UserVo.tenantId`**（经网关 `X-User-GTenant`）带出租户；生产可开启 **`strict-missing-tenant`**，并保证 JWT/会话中写入租户与库中 `tenant_id` 一致。
---

## 13. 已知配置注意点

1. **网关路由**：仓库内已统一为 **`AuthFilter` + `StripPrefix=1`**；若线上 Nacos 仍为旧片段，请按 `nacos-configs/gatewayService.yml` 同步，避免路径错位。
2. **JWT 密钥**：`jwt.secret` 若短于 32 字节会经 SHA-256 派生后再用于 HS256；生产请使用**足够熵**的随机密钥。
3. **认证服务数据源**：`MuchAuthApplication` 排除了 JDBC 自动配置；`application-test.yml` 中的 `spring.datasource` 对主应用类而言通常不会生效，**勿依赖该文件为认证服务提供 ORM**。
4. **白名单运维接口**：`/api/whitelist/**` 默认 **404**；生产若开启 `gateway.whitelist-management.enabled`，须配置高强度 **admin-token**，并仅在受信网络或管理平面访问。
5. **入站网关信任**：生产在 **gateway、auth、system、member** 配置**相同**的 `much.internal.trust-secret`（如 `MUCH_INTERNAL_TRUST_SECRET`）；system / member 另设 `much.internal.inbound-trust-enabled: true` 后才会校验 `X-Much-Internal-Token`。启用后请勿直连业务端口调试，应走网关或临时关闭该校验。

---

## 14. 许可证

本项目使用 **Apache License 2.0**，全文见仓库根目录 [LICENSE](LICENSE)。

---

## 15. 项目文档

| 文档 | 说明 |
|------|------|
| [README.md](README.md) | 架构、网关、配置、接口索引（本文） |
| [docs/API-Admin-Frontend.md](docs/API-Admin-Frontend.md) | 管理端/前端对接：经网关的完整路径、权限码、请求体与示例 |
| [LICENSE](LICENSE) | Apache 2.0 |

**源码注释**：`much-system-service` 的 Controller、Service、ServiceImpl 及公共模块核心类已补充 **JavaDoc**（类与方法说明）；阅读接口行为时可与上述 API 文档对照。

**网关运维 API**（默认关闭，见 [5.5](#55-白名单管理接口-apiwhitelist)）：`GET/POST http://{gateway}:8080/api/whitelist/*`，需 `gateway.whitelist-management.enabled=true` 且请求头 `X-Gateway-Admin-Token`。

---

**文档生成说明**：本文档依据仓库内 `pom.xml`、`application*.yml` 与 Controller 源码整理（更新于 2026-05）。若变更路由或接口，请同步更新 **第 5、11 节** 与 **docs/API-Admin-Frontend.md**。