# 定时任务 UI 参考

> 适用范围：定时任务列表、配置工作台、执行日志、告警、开放 Token、出站策略和流程绑定页面。
> 目标用户：平台运维人员、业务配置人员、集成开发人员。

## 1. 当前页面为什么难懂

当前页面以数据库字段和 Quartz 技术概念组织信息：

- 列表直接展示 Bean 名称、方法名、Handler 和 Cron 表达式，用户难以先判断“任务做什么、什么时候执行、是否正常”。
- 新增/编辑在一个宽弹窗中连续堆放基本信息、执行配置、Cron、高级配置、邮箱和 Webhook，缺少明确的操作主线。
- Cron 只能手输或从硬编码表达式列表选择，没有自然语言结果和未来执行时间反馈。
- “清理 7 天前日志”和“清空所有日志”位于任务首页顶部，危险维护动作抢占了主要操作位置。
- 一行同时出现编辑、启动、停止、运行一次、运行日志、删除，扫描和选择成本高。
- 日志放在大弹窗中并横向滚动，直接展示 Handler、任务参数和完整异常，既难读也存在敏感信息风险。

对应代码入口：

- forge-admin-ui/src/views/system/job-config.vue
- forge-admin-ui/src/views/system/job-log-list.vue

## 2. 设计目标

用户进入任务中心后，应能在不理解 Cron、Bean 或 Handler 的情况下完成以下判断：

1. 这个任务负责什么。
2. 它什么时候执行。
3. 当前是启用、停用、已结束还是同步异常。
4. 最近一次是否成功，下一次什么时候执行。
5. 如何编辑、立即运行、暂停和查看日志。

技术字段仍保留给平台开发人员，但默认进入“高级设置”，不作为普通操作主线。

## 3. 信息架构

### 3.1 任务列表

任务首页只承担“查找、判断状态、执行高频动作”：

~~~text
┌──────────────────────────────────────────────────────────────────────────┐
│ 定时任务                                      [筛选] [刷新] [+ 新建任务] │
├──────────────────────────────────────────────────────────────────────────┤
│ 搜索任务  [分组] [状态] [执行方式]                         [重置] [查询] │
├──────────────────────────────────────────────────────────────────────────┤
│ 任务              执行内容        执行计划       状态    下次执行   操作 │
│ 库存日结          库存日结处理器  每天 02:00     运行中  明天02:00  ... │
│ 订单同步          订单同步处理器  每 10 分钟     异常    --         ... │
└──────────────────────────────────────────────────────────────────────────┘
~~~

默认列：

- 任务：任务名称 + 分组。
- 执行内容：处理器展示名称或自然语言摘要。
- 执行计划：例如“每天 02:00”“每 10 分钟”“2026-07-20 09:00 执行一次”。
- 状态：启用、停用、已结束；同步失败单独展示异常标识。
- 下次执行：使用用户时区格式化。
- 最近结果：成功、失败、跳过、运行中。
- 操作：编辑、立即运行、日志为高频动作；启停、同步重试、删除进入更多菜单。

不在默认列展示 Bean、方法名、Handler 编码、Cron 原文和完整异常。这些字段进入详情或高级设置。

### 3.2 任务配置工作台

复杂配置使用独立路由和全屏工作台，不使用通用 CRUD 弹窗：

~~~text
┌──────────────────────────────────────────────────────────────────────────┐
│ ← 返回任务列表   新建任务 / 库存日结        未保存      [取消] [保存]  │
├──────────────┬──────────────────────────────────────┬────────────────────┤
│ 基本信息     │ 任务名称                             │ 配置摘要           │
│ 执行内容     │ 任务分组                             │ 执行：库存日结     │
│ 执行计划     │ 任务说明                             │ 计划：每天 02:00   │
│ 高级设置     │                                      │ 状态：保存后启用   │
│              │ 当前分区的实际表单                   │                    │
│              │                                      │ 未来执行           │
│              │                                      │ 07-20 02:00        │
│              │                                      │ 07-21 02:00        │
└──────────────┴──────────────────────────────────────┴────────────────────┘
~~~

- 顶部固定：返回、任务名称、保存状态、取消和保存。
- 左侧导航宽度稳定，分为基本信息、执行内容、执行计划、高级设置。
- 中间是当前配置区，使用分隔线组织，不嵌套卡片。
- 右侧是实时摘要和未来 5 次执行时间；窄屏移动到表单下方。
- 离开存在未保存改动的页面时使用项目现有 dirty tab 和路由离开确认。

## 4. 各区域交互

### 4.1 基本信息

- 任务名称：面向用户的展示名称。
- 任务分组：使用可搜索选择器，允许输入已有分组；不要求用户理解 DEFAULT。
- 任务说明：简短描述业务目的。
- 任务标识：编辑时只读，放在高级信息中，不让用户误以为可以随意改名。

### 4.2 执行内容

默认入口是选择“任务处理器”，数据来自后端注册目录：

~~~text
执行方式  [任务处理器] [本地服务方法] [远程服务]

任务处理器  [库存日结                                  v]
             库存日结
             每日汇总库存流水并生成日结结果
~~~

- HANDLER 对用户显示为“任务处理器”，优先使用可搜索目录选择，不手填编码。
- BEAN 显示为“本地服务方法”，Bean 和方法字段只对技术配置人员展开。
- RPC 显示为“远程服务”，服务名和处理器字段放在高级执行设置。
- 已有但未进入注册目录的历史目标显示“历史配置”，允许只读回显和技术人员修正。
- 任务参数提供 JSON 编辑器、格式化和即时校验；普通用户未配置参数时不显示空代码框。

### 4.3 执行计划

默认进入简单模式：

