tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-28 05:46:36 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
5fd056f99fc019415f8cf62e2f8c2b520683b751
OpenFlare/docs/docs.go
T
ryan 410ff14795 refactor(storage): drop per-upload storage_driver, use storage_config as single source 
Remove w_uploads.storage_driver and route all read/write/delete paths through
storage.Active() backed by storage_config.driver. Block direct driver switches
when uploads exist; require migration task instead. Simplify migration to
cursor-based file_path iteration without per-row driver updates.
2026-06-18 13:56:31 +08:00

7572 lines
262 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
import "github.com/swaggo/swag"
const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {
"name": "Wavelet",
"url": "https://github.com/Rain-kl/Wavelet"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/cap/challenge": {
"post": {
"description": "客户端获取 PoW 难题和签名的 JWT Token，并在后台计算。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"cap"
],
"summary": "生成人机验证难题",
"parameters": [
{
"description": "可选范围限制参数",
"name": "request",
"in": "body",
"schema": {
"$ref": "#/definitions/cap.challengeRequest"
}
}
],
"responses": {
"200": {
"description": "成功返回 PoW 难题",
"schema": {
"$ref": "#/definitions/cap.ChallengeResponse"
}
},
"500": {
"description": "内部服务错误",
"schema": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse"
}
}
}
}
},
"/api/cap/redeem": {
"post": {
"description": "提交 PoW 解答进行核销，成功后返回一次性 X-Cap-Token 凭证",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"cap"
],
"summary": "校验人机验证解答",
"parameters": [
{
"description": "难题 Token 与解答 solutions 数组",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/cap.redeemRequest"
}
}
],
"responses": {
"200": {
"description": "核销成功，返回 X-Cap-Token",
"schema": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse"
}
},
"400": {
"description": "参数错误或核销失败",
"schema": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse"
}
},
"500": {
"description": "内部服务错误",
"schema": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse"
}
}
}
}
},
"/api/health": {
"get": {
"description": "检查服务是否正常运行，可用于负载均衡存活探测",
"produces": [
"application/json"
],
"tags": [
"health"
],
"summary": "健康检查",
"responses": {
"200": {
"description": "服务正常",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/auth-sources": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回所有已配置的 OAuth/OIDC 认证源列表，包括已启用和未启用的，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取认证源列表",
"responses": {
"200": {
"description": "认证源列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.AuthSource"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "创建一个新的 OAuth/OIDC 认证源配置，认证源名称必须唯一且符合命名规范，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "创建认证源",
"parameters": [
{
"description": "创建认证源参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/auth_source.AuthSourceRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功，返回认证源信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.AuthSource"
}
}
}
]
}
},
"400": {
"description": "参数错误或验证失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/auth-sources/{id}": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "更新指定 ID 的认证源配置。若 client_secret 字段为空，则保留原有密钥不变，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "更新认证源",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "认证源 ID 或名称",
"name": "id",
"in": "path",
"required": true
},
{
"description": "更新认证源参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/auth_source.AuthSourceRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功，返回更新后的认证源信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.AuthSource"
}
}
}
]
}
},
"400": {
"description": "参数错误或验证失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "删除指定认证源及其关联的所有外部帐号绑定记录，警告：删除后相关用户将无法通过该源登录，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "删除认证源",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "认证源 ID 或名称",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "ID 无效或删除失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/auth-sources/{id}/toggle": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "启用或禁用指定认证源。尝试启用时将验证 Client ID 和 Client Secret 是否已配置，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "切换认证源启用状态",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "认证源 ID 或名称",
"name": "id",
"in": "path",
"required": true
},
{
"description": "启用状态",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/auth_source.ToggleAuthSourceRequest"
}
}
],
"responses": {
"200": {
"description": "切换成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "验证失败或认证源不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/cache/clear": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "清除系统磁盘缓存目录中的所有临时文件，并重置缓存容量和 Key 追踪数据",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "清空缓存",
"responses": {
"200": {
"description": "清理成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/cache/config": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "更改磁盘缓存最大容量限制、文件生存时间（TTL）以及是否启用 LRU 淘汰淘汰算法，并进行热更新",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "更新缓存配置",
"parameters": [
{
"description": "缓存配置请求体",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/cache.updateCacheConfigRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/cache/status": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "获取当前系统磁盘缓存的使用情况（已占用字节、Key 数量等）与策略配置",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取缓存状态",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/diskcache.Status"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/db-export": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "SQLite 时直接下载 .db 文件；PostgreSQL 时执行 pg_dump 并流式下载 .sql 文件，需要管理员权限",
"produces": [
"application/octet-stream"
],
"tags": [
"admin"
],
"summary": "导出数据库",
"responses": {
"200": {
"description": "数据库文件",
"schema": {
"type": "file"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "导出失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/db-info": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前使用的数据库类型（sqlite/postgres）、名称/路径及版本字符串，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取数据库信息",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/status.DatabaseInfoResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/db-manage/overview": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "获取数据库类型、版本、名称、文件大小、表数量及当前连接数，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取数据库运行概览",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/db_manage.DBOverviewResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/db-manage/query": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "在当前数据库中执行任意自定义 SQL，如果是查询语句将返回格式化后的列与数据集，否则返回受影响行数，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "执行 SQL 查询",
"parameters": [
{
"description": "SQL 请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/db_manage.ExecuteSQLRequest"
}
}
],
"responses": {
"200": {
"description": "执行完毕",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/db_manage.ExecuteSQLResponse"
}
}
}
]
}
},
"400": {
"description": "SQL 语句错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/db-manage/tables": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前数据库的所有用户自定义表名称列表，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取数据库所有表名",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/logs": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "分页获取系统历史日志，cursor=0 获取最新日志，cursor\u003e0 获取更早日志",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取系统日志",
"parameters": [
{
"type": "integer",
"default": 0,
"description": "日志游标，0=获取最新",
"name": "cursor",
"in": "query"
},
{
"type": "integer",
"default": 200,
"description": "每页条数",
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "日志列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/logs.logsResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/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/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/logs.accessLogsResponse"
}
}
}
]
}
},
"400": {
"description": "ClickHouse 未启用或参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/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/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/logs.logsAnalyticsResponse"
}
}
}
]
}
},
"400": {
"description": "ClickHouse 未启用",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/logs/ws": {
"get": {
"description": "通过 WebSocket 实时推送系统日志，需要管理员权限",
"tags": [
"admin"
],
"summary": "系统日志实时推送",
"responses": {}
}
},
"/api/v1/admin/push/channels": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统配置的所有消息通道列表，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "获取所有消息通道",
"responses": {
"200": {
"description": "消息通道列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.PushChannel"
}
}
}
}
]
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "新建一个消息通道配置，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "创建消息通道",
"parameters": [
{
"description": "创建参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.CreateChannelRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.PushChannel"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/channels/definitions": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统支持的所有消息通道类型（如飞书、邮件、自定义、Telegram）的动态表单定义，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "获取所有消息通道配置字段定义",
"responses": {
"200": {
"description": "通道配置定义列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/push.Definition"
}
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/channels/test": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "触发一次临时的或现有的通道连通性推送测试，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "测试通道连通性",
"parameters": [
{
"description": "测试参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.TestChannelRequest"
}
}
],
"responses": {
"200": {
"description": "测试触发成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/push/channels/{id}": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "修改消息通道配置，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "更新消息通道",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "通道ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "更新参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.UpdateChannelRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.PushChannel"
}
}
}
]
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据ID删除消息通道，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "删除消息通道",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "通道ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/push/events": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统配置的通知事件列表，包括预置和自定义事件，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "获取所有通知事件",
"responses": {
"200": {
"description": "通知事件列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.PushEvent"
}
}
}
}
]
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "绑定系统内置事件或异步任务、推送渠道、接收目标并创建通知事件配置，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "创建通知事件",
"parameters": [
{
"description": "创建参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.CreateEventRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.PushEvent"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/events/builtin": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统定义的所有内置通知事件元数据，供前端下拉框选择，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "获取所有内置通知事件",
"responses": {
"200": {
"description": "内置通知事件列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/push.EventMetadata"
}
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/events/{id}": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "更新已有通知事件的推送渠道、接收目标和内容模板，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "更新通知事件",
"parameters": [
{
"type": "integer",
"description": "事件 ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "更新参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.UpdateEventRequest"
}
}
],
"responses": {
"200": {
"description": "修改成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "删除数据库中的特定通知事件配置，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "删除通知事件配置",
"parameters": [
{
"type": "integer",
"description": "事件 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/events/{id}/toggle": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "启用或禁用指定的通知事件",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "快捷切换通知事件启用状态",
"parameters": [
{
"type": "integer",
"description": "事件 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "切换成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/histories": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回分页的通知历史日志数据，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "分页获取通知推送历史",
"parameters": [
{
"type": "integer",
"description": "当前页码",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "分页大小",
"name": "page_size",
"in": "query"
},
{
"type": "string",
"description": "过滤事件名称",
"name": "event_key",
"in": "query"
},
{
"type": "string",
"description": "过滤发送状态",
"name": "status",
"in": "query"
}
],
"responses": {
"200": {
"description": "推送历史列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/push.pushHistoriesResponse"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/push/test": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "接收临时通知渠道配置并在本地同步调用 Pusher.Send 发送测试消息",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin-push"
],
"summary": "测试推送通道发送",
"parameters": [
{
"description": "测试请求体",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/push.TestPushRequest"
}
}
],
"responses": {
"200": {
"description": "测试成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
}
},
"/api/v1/admin/status": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "获取后端服务运行状态、Goroutine、内存指标等详细统计数据，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取系统状态信息",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/status.SystemStatusResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/system-configs": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取系统配置列表",
"parameters": [
{
"type": "string",
"description": "配置类型（system/business）",
"name": "type",
"in": "query"
}
],
"responses": {
"200": {
"description": "系统配置列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.SystemConfig"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "创建一条新的系统配置项，配置键不可重复，同时将新配置同步到 Redis，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "创建系统配置",
"parameters": [
{
"description": "创建请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/system_config.CreateSystemConfigRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误或配置键已存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/system-configs/smtp/test": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "使用传入的配置进行 SMTP 邮件发送测试，支持使用 ****** 占位符使用保存的数据库密码",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "测试 SMTP 邮件发送",
"parameters": [
{
"description": "测试请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/system_config.TestSMTPRequest"
}
}
],
"responses": {
"200": {
"description": "测试执行完毕",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/system_config.TestSMTPResponse"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/system-configs/{key}": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据配置键获取对应的系统配置详情，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取单个系统配置",
"parameters": [
{
"type": "string",
"description": "配置键",
"name": "key",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "系统配置详情",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.SystemConfig"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "配置不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据配置键更新对应的配置内容，同时将更新同步到 Redis，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "更新系统配置",
"parameters": [
{
"type": "string",
"description": "配置键",
"name": "key",
"in": "path",
"required": true
},
{
"description": "更新请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/system_config.UpdateSystemConfigRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "配置不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/dispatch": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "手动触发指定类型的异步任务，支持指定时间范围和用户，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "下发异步任务",
"parameters": [
{
"description": "任务请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/task.DispatchTaskRequest"
}
}
],
"responses": {
"200": {
"description": "任务已入队",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "任务类型不存在或参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "任务入队失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/executions": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "分页查询任务执行记录，支持按状态和任务类型筛选，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "查询任务执行记录",
"parameters": [
{
"type": "string",
"description": "状态筛选 (pending/running/succeeded/failed)",
"name": "status",
"in": "query"
},
{
"type": "string",
"description": "任务类型筛选",
"name": "task_type",
"in": "query"
},
{
"type": "integer",
"default": 1,
"description": "页码",
"name": "page",
"in": "query"
},
{
"type": "integer",
"default": 20,
"description": "每页条数",
"name": "page_size",
"in": "query"
}
],
"responses": {
"200": {
"description": "任务执行记录列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "object"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/executions/{id}": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据 ID 查询任务执行记录详情，包含完整执行日志，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "查询任务执行详情",
"parameters": [
{
"type": "integer",
"description": "任务执行记录 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "任务执行详情",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.TaskExecution"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "记录不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/executions/{id}/retry": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "重新下发一条失败的任务，创建新的执行记录，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "重试失败任务",
"parameters": [
{
"type": "integer",
"description": "任务执行记录 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "新任务的 TaskID",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "任务不支持重试或参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "记录不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "重试失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/schedules": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统所有的定时任务配置列表，包括名称、关联的异步任务类型、Cron 表达式和启用状态，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取定时任务列表",
"responses": {
"200": {
"description": "定时任务列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.Schedule"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "新增一个动态定时任务配置，关联已有的异步任务，配置 Cron 表达式和执行参数，并触发调度器热加载，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "创建定时任务",
"parameters": [
{
"description": "创建定时任务请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/task.CreateScheduleRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功的定时任务信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Schedule"
}
}
}
]
}
},
"400": {
"description": "Cron 表达式无效、异步任务类型不存在或参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "保存定时任务失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/schedules/{id}": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "修改一个定时任务的配置（名称、Cron 表达式、异步任务参数和是否启用等），并触发调度器热加载，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "修改定时任务",
"parameters": [
{
"type": "integer",
"description": "定时任务 ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "修改定时任务请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/task.UpdateScheduleRequest"
}
}
],
"responses": {
"200": {
"description": "修改后的定时任务信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Schedule"
}
}
}
]
}
},
"400": {
"description": "Cron 表达式无效、参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "定时任务不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "修改定时任务失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "删除指定的定时任务配置，并触发调度器热加载，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "删除定时任务",
"parameters": [
{
"type": "integer",
"description": "定时任务 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除结果",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "删除定时任务失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/tasks/types": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统支持的所有可调度任务类型列表，包括任务名称、描述、是否支持时间范围等元数据，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取支持的任务类型",
"responses": {
"200": {
"description": "任务类型列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/task.TaskMeta"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/templates": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回所有通知模板列表，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取模板列表",
"responses": {
"200": {
"description": "模板列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.Template"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "创建一条新的自定义通知模板，模板标识符（Key）不可重复，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "创建模板",
"parameters": [
{
"description": "创建请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/template.CreateTemplateRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误或模板标识符已存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/templates/{key}": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据模板标识符获取对应的模板详情，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取单个模板",
"parameters": [
{
"type": "string",
"description": "模板标识符",
"name": "key",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "模板详情",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Template"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "模板不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据模板标识符更新对应的模板内容，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "更新模板",
"parameters": [
{
"type": "string",
"description": "模板标识符",
"name": "key",
"in": "path",
"required": true
},
{
"description": "更新请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/template.UpdateTemplateRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Template"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "模板不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据模板标识符删除对应模板，系统预置模板不可删除，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "删除模板",
"parameters": [
{
"type": "string",
"description": "模板标识符",
"name": "key",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "不可删除系统模板",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "模板不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/update": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "从系统配置指定的 GitHub 上游仓库查询最新兼容 Release，并与当前服务版本比较",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取应用更新状态",
"responses": {
"200": {
"description": "更新状态",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/updater.Status"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "查询失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/update/apply": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "下载当前平台对应的 GitHub Actions Release 资产，替换当前二进制并重启进程",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "下载并应用应用更新",
"responses": {
"200": {
"description": "升级已准备并即将重启",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"400": {
"description": "当前版本不可升级",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "升级准备失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "分页获取系统上传的文件列表，支持文件名关键词、业务类型、扩展名、上传用户ID过滤",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取文件列表",
"parameters": [
{
"type": "integer",
"description": "页码（默认 1）",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "每页数量（默认 20，最大 100）",
"name": "page_size",
"in": "query"
},
{
"type": "string",
"description": "文件名关键词（模糊匹配）",
"name": "keyword",
"in": "query"
},
{
"type": "string",
"description": "业务分类过滤",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "扩展名过滤",
"name": "extension",
"in": "query"
},
{
"type": "integer",
"format": "int64",
"description": "上传用户 ID",
"name": "user_id",
"in": "query"
}
],
"responses": {
"200": {
"description": "查询成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/handler.listFilesResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads/download/batch": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "传入多个文件 ID，后台实时将其打包压缩为 ZIP 流并输出，自动处理文件名重复冲突",
"consumes": [
"application/json"
],
"produces": [
"application/octet-stream"
],
"tags": [
"admin"
],
"summary": "批量打包下载",
"parameters": [
{
"description": "包含文件 ID 数组 of string 的请求体",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/handler.batchDownloadRequest"
}
}
],
"responses": {
"200": {
"description": "成功下载打包后的 ZIP",
"schema": {
"type": "file"
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "打包失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads/download/{id}": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "根据文件 ID 获取文件，以附件形式 (Attachment) 强制开启客户端浏览器下载",
"produces": [
"application/octet-stream"
],
"tags": [
"admin"
],
"summary": "下载单文件",
"parameters": [
{
"type": "string",
"description": "文件 ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "图片质量 (low, medium, high, origin)，默认为 origin",
"name": "quality",
"in": "query"
}
],
"responses": {
"200": {
"description": "成功下载文件",
"schema": {
"type": "file"
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "文件不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads/stats": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回系统级的总文件数、占用大小、最近 7 天新增趋势、文件类型/格式分布等数据",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取文件统计数据",
"responses": {
"200": {
"description": "获取成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/handler.fileStatsResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads/types": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回数据库中所有已上传文件实际拥有的业务类型列表",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取文件业务类型列表",
"responses": {
"200": {
"description": "业务类型列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/uploads/{id}": {
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "将文件状态置为 deleted（软删除），不会立即清理底层存储对象",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "删除文件",
"parameters": [
{
"type": "string",
"description": "文件 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无权操作",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "文件不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/users": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取用户列表",
"parameters": [
{
"minimum": 1,
"type": "integer",
"name": "page",
"in": "query"
},
{
"maximum": 100,
"minimum": 1,
"type": "integer",
"name": "page_size",
"in": "query"
},
{
"type": "integer",
"name": "user_id",
"in": "query"
},
{
"type": "string",
"name": "username",
"in": "query"
}
],
"responses": {
"200": {
"description": "用户列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/user.listUsersResponse"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "创建一个本地密码登录的新用户，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "创建用户",
"parameters": [
{
"description": "创建用户参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.createUserRequest"
}
}
],
"responses": {
"200": {
"description": "创建成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/user.user"
}
}
}
]
}
},
"400": {
"description": "参数错误或用户名已存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/users/{id}": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回指定用户的完整个人资料和系统状态，需要管理员权限，不返回密码等敏感字段",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "获取用户详情",
"parameters": [
{
"type": "integer",
"description": "用户 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "用户详情",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/user.user"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "用户不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "删除指定非管理员用户，需要管理员权限，不能删除当前登录用户",
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "删除用户",
"parameters": [
{
"type": "integer",
"description": "用户 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限、尝试删除管理员或当前用户",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "用户不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/admin/users/{id}/status": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "启用或禁用指定用户，管理员账号无法被禁用，需要管理员权限",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"admin"
],
"summary": "更新用户状态",
"parameters": [
{
"type": "integer",
"description": "用户 ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "状态参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.updateUserStatusRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无管理员权限或尝试禁用管理员",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "用户不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/config/public": {
"get": {
"description": "返回系统配置表中 visibility 为 1 的配置键值集合",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"config"
],
"summary": "获取公共配置",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/custom/hello": {
"get": {
"description": "A sample business API for customization",
"produces": [
"application/json"
],
"tags": [
"custom"
],
"summary": "Sample Hello API",
"responses": {
"200": {
"description": "成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
}
}
}
},
"/api/v1/oauth/callback": {
"post": {
"description": "接收前端传回的 state 和 code，完成 OAuth/OIDC 认证并建立会话。支持登录（login）和账号绑定（bind）两种场景。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "OAuth 回调处理",
"parameters": [
{
"description": "回调请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/oauth.CallbackRequest"
}
}
],
"responses": {
"200": {
"description": "登录或绑定成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.OAuthCallbackResult"
}
}
}
]
}
},
"400": {
"description": "state 无效、参数错误或认证源错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "绑定场景未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "OAuth 认证失败或内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/external-accounts": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前登录用户已绑定的所有外部 OAuth 帐号信息，需要登录",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取外部帐号列表",
"responses": {
"200": {
"description": "外部帐号列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.ExternalAccountView"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/external-accounts/{id}/delete": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "解除当前登录用户与指定外部帐号的绑定关系，需要登录",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "解除外部帐号绑定",
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "外部帐号绑定记录 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "解除绑定成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "ID 无效或解除失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/login": {
"get": {
"description": "根据指定认证源生成 OAuth 授权 URL，前端跳转到该 URL 完成 OAuth 登录授权。source 参数为空时使用第一个启用的认证源。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取登录授权地址",
"parameters": [
{
"type": "string",
"description": "认证源名称，为空使用第一个启用的认证源",
"name": "source",
"in": "query"
}
],
"responses": {
"200": {
"description": "授权 URL",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.OAuthAuthorizeResponse"
}
}
}
]
}
},
"400": {
"description": "认证源不存在或未配置",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "Redis 异常 or 构造 URL 失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/logout": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "清除当前用户的登录会话，完成退出。清除 Cookie 中的 Session 数据。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "退出登录",
"responses": {
"200": {
"description": "退出成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"500": {
"description": "Session 清除失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/sources": {
"get": {
"description": "返回当前系统已启用的所有 OAuth 登录源，前端展示登录按钮列表时调用",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取可用登录源",
"responses": {
"200": {
"description": "登录源列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/oauth.AuthSourceView"
}
}
}
}
]
}
}
}
}
},
"/api/v1/oauth/user-info": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取当前登录用户信息",
"responses": {
"200": {
"description": "用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/oauth/{source}/authorize": {
"get": {
"description": "根据指定认证源名称发起 OAuth 授权，支持 purpose 参数用于区分登录和账号绑定场景。认证源必须已启用。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "发起指定认证源授权",
"parameters": [
{
"type": "string",
"description": "认证源名称",
"name": "source",
"in": "path",
"required": true
},
{
"type": "string",
"description": "授权目的：login（登录）或 bind（绑定账号），默认 login",
"name": "purpose",
"in": "query"
}
],
"responses": {
"200": {
"description": "授权 URL",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.OAuthAuthorizeResponse"
}
}
}
]
}
},
"400": {
"description": "认证源不存在或未启用",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "Redis 异常或构造 URL 失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/upload": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "支持各种类型的通用文件上传，支持自动文件类型检测、哈希计算与“秒传”去重",
"consumes": [
"multipart/form-data"
],
"produces": [
"application/json"
],
"tags": [
"upload"
],
"summary": "上传文件",
"parameters": [
{
"type": "file",
"description": "要上传的文件",
"name": "file",
"in": "formData",
"required": true
},
{
"type": "string",
"description": "业务分类 (例如: avatar, attachment, doc，默认为 generic)",
"name": "type",
"in": "formData"
},
{
"type": "string",
"description": "额外的 JSON 格式元数据",
"name": "metadata",
"in": "formData"
}
],
"responses": {
"200": {
"description": "上传成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Upload"
}
}
}
]
}
},
"400": {
"description": "请求参数错误或文件受限",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/upload/my": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "分页获取当前登录用户上传的文件，支持文件名关键词、业务类型、扩展名过滤",
"produces": [
"application/json"
],
"tags": [
"upload"
],
"summary": "获取我的文件列表",
"parameters": [
{
"type": "integer",
"description": "页码（默认 1）",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "每页数量（默认 20，最大 100）",
"name": "page_size",
"in": "query"
},
{
"type": "string",
"description": "文件名关键词（模糊匹配）",
"name": "keyword",
"in": "query"
},
{
"type": "string",
"description": "业务分类过滤",
"name": "type",
"in": "query"
},
{
"type": "string",
"description": "扩展名过滤",
"name": "extension",
"in": "query"
}
],
"responses": {
"200": {
"description": "查询成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/handler.listMyFilesResponse"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/upload/{id}": {
"put": {
"security": [
{
"SessionCookie": []
}
],
"description": "更新当前用户本人的文件名或访问权限模式 (AccessMode)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"upload"
],
"summary": "更新我的文件信息",
"parameters": [
{
"type": "string",
"description": "文件 ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "更新字段",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/handler.updateMyFileRequest"
}
}
],
"responses": {
"200": {
"description": "更新成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/model.Upload"
}
}
}
]
}
},
"403": {
"description": "无权操作",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "文件不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "将当前用户本人的文件状态置为 deleted（软删除）",
"produces": [
"application/json"
],
"tags": [
"upload"
],
"summary": "删除我的文件",
"parameters": [
{
"type": "string",
"description": "文件 ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"403": {
"description": "无权操作",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "文件不存在",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user-info": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取当前登录用户信息",
"responses": {
"200": {
"description": "用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/access-tokens": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前登录用户的所有 active access tokens（脱敏后）",
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "获取当前用户的 AccessToken 列表",
"responses": {
"200": {
"description": "令牌列表",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/model.AccessToken"
}
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
},
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "为当前用户新建一个 API 访问令牌，仅在此接口返回一次明文令牌值，请妥善保存。可通过 is_admin 字段赋予令牌管理员权限（仅管理员用户可设置）。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "创建一个新的 AccessToken",
"parameters": [
{
"description": "令牌名称",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.createTokenRequest"
}
}
],
"responses": {
"200": {
"description": "新建令牌成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/user.tokenResponse"
}
}
}
]
}
},
"400": {
"description": "参数错误或超限",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/access-tokens/{id}": {
"delete": {
"security": [
{
"SessionCookie": []
}
],
"description": "撤销并删除一个属于当前用户的 API 访问令牌",
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "删除一个 AccessToken",
"parameters": [
{
"type": "string",
"description": "令牌ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "删除成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/access-tokens/{id}/rotate": {
"post": {
"security": [
{
"SessionCookie": []
}
],
"description": "轮换（重新生成）一个属于当前用户的 API 访问令牌的密钥，旧令牌将立即失效",
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "轮换一个 AccessToken",
"parameters": [
{
"type": "string",
"description": "令牌ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "令牌轮换成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/user.tokenResponse"
}
}
}
]
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/change-password": {
"post": {
"description": "修改当前登录用户的密码。修改成功后，如果是首次明文登录的升级提示，则清除修改密码的提示状态。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "修改用户密码",
"parameters": [
{
"description": "修改密码请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.changePasswordRequest"
}
}
],
"responses": {
"200": {
"description": "修改密码成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"400": {
"description": "原密码错误或新密码不符合要求",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "请先登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/login": {
"post": {
"description": "使用用户名和密码登录，登录成功后建立 Session。若管理员已关闭密码登录功能则返回错误。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "用户密码登录",
"parameters": [
{
"description": "登录请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.loginRequest"
}
}
],
"responses": {
"200": {
"description": "登录成功，返回用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"400": {
"description": "用户名或密码错误、帐号已禁用等",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/logout": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "清除用户登录 Session，完成退出",
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "用户退出登录",
"responses": {
"200": {
"description": "退出成功",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}
]
}
},
"500": {
"description": "Session 清除失败",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/profile": {
"put": {
"description": "修改当前登录用户的昵称、邮箱、头像、简介、电话、性别、个人网站和所在地。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "修改当前登录用户的个人资料",
"parameters": [
{
"description": "更新请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.updateProfileRequest"
}
}
],
"responses": {
"200": {
"description": "修改成功，返回更新后的用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"400": {
"description": "邮箱已被占用或参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/register": {
"post": {
"description": "使用用户名和密码注册新账号，注册成功后自动登录并建立 Session。密码长度不能少于 8 位。",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "用户注册",
"parameters": [
{
"description": "注册请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.registerRequest"
}
}
],
"responses": {
"200": {
"description": "注册并登录成功，返回用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"400": {
"description": "参数错误、用户名已存在或注册已关闭",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/self": {
"get": {
"security": [
{
"SessionCookie": []
}
],
"description": "返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。",
"produces": [
"application/json"
],
"tags": [
"oauth"
],
"summary": "获取当前登录用户信息",
"responses": {
"200": {
"description": "用户信息",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.Any"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
}
]
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/api/v1/user/send-email-code": {
"post": {
"description": "向指定邮箱发送验证码（用于注册场景）",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "发送邮箱验证码",
"parameters": [
{
"description": "发送验证码请求参数",
"name": "request",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.sendEmailCodeRequest"
}
}
],
"responses": {
"200": {
"description": "发送成功",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"400": {
"description": "参数错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/f/{id}": {
"get": {
"description": "根据文件 ID 获取并提供已上传的临时或正式文件，若配置了缓存则优先走本地缓存，否则从 S3 等后端存储读取并流式返回",
"produces": [
"application/octet-stream"
],
"tags": [
"upload"
],
"summary": "获取已上传文件",
"parameters": [
{
"type": "string",
"description": "文件 ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "图片质量 (low, medium, high, origin)，默认为 origin",
"name": "quality",
"in": "query"
}
],
"responses": {
"200": {
"description": "成功获取文件内容",
"schema": {
"type": "file"
}
},
"400": {
"description": "文件 ID 格式错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"401": {
"description": "未登录",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"404": {
"description": "文件未找到",
"schema": {
"$ref": "#/definitions/response.Any"
}
},
"500": {
"description": "服务内部错误",
"schema": {
"$ref": "#/definitions/response.Any"
}
}
}
}
},
"/robots.txt": {
"get": {
"description": "根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容",
"produces": [
"text/plain"
],
"tags": [
"config"
],
"summary": "获取 robots.txt",
"responses": {
"200": {
"description": "robots.txt 内容",
"schema": {
"type": "string"
}
}
}
}
}
},
"definitions": {
"auth_source.AuthSourceRequest": {
"type": "object",
"properties": {
"client_id": {
"type": "string"
},
"client_secret": {
"type": "string"
},
"display_name": {
"type": "string"
},
"icon_url": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"openid_discovery_url": {
"type": "string"
},
"scopes": {
"type": "string"
},
"type": {
"type": "string"
}
}
},
"auth_source.ToggleAuthSourceRequest": {
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
}
},
"cache.updateCacheConfigRequest": {
"type": "object",
"required": [
"max_size_mb",
"ttl_minutes"
],
"properties": {
"lru_enabled": {
"type": "boolean"
},
"max_size_mb": {
"type": "integer",
"minimum": 1
},
"ttl_minutes": {
"type": "integer",
"minimum": 0
}
}
},
"cap.ChallengeResponse": {
"type": "object",
"properties": {
"challenge": {
"type": "object",
"properties": {
"c": {
"type": "integer"
},
"d": {
"type": "integer"
},
"s": {
"type": "integer"
}
}
},
"expires": {
"description": "ms timestamp",
"type": "integer"
},
"token": {
"type": "string"
}
}
},
"cap.challengeRequest": {
"type": "object",
"properties": {
"scope": {
"type": "string"
}
}
},
"cap.redeemRequest": {
"type": "object",
"required": [
"solutions",
"token"
],
"properties": {
"scope": {
"type": "string"
},
"solutions": {
"type": "array",
"items": {
"type": "integer"
}
},
"token": {
"type": "string"
}
}
},
"db_manage.DBOverviewResponse": {
"type": "object",
"properties": {
"connections": {
"type": "integer"
},
"name": {
"type": "string"
},
"size": {
"type": "string"
},
"table_count": {
"type": "integer"
},
"type": {
"type": "string"
},
"version": {
"type": "string"
}
}
},
"db_manage.ExecuteSQLRequest": {
"type": "object",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "string"
}
}
},
"db_manage.ExecuteSQLResponse": {
"type": "object",
"properties": {
"affected_rows": {
"type": "integer"
},
"columns": {
"type": "array",
"items": {
"type": "string"
}
},
"execution_time_ms": {
"type": "integer"
},
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"type": {
"description": "\"select\" 或 \"exec\"",
"type": "string"
}
}
},
"diskcache.Status": {
"type": "object",
"properties": {
"base_path": {
"type": "string"
},
"keys_count": {
"type": "integer"
},
"lru_enabled": {
"type": "boolean"
},
"max_size_mb": {
"type": "integer"
},
"total_size": {
"type": "integer"
},
"ttl_minutes": {
"type": "integer"
}
}
},
"github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"expires": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"token": {
"type": "string"
}
}
},
"handler.batchDownloadRequest": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
}
},
"handler.distributionItem": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"name": {
"type": "string"
},
"size": {
"type": "integer"
}
}
},
"handler.fileStatsResponse": {
"type": "object",
"properties": {
"categories": {
"type": "array",
"items": {
"$ref": "#/definitions/handler.distributionItem"
}
},
"total_count": {
"type": "integer"
},
"total_size": {
"type": "integer"
},
"trend": {
"type": "array",
"items": {
"$ref": "#/definitions/handler.trendItem"
}
},
"types": {
"type": "array",
"items": {
"$ref": "#/definitions/handler.distributionItem"
}
}
}
},
"handler.listFilesResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/model.Upload"
}
},
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"handler.listMyFilesResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/definitions/model.Upload"
}
},
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"handler.trendItem": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"date": {
"type": "string"
},
"size": {
"type": "integer"
}
}
},
"handler.updateMyFileRequest": {
"type": "object",
"properties": {
"access_mode": {
"type": "integer",
"enum": [
0,
1
]
},
"file_name": {
"type": "string",
"maxLength": 255
}
}
},
"logger.LogEntry": {
"type": "object",
"properties": {
"data": {
"description": "一行日志原文（含换行符）",
"type": "string"
},
"index": {
"description": "全局递增序号",
"type": "integer"
}
}
},
"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": {
"has_more": {
"type": "boolean"
},
"lines": {
"type": "array",
"items": {
"$ref": "#/definitions/logger.LogEntry"
}
},
"next_cursor": {
"description": "用于加载更早日志的 cursor",
"type": "integer"
}
}
},
"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": {
"created_at": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_admin": {
"type": "boolean"
},
"masked_token": {
"type": "string"
},
"name": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"user_id": {
"type": "integer"
}
}
},
"model.AuthSource": {
"type": "object",
"properties": {
"client_id": {
"type": "string"
},
"client_secret_configured": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"display_name": {
"type": "string"
},
"icon_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"openid_discovery_url": {
"type": "string"
},
"scopes": {
"type": "string"
},
"type": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"model.ExternalAccountView": {
"type": "object",
"properties": {
"auth_source_id": {
"type": "integer"
},
"auth_source_label": {
"type": "string"
},
"auth_source_name": {
"type": "string"
},
"auth_source_type": {
"type": "string"
},
"created_at": {
"type": "string"
},
"email": {
"type": "string"
},
"external_username": {
"type": "string"
},
"id": {
"type": "integer"
}
}
},
"model.PushChannel": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"description": {
"description": "备注",
"type": "string"
},
"enabled": {
"description": "通道是否启用",
"type": "boolean"
},
"id": {
"type": "integer"
},
"name": {
"description": "通道名称，仅英文字母和下划线，唯一",
"type": "string"
},
"other": {
"description": "请求体/SMTP 密码等",
"type": "string"
},
"token": {
"description": "鉴权令牌或发信用户名等",
"type": "string"
},
"type": {
"description": "通道类型：custom, lark, email",
"type": "string"
},
"updated_at": {
"type": "string"
},
"url": {
"description": "请求地址，HTTPS 协议或 SMTP 地址",
"type": "string"
}
}
},
"model.PushEvent": {
"type": "object",
"properties": {
"channels": {
"description": "推送渠道列表，如 [\"lark\"]",
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string"
},
"enabled": {
"description": "是否启用",
"type": "boolean"
},
"event_key": {
"description": "如 admin_login",
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"description": "如 管理员登录",
"type": "string"
},
"targets": {
"description": "推送目标用户/邮箱列表",
"type": "array",
"items": {
"type": "string"
}
},
"task_type": {
"description": "关联的异步任务类型",
"type": "string"
},
"template": {
"description": "消息模板 JSON",
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"model.PushHistory": {
"type": "object",
"properties": {
"channel": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"error_msg": {
"type": "string"
},
"event_key": {
"type": "string"
},
"id": {
"type": "integer"
},
"level": {
"type": "string"
},
"status": {
"description": "success / failed",
"type": "string"
},
"target": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"model.Schedule": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"cron": {
"type": "string"
},
"id": {
"type": "string",
"example": "0"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"payload": {
"type": "string"
},
"task_type": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"model.SystemConfig": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"value": {
"type": "string"
},
"visibility": {
"type": "integer"
}
}
},
"model.TaskExecution": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"duration": {
"type": "integer"
},
"error_message": {
"type": "string"
},
"finished_at": {
"type": "string"
},
"id": {
"type": "string",
"example": "0"
},
"log": {
"type": "string"
},
"max_retry": {
"type": "integer"
},
"payload": {
"type": "string"
},
"result": {
"type": "string"
},
"retry_count": {
"type": "integer"
},
"retryable": {
"type": "boolean"
},
"started_at": {
"type": "string"
},
"status": {
"$ref": "#/definitions/model.TaskExecutionStatus"
},
"task_id": {
"type": "string"
},
"task_name": {
"type": "string"
},
"task_type": {
"type": "string"
},
"triggered_by": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"model.TaskExecutionStatus": {
"type": "string",
"enum": [
"pending",
"running",
"succeeded",
"failed"
],
"x-enum-varnames": [
"TaskExecutionStatusPending",
"TaskExecutionStatusRunning",
"TaskExecutionStatusSucceeded",
"TaskExecutionStatusFailed"
]
},
"model.Template": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_system": {
"type": "boolean"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"subject": {
"type": "string"
},
"type": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"model.Upload": {
"type": "object",
"properties": {
"access_mode": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"extension": {
"description": "文件后缀名 (不含点，如 png, pdf)",
"type": "string"
},
"file_name": {
"description": "原始文件名 (例如: image.png)",
"type": "string"
},
"file_path": {
"description": "文件相对路径 / S3 Key",
"type": "string"
},
"file_size": {
"description": "文件大小（字节）",
"type": "integer"
},
"hash": {
"description": "文件哈希 (SHA-256/MD5，可用于排重)",
"type": "string"
},
"id": {
"type": "string",
"example": "0"
},
"metadata": {
"description": "业务扩展元数据",
"allOf": [
{
"$ref": "#/definitions/model.UploadMetadata"
}
]
},
"mime_type": {
"description": "媒体类型 (MIME, 如 image/png)",
"type": "string"
},
"status": {
"description": "状态",
"allOf": [
{
"$ref": "#/definitions/model.UploadStatus"
}
]
},
"type": {
"description": "业务标识类型 (如 avatar, doc, attachment)",
"type": "string"
},
"updated_at": {
"type": "string"
},
"user_id": {
"type": "string",
"example": "0"
}
}
},
"model.UploadMetadata": {
"type": "object",
"properties": {
"bucket": {
"description": "存储桶名称 (适用于 S3 等)",
"type": "string"
},
"client_ip": {
"description": "上传者 IP",
"type": "string"
},
"duration": {
"description": "音视频时长 (s)",
"type": "number"
},
"extra": {
"description": "其它任意业务自定义元数据",
"type": "object",
"additionalProperties": {}
},
"height": {
"description": "图像/视频高度 (px)",
"type": "integer"
},
"original_mime": {
"description": "原始 MIME 类型",
"type": "string"
},
"user_agent": {
"description": "上传者的 UA",
"type": "string"
},
"width": {
"description": "图像/视频宽度 (px)",
"type": "integer"
}
}
},
"model.UploadStatus": {
"type": "string",
"enum": [
"pending",
"used",
"deleted"
],
"x-enum-comments": {
"UploadStatusDeleted": "已删除",
"UploadStatusPending": "待使用",
"UploadStatusUsed": "已使用"
},
"x-enum-descriptions": [
"待使用",
"已使用",
"已删除"
],
"x-enum-varnames": [
"UploadStatusPending",
"UploadStatusUsed",
"UploadStatusDeleted"
]
},
"oauth.AuthSourceView": {
"type": "object",
"properties": {
"client_secret_configured": {
"type": "boolean"
},
"display_name": {
"type": "string"
},
"icon_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
},
"oauth.BasicUserInfo": {
"type": "object",
"properties": {
"avatar_url": {
"type": "string"
},
"bio": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"id": {
"type": "integer"
},
"is_admin": {
"type": "boolean"
},
"location": {
"type": "string"
},
"need_change_password": {
"type": "boolean"
},
"nickname": {
"type": "string"
},
"phone": {
"type": "string"
},
"username": {
"type": "string"
},
"website": {
"type": "string"
}
}
},
"oauth.CallbackRequest": {
"type": "object",
"required": [
"code",
"state"
],
"properties": {
"code": {
"type": "string"
},
"state": {
"type": "string"
}
}
},
"oauth.OAuthAuthorizeResponse": {
"type": "object",
"properties": {
"authorize_url": {
"type": "string"
}
}
},
"oauth.OAuthCallbackResult": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"user": {
"$ref": "#/definitions/oauth.BasicUserInfo"
}
}
},
"push.Config": {
"type": "object",
"properties": {
"channel": {
"description": "渠道名称，例如 \"lark\", \"custom\", \"email\" 等，唯一标识",
"type": "string"
},
"ext": {
"description": "预留拓展 JSON 配置",
"type": "object",
"additionalProperties": {}
},
"key": {
"description": "AppID 或 SMTP 用户名",
"type": "string"
},
"secret": {
"description": "签名密钥或 SMTP 密码/Token",
"type": "string"
},
"url": {
"description": "Webhook 地址或 SMTP 地址",
"type": "string"
}
}
},
"push.CreateChannelRequest": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"name": {
"type": "string"
},
"other": {
"type": "string"
},
"token": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"push.CreateEventRequest": {
"type": "object",
"properties": {
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"event_key": {
"type": "string"
},
"targets": {
"type": "array",
"items": {
"type": "string"
}
},
"task_type": {
"description": "关联的异步任务类型",
"type": "string"
},
"template": {
"type": "string"
}
}
},
"push.Definition": {
"type": "object",
"properties": {
"description": {
"description": "short description",
"type": "string"
},
"fields": {
"description": "form fields",
"type": "array",
"items": {
"$ref": "#/definitions/push.Field"
}
},
"name": {
"description": "display name",
"type": "string"
},
"type": {
"description": "channel type (e.g., custom, lark, email)",
"type": "string"
}
}
},
"push.EventMetadata": {
"type": "object",
"properties": {
"default_template": {
"$ref": "#/definitions/push.NotificationMessage"
},
"description": {
"type": "string"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"push.Field": {
"type": "object",
"properties": {
"description": {
"description": "field explanation/help text",
"type": "string"
},
"key": {
"description": "unique key for the field (e.g. url, token, other)",
"type": "string"
},
"label": {
"description": "human readable label (e.g. \"Webhook 地址\")",
"type": "string"
},
"placeholder": {
"description": "input placeholder",
"type": "string"
},
"required": {
"description": "whether this field is required",
"type": "boolean"
},
"type": {
"description": "input type: \"text\" | \"password\" | \"textarea\"",
"type": "string"
}
}
},
"push.NotificationMessage": {
"type": "object",
"properties": {
"content": {
"type": "string"
},
"ext": {
"type": "object",
"additionalProperties": {}
},
"level": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"push.TestChannelRequest": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"other": {
"type": "string"
},
"target": {
"type": "string"
},
"token": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"push.TestPushRequest": {
"type": "object",
"required": [
"config"
],
"properties": {
"config": {
"$ref": "#/definitions/push.Config"
},
"target": {
"type": "string"
}
}
},
"push.UpdateChannelRequest": {
"type": "object",
"required": [
"type"
],
"properties": {
"description": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"other": {
"type": "string"
},
"token": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"push.UpdateEventRequest": {
"type": "object",
"required": [
"template"
],
"properties": {
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"targets": {
"type": "array",
"items": {
"type": "string"
}
},
"template": {
"type": "string"
}
}
},
"push.pushHistoriesResponse": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/definitions/model.PushHistory"
}
},
"total": {
"type": "integer"
}
}
},
"response.Any": {
"type": "object",
"properties": {
"data": {},
"error_msg": {
"type": "string",
"example": ""
}
}
},
"status.DatabaseInfoResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"version": {
"type": "string"
}
}
},
"status.SystemStatusResponse": {
"type": "object",
"properties": {
"alloc": {
"type": "string"
},
"buck_hash_sys": {
"type": "string"
},
"frees": {
"type": "integer"
},
"gc_sys": {
"type": "string"
},
"heap_alloc": {
"type": "string"
},
"heap_idle": {
"type": "string"
},
"heap_inuse": {
"type": "string"
},
"heap_objects": {
"type": "integer"
},
"heap_released": {
"type": "string"
},
"heap_sys": {
"type": "string"
},
"last_gc_time": {
"type": "string"
},
"last_pause": {
"type": "string"
},
"lookups": {
"type": "integer"
},
"mallocs": {
"type": "integer"
},
"mcache_inuse": {
"type": "string"
},
"mcache_sys": {
"type": "string"
},
"mspan_inuse": {
"type": "string"
},
"mspan_sys": {
"type": "string"
},
"next_gc": {
"type": "string"
},
"num_gc": {
"type": "integer"
},
"num_goroutine": {
"type": "integer"
},
"other_sys": {
"type": "string"
},
"pause_total_ns": {
"type": "string"
},
"stack_inuse": {
"type": "string"
},
"stack_sys": {
"type": "string"
},
"sys": {
"type": "string"
},
"total_alloc": {
"type": "string"
},
"uptime": {
"type": "string"
}
}
},
"system_config.CreateSystemConfigRequest": {
"type": "object",
"required": [
"key",
"type",
"value"
],
"properties": {
"description": {
"type": "string",
"maxLength": 255
},
"key": {
"type": "string",
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"system",
"business"
]
},
"value": {
"type": "string"
},
"visibility": {
"type": "integer",
"enum": [
0,
1
]
}
}
},
"system_config.TestSMTPRequest": {
"type": "object",
"required": [
"smtp_host",
"smtp_password",
"smtp_port",
"smtp_username",
"to"
],
"properties": {
"smtp_host": {
"type": "string",
"maxLength": 255
},
"smtp_password": {
"type": "string",
"maxLength": 255
},
"smtp_port": {
"type": "integer"
},
"smtp_username": {
"type": "string",
"maxLength": 255
},
"to": {
"type": "string"
}
}
},
"system_config.TestSMTPResponse": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"log": {
"type": "string"
},
"success": {
"type": "boolean"
}
}
},
"system_config.UpdateSystemConfigRequest": {
"type": "object",
"required": [
"value"
],
"properties": {
"description": {
"type": "string",
"maxLength": 255
},
"value": {
"type": "string"
},
"visibility": {
"type": "integer",
"enum": [
0,
1
]
}
}
},
"task.CreateScheduleRequest": {
"type": "object",
"required": [
"cron",
"is_active",
"name",
"task_type"
],
"properties": {
"cron": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"payload": {
"type": "string"
},
"task_type": {
"type": "string"
}
}
},
"task.DispatchTaskRequest": {
"type": "object",
"required": [
"task_type"
],
"properties": {
"end_time": {
"type": "string"
},
"payload": {
"type": "string"
},
"start_time": {
"type": "string"
},
"task_type": {
"type": "string"
},
"user_id": {
"type": "integer"
}
}
},
"task.TaskMeta": {
"type": "object",
"properties": {
"asynq_task": {
"type": "string"
},
"description": {
"type": "string"
},
"max_retry": {
"type": "integer"
},
"name": {
"type": "string"
},
"params": {
"type": "array",
"items": {
"$ref": "#/definitions/task.TaskParam"
}
},
"queue": {
"type": "string"
},
"retryable": {
"description": "是否支持手动重试",
"type": "boolean"
},
"supports_time": {
"type": "boolean"
},
"type": {
"type": "string"
}
}
},
"task.TaskParam": {
"type": "object",
"properties": {
"description": {
"description": "描述",
"type": "string"
},
"label": {
"description": "显示名称",
"type": "string"
},
"name": {
"description": "参数键名",
"type": "string"
},
"placeholder": {
"description": "占位符",
"type": "string"
},
"required": {
"description": "是否必填",
"type": "boolean"
},
"type": {
"description": "类型：string, text, number, boolean",
"type": "string"
}
}
},
"task.UpdateScheduleRequest": {
"type": "object",
"required": [
"cron",
"is_active",
"name",
"task_type"
],
"properties": {
"cron": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"name": {
"type": "string"
},
"payload": {
"type": "string"
},
"task_type": {
"type": "string"
}
}
},
"template.CreateTemplateRequest": {
"type": "object",
"required": [
"content",
"key",
"name",
"type"
],
"properties": {
"content": {
"type": "string"
},
"description": {
"type": "string",
"maxLength": 255
},
"key": {
"type": "string",
"maxLength": 80
},
"name": {
"type": "string",
"maxLength": 100
},
"subject": {
"type": "string",
"maxLength": 255
},
"type": {
"type": "string",
"maxLength": 20
}
}
},
"template.UpdateTemplateRequest": {
"type": "object",
"required": [
"content",
"name",
"type"
],
"properties": {
"content": {
"type": "string"
},
"description": {
"type": "string",
"maxLength": 255
},
"name": {
"type": "string",
"maxLength": 100
},
"subject": {
"type": "string",
"maxLength": 255
},
"type": {
"type": "string",
"maxLength": 20
}
}
},
"updater.Status": {
"type": "object",
"properties": {
"asset_name": {
"type": "string"
},
"build_time": {
"type": "string"
},
"can_upgrade": {
"type": "boolean"
},
"current_version": {
"type": "string"
},
"latest_version": {
"type": "string"
},
"platform": {
"type": "string"
},
"prerelease": {
"type": "boolean"
},
"published_at": {
"type": "string"
},
"release_name": {
"type": "string"
},
"release_notes": {
"type": "string"
},
"release_url": {
"type": "string"
},
"update_available": {
"type": "boolean"
},
"upstream_repository": {
"type": "string"
}
}
},
"user.changePasswordRequest": {
"type": "object",
"properties": {
"new_password": {
"type": "string"
},
"old_password": {
"type": "string"
}
}
},
"user.createTokenRequest": {
"type": "object",
"properties": {
"is_admin": {
"type": "boolean"
},
"name": {
"type": "string"
}
}
},
"user.createUserRequest": {
"type": "object",
"required": [
"email",
"password",
"username"
],
"properties": {
"email": {
"type": "string",
"maxLength": 255
},
"is_active": {
"type": "boolean"
},
"is_admin": {
"type": "boolean"
},
"nickname": {
"type": "string",
"maxLength": 64
},
"password": {
"type": "string",
"maxLength": 64,
"minLength": 8
},
"username": {
"type": "string",
"maxLength": 64,
"minLength": 3
}
}
},
"user.listUsersResponse": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"users": {
"type": "array",
"items": {
"$ref": "#/definitions/user.user"
}
}
}
},
"user.loginRequest": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"user.registerRequest": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"display_name": {
"type": "string"
},
"email": {
"type": "string"
},
"nickname": {
"type": "string"
},
"password": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"user.sendEmailCodeRequest": {
"type": "object",
"required": [
"email",
"scene"
],
"properties": {
"email": {
"type": "string"
},
"scene": {
"type": "string"
}
}
},
"user.tokenResponse": {
"type": "object",
"properties": {
"record": {
"$ref": "#/definitions/model.AccessToken"
},
"token": {
"type": "string"
}
}
},
"user.updateProfileRequest": {
"type": "object",
"properties": {
"avatar_url": {
"type": "string"
},
"bio": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"location": {
"type": "string"
},
"nickname": {
"type": "string"
},
"phone": {
"type": "string"
},
"website": {
"type": "string"
}
}
},
"user.updateUserStatusRequest": {
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
}
},
"user.user": {
"type": "object",
"properties": {
"avatar_url": {
"type": "string"
},
"bio": {
"type": "string"
},
"created_at": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"id": {
"type": "string",
"example": "0"
},
"is_active": {
"type": "boolean"
},
"is_admin": {
"type": "boolean"
},
"last_login_at": {
"type": "string"
},
"location": {
"type": "string"
},
"nickname": {
"type": "string"
},
"phone": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"username": {
"type": "string"
},
"website": {
"type": "string"
}
}
}
},
"securityDefinitions": {
"SessionCookie": {
"type": "apiKey",
"name": "session",
"in": "cookie"
}
}
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "1.0.0",
Host: "",
BasePath: "/",
Schemes: []string{},
Title: "Wavelet API",
Description: "Wavelet 平台后端 API，提供用户认证、系统配置、任务调度等通用功能。",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
RightDelim: "}}",
}
func init() {
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
Reference in New Issue View Git Blame Copy Permalink