From 31f0fb4ceb64085c0f2b0aa1b31f9e3051e0e21b Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Tue, 9 Jun 2026 11:26:57 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A7=84=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/build-image.yml             |   2 +-
 .github/workflows/cleanup-prerelease-tags.yml |   2 +-
 Agents.md                                     | 459 +++++++++---------
 CLAUDE.md                                     | 267 +++++++---
 config.example.yaml                           |   2 +-
 docs/docs.go                                  | 376 ++++++++++++++
 docs/swagger.json                             | 376 ++++++++++++++
 docs/swagger.yaml                             | 231 +++++++++
 internal/apps/oauth/routers.go                |   2 +
 9 files changed, 1411 insertions(+), 306 deletions(-)

diff --git a/.github/workflows/build-image.yml b/.github/workflows/build-image.yml
index cb5b1ac9..c02dee6a 100644
--- a/.github/workflows/build-image.yml
+++ b/.github/workflows/build-image.yml
@@ -1,4 +1,4 @@
-name: Docker image build (Server)
+name: Build Image
 
 on:
   workflow_dispatch:
diff --git a/.github/workflows/cleanup-prerelease-tags.yml b/.github/workflows/cleanup-prerelease-tags.yml
index 5de62e4d..ad32e2e4 100644
--- a/.github/workflows/cleanup-prerelease-tags.yml
+++ b/.github/workflows/cleanup-prerelease-tags.yml
@@ -1,4 +1,4 @@
-name: Cleanup prerelease tags
+name: Cleanup Prerelease
 
 on:
   workflow_dispatch:
diff --git a/Agents.md b/Agents.md
index a74c1a1f..602adc4f 100644
--- a/Agents.md
+++ b/Agents.md
@@ -1,6 +1,6 @@
 # 项目开发规范
 
-> 本文档面向 AI 代理（Agent）和开发者，描述项目的目录结构、模块职责与开发规范。
+> 本文档面向 AI 代理（Agent）与开发者，描述项目的目录结构、模块职责、代码规范与开发流程。
 
 ---
 
@@ -34,9 +34,11 @@
 
 ---
 
-## 二、顶层目录结构
+## 二、项目目录结构
 
-以下是项目的顶层目录结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：
+### 2.1 顶层目录结构
+
+以下是项目的顶层目录结构及其职责：
 
 ```
 wavelet/                           # 项目根目录（模块名: github.com/Rain-kl/Wavelet）
@@ -45,7 +47,7 @@ wavelet/                           # 项目根目录（模块名: github.com/Rai
 ├── config.yaml                    # 运行时配置（不提交到 Git）
 ├── config.example.yaml            # 配置模板（需提交）
 ├── DEPLOYMENT_zh.md               # 部署说明文档（中文版）
-├── Makefile                       # 常用命令（swagger/tidy/license）
+├── Makefile                       # 常用命令（swagger/tidy/license/code-check）
 ├── docker/                        # Docker 镜像构建文件（集成/前端/后端）
 │   ├── Dockerfile                 # 标准集成镜像（前端静态导出嵌入后端）
 │   ├── Dockerfile.frontend        # 仅前端镜像（Next.js）
@@ -60,11 +62,9 @@ wavelet/                           # 项目根目录（模块名: github.com/Rai
 └── support-files/                 # 辅助文件（如 nginx 配置等）
 ```
 
----
+### 2.2 后端 `internal/` 目录结构
 
-## 三、后端 `internal/` 目录结构
-
-以下是 `internal/` 目录的结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：
+以下是 `internal/` 目录的结构及其职责：
 
 ```
 internal/
@@ -156,9 +156,7 @@ internal/
     └── ...                        # Span 创建、Exporter 配置
 ```
 
----
-
-## 四、`apps/` 模块内部文件规范
+### 2.3 `apps/` 业务模块文件规范
 
 每个业务模块（`apps/<module>/`）内部按照以下约定组织文件：
 
@@ -174,7 +172,7 @@ internal/
 > - 路由 **不在** 模块内部注册，统一在 `internal/router/router.go` 中注册。  
 > - `errs.go` 只定义字符串常量，不定义 `error` 类型值，错误通过 `response.RespondFailure(c, errMsg)` 输出。
 
-### `admin/` 子模块结构示例
+#### `admin/` 子模块结构示例：
 
 ```
 apps/admin/
@@ -193,11 +191,9 @@ apps/admin/
     └── routers.go
 ```
 
----
+### 2.4 前端 `frontend/` 目录结构
 
-## 五、前端 `frontend/` 目录结构
-
-以下是前端 `frontend/` 目录的结构, 如果需要调整请在此处同步更改：
+以下是前端 `frontend/` 目录的结构：
 
 ```
 frontend/
@@ -231,11 +227,9 @@ frontend/
 └── .env.example                   # 环境变量模板（需提交）
 ```
 
----
+### 2.5 前端 `components/common/` 通用业务组件详解
 
-## 5.1 前端 `components/common/` 通用业务组件详解
-
-`common/` 目录存放跨页面复用的业务组件，按功能域分为五个子目录。以下是每个文件的职责说明：
+`common/` 目录存放跨页面复用的业务组件，按功能域分为五个子目录：
 
 ```
 components/common/
@@ -249,7 +243,7 @@ components/common/
 │   └── users.tsx                   # UsersManager — 用户管理页面，提供分页、搜索、筛选的用户列表表格，
 │                                   #   支持在侧边抽屉查看用户详情，以及启用/禁用（封禁/解封）切换
 │
-├── docs/                           # 文档页面组件,包括法律文档（隐私政策/服务条款）和接口文档
+├── docs/                           # 文档页面组件，包括法律文档（隐私政策/服务条款）和接口文档
 │
 ├── general/                        # 通用框架组件
 │   ├── manage-pannel.tsx           # ManagePage（泛型）— 通用管理页面框架，封装"列表 + 详情面板"布局，
@@ -280,9 +274,9 @@ components/common/
 
 ---
 
-## 六、开发规范
+## 三、后端开发规范
 
-### 6.1 命名规范
+### 3.1 命名规范
 
 | 对象 | 规范 | 示例 |
 |------|------|------|
@@ -295,7 +289,7 @@ components/common/
 | 任务类型常量 | 全大写蛇形 | `CleanupUnusedUploadsTask` |
 | 配置 Key | 全小写蛇形（YAML） | `session_cookie_name`、`max_idle_conn` |
 
-### 6.2 HTTP Handler 规范
+### 3.2 HTTP Handler 规范
 
 ```go
 // Handler 函数命名：动词 + 名词（PascalCase）
