zangch
/
hw-web
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6d8d0cc5fb'
${ noResults }
hw-web/Admin.NET-v2/BACKEND_INFRA_CONTEXT.md

22 KiB
Raw Blame History Unescape Escape

后端基础封装长期上下文

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；复用：在 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；文件：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、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、SysCacheService、SysTenantService、SysAuthService、JwtHandler。这几类基本决定了“配置如何绑定、接口如何暴露、数据如何访问、用户如何鉴权、租户如何切换、返回如何统一”。 与 Furion 强相关：IDynamicApiController 是服务层默认暴露方式；AddConfigurableOptions 负责 Options 绑定；AddInjectWithUnifyResult 负责统一返回；AddJwt、AddSignatureAuthentication、AddEventBus、AddSchedule、AddHttpRemote 都在 Startup 汇总；SqlSugarUnitOfWork 是 Furion [UnitOfWork] 到 SqlSugar 的适配层。 与 SqlSugar 强相关：SqlSugarSetup、SqlSugarRepository、SqlSugarPagedList、RepositoryExtension、SqlSugarExtension、SqlSugarFilter、SqlSugarCache、SqlSugarUnitOfWork 是完整的二次封装链，覆盖分页、过滤、分表、租户切库、软删、差异日志、种子、AOP 与缓存。 多租户相关：先看 SysTenantService，再看 SqlSugarRepository 的自动切库逻辑，最后看 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、SqlSugarFilter、SqlSugarSetup；遇到鉴权问题时优先看 SysAuthService、JwtHandler、SignatureAuthenticationHandler、SysOpenAccessService、OAuthSetup。 遇到数据访问问题，不要先从具体业务服务硬读 SQL，先看 SqlSugarRepository 的切库规则、RepositoryExtension 的差异日志/软删增强、SqlSugarExtension 的动态过滤，再回到业务查询。 遇到插件与外部系统集成，先看插件自己的 Option、Proxy、Utils/BaseHttpOutput 或自定义 ResultProvider，本仓库远程调用模式偏向“声明式 HTTP 接口 + 统一输入输出 DTO”，不是散落的裸 HttpClient。 当前代码基底明确是 Furion + SqlSugar + Furion EventBus/Schedule/RemoteRequest 组合，后续开发应优先复用这些既有封装，不要绕开它们直接造新的通用层。