~~~text
计划方式  [简单设置] [Cron 专家模式]

执行频率  [每天 v]
执行时间  [02:00]

结果：每天 02:00 执行
下次：07-20 02:00、07-21 02:00、07-22 02:00……
~~~

简单设置支持：

- 每隔 N 分钟。
- 每小时的第 N 分钟。
- 每天指定时间。
- 每周选择星期和时间。
- 每月选择日期和时间。

专家模式：

- 直接编辑 Quartz 6 段表达式。
- 显示服务端校验结果和未来 5 次执行时间。
- 无法安全反解析时保持原表达式并进入专家模式，不覆盖数据。

V3 增加一次性任务和时区后，调度类型先选择“周期执行/执行一次”，再显示对应字段；普通用户不需要看到 CRON/ONCE 枚举值。

### 4.4 保存状态

- 新建任务默认“保存后停用”，避免配置未验证即运行。
- 用户可以显式选择“保存后启用”。
- 保存按钮在校验失败时保持可点击并聚焦首个错误，不能静默无反应。
- 保存成功后明确返回“配置已保存，调度同步成功”或“配置已保存，调度同步失败，可重新同步”。
- 同步失败不能只显示通用错误 Toast，页面摘要区和任务列表都要保留可见状态。

## 5. 术语映射

| 技术字段 | 默认用户文案 | 展示位置 |
|---|---|---|
| executeMode | 执行方式 | 执行内容 |
| HANDLER | 任务处理器 | 默认选项 |
| BEAN | 本地服务方法 | 技术配置 |
| RPC | 远程服务 | 技术配置 |
| executorHandler | 处理器 | 选择目录/高级信息 |
| executorBean | 服务 Bean | 高级信息 |
| executorMethod | 执行方法 | 高级信息 |
| cronExpression | Cron 表达式 | 专家模式 |
| scheduleType=CRON | 周期执行 | 执行计划 |
| scheduleType=ONCE | 执行一次 | 执行计划 |
| misfirePolicy | 错过执行处理 | 运行策略 |
| FIRE_ONCE_NOW | 系统恢复后补执行一次 | 运行策略 |
| DO_NOTHING | 等待下一次计划 | 运行策略 |
| SKIP_IF_RUNNING | 上一轮未结束时跳过 | 运行策略 |
| syncStatus=FAILED | 调度同步失败 | 状态与列表 |
| triggerType=MANUAL | 手动运行 | 日志 |
| triggerType=SCHEDULED | 计划触发 | 日志 |

## 6. 操作层级

任务行高频操作：

- 编辑：铅笔图标 + 文案。
- 立即运行：播放图标 + 文案，确认框展示任务名和当前计划，不修改启停状态。
- 查看日志：日志图标 + 文案。

更多菜单：

- 启用/停用。
- 重新同步，仅同步失败时显示。
- 删除，使用红色危险操作并二次确认。

全局日志清理不放在任务首页主操作区。V5 实施后放入日志页“数据维护”菜单；V5 之前保留在页面更多菜单中，不与“新建任务”并列。

## 7. 日志页面

V5 将日志从大弹窗迁移为独立页面：

- 顶部组合筛选：任务、状态、来源、时间范围。
- 默认列：任务、状态、来源、开始时间、耗时、重试次数。
- 点击行在右侧详情抽屉展示执行时间线、结果摘要和错误摘要。
- Handler、fireInstanceId 等技术字段放入“技术信息”折叠区。
- 任务参数和完整异常按敏感详情权限加载，不直接进入列表响应。

## 8. 后续版本的 UI 落位

| 版本 | UI 增量 |
|---|---|
| V1 | 列表增加调度同步状态和重新同步反馈，不重做整体布局 |
| V2 | 完成任务列表重构、全屏配置工作台、处理器目录、Cron 简单/专家模式 |
| V3 | 在执行计划区增加周期执行/执行一次和时区 |
| V4 | 在高级设置增加并发、重试和错过执行处理，危险重试需明确确认 |
| V5 | 独立日志页、详情抽屉、导出和轻量监控摘要 |
| V6 | 告警配置和按权限显示操作 |
| V7 | 独立 Token 管理页，明文只在创建结果弹窗显示一次 |
| V8 | 克制的出站白名单主从配置工作台 |
| V9 | 执行内容区选择已发布流程名称和固定版本 |

## 9. 视觉与响应式约束

- 使用 Forge 当前主题变量、Naive UI 和现有 Iconify/vicons 图标，不建立独立橙色或绿色主题。
- 页面保持企业控制台风格：高信息密度、清晰边框、8px 以内圆角、无渐变背景和装饰性动效。
- 不使用卡片嵌套卡片；工作台分区用页面列、分隔线和稳定宽度表达。
- 桌面宽度大于 1280px 时使用左导航 + 主表单 + 摘要；中等宽度隐藏左侧说明，仅保留锚点；移动端单列并固定底部保存操作。
- 所有按钮文本和状态标签必须完整显示，不能因列宽截断关键动作。
- 支持键盘焦点、表单错误聚焦、色彩之外的状态图标和文案。

## 10. UI 验收场景

1. 用户不输入 Cron，只通过简单设置创建“每天 02:00 执行”的停用任务。
2. 用户从处理器目录选择任务并看懂其业务描述，不手填 Handler 编码。
3. 用户打开复杂历史 Cron，表达式保持不变并显示未来执行时间。
4. 用户保存后能区分“保存成功并同步成功”和“保存成功但同步失败”。
5. 用户能从列表完成立即运行、停用和查看日志，不在六个并列操作中寻找。
6. 用户误触删除或日志清理时必须经过明确二次确认。
7. 1366×768、1920×1080 和移动宽度下无按钮、标签或表单重叠。