2a60caae80
- 描述整体基于ASP.NET Core的分层架构与领域驱动设计 - 详细说明表现层、视图模型层、配置层和基础设施层职责 - 介绍用户认证、OAuth2授权码与令牌颁发的数据流过程 - 抽象说明用户与租户、声明和授权实体设计 - 说明应用启动入口和关键HTTP端点 - 列出错误处理策略和跨领域关注点（日志、追踪、安全） docs(concerns): 新增代码库问题与关注点分析文档 - 汇总并详述安全漏洞如配置文件泄露、Cookie策略不当 - 记录技术债务包括缺乏单元测试、依赖注入不统一等 - 罗列性能问题和具体代码缺陷 - 给出优先级明确的修复建议和改进措施 - 涵盖架构设计问题和依赖兼容性风险 - 说明测试覆盖缺口及高风险未测试区域 docs(conventions): 新增编码约定与规范文档 - 明确文件、类、方法、变量等命名规则 - 规范代码风格包括命名空间、主构造函数使用 - 制定日志记录、审计日志和依赖注入的标准 - 规定控制器路由、异步模式和错误处理方式 - 说明DTO命名及特性使用规范 - 描述配置管理、注释规范及常用代码注释样例 docs(integrations): 添加外部系统集成文档 - 介绍数据库连接和PostgreSQL客户端库版本 - 描述身份认证与授权服务及默认用户信息 - 说明可观测性方案及OpenTelemetry组件 - 涵盖容器化部署相关Docker与Kubernetes配置 - 说明CI/CD流水线触发条件与构建流程 - 列出环境变量需求和主要API端点 - 强调生产环境密钥管理与安全存储机制
258 lines
6.1 KiB
Markdown
258 lines
6.1 KiB
Markdown
# 架构分析
|
||
|
||
**分析日期：** 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*
|