# 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` 负责仓储访问与租户切库，`SqlSugarUnitOfWork` 适配工作单元。 - 架构形态：分层结构 + 插件模块化。`Web.Entry` 宿主，`Web.Core` 启动装配，`Application` 应用接口，`Core` 实体与基础设施，`Plugins` 扩展模块。 - 能力归属确认： - 缓存：`CacheSetup` + `SysCacheService` + `SqlSugarCache` - 鉴权：`AddJwt` + `SignatureAuthenticationHandler` + `SysAuthService`/`SysOpenAccessService` - 事件总线：`AddEventBus` + `RetryEventHandlerExecutor` + `RedisEventSourceStorer` + `AppEventSubscriber` - 任务调度：`AddSchedule` + `UseScheduleUI` + `DynamicJobCompiler` + `SysScheduleService` - 多租户：`SysTenantService` + `SqlSugarRepository` + `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())` 启动应用，并设置日志过滤与 Kestrel 超时/上传限制。 2. Startup 扫描阶段：Furion 根据 `[AppStartup]` 扫描并装配 `Application`、`Plugins`、`Web.Core` 的 `Startup`。 3. 服务注册阶段（`Web.Core/Startup.ConfigureServices`）： - 基础配置：`AddProjectOptions` - 基础设施：`AddCache`、`AddSqlSugar` - 鉴权：`AddJwt(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(enableGlobalAuthorize: true)`。 - 开放接口签名：`AddSignatureAuthentication` + `SignatureAuthenticationHandler` + `SysOpenAccessService.GetSignatureAuthenticationEventImpl()`。 - 中间件顺序：`UseCorsAccessor` 之后进入 `UseAuthentication` 与 `UseAuthorization`。 - 统一返回链路 - `AddInjectWithUnifyResult()` 统一成功/异常响应。 - 数据访问链路 - API/动态控制器 -> 业务 Service -> `SqlSugarRepository` -> `SqlSugarScope` -> DB。 - `SqlSugarRepository` 在构造时根据实体特性（系统表/日志表/租户表）+ 请求头 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()` - 通讯扩展：声明式远程请求（如 DingTalk `AddHttpRemote().AddHttpDeclarative<...>()`） - 返回规范扩展：插件可注册自身 `UnifyProvider`（如 GoView） - 中间件扩展：插件可在 `Configure` 注入专属中间件（如 ApprovalFlow） - 动态插件（运行时热扩展） - `SysPluginService` 支持把 C# 代码编译为程序集，并通过 `IDynamicApiRuntimeChangeProvider` 进行 API 热添加/热移除。 - 该机制使“插件化扩展”同时支持静态项目插件和动态代码插件两条路径。