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参考/档案API/创建与列表.md
+++ b/.qoder/repowiki/zh/content/API参考/档案API/创建与列表.md
@@ -0,0 +1,398 @@
+# 创建与列表
+
+<cite>
+**本文引用的文件**
+- [routes.go](file://internal/handler/routes.go)
+- [profile_handler.go](file://internal/handler/profile_handler.go)
+- [profile_service.go](file://internal/service/profile_service.go)
+- [profile_repository.go](file://internal/repository/profile_repository.go)
+- [profile.go](file://internal/model/profile.go)
+- [common.go](file://internal/types/common.go)
+- [response.go](file://internal/model/response.go)
+- [texture.go](file://internal/model/texture.go)
+- [profile_handler_test.go](file://internal/handler/profile_handler_test.go)
+- [common_test.go](file://internal/types/common_test.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向开发者与集成方，系统性梳理“创建与列表”相关接口的实现与使用规范，重点覆盖：
+- 通过 POST /api/v1/profile/ 创建新档案，请求体中必须包含 1-16 字符的角色名；可选皮肤ID与披风ID。
+- 系统在创建时自动将该档案设为用户活跃档案，并将该用户其他档案置为非活跃。
+- 通过 GET /api/v1/profile/ 获取当前用户所有档案列表，响应包含档案UUID、名称、活跃状态、关联材质等信息。
+- 结合 profile_service.go 中的 CheckProfileLimit 逻辑说明用户档案数量上限（默认5个）的控制机制。
+
+## 项目结构
+围绕档案模块的路由、处理器、服务层、仓储层与模型如下所示：
+
+```mermaid
+graph TB
+subgraph "路由层"
+R["routes.go<br/>注册 /api/v1/profile/* 路由"]
+end
+subgraph "处理器层"
+H["profile_handler.go<br/>CreateProfile / GetProfiles / SetActiveProfile 等"]
+end
+subgraph "服务层"
+S["profile_service.go<br/>CreateProfile / GetUserProfiles / CheckProfileLimit 等"]
+end
+subgraph "仓储层"
+RP["profile_repository.go<br/>CreateProfile / FindProfilesByUserID / SetActiveProfile 等"]
+end
+subgraph "模型与类型"
+M["profile.go<br/>Profile / ProfileResponse / ProfileTexturesData 等"]
+T["texture.go<br/>Texture 类型"]
+C["common.go<br/>CreateProfileRequest / ProfileInfo / UpdateProfileRequest 等"]
+RESP["response.go<br/>统一响应结构"]
+end
+R --> H
+H --> S
+S --> RP
+RP --> M
+S --> M
+H --> RESP
+H --> C
+M --> T
+```
+
+图表来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L15-L399)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L118)
+- [profile.go](file://internal/model/profile.go#L7-L57)
+- [texture.go](file://internal/model/texture.go#L16-L31)
+- [common.go](file://internal/types/common.go#L81-L166)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+章节来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+
+## 核心组件
+- 路由注册：在路由层为档案模块注册了认证中间件保护的 POST / GET / PUT / DELETE / POST activate 等路径。
+- 处理器：负责解析请求、鉴权、调用服务层并返回统一响应。
+- 服务层：封装业务规则，如创建档案时的用户存在性校验、角色名唯一性校验、活跃状态设置、档案数量上限检查等。
+- 仓储层：封装数据库访问，如创建档案、查询用户档案列表、批量设置活跃状态等。
+- 模型与类型：定义档案实体、响应结构、请求体结构以及材质类型。
+
+章节来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L15-L399)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L118)
+- [profile.go](file://internal/model/profile.go#L7-L57)
+- [common.go](file://internal/types/common.go#L81-L166)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+## 架构总览
+下图展示从客户端到数据库的调用链路与关键步骤。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Router as "路由层(routes.go)"
+participant Handler as "处理器(profile_handler.go)"
+participant Service as "服务层(profile_service.go)"
+participant Repo as "仓储层(profile_repository.go)"
+participant DB as "数据库"
+Client->>Router : "POST /api/v1/profile"
+Router->>Handler : "CreateProfile"
+Handler->>Handler : "解析请求体(CreateProfileRequest)"
+Handler->>Handler : "读取用户ID(鉴权)"
+Handler->>Service : "CheckProfileLimit(userID, 5)"
+Service->>Repo : "CountProfilesByUserID(userID)"
+Repo->>DB : "统计数量"
+DB-->>Repo : "count"
+Repo-->>Service : "返回count"
+Service-->>Handler : "通过/错误"
+alt "未达上限"
+Handler->>Service : "CreateProfile(userID, name)"
+Service->>Repo : "FindUserByID(userID)"
+Repo->>DB : "查询用户"
+DB-->>Repo : "用户"
+Repo-->>Service : "返回用户"
+Service->>Repo : "FindProfileByName(name)"
+Repo->>DB : "查询角色名"
+DB-->>Repo : "结果"
+Service->>Repo : "CreateProfile(Profile)"
+Repo->>DB : "插入档案"
+Service->>Repo : "SetActiveProfile(uuid, userID)"
+Repo->>DB : "事务 : 将其他档案置为非活跃<br/>并将当前档案置为活跃"
+DB-->>Repo : "提交"
+Repo-->>Service : "返回Profile"
+Service-->>Handler : "返回Profile"
+Handler-->>Client : "200 成功(统一响应)"
+else "已达上限"
+Handler-->>Client : "400 参数错误(已达上限)"
+end
+```
+
+图表来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L69)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L109)
+
+## 详细组件分析
+
+### POST /api/v1/profile/ 创建档案
+- 功能概述：创建新的Minecraft角色档案，系统自动生成UUID并默认设为活跃状态，同时将该用户其他档案置为非活跃。
+- 请求体
+  - 必填：name（字符串，1-16字符）
+  - 可选：skin_id（整数，材质ID）、cape_id（整数，材质ID）
+- 响应
+  - 成功：返回统一响应结构，data为 ProfileInfo 对象，包含 uuid、user_id、name、skin_id、cape_id、is_active、last_used_at、created_at、updated_at。
+  - 失败：根据错误类型返回 400（参数错误/已达上限）、401（未授权）、500（服务器错误）。
+- 关键业务逻辑
+  - 用户存在性与状态校验
+  - 角色名唯一性校验
+  - 档案数量上限检查（默认5个）
+  - 创建成功后自动设置活跃状态，并将其他档案置为非活跃
+- 请求示例
+  - 方法：POST
+  - URL：/api/v1/profile
+  - 请求头：Authorization: Bearer <token>
+  - 请求体：
+    - name: "PlayerName"
+    - skin_id: 123（可选）
+    - cape_id: 456（可选）
+- 响应示例
+  - 成功：
+    - code: 200
+    - message: "操作成功"
+    - data: {
+        uuid: "550e8400-e29b-41d4-a716-446655440000"
+        user_id: 1
+        name: "PlayerName"
+        skin_id: 123
+        cape_id: 456
+        is_active: true
+        last_used_at: "2025-10-01T12:00:00Z"
+        created_at: "2025-10-01T10:00:00Z"
+        updated_at: "2025-10-01T10:00:00Z"
+      }
+  - 达到上限：
+    - code: 400
+    - message: "已达到档案数量上限（5个）"
+
+```mermaid
+flowchart TD
+Start(["进入 CreateProfile"]) --> Bind["绑定请求体(CreateProfileRequest)"]
+Bind --> CheckAuth{"鉴权通过？"}
+CheckAuth --> |否| Resp401["返回 401 未授权"]
+CheckAuth --> |是| Limit["CheckProfileLimit(userID, 5)"]
+Limit --> Over{"超过上限？"}
+Over --> |是| Resp400["返回 400 已达上限"]
+Over --> |否| Create["CreateProfile(userID, name)"]
+Create --> Exists{"用户存在且状态正常？"}
+Exists --> |否| Resp500["返回 500 用户异常"]
+Exists --> |是| Unique{"角色名唯一？"}
+Unique --> |否| Resp400["返回 400 角色名冲突"]
+Unique --> |是| Insert["插入档案记录"]
+Insert --> SetActive["SetActiveProfile(uuid, userID)<br/>将其他档案置为非活跃，当前置为活跃"]
+SetActive --> Done(["返回 200 成功"])
+```
+
+图表来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L69)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L109)
+
+章节来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L69)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L109)
+- [common.go](file://internal/types/common.go#L81-L90)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+### GET /api/v1/profile/ 获取档案列表
+- 功能概述：返回当前用户的所有档案列表，包含每个档案的UUID、名称、活跃状态、关联材质等。
+- 请求
+  - 方法：GET
+  - URL：/api/v1/profile
+  - 请求头：Authorization: Bearer <token>
+- 响应
+  - 成功：返回统一响应结构，data为 ProfileInfo 数组。
+  - 失败：401（未授权）、500（服务器错误）。
+- 关键逻辑
+  - 服务层查询用户所有档案并预加载关联材质（Skin/Cape）
+  - 处理器将模型转换为 ProfileInfo 并返回
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Router as "路由层(routes.go)"
+participant Handler as "处理器(profile_handler.go)"
+participant Service as "服务层(profile_service.go)"
+participant Repo as "仓储层(profile_repository.go)"
+participant DB as "数据库"
+Client->>Router : "GET /api/v1/profile"
+Router->>Handler : "GetProfiles"
+Handler->>Handler : "读取用户ID(鉴权)"
+Handler->>Service : "GetUserProfiles(userID)"
+Service->>Repo : "FindProfilesByUserID(userID)"
+Repo->>DB : "查询档案列表并预加载 Skin/Cape"
+DB-->>Repo : "返回 profiles"
+Repo-->>Service : "返回 profiles"
+Service-->>Handler : "返回 profiles"
+Handler->>Handler : "转换为 ProfileInfo 列表"
+Handler-->>Client : "200 成功(统一响应)"
+```
+
+图表来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L95-L151)
+- [profile_service.go](file://internal/service/profile_service.go#L83-L90)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L44-L57)
+
+章节来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L95-L151)
+- [profile_service.go](file://internal/service/profile_service.go#L83-L90)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L44-L57)
+- [profile.go](file://internal/model/profile.go#L7-L24)
+- [texture.go](file://internal/model/texture.go#L16-L31)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+### 档案数量上限与活跃状态控制
+- 档案数量上限
+  - 默认上限为5个，来源于系统配置与处理器中的硬编码值。
+  - 服务层提供 CheckProfileLimit(userID, maxProfiles) 进行检查。
+- 活跃状态控制
+  - 创建新档案时，服务层会将该档案设为活跃，并通过仓储层的事务将该用户其他档案置为非活跃。
+  - 提供 SetActiveProfile 接口用于手动切换活跃档案。
+
+```mermaid
+flowchart TD
+A["创建/切换活跃"] --> B["CheckProfileLimit(userID, 5)"]
+B --> C{"未超限？"}
+C --> |是| D["CreateProfile 或 SetActiveProfile"]
+D --> E["SetActiveProfile(uuid, userID) 事务"]
+E --> F["将其他档案 is_active=false"]
+E --> G["将当前档案 is_active=true"]
+C --> |否| H["返回 400 达到上限"]
+```
+
+图表来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L52-L63)
+- [profile_service.go](file://internal/service/profile_service.go#L190-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L89-L109)
+
+章节来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L52-L63)
+- [profile_service.go](file://internal/service/profile_service.go#L190-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L89-L109)
+
+## 依赖分析
+- 路由层依赖处理器层，处理器层依赖服务层，服务层依赖仓储层，仓储层依赖数据库与模型。
+- 处理器层与服务层均依赖统一响应结构与请求/响应类型定义。
+- 档案模型与材质模型存在外键关联，查询时进行预加载以减少N+1问题。
+
+```mermaid
+graph LR
+Routes["routes.go"] --> Handler["profile_handler.go"]
+Handler --> Service["profile_service.go"]
+Service --> Repo["profile_repository.go"]
+Repo --> Model["profile.go"]
+Model --> Texture["texture.go"]
+Handler --> Types["common.go"]
+Handler --> Resp["response.go"]
+```
+
+图表来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L15-L399)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L118)
+- [profile.go](file://internal/model/profile.go#L7-L57)
+- [texture.go](file://internal/model/texture.go#L16-L31)
+- [common.go](file://internal/types/common.go#L81-L166)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+章节来源
+- [routes.go](file://internal/handler/routes.go#L63-L79)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L15-L399)
+- [profile_service.go](file://internal/service/profile_service.go#L17-L202)
+- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L118)
+- [profile.go](file://internal/model/profile.go#L7-L57)
+- [texture.go](file://internal/model/texture.go#L16-L31)
+- [common.go](file://internal/types/common.go#L81-L166)
+- [response.go](file://internal/model/response.go#L1-L86)
+
+## 性能考虑
+- 预加载关联材质：仓储层在查询用户档案列表时预加载 Skin 与 Cape，避免多次查询。
+- 事务一致性：设置活跃状态采用数据库事务，确保原子性与一致性。
+- 唯一性约束：角色名在模型层定义唯一索引，查询时可快速判定冲突。
+- 响应结构：统一响应结构便于前端处理与日志记录。
+
+[本节为通用建议，不涉及具体文件分析]
+
+## 故障排查指南
+- 400 参数错误
+  - 角色名为空或长度不在1-16范围内
+  - 已达到档案数量上限（默认5个）
+- 401 未授权
+  - 缺少或无效的认证令牌
+- 403 权限不足
+  - 操作他人档案（如更新/删除/设置活跃）
+- 404 资源不存在
+  - 档案UUID不存在
+- 500 服务器错误
+  - 数据库查询失败、事务提交失败、用户状态异常等
+
+章节来源
+- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L95-L151)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L197-L280)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L282-L339)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L341-L399)
+- [profile_handler_test.go](file://internal/handler/profile_handler_test.go#L40-L73)
+- [common_test.go](file://internal/types/common_test.go#L350-L383)
+
+## 结论
+- 创建档案接口严格遵循请求体校验与业务规则，确保角色名唯一与数量上限控制。
+- 活跃状态切换通过事务保障一致性，避免并发场景下的状态不一致。
+- 档案列表接口提供完整档案信息与关联材质，满足前端展示需求。
+- 建议在生产环境中将上限值从硬编码迁移到系统配置中心，以便动态调整。
+
+[本节为总结性内容，不涉及具体文件分析]
+
+## 附录
+
+### API 定义与数据结构
+
+- POST /api/v1/profile
+  - 请求体：CreateProfileRequest
+    - name: string (必填，1-16字符)
+    - skin_id: int64 (可选)
+    - cape_id: int64 (可选)
+  - 响应体：统一响应结构，data 为 ProfileInfo
+    - uuid: string
+    - user_id: int64
+    - name: string
+    - skin_id: int64 (可选)
+    - cape_id: int64 (可选)
+    - is_active: bool
+    - last_used_at: datetime (可选)
+    - created_at: datetime
+    - updated_at: datetime
+
+- GET /api/v1/profile
+  - 响应体：统一响应结构，data 为 ProfileInfo 数组
+
+章节来源
+- [common.go](file://internal/types/common.go#L81-L90)
+- [common.go](file://internal/types/common.go#L154-L166)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
+- [profile_handler.go](file://internal/handler/profile_handler.go#L95-L151)
+- [response.go](file://internal/model/response.go#L1-L86)