@@ -317,16 +311,9 @@ func ListUsers(c *gin.Context) {
 **响应格式约定**：
 - 成功：`util.OK(data)` 或 `util.OKNil()`  
 - 失败：`util.Err(msg)` + 对应 HTTP 状态码  
-- 通过 `response.RespondSuccess / RespondFailure` 也可（两套工具共存）
+- 通过 `response.RespondSuccess / RespondFailure` 均可（两套工具共存）
 
-### 6.4 错误处理规范
-
-- **模块内错误消息**：定义在本模块 `errs.go` 中，使用 `const` 字符串。
-- **跨模块错误消息**：定义在 `internal/common/errs.go` 或 `common/constants.go`。
-- **数据库错误**：直接 `err.Error()` 返回给响应（开发阶段），生产环境应屏蔽详情。
-- **gorm.ErrRecordNotFound**：显式判断，返回 404。
-
-### 6.5 中间件使用规范
+### 3.3 中间件使用规范
 
 | 中间件 | 位置 | 作用 |
 |--------|------|------|
@@ -337,20 +324,20 @@ func ListUsers(c *gin.Context) {
 | `oauth.LoginRequired()` | 路由组 | 登录校验 |
 | `admin.LoginAdminRequired()` | Admin 路由组 | 管理员校验 |
 
-### 6.6 配置访问规范
+### 3.4 配置访问规范
 
 - 所有配置通过 `config.Config.<Section>.<Field>` 访问（全局单例）。
 - 不允许在业务代码中使用 `os.Getenv()` 读取配置，统一通过 Viper 加载。
 - 新增配置项：先在 `config.example.yaml` 添加注释模板，再在 `internal/config/model.go` 添加结构体字段。
 
-### 6.7 数据库访问规范
+### 3.5 数据库访问规范
 
 - 直接使用 GORM：`model.DB.Where(...).Find(&result)`（适合简单查询）。
 - 通过 `db.DB(ctx)` 获取带链路追踪的 DB 实例（Admin 模块推荐）。
 - 禁止在 Handler 层直接写复杂 SQL，应封装到 `model/` 层方法或 `service/` 层。
 - 数据库迁移使用 `db/migrator/` 中的 AutoMigrate，不允许手动执行 DDL。
 
-### 6.8 异步任务规范
+### 3.6 异步任务规范
 
 **定义任务**：
 1. 在 `internal/task/constants.go` 中定义任务类型常量。
@@ -360,12 +347,15 @@ func ListUsers(c *gin.Context) {
 
 **队列优先级**（从高到低）：`webhook` > `whitelist_only` > `default`
 
-### 6.9 前端组件样式规范
+---
 
-**基础组件必须遵循系统的色彩主题系统。** 所有基于 shadcn/ui 的基础组件（Button、Dialog、Input 等）应使用组件内置的 `variant` 属性来控制样式，禁止通过 `className` 手写颜色或背景等样式。
+## 四、前端开发规范
+
+### 4.1 组件样式规范
+
+**基础组件必须遵循系统的色彩主题系统。** 所有基于 shadcn/ui 的基础组件（Button、Dialog、Input 等）应使用组件内置 of `variant` 属性来控制样式，禁止通过 `className` 手写颜色或背景等样式。
 
 **错误示例（禁止）**：
-
 ```tsx
 // ❌ 禁止通过 className 手写颜色、背景、阴影等样式
 <Button
@@ -379,7 +369,6 @@ func ListUsers(c *gin.Context) {
 ```
 
 **正确示例**：
-
 ```tsx
 // ✅ 使用 variant 属性，让组件遵循系统主题
 <Button
@@ -394,65 +383,7 @@ func ListUsers(c *gin.Context) {
 
 > **原则**：组件的视觉表现由 shadcn/ui 的 variant 系统和全局 CSS 变量统一控制，保持应用内所有页面风格一致。如现有 variant 无法满足需求，应扩展 shadcn/ui 组件的 variant 定义，而非在业务代码中硬编码颜色值。
 
-### 6.10 严格禁止事项
-
-| 禁止行为 | 说明 |
-|----------|------|
-| **禁止删除 `node_modules` 目录** | `node_modules` 为前端依赖安装目录，删除会导致项目无法运行。如需重新安装依赖，使用 `pnpm install` 覆盖更新即可，严禁执行 `rm -rf node_modules`。 |
-| **`internal/util/` 下禁止引用框架包** | `util/` 及其子包（如 `util/cap`）定位为**纯工具层**，不得 `import` 任何 HTTP / ORM / 框架包，包括但不限于 `github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions`。违反此约束会导致工具层与框架产生耦合，无法独立测试。详见 **6.11** 的建议方案。 |
-
-### 6.11 `util/` 包依赖约束与建议方案
-
-#### 约束范围
-
-`internal/util/` 及其全部子包（如 `util/cap`、`util/crypto` 等）只允许引用：
-
-- Go 标准库（`context`、`crypto`、`encoding`、`net/http` 原生包等）
-- 项目内同级别的纯工具包（`internal/config`、`internal/db`、`internal/model` 等无框架依赖的包）
-- 与框架无关的第三方库（如 `github.com/redis/go-redis`、`github.com/shopspring/decimal` 等）
-
-**严禁引用**：`github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions` 及任何 HTTP 框架 / Web 中间件相关包。
-
-#### 常见误区与建议方案
-
-| 误区 | 建议方案 |
-|------|----------|
-| 在 `util/` 中写 `gin.HandlerFunc` 形式的中间件 | 将中间件移至对应的 `apps/<module>/middleware.go`，通过**函数参数**接收 `util/` 层的核心对象（如 `*cap.Manager`） |
-| 在 `util/` 中通过 `*gin.Context` 写响应 | 只在 `util/` 中计算/校验逻辑并返回 `(result, error)`，由 `apps/` 层的 Handler 负责调用 `c.AbortWithStatusJSON` 写响应 |
-| 在 `util/` 中使用 `gorm.DB` 直接查询 | 将数据库查询封装在 `internal/model/` 层方法中，`util/` 只接收已查出的数据结构 |
-
-#### 正确示例
-
-```go
-// ✅ internal/util/cap/manager.go — 纯逻辑，无框架依赖
-func (m *Manager) VerifyToken(ctx context.Context, token, scope string) (bool, error) {
-    // 只依赖 context、标准库、redis client
-    ...
-}
-
-// ✅ internal/apps/cap/middleware.go — 框架胶水层，持有 gin 依赖
-func VerifyMiddleware(mgr *caputil.Manager, scope string, enabledFunc func() bool) gin.HandlerFunc {
-    return func(c *gin.Context) {
-        valid, err := mgr.VerifyToken(c.Request.Context(), token, scope) // 调用纯逻辑
-        if err != nil || !valid {
-            c.AbortWithStatusJSON(http.StatusUnauthorized, util.Err("验证码校验失败"))
-            return
-        }
-        c.Next()
-    }
-}
-```
-
-#### 错误示例（禁止）
-
-```go
-// ❌ internal/util/cap/middleware.go — util/ 层不应出现 gin
-import "github.com/gin-gonic/gin"
-
-func (m *Manager) VerifyMiddleware(...) gin.HandlerFunc { ... }
-```
-
-### 6.12 前端页面宽度自适应规范
+### 4.2 页面宽度自适应规范
 
 **开发或更新前端页面时，页面主容器必须支持全宽（Full Width）自适应。** 页面组件的根容器禁止硬编码固定最大宽度（如 `max-w-6xl`、`max-w-4xl` 等），而应统一使用 `w-full`。
 
@@ -482,140 +413,21 @@ export function FeatureMain() {
 }
 ```
 
----
+### 4.3 组件规范
 
-## 七、新增功能开发流程
+- 组件应按功能分类。
+- 公共业务组件放在 `components/common` 目录。
+- ShadcnUI 基础组件放在 `components/ui` 目录。
+- 自定义图标应放置在 `/components/icons/` 目录下以命名导出形式管理。常规图标统一使用 Lucide 库。
 
-新增 **异步任务** ：使用项目专属 SKILL: new-async-task 进行开发
+### 4.4 服务层架构与接口服务新建
 
-以新增 **管理员功能模块** 为例：
+服务层架构是前端与 API 交互的统一入口，基于以下原则：
+1. **关注点分离** - 每个服务类只负责一个业务领域。
+2. **统一入口** - 统一通过 `services` 对象对外导出所有服务。
+3. **类型安全** - 所有请求参数和返回响应均有明确的 TypeScript 类型定义。
 
-```
-1. 在 internal/model/ 中定义/扩展数据模型
-2. 在 db/migrator/ 中注册 AutoMigrate
-3. 在 internal/apps/admin/<module>/ 中创建：
-   - routers.go    （Handler 实现 + Swagger 注释）
-   - errs.go       （错误常量，按需）
-4. 在 internal/router/router.go 中注册路由
-5. 执行 make swagger 更新文档
-```
-
-**Handler 文件拆分规则**：
-
-逻辑简单的 CRUD 可以全部放在 `routers.go` 中。但当文件代码行数增长时，必须按以下规则拆分：
-
-| 条件                        | 拆分方式 |
-|---------------------------|----------|
-| 文件超过 **600 行**            | 必须拆分 |
-| 包含复杂业务逻辑（如外部调用、多步校验、事务处理） | 将业务逻辑拆到 `logic.go` 或 `logics.go` |
-| 同一模块有多个独立功能域              | 按功能域拆分多个文件，如 `user_routers.go`、`role_routers.go` |
-
-拆分后的模块文件结构示例：
-
-```
-apps/admin/<module>/
-├── routers.go          # 路由注册入口 + 简单 Handler（参数绑定 → 调用逻辑 → 响应）
-├── logics.go           # 复杂业务逻辑（外部调用、事务、多步处理）
-├── errs.go             # 错误常量
-└── constants.go        # 业务常量（按需）
-```
-
-**职责边界**：
-
-- `routers.go` 只做三件事：参数绑定、调用 logic 函数、返回响应。不包含任何业务判断逻辑。
-- `logics.go` 负责所有业务逻辑，接收已校验的参数，返回处理结果和错误。函数以 `PascalCase` 导出，供 `routers.go` 调用。
-
-
----
-
-## 八、前端任务管理页面
-
-任务管理 API 路由（Admin）：
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/api/v1/admin/tasks/types` | 获取可调度任务类型列表 |
-| POST | `/api/v1/admin/tasks/dispatch` | 手动下发任务 |
-| GET | `/api/v1/admin/tasks/executions` | 分页查询任务执行记录（支持 status / task_type 筛选） |
-| GET | `/api/v1/admin/tasks/executions/:id` | 查询单条任务执行详情（含完整 Log） |
-| POST | `/api/v1/admin/tasks/executions/:id/retry` | 重试失败任务（校验 Retryable && RetryCount < MaxRetry） |
-
----
-
-
-## 代码规范
-
-> [!IMPORTANT]
-> **代码开发完成后，必须在项目根目录运行 `make code-check` 进行本地代码质量与风格检查，确保前端 ESLint 没有报错和警告（`--max-warnings 0`）。**
-
-### 后端
-
-**基础检查**
-
-需要通过 CodeQL 扫描，较长的代码建议增加 Copilot 检查。
-
-**API 文档**
-
-所有接口需要写 Swagger 文档，提交前通过 make swagger 更新文档后再提交。
-
-**响应格式**
-
-```json
-# 响应数据最外层有两个字段，error_msg 和 data
-{
-    "error_msg": "",
-    "data": null
-}
-
-# 如果是非列表数据
-{
-    "error_msg": "",
-    "data": {}
-}
-
-# 如果是分页数据
-{
-    "error_msg": "",
-    "data": {
-        "total": 0,
-        "results": []
-    }
-}
-```
-
-**数据库**
-
-- 禁止使用外键，但需要保留对应字段的索引；
-- 字段如有默认值，需要与 struct 默认值相同，如 nil，0，false，空字符串等，避免初始化时未填写或漏填写导致的数据异常。
-
-### 前端
-
-**基础检查**
-
-代码需要通过 ESLint 检查和 CodeQL 扫描。
-
-**类型安全**
-
-- 禁止使用 `any` 类型，`any` 类型绕过了 TypeScript 的类型检查系统，会导致潜在的运行时错误；
-- `unknown` 是类型安全的 `any`，但必须立即进行类型断言或类型收窄；
-- `never` 类型表示永远不会发生的值类型，必须谨慎使用，并提供清晰的注释说明。
-
-**组件规范**
-
-- 组件应按功能分类
-- 公共组件放在 `components/common` 目录
-- ShadcnUI 组件放在 `components/ui` 目录
-- 自定义图标应放置在 `/components/icons/` 目录下以命名导出形式管理，对于常规的图标，我们使用 Lucide 库
-
-**服务层**
-
-服务层架构是前端与API交互的统一入口，基于以下原则：
-1. 关注点分离 - 每个服务负责一个业务领域
-2. 统一入口 - 通过services对象导出所有服务
-3. 类型安全 - 所有请求和响应有明确类型定义
-
-
-**如何新建接口服务**
+#### 如何新建接口服务：
 
 1. **创建目录结构**:
    ```
@@ -639,7 +451,7 @@ apps/admin/<module>/
    }
    ```
 
-3. **在services/index.ts注册**:
+3. **在 `services/index.ts` 注册**:
    ```typescript
    import {新服务类} from './新服务名';
 
@@ -649,11 +461,186 @@ apps/admin/<module>/
    };
    ```
 
-**使用方法**
+4. **使用方法**:
+   ```typescript
+   import services from '@/lib/services';
 
-```typescript
-import services from '@/lib/services';
+   // 调用服务方法
+   const 结果 = await services.新服务名.方法名(参数);
+   ```
 
-// 调用服务方法
-const 结果 = await services.新服务名.方法名(参数);
-```
\ No newline at end of file
+---
+
+## 五、代码质量与审查规范
+
+### 5.1 统一代码检查与提交
+
+> [!IMPORTANT]
+> **代码开发完成后，提交前必须在项目根目录运行 `make code-check` 进行本地代码质量与风格检查，确保前端 ESLint 没有报错和警告（`--max-warnings 0`）。**
+
+```bash
+# 执行根目录的检查指令
+make code-check
+```
+
+### 5.2 后端规范检查
+
+**基础检查**：
+- 后端 Go 代码需要通过 CodeQL 扫描。较复杂的逻辑建议结合 Copilot 检查。
+
+**API 文档**：
+- 所有 HTTP 接口都必须编写完整的 Swagger 注释。提交前需运行 `make swagger` 自动生成与更新接口文档。
+
+**统一响应格式**：
+```json
+// 响应数据最外层固定包含 error_msg 与 data
+{
+    "error_msg": "",
+    "data": null
+}
+
+// 示例：单条实体数据
+{
+    "error_msg": "",
+    "data": {}
+}
+
+// 示例：分页数据格式
+{
+    "error_msg": "",
+    "data": {
+        "total": 0,
+        "results": []
+    }
+}
+```
+
+### 5.3 数据库设计规范
+
+- **外键约束**：禁止在数据库物理层面使用外键（FK），但需要在对应关联字段上显式建立索引。
+- **默认值一致性**：数据库表字段的默认值必须与 Go model struct 的默认零值一致（如 `nil`, `0`, `false`, `""`），防止由于插入时漏填导致字段产生数据库异常默认值。
+
+### 5.4 前端类型安全规范
+
+- **禁止使用 `any`**：`any` 类型会绕过 TypeScript 编译期的类型检查系统，掩盖潜在的运行时错误，因此全面禁止使用。
+- **合理使用 `unknown`**：`unknown` 是类型安全的 `any`，接收到此类值后必须先进行类型断言（Type Assertion）或类型收窄（Type Narrowing）后方可使用。
+- **合理使用 `never`**：`never` 类型表示永远不会发生的值类型，必须谨慎使用，并在其使用处编写清晰的注释。
+- **静态分析检查**：前端代码必须通过 ESLint 检查和 CodeQL 静态漏洞扫描。
+
+---
+
+## 六、包依赖与安全禁止项
+
+### 6.1 严格禁止事项
+
+| 禁止行为 | 说明 |
+|----------|------|
+| **禁止删除 `node_modules` 目录** | `node_modules` 为前端依赖安装目录，删除会导致项目无法运行。如需重新安装依赖，使用 `pnpm install` 覆盖更新即可，严禁执行 `rm -rf node_modules`。 |
+| **`internal/util/` 下禁止引用框架包** | `util/` 及其子包（如 `util/cap`）定位为**纯工具层**，不得 `import` 任何 HTTP / ORM / 框架包，包括但不限于 `github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions`。违反此约束会导致工具层与框架产生耦合，无法独立测试。详见下文的建议方案。 |
+
+### 6.2 `util/` 包依赖约束与建议方案
+
+#### 约束范围：
+
+`internal/util/` 及其全部子包（如 `util/cap`、`util/crypto` 等）只允许引用：
+- Go 标准库（`context`、`crypto`、`encoding`、`net/http` 原生包等）
+- 项目内同级别的纯工具包（`internal/config`、`internal/db`、`internal/model` 等无框架依赖的包）
+- 与框架无关的第三方库（如 `github.com/redis/go-redis`、`github.com/shopspring/decimal` 等）
+
+**严禁引用**：`github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions` 及任何 HTTP 框架 / Web 中间件相关包。
+
+#### 常见误区与建议方案：
+
+| 误区 | 建议方案 |
+|------|----------|
+| 在 `util/` 中写 `gin.HandlerFunc` 形式的中间件 | 将中间件移至对应的 `apps/<module>/middleware.go`，通过**函数参数**接收 `util/` 层的核心对象（如 `*cap.Manager`） |
+| 在 `util/` 中通过 `*gin.Context` 写响应 | 只在 `util/` 中计算/校验逻辑并返回 `(result, error)`，由 `apps/` 层的 Handler 负责调用 `c.AbortWithStatusJSON` 写响应 |
+| 在 `util/` 中使用 `gorm.DB` 直接查询 | 将数据库查询封装在 `internal/model/` 层方法中，`util/` 只接收已查出的数据结构 |
+
+#### 正确示例：
+
+```go
+// ✅ internal/util/cap/manager.go — 纯逻辑，无框架依赖
+func (m *Manager) VerifyToken(ctx context.Context, token, scope string) (bool, error) {
+    // 只依赖 context、标准库、redis client
+    ...
+}
+
+// ✅ internal/apps/cap/middleware.go — 框架胶水层，持有 gin 依赖
+func VerifyMiddleware(mgr *caputil.Manager, scope string, enabledFunc func() bool) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        valid, err := mgr.VerifyToken(c.Request.Context(), token, scope) // 调用纯逻辑
+        if err != nil || !valid {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, util.Err("验证码校验失败"))
+            return
+        }
+        c.Next()
+    }
+}
+```
+
+#### 错误示例（禁止）：
+
+```go
+// ❌ internal/util/cap/middleware.go — util/ 层不应出现 gin
+import "github.com/gin-gonic/gin"
+
+func (m *Manager) VerifyMiddleware(...) gin.HandlerFunc { ... }
+```
+
+---
+
+## 七、新增功能开发流程
+
+### 7.1 新增模块开发流程
+
+新增 **异步任务**：使用项目专属 SKILL: `new-async-task` 进行开发。
+
+以新增 **管理员功能模块** 为例：
+```
+1. 在 internal/model/ 中定义/扩展数据模型
+2. 在 db/migrator/ 中注册 AutoMigrate
+3. 在 internal/apps/admin/<module>/ 中创建：
+   - routers.go    （Handler 实现 + Swagger 注释）
+   - errs.go       （错误常量，按需）
+4. 在 internal/router/router.go 中注册路由
+5. 执行 make swagger 更新文档
+```
+
+### 7.2 Handler 文件拆分规则
+
+逻辑简单的 CRUD 可以全部放在 `routers.go` 中。但当文件代码行数增长时，必须按以下规则拆分：
+
+| 条件 | 拆分方式 |
+|------|----------|
+| 文件超过 **600 行** | 必须拆分 |
+| 包含复杂业务逻辑（如外部调用、多步校验、事务处理） | 将业务逻辑拆到 `logic.go` 或 `logics.go` |
+| 同一模块有多个独立功能域 | 按功能域拆分多个文件，如 `user_routers.go`、`role_routers.go` |
+
+#### 拆分后的模块文件结构示例：
+
+```
+apps/admin/<module>/
+├── routers.go          # 路由注册入口 + 简单 Handler（参数绑定 → 调用逻辑 → 响应）
+├── logics.go           # 复杂业务逻辑（外部调用、事务、多步处理）
+├── errs.go             # 错误常量
+└── constants.go        # 业务常量（按需）
+```
+
+#### 职责边界：
+- `routers.go` 只做三件事：参数绑定、调用 logic 函数、返回响应。不包含任何业务判断逻辑。
+- `logics.go` 负责所有业务逻辑，接收已校验的参数，返回处理结果和错误。函数以 `PascalCase` 导出，供 `routers.go` 调用。
+
+---
+
+## 八、后端任务管理 API 接口
+
+任务管理 API 路由（Admin）：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/admin/tasks/types` | 获取可调度任务类型列表 |
+| POST | `/api/v1/admin/tasks/dispatch` | 手动下发任务 |
+| GET | `/api/v1/admin/tasks/executions` | 分页查询任务执行记录（支持 status / task_type 筛选） |
+| GET | `/api/v1/admin/tasks/executions/:id` | 查询单条任务执行详情（含完整 Log） |
+| POST | `/api/v1/admin/tasks/executions/:id/retry` | 重试失败任务（校验 Retryable && RetryCount < MaxRetry） |
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 677fccaa..55085d3a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # 项目开发规范
 
