# 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 | 通用工具 |
| Lombok | 1.18.40 | 代码简化 |

## 代码结构

```
src/main/java/cn/apes/
├── AuthonApplication.java              # 主启动类
├── commons/                            # apes-commons 内联实现（原外部 JAR）
│   ├── Res.java                           # 统一 API 响应封装
│   ├── auth/
│   │   ├── AuthContext.java               # ThreadLocal 认证上下文
│   │   ├── Login.java                     # @Login 注解
│   │   ├── LoginAspect.java              # 登录认证 AOP 切面
│   │   ├── LoginUser.java                 # 登录用户信息
│   │   ├── LoginCustomer.java             # 登录客户/企业信息
│   │   └── UserSession.java              # 会话对象
│   └── domain/
│       └── DbEntity.java                 # 基础实体（id/createTime/updateTime/isDel）
└── authon/                             # 账权业务代码
    ├── 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/                        # 7 个 Service 接口
    │   └── impl/                       # 18 个 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 加解密工具
```

## apes-commons 内联说明

原 `apes-commons 0.0.7-SNAPSHOT` 外部 JAR 已内联为 `cn.apes.commons` 包，共 8 个类：

| 类 | 说明 |
|----|------|
| `Res` | 统一 API 响应包装（success/fail/error/get） |
| `AuthContext` | ThreadLocal 认证上下文，存储 UserSession |
| `UserSession` | 会话对象（LoginUser + LoginCustomer + token） |
| `LoginUser` | 登录用户信息（id/nickName/phone/portrait/email） |
| `LoginCustomer` | 登录客户/企业信息（id/customerName/customerType...） |
| `@Login` | 方法/类级注解，AOP 自动注入登录信息 |
| `LoginAspect` | 登录认证 AOP 切面（从 Redis 读取会话 → 写入 AuthContext） |
| `DbEntity` | 基础实体（id / createTime / updateTime / isDel） |

**LoginAspect 工作流程**：
1. 拦截 `@Login` 注解的 Controller 类/方法
2. 从请求头读取 `token`
3. 查 Redis 获取用户信息（key=token）和客户信息（key=token:customer）
4. 组装 `UserSession` 写入 `AuthContext` ThreadLocal
5. 业务方法执行完毕后清理 `AuthContext`

## 已完成的阶段

### Phase 1: apes-commons 内联 ✅
- 反推 7 个核心类接口（AuthContext/Login/LoginUser/LoginCustomer/UserSession/Res/DbEntity）
- 实现 LoginAspect AOP 切面（原在外部 JAR 中）
- 移除外部 JAR 依赖，pom.xml 无需手动安装

### Phase 2: 包名重构 ✅
- `cn.apes.cloud` → `cn.apes.authon` 全局包名重构
- `@MapperScan` 路径更新
- application.yml 配置更新
- 零 `cn.apes.cloud` 残留

### Phase 3: 编译验证 ✅
- maven-compiler-plugin 升级至 3.13.0（兼容 Java 24）
- Lombok 升级至 1.18.40（兼容 Java 24）
- 移除 `syncAllTenantsToHuoban()` 伙伴云同步（业务集成，非账权核心）
- 创建 `IpLocationService` 接口 + 桩实现
- **124 个源文件编译通过**

## 待完成事项

### Phase 4: SDK 化
- [ ] 将 `AuthContext` 改造为可远程调用的 SDK
- [ ] 提供 `authon-sdk` 模块供业务系统引用
- [ ] Token 校验改为 HTTP API 调用

### Phase 5: 网关集成
- [ ] 接入 API 网关（Spring Cloud Gateway / Nginx）
- [ ] 请求头注入认证信息（替代 ThreadLocal）
- [ ] 多租户数据源改为网关路由模式

## 从原项目提取的文件清单

共 **124 个 Java 文件**（含 8 个内联 commons 类 + 2 个新增桩实现）：

| 类型 | 数量 |
|------|------|
| Controller | 11 |
| Entity | 23 |
| DTO | 12 |
| VO | 3 |
| Service 接口 | 7 |
| Service 实现 | 18 |
| Mapper | 23 |
| Config | 5 |
| Filter | 1 |
| Util | 2 |
| Huoban DTO | 11 |
| commons 内联 | 8 |
| 主启动类 | 1 |

## 编译方式

```bash
# 直接编译（无需安装外部 JAR）
mvn clean compile

# 打包
mvn clean package -DskipTests

# 运行
java -jar target/apes-authon.jar
```

服务默认端口 `8090`，context-path `/authon`。

## 关联仓库

- 源仓库：[apes-Authdata](https://gitea.apescale.com/figmar/apes-Authdata) — 完整单体应用（含业务代码）
- 方案文档：`docs/账权模块独立服务化方案.html`（在 apes-Authdata 仓库中）
- 源码对比：`docs/源码版本对比分析-20260809.md`（在 apes-Authdata 仓库中）