# OmniScheduler 产品需求与交互说明书 (PRD)

## 1. 产品概述
**OmniScheduler** 是一款专为 Windows 系统设计的本地高级任务调度与消息推送管理软件。其核心目标是允许用户创建高度灵活的定时/计时规则，并在规则触发时，向本地环境的 `OmniNotify` 软件标准 API 发送结构化的 JSON 消息（包含频道、标题、内容）。
产品风格定位为**技术工具型软件**，追求逻辑严密性、高信息密度、无干扰的后台运行体验以及所见即所得的日志反馈。

## 2. 核心术语
*   **任务 (Task)**：一个完整的调度单元，包含基础信息、触发器和消息载荷。
*   **触发器 (Trigger)**：定义任务何时运行的时间规则（如固定时间、间隔、Cron表达式等）。
*   **消息载荷 (Payload)**：触发时向 OmniNotify 发送的具体内容，由 `channel`（频道）、`title`（标题）、`body`（内容）组成。
*   **补偿策略 (Misfire Strategy)**：当系统休眠或关机导致错过了原定触发时间后，系统恢复时如何处理这些错过的触发。

---

## 3. 核心功能需求

### 3.1 任务管理 (Task Management)
*   **任务属性**：
    *   **任务名称**：必填，用于在列表中识别任务。
    *   **任务描述**：选填，用于记录任务用途的备忘。
    *   **状态开关**：启用 (Enabled) / 禁用 (Disabled)。禁用状态下的任务不会触发。
*   **列表操作**：支持新建、编辑、删除、克隆（复制现有任务以便微调）、立即手动执行一次（用于测试）。

### 3.2 触发器配置引擎 (Trigger Engine)
为满足“丰富的可配置性”，一个任务允许配置**单个或多个**触发器。支持以下触发器类型：
1.  **单次执行 (One-Time)**：指定未来的某一个具体日期和时间点。
2.  **固定间隔 (Simple Interval)**：
    *   配置项：每隔 `X` [秒/分钟/小时/天] 执行一次。
    *   附加项：可设置“起始生效时间”和“结束失效时间”。
3.  **每日/每周/每月定时 (Calendar Scheduled)**：
    *   每日：每天 `HH:mm:ss` 执行（可添加多个时间点）。
    *   每周：勾选周一至周日，在选定日的 `HH:mm:ss` 执行。
    *   每月：每月的第 `X` 天 或 每月的“最后一个工作日”的 `HH:mm:ss` 执行。
4.  **高级规则 (Cron Expression)** *(技术向特色功能)*：
    *   允许用户直接输入标准的 Cron 表达式（如 `0 0/5 14 * * ?`）。
    *   UI 需提供 Cron 表达式的“未来5次执行时间”的实时预览，方便用户自测。

**高级调度设置（补偿策略）**：
*   当系统从休眠中唤醒，发现错过了某次执行时，用户可配置：
    *   *忽略 (Do Nothing)*：当作没发生，等待下一个周期。
    *   *立即补偿 (Fire Once Now)*：立即补发一次消息，随后恢复正常计划。

### 3.3 消息载荷配置 (Payload Configuration)
任务触发后生成的 JSON 数据配置区：
*   **频道 (Channel)**：单行文本输入框。提示用户“必须与 OmniNotify 控制面板中已创建的频道一致，否则将被 OmniNotify 拦截”。
*   **标题 (Title)**：单行文本输入框。
*   **内容 (Body)**：多行文本输入框，支持自动换行。
*   **动态变量支持 (Dynamic Variables)** *(技术向特色功能)*：
    *   允许在 Title 和 Body 中使用预设变量，以丰富消息内容。
    *   例如：`{CurrentTime}` (当前时间), `{TaskName}` (任务名称), `{TriggerType}` (触发类型)。在发送时自动替换为真实值。

### 3.4 运行日志与审计 (Execution Logs)
*   **本地日志记录**：记录每一次任务触发的详细情况。
*   **日志字段**：时间戳、任务名称、触发类型、目标 URL、HTTP 响应状态码（成功为 200，失败/拒绝需标红）、响应耗时。
*   **详情查阅**：点击单条日志可查看实际发出的完整 JSON 请求体及接收方的响应。

---

## 4. 界面与交互规范 (UI/UX)

整体 UI 风格向 Visual Studio、Postman 或 Windows 本地管理工具（MMC）靠拢。采用高对比度、紧凑的数据表格布局，支持 Windows 系统的深色/浅色模式切换。

### 4.1 主窗口布局 (Main Dashboard)
主界面采用 **“上下分栏 (Split View)”** 布局：

*   **顶部工具栏 (Toolbar)**：
    *   包含图标按钮：`新建任务`、`编辑`、`删除`、`克隆`、`手动触发`、`全局设置`。
*   **上半部分：任务列表区 (DataGrid)**：
    *   以数据表格形式展示。
    *   列包含：状态 (Toggle Switch)、任务名称、频道、触发规则简述、上次运行时间、下次运行时间、最近一次状态 (成功/失败指示灯)。
    *   支持按列头点击排序。
*   **下半部分：执行日志区 (Log Console)**：
    *   类似控制台输出，按时间倒序滚动显示近期日志。
    *   分为 `INFO` (正常发送) 和 `ERROR` (发送失败或 OmniNotify 未启动/拒收)。
    *   提供“清空日志”按钮。

### 4.2 任务编辑窗口 (Task Editor Modal)
采用 **“左侧导航树 + 右侧属性面板”** 或 **“多标签页 (Tabs)”** 形式：

*   **Tab 1: 常规 (General)**
    *   输入任务名称、描述，以及启用/禁用状态开关。
*   **Tab 2: 触发器 (Triggers)**
    *   左侧列出该任务已添加的触发器，右侧为具体配置表单。
    *   下拉菜单选择触发器类型（间隔、每日、Cron等），下方表单根据类型动态切换。
    *   最底部折叠面板提供“错过触发补偿策略”设置。
*   **Tab 3: 消息动作 (Action/Payload)**
    *   **目标地址**：默认只读显示 `http://127.0.0.1:19845/notify`（随全局设置变动）。
    *   **载荷表单**：
        *   Channel (带输入历史记忆的下拉文本框)
        *   Title
        *   Body
    *   **测试按钮**：提供一个 `Send Test Message` 按钮，点击后立即使用当前填写的 Channel/Title/Body 向 OmniNotify 发送一次请求，并在旁边气泡提示成功或失败，无需保存任务即可验证频道是否合法。

### 4.3 托盘与后台交互 (System Tray)
*   **最小化到托盘**：由于是定时软件，点击主窗口的“关闭”按钮默认不退出程序，而是隐藏到系统托盘 (System Tray)。
*   **托盘右键菜单**：
    *   打开主界面 (Open Dashboard)
    *   快速暂停所有任务 (Pause All Tasks)
    *   退出 (Exit)
*   **静默运行**：软件启动和运行时不应有任何强制弹窗打扰用户，所有通知全权交由 OmniNotify 处理。

---

## 5. 全局设置 (Global Settings)

在独立的“设置”弹窗中提供以下全局配置：
1.  **开机自启动**：跟随 Windows 登录启动（最小化到托盘）。
2.  **OmniNotify API 地址**：默认值为 `http://127.0.0.1:19845/notify`。提供修改入口，以防未来 OmniNotify 端口或地址发生变更。
3.  **日志保留策略**：防止本地日志无限膨胀，例如“保留最近 30 天的日志”或“最多保留 10000 条记录”。

## 6. 异常流与边界说明 (Exception Flows)

1.  **OmniNotify 未运行或端口被占用**：
    *   触发器正常到点执行，但网络请求失败。
    *   系统不应弹窗报错（避免积压成百上千个弹窗导致死机），只需在“执行日志区”静默记录一条标红的 `ERROR` 日志（如 `Connection Refused`）。
2.  **OmniNotify 频道校验失败 (`IllegalChannel`)**：
    *   触发器正常执行，网络请求发出。
    *   收到 HTTP 状态异常（或特定拒收报文）。
    *   日志区记录 `ERROR: IllegalChannel`，提示用户检查 OmniScheduler 中的频道名配置。
3.  **并发触发 (Concurrent Execution)**：
    *   若用户配置了大量的任务在同一秒（如 `00:00:00`）触发，系统需具备并行发出网络请求的能力，不能因为单条消息的发送阻塞导致后续消息延迟。
4.  **规则冲突检查**：
    *   UI 层面在用户保存时，如果发现“固定间隔”被设置为 0 秒，需高亮报错并阻断保存。最低间隔建议限制为 1 秒。