From 455d394682beb439531f4fee2be03cb141cdbf34 Mon Sep 17 00:00:00 2001
From: yexb <553699424@qq.com>
Date: Wed, 22 Apr 2026 20:27:30 +0800
Subject: [PATCH] docs: add disk monitor design spec

---
 .../specs/2026-04-22-disk-monitor-design.md   | 1034 +++++++++++++++++
 1 file changed, 1034 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-22-disk-monitor-design.md

diff --git a/docs/superpowers/specs/2026-04-22-disk-monitor-design.md b/docs/superpowers/specs/2026-04-22-disk-monitor-design.md
new file mode 100644
index 0000000..493cc00
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-22-disk-monitor-design.md
@@ -0,0 +1,1034 @@
+# 系统磁盘监控功能设计
+
+## 1. 背景
+
+当前仓库已经存在系统监控入口页与磁盘监控占位页：
+
+- `frontend/src/views/systemMonitor/index.vue`
+- `frontend/src/views/systemMonitor/diskMonitor/index.vue`
+
+本次目标是在现有“系统监控 > 磁盘监控”入口下，补齐一套完整的磁盘监控方案设计，覆盖：
+
+- 多盘符监控配置
+- 盘符级预警/告警阈值配置
+- 配置保存与回显
+- 应用启动后自动执行一次监控
+- 每日统一时间执行定时监控
+- 本地目录/网络路径通知
+- HTTP 回调通知
+- 监控结果与通知日志留痕
+- MySQL 表结构与建表 SQL
+
+## 2. 已确认需求结论
+
+### 2.1 业务范围
+
+- 磁盘监控配置由页面完成，配置后持久化保存
+- 页面支持配置磁盘预警和告警阈值，配置后持久化保存
+- 支持多个盘符监控，每个盘符独立配置预警和告警阈值
+- 应用启动时立即执行一次监控
+- 支持录入通知路径，录入完成后按规则通知
+- 支持每天定时执行监控
+
+### 2.2 已确认的约束
+
+- 监控阈值采用“已使用率”而不是“剩余容量”
+- “系统启动时即可进行监控”指“应用启动后立即执行一次”，不包含操作系统开机自启动
+- 每日定时监控采用“全局统一时间”，而不是每盘符独立时间
+- 通知方式同时支持：
+  - 本地目录路径
+  - 网络共享路径
+  - HTTP 回调地址
+- 通知规则固定为：
+  - 告警状态下每次监控都通知
+  - 其他状态按状态变化通知
+
+### 2.3 当前仓库边界
+
+- 当前仓库包含前端和 Electron 壳层
+- 当前仓库中未提供可直接修改的业务后端源码
+- 因此本设计覆盖完整业务方案，但在本仓库实际落地时，前端页面和接口契约可直接实现，真正的扫描、调度、通知执行需由后端配合实现
+
+## 3. 推荐方案
+
+采用“分层业务方案”，但按最终确认结果收敛为 5 张核心表：
+
+1. `disk_monitor_policy`
+2. `disk_monitor_target`
+3. `disk_monitor_job`
+4. `disk_monitor_result`
+5. `disk_monitor_notify_log`
+
+其中：
+
+- `disk_monitor_policy` 负责全局监控策略
+- `disk_monitor_target` 单独存盘符配置，并合并该盘符的通知目标配置
+- `disk_monitor_job` 记录每次监控批次
+- `disk_monitor_result` 记录批次内每个盘符的扫描结果
+- `disk_monitor_notify_log` 记录通知发送结果
+
+该方案兼顾当前需求与后续可维护性，避免把状态判断、任务记录、通知日志混在单表里。
+
+## 4. 页面设计
+
+## 4.1 页面入口
+
+页面入口保留在系统监控模块下：
+
+- 入口页：`frontend/src/views/systemMonitor/index.vue`
+- 目标页：`frontend/src/views/systemMonitor/diskMonitor/index.vue`
+
+磁盘监控页作为独立配置页，不再只是占位内容。
+
+## 4.2 页面布局
+
+页面分为 4 个区域。
+
+### 4.2.1 顶部摘要区
+
+展示当前系统的全局监控状态，字段建议包括：
+
+- 监控总开关
+- 应用启动即监控
+- 每日统一执行时间
+- 最近执行时间
+- 最近执行状态
+- 监控盘符数量
+- 当前告警盘符数量
+
+### 4.2.2 全局策略区
+
+用于维护全局监控策略，字段包括：
+
+- 是否启用磁盘监控
+- 应用启动后立即执行一次
+- 每日统一监控时间
+- 通知规则说明
+
+通知规则在页面上只展示，不开放复杂配置：
+
+- 预警：状态变化通知
+- 告警：每次命中都通知
+
+### 4.2.3 通知配置区
+
+通知配置跟盘符走，每个盘符都带一组通知目标。页面上建议以“盘符展开卡片”或“盘符表格 + 弹窗”方式编辑通知配置。
+
+每个盘符支持两类通知目标：
+
+- 路径通知：
+  - 本地目录，如 `D:\disk-monitor`
+  - 网络共享目录，如 `\\server\share\disk-monitor`
+- HTTP 回调通知：
+  - 如 `http://127.0.0.1:8080/api/disk/notify`
+
+每条通知目标包含：
+
+- 名称
+- 地址
+- 是否启用
+- 备注
+
+HTTP 目标额外包含：
+
+- 请求方法，默认 `POST`
+- 超时时间，默认 `5000ms`
+
+### 4.2.4 盘符配置区
+
+盘符配置区以表格展示，支持新增、编辑、删除盘符配置。字段包括：
+
+- 盘符
+- 是否监控
+- 预警使用率
+- 告警使用率
+- 当前状态
+- 最近扫描时间
+- 最近使用率
+- 操作
+
+## 4.3 页面交互规则
+
+### 4.3.1 配置保存
+
+页面保存时一次性提交整页配置，包含：
+
+- 全局策略
+- 所有盘符配置
+- 每个盘符下的路径通知配置
+- 每个盘符下的 HTTP 通知配置
+
+### 4.3.2 配置回显
+
+页面加载时一次性读取当前生效配置，并回显：
+
+- 全局策略
+- 盘符列表
+- 各盘符的通知配置
+- 最近执行摘要
+
+### 4.3.3 手动执行
+
+页面建议提供“立即执行监控”按钮，用于：
+
+- 联调验证
+- 保存配置后立刻测试
+- 验证通知逻辑
+
+### 4.3.4 最近执行结果
+
+页面下半区建议展示最近若干次执行记录，支持查看：
+
+- 任务来源
+- 开始/结束时间
+- 执行状态
+- 预警数量
+- 告警数量
+- 每盘符结果
+- 通知发送记录
+
+## 4.4 页面校验规则
+
+- 盘符不能为空
+- 盘符不能重复
+- 预警使用率必须在 `1-100` 之间
+- 告警使用率必须在 `1-100` 之间
+- 告警使用率必须大于等于预警使用率
+- 每日统一执行时间不能为空，格式固定 `HH:mm:ss`
+- 路径通知目标不能为空
+- HTTP 通知目标必须是合法 URL
+
+## 5. 数据库设计
+
+## 5.1 设计原则
+
+- 使用 MySQL 8.0
+- 使用 `InnoDB`
+- 字符集使用 `utf8mb4`
+- 配置表与日志表分离
+- 为减少配置调整对历史记录的影响，表之间以“索引型关联”为主，不强依赖数据库外键
+- 通知目标与盘符配置合并到 `disk_monitor_target`，使用 JSON 字段存多条通知目标
+
+## 5.2 表结构概览
+
+### 5.2.1 `disk_monitor_policy`
+
+用途：存全局策略，仅保留一套当前生效配置。
+
+关键字段：
+
+- `id`
+- `policy_name`
+- `monitor_enabled`
+- `run_on_app_start`
+- `daily_run_time`
+- `warning_notify_mode`
+- `alarm_notify_mode`
+- `last_job_id`
+- `remark`
+- `created_by`
+- `created_at`
+- `updated_by`
+- `updated_at`
+
+### 5.2.2 `disk_monitor_target`
+
+用途：存盘符配置，并合并该盘符的通知配置。
+
+关键字段：
+
+- `id`
+- `policy_id`
+- `drive_letter`
+- `monitor_enabled`
+- `warning_usage_percent`
+- `alarm_usage_percent`
+- `notify_path_enabled`
+- `notify_path_list_json`
+- `notify_http_enabled`
+- `notify_http_list_json`
+- `last_status`
+- `last_scan_time`
+- `last_used_percent`
+- `remark`
+- `created_by`
+- `created_at`
+- `updated_by`
+- `updated_at`
+
+### 5.2.3 `disk_monitor_job`
+
+用途：记录每次监控任务批次。
+
+关键字段：
+
+- `id`
+- `job_no`
+- `job_source`
+- `planned_time`
+- `started_at`
+- `finished_at`
+- `job_status`
+- `target_count`
+- `success_count`
+- `warning_count`
+- `alarm_count`
+- `message`
+- `created_at`
+
+### 5.2.4 `disk_monitor_result`
+
+用途：记录一次任务下每个盘符的扫描结果。
+
+关键字段：
+
+- `id`
+- `job_id`
+- `target_id`
+- `drive_letter`
+- `total_bytes`
+- `used_bytes`
+- `free_bytes`
+- `used_percent`
+- `current_status`
+- `previous_status`
+- `status_changed`
+- `should_notify`
+- `notify_reason`
+- `scan_time`
+- `message`
+
+### 5.2.5 `disk_monitor_notify_log`
+
+用途：记录每次通知发送日志。
+
+关键字段：
+
+- `id`
+- `job_id`
+- `result_id`
+- `target_id`
+- `drive_letter`
+- `notify_level`
+- `channel_type`
+- `channel_target`
+- `notify_title`
+- `notify_content`
+- `send_status`
+- `response_message`
+- `sent_at`
+
+## 5.3 JSON 字段结构
+
+### 5.3.1 `notify_path_list_json`
+
+```json
+[
+  {
+    "path": "D:\\disk-monitor",
+    "name": "本地通知目录",
+    "enabled": true
+  },
+  {
+    "path": "\\\\server\\share\\disk-monitor",
+    "name": "共享目录通知",
+    "enabled": true
+  }
+]
+```
+
+### 5.3.2 `notify_http_list_json`
+
+```json
+[
+  {
+    "url": "http://127.0.0.1:8080/api/disk/notify",
+    "name": "运维平台回调",
+    "method": "POST",
+    "timeoutMs": 5000,
+    "enabled": true
+  }
+]
+```
+
+## 5.4 状态值约定
+
+### 5.4.1 盘符状态
+
+- `UNKNOWN`
+- `NORMAL`
+- `WARNING`
+- `ALARM`
+
+### 5.4.2 任务来源
+
+- `APP_START`
+- `DAILY_SCHEDULE`
+- `MANUAL`
+
+### 5.4.3 任务状态
+
+- `RUNNING`
+- `SUCCESS`
+- `PARTIAL_SUCCESS`
+- `FAILED`
+
+### 5.4.4 通知原因
+
+- `ALARM_EVERY_TIME`
+- `STATUS_CHANGED`
+- `NO_NOTIFY`
+
+### 5.4.5 通知级别
+
+- `WARNING`
+- `ALARM`
+- `RECOVER`
+
+### 5.4.6 通知通道类型
+
+- `PATH`
+- `HTTP`
+
+### 5.4.7 通知发送状态
+
+- `SUCCESS`
+- `FAILED`
+
+## 5.5 索引设计
+
+### 5.5.1 `disk_monitor_policy`
+
+- 主键：`id`
+
+### 5.5.2 `disk_monitor_target`
+
+- 主键：`id`
+- 唯一索引：`uk_drive_letter(drive_letter)`
+- 普通索引：`idx_policy_id(policy_id)`
+
+### 5.5.3 `disk_monitor_job`
+
+- 主键：`id`
+- 唯一索引：`uk_job_no(job_no)`
+- 普通索引：`idx_job_source(job_source)`
+- 普通索引：`idx_started_at(started_at)`
+
+### 5.5.4 `disk_monitor_result`
+
+- 主键：`id`
+- 普通索引：`idx_job_id(job_id)`
+- 普通索引：`idx_target_id(target_id)`
+- 普通索引：`idx_drive_letter(drive_letter)`
+- 普通索引：`idx_scan_time(scan_time)`
+
+### 5.5.5 `disk_monitor_notify_log`
+
+- 主键：`id`
+- 普通索引：`idx_job_id(job_id)`
+- 普通索引：`idx_result_id(result_id)`
+- 普通索引：`idx_target_id(target_id)`
+- 普通索引：`idx_sent_at(sent_at)`
+
+## 5.6 MySQL 建表 SQL
+
+```sql
+CREATE TABLE IF NOT EXISTS `disk_monitor_policy` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    `policy_name` VARCHAR(100) NOT NULL DEFAULT '默认磁盘监控策略' COMMENT '策略名称',
+    `monitor_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用监控：0否 1是',
+    `run_on_app_start` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '应用启动后是否执行一次：0否 1是',
+    `daily_run_time` TIME NOT NULL COMMENT '每日统一执行时间',
+    `warning_notify_mode` VARCHAR(32) NOT NULL DEFAULT 'STATUS_CHANGE' COMMENT '预警通知模式',
+    `alarm_notify_mode` VARCHAR(32) NOT NULL DEFAULT 'EVERY_TIME' COMMENT '告警通知模式',
+    `last_job_id` BIGINT NULL COMMENT '最近一次任务ID',
+    `remark` VARCHAR(500) NULL COMMENT '备注',
+    `created_by` VARCHAR(64) NULL COMMENT '创建人',
+    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    `updated_by` VARCHAR(64) NULL COMMENT '更新人',
+    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='磁盘监控全局策略表';
+
+CREATE TABLE IF NOT EXISTS `disk_monitor_target` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    `policy_id` BIGINT NOT NULL COMMENT '策略ID',
+    `drive_letter` VARCHAR(10) NOT NULL COMMENT '盘符，例如 C:',
+    `monitor_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用监控：0否 1是',
+    `warning_usage_percent` TINYINT UNSIGNED NOT NULL COMMENT '预警使用率阈值',
+    `alarm_usage_percent` TINYINT UNSIGNED NOT NULL COMMENT '告警使用率阈值',
+    `notify_path_enabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否启用路径通知：0否 1是',
+    `notify_path_list_json` JSON NULL COMMENT '路径通知目标列表JSON',
+    `notify_http_enabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否启用HTTP通知：0否 1是',
+    `notify_http_list_json` JSON NULL COMMENT 'HTTP通知目标列表JSON',
+    `last_status` VARCHAR(32) NOT NULL DEFAULT 'UNKNOWN' COMMENT '最近一次状态',
+    `last_scan_time` DATETIME NULL COMMENT '最近扫描时间',
+    `last_used_percent` DECIMAL(5,2) NULL COMMENT '最近一次使用率',
+    `remark` VARCHAR(500) NULL COMMENT '备注',
+    `created_by` VARCHAR(64) NULL COMMENT '创建人',
+    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    `updated_by` VARCHAR(64) NULL COMMENT '更新人',
+    `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_drive_letter` (`drive_letter`),
+    KEY `idx_policy_id` (`policy_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='磁盘监控盘符配置表';
+
+CREATE TABLE IF NOT EXISTS `disk_monitor_job` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    `job_no` VARCHAR(64) NOT NULL COMMENT '任务编号',
+    `job_source` VARCHAR(32) NOT NULL COMMENT '任务来源',
+    `planned_time` DATETIME NULL COMMENT '计划执行时间',
+    `started_at` DATETIME NOT NULL COMMENT '开始时间',
+    `finished_at` DATETIME NULL COMMENT '结束时间',
+    `job_status` VARCHAR(32) NOT NULL COMMENT '任务状态',
+    `target_count` INT NOT NULL DEFAULT 0 COMMENT '计划扫描盘符数量',
+    `success_count` INT NOT NULL DEFAULT 0 COMMENT '成功扫描数量',
+    `warning_count` INT NOT NULL DEFAULT 0 COMMENT '预警数量',
+    `alarm_count` INT NOT NULL DEFAULT 0 COMMENT '告警数量',
+    `message` VARCHAR(1000) NULL COMMENT '结果说明',
+    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_job_no` (`job_no`),
+    KEY `idx_job_source` (`job_source`),
+    KEY `idx_started_at` (`started_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='磁盘监控任务批次表';
+
+CREATE TABLE IF NOT EXISTS `disk_monitor_result` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    `job_id` BIGINT NOT NULL COMMENT '任务ID',
+    `target_id` BIGINT NOT NULL COMMENT '盘符配置ID',
+    `drive_letter` VARCHAR(10) NOT NULL COMMENT '盘符',
+    `total_bytes` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '总容量字节数',
+    `used_bytes` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '已使用字节数',
+    `free_bytes` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '剩余字节数',
+    `used_percent` DECIMAL(5,2) NOT NULL DEFAULT 0.00 COMMENT '使用率',
+    `current_status` VARCHAR(32) NOT NULL COMMENT '当前状态',
+    `previous_status` VARCHAR(32) NOT NULL DEFAULT 'UNKNOWN' COMMENT '上一次状态',
+    `status_changed` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '状态是否变化：0否 1是',
+    `should_notify` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '本次是否通知：0否 1是',
+    `notify_reason` VARCHAR(32) NOT NULL DEFAULT 'NO_NOTIFY' COMMENT '通知原因',
+    `scan_time` DATETIME NOT NULL COMMENT '扫描时间',
+    `message` VARCHAR(1000) NULL COMMENT '扫描说明',
+    PRIMARY KEY (`id`),
+    KEY `idx_job_id` (`job_id`),
+    KEY `idx_target_id` (`target_id`),
+    KEY `idx_drive_letter` (`drive_letter`),
+    KEY `idx_scan_time` (`scan_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='磁盘监控结果表';
+
+CREATE TABLE IF NOT EXISTS `disk_monitor_notify_log` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    `job_id` BIGINT NOT NULL COMMENT '任务ID',
+    `result_id` BIGINT NOT NULL COMMENT '结果ID',
+    `target_id` BIGINT NOT NULL COMMENT '盘符配置ID',
+    `drive_letter` VARCHAR(10) NOT NULL COMMENT '盘符',
+    `notify_level` VARCHAR(32) NOT NULL COMMENT '通知级别',
+    `channel_type` VARCHAR(32) NOT NULL COMMENT '通知通道类型',
+    `channel_target` VARCHAR(1000) NOT NULL COMMENT '通知目标',
+    `notify_title` VARCHAR(255) NOT NULL COMMENT '通知标题',
+    `notify_content` TEXT NOT NULL COMMENT '通知内容',
+    `send_status` VARCHAR(32) NOT NULL COMMENT '发送状态',
+    `response_message` VARCHAR(2000) NULL COMMENT '响应结果或异常信息',
+    `sent_at` DATETIME NOT NULL COMMENT '发送时间',
+    PRIMARY KEY (`id`),
+    KEY `idx_job_id` (`job_id`),
+    KEY `idx_result_id` (`result_id`),
+    KEY `idx_target_id` (`target_id`),
+    KEY `idx_sent_at` (`sent_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='磁盘监控通知日志表';
+```
+
+## 6. 接口设计
+
+## 6.1 配置查询
+
+### 接口
+
+`GET /disk-monitor/policy/detail`
+
+### 用途
+
+页面初始化时一次性返回：
+
+- 当前生效的全局策略
+- 所有盘符配置
+
+### 返回结构
+
+```json
+{
+  "code": "A0000",
+  "message": "success",
+  "data": {
+    "policy": {
+      "id": 1,
+      "policyName": "默认磁盘监控策略",
+      "monitorEnabled": true,
+      "runOnAppStart": true,
+      "dailyRunTime": "08:30:00",
+      "warningNotifyMode": "STATUS_CHANGE",
+      "alarmNotifyMode": "EVERY_TIME",
+      "lastJobId": 1001,
+      "remark": ""
+    },
+    "targets": [
+      {
+        "id": 11,
+        "driveLetter": "C:",
+        "monitorEnabled": true,
+        "warningUsagePercent": 80,
+        "alarmUsagePercent": 90,
+        "notifyPathEnabled": true,
+        "notifyPathList": [
+          {
+            "path": "D:\\disk-monitor",
+            "name": "本地目录",
+            "enabled": true
+          }
+        ],
+        "notifyHttpEnabled": true,
+        "notifyHttpList": [
+          {
+            "url": "http://127.0.0.1:8080/api/disk/notify",
+            "name": "运维平台",
+            "method": "POST",
+            "timeoutMs": 5000,
+            "enabled": true
+          }
+        ],
+        "lastStatus": "NORMAL",
+        "lastScanTime": "2026-04-22 08:30:00",
+        "lastUsedPercent": 76.42,
+        "remark": ""
+      }
+    ]
+  }
+}
+```
+
+## 6.2 配置保存
+
+### 接口
+
+`POST /disk-monitor/policy/save`
+
+### 用途
+
+页面点击保存时，整页提交一次：
+
+- 全局策略
+- 所有盘符配置
+- 所有通知配置
+
+### 请求结构
+
+```json
+{
+  "policy": {
+    "id": 1,
+    "policyName": "默认磁盘监控策略",
+    "monitorEnabled": true,
+    "runOnAppStart": true,
+    "dailyRunTime": "08:30:00",
+    "warningNotifyMode": "STATUS_CHANGE",
+    "alarmNotifyMode": "EVERY_TIME",
+    "remark": ""
+  },
+  "targets": [
+    {
+      "id": 11,
+      "driveLetter": "C:",
+      "monitorEnabled": true,
+      "warningUsagePercent": 80,
+      "alarmUsagePercent": 90,
+      "notifyPathEnabled": true,
+      "notifyPathList": [
+        {
+          "path": "D:\\disk-monitor",
+          "name": "本地目录",
+          "enabled": true
+        }
+      ],
+      "notifyHttpEnabled": true,
+      "notifyHttpList": [
+        {
+          "url": "http://127.0.0.1:8080/api/disk/notify",
+          "name": "运维平台",
+          "method": "POST",
+          "timeoutMs": 5000,
+          "enabled": true
+        }
+      ],
+      "remark": ""
+    }
+  ]
+}
+```
+
+### 保存规则
+
+- 已存在盘符则更新
+- 新增盘符则插入
+- 请求中已移除的盘符可按业务选择：
+  - 直接删除
+  - 逻辑删除
+- 必须做完整参数校验
+
+## 6.3 手动执行监控
+
+### 接口
+
+`POST /disk-monitor/job/run`
+
+### 用途
+
+页面“立即执行监控”按钮触发一次人工监控。
+
+### 请求结构
+
+```json
+{
+  "jobSource": "MANUAL"
+}
+```
+
+### 返回结构
+
+```json
+{
+  "code": "A0000",
+  "message": "任务已启动",
+  "data": {
+    "jobId": 1002,
+    "jobNo": "DM202604220001"
+  }
+}
+```
+
+## 6.4 最近任务列表
+
+### 接口
+
+`POST /disk-monitor/job/list`
+
+### 用途
+
+查询最近执行记录，用于页面结果区展示。
+
+### 请求结构
+
+```json
+{
+  "pageNum": 1,
+  "pageSize": 10
+}
+```
+
+### 列表字段
+
+- `jobId`
+- `jobNo`
+- `jobSource`
+- `startedAt`
+- `finishedAt`
+- `jobStatus`
+- `targetCount`
+- `warningCount`
+- `alarmCount`
+- `message`
+
+## 6.5 任务详情
+
+### 接口
+
+`GET /disk-monitor/job/{jobId}/detail`
+
+### 用途
+
+查看一次任务的盘符结果和通知发送情况。
+
+### 返回结构
+
+```json
+{
+  "code": "A0000",
+  "message": "success",
+  "data": {
+    "job": {
+      "id": 1002,
+      "jobNo": "DM202604220001",
+      "jobSource": "MANUAL",
+      "jobStatus": "SUCCESS"
+    },
+    "results": [
+      {
+        "resultId": 2001,
+        "targetId": 11,
+        "driveLetter": "C:",
+        "totalBytes": 512000000000,
+        "usedBytes": 430000000000,
+        "freeBytes": 82000000000,
+        "usedPercent": 83.98,
+        "currentStatus": "WARNING",
+        "previousStatus": "NORMAL",
+        "statusChanged": true,
+        "shouldNotify": true,
+        "notifyReason": "STATUS_CHANGED",
+        "scanTime": "2026-04-22 15:10:00",
+        "message": ""
+      }
+    ],
+    "notifyLogs": [
+      {
+        "id": 3001,
+        "resultId": 2001,
+        "driveLetter": "C:",
+        "notifyLevel": "WARNING",
+        "channelType": "HTTP",
+        "channelTarget": "http://127.0.0.1:8080/api/disk/notify",
+        "sendStatus": "SUCCESS",
+        "responseMessage": "200 OK",
+        "sentAt": "2026-04-22 15:10:02"
+      }
+    ]
+  }
+}
+```
+
+## 6.6 通知测试接口
+
+### 接口
+
+`POST /disk-monitor/notify/test`
+
+### 用途
+
+用于页面保存配置后，快速验证通知目标是否可用。
+
+### 请求结构
+
+```json
+{
+  "driveLetter": "C:"
+}
+```
+
+该接口非必须，但建议保留，便于联调。
+
+## 7. 执行流设计
+
+## 7.1 应用启动监控
+
+执行条件：
+
+- `disk_monitor_policy.monitor_enabled = 1`
+- `disk_monitor_policy.run_on_app_start = 1`
+
+执行流程：
+
+1. 应用启动完成
+2. 后端读取当前全局策略
+3. 创建一条 `disk_monitor_job`
+4. `job_source = APP_START`
+5. 扫描所有启用监控的盘符
+6. 为每个盘符生成一条 `disk_monitor_result`
+7. 若本次需通知，则生成 `disk_monitor_notify_log`
+8. 更新 `disk_monitor_target.last_status / last_scan_time / last_used_percent`
+
+## 7.2 每日定时监控
+
+执行条件：
+
+- `disk_monitor_policy.monitor_enabled = 1`
+- 已配置 `daily_run_time`
+
+执行流程：
+
+1. 后端启动时注册统一调度器
+2. 每天到 `daily_run_time` 执行一次
+3. 创建一条 `disk_monitor_job`
+4. `job_source = DAILY_SCHEDULE`
+5. 扫描所有启用监控的盘符
+6. 生成结果与通知日志
+
+## 7.3 手动执行监控
+
+执行流程：
+
+1. 页面点击“立即执行监控”
+2. 调用 `POST /disk-monitor/job/run`
+3. 创建一条 `disk_monitor_job`
+4. `job_source = MANUAL`
+5. 扫描所有启用盘符
+6. 返回任务编号
+
+## 8. 状态判定与通知规则
+
+## 8.1 盘符状态判定
+
+设：
+
+- `usedPercent` 为当前使用率
+- `warningUsagePercent` 为预警阈值
+- `alarmUsagePercent` 为告警阈值
+
+判定规则：
+
+- `usedPercent >= alarmUsagePercent` -> `ALARM`
+- `usedPercent >= warningUsagePercent 且 usedPercent < alarmUsagePercent` -> `WARNING`
+- 其他 -> `NORMAL`
+
+## 8.2 通知判定规则
+
+本次需求固定为：
+
+- 告警后需要每次都通知
+- 其余状态按状态变化通知
+
+执行逻辑：
+
+```text
+if currentStatus == ALARM:
+    shouldNotify = true
+    notifyReason = ALARM_EVERY_TIME
+
+else if currentStatus == WARNING and previousStatus != WARNING:
+    shouldNotify = true
+    notifyReason = STATUS_CHANGED
+
+else if currentStatus == NORMAL and previousStatus in (WARNING, ALARM):
+    shouldNotify = true
+    notifyReason = STATUS_CHANGED
+
+else:
+    shouldNotify = false
+    notifyReason = NO_NOTIFY
+```
+
+## 8.3 恢复通知
+
+当盘符由：
+
+- `WARNING -> NORMAL`
+- `ALARM -> NORMAL`
+
+时，视为状态变化，发送恢复通知，通知级别建议记为 `RECOVER`。
+
+## 9. 通知执行设计
+
+## 9.1 路径通知
+
+执行方式：
+
+- 遍历 `notify_path_list_json`
+- 对每个启用路径生成一份通知文件
+
+建议文件内容为 JSON 或文本，至少包含：
+
+- 任务编号
+- 盘符
+- 当前状态
+- 当前使用率
+- 预警阈值
+- 告警阈值
+- 扫描时间
+
+每次路径写入都要记录到 `disk_monitor_notify_log`。
+
+## 9.2 HTTP 回调通知
+
+执行方式：
+
+- 遍历 `notify_http_list_json`
+- 按配置的 `url / method / timeoutMs` 发请求
+
+建议请求体：
+
+```json
+{
+  "jobNo": "DM202604220001",
+  "driveLetter": "C:",
+  "currentStatus": "ALARM",
+  "usedPercent": 93.12,
+  "warningUsagePercent": 80,
+  "alarmUsagePercent": 90,
+  "scanTime": "2026-04-22 15:10:00"
+}
+```
+
+HTTP 执行结果需要记录：
+
+- 发送成功或失败
+- 状态码
+- 异常信息
+
+并统一写入 `disk_monitor_notify_log`。
+
+## 10. 前端改动范围建议
+
+若后续进入本仓库实现，预计改动集中在：
+
+- `frontend/src/views/systemMonitor/diskMonitor/index.vue`
+- `frontend/src/views/systemMonitor/diskMonitor/components/`
+- `frontend/src/api/systemMonitor/`
+- 必要的前端类型定义文件
+
+页面入口继续复用：
+
+- `frontend/src/views/systemMonitor/index.vue`
+
+## 11. 验证方案
+
+## 11.1 配置验证
+
+- 页面保存后重新进入
+- 全局策略正确回显
+- 盘符配置正确回显
+- 通知路径与 HTTP 回调正确回显
+
+## 11.2 启动验证
+
+- 应用启动后自动生成一条 `APP_START` 任务记录
+- 启用盘符均生成结果记录
+
+## 11.3 定时验证
+
+- 到设定时间后自动生成一条 `DAILY_SCHEDULE` 任务记录
+- 所有启用盘符都参与扫描
+
+## 11.4 通知规则验证
+
+- `NORMAL -> WARNING` 时通知一次
+- 连续 `WARNING -> WARNING` 不重复通知
+- 连续 `ALARM -> ALARM` 每次都通知
+- `WARNING -> NORMAL` 时发恢复通知
+- `ALARM -> NORMAL` 时发恢复通知
+
+## 11.5 通知通道验证
+
+- 路径通知能成功写入本地目录
+- 路径通知能成功写入网络共享目录
+- HTTP 回调能成功返回状态码
+- 失败情况能正确写入通知日志
+
+## 12. 风险与注意事项
+
+- 当前仓库中未提供业务后端源码，设计中的扫描、调度、通知逻辑需由后端配合实现
+- 通知目标合并进 `disk_monitor_target` 后，当前需求下表结构更简洁，但后续若要做通知目标复用统计，不如独立通知表灵活
+- 路径通知涉及网络共享目录时，需要额外关注运行账户权限
+- HTTP 回调需要处理超时、重复通知、目标不可达等异常情况
+- 若后续允许删除盘符配置，建议保留结果表中的 `drive_letter` 冗余字段，避免历史查询受影响
+
+## 13. 结论
+
+本设计采用“全局策略 + 盘符配置 + 任务批次 + 扫描结果 + 通知日志”的五表方案，在满足当前需求的前提下，保证了：
+
+- 多盘符独立配置
+- 启动监控
+- 每日统一定时监控
+- 路径与 HTTP 双通知通道
+- 告警每次通知、其他状态变化通知
+- 配置、结果、通知日志完整留痕
+
+该设计可直接作为后续接口开发、数据库建表和前端页面实现的依据。