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 热添加/热移除。
  - 该机制使“插件化扩展”同时支持静态项目插件和动态代码插件两条路径。