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

Repository Guidelines

Backend Reading Context

Before reading or changing backend code under Admin.NET/, read the root document BACKEND_INFRA_CONTEXT.md first. It summarizes the project's common backend wrappers, infrastructure entry points, SqlSugar/Furion adaptation layers, and the recommended lookup order for cache, tenant, auth, data access, scheduling, and plugin integrations.

Project Structure & Module Organization

Admin.NET/ contains the backend solution Admin.NET.sln. Core business and infrastructure live in Admin.NET.Core/, example application services in Admin.NET.Application/, host bootstrapping in Admin.NET.Web.Core/ and Admin.NET.Web.Entry/, automated tests in Admin.NET.Test/, and optional integrations in Admin.NET/Plugins/. Web/ is the Vue 3 + Vite frontend; main code is under Web/src/, static files under Web/public/, localization under Web/lang/, and API generation scripts under Web/api_build/. Deployment and reference material live in docker/ and doc/.

Build, Test, and Development Commands

• dotnet restore Admin.NET/Admin.NET.sln restores backend dependencies.
• dotnet build Admin.NET/Admin.NET.sln -c Debug builds all backend projects and plugins.
• dotnet run --project Admin.NET/Admin.NET.Web.Entry starts the backend entry host locally.
• dotnet test Admin.NET/Admin.NET.Test/Admin.NET.Test.csproj runs xUnit/Furion tests.
• pnpm install --dir Web installs frontend dependencies. Use Node >=18.
• pnpm --dir Web dev starts the Vite dev server.
• pnpm --dir Web build creates the production frontend bundle.
• pnpm --dir Web lint-fix runs ESLint autofixes; pnpm --dir Web format applies Prettier.

Coding Style & Naming Conventions

Backend style is defined by Admin.NET/.editorconfig: 4-space indentation, CRLF line endings, file-scoped namespaces, braces enabled, explicit types preferred over var, PascalCase for types and members, and I prefixes for interfaces. Frontend formatting is defined in Web/.prettierrc.cjs: tabs with width 2, LF line endings, single quotes, semicolons, and trailing commas where valid. Keep feature folders stable and follow existing descriptive names in Web/src/views/ and Web/src/api-services/.

Testing Guidelines

Backend tests live in Admin.NET/Admin.NET.Test/ and currently use Furion.Xunit, Microsoft.NET.Test.Sdk, and xUnit assertions. Add tests near the relevant feature area and prefer names like DateTimeUtilTests.cs or UserTest.cs, matching the current convention. Frontend automated tests are not present in this workspace; for UI changes, run pnpm --dir Web dev, verify critical pages manually, and include lint/format results with the change.

Commit & Pull Request Guidelines

This workspace does not include .git metadata, so local history could not be inspected. Use concise, imperative commit messages and prefer a conventional format such as feat(web): add tenant switcher or fix(core): guard null claim. PRs should describe scope, affected modules, configuration changes, validation steps, and include screenshots for Web/ UI updates.

Security & Configuration Tips

Do not hardcode connection strings, tokens, tenant rules, or approval logic. Keep environment-specific values in configuration files or deployment variables, and prefer extending dictionaries, seed data, or plugin modules over editing shared core behavior directly.

---

A. 技术栈总览

• 运行时：后端核心项目均为 net8.0;net10.0 双目标（Admin.NET.Web.Entry、Admin.NET.Web.Core、Admin.NET.Application、Admin.NET.Core）。
• 基础框架：以 Furion 为主干，使用 AppStartup 装配、IDynamicApiController 动态 API、统一返回、JWT、事件总线、任务调度、远程请求等能力。
• 数据访问：Startup.AddSqlSugar() 统一接入，SqlSugarSetup 负责全局初始化/AOP/过滤器/种子，SqlSugarRepository<T> 负责仓储访问与租户切库，SqlSugarUnitOfWork 适配工作单元。
• 架构形态：分层结构 + 插件模块化。Web.Entry 宿主，Web.Core 启动装配，Application 应用接口，Core 实体与基础设施，Plugins 扩展模块。
• 能力归属确认：
  • 缓存：CacheSetup + SysCacheService + SqlSugarCache
  • 鉴权：AddJwt<JwtHandler> + SignatureAuthenticationHandler + SysAuthService/SysOpenAccessService
  • 事件总线：AddEventBus + RetryEventHandlerExecutor + RedisEventSourceStorer + AppEventSubscriber
  • 任务调度：AddSchedule + UseScheduleUI + DynamicJobCompiler + SysScheduleService
  • 多租户：SysTenantService + SqlSugarRepository<T> + SqlSugarSetup 查询过滤器