-> 本文档面向 AI 代理（Agent）和开发者，描述项目的目录结构、模块职责与开发规范。
+> 本文档面向 AI 代理（Agent）与开发者，描述项目的目录结构、模块职责、代码规范与开发流程。
 
 ---
 
@@ -34,9 +34,11 @@
 
 ---
 
-## 二、顶层目录结构
+## 二、项目目录结构
 
-以下是项目的顶层目录结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：
+### 2.1 顶层目录结构
+
+以下是项目的顶层目录结构及其职责：
 
 ```
 wavelet/                           # 项目根目录（模块名: github.com/Rain-kl/Wavelet）
@@ -45,7 +47,7 @@ wavelet/                           # 项目根目录（模块名: github.com/Rai
 ├── config.yaml                    # 运行时配置（不提交到 Git）
 ├── config.example.yaml            # 配置模板（需提交）
 ├── DEPLOYMENT_zh.md               # 部署说明文档（中文版）
-├── Makefile                       # 常用命令（swagger/tidy/license）
+├── Makefile                       # 常用命令（swagger/tidy/license/code-check）
 ├── docker/                        # Docker 镜像构建文件（集成/前端/后端）
 │   ├── Dockerfile                 # 标准集成镜像（前端静态导出嵌入后端）
 │   ├── Dockerfile.frontend        # 仅前端镜像（Next.js）
@@ -60,11 +62,9 @@ wavelet/                           # 项目根目录（模块名: github.com/Rai
 └── support-files/                 # 辅助文件（如 nginx 配置等）
 ```
 
