OpenAuth.Net/.agents/skills/dev/SKILL.md

name, description

name	description
dev	OpenAuth.Net后端开发规范

编码规范

通用规范

• 使用C# 9+语法特性
• 遵循Microsoft C#编码规范
• 类名使用PascalCase，方法名使用PascalCase
• 私有字段使用_camelCase，公共属性使用PascalCase
• 常量使用UPPER_CASE
• 异步方法必须添加Async后缀
• 修改完代码后不需要编译

命名规范

• Controller: 以Controller结尾，如UsersController
• Service/App: 以App结尾，如UserManagerApp
• Repository: 以Repository结尾，如UserRepository
• Entity: 实体类直接使用名词，如SysUser
• Request: 请求类以Req结尾，如QueryUserListReq
• Response: 响应类以Resp结尾，如PagedListDataResp
• DTO: 视图模型以View结尾，如UserView

注释规范

• 所有公共方法必须添加XML注释
• 复杂业务逻辑必须添加行内注释
• 使用///
  标记方法说明
• 参数使用/// 说明
• 返回值使用/// 说明

项目概述

OpenAuth.Net是一个基于.NET 9的企业级权限管理和快速开发框架，采用Martin Fowler企业级应用开发思想，集成了最新的技术栈。

技术栈

• 后端: .NET 9, ASP.NET Core WebAPI
• ORM: SqlSugar (主要) + Entity Framework Core (兼容)
• 依赖注入: Autofac
• 数据库: 支持SqlServer、MySQL、Oracle、PostgreSQL
• 定时任务: Quartz.NET
• 缓存: Redis, MemoryCache
• 前端: Vue2 + Element-UI
• 测试: NUnit
• 文档: Swagger

项目架构

📦OpenAuth.Net
 ┣ 📂Infrastructure       # 基础设施层 - 工具类、扩展方法、帮助类
 ┣ 📂OpenAuth.Repository  # 数据访问层 - 实体定义、数据访问
 ┣ 📂OpenAuth.App         # 应用服务层 - 业务逻辑
 ┣ 📂OpenAuth.WebApi      # 表示层 - WebAPI控制器
 ┣ 📂OpenAuth.Identity    # 身份认证服务 - IdentityServer4
 ┣ 📂Vue2                 # 前端项目
 ┗ 📂数据库脚本           # 数据库初始化脚本

分层架构规则

Infrastructure层 (基础设施层)

• 职责: 提供通用工具类、扩展方法、帮助类、常量定义
• 规则:
  • 不依赖其他业务层
  • 提供可复用的基础功能
  • 包含缓存、配置、工具类等
• 文件组织:
  • /Cache - 缓存相关
  • /Extensions - 扩展方法
  • /Helpers - 帮助类
  • /Const - 常量定义

Repository层 (数据访问层)

• 职责: 数据访问、实体定义、数据库操作
• 规则:
  • 继承自BaseRepository<T,TContext>
  • 实体类继承自StringEntity、LongEntity或IntAutoGenEntity
  • 使用SqlSugar或EF Core进行数据访问
  • 包含DbContext配置
• 基类使用:
  • StringEntity: 字符串主键实体
  • LongEntity: 长整型主键实体
  • IntAutoGenEntity: 自增整型主键实体

App层 (应用服务层)

• 职责: 业务逻辑处理、数据传输对象、业务规则
• 规则:
  • 继承自SqlSugarBaseApp<T>、BaseStringApp<T>、BaseLongApp<T>等基类
  • 通过构造函数注入依赖
  • 实现业务逻辑，不直接操作数据库
  • 使用Request/Response模式
• 依赖注入:

  public UserManagerApp(ISqlSugarClient client, RevelanceManagerApp app, IAuth auth) 
      : base(client, auth)
  

WebApi层 (表示层)

• 职责: HTTP请求处理、参数验证、响应格式化
• 规则:
  • 继承自ControllerBase
  • 使用[ApiController]特性
  • 统一返回Response<T>格式
  • 进行参数验证
  • 添加Swagger文档注释

数据库操作规范

SqlSugar使用规范

// 查询
var users = SugarClient.Queryable<SysUser>()
    .Where(u => u.Status == 1)
    .ToList();

// 分页查询
var result = new PagedListDataResp<Role>();
var objs = SugarClient.Queryable<Role>();
if (!string.IsNullOrEmpty(request.key))
{
    objs = objs.Where(u => u.Name.Contains(request.key));
}

result.Data = await objs.OrderBy(u => u.Name)
    .Skip((request.page - 1) * request.limit)
    .Take(request.limit).ToListAsync();
result.Count = await objs.CountAsync();
return result;

// 联表查询
 var result = SugarClient.Queryable<Relevance>()
                .LeftJoin<SysOrg>((u, o) => u.SecondId == o.Id)
                .Where((u, o) => u.FirstId == userId && u.RelKey == Define.USERORG)
                .Select((u, o) => o);
    return result.ToList();

事务处理

SugarClient.Ado.BeginTran();
try
{
    // 数据库操作
    SugarClient.Ado.CommitTran();
}
catch
{
    SugarClient.Ado.RollbackTran();
    throw;
}

权限和安全规范

权限验证

• 使用IAuth接口获取当前用户信息
• 通过_auth.GetCurrentUser()获取登录用户
• 数据权限通过机构级联控制

API设计规范

控制器设计

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly UserManagerApp _app;
    
    public UsersController(UserManagerApp app)
    {
        _app = app;
    }
    
    /// <summary>
    /// 获取用户列表
    /// </summary>
    [HttpGet]
    public async Task<Response<PagedListDataResp<UserView>>> Get([FromQuery] QueryUserListReq request)
    {
        var result = await _app.Load(request);
        return Response.Ok(result);
    }
}

依赖注入规范

Autofac配置

• 在AutofacExt.cs中配置依赖注入
• 实现IDependency接口的类自动注册
• 使用构造函数注入

测试规范

单元测试

• 使用NUnit框架
• 继承自TestBase基类
• 测试类以Test结尾
• 测试方法使用描述性名称

集成测试

• 使用AutofacWebApplicationFactory
• 模拟HTTP请求
• 验证完整的业务流程

工作流规范

流程定义

• 使用FlowScheme定义流程模板
• 通过FlowInstance管理流程实例
• FlowNode表示流程节点

流程引擎

• 使用FlowRuntime执行流程
• 支持顺序、并行、条件等流程类型
• 流程状态通过FlowInstanceStatus管理

定时任务规范

Quartz使用

• 继承自IJob接口
• 在QuartzService中注册任务
• 支持Cron表达式配置

文档规范

代码文档

• 重要业务逻辑添加注释
• 复杂算法添加说明
• 配置文件添加说明注释

配置管理

配置文件

• appsettings.json: 基础配置
• appsettings.Development.json: 开发环境配置
• appsettings.Production.json: 生产环境配置