# 系统API

<cite>
**本文引用的文件**
- [internal/handler/swagger.go](file://internal/handler/swagger.go)
- [internal/handler/routes.go](file://internal/handler/routes.go)
- [internal/model/system_config.go](file://internal/model/system_config.go)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go)
- [README.md](file://README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件聚焦于系统相关的两个关键API：健康检查与系统配置获取。前者用于服务可用性监控，后者用于获取公开的全局配置项，帮助前端与运维侧快速了解站点状态与功能开关。文档将结合路由注册、处理器实现、模型与仓库层，给出端点定义、响应结构、调用流程与最佳实践，并说明Swagger文档的访问方式。

## 项目结构
系统API位于内部处理层（handler），通过路由注册挂载至Gin引擎；系统配置模型与仓库层负责持久化与查询；Swagger文档通过中间件暴露静态页面与健康检查端点。

```mermaid
graph TB
subgraph "路由与处理器"
Routes["routes.go<br/>注册 /api/v1/system/config"]
Swagger["swagger.go<br/>注册 /health 与 /swagger/*any"]
Health["HealthCheck()<br/>返回 {status,message}"]
SysCfg["GetSystemConfig()<br/>返回公开配置"]
end
subgraph "模型与仓库"
ModelSC["SystemConfig 模型<br/>公开字段: site_name, registration_enabled, ..."]
RepoSC["system_config_repository<br/>GetPublicSystemConfigs()"]
end
Routes --> SysCfg
Swagger --> Health
SysCfg --> RepoSC
RepoSC --> ModelSC
```

图表来源
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)

章节来源
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)

## 核心组件
- 健康检查端点
  - 路径：/health
  - 方法：GET
  - 作用：返回服务运行状态，便于Kubernetes、负载均衡器或监控系统进行存活探针与就绪探针
  - 响应：包含状态与消息字段的对象
- 系统配置端点
  - 路径：/api/v1/system/config
  - 方法：GET
  - 作用：返回公开的系统配置集合，供前端渲染站点标题、描述、注册开关、用户限制等
  - 当前实现：返回硬编码的公开配置；后续可替换为从数据库读取

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)

## 架构总览
系统API的调用链路如下：客户端请求 -> Gin路由 -> 处理器函数 -> 仓库层（当前为内存返回，未来可改为数据库查询）-> 返回响应。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "Gin路由"
participant H as "处理器"
participant M as "模型/仓库(当前为内存)"
participant S as "Swagger/健康检查"
C->>R : GET /health
R->>S : HealthCheck()
S-->>C : {status,message}
C->>R : GET /api/v1/system/config
R->>H : GetSystemConfig()
H->>M : 当前返回硬编码公开配置
M-->>H : 公开配置对象
H-->>C : 成功响应
```

图表来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)

## 详细组件分析

### 健康检查端点 /health
- 注册位置：Swagger设置函数中注册了 /health 路由
- 处理逻辑：返回固定的成功状态与消息
- 响应结构：包含状态与消息字段的对象
- 用途：作为Kubernetes探针、负载均衡器健康检查、CI流水线可用性检测

```mermaid
flowchart TD
Start(["请求进入 /health"]) --> Check["调用 HealthCheck()"]
Check --> BuildResp["构建响应对象<br/>包含 status 与 message"]
BuildResp --> Return["返回 200 OK"]
```

图表来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)

### 系统配置端点 /api/v1/system/config
- 注册位置：v1路由组下的 /system/config
- 处理逻辑：当前实现返回硬编码的公开配置；注释提示后续应从数据库读取
- 响应结构：当前返回包含站点名称、描述、注册开关、每用户材质与档案上限等字段的对象
- 模型与仓库：
  - 模型定义了公开配置的结构（站点名称、描述、注册开关、维护模式、公告等）
  - 仓库提供了获取公开配置的方法（按 is_public 过滤）

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "Gin路由"
participant H as "GetSystemConfig()"
participant Repo as "GetPublicSystemConfigs()"
participant DB as "数据库"
C->>R : GET /api/v1/system/config
R->>H : 调用处理器
alt 当前实现为内存返回
H-->>C : 返回硬编码公开配置
else 后续实现为数据库读取
H->>Repo : 查询 is_public=true 的配置
Repo->>DB : 执行查询
DB-->>Repo : 返回配置列表
Repo-->>H : 配置对象
H-->>C : 返回公开配置
end
```

图表来源
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)