----
+### 2.2 后端 `internal/` 目录结构
 
-## 三、后端 `internal/` 目录结构
-
-以下是 `internal/` 目录的结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：
+以下是 `internal/` 目录的结构及其职责：
 
 ```
 internal/
@@ -156,9 +156,7 @@ internal/
     └── ...                        # Span 创建、Exporter 配置
 ```
 
----
-
-## 四、`apps/` 模块内部文件规范
+### 2.3 `apps/` 业务模块文件规范
 
 每个业务模块（`apps/<module>/`）内部按照以下约定组织文件：
 
@@ -170,11 +168,11 @@ internal/
 | `errs.go` | 本模块专属错误消息字符串常量（`const`）|
 | `constants.go` | 本模块专属业务常量（非错误）|
 
-> **规则**：  
-> - 路由 **不在** 模块内部注册，统一在 `internal/router/router.go` 中注册。  
+> **规则**：
+> - 路由 **不在** 模块内部注册，统一在 `internal/router/router.go` 中注册。
 > - `errs.go` 只定义字符串常量，不定义 `error` 类型值，错误通过 `response.RespondFailure(c, errMsg)` 输出。
 
-### `admin/` 子模块结构示例
+#### `admin/` 子模块结构示例：
 
 ```
 apps/admin/
@@ -193,11 +191,9 @@ apps/admin/
     └── routers.go
 ```
 
