zzh
983dff12c5
All checks were successful
Build and Deploy / deploy (push) Successful in 1m2s
Co-authored-by: Cursor <cursoragent@cursor.com>
238 lines
6.7 KiB
Markdown
238 lines
6.7 KiB
Markdown
# 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` 中的连接字符串：
|
||
|
||
```json
|
||
{
|
||
"ConnectionStrings": {
|
||
"Default": "Server=(localdb)\\mssqllocaldb;Database=SimpleAdminDb;Trusted_Connection=true;MultipleActiveResultSets=true"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 添加迁移
|
||
dotnet ef migrations add InitialCreate --project ../modules/rbac/Fake.Rbac.Infrastructure
|
||
|
||
# 更新数据库
|
||
dotnet ef database update --project ../modules/rbac/Fake.Rbac.Infrastructure
|
||
```
|
||
|
||
### 运行项目
|
||
|
||
```bash
|
||
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、领域常量、非显而易见的私有辅助方法也应补注释，避免「只有路由名能猜业务」。
|
||
|
||
```csharp
|
||
/// <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` 等共享分支会有其他人提交。**推送前必须先拉取远端，再上传**，避免覆盖或漏掉别人的提交。
|
||
|
||
```bash
|
||
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]` 特性声明模块依赖：
|
||
|
||
```csharp
|
||
[DependsOn(
|
||
typeof(FakeAspNetCoreModule),
|
||
typeof(FakeRbacApplicationModule)
|
||
)]
|
||
public class SimpleAdminApiModule : FakeModule
|
||
{
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 依赖注入
|
||
|
||
框架自动注册服务，支持：
|
||
- `ITransientDependency` - 瞬时
|
||
- `IScopedDependency` - 作用域
|
||
- `ISingletonDependency` - 单例
|
||
|
||
### 工作单元
|
||
|
||
应用服务方法自动包装在工作单元中，支持事务管理。
|
||
|
||
## JWT 配置
|
||
|
||
JWT 配置在 `appsettings.json` 中：
|
||
|
||
```json
|
||
{
|
||
"JwtSettings": {
|
||
"SecretKey": "your-secret-key-here",
|
||
"ExpiryInMinutes": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
## CORS 配置
|
||
|
||
默认允许的前端地址：
|
||
- http://localhost:3000
|
||
- http://localhost:5173
|
||
|
||
可在 `SimpleAdminApiModule.cs` 中修改。
|
||
|
||
## 许可证
|
||
|
||
MIT
|