chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00
parent 4b4980820f
commit a4b6c5011e
58 changed files with 19353 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/Yggdrasil协议API.md
+++ b/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/Yggdrasil协议API.md
@@ -0,0 +1,386 @@
+# Yggdrasil协议API
+
+<cite>
+**本文档引用的文件**   
+- [routes.go](file://internal/handler/routes.go)
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go)
+- [yggdrasil_repository.go](file://internal/repository/yggdrasil_repository.go)
+- [yggdrasil.go](file://internal/model/yggdrasil.go)
+- [token.go](file://internal/model/token.go)
+- [user_service.go](file://internal/service/user_service.go)
+- [profile_service.go](file://internal/service/profile_service.go)
+- [profile_repository.go](file://internal/repository/profile_repository.go)
+- [jwt.go](file://pkg/auth/jwt.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [Yggdrasil路由结构](#yggdrasil路由结构)
+3. [认证服务API](#认证服务api)
+4. [会话服务API](#会话服务api)
+5. [档案服务API](#档案服务api)
+6. [与Minecraft客户端交互流程](#与minecraft客户端交互流程)
+7. [内部用户系统集成](#内部用户系统集成)
+8. [错误处理](#错误处理)
+9. [元数据与证书](#元数据与证书)
+
+## 简介
+Yggdrasil协议是Minecraft客户端认证的核心接口，本系统实现了完整的Yggdrasil协议集成，为Minecraft玩家提供认证、会话管理和档案查询服务。该实现通过`/yggdrasil`路由组暴露标准API端点，与Minecraft客户端无缝对接，同时将Yggdrasil请求映射到系统的内部用户体系。
+
+**Section sources**
+- [routes.go](file://internal/handler/routes.go#L87-L111)
+
+## Yggdrasil路由结构
+系统在`/api/v1/yggdrasil`路径下提供了完整的Yggdrasil协议支持，包含三个主要子路由组：`authserver`、`sessionserver`和`profiles`，分别处理认证、会话和档案相关请求。
+
+```mermaid
+graph TB
+Yggdrasil[Yggdrasil根路由 /yggdrasil]
+subgraph AuthServer
+Authenticate[POST /authserver/authenticate]
+Validate[POST /authserver/validate]
+Refresh[POST /authserver/refresh]
+Invalidate[POST /authserver/invalidate]
+SignOut[POST /authserver/signout]
+end
+subgraph SessionServer
+GetProfile[GET /sessionserver/session/minecraft/profile/:uuid]
+JoinServer[POST /sessionserver/session/minecraft/join]
+HasJoined[GET /sessionserver/session/minecraft/hasJoined]
+end
+subgraph Profiles
+GetProfilesByName[POST /api/profiles/minecraft]
+end
+Yggdrasil --> Authenticate
+Yggdrasil --> Validate
+Yggdrasil --> Refresh
+Yggdrasil --> Invalidate
+Yggdrasil --> SignOut
+Yggdrasil --> GetProfile
+Yggdrasil --> JoinServer
+Yggdrasil --> HasJoined
+Yggdrasil --> GetProfilesByName
+```
+
+**Diagram sources **
+- [routes.go](file://internal/handler/routes.go#L87-L111)
+
+**Section sources**
+- [routes.go](file://internal/handler/routes.go#L87-L111)
+
+## 认证服务API
+认证服务API位于`/yggdrasil/authserver`路径下，提供用户认证和令牌管理功能。
+
+### authenticate
+用户认证端点，用于验证用户凭据并获取访问令牌。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/authserver/authenticate`
+- **请求体**:
+  ```json
+  {
+    "username": "用户邮箱或用户名",
+    "password": "密码",
+    "clientToken": "客户端令牌"
+  }
+  ```
+- **响应**:
+  - 200: 返回包含`accessToken`、`availableProfiles`和`selectedProfile`的认证响应
+  - 403: 认证失败
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L156-L246)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L204-L209)
+
+### validate
+验证访问令牌的有效性。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/authserver/validate`
+- **请求体**:
+  ```json
+  {
+    "accessToken": "访问令牌"
+  }
+  ```
+- **响应**:
+  - 204: 令牌有效
+  - 403: 令牌无效
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L248-L267)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L260-L261)
+
+### refresh
+刷新访问令牌，延长会话有效期。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/authserver/refresh`
+- **请求体**:
+  ```json
+  {
+    "accessToken": "当前访问令牌",
+    "clientToken": "客户端令牌",
+    "selectedProfile": "选定的档案"
+  }
+  ```
+- **响应**:
+  - 200: 返回新的`accessToken`和`selectedProfile`
+  - 400: 刷新失败
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L269-L361)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L341-L351)
+
+### invalidate
+使访问令牌失效。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/authserver/invalidate`
+- **请求体**:
+  ```json
+  {
+    "accessToken": "要使失效的令牌"
+  }
+  ```
+- **响应**:
+  - 204: 成功使令牌失效
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L363-L378)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L375)
+
+### signout
+用户登出，使该用户的所有令牌失效。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/authserver/signout`
+- **请求体**:
+  ```json
+  {
+    "username": "用户邮箱",
+    "password": "密码"
+  }
+  ```
+- **响应**:
+  - 204: 登出成功
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L380-L425)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L422)
+
+## 会话服务API
+会话服务API位于`/yggdrasil/sessionserver`路径下，管理玩家与服务器的会话。
+
+### JoinServer
+记录玩家加入服务器的会话信息。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/sessionserver/session/minecraft/join`
+- **请求体**:
+  ```json
+  {
+    "accessToken": "访问令牌",
+    "selectedProfile": "选定的档案UUID",
+    "serverId": "服务器ID"
+  }
+  ```
+- **响应**:
+  - 204: 加入成功
+  - 500: 加入失败
+
+```mermaid
+sequenceDiagram
+participant Client as "Minecraft客户端"
+participant SessionServer as "会话服务"
+participant Redis as "Redis存储"
+Client->>SessionServer : POST /join
+SessionServer->>SessionServer : 验证accessToken
+SessionServer->>SessionServer : 验证selectedProfile
+SessionServer->>Redis : 存储会话数据
+Redis-->>SessionServer : 存储成功
+SessionServer-->>Client : 204 No Content
+```
+
+**Diagram sources **
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)
+
+### HasJoinedServer
+验证玩家是否已加入指定服务器。
+
+- **方法**: GET
+- **路径**: `/yggdrasil/sessionserver/session/minecraft/hasJoined`
+- **查询参数**:
+  - `serverId`: 服务器ID
+  - `username`: 用户名
+  - `ip`: IP地址（可选）
+- **响应**:
+  - 200: 返回玩家档案信息
+  - 204: 未加入或验证失败
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L498-L552)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L165-L201)
+
+## 档案服务API
+档案服务API提供玩家档案查询功能。
+
+### GetProfileByUUID
+根据UUID获取玩家档案。
+
+- **方法**: GET
+- **路径**: `/yggdrasil/sessionserver/session/minecraft/profile/:uuid`
+- **响应**:
+  - 200: 返回玩家档案信息
+  - 500: 获取失败
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L427-L447)
+- [profile_service.go](file://internal/service/profile_service.go#L71-L80)
+
+### GetProfilesByName
+根据用户名批量获取玩家档案。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/api/profiles/minecraft`
+- **请求体**: 用户名数组
+  ```json
+  ["player1", "player2"]
+  ```
+- **响应**: 返回匹配的档案列表
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L554-L587)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L129-L137)
+
+## 与Minecraft客户端交互流程
+Minecraft客户端与Yggdrasil服务的完整交互流程如下：
+
+```mermaid
+sequenceDiagram
+participant Client as "Minecraft客户端"
+participant AuthServer as "认证服务"
+participant SessionServer as "会话服务"
+participant ProfileServer as "档案服务"
+Client->>AuthServer : authenticate(邮箱/用户名, 密码)
+AuthServer-->>Client : accessToken, availableProfiles
+Client->>SessionServer : join(serverId, accessToken, selectedProfile)
+SessionServer-->>Client : 204
+Client->>ProfileServer : hasJoined(serverId, username)
+ProfileServer-->>Client : 玩家档案
+Client->>ProfileServer : getProfile(uuid)
+ProfileServer-->>Client : 档案详情
+```
+
+**Diagram sources **
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go)
+
+## 内部用户系统集成
+Yggdrasil实现与系统内部用户体系的集成通过以下方式完成：
+
+### 用户映射
+系统通过`Yggdrasil`模型将Yggdrasil协议的密码认证与内部用户ID关联。当用户注册时，系统自动生成一个16位随机密码与用户ID绑定。
+
+```mermaid
+classDiagram
+class User {
+int64 ID
+string Username
+string Email
+string Password
+}
+class Yggdrasil {
+int64 ID
+string Password
+}
+User --> Yggdrasil : "1对1关联"
+```
+
+**Diagram sources **
+- [yggdrasil.go](file://internal/model/yggdrasil.go)
+- [user_service.go](file://internal/service/user_service.go#L13-L67)
+
+**Section sources**
+- [yggdrasil.go](file://internal/model/yggdrasil.go#L13-L38)
+- [user_service.go](file://internal/service/user_service.go#L13-L67)
+
+### 令牌管理
+系统使用`Token`模型管理访问令牌，将`accessToken`与`userID`、`profileId`关联，实现会话状态管理。
+
+```mermaid
+classDiagram
+class Token {
+string AccessToken
+int64 UserID
+string ProfileId
+bool Usable
+}
+class Profile {
+string UUID
+int64 UserID
+string Name
+}
+Token --> Profile : "关联档案"
+Token --> User : "关联用户"
+```
+
+**Diagram sources **
+- [token.go](file://internal/model/token.go)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)
+
+**Section sources**
+- [token.go](file://internal/model/token.go)
+- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)
+
+## 错误处理
+系统实现了标准化的错误处理机制，所有Yggdrasil端点返回一致的错误响应格式。
+
+### 常见错误代码
+| HTTP状态码 | 错误类型 | 描述 |
+|-----------|---------|------|
+| 400 | Bad Request | 请求格式无效 |
+| 403 | Forbidden | 认证失败或权限不足 |
+| 404 | Not Found | 资源未找到 |
+| 500 | Internal Server Error | 服务器内部错误 |
+
+### 错误响应示例
+```json
+{
+  "error": "密码错误"
+}
+```
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L19-L57)
+
+## 元数据与证书
+系统提供元数据和玩家证书服务，支持Minecraft客户端的高级功能。
+
+### GetMetaData
+获取服务元数据。
+
+- **方法**: GET
+- **路径**: `/yggdrasil`
+- **响应**: 包含实现信息、链接和功能标志
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L589-L615)
+
+### GetPlayerCertificates
+获取玩家证书。
+
+- **方法**: POST
+- **路径**: `/yggdrasil/minecraftservices/player/certificates`
+- **认证**: Bearer Token
+- **响应**: 包含玩家公钥证书
+
+**Section sources**
+- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L618-L667)
+- [profile_service.go](file://internal/service/profile_service.go#L44-L48)