SimpleAdmin API

基于 Fake 框架的简单管理系统后端 API。

技术栈

• .NET 8.0 - 最新的 .NET 平台
• Fake Framework - 模块化应用框架
• Entity Framework Core - ORM 框架
• SQL Server - 数据库
• JWT - 身份认证
• Swagger - API 文档

功能特性

• ✅ 模块化架构
• ✅ 自动 API 生成（ApplicationService 自动转换为 Controller）
• ✅ RBAC 权限管理
• ✅ JWT 认证
• ✅ Swagger 文档
• ✅ 依赖注入
• ✅ 工作单元
• ✅ 审计日志

开始使用

前置要求

• .NET 8.0 SDK
• SQL Server (LocalDB 或完整版)

配置数据库

修改 appsettings.json 中的连接字符串：

{
  "ConnectionStrings": {
    "Default": "Server=(localdb)\\mssqllocaldb;Database=SimpleAdminDb;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}

数据库迁移

# 添加迁移
dotnet ef migrations add InitialCreate --project ../modules/rbac/Fake.Rbac.Infrastructure

# 更新数据库
dotnet ef database update --project ../modules/rbac/Fake.Rbac.Infrastructure

运行项目

dotnet run

访问 http://localhost:5000 查看 Swagger 文档。

默认账号

系统会自动创建默认管理员账号：

• 账号：admin
• 密码：123456
• 角色：超级管理员

⚠️ 重要：请在生产环境中立即修改默认密码！

API 端点

认证 API

• POST /api/auth/login - 用户登录
• GET /api/auth/current - 获取当前用户信息
• PUT /api/auth/password - 修改密码

用户管理 API

• GET /api/rbac/user/list - 获取用户列表
• GET /api/rbac/user/{id} - 获取用户详情
• POST /api/rbac/user - 创建用户
• PUT /api/rbac/user/{id} - 更新用户
• DELETE /api/rbac/user/{id} - 删除用户
• PUT /api/rbac/user/{id}/roles - 分配角色
• GET /api/rbac/user/{id}/permissions - 获取用户权限

角色管理 API

• GET /api/rbac/role/list - 获取角色列表
• GET /api/rbac/role/all - 获取所有角色
• GET /api/rbac/role/{id} - 获取角色详情
• POST /api/rbac/role - 创建角色
• PUT /api/rbac/role/{id} - 更新角色
• DELETE /api/rbac/role/{id} - 删除角色
• PUT /api/rbac/role/{id}/permissions - 分配权限

菜单管理 API

• GET /api/rbac/menu/tree - 获取菜单树
• GET /api/rbac/menu/user/{userId} - 获取用户菜单
• GET /api/rbac/menu/{id} - 获取菜单详情
• POST /api/rbac/menu - 创建菜单
• PUT /api/rbac/menu/{id} - 更新菜单
• DELETE /api/rbac/menu/{id} - 删除菜单

权限管理 API

• GET /api/rbac/permission/all - 获取所有权限
• GET /api/rbac/permission/tree - 获取权限树

项目结构

SimpleAdmin.Api/
├── Controllers/          # 控制器（手动创建的）
├── Program.cs           # 程序入口
├── SimpleAdminApiModule.cs  # 主模块配置
├── appsettings.json     # 配置文件
└── README.md

开发规范（强制）

更完整的分层 / 路由 / DTO 约定见 开发复刻说明.md、design.md。下列为新增代码与合入共享分支的硬性标准，评审与上传前必须满足。

1. 写接口必须写注释

对外暴露的 Application API（ApplicationService 上的 [HttpGet] / [HttpPost] 等方法）必须有 XML / 中文注释，至少说明：

• 接口用途（做什么）
• 关键入参含义与约束（可写在方法注释或 DTO 属性注释上）
• 关键返回语义或业务失败场景（如抛 BusinessException 的条件）

DTO、领域常量、非显而易见的私有辅助方法也应补注释，避免「只有路由名能猜业务」。

/// <summary>
/// 批量创建仓储代发订单：建单并绑定库存/包裹，产品须为分组 wms。
/// </summary>
/// <param name="input">仓库、产品编码与店铺订单绑定明细。</param>
[HttpPost("/order/platform-store-order/batch-create-fulfill-wms")]
public async Task<PlatformStoreOrderBatchCreateLogisticsOutput> BatchCreateFulfillWmsAsync(
    PlatformStoreOrderBatchCreateFulfillInput input)

2. 写 SQL 必须走 ORM（SqlSugar）

业务读写、列表筛选、联表、聚合、更新一律通过 SqlSugar / Repository，禁止在 Application / Domain 服务里手写拼装 SQL 字符串或 Ado.SqlQuery 作为常规实现。

允许	禁止（业务代码）
Repository / ISugarQueryable / 表达式 Where	服务内大段 "SELECT ... " + 拼接
实体 + 仓储封装复杂查询	绕过仓储直接 ADO 执行业务 SQL
sql/*.sql 仅作建库 / 存量 DDL 迁移	用脚本替代日常业务 CRUD

存量 DDL、字典初始化等脚本放在 sql/（说明见 sql/README.md），与运行时 ORM 查询分离；运行时查询与写入必须 ORM。

新增增量迁移文件命名：migrate_<主题>_YYYYMMDD.sql（日期在末尾，例如 migrate_xxx_20261016.sql）。详细约定见 sql/README.md。

3. 上传代码前先同步远端

test、master 等共享分支会有其他人提交。推送前必须先拉取远端，再上传，避免覆盖或漏掉别人的提交。

git fetch origin
git pull --ff-only origin <当前分支>
git push origin <当前分支>

• 工作区有未提交改动时，先暂存（stash）或提交，再同步，同步完成后再恢复。
• 本地已有未推送提交、远端也有新提交时，先 rebase 或 merge 并解决冲突，确认与远端对齐后再 push。
• 禁止在未同步远端的情况下直接 push 共享分支。

4. 相关约定速查

• 禁止新建库级唯一索引（UNIQUE KEY）：见 .cursor/rules/no-unique-indexes.mdc，业务唯一性在 Application 校验。
• 路由显式声明；分页统一 totalCount + items；勿把 Entity 直接返回前端。

Fake 框架特性

自动 API 生成

所有继承自 ApplicationService 的服务会自动生成对应的 API 端点，无需手动创建 Controller。

模块化

通过 [DependsOn] 特性声明模块依赖：

[DependsOn(
    typeof(FakeAspNetCoreModule),
    typeof(FakeRbacApplicationModule)
)]
public class SimpleAdminApiModule : FakeModule
{
    // ...
}

依赖注入

框架自动注册服务，支持：

• ITransientDependency - 瞬时
• IScopedDependency - 作用域
• ISingletonDependency - 单例

工作单元

应用服务方法自动包装在工作单元中，支持事务管理。

JWT 配置

JWT 配置在 appsettings.json 中：

{
  "JwtSettings": {
    "SecretKey": "your-secret-key-here",
    "ExpiryInMinutes": 60
  }
}

CORS 配置

默认允许的前端地址：

• http://localhost:3000
• http://localhost:5173

可在 SimpleAdminApiModule.cs 中修改。

许可证

MIT