# 代码库结构

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

## 目录布局

```
fengling-auth-service/
├── src/                          # 源代码根目录
│   ├── Controllers/               # MVC 控制器
│   ├── ViewModels/               # 视图模型
│   ├── Views/                    # Razor 视图
│   ├── Configuration/            # 配置类
│   ├── Properties/               # 启动配置
│   ├── Program.cs                # 入口点
│   ├── Fengling.AuthService.csproj # 项目文件
│   ├── appsettings.json          # 应用配置
│   ├── appsettings.Development.json # 开发环境配置
│   └── Fengling.AuthService.http  # HTTP 请求测试文件
├── k8s/                          # Kubernetes 部署配置
│   ├── deployment.yaml            # Deployment 配置
│   └── service.yaml              # Service 配置
├── .gitea/workflows/             # Gittea CI/CD 配置
│   └── ci.yaml                   # CI 流程
├── Dockerfile                     # Docker 镜像构建
├── NuGet.Config                  # NuGet 源配置
├── Directory.Packages.props      # 包版本管理
├── Fengling.AuthService.slnx     # 解决方案文件
└── README.md                     # 项目说明
```

## 目录用途

### 源代码目录（src/）

**Controllers/：**
- 用途：MVC 控制器，处理 HTTP 请求
- 包含：
  - `AccountController.cs`：账户管理（登录、注册、登出）
  - `AuthorizationController.cs`：OAuth2 授权
  - `TokenController.cs`：令牌颁发
  - `DashboardController.cs`：用户仪表板
  - `UsersController.cs`、`RolesController.cs`、`TenantsController.cs`：管理功能
  - `StatsController.cs`、`AuditLogsController.cs`、`AccessLogsController.cs`：日志统计
  - `OAuthClientsController.cs`：OAuth 客户端管理
  - `LogoutController.cs`：登出处理

**ViewModels/：**
- 用途：视图模型，用于视图与控制器之间的数据传输
- 包含：
  - `LoginViewModel.cs`：登录视图模型
  - `RegisterViewModel.cs`：注册视图模型
  - `AuthorizeViewModel.cs`：授权确认视图模型
  - `DashboardViewModel.cs`：仪表板视图模型

**Views/：**
- 用途：Razor 视图文件
- 结构：
  - `Account/`：账户相关视图（Login、Register）
  - `Authorization/`：授权视图（Authorize）
  - `Dashboard/`：仪表板视图（Index、Profile、Settings）
  - `Shared/`：共享视图（_Layout）
  - `_ViewStart.cshtml`：视图起始配置
  - `_ViewImports.cshtml`：视图导入配置

**Configuration/：**
- 用途：集中管理应用程序配置
- 包含：
  - `OpenIddictSetup.cs`：OpenIddict 服务配置
  - `FormValueRequiredAttribute.cs`：自定义验证属性

**Properties/：**
- 用途：启动配置文件
- 包含：
  - `launchSettings.json`：启动配置

## 关键文件位置

### 入口点

**`src/Program.cs`：**
- 应用程序启动入口
- 服务注册
- 中间件配置
- 管道构建

### 配置文件

**`src/appsettings.json`：**
- 数据库连接字符串
- JWT 配置
- OpenIddict 配置
- 日志配置

**`src/appsettings.Development.json`：**
- 开发环境特定配置

### 项目文件

**`src/Fengling.AuthService.csproj`：**
- 项目依赖声明
- 目标框架：net10.0
- 关键包：
  - OpenIddict（OAuth2/OIDC）
  - Entity Framework Core（数据访问）
  - ASP.NET Core Identity（身份管理）
  - Serilog（日志）
  - OpenTelemetry（可观测性）

## 命名约定

### 文件命名

**控制器：**
- 模式：`{EntityName}Controller.cs`
- 示例：`AccountController.cs`、`UsersController.cs`

**视图模型：**
- 模式：`{Feature}ViewModel.cs`
- 示例：`LoginViewModel.cs`、`AuthorizeViewModel.cs`

**视图：**
- 模式：`{Action}.cshtml`
- 示例：`Login.cshtml`、`Authorize.cshtml`

**配置类：**
- 模式：`{Feature}Setup.cs` 或 `{Feature}Attribute.cs`
- 示例：`OpenIddictSetup.cs`、`FormValueRequiredAttribute.cs`

### 目录命名

** Controllers：**
- 复数形式，如 `Controllers`、`Users`

** ViewModels：**
- 复数形式，如 `ViewModels`

** Views：**
- 与控制器对应，如 `Account`、`Dashboard`

### 命名空间

**模式：** `Fengling.AuthService.{FolderName}`

**示例：**
- `Fengling.AuthService.Controllers`
- `Fengling.AuthService.ViewModels`
- `Fengling.AuthService.Configuration`

### 类命名

**控制器：**
- 继承自 `Controller` 或 `ControllerBase`
- 使用 `[ControllerName]` 属性或路由属性

**视图模型：**
- 使用 `ViewModel` 后缀
- 包含输入属性和验证属性

## 添加新代码的位置

### 新增功能模块

**场景：** 添加新的业务功能

**代码位置：** `src/Controllers/`
- 创建新的 Controller 文件

**视图位置：** `src/Views/{Feature}/`

**视图模型位置：** `src/ViewModels/`

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

### 新增 API 端点

**场景：** 添加新的 REST API

**代码位置：** `src/Controllers/`
- 在现有 Controller 中添加 Action
- 或创建新的 Controller（继承 ControllerBase）

### 新增视图页面

**场景：** 添加新的 Razor 页面

**视图位置：** `src/Views/{ControllerName}/{Action}.cshtml`

**视图模型位置：** `src/ViewModels/{Feature}ViewModel.cs`

### 新增配置

**场景：** 添加新的服务配置

**配置位置：** `src/Configuration/`
- 创建静态配置类
- 在 Program.cs 中调用

## 特殊目录

### k8s/

- 用途：Kubernetes 部署配置
- 生成：手动维护
- 提交：是的

### .gitea/workflows/

- 用途：Gitea CI/CD 流水线配置
- 生成：手动维护
- 提交：是的

### Properties/

- 用途：开发环境启动配置
- 生成：IDE 生成
- 提交：是的（launchSettings.json 不含敏感信息）

### Views/Shared/

- 用途：共享视图组件
- 包含：_Layout.cshtml 主布局

---

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