hw-web/Admin.NET-v2/BACKEND_INFRA_CONTEXT.md

# 后端基础封装长期上下文

## 1. 先看哪里

阅读本仓库后端时，建议固定按下面顺序建立上下文：

1. `Admin.NET/Admin.NET.Web.Core/Startup.cs`
2. `Admin.NET/Admin.NET.Web.Core/ProjectOptions.cs`
3. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarSetup.cs`
4. `Admin.NET/Admin.NET.Core/Utils/AdminResultProvider.cs`
5. 具体能力目录：`Service/*`、`Extension/*`、`Utils/*`、`Option/*`

说明：

- `Admin.NET.Web.Entry` 基本只是宿主入口，核心装配在 `Admin.NET.Web.Core`
- `Admin.NET.Application` 当前更偏配置与示例开放接口，不是主要基础设施承载层
- `Admin.NET.Core` 是后端公共封装与基础设施中心

## 2. 后端常见封装模式

本项目后端整体是 `Furion + SqlSugar + 动态 API + 统一返回 + 多租户 + 缓存/事件/调度` 的组合式封装，常见模式如下：

- `Option/*.cs + Configuration/*.json`
  - 用于强类型配置绑定
  - 统一由 `ProjectOptions.AddProjectOptions()` 注册
- `*Setup.cs`
  - 用于框架能力接入与初始化
  - 常见如缓存、SqlSugar、OAuth、日志、SignalR
- `Service/**/*Service.cs + IDynamicApiController`
  - 默认服务暴露方式
  - 业务服务与基础设施服务都大量采用动态 API 控制器模式
- `Utils/*`
  - 放通用工具、统一返回、通用请求封装、导入导出、加解密
- `Extension/*`
  - 放高频扩展方法，特别是 SqlSugar 查询、仓储增强、请求上下文增强
- `SqlSugar/*`
  - 放数据库层二次封装
  - 包括切库、分页、过滤器、事务、初始化、缓存桥接
- `Plugins/*`
  - 外部系统集成通常独立在插件中
  - 常见模式是 `Option + Proxy + Dto + ResultProvider`

## 3. 全局核心封装

这些类/文件是后端全局理解的关键入口：

- `Admin.NET/Admin.NET.Web.Core/Startup.cs`
  - 后端总装配入口
  - 串起缓存、Jwt、Signature 鉴权、SqlSugar、EventBus、Schedule、SignalR、OSS、统一返回
- `Admin.NET/Admin.NET.Web.Core/ProjectOptions.cs`
  - 配置选项统一注册入口
- `Admin.NET/Admin.NET.Core/Utils/AdminResultProvider.cs`
  - 全局统一返回封装
  - 将成功、异常、校验失败、401/403 等全部收敛为 `AdminResult<T>`
- `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarSetup.cs`
  - SqlSugar 全局装配入口
  - 包含 AOP、软删过滤、租户过滤、数据权限过滤、差异日志、建库建表、视图、种子初始化
- `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarRepository.cs`
  - 默认仓储入口
  - 自动处理主库、日志库、租户库切换
- `Admin.NET/Admin.NET.Core/Service/Cache/SysCacheService.cs`
  - 系统缓存统一访问入口
  - 也是分布式锁、缓存包装、Hash 操作入口
- `Admin.NET/Admin.NET.Core/Service/Tenant/SysTenantService.cs`
  - 多租户核心服务
  - 租户初始化、租户缓存、租户库连接创建都集中在这里
- `Admin.NET/Admin.NET.Core/Service/Auth/SysAuthService.cs`
  - 登录、Token、RefreshToken、验证码、单点登录、黑名单等核心鉴权逻辑入口
- `Admin.NET/Admin.NET.Web.Core/Handlers/JwtHandler.cs`
  - JWT 自动续期与权限校验核心处理器

## 4. 高频工具类位置

### 4.1 Utils

- `Admin.NET/Admin.NET.Core/Utils/CommonUtil.cs`
  - 综合工具类
  - 包含固定哈希、服务地址、Excel 导入导出、设备/IP 信息等
- `Admin.NET/Admin.NET.Core/Utils/CryptogramUtil.cs`
  - 统一加解密入口
  - 支持 MD5/SM2/SM4，认证、租户连接串、开放接口都会依赖它
- `Admin.NET/Admin.NET.Core/Utils/DateTimeUtil.cs`
  - 时间处理工具
- `Admin.NET/Admin.NET.Core/Utils/FileHelper.cs`
  - 文件工具
- `Admin.NET/Admin.NET.Core/Utils/ExcelHelper.cs`
  - Excel 输出辅助
- `Admin.NET/Admin.NET.Core/Utils/CodeGenUtil.cs`
  - 代码生成辅助
- `Admin.NET/Admin.NET.Core/Utils/SSHHelper.cs`
  - SSH/SFTP 工具
- `Admin.NET/Admin.NET.Core/Utils/AdminResultProvider.cs`
  - 全局统一返回

### 4.2 通用请求/返回封装

- `Admin.NET/Admin.NET.Core/Utils/BaseFilter.cs`
  - 关键字搜索、结构化过滤模型底座
- `Admin.NET/Admin.NET.Core/Utils/BasePageInput.cs`
  - 全局分页入参底座
- `Admin.NET/Admin.NET.Core/Utils/BaseIdInput.cs`
  - 通用主键入参
- `Admin.NET/Admin.NET.Core/Utils/BaseStatusInput.cs`
  - 通用状态切换入参
- `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarPagedList.cs`
  - 通用分页返回结构

### 4.3 Extensions

- `Admin.NET/Admin.NET.Core/Extension/RepositoryExtension.cs`
  - 仓储增强最重要的扩展类
  - 包含假删除、差异日志、排序、防注入排序、多库表名 `AS`、忽略过滤器、批量列表查询
- `Admin.NET/Admin.NET.Core/Extension/SqlSugarExtension.cs`
  - 动态高级搜索/过滤扩展
  - 直接承接 `BaseFilter`
- `Admin.NET/Admin.NET.Core/Extension/HttpContextExtension.cs`
  - 设备、浏览器、操作系统、外部登录提供者等扩展
- `Admin.NET/Admin.NET.Core/Extension/RequestExtension.cs`
  - 请求源地址扩展

## 5. 遇到数据访问时先查哪些类

如果要理解某个服务方法的数据访问，不建议一开始直接盯业务查询语句，建议按下面顺序查：

1. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarRepository.cs`
2. `Admin.NET/Admin.NET.Core/Extension/RepositoryExtension.cs`
3. `Admin.NET/Admin.NET.Core/Extension/SqlSugarExtension.cs`
4. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarPagedList.cs`
5. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarSetup.cs`

重点说明：

- 仓储默认不是简单单库访问，而是带租户自动切库能力
- 软删除、租户过滤、组织数据权限过滤，都是在 `SqlSugarSetup.SetDbAop()` 和 `SqlSugarFilter` 中统一挂载
- 分页返回不是随意对象，而是统一使用 `SqlSugarPagedList<T>`

## 6. 遇到缓存时先查哪些类

缓存能力优先看下面几处：

1. `Admin.NET/Admin.NET.Core/Cache/CacheSetup.cs`
2. `Admin.NET/Admin.NET.Core/Service/Cache/SysCacheService.cs`
3. `Admin.NET/Admin.NET.Core/Cache/SqlSugarCache.cs`
4. `Admin.NET/Admin.NET.Core/Const/CacheConst.cs`

说明：

- `CacheSetup` 负责接入 Redis 或内存兜底
- `SysCacheService` 是项目内缓存统一门面，不要绕开它直接散写缓存逻辑
- `SqlSugarCache` 是 SqlSugar 二级缓存到系统缓存的桥接层
- 许多防重、黑名单、配置缓存、在线用户缓存都依赖 `SysCacheService`

## 7. 遇到多租户时先查哪些类

多租户相关优先看：

1. `Admin.NET/Admin.NET.Core/Service/Tenant/SysTenantService.cs`
2. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarRepository.cs`
3. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarSetup.cs`
4. `Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarFilter.cs`
5. `Admin.NET/Admin.NET.Core/Const/SqlSugarConst.cs`
6. `Admin.NET/Admin.NET.Core/Const/ClaimConst.cs`

关键点：

- 租户库连接是运行期动态创建的，不是固定写死
- 仓储会优先判断实体特性、请求头租户、当前登录租户，再决定切哪个库
- 数据权限与租户过滤是全局过滤器，不是每个服务手写

## 8. 遇到鉴权时先查哪些类

普通登录/JWT：

1. `Admin.NET/Admin.NET.Core/Service/Auth/SysAuthService.cs`
2. `Admin.NET/Admin.NET.Web.Core/Handlers/JwtHandler.cs`
3. `Admin.NET/Admin.NET.Core/Const/ClaimConst.cs`
4. `Admin.NET/Admin.NET.Core/Const/ConfigConst.cs`

开放接口签名鉴权：

1. `Admin.NET/Admin.NET.Core/SignatureAuth/SignatureAuthenticationHandler.cs`
2. `Admin.NET/Admin.NET.Core/Service/OpenAccess/SysOpenAccessService.cs`
3. `Admin.NET/Admin.NET.Core/SignatureAuth/SignatureAuthenticationOptions.cs`
4. `Admin.NET/Admin.NET.Core/SignatureAuth/SignatureAuthenticationEvent.cs`

第三方 OAuth：

1. `Admin.NET/Admin.NET.Core/Service/OAuth/OAuthSetup.cs`
2. `Admin.NET/Admin.NET.Core/Option/OAuthOptions.cs`

## 9. Furion / SqlSugar 强相关封装

### 9.1 Furion 强相关

- 动态 API：大量服务直接实现 `IDynamicApiController`
- 配置绑定：`ProjectOptions` 中使用 `AddConfigurableOptions<T>()`
- 统一返回：`AddInjectWithUnifyResult<AdminResultProvider>()`
- 工作单元：`SqlSugarUnitOfWork` 适配 Furion 的 `[UnitOfWork]`
- JWT：`AddJwt<JwtHandler>()`
- 签名鉴权：`AddSignatureAuthentication(...)`
- 事件总线：`AddEventBus(...)`
- 任务调度：`AddSchedule(...)`
- 声明式远程请求：`AddHttpRemote()`

### 9.2 SqlSugar 强相关

- `SqlSugarSetup`
- `SqlSugarRepository<T>`
- `SqlSugarUnitOfWork`
- `SqlSugarPagedList`
- `SqlSugarFilter`
- `SqlSugarCache`
- `RepositoryExtension`
- `SqlSugarExtension`

这些共同构成了本项目的数据访问基础设施层。

## 10. 事件、调度、打印、远程请求入口

### 10.1 事件总线

- `Admin.NET/Admin.NET.Core/EventBus/AppEventSubscriber.cs`
- `Admin.NET/Admin.NET.Core/EventBus/RetryEventHandlerExecutor.cs`
- `Admin.NET/Admin.NET.Core/EventBus/RedisEventSourceStorer.cs`
- `Admin.NET/Admin.NET.Core/EventBus/EventConsumer.cs`

说明：

- 当前事件总线不是裸 Furion 默认行为，做了 Redis 存储和失败重试增强

### 10.2 任务调度

- `Admin.NET/Admin.NET.Web.Core/Startup.cs`
- `Admin.NET/Admin.NET.Core/Job/DynamicJobCompiler.cs`

说明：

- `SysScheduleService` 更偏业务日程管理
- 框架级作业能力要看 `AddSchedule` 和 `DynamicJobCompiler`

### 10.3 打印

- `Admin.NET/Admin.NET.Core/Service/Print/SysPrintService.cs`

### 10.4 远程请求与插件代理

- `Admin.NET/Admin.NET.Web.Core/Startup.cs` 中 `AddHttpRemote()`
- `Admin.NET/Plugins/Admin.NET.Plugin.WorkWeixin/Proxy/*`
- `Admin.NET/Plugins/Admin.NET.Plugin.WorkWeixin/Utils/BaseHttpOutput.cs`
- `Admin.NET/Plugins/Admin.NET.Plugin.GoView/Util/GoViewResultProvider.cs`

说明：

- 本仓库插件侧远程调用以声明式 HTTP 接口代理为主
- 不建议新增散落式裸 `HttpClient` 封装，优先复用既有声明式模式

## 11. 配置封装位置

核心配置类主要集中在：

- `Admin.NET/Admin.NET.Core/Option/*`
- `Admin.NET/Plugins/*/Option/*`
- `Admin.NET/Admin.NET.Application/Configuration/*.json`

高频配置：

- `DbConnectionOptions`
- `CacheOptions`
- `EventBusOptions`
- `OAuthOptions`
- `UploadOptions`
- 插件侧如 `WorkWeixinOptions`、`DingTalkOptions`

## 12. 实际开发建议

- 扩展后端能力前，先确认是否已有 `Utils`、`Extension`、`SqlSugar`、`Service` 中的公共封装可复用
- 不要绕开 `SysCacheService`、`SqlSugarRepository<T>`、`AdminResultProvider` 另起一套公共实现
- 多租户、缓存键、鉴权 Claim、系统配置键都优先复用现有常量类，不要新增硬编码字符串
- 如果需要排查“为什么查询结果不对”，优先检查全局过滤器、租户切库、软删除、数据权限，而不是先怀疑业务查询本身


## 附录
### A. 工具类清单：
Startup、ProjectOptions；文件：Startup.cs、ProjectOptions.cs；分类：Infrastructure；主要用途：全局装配 Furion、Jwt、Signature、SqlSugar、Cache、EventBus、Schedule、SignalR、OSS、统一返回与 Options 绑定；复用：后端所有能力最终都从这里接入。
AdminResultProvider；文件：AdminResultProvider.cs；分类：Wrapper；主要用途：全局统一返回、异常返回、校验失败返回、401/403 状态码包装为 AdminResult<T>；复用：在 Startup 中全局注入，ExcelHelper 也直接引用。
GoViewResultProvider；文件：GoViewResultProvider.cs；分类：Wrapper；主要用途：插件侧单独的统一返回模型；复用：GoView 插件接口。
BaseFilter、BasePageInput、BaseIdInput、BaseStatusInput；文件：BaseFilter.cs、BasePageInput.cs、BaseIdInput.cs、BaseStatusInput.cs；分类：Wrapper/Request；主要用途：统一关键字搜索、结构化过滤、分页、主键入参、状态切换入参；复用：BasePageInput 约被 28 个 DTO 复用，BaseIdInput 约被 30 个 DTO 复用。
SqlSugarPagedList、SqlSugarPagedExtensions；文件：SqlSugarPagedList.cs；分类：Wrapper；主要用途：统一分页结果结构与 ToPagedList* 扩展；复用：约 32 个服务/DTO 返回分页结果时复用。
CommonUtil；文件：CommonUtil.cs；分类：Util；主要用途：固定哈希、服务地址、Excel 导入导出、XML 序列化、设备/IP 信息等综合工具；复用：登录、日志、种子数据、导入导出等多个模块。
CryptogramUtil；文件：CryptogramUtil.cs；分类：Util；主要用途：统一密码/密钥加解密入口，兼容 MD5/SM2/SM4；复用：认证、LDAP、租户连接串、更新服务等约 10 个文件。
DateTimeUtil；文件：DateTimeUtil.cs；分类：Util；主要用途：时间格式转换、Unix 时间处理；复用：签名鉴权、服务器信息、测试。
FileHelper、ExcelHelper、CodeGenUtil、SSHHelper；文件：FileHelper.cs、ExcelHelper.cs、CodeGenUtil.cs、SSHHelper.cs；分类：Helper/Util；主要用途：文件处理、Excel 导出、代码生成、SSH/SFTP；复用：代码生成、语言包、更新、外部集成。
HttpContextExtension、RequestExtension；文件：HttpContextExtension.cs、RequestExtension.cs；分类：Extensions；主要用途：扩展外部登录提供者、设备/浏览器/OS、请求源地址获取；复用：登录链路、日志链路。
RepositoryExtension；文件：RepositoryExtension.cs；分类：Extensions；主要用途：SqlSugar 仓储增强，提供假删除、差异日志、排序、防注入排序、多库 AS、忽略租户过滤器、批量 in 查询等；复用：数据访问层核心增强。
SqlSugarExtension；文件：SqlSugarExtension.cs；分类：Extensions；主要用途：动态高级搜索、组合过滤、字段表达式解析；复用：承接 BaseFilter 查询模型。
CacheSetup、SqlSugarCache；文件：CacheSetup.cs、SqlSugarCache.cs；分类：Infrastructure；主要用途：统一缓存提供者接入，Redis 与内存兜底，SqlSugar 二级缓存桥接到系统缓存；复用：全局缓存与数据访问层。
SysCacheService；文件：SysCacheService.cs；分类：Infrastructure；主要用途：缓存 CRUD、前缀删除、分布式锁、Hash、Redis 类型读取、缓存穿透包装 AdGetAsync；复用：约 33 个文件，覆盖认证、幂等、在线用户、配置、SqlSugar 缓存等。
SqlSugarRepository<T>；文件：SqlSugarRepository.cs；分类：Infrastructure；主要用途：按系统表/日志表/租户头/登录租户自动切库，封装分表操作；复用：约 61 个文件，是几乎所有服务的默认仓储入口。
SqlSugarSetup；文件：SqlSugarSetup.cs；分类：Infrastructure；主要用途：SqlSugar 全局初始化、AOP、审计字段、软删/租户/数据权限过滤、差异日志、建库建表、视图、种子、租户库初始化；复用：数据库层总装配。
SqlSugarUnitOfWork；文件：SqlSugarUnitOfWork.cs；分类：Infrastructure；主要用途：把 Furion UnitOfWork 对接到 ISqlSugarClient.AsTenant() 事务；复用：所有 [UnitOfWork] 服务方法。
SqlSugarFilter；文件：SqlSugarFilter.cs；分类：Infrastructure；主要用途：组织数据权限、自定义实体过滤器、过滤器缓存清理；复用：SqlSugarSetup 启动时挂载，组织/角色/用户服务会主动清理相关缓存。
SysTenantService；文件：SysTenantService.cs；分类：Infrastructure；主要用途：租户 CRUD、菜单初始化、Logo、默认角色、缓存租户、动态租户库连接；复用：认证、配置、在线用户、仓储切库。
SysAuthService、JwtHandler；文件：SysAuthService.cs、JwtHandler.cs；分类：Infrastructure；主要用途：登录、Token/RefreshToken、单点/黑名单、验证码、租户切换，外加 JWT 自动续期与按钮权限校验；复用：全局鉴权主链路。
SignatureAuthenticationHandler、SysOpenAccessService；文件：SignatureAuthenticationHandler.cs、SysOpenAccessService.cs；分类：Infrastructure；主要用途：开放接口签名鉴权、accessKey/accessSecret 校验、重放防护、绑定用户租户 Claim；复用：AddSignatureAuthentication 和开放接口控制器。
OAuthSetup；文件：OAuthSetup.cs；分类：Infrastructure；主要用途：微信/Gitee 第三方登录注册与 Cookie 策略；复用：认证入口。
LoggingSetup；文件：LoggingSetup.cs；分类：Infrastructure；主要用途：控制台、文件、数据库、ES 日志写入与 Furion Monitor Logging 配置；复用：全局日志体系。
AppEventSubscriber、EventConsumer<T>、RetryEventHandlerExecutor；文件：AppEventSubscriber.cs、EventConsumer.cs、RetryEventHandlerExecutor.cs；分类：Infrastructure；主要用途：事件订阅、Redis 消费桥接、失败重试/熔断回调；复用：全局 EventBus 增强。
DynamicJobCompiler、SysScheduleService；文件：DynamicJobCompiler.cs、SysScheduleService.cs；分类：Infrastructure；主要用途：前者是框架级动态任务编译，后者是业务日程管理；复用：任务调度与日程能力。
SignalRSetup；文件：SignalRSetup.cs；分类：Infrastructure；主要用途：SignalR 序列化、Redis Backplane、DataProtection Key 持久化；复用：在线用户/即时通讯链路。
SysPrintService；文件：SysPrintService.cs；分类：Infrastructure；主要用途：打印模板分页、增删改查；复用：打印能力统一入口。
IOSSServiceManager、OSSServiceManager；文件：IOSSServiceManager.cs；分类：Infrastructure；主要用途：统一 OSS 服务实例缓存、动态 provider 配置转换；复用：文件存储、MultiOSSFileProvider、SysFileProviderService。
IWorkWeixinAuthHttp、IWorkWeixinAppChatHttp、IDepartmentHttp、ITagHttp、BaseWorkOutput；文件：IWorkWeixinAuthHttp.cs、IWorkWeixinAppChatHttp.cs、IDepartmentHttp.cs、ITagHttp.cs、BaseHttpOutput.cs；分类：Infrastructure/Remote；主要用途：通过声明式 HTTP 代理封装企业微信远程调用，统一返回基类；复用：插件远程集成入口。
DbConnectionOptions、CacheOptions、EventBusOptions、OAuthOptions、UploadOptions、WorkWeixinOptions、DingTalkOptions；文件：DbConnectionOptions.cs、CacheOptions.cs、EventBusOptions.cs、OAuthOptions.cs、UploadOptions.cs、WorkWeixinOptions.cs、DingTalkOptions.cs；分类：Options；主要用途：把 Configuration/*.json 与插件配置绑定到强类型 Options；复用：由 ProjectOptions 统一注册。
CacheConst、ClaimConst、ConfigConst、SqlSugarConst、ApplicationConst；文件：CacheConst.cs、ClaimConst.cs、ConfigConst.cs、SqlSugarConst.cs、ApplicationConst.cs；分类：Const；主要用途：统一缓存键、Claim 名、配置键、数据库配置 ID、应用分组名；复用：认证/缓存/多租户/配置/分页/日志全链路。

### B. 高价值基础封装：
全局核心封装：Startup + ProjectOptions、AdminResultProvider、SqlSugarSetup、SqlSugarRepository<T>、SysCacheService、SysTenantService、SysAuthService、JwtHandler。这几类基本决定了“配置如何绑定、接口如何暴露、数据如何访问、用户如何鉴权、租户如何切换、返回如何统一”。
与 Furion 强相关：IDynamicApiController 是服务层默认暴露方式；AddConfigurableOptions 负责 Options 绑定；AddInjectWithUnifyResult<AdminResultProvider> 负责统一返回；AddJwt<JwtHandler>、AddSignatureAuthentication、AddEventBus、AddSchedule、AddHttpRemote 都在 Startup 汇总；SqlSugarUnitOfWork 是 Furion [UnitOfWork] 到 SqlSugar 的适配层。
与 SqlSugar 强相关：SqlSugarSetup、SqlSugarRepository<T>、SqlSugarPagedList、RepositoryExtension、SqlSugarExtension、SqlSugarFilter、SqlSugarCache、SqlSugarUnitOfWork 是完整的二次封装链，覆盖分页、过滤、分表、租户切库、软删、差异日志、种子、AOP 与缓存。
多租户相关：先看 SysTenantService，再看 SqlSugarRepository<T> 的自动切库逻辑，最后看 SqlSugarSetup.SetDbAop 和 SqlSugarFilter 的租户/数据权限过滤。
缓存相关：先看 CacheSetup，日常调用和锁都收敛到 SysCacheService，数据库二级缓存走 SqlSugarCache，缓存键规范看 CacheConst。
鉴权相关：普通登录链路看 SysAuthService + JwtHandler，开放接口签名链路看 SignatureAuthenticationHandler + SysOpenAccessService，第三方登录看 OAuthSetup，Claim 规范看 ClaimConst。
事件/任务/远程/打印：事件总线看 AppEventSubscriber + RetryEventHandlerExecutor + RedisEventSourceStorer；任务调度看 Startup.AddSchedule 和 DynamicJobCompiler；远程请求看 Startup.AddHttpRemote 加插件 Proxy/*Http.cs；打印入口看 SysPrintService。

### C. 建议写入 AGENTS.md 的内容草案
本项目后端公共封装高度集中在 Admin.NET.Core，Admin.NET.Application 目前更多承担配置与示例开放接口，Admin.NET.Web.Core 主要负责能力装配，Admin.NET.Web.Entry 只是最薄宿主入口。
常见封装模式是：Option/*.cs + Configuration/*.json 做配置绑定，*Setup.cs 做框架接入，Service/**/*Service.cs + IDynamicApiController 做动态 API，Utils/* 与 Extension/* 提供高频工具和查询增强，SqlSugar/* 承担数据库层二次封装。
阅读代码的优先顺序建议固定为：Admin.NET.Web.Core/Startup.cs -> Admin.NET.Web.Core/ProjectOptions.cs -> Admin.NET.Core/SqlSugar/SqlSugarSetup.cs -> Admin.NET.Core/Utils/AdminResultProvider.cs -> 具体能力服务目录。
高频工具类主要在 Admin.NET.Core/Utils 与 Admin.NET.Core/Extension。如果看到分页、筛选、关键字搜索，先查 BaseFilter、BasePageInput、SqlSugarExtension、SqlSugarPagedList；如果看到通用导出/文件/加密，先查 CommonUtil、ExcelHelper、FileHelper、CryptogramUtil。
遇到缓存问题时优先看 CacheSetup、SysCacheService、SqlSugarCache、CacheConst；遇到租户与数据权限时优先看 SysTenantService、SqlSugarRepository<T>、SqlSugarFilter、SqlSugarSetup；遇到鉴权问题时优先看 SysAuthService、JwtHandler、SignatureAuthenticationHandler、SysOpenAccessService、OAuthSetup。
遇到数据访问问题，不要先从具体业务服务硬读 SQL，先看 SqlSugarRepository<T> 的切库规则、RepositoryExtension 的差异日志/软删增强、SqlSugarExtension 的动态过滤，再回到业务查询。
遇到插件与外部系统集成，先看插件自己的 Option、Proxy、Utils/BaseHttpOutput 或自定义 ResultProvider，本仓库远程调用模式偏向“声明式 HTTP 接口 + 统一输入输出 DTO”，不是散落的裸 HttpClient。
当前代码基底明确是 Furion + SqlSugar + Furion EventBus/Schedule/RemoteRequest 组合，后续开发应优先复用这些既有封装，不要绕开它们直接造新的通用层。