# 架构分析

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

## 模式概述

**整体架构：** 基于 ASP.NET Core 的现代 Web 应用架构，采用分层设计结合领域驱动思想。

**核心特性：**
- 使用 OpenIddict 实现 OAuth2/OIDC 授权服务器功能
- 采用 ASP.NET Core Identity 进行用户身份管理
- 基于 Entity Framework Core 进行数据访问
- 支持多租户（Tenant）架构
- 集成 MediatR 实现 CQRS 模式（通过共享基础设施包）

## 分层架构

### 1. 表现层（Presentation Layer）

**位置：** `src/Controllers/`、`src/Views/`

**职责：**
- 处理 HTTP 请求与响应
- 渲染 Razor 视图
- 用户交互界面

**关键控制器：**
- `AccountController`：用户登录、注册、登出
- `AuthorizationController`：OAuth2 授权端点
- `TokenController`：令牌颁发端点
- `DashboardController`：用户仪表板
- `UsersController`、`RolesController`、`TenantsController`：管理功能

### 2. 视图模型层（ViewModel Layer）

**位置：** `src/ViewModels/`

**职责：**
- 在控制器与视图之间传递数据
- 表单数据绑定与验证

**关键视图模型：**
- `LoginViewModel`：登录表单
- `RegisterViewModel`：注册表单
- `AuthorizeViewModel`：授权确认表单
- `DashboardViewModel`：仪表板数据

### 3. 配置层（Configuration Layer）

**位置：** `src/Configuration/`

**职责：**
- 集中管理应用程序配置
- OpenIddict 服务配置
- 身份验证策略配置

**关键配置：**
- `OpenIddictSetup.cs`：OpenIddict 完整配置，包括授权流程、令牌生命周期、作用域等
- `FormValueRequiredAttribute.cs`：自定义属性用于表单提交处理

### 4. 基础设施层（Infrastructure Layer）

**外部依赖：** `Fengling.Platform.Infrastructure` NuGet 包

**提供的功能：**
- `PlatformDbContext`：Entity Framework Core 数据库上下文
- `ApplicationUser`：应用程序用户实体
- `ApplicationRole`：应用程序角色实体
- 仓储（Repository）模式实现
- MediatR 中间件与行为（Behaviors）
- 命令锁定行为（Command Lock Behavior）
- 工作单元（Unit of Work）支持

## 数据流

### 用户认证流程

```
1. 用户访问 /account/login
   ↓
2. AccountController 返回登录视图（Login.cshtml）
   ↓
3. 用户提交表单 → AccountController.Login POST
   ↓
4. UserManager 验证用户名密码
   ↓
5. SignInManager 创建认证 Cookie
   ↓
6. 重定向到原始 URL 或 /dashboard
```

### OAuth2 授权码流程

```
1. 客户端应用重定向到 /connect/authorize
   ↓
2. AuthorizationController.Authorize 检查用户登录状态
   ↓
3. 未登录 → 重定向到登录页面
   ↓
4. 已登录 → 检查授权记录
   ↓
5. 需要用户授权 → 返回授权确认视图（Authorize.cshtml）
   ↓
6. 用户确认 → AuthorizationController.Accept
   ↓
7. 创建授权记录 → 返回令牌
```

### 令牌颁发流程

```
1. 客户端 POST /connect/token
   ↓
2. TokenController.Exchange 处理请求
   ↓
3. 根据授权类型（password/refresh_token/authorization_code）处理
   ↓
4. 从 UserManager 获取用户信息
   ↓
5. 构建 Claims 身份（包括租户信息、角色）
   ↓
6. 设置 Claim Destinations
   ↓
7. SignIn 返回令牌
```

## 关键抽象

### 用户与租户抽象

**ApplicationUser：**
- 继承自 ASP.NET Core Identity 的 IdentityUser
- 包含 `TenantInfo` 属性实现多租户支持

**TenantInfo 值对象：**
- `TenantId`：租户标识符
- `TenantCode`：租户代码
- `TenantName`：租户名称

### 声明（Claims）抽象

**标准声明：**
- `sub`：用户唯一标识
- `name`：用户名
- `email`：用户邮箱
- `role`：用户角色

**自定义声明：**
- `tenant_id`：租户 ID
- `tenant_code`：租户代码
- `tenant_name`：租户名称

### 授权（Authorization）抽象

**OpenIddict 实体：**
- `OpenIddictApplication`：OAuth2 客户端应用
- `OpenIddictAuthorization`：授权记录
- `OpenIddictScope`：授权作用域
- `OpenIddictToken`：访问令牌/刷新令牌

## 入口点

### Web 应用程序入口

**位置：** `src/Program.cs`

**启动流程：**
1. 配置 Serilog 日志
2. 注册平台核心服务（AddPlatformCore）
3. 配置 ASP.NET Core Identity
4. 配置 Razor Pages 和 MVC
5. 配置 Cookie 认证
6. 配置 OpenIddict
7. 配置 OpenTelemetry 分布式追踪
8. 配置健康检查
9. 注册仓储（Repositories）
10. 注册 MediatR 和中间件行为
11. 配置 Swagger（开发环境）
12. 初始化数据库

### HTTP 端点

**认证端点：**
- `GET/POST /account/login`：用户登录
- `GET/POST /account/register`：用户注册
- `POST /account/~/connect/logout`：用户登出
- `GET/POST /connect/authorize`：授权端点
- `POST /connect/token`：令牌端点
- `GET /connect/userinfo`：用户信息端点

**管理端点：**
- `GET /dashboard`：用户仪表板
- `GET /dashboard/profile`：用户资料
- `GET /dashboard/settings`：设置页面
- `GET/POST /users`：用户管理
- `GET/POST /roles`：角色管理
- `GET/POST /tenants`：租户管理

**系统端点：**
- `GET /health`：健康检查
- `GET /swagger/index.html`：API 文档

## 错误处理

**策略：** 基于 ASP.NET Core 标准异常处理

**模式：**
- 模型验证失败返回视图（ModelState）
- 认证失败返回 401/403
- OpenIddict 错误返回标准错误响应
- 全局异常由中间件捕获并记录

## 跨领域关注点

### 日志记录

**框架：** Serilog

**配置：** 在 Program.cs 中配置，控制台输出

**模板：**
```
[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}
```

### 分布式追踪

**框架：** OpenTelemetry

**组件：**
- AspNetCoreInstrumentation
- HttpClientInstrumentation
- OpenIddict.Server.AspNetCore 追踪源
- OTLP Exporter

### 健康检查

**端点：** `/health`

**检查项：**
- PostgreSQL 数据库连接（NpgSql）

### 安全配置

**认证方案：**
- Cookie 认证（默认方案）：用于 Web 界面登录
- OpenIddict Server：用于 OAuth2/OIDC

**令牌配置：**
- 访问令牌生命周期：24 小时
- 使用引用令牌（Reference Tokens）
- 支持刷新令牌

---

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