----
+### 2.4 前端 `frontend/` 目录结构
 
-## 五、前端 `frontend/` 目录结构
-
-以下是前端 `frontend/` 目录的结构, 如果需要调整请在此处同步更改：
+以下是前端 `frontend/` 目录的结构：
 
 ```
 frontend/
@@ -231,11 +227,9 @@ frontend/
 └── .env.example                   # 环境变量模板（需提交）
 ```
 
----
+### 2.5 前端 `components/common/` 通用业务组件详解
 
-## 5.1 前端 `components/common/` 通用业务组件详解
-
-`common/` 目录存放跨页面复用的业务组件，按功能域分为五个子目录。以下是每个文件的职责说明：
+`common/` 目录存放跨页面复用的业务组件，按功能域分为五个子目录：
 
 ```
 components/common/
@@ -249,7 +243,7 @@ components/common/
 │   └── users.tsx                   # UsersManager — 用户管理页面，提供分页、搜索、筛选的用户列表表格，
 │                                   #   支持在侧边抽屉查看用户详情，以及启用/禁用（封禁/解封）切换
 │
-├── docs/                           # 文档页面组件,包括法律文档（隐私政策/服务条款）和接口文档
+├── docs/                           # 文档页面组件，包括法律文档（隐私政策/服务条款）和接口文档
 │
 ├── general/                        # 通用框架组件
 │   ├── manage-pannel.tsx           # ManagePage（泛型）— 通用管理页面框架，封装"列表 + 详情面板"布局，
@@ -280,9 +274,9 @@ components/common/
 
 ---
 
-## 六、开发规范
+## 三、后端开发规范
 
-### 6.1 命名规范
+### 3.1 命名规范
 
 | 对象 | 规范 | 示例 |
 |------|------|------|
@@ -295,7 +289,7 @@ components/common/
 | 任务类型常量 | 全大写蛇形 | `CleanupUnusedUploadsTask` |
 | 配置 Key | 全小写蛇形（YAML） | `session_cookie_name`、`max_idle_conn` |
 
-### 6.2 HTTP Handler 规范
+### 3.2 HTTP Handler 规范
 
 ```go
 // Handler 函数命名：动词 + 名词（PascalCase）