章节来源
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)

### Swagger 文档访问
- 路由：/swagger/*any
- 作用：提供交互式API文档，便于开发者与测试人员查阅接口定义、参数与示例
- 项目说明：README中明确给出了Swagger文档地址与健康检查地址

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
- [README.md](file://README.md#L149-L153)

## 依赖分析
- 路由注册依赖：
  - Swagger设置函数负责注册 /health 与 /swagger/*any
  - v1路由组负责注册 /api/v1/system/config
- 处理器依赖：
  - GetSystemConfig 当前为内存返回；若改为数据库读取，则依赖仓库层的公开配置查询
- 模型与仓库：
  - SystemConfig 模型定义公开配置字段
  - 仓库层提供按 is_public 过滤的查询方法

```mermaid
graph LR
Swagger["swagger.go"] --> Routes["routes.go"]
Routes --> HandlerSys["GetSystemConfig()"]
HandlerSys --> Repo["system_config_repository.go"]
Repo --> Model["system_config.go"]
```

图表来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [internal/repository/system_config_repository.go](file://internal/repository/system_config_repository.go#L25-L34)
- [internal/model/system_config.go](file://internal/model/system_config.go#L17-L41)

## 性能考虑
- 健康检查：纯内存返回，延迟极低，适合高频探针
- 系统配置：
  - 当前为内存返回，避免数据库开销
  - 若切换为数据库查询，建议：
    - 对公开配置建立索引（如按 is_public 过滤）
    - 引入缓存层（如Redis）短期缓存公开配置，减少数据库压力
    - 控制响应大小，仅返回必要字段
- Swagger文档：静态文件托管，对性能影响可忽略

## 故障排查指南
- 健康检查失败
  - 检查服务进程是否正常运行
  - 确认 /health 路由已注册（Swagger设置函数）
  - 使用浏览器或curl访问 /health，观察返回状态与内容
- 系统配置端点异常
  - 当前实现为内存返回，若返回异常，检查处理器逻辑
  - 若切换为数据库查询，检查数据库连接、表是否存在、字段是否正确
- Swagger文档无法访问
  - 确认 /swagger/*any 路由已注册
  - 访问 /swagger/index.html 查看文档
  - 若文档为空，检查是否已生成Swagger文档

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L44)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [README.md](file://README.md#L149-L153)

## 结论
- /health 提供轻量级服务可用性检查，适合作为探针与监控指标
- /api/v1/system/config 当前返回硬编码公开配置，满足前端基础展示需求；后续可无缝替换为数据库读取，配合缓存与索引提升性能
- Swagger文档提供便捷的接口浏览与调试入口，有助于开发与运维协作

## 附录

### API定义与响应示例

- 健康检查
  - 方法：GET
  - 路径：/health
  - 响应示例（结构示意）：
    - status: 字符串，表示服务状态
    - message: 字符串，简要描述
  - 用途：存活/就绪探针、CI流水线可用性检测

- 系统配置
  - 方法：GET
  - 路径：/api/v1/system/config
  - 响应示例（结构示意）：
    - site_name: 字符串，站点名称
    - site_description: 字符串，站点描述
    - registration_enabled: 布尔值，是否允许注册
    - max_textures_per_user: 整数，每用户最大材质数
    - max_profiles_per_user: 整数，每用户最大档案数
  - 用途：前端渲染站点标题、描述、注册开关、用户限制等

- Swagger文档
  - 访问路径：/swagger/index.html
  - 用途：查看与调试所有API接口

章节来源
- [internal/handler/swagger.go](file://internal/handler/swagger.go#L41-L62)
- [internal/handler/routes.go](file://internal/handler/routes.go#L112-L139)
- [README.md](file://README.md#L149-L153)