定时任务前端底座:接口约定的类型、api.schedules、页面用的纯函数和文案

types.ts 末尾一段写定时任务的接口约定(Schedule、Fire、预览、变量、立即运行、触发历史、Webhook 测试),字段名和形状照前后端共用的约定,不各自发挥;运行列表的 schedule_id 用同名接口合并补在这一段,不去改上面 Run 的定义。

api/schedules.ts 挂上全部接口:列表、详情、新建、修改(只带改了的字段和读到的版本)、删除、预览(可取消,丢掉过时的请求)、变量、立即运行、触发历史分页、发送测试消息。

pages/schedules/model.ts 是不碰 React 的纯函数:
- 频率预设和 cron 互转:每天 / 每周(连着三天以上写区间)/ 每月 / 每隔几小时(只给 24 的约数,*/5 在跨天处会断)/ 自定义;填得不完整时返回空串,不拿猜出来的频率顶上;认不出的 cron 一律算自定义、原文照放
- 按定时任务自己的时区写时间(Intl 取各段再拼中文,周几、偏移照算),本机时区另给;距下次运行先取整再判档
- 表单和请求体互转:修改时和打开时的表单比,只交改了的字段(cron 写法不同但人没动不算改);Webhook 按约定地址省略即不改、空串即删除,密钥省略即不改、空串即清除,交 Webhook 时格式和事件总是一起交
- 表单的问题按字段给出,写在对应的输入框下

terms.ts 的 SCHEDULE_TEXT 写全定时任务页的文案;占位页的两条先留着,换成真页面时删掉。「钉钉」是 Webhook 的产品名,会被「钉住」那条规则误报,在 copy-allow.json 里登记一条例外并写明理由。
This commit is contained in:
ThearchyHelios
2026-10-05 08:56:02 +08:00
parent 26595b70f7
commit 4deffd62f7
5 changed files with 951 additions and 3 deletions
+35 -2
View File
@@ -1,7 +1,40 @@
/**
* 定时任务的接口(/api/schedules)。现在是空的,定时任务的工作包往里加,挂在 api.schedules 上。
* 定时任务的接口(/api/schedules),挂在 api.schedules 上。字段名和形状照前后端共用的接口约定(types.ts 末尾那一段)。
*
* 请求函数(get / post / del……)和 ApiError 从 ./http 导入,不要从 ./client 导入:client.ts 要导入
* 这个文件把它挂到 api 上,反过来导入就成了循环(见 http.ts 开头的说明)。
*
* 错误都是 ApiError,message 是服务端给的中文 detail:修改时版本不符回 409,预览非法回 422 且 field 指明是
* cron / timezone / input_template 哪一项(ApiError.field)。老服务端没有这些接口,回 404 且没有 code
*/
export const schedules = {}
import type {
Schedule, ScheduleCreate, ScheduleFirePage, SchedulePatch, SchedulePreview, SchedulePreviewRequest, ScheduleRunResult,
ScheduleVariable, ScheduleWebhookTest,
} from '../types'
import { del, get, patch, post, qs, request, type RequestOptions } from './http'
const at = (id: string) => `/schedules/${encodeURIComponent(id)}`
export const schedules = {
list: (opts?: RequestOptions) => get<{ items: Schedule[] }>('/schedules', opts),
get: (id: string, opts?: RequestOptions) => get<Schedule>(at(id), opts),
create: (body: ScheduleCreate) => post<Schedule>('/schedules', body),
/** 只带改了的字段和读到的版本;Webhook 的地址省略表示不改、空串表示删除 */
update: (id: string, body: SchedulePatch) => patch<Schedule>(at(id), body),
remove: (id: string) => del(at(id)),
/**
* 接下来几次触发时间和渲染出的输入,只算不存。signal 用来丢掉过时的请求:频率还在改、又发了新的一次时,
* 上一次的答复不再要(取消照旧抛 AbortError)
*/
preview: (body: SchedulePreviewRequest, opts?: { signal?: AbortSignal }) =>
request<SchedulePreview>('/schedules/preview', { method: 'POST', body: JSON.stringify(body), signal: opts?.signal }),
/** 输入模板里能用的变量(schedule.yesterday 这类),按触发时间计算 */
variables: (opts?: RequestOptions) => get<ScheduleVariable[]>('/schedules/variables', opts),
/** 立即运行一次:记一条手动触发,上一次还没结束时照样按重叠策略跳过 */
run: (id: string) => post<ScheduleRunResult>(`${at(id)}/run`),
/** 触发历史,新的在前。before 是上一页给的 next_before */
fires: (id: string, page?: { limit?: number; before?: string | null }, opts?: RequestOptions) =>
get<ScheduleFirePage>(`${at(id)}/fires${qs(page)}`, opts),
/** 用已保存的 Webhook 设置发一条测试消息(不用页面上还没保存的) */
testWebhook: (id: string) => post<ScheduleWebhookTest>(`${at(id)}/webhook/test`),
}