# 架构

**分析日期：** 2026-02-28

## 模式概述

**整体：** 分层架构 + 领域驱动设计 (DDD)

**关键特性：**
- **控制器层 (Controllers)** - 处理 HTTP 请求，返回 API 响应
- **服务层 (Services)** - 业务逻辑实现，使用依赖注入
- **数据访问层** - 通过 Entity Framework Core 访问数据库
- **领域模型** - 来自外部 Domain 程序集 (Fengling.Platform.Domain)

## 层次

**控制器层 (Controllers)：**
- 位置：`src/Controllers/`
- 包含：`UsersController.cs`, `RolesController.cs`, `TenantsController.cs`, `OAuthClientsController.cs`, `GatewayController.cs`
- 职责：处理 HTTP 请求、参数验证、返回响应
- 依赖：Service 层接口

**服务层 (Services)：**
- 位置：`src/Services/`
- 包含：`UserService.cs`, `RoleService.cs`, `TenantService.cs`, `OAuthClientService.cs`, `GatewayService.cs`, `H5LinkService.cs`
- 职责：业务逻辑实现、数据转换、事务管理
- 依赖：Domain 模型、DbContext、UserManager、RoleManager

**数据层 (Data/Infrastructure)：**
- PlatformDbContext - 平台业务数据
- GatewayDbContext - 网关配置数据
- 仓储模式：通过 NetCorePal.Extensions.Repository

**领域层 (Domain - 外部引用)：**
- Fengling.Platform.Domain.AggregatesModel.UserAggregate
- Fengling.Platform.Domain.AggregatesModel.RoleAggregate
- Fengling.Platform.Domain.AggregatesModel.TenantAggregate

## 数据流

**典型请求流程：**

1. **HTTP 请求** → Controller 接收
2. **参数验证** → DTO 绑定
3. **业务处理** → Service 层执行
4. **数据持久化** → EF Core 保存
5. **响应返回** → Controller 返回结果

**状态管理：**
- 无状态 API 设计
- 状态存储在 PostgreSQL 数据库
- 认证状态通过 JWT Token 传递

## 关键抽象

**服务接口：**
- `IUserService` - 用户管理
- `IRoleService` - 角色管理
- `ITenantService` - 租户管理
- `IOAuthClientService` - OAuth 客户端管理
- `IGatewayService` - 网关配置
- `IH5LinkService` - H5 链接服务

**数据传输对象 (DTO)：**
- 位置：`src/Models/Dtos/`
- 模式：CreateXxxDto, UpdateXxxDto, XxxDto, XxxQueryDto
- 用途：API 请求/响应数据结构

## 入口点

**主入口：**
- 位置：`src/Program.cs`
- 触发：应用启动时执行
- 职责：服务注册、中间件配置、管道构建

**API 端点：**
- `/api/console/[controller]` - RESTful API 前缀
- `/swagger` - API 文档

## 错误处理

**策略：** 
- 异常捕获 + 日志记录
- 返回标准 HTTP 状态码
- 错误详情通过响应体返回

**模式：**
```csharp
try {
    // 业务逻辑
} catch (KeyNotFoundException ex) {
    return NotFound();
} catch (InvalidOperationException ex) {
    return BadRequest();
} catch (Exception ex) {
    _logger.LogError(ex, "...");
    return StatusCode(500);
}
```

## 跨领域关注

**日志：** Microsoft.Extensions.Logging + ILogger<T>
**验证：** ASP.NET Core Model Validation + FluentValidation (已引用)
**认证：** OpenIddict + JWT Bearer

---

*架构分析：2026-02-28*