• 前端现状：README 文案仍写 Vue3 + Element Plus + Vite5，但 Web/package.json 实际依赖为 vue ^3.5.28、element-plus ^2.13.2、vite ^7.3.1（以代码配置为准）。

B. 关键依据文件

1. Admin.NET/Admin.NET.sln（解决方案与插件挂载结构）
2. Admin.NET/Admin.NET.Web.Entry/Program.cs（应用启动入口）
3. Admin.NET/Admin.NET.Web.Core/Startup.cs（核心服务注册与中间件链）
4. Admin.NET/Admin.NET.Web.Core/ProjectOptions.cs（配置绑定）
5. Admin.NET/Admin.NET.Core/Admin.NET.Core.csproj（Furion/SqlSugar 等核心依赖）
6. Admin.NET/Admin.NET.Web.Entry/Admin.NET.Web.Entry.csproj（.NET 目标框架确认）
7. Admin.NET/Admin.NET.Web.Core/Admin.NET.Web.Core.csproj
8. Admin.NET/Admin.NET.Application/Admin.NET.Application.csproj（应用层与插件引用）
9. Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarSetup.cs（SqlSugar 接入主入口）
10. Admin.NET/Admin.NET.Core/SqlSugar/SqlSugarRepository.cs（仓储与租户切库）
11. Admin.NET/Admin.NET.Core/Cache/CacheSetup.cs、Admin.NET/Admin.NET.Core/Service/Cache/SysCacheService.cs、Admin.NET/Admin.NET.Core/Cache/SqlSugarCache.cs
12. Admin.NET/Admin.NET.Web.Core/Handlers/JwtHandler.cs、Admin.NET/Admin.NET.Core/Service/Auth/SysAuthService.cs
13. Admin.NET/Admin.NET.Core/SignatureAuth/SignatureAuthenticationHandler.cs、Admin.NET/Admin.NET.Core/Service/OpenAccess/SysOpenAccessService.cs
14. Admin.NET/Admin.NET.Core/Service/Tenant/SysTenantService.cs
15. Admin.NET/Admin.NET.Core/EventBus/AppEventSubscriber.cs、Admin.NET/Admin.NET.Core/EventBus/RetryEventHandlerExecutor.cs、Admin.NET/Admin.NET.Core/EventBus/RedisEventSourceStorer.cs
16. Admin.NET/Admin.NET.Core/Job/DynamicJobCompiler.cs、Admin.NET/Admin.NET.Core/Service/Schedule/SysScheduleService.cs
17. Admin.NET/Admin.NET.Application/OpenApi/DemoOpenApi.cs（动态 API 与签名鉴权示例）
18. Admin.NET/Admin.NET.Core/Service/Plugin/SysPluginService.cs（动态插件热加载）
19. Admin.NET/Plugins/*/Startup.cs（插件装配入口）
20. README.md + Web/package.json（前端栈声明与实际依赖对照）

C. 后端模块结构树

• Admin.NET.sln
  • 启动层：Admin.NET.Web.Entry
    • 最薄宿主，Serve.Run + WebComponent（日志过滤、Kestrel 限制）
  • 启动装配层：Admin.NET.Web.Core
    • Startup 汇总注册中间件与基础能力，ProjectOptions 统一绑定配置
  • 接口/应用层：Admin.NET.Application
    • 示例开放接口（OpenApi/DemoOpenApi.cs），承接业务服务暴露；默认引用 Core 与部分插件
  • 实体层：Admin.NET.Core/Entity
    • 领域实体、表特性、租户/日志/系统表标记
  • 基础设施层：Admin.NET.Core
    • SqlSugar/、Cache/、SignatureAuth/、EventBus/、SignalR/、Job/、Service/、Option/、Utils/、Extension/
  • 测试层：Admin.NET.Test
  • 插件模块：Admin.NET/Plugins/*
    • ApprovalFlow、DingTalk、GoView、K3Cloud、ReZero、WorkWeixin，各自有 Startup.cs 与独立 Option/Service/Proxy/Dto（按插件而异）
• 业务模块注册/加载/扩展方式
  • 编译期：通过 Application.csproj 的 ProjectReference 显式引用插件（当前默认引用 ApprovalFlow、DingTalk、GoView）。
  • 启动期：Furion 扫描 [AppStartup]（Application、Plugins、Web.Core）并执行对应 ConfigureServices/Configure。
  • 运行期：SysPluginService 支持编译 C# 动态程序集，并通过 IDynamicApiRuntimeChangeProvider 热增删 API。

D. 核心启动流程

1. 入口阶段：Program.cs 调用 Serve.Run(RunOptions.Default.AddWebComponent<WebComponent>()) 启动应用，并设置日志过滤与 Kestrel 超时/上传限制。
2. Startup 扫描阶段：Furion 根据 [AppStartup] 扫描并装配 Application、Plugins、Web.Core 的 Startup。
3. 服务注册阶段（Web.Core/Startup.ConfigureServices）：

• 基础配置：AddProjectOptions
• 基础设施：AddCache、AddSqlSugar
• 鉴权：AddJwt<JwtHandler>(enableGlobalAuthorize: true) + AddSignatureAuthentication
• 应用能力：AddCorsAccessor、AddHttpRemote、AddTaskQueue、AddSchedule、AddEventBus
• Web 能力：控制器与统一返回、OAuth、ElasticSearch、限流、SignalR、OSS、日志、验证码、虚拟文件系统等

4. 中间件阶段（Web.Core/Startup.Configure）：

• 压缩/转发/异常/静态资源
• UseOAuth -> UseUnifyResultStatusCodes -> UseAppLocalization -> UseRouting
• UseCorsAccessor -> UseAuthentication -> UseAuthorization
• 限流、UseScheduleUI、Swagger/Scalar 注入、MapHubs、MVC 路由

5. 插件扩展阶段：插件 Startup 按自身实现追加注册（如审批流中间件、DingTalk 声明式远程 API、GoView 返回规范化等）。

E. 请求处理链路

• 接口暴露方式
  • 主体为 IDynamicApiController 服务类，Furion 自动生成路由。
  • 示例：DemoOpenApi 通过 [Authorize(AuthenticationSchemes = SignatureAuthenticationDefaults.AuthenticationScheme)] 走签名鉴权。
• 鉴权链路
  • 全局 JWT：AddJwt<JwtHandler>(enableGlobalAuthorize: true)。
  • 开放接口签名：AddSignatureAuthentication + SignatureAuthenticationHandler + SysOpenAccessService.GetSignatureAuthenticationEventImpl()。
  • 中间件顺序：UseCorsAccessor 之后进入 UseAuthentication 与 UseAuthorization。
• 统一返回链路
  • AddInjectWithUnifyResult<AdminResultProvider>() 统一成功/异常响应。
• 数据访问链路
  • API/动态控制器 -> 业务 Service -> SqlSugarRepository<T> -> SqlSugarScope -> DB。
  • SqlSugarRepository<T> 在构造时根据实体特性（系统表/日志表/租户表）+ 请求头 TenantId + 用户 Claim TenantId 决定连接。
  • SqlSugarSetup.SetDbAop() 统一注入软删过滤、租户过滤、数据权限过滤、审计字段与慢 SQL/错误 SQL 记录。
• 多租户介入阶段
  • 请求进入仓储前：仓储构造函数根据 Header/Claim 切租户库。
  • 查询执行前：SqlSugar 全局过滤器按租户与数据权限过滤。
  • 租户库维护：SysTenantService.GetTenantDbConnectionScope + SqlSugarSetup.InitTenantDatabase。
• 缓存介入阶段
  • 启动期：AddCache 根据配置选择 Redis，未配置则内存兜底。
  • 运行期：业务缓存统一经 SysCacheService，SqlSugar 二级缓存经 SqlSugarCache 桥接。
  • 鉴权/开放接口也依赖缓存（如黑名单、签名重放 nonce）。
• 事件与调度介入阶段
  • 事件总线：AddEventBus 注册执行器、监视器；可替换 RedisEventSourceStorer；消费由 EventConsumer。
  • 调度：AddSchedule 注册持久化/监控，UseScheduleUI 提供运维看板；动态任务编译由 DynamicJobCompiler。

F. 插件式模块机制说明

• 插件目录与职责
  • Admin.NET/Plugins 下每个插件都有独立项目与 Startup.cs，按功能拆分集成能力（审批流、钉钉、可视化大屏、K3Cloud、ReZero、企业微信等）。
• 插件注册与加载
  • 解决方案层面：插件项目挂在 Admin.NET.sln。
  • 应用层面：Admin.NET.Application.csproj 当前默认引用 ApprovalFlow、DingTalk、GoView；其它插件可按需追加引用启用。
  • 运行层面：插件 Startup 使用 [AppStartup(100)] 参与全局服务装配。
• 插件扩展模式
  • 配置扩展：插件 Option + AddConfigurableOptions<T>()
  • 通讯扩展：声明式远程请求（如 DingTalk AddHttpRemote().AddHttpDeclarative<...>()）
  • 返回规范扩展：插件可注册自身 UnifyProvider（如 GoView）
  • 中间件扩展：插件可在 Configure 注入专属中间件（如 ApprovalFlow）
• 动态插件（运行时热扩展）
  • SysPluginService 支持把 C# 代码编译为程序集，并通过 IDynamicApiRuntimeChangeProvider 进行 API 热添加/热移除。
  • 该机制使“插件化扩展”同时支持静态项目插件和动态代码插件两条路径。