@@ -315,18 +309,11 @@ func ListUsers(c *gin.Context) {
 ```
 
 **响应格式约定**：
-- 成功：`util.OK(data)` 或 `util.OKNil()`  
-- 失败：`util.Err(msg)` + 对应 HTTP 状态码  
-- 通过 `response.RespondSuccess / RespondFailure` 也可（两套工具共存）
+- 成功：`util.OK(data)` 或 `util.OKNil()`
+- 失败：`util.Err(msg)` + 对应 HTTP 状态码
+- 通过 `response.RespondSuccess / RespondFailure` 均可（两套工具共存）
 
-### 6.4 错误处理规范
-
-- **模块内错误消息**：定义在本模块 `errs.go` 中，使用 `const` 字符串。
-- **跨模块错误消息**：定义在 `internal/common/errs.go` 或 `common/constants.go`。
-- **数据库错误**：直接 `err.Error()` 返回给响应（开发阶段），生产环境应屏蔽详情。
-- **gorm.ErrRecordNotFound**：显式判断，返回 404。
-
-### 6.5 中间件使用规范
+### 3.3 中间件使用规范
 
 | 中间件 | 位置 | 作用 |
 |--------|------|------|
@@ -337,20 +324,20 @@ func ListUsers(c *gin.Context) {
 | `oauth.LoginRequired()` | 路由组 | 登录校验 |
 | `admin.LoginAdminRequired()` | Admin 路由组 | 管理员校验 |
 
-### 6.6 配置访问规范
+### 3.4 配置访问规范
 
 - 所有配置通过 `config.Config.<Section>.<Field>` 访问（全局单例）。
 - 不允许在业务代码中使用 `os.Getenv()` 读取配置，统一通过 Viper 加载。
 - 新增配置项：先在 `config.example.yaml` 添加注释模板，再在 `internal/config/model.go` 添加结构体字段。
 
-### 6.7 数据库访问规范
+### 3.5 数据库访问规范
 
 - 直接使用 GORM：`model.DB.Where(...).Find(&result)`（适合简单查询）。
 - 通过 `db.DB(ctx)` 获取带链路追踪的 DB 实例（Admin 模块推荐）。
 - 禁止在 Handler 层直接写复杂 SQL，应封装到 `model/` 层方法或 `service/` 层。
 - 数据库迁移使用 `db/migrator/` 中的 AutoMigrate，不允许手动执行 DDL。
 
-### 6.8 异步任务规范
+### 3.6 异步任务规范
 
 **定义任务**：
 1. 在 `internal/task/constants.go` 中定义任务类型常量。
@@ -360,12 +347,15 @@ func ListUsers(c *gin.Context) {
 
 **队列优先级**（从高到低）：`webhook` > `whitelist_only` > `default`
 
-### 6.9 前端组件样式规范
+---
 
-**基础组件必须遵循系统的色彩主题系统。** 所有基于 shadcn/ui 的基础组件（Button、Dialog、Input 等）应使用组件内置的 `variant` 属性来控制样式，禁止通过 `className` 手写颜色或背景等样式。
+## 四、前端开发规范
+
+### 4.1 组件样式规范
+
+**基础组件必须遵循系统的色彩主题系统。** 所有基于 shadcn/ui 的基础组件（Button、Dialog、Input 等）应使用组件内置 of `variant` 属性来控制样式，禁止通过 `className` 手写颜色或背景等样式。
 
 **错误示例（禁止）**：
-
 ```tsx
 // ❌ 禁止通过 className 手写颜色、背景、阴影等样式
 <Button
@@ -379,7 +369,6 @@ func ListUsers(c *gin.Context) {
 ```
 
 **正确示例**：
-
 ```tsx
 // ✅ 使用 variant 属性，让组件遵循系统主题
 <Button
@@ -394,26 +383,173 @@ func ListUsers(c *gin.Context) {
 
 > **原则**：组件的视觉表现由 shadcn/ui 的 variant 系统和全局 CSS 变量统一控制，保持应用内所有页面风格一致。如现有 variant 无法满足需求，应扩展 shadcn/ui 组件的 variant 定义，而非在业务代码中硬编码颜色值。
 
-### 6.10 严格禁止事项
+### 4.2 页面宽度自适应规范
+
+**开发或更新前端页面时，页面主容器必须支持全宽（Full Width）自适应。** 页面组件的根容器禁止硬编码固定最大宽度（如 `max-w-6xl`、`max-w-4xl` 等），而应统一使用 `w-full`。
+
+由于系统主布局（`MainLayout`）已包含全局 "切换全宽" 状态与按钮，页面主容器不设最大宽度即可让页面宽度完美跟随全局状态。默认情况下由主布局约束在正常宽度限制内，开启全宽后能自动拉伸至 `100%`。
+
+**错误示例（禁止限制宽度）**：
+```tsx
+// ❌ 禁止在页面外层组件硬编码 max-w 限制
+export function FeatureMain() {
+  return (
+    <div className="py-6 space-y-6 max-w-6xl mx-auto">
+      {/* 页面内容 */}
+    </div>
+  )
+}
+```
+
+**正确示例（推荐自适应全宽）**：
+```tsx
+// ✅ 容器使用 w-full，使其自适应外层 layout 的宽度调整
+export function FeatureMain() {
+  return (
+    <div className="py-6 space-y-6 w-full">
+      {/* 页面内容 */}
+    </div>
+  )
+}
+```
+
+### 4.3 组件规范
+
+- 组件应按功能分类。
+- 公共业务组件放在 `components/common` 目录。
+- ShadcnUI 基础组件放在 `components/ui` 目录。
+- 自定义图标应放置在 `/components/icons/` 目录下以命名导出形式管理。常规图标统一使用 Lucide 库。
+
+### 4.4 服务层架构与接口服务新建
+
+服务层架构是前端与 API 交互的统一入口，基于以下原则：
+1. **关注点分离** - 每个服务类只负责一个业务领域。
+2. **统一入口** - 统一通过 `services` 对象对外导出所有服务。
+3. **类型安全** - 所有请求参数和返回响应均有明确的 TypeScript 类型定义。
+
+#### 如何新建接口服务：
+
+1. **创建目录结构**:
+   ```
+   /services/新服务名/
+     - types.ts       // 类型定义
+     - 服务名.service.ts  // 服务实现
+     - index.ts       // 导出服务
+   ```
+
+2. **实现服务类**:
+   ```typescript
+   // 新服务名/服务名.service.ts
+   import {BaseService} from '../core/base.service';
+
+   export class 新服务类 extends BaseService {
+     protected static readonly basePath = '/api/v1/路径';
+
+     static async 方法名(参数): Promise<返回类型> {
+       return this.get<返回类型>('/endpoint');
+     }
+   }
+   ```
+
+3. **在 `services/index.ts` 注册**:
+   ```typescript
+   import {新服务类} from './新服务名';
+
+   const services = {
+     auth: AuthService,
+     新服务名: 新服务类
+   };
+   ```
+
+4. **使用方法**:
+   ```typescript
+   import services from '@/lib/services';
+
+   // 调用服务方法
+   const 结果 = await services.新服务名.方法名(参数);
+   ```
+
+---
+
+## 五、代码质量与审查规范
+
+### 5.1 统一代码检查与提交
+
+> [!IMPORTANT]
+> **代码开发完成后，提交前必须在项目根目录运行 `make code-check` 进行本地代码质量与风格检查，确保前端 ESLint 没有报错和警告（`--max-warnings 0`）。**
+
+```bash
+# 执行根目录的检查指令
+make code-check
+```
+
+### 5.2 后端规范检查
+
+**基础检查**：
+- 后端 Go 代码需要通过 CodeQL 扫描。较复杂的逻辑建议结合 Copilot 检查。
+
+**API 文档**：
+- 所有 HTTP 接口都必须编写完整的 Swagger 注释。提交前需运行 `make swagger` 自动生成与更新接口文档。
+
+**统一响应格式**：
+```json
+// 响应数据最外层固定包含 error_msg 与 data
+{
+    "error_msg": "",
+    "data": null
+}
+
+// 示例：单条实体数据
+{
+    "error_msg": "",
+    "data": {}
+}
+
+// 示例：分页数据格式
+{
+    "error_msg": "",
+    "data": {
+        "total": 0,
+        "results": []
+    }
+}
+```
+
+### 5.3 数据库设计规范
+
+- **外键约束**：禁止在数据库物理层面使用外键（FK），但需要在对应关联字段上显式建立索引。
+- **默认值一致性**：数据库表字段的默认值必须与 Go model struct 的默认零值一致（如 `nil`, `0`, `false`, `""`），防止由于插入时漏填导致字段产生数据库异常默认值。
+
+### 5.4 前端类型安全规范
+
+- **禁止使用 `any`**：`any` 类型会绕过 TypeScript 编译期的类型检查系统，掩盖潜在的运行时错误，因此全面禁止使用。
+- **合理使用 `unknown`**：`unknown` 是类型安全的 `any`，接收到此类值后必须先进行类型断言（Type Assertion）或类型收窄（Type Narrowing）后方可使用。
+- **合理使用 `never`**：`never` 类型表示永远不会发生的值类型，必须谨慎使用，并在其使用处编写清晰的注释。
+- **静态分析检查**：前端代码必须通过 ESLint 检查和 CodeQL 静态漏洞扫描。
+
+---
+
+## 六、包依赖与安全禁止项
+
+### 6.1 严格禁止事项
 
 | 禁止行为 | 说明 |
 |----------|------|
 | **禁止删除 `node_modules` 目录** | `node_modules` 为前端依赖安装目录，删除会导致项目无法运行。如需重新安装依赖，使用 `pnpm install` 覆盖更新即可，严禁执行 `rm -rf node_modules`。 |
-| **`internal/util/` 下禁止引用框架包** | `util/` 及其子包（如 `util/cap`）定位为**纯工具层**，不得 `import` 任何 HTTP / ORM / 框架包，包括但不限于 `github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions`。违反此约束会导致工具层与框架产生耦合，无法独立测试。详见 **6.11** 的建议方案。 |
+| **`internal/util/` 下禁止引用框架包** | `util/` 及其子包（如 `util/cap`）定位为**纯工具层**，不得 `import` 任何 HTTP / ORM / 框架包，包括但不限于 `github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions`。违反此约束会导致工具层与框架产生耦合，无法独立测试。详见下文的建议方案。 |
 
-### 6.11 `util/` 包依赖约束与建议方案
+### 6.2 `util/` 包依赖约束与建议方案
 
-#### 约束范围
+#### 约束范围：
 
 `internal/util/` 及其全部子包（如 `util/cap`、`util/crypto` 等）只允许引用：
-
 - Go 标准库（`context`、`crypto`、`encoding`、`net/http` 原生包等）
 - 项目内同级别的纯工具包（`internal/config`、`internal/db`、`internal/model` 等无框架依赖的包）
 - 与框架无关的第三方库（如 `github.com/redis/go-redis`、`github.com/shopspring/decimal` 等）
 
 **严禁引用**：`github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions` 及任何 HTTP 框架 / Web 中间件相关包。
 
-#### 常见误区与建议方案
+#### 常见误区与建议方案：
 
 | 误区 | 建议方案 |
 |------|----------|
@@ -421,7 +557,7 @@ func ListUsers(c *gin.Context) {
 | 在 `util/` 中通过 `*gin.Context` 写响应 | 只在 `util/` 中计算/校验逻辑并返回 `(result, error)`，由 `apps/` 层的 Handler 负责调用 `c.AbortWithStatusJSON` 写响应 |
 | 在 `util/` 中使用 `gorm.DB` 直接查询 | 将数据库查询封装在 `internal/model/` 层方法中，`util/` 只接收已查出的数据结构 |
 
-#### 正确示例
+#### 正确示例：
 
 ```go
 // ✅ internal/util/cap/manager.go — 纯逻辑，无框架依赖
@@ -443,7 +579,7 @@ func VerifyMiddleware(mgr *caputil.Manager, scope string, enabledFunc func() boo
 }
 ```
 
-#### 错误示例（禁止）
+#### 错误示例（禁止）：
 
 ```go
 // ❌ internal/util/cap/middleware.go — util/ 层不应出现 gin
@@ -456,10 +592,11 @@ func (m *Manager) VerifyMiddleware(...) gin.HandlerFunc { ... }
 
 ## 七、新增功能开发流程
 
-新增 **异步任务** ：使用项目专属 SKILL: new-async-task 进行开发
+### 7.1 新增模块开发流程
+
+新增 **异步任务**：使用项目专属 SKILL: `new-async-task` 进行开发。
 
 以新增 **管理员功能模块** 为例：
-
 ```
 1. 在 internal/model/ 中定义/扩展数据模型
 2. 在 db/migrator/ 中注册 AutoMigrate
@@ -470,17 +607,17 @@ func (m *Manager) VerifyMiddleware(...) gin.HandlerFunc { ... }
 5. 执行 make swagger 更新文档
 ```
 
-**Handler 文件拆分规则**：
+### 7.2 Handler 文件拆分规则
 
 逻辑简单的 CRUD 可以全部放在 `routers.go` 中。但当文件代码行数增长时，必须按以下规则拆分：
 
-| 条件                        | 拆分方式 |
-|---------------------------|----------|
-| 文件超过 **600 行**            | 必须拆分 |
+| 条件 | 拆分方式 |
+|------|----------|
+| 文件超过 **600 行** | 必须拆分 |
 | 包含复杂业务逻辑（如外部调用、多步校验、事务处理） | 将业务逻辑拆到 `logic.go` 或 `logics.go` |
-| 同一模块有多个独立功能域              | 按功能域拆分多个文件，如 `user_routers.go`、`role_routers.go` |
+| 同一模块有多个独立功能域 | 按功能域拆分多个文件，如 `user_routers.go`、`role_routers.go` |
 
-拆分后的模块文件结构示例：
+#### 拆分后的模块文件结构示例：
 
 ```
 apps/admin/<module>/
@@ -490,15 +627,13 @@ apps/admin/<module>/
 └── constants.go        # 业务常量（按需）
 ```
 
-**职责边界**：
-
+#### 职责边界：
 - `routers.go` 只做三件事：参数绑定、调用 logic 函数、返回响应。不包含任何业务判断逻辑。
 - `logics.go` 负责所有业务逻辑，接收已校验的参数，返回处理结果和错误。函数以 `PascalCase` 导出，供 `routers.go` 调用。
 
-
 ---
 
-## 八、前端任务管理页面
+## 八、后端任务管理 API 接口
 
 任务管理 API 路由（Admin）：
 
@@ -508,6 +643,4 @@ apps/admin/<module>/
 | POST | `/api/v1/admin/tasks/dispatch` | 手动下发任务 |
 | GET | `/api/v1/admin/tasks/executions` | 分页查询任务执行记录（支持 status / task_type 筛选） |
 | GET | `/api/v1/admin/tasks/executions/:id` | 查询单条任务执行详情（含完整 Log） |
-| POST | `/api/v1/admin/tasks/executions/:id/retry` | 重试失败任务（校验 Retryable && RetryCount < MaxRetry） |
-
----
+| POST | `/api/v1/admin/tasks/executions/:id/retry` | 重试失败任务（校验 Retryable && RetryCount < MaxRetry） |
\ No newline at end of file
diff --git a/config.example.yaml b/config.example.yaml
index b5486dac..c1db088e 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -111,7 +111,7 @@ worker:
 
 # ─── OpenTelemetry Tracing ──────────────────────────────────────────────────────
 otel:
-  sampling_rate: 0.1           # Trace sampling rate (0.0 – 1.0)
+  sampling_rate: 0.0           # Trace sampling rate (0.0 – 1.0)
 
 # ─── S3-Compatible File Storage ─────────────────────────────────────────────────
 # Compatible with AWS S3, MinIO, Cloudflare R2, Tencent COS, etc.
diff --git a/docs/docs.go b/docs/docs.go
index 04b6e2d2..08dae68b 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -517,6 +517,156 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/v1/admin/logs/access": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "admin"
+                ],
+                "summary": "获取用户访问日志",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "页码",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "每页条数",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "用户名模糊搜索",
+                        "name": "username",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "接口路径模糊搜索",
+                        "name": "path",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "起始时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）",
+                        "name": "start_time",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "结束时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）",
+                        "name": "end_time",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "访问日志列表",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/logs.accessLogsResponse"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "ClickHouse 未启用或参数错误",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "403": {
+                        "description": "无管理员权限",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/admin/logs/analytics": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "admin"
+                ],
+                "summary": "获取访问日志分析数据",
+                "responses": {
+                    "200": {
+                        "description": "分析统计数据",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/logs.logsAnalyticsResponse"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "ClickHouse 未启用",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "403": {
+                        "description": "无管理员权限",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/admin/logs/ws": {
             "get": {
                 "description": "通过 WebSocket 实时推送系统日志，需要管理员权限",
@@ -2650,6 +2800,49 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/v1/user-info": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "oauth"
+                ],
+                "summary": "获取当前登录用户信息",
+                "responses": {
+                    "200": {
+                        "description": "用户信息",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/oauth.BasicUserInfo"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/user/access-tokens": {
             "get": {
                 "security": [
@@ -3130,6 +3323,49 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/v1/user/self": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "oauth"
+                ],
+                "summary": "获取当前登录用户信息",
+                "responses": {
+                    "200": {
+                        "description": "用户信息",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/oauth.BasicUserInfo"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/user/send-email-code": {
             "post": {
                 "description": "向指定邮箱发送验证码（用于注册场景）",
@@ -3216,6 +3452,26 @@ const docTemplate = `{
                     }
                 }
             }
+        },
+        "/robots.txt": {
+            "get": {
+                "description": "根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容",
+                "produces": [
+                    "text/plain"
+                ],
+                "tags": [
+                    "config"
+                ],
+                "summary": "获取 robots.txt",
+                "responses": {
+                    "200": {
+                        "description": "robots.txt 内容",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
         }
     },
     "definitions": {
@@ -3344,6 +3600,97 @@ const docTemplate = `{
                 }
             }
         },
+        "logs.accessLogItem": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string"
+                },
+                "headers": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "ip": {
+                    "type": "string"
+                },
+                "latency": {
+                    "type": "integer"
+                },
+                "method": {
+                    "type": "string"
+                },
+                "nickname": {
+                    "type": "string"
+                },
+                "path": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "integer"
+                },
+                "user_agent": {
+                    "type": "string"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "logs.accessLogsResponse": {
+            "type": "object",
+            "properties": {
+                "list": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.accessLogItem"
+                    }
+                },
+                "total": {
+                    "type": "integer"
+                }
+            }
+        },
+        "logs.browserItem": {
+            "type": "object",
+            "properties": {
+                "browser": {
+                    "type": "string"
+                },
+                "count": {
+                    "type": "integer"
+                }
+            }
+        },
+        "logs.logsAnalyticsResponse": {
+            "type": "object",
+            "properties": {
+                "browsers": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.browserItem"
+                    }
+                },
+                "top_users": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.topUserItem"
+                    }
+                },
+                "trend": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.trendItem"
+                    }
+                }
+            }
+        },
         "logs.logsResponse": {
             "type": "object",
             "properties": {
@@ -3362,6 +3709,35 @@ const docTemplate = `{
                 }
             }
         },
+        "logs.topUserItem": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "nickname": {
+                    "type": "string"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "logs.trendItem": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "date": {
+                    "type": "string"
+                }
+            }
+        },
         "model.AccessToken": {
             "type": "object",
             "properties": {
diff --git a/docs/swagger.json b/docs/swagger.json
index 4457b72c..b9d5226e 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -510,6 +510,156 @@
                 }
             }
         },
+        "/api/v1/admin/logs/access": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "admin"
+                ],
+                "summary": "获取用户访问日志",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "页码",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "每页条数",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "用户名模糊搜索",
+                        "name": "username",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "接口路径模糊搜索",
+                        "name": "path",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "起始时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）",
+                        "name": "start_time",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "结束时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）",
+                        "name": "end_time",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "访问日志列表",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/logs.accessLogsResponse"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "ClickHouse 未启用或参数错误",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "403": {
+                        "description": "无管理员权限",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/admin/logs/analytics": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "admin"
+                ],
+                "summary": "获取访问日志分析数据",
+                "responses": {
+                    "200": {
+                        "description": "分析统计数据",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/logs.logsAnalyticsResponse"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "ClickHouse 未启用",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    },
+                    "403": {
+                        "description": "无管理员权限",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/admin/logs/ws": {
             "get": {
                 "description": "通过 WebSocket 实时推送系统日志，需要管理员权限",
@@ -2643,6 +2793,49 @@
                 }
             }
         },
+        "/api/v1/user-info": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "oauth"
+                ],
+                "summary": "获取当前登录用户信息",
+                "responses": {
+                    "200": {
+                        "description": "用户信息",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/oauth.BasicUserInfo"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/user/access-tokens": {
             "get": {
                 "security": [
@@ -3123,6 +3316,49 @@
                 }
             }
         },
+        "/api/v1/user/self": {
+            "get": {
+                "security": [
+                    {
+                        "SessionCookie": []
+                    }
+                ],
+                "description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "oauth"
+                ],
+                "summary": "获取当前登录用户信息",
+                "responses": {
+                    "200": {
+                        "description": "用户信息",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/oauth.BasicUserInfo"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "401": {
+                        "description": "未登录",
+                        "schema": {
+                            "$ref": "#/definitions/util.ResponseAny"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/user/send-email-code": {
             "post": {
                 "description": "向指定邮箱发送验证码（用于注册场景）",
@@ -3209,6 +3445,26 @@
                     }
                 }
             }
+        },
+        "/robots.txt": {
+            "get": {
+                "description": "根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容",
+                "produces": [
+                    "text/plain"
+                ],
+                "tags": [
+                    "config"
+                ],
+                "summary": "获取 robots.txt",
+                "responses": {
+                    "200": {
+                        "description": "robots.txt 内容",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
         }
     },
     "definitions": {
@@ -3337,6 +3593,97 @@
                 }
             }
         },
+        "logs.accessLogItem": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string"
+                },
+                "headers": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "ip": {
+                    "type": "string"
+                },
+                "latency": {
+                    "type": "integer"
+                },
+                "method": {
+                    "type": "string"
+                },
+                "nickname": {
+                    "type": "string"
+                },
+                "path": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "integer"
+                },
+                "user_agent": {
+                    "type": "string"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "logs.accessLogsResponse": {
+            "type": "object",
+            "properties": {
+                "list": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.accessLogItem"
+                    }
+                },
+                "total": {
+                    "type": "integer"
+                }
+            }
+        },
+        "logs.browserItem": {
+            "type": "object",
+            "properties": {
+                "browser": {
+                    "type": "string"
+                },
+                "count": {
+                    "type": "integer"
+                }
+            }
+        },
+        "logs.logsAnalyticsResponse": {
+            "type": "object",
+            "properties": {
+                "browsers": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.browserItem"
+                    }
+                },
+                "top_users": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.topUserItem"
+                    }
+                },
+                "trend": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/logs.trendItem"
+                    }
+                }
+            }
+        },
         "logs.logsResponse": {
             "type": "object",
             "properties": {
@@ -3355,6 +3702,35 @@
                 }
             }
         },
+        "logs.topUserItem": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "nickname": {
+                    "type": "string"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "0"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "logs.trendItem": {
+            "type": "object",
+            "properties": {
+                "count": {
+                    "type": "integer"
+                },
+                "date": {
+                    "type": "string"
+                }
+            }
+        },
         "model.AccessToken": {
             "type": "object",
             "properties": {
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 102b156b..2041e936 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -82,6 +82,66 @@ definitions:
         description: 全局递增序号
         type: integer
     type: object
+  logs.accessLogItem:
+    properties:
+      created_at:
+        type: string
+      headers:
+        type: string
+      id:
+        example: "0"
+        type: string
+      ip:
+        type: string
+      latency:
+        type: integer
+      method:
+        type: string
+      nickname:
+        type: string
+      path:
+        type: string
+      status:
+        type: integer
+      user_agent:
+        type: string
+      user_id:
+        example: "0"
+        type: string
+      username:
+        type: string
+    type: object
+  logs.accessLogsResponse:
+    properties:
+      list:
+        items:
+          $ref: '#/definitions/logs.accessLogItem'
+        type: array
+      total:
+        type: integer
+    type: object
+  logs.browserItem:
+    properties:
+      browser:
+        type: string
+      count:
+        type: integer
+    type: object
+  logs.logsAnalyticsResponse:
+    properties:
+      browsers:
+        items:
+          $ref: '#/definitions/logs.browserItem'
+        type: array
+      top_users:
+        items:
+          $ref: '#/definitions/logs.topUserItem'
+        type: array
+      trend:
+        items:
+          $ref: '#/definitions/logs.trendItem'
+        type: array
+    type: object
   logs.logsResponse:
     properties:
       has_more:
@@ -94,6 +154,25 @@ definitions:
         description: 用于加载更早日志的 cursor
         type: integer
     type: object
+  logs.topUserItem:
+    properties:
+      count:
+        type: integer
+      nickname:
+        type: string
+      user_id:
+        example: "0"
+        type: string
+      username:
+        type: string
+    type: object
+  logs.trendItem:
+    properties:
+      count:
+        type: integer
+      date:
+        type: string
+    type: object
   model.AccessToken:
     properties:
       created_at:
@@ -1098,6 +1177,97 @@ paths:
       summary: 获取系统日志
       tags:
       - admin
+  /api/v1/admin/logs/access:
+    get:
+      description: 分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）
+      parameters:
+      - default: 1
+        description: 页码
+        in: query
+        name: page
+        type: integer
+      - default: 20
+        description: 每页条数
+        in: query
+        name: page_size
+        type: integer
+      - description: 用户名模糊搜索
+        in: query
+        name: username
+        type: string
+      - description: 接口路径模糊搜索
+        in: query
+        name: path
+        type: string
+      - description: 起始时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）
+        in: query
+        name: start_time
+        type: string
+      - description: 结束时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）
+        in: query
+        name: end_time
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 访问日志列表
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/logs.accessLogsResponse'
+              type: object
+        "400":
+          description: ClickHouse 未启用或参数错误
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "403":
+          description: 无管理员权限
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 获取用户访问日志
+      tags:
+      - admin
+  /api/v1/admin/logs/analytics:
+    get:
+      description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 分析统计数据
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/logs.logsAnalyticsResponse'
+              type: object
+        "400":
+          description: ClickHouse 未启用
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+        "403":
+          description: 无管理员权限
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 获取访问日志分析数据
+      tags:
+      - admin
   /api/v1/admin/logs/ws:
     get:
       description: 通过 WebSocket 实时推送系统日志，需要管理员权限
@@ -2380,6 +2550,30 @@ paths:
       summary: 获取我的文件列表
       tags:
       - upload
+  /api/v1/user-info:
+    get:
+      description: 返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 用户信息
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/oauth.BasicUserInfo'
+              type: object
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 获取当前登录用户信息
+      tags:
+      - oauth
   /api/v1/user/access-tokens:
     get:
       description: 返回当前登录用户的所有 active access tokens（脱敏后）
@@ -2662,6 +2856,30 @@ paths:
       summary: 用户注册
       tags:
       - user
+  /api/v1/user/self:
+    get:
+      description: 返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 用户信息
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  $ref: '#/definitions/oauth.BasicUserInfo'
+              type: object
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/util.ResponseAny'
+      security:
+      - SessionCookie: []
+      summary: 获取当前登录用户信息
+      tags:
+      - oauth
   /api/v1/user/send-email-code:
     post:
       consumes:
@@ -2719,6 +2937,19 @@ paths:
       summary: 获取已上传文件
       tags:
       - upload
+  /robots.txt:
+    get:
+      description: 根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容
+      produces:
+      - text/plain
+      responses:
+        "200":
+          description: robots.txt 内容
+          schema:
+            type: string
+      summary: 获取 robots.txt
+      tags:
+      - config
 securityDefinitions:
   SessionCookie:
     in: cookie
diff --git a/internal/apps/oauth/routers.go b/internal/apps/oauth/routers.go
index 678e0e9f..657d1a36 100644
--- a/internal/apps/oauth/routers.go
+++ b/internal/apps/oauth/routers.go
@@ -67,6 +67,8 @@ func BuildBasicUserInfo(user *model.User, needChange bool) BasicUserInfo {
 // @Success 200 {object} util.ResponseAny{data=oauth.BasicUserInfo} "用户信息"
 // @Failure 401 {object} util.ResponseAny "未登录"
 // @Router /api/v1/oauth/user-info [get]
+// @Router /api/v1/user-info [get]
+// @Router /api/v1/user/self [get]
 func UserInfo(c *gin.Context) {
 	user, _ := util.GetFromContext[*model.User](c, UserObjKey)
 	session := sessions.Default(c)