CN_Tool_client/docs/superpowers/specs/2026-04-22-disk-monitor-design.md

# 系统磁盘监控功能设计

## 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": 100,
  "sortField": "startedAt",
  "sortOrder": "desc"
}
```

说明：该接口默认用于“最近任务”区域，后端应按 `startedAt desc` 返回最近记录，前端再截取前 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 双通知通道
- 告警每次通知、其他状态变化通知
- 配置、结果、通知日志完整留痕

该设计可直接作为后续接口开发、数据库建表和前端页面实现的依据。