figmar
204 lines
7.7 KiB
Markdown
204 lines
7.7 KiB
Markdown
# apes-Authon — 账权独立服务
|
||
|
||
> 从 saas-service（账权平台）提取的纯净认证/授权/用户/角色/权限/多租户体系
|
||
> 目标：作为独立微服务运行，为所有业务系统提供统一的账权能力
|
||
|
||
## 项目背景
|
||
|
||
本项目源自 `saas-service`（账权平台）单体应用，经过耦合度分析确认账权模块与业务模块零直接 Service 调用，具备独立服务化条件。本仓库是提取后的纯净账权代码，不包含任何业务逻辑（溯源、称重、水肥、巡检、维修、农大同步等）。
|
||
|
||
### 提取依据
|
||
|
||
- AuthContext 被 52 个文件 / 111 处引用，但业务 Service → 账权 Service 直接调用为 **0 个**
|
||
- 账权模块仅通过 ThreadLocal（AuthContext）与业务模块间接耦合
|
||
- 新增业务模块（如巡检、维修）均不直接调用账权 Service，验证了独立服务化的可行性
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Spring Boot | 2.2.1.RELEASE | Web 框架 |
|
||
| Java | 11 | 运行时 |
|
||
| MyBatis Plus | 3.5.7 | ORM |
|
||
| dynamic-datasource | 3.6.1 | 多租户数据源切换 |
|
||
| Redisson | 3.35.0 | Redis 客户端 / 分布式锁 |
|
||
| Hutool | 5.8.16 | 通用工具 |
|
||
| apes-commons | 0.0.7-SNAPSHOT | 认证核心（AuthContext / @Login / Res / DbEntity） |
|
||
|
||
## 代码结构
|
||
|
||
```
|
||
src/main/java/cn/apes/
|
||
├── AuthonApplication.java # 主启动类
|
||
└── cloud/
|
||
├── controller/ # 11 个 Controller
|
||
│ ├── UserController.java # 用户认证（登录/注册/改密/多企业切换）
|
||
│ ├── PermissionController.java # 权限管理（菜单/权限码/角色/成员角色）
|
||
│ ├── AccessTokenController.java # 外部 API Token 管理
|
||
│ ├── CustomerController.java # 客户/企业管理
|
||
│ ├── CustomerPackageController.java # 客户套餐管理
|
||
│ ├── AppController.java # 应用管理
|
||
│ ├── SysOrganizationController.java # 组织架构
|
||
│ ├── SysPackagePlanController.java # 套餐方案
|
||
│ ├── SysQuotaController.java # 配额模板
|
||
│ ├── SysOperationLogController.java # 操作日志
|
||
│ └── UserPreferenceController.java # 用户偏好
|
||
├── domain/
|
||
│ ├── entity/ # 23 个实体类
|
||
│ ├── dto/ # 12 个 DTO（含公共 PageDTO）
|
||
│ ├── vo/ # 3 个 VO
|
||
│ └── huoban/ # 11 个伙伴云 API 模型（SSO 依赖）
|
||
├── service/ # 6 个 Service 接口
|
||
│ └── impl/ # 16 个 Service 实现
|
||
├── mapper/ # 23 个 Mapper
|
||
├── config/ # 5 个配置类
|
||
│ ├── AccessTokenFilterConfig.java # Token 过滤器注册
|
||
│ ├── DataSourceHeaderAspect.java # 多租户数据源 AOP 切面
|
||
│ ├── TenantSource.java # @TenantSource 注解
|
||
│ ├── HbTokenContext.java # 伙伴云 Token ThreadLocal
|
||
│ └── SiteConfig.java # 站点配置
|
||
├── filter/
|
||
│ └── AccessTokenFilter.java # 外部 API 鉴权过滤器
|
||
└── util/
|
||
├── OperationLogUtil.java # 操作日志工具
|
||
└── RsaUtil.java # RSA 加解密工具
|
||
```
|
||
|
||
## 模块说明
|
||
|
||
### 1. 用户认证
|
||
|
||
- **密码登录**：`UserController.loginPwd()` → `UserInfoServiceImpl` → Redis 会话
|
||
- **多企业切换**：`UserController.selectCustomer()` → 切换 Redis 中的企业上下文
|
||
- **企业认证**：`UserController.certifyEnterprise()` → 提交企业资质
|
||
- **注册/改密**：`UserController.register()` / `UserController.updatePwd()`
|
||
|
||
### 2. RBAC 权限模型
|
||
|
||
```
|
||
AppInfo（应用）
|
||
└── SysMenu（菜单）── SysPermission（权限码）
|
||
└── SysRole（角色）── SysRolePermission（角色-权限关联）
|
||
└── SysMemberRole（成员-角色关联）
|
||
```
|
||
|
||
- 菜单树：`PermissionController.menuTree()`
|
||
- 权限码：`PermissionController.permissionCodes()`
|
||
- 角色管理：`PermissionController` 的 role CRUD
|
||
- 成员角色：`PermissionController` 的 member-role 分配
|
||
|
||
### 3. 多租户管理
|
||
|
||
- **数据源切换**：`@TenantSource` 注解 + `DataSourceHeaderAspect` AOP，从 `X-Tenant-ID` 请求头读取数据源标识
|
||
- **租户隔离**：业务数据通过 `AuthContext.getLoginInfo().getCustomer().getId()` 获取 customerId 过滤
|
||
|
||
### 4. 外部 API 鉴权
|
||
|
||
- `AccessTokenFilter`（order=1）拦截所有请求
|
||
- 校验 `X-Access-Token` / `Bearer` Token
|
||
- 校验通过后将用户/企业信息写入 Redis，使 `@Login` AOP 正常工作
|
||
|
||
### 5. SSO 单点登录
|
||
|
||
- 伙伴云 SSO V1：`SsoServiceImpl` → HMAC-SHA256 签名 → 伙伴云 `/sso/get_token`
|
||
- 伙伴云 SSO V2：`Sso2ServiceImpl` → 同上，不同 baseUrl
|
||
|
||
### 6. 套餐与配额
|
||
|
||
```
|
||
SysPackagePlan（套餐方案）── SysPackagePlanPermission（套餐-权限）
|
||
└── SysPackagePlanQuota（套餐-配额）
|
||
CustomerPackage（客户套餐）── CustomerPackageQuota（客户配额）
|
||
└── CustomerPackageExtendApply（延期申请）
|
||
SysQuota（配额模板）
|
||
```
|
||
|
||
## 外部依赖
|
||
|
||
### apes-commons JAR
|
||
|
||
本服务依赖 `cn.apes:apes-commons:0.0.7-SNAPSHOT`，提供以下核心类：
|
||
|
||
| 类 | 说明 |
|
||
|----|------|
|
||
| `AuthContext` | ThreadLocal 认证上下文，存储 UserSession |
|
||
| `UserSession` | 会话对象（LoginUser + LoginCustomer） |
|
||
| `LoginUser` | 登录用户信息 |
|
||
| `LoginCustomer` | 登录客户/企业信息 |
|
||
| `@Login` | 方法级注解，AOP 自动注入登录信息 |
|
||
| `Res` | 统一 API 响应包装 |
|
||
| `DbEntity` | 基础实体（id / createTime / updateTime / isDel） |
|
||
|
||
**安装方式**：将 `apes-commons-0.0.7-SNAPSHOT.jar` 安装到本地 Maven 仓库：
|
||
|
||
```bash
|
||
mvn install:install-file \
|
||
-Dfile=apes-commons-0.0.7-SNAPSHOT.jar \
|
||
-DgroupId=cn.apes \
|
||
-DartifactId=apes-commons \
|
||
-Dversion=0.0.7-SNAPSHOT \
|
||
-Dpackaging=jar
|
||
```
|
||
|
||
## 启动方式
|
||
|
||
```bash
|
||
# 1. 安装 apes-commons JAR
|
||
mvn install:install-file -Dfile=apes-commons-0.0.7-SNAPSHOT.jar ...
|
||
|
||
# 2. 编译打包
|
||
mvn clean package -DskipTests
|
||
|
||
# 3. 运行
|
||
java -jar target/apes-authon.jar
|
||
```
|
||
|
||
服务默认端口 `8090`，context-path `/authon`。
|
||
|
||
## 待完成事项
|
||
|
||
### Phase 1: 验证编译（当前）
|
||
- [ ] 安装 apes-commons JAR 后验证编译通过
|
||
- [ ] 补充缺失的 MyBatis XML（如有）
|
||
- [ ] 编写基础单元测试
|
||
|
||
### Phase 2: 包名重构
|
||
- [ ] `cn.apes.cloud` → `cn.apes.authon` 全局包名重构
|
||
- [ ] 调整 MapperScan 路径
|
||
- [ ] 更新所有 import
|
||
|
||
### Phase 3: SDK 化
|
||
- [ ] 将 `AuthContext` 改造为可远程调用的 SDK
|
||
- [ ] 提供 `authon-sdk` 模块供业务系统引用
|
||
- [ ] Token 校验改为 HTTP API 调用
|
||
|
||
### Phase 4: 网关集成
|
||
- [ ] 接入 API 网关（Spring Cloud Gateway / Nginx）
|
||
- [ ] 请求头注入认证信息（替代 ThreadLocal）
|
||
- [ ] 多租户数据源改为网关路由模式
|
||
|
||
## 从原项目提取的文件清单
|
||
|
||
共提取 **114 个 Java 文件**：
|
||
|
||
| 类型 | 数量 |
|
||
|------|------|
|
||
| Controller | 11 |
|
||
| Entity | 23 |
|
||
| DTO | 12 |
|
||
| VO | 3 |
|
||
| Service 接口 | 6 |
|
||
| Service 实现 | 16 |
|
||
| Mapper | 23 |
|
||
| Config | 5 |
|
||
| Filter | 1 |
|
||
| Util | 2 |
|
||
| Huoban DTO | 11 |
|
||
| 主启动类 | 1 |
|
||
|
||
## 关联仓库
|
||
|
||
- 源仓库：[apes-Authdata](https://gitea.apescale.com/figmar/apes-Authdata) — 完整单体应用（含业务代码）
|
||
- 方案文档：`docs/账权模块独立服务化方案.html`（在 apes-Authdata 仓库中）
|
||
- 源码对比：`docs/源码版本对比分析-20260809.md`（在 apes-Authdata 仓库中）
|