tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-11 01:36:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

规约

Browse Source
This commit is contained in:
ryan
2026-06-09 11:26:57 +08:00
parent e100441e8a
commit 31f0fb4ceb
9 changed files with 1411 additions and 306 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Agents.md
+223 -236
View File
@@ -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.新服务名.方法名(参数);
```
---
## 五、代码质量与审查规范
### 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） |