From 7fe6cee942892051a04a5df11aee39f88f739295 Mon Sep 17 00:00:00 2001
From: huang <1724659546@qq.com>
Date: Mon, 10 Nov 2025 23:22:13 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0api.js?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/api/alarm.js          | 266 ++++++++++++++++++++++++++++++++++++++
 src/api/areaController.js |   8 +-
 src/api/device.js         |   8 +-
 src/api/deviceTemplate.js |  16 +--
 src/api/index.js          |   2 +
 src/api/monitor.js        | 121 ++---------------
 src/api/pen.js            |  16 +--
 src/api/pigBatch.js       |  22 +---
 src/api/pigHouse.js       |   8 +-
 src/api/plan.js           |  55 +++-----
 src/api/user.js           |  13 +-
 11 files changed, 312 insertions(+), 223 deletions(-)
 create mode 100644 src/api/alarm.js

diff --git a/src/api/alarm.js b/src/api/alarm.js
new file mode 100644
index 00000000..41c8303a
--- /dev/null
+++ b/src/api/alarm.js
@@ -0,0 +1,266 @@
+import http from '../utils/http';
+import { Response, SeverityLevel, AlarmSourceType, Operator, AlarmCode, NotificationStatus, PaginationDTO, SensorType } from '../enums';
+
+// --- Typedefs for Alarm Management ---
+
+/**
+ * @typedef {object} ActiveAlarmDTO
+ * @property {number} id
+ * @property {AlarmCode} alarm_code
+ * @property {string} alarm_summary
+ * @property {string} alarm_details
+ * @property {SeverityLevel} level
+ * @property {AlarmSourceType} source_type
+ * @property {number} source_id
+ * @property {string} trigger_time
+ * @property {boolean} is_ignored
+ * @property {string} ignored_until
+ * @property {string} last_notified_at
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListActiveAlarmResponse
+ * @property {Array<ActiveAlarmDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} ActiveAlarmsParams
+ * @property {string} [end_time] - 告警触发时间范围 - 结束时间
+ * @property {boolean} [is_ignored] - 按是否被忽略过滤
+ * @property {SeverityLevel} [level] - 按告警严重性等级过滤
+ * @property {string} [order_by] - 排序字段，例如 "trigger_time DESC"
+ * @property {number} [page]
+ * @property {number} [page_size]
+ * @property {number} [source_id] - 按告警来源ID过滤
+ * @property {AlarmSourceType} [source_type] - 按告警来源类型过滤
+ * @property {string} [trigger_time] - 告警触发时间范围 - 开始时间
+ */
+
+/**
+ * @typedef {object} CreateAreaThresholdAlarmDTO
+ * @property {number} area_controller_id - 区域主控ID
+ * @property {Operator} operator - 操作符
+ * @property {SensorType} sensor_type - 传感器类型
+ * @property {number} thresholds - 阈值
+ * @property {SeverityLevel} [level] - 告警等级，可选
+ */
+
+/**
+ * @typedef {object} AreaThresholdAlarmDTO
+ * @property {number} id
+ * @property {number} area_controller_id
+ * @property {SeverityLevel} level
+ * @property {Operator} operator
+ * @property {SensorType} sensor_type
+ * @property {number} thresholds
+ */
+
+/**
+ * @typedef {object} UpdateAreaThresholdAlarmDTO
+ * @property {Operator} operator - 新的操作符
+ * @property {number} thresholds - 新的阈值
+ * @property {SeverityLevel} [level] - 新的告警等级，可选
+ */
+
+/**
+ * @typedef {object} CreateDeviceThresholdAlarmDTO
+ * @property {number} device_id - 设备ID
+ * @property {Operator} operator - 操作符
+ * @property {SensorType} sensor_type - 传感器类型
+ * @property {number} thresholds - 阈值
+ * @property {SeverityLevel} [level] - 告警等级，可选
+ */
+
+/**
+ * @typedef {object} DeviceThresholdAlarmDTO
+ * @property {number} id
+ * @property {number} device_id
+ * @property {SeverityLevel} level
+ * @property {Operator} operator
+ * @property {SensorType} sensor_type
+ * @property {number} thresholds
+ */
+
+/**
+ * @typedef {object} UpdateDeviceThresholdAlarmDTO
+ * @property {Operator} operator - 新的操作符
+ * @property {number} thresholds - 新的阈值
+ * @property {SeverityLevel} [level] - 新的告警等级，可选
+ */
+
+/**
+ * @typedef {object} DeleteDeviceThresholdAlarmDTO
+ * @property {SensorType} sensor_type - 传感器类型
+ */
+
+/**
+ * @typedef {object} HistoricalAlarmDTO
+ * @property {number} id
+ * @property {AlarmCode} alarm_code
+ * @property {string} alarm_summary
+ * @property {string} alarm_details
+ * @property {SeverityLevel} level
+ * @property {AlarmSourceType} source_type
+ * @property {number} source_id
+ * @property {string} trigger_time
+ * @property {string} resolve_time
+ * @property {string} resolve_method
+ * @property {number} resolved_by
+ */
+
+/**
+ * @typedef {object} ListHistoricalAlarmResponse
+ * @property {Array<HistoricalAlarmDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} HistoricalAlarmsParams
+ * @property {SeverityLevel} [level] - 按告警严重性等级过滤
+ * @property {string} [order_by] - 排序字段，例如 "trigger_time DESC"
+ * @property {number} [page]
+ * @property {number} [page_size]
+ * @property {string} [resolve_time_end] - 告警解决时间范围 - 结束时间
+ * @property {string} [resolve_time_start] - 告警解决时间范围 - 开始时间
+ * @property {number} [source_id] - 按告警来源ID过滤
+ * @property {AlarmSourceType} [source_type] - 按告警来源类型过滤
+ * @property {string} [trigger_time_end] - 告警触发时间范围 - 结束时间
+ * @property {string} [trigger_time_start] - 告警触发时间范围 - 开始时间
+ */
+
+/**
+ * @typedef {object} SnoozeAlarmRequest
+ * @property {number} duration_minutes - 忽略时长，单位分钟
+ */
+
+// --- API Functions ---
+
+/**
+ * 根据过滤条件和分页参数查询活跃告警列表
+ * @param {ActiveAlarmsParams} params - 查询参数
+ * @returns {Promise<ListActiveAlarmResponse>}
+ */
+export const getActiveAlarms = (params) => {
+  return http.get('/api/v1/alarm/threshold/active-alarms', { params });
+};
+
+/**
+ * 为指定的区域主控创建一个新的阈值告警规则
+ * @param {CreateAreaThresholdAlarmDTO} requestBody - 创建区域阈值告警请求体
+ * @returns {Promise<Response>}
+ */
+export const createAreaThresholdAlarm = (requestBody) => {
+  return http.post('/api/v1/alarm/threshold/area', requestBody);
+};
+
+/**
+ * 根据任务ID获取单个区域阈值告警规则的详细信息
+ * @param {number} task_id - 任务ID
+ * @returns {Promise<AreaThresholdAlarmDTO>}
+ */
+export const getAreaThresholdAlarmById = (task_id) => {
+  return http.get(`/api/v1/alarm/threshold/area/${task_id}`);
+};
+
+/**
+ * 根据任务ID更新已存在的区域阈值告警规则
+ * @param {number} task_id - 任务ID
+ * @param {UpdateAreaThresholdAlarmDTO} requestBody - 更新区域阈值告警请求体
+ * @returns {Promise<Response>}
+ */
+export const updateAreaThresholdAlarm = (task_id, requestBody) => {
+  return http.put(`/api/v1/alarm/threshold/area/${task_id}`, requestBody);
+};
+
+/**
+ * 根据任务ID删除区域阈值告警规则
+ * @param {number} task_id - 任务ID
+ * @returns {Promise<Response>}
+ */
+export const deleteAreaThresholdAlarm = (task_id) => {
+  return http.delete(`/api/v1/alarm/threshold/area/${task_id}`);
+};
+
+/**
+ * 为单个设备创建一个新的阈值告警规则
+ * @param {CreateDeviceThresholdAlarmDTO} requestBody - 创建设备阈值告警请求体
+ * @returns {Promise<Response>}
+ */
+export const createDeviceThresholdAlarm = (requestBody) => {
+  return http.post('/api/v1/alarm/threshold/device', requestBody);
+};
+
+/**
+ * 根据任务ID获取单个设备阈值告警规则的详细信息
+ * @param {number} task_id - 任务ID
+ * @returns {Promise<DeviceThresholdAlarmDTO>}
+ */
+export const getDeviceThresholdAlarmById = (task_id) => {
+  return http.get(`/api/v1/alarm/threshold/device/${task_id}`);
+};
+
+/**
+ * 根据任务ID更新已存在的设备阈值告警规则
+ * @param {number} task_id - 任务ID
+ * @param {UpdateDeviceThresholdAlarmDTO} requestBody - 更新设备阈值告警请求体
+ * @returns {Promise<Response>}
+ */
+export const updateDeviceThresholdAlarm = (task_id, requestBody) => {
+  return http.put(`/api/v1/alarm/threshold/device/${task_id}`, requestBody);
+};
+
+/**
+ * 根据任务ID删除设备阈值告警规则
+ * @param {number} task_id - 任务ID
+ * @param {DeleteDeviceThresholdAlarmDTO} requestBody - 删除设备阈值告警请求体
+ * @returns {Promise<Response>}
+ */
+export const deleteDeviceThresholdAlarm = (task_id, requestBody) => {
+  return http.delete(`/api/v1/alarm/threshold/device/${task_id}`, { data: requestBody }); // DELETE with body
+};
+
+/**
+ * 根据过滤条件和分页参数查询历史告警列表
+ * @param {HistoricalAlarmsParams} params - 查询参数
+ * @returns {Promise<ListHistoricalAlarmResponse>}
+ */
+export const getHistoricalAlarms = (params) => {
+  return http.get('/api/v1/alarm/threshold/historical-alarms', { params });
+};
+
+/**
+ * 根据告警ID取消对一个阈值告警的忽略状态
+ * @param {string} id - 告警ID
+ * @returns {Promise<Response>}
+ */
+export const cancelSnoozeAlarm = (id) => {
+  return http.post(`/api/v1/alarm/threshold/${id}/cancel-snooze`);
+};
+
+/**
+ * 根据告警ID忽略一个活跃的阈值告警，或更新其忽略时间
+ * @param {string} id - 告警ID
+ * @param {SnoozeAlarmRequest} requestBody - 忽略告警请求体
+ * @returns {Promise<Response>}
+ */
+export const snoozeAlarm = (id, requestBody) => {
+  return http.post(`/api/v1/alarm/threshold/${id}/snooze`, requestBody);
+};
+
+export const AlarmApi = {
+  getActiveAlarms,
+  createAreaThresholdAlarm,
+  getAreaThresholdAlarmById,
+  updateAreaThresholdAlarm,
+  deleteAreaThresholdAlarm,
+  createDeviceThresholdAlarm,
+  getDeviceThresholdAlarmById,
+  updateDeviceThresholdAlarm,
+  deleteDeviceThresholdAlarm,
+  getHistoricalAlarms,
+  cancelSnoozeAlarm,
+  snoozeAlarm,
+};
diff --git a/src/api/areaController.js b/src/api/areaController.js
index e23e1a98..ee07bf59 100644
--- a/src/api/areaController.js
+++ b/src/api/areaController.js
@@ -1,11 +1,5 @@
 import http from '../utils/http';
-
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
+import { Response } from '../enums';
 
 /**
  * @typedef {object} AreaControllerResponse
diff --git a/src/api/device.js b/src/api/device.js
index f4d1e06f..5873b2a2 100644
--- a/src/api/device.js
+++ b/src/api/device.js
@@ -1,14 +1,8 @@
 import http from '../utils/http';
+import { Response } from '../enums';
 
 // --- Typedefs ---
 
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
-
 /**
  * @typedef {object} DeviceResponse
  * @property {number} id
diff --git a/src/api/deviceTemplate.js b/src/api/deviceTemplate.js
index baaa3a0b..d93b2dc4 100644
--- a/src/api/deviceTemplate.js
+++ b/src/api/deviceTemplate.js
@@ -1,19 +1,5 @@
 import http from '../utils/http';
-
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
-
-/**
- * @typedef {('执行器'|'传感器')} DeviceCategory
- */
-
-/**
- * @typedef {('信号强度'|'电池电量'|'温度'|'湿度'|'重量')} SensorType
- */
+import { Response, DeviceCategory, SensorType } from '../enums';
 
 /**
  * @typedef {object} ValueDescriptor
diff --git a/src/api/index.js b/src/api/index.js
index c720d1db..94725c76 100644
--- a/src/api/index.js
+++ b/src/api/index.js
@@ -1,6 +1,7 @@
 import { AreaControllerApi, DeviceApi } from './device.js';
 import { PlanApi } from './plan.js';
 import { UserApi } from './user.js';
+import { AlarmApi } from './alarm.js'; // 导入告警API
 import { DeviceTemplateApi } from './deviceTemplate.js'; // 导入设备模板API
 
 /**
@@ -12,6 +13,7 @@ export class ApiClient {
     this.devices = DeviceApi;
     this.plans = PlanApi;
     this.users = UserApi;
+    this.alarms = AlarmApi; // 添加告警API
     this.deviceTemplates = DeviceTemplateApi; // 添加设备模板API
   }
 }
diff --git a/src/api/monitor.js b/src/api/monitor.js
index 0873f00e..23fffe7b 100644
--- a/src/api/monitor.js
+++ b/src/api/monitor.js
@@ -1,14 +1,16 @@
 import http from '../utils/http';
+import {
+  PaginationDTO, DeviceCommandLogDTO, FeedFormulaDTO, PenDTO, FeedUsageRecordDTO, MedicationReasonType,
+  MedicationDTO, MedicationLogDTO, NotifierType, NotificationStatus, NotificationDTO, PendingCollectionStatus,
+  PendingCollectionDTO, LogChangeType, PigBatchLogDTO, PigPurchaseDTO, PigSaleDTO, PigBatchSickPigReasonType,
+  PigBatchSickPigTreatmentLocation, PigSickLogDTO, PigTransferType, PigTransferLogDTO, ExecutionStatus,
+  PlanExecutionLogDTO, RawMaterialDTO, RawMaterialPurchaseDTO, StockLogSourceType, RawMaterialStockLogDTO,
+  SensorType, SensorDataDTO, TaskDTO, TaskExecutionLogDTO, AuditStatus, UserActionLogDTO, WeighingBatchDTO,
+  WeighingRecordDTO, ZapcoreLevel, SeverityLevel
+} from '../enums';
 
 // --- Typedefs ---
 
-/**
- * @typedef {object} PaginationDTO
- * @property {number} page
- * @property {number} page_size
- * @property {number} total
- */
-
 /**
  * @typedef {object} DeviceCommandLogDTO
  * @property {string} message_id
@@ -35,18 +37,6 @@ import http from '../utils/http';
  * @property {boolean} [received_success]
  */
 
-/**
- * @typedef {object} FeedFormulaDTO
- * @property {number} id
- * @property {string} name
- */
-
-/**
- * @typedef {object} PenDTO
- * @property {number} id
- * @property {string} name
- */
-
 /**
  * @typedef {object} FeedUsageRecordDTO
  * @property {number} id
@@ -78,16 +68,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-/**
- * @typedef {('预防'|'治疗'|'保健')} MedicationReasonType
- */
-
-/**
- * @typedef {object} MedicationDTO
- * @property {number} id
- * @property {string} name
- */
-
 /**
  * @typedef {object} MedicationLogDTO
  * @property {number} id
@@ -121,14 +101,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-/**
- * @typedef {('邮件'|'企业微信'|'飞书'|'日志')} NotifierType
- */
-
-/**
- * @typedef {('发送成功'|'发送失败'|'已跳过')} NotificationStatus
- */
-
 /**
  * @typedef {object} NotificationDTO
  * @property {number} id
@@ -137,7 +109,7 @@ import http from '../utils/http';
  * @property {string} to_address
  * @property {string} title
  * @property {string} message
- * @property {number} level - 日志级别, 见 ZapcoreLevel 枚举
+ * @property {SeverityLevel} level - 日志级别, 见 SeverityLevel 枚举
  * @property {string} alarm_timestamp
  * @property {NotificationStatus} status
  * @property {string} error_message
@@ -158,16 +130,12 @@ import http from '../utils/http';
  * @property {string} [order_by]
  * @property {string} [start_time]
  * @property {string} [end_time]
- * @property {number} [level] - 日志级别, 见 ZapcoreLevel 枚举
+ * @property {SeverityLevel} [level] - 日志级别, 见 SeverityLevel 枚举
  * @property {NotifierType} [notifier_type]
  * @property {NotificationStatus} [status]
  * @property {number} [user_id]
  */
 
-/**
- * @typedef {('等待中'|'已完成'|'已超时')} PendingCollectionStatus
- */
-
 /**
  * @typedef {object} PendingCollectionDTO
  * @property {string} correlation_id
@@ -195,10 +163,6 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {('死亡'|'淘汰'|'销售'|'购买'|'转入'|'转出'|'盘点校正')} LogChangeType
- */
-
 /**
  * @typedef {object} PigBatchLogDTO
  * @property {number} id
@@ -298,14 +262,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-/**
- * @typedef {('患病'|'康复'|'死亡'|'淘汰'|'转入'|'转出'|'其他')} PigBatchSickPigReasonType
- */
-
-/**
- * @typedef {('原地治疗'|'病猪栏治疗')} PigBatchSickPigTreatmentLocation
- */
-
 /**
  * @typedef {object} PigSickLogDTO
  * @property {number} id
@@ -343,10 +299,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-/**
- * @typedef {('群内调栏'|'跨群调栏'|'销售'|'死亡'|'淘汰'|'新购入'|'产房转入')} PigTransferType
- */
-
 /**
  * @typedef {object} PigTransferLogDTO
  * @property {number} id
@@ -382,10 +334,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-/**
- * @typedef {('已开始'|'已完成'|'失败'|'已取消'|'等待中')} ExecutionStatus
- */
-
 /**
  * @typedef {object} PlanExecutionLogDTO
  * @property {number} id
@@ -416,12 +364,6 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {object} RawMaterialDTO
- * @property {number} id
- * @property {string} name
- */
-
 /**
  * @typedef {object} RawMaterialPurchaseDTO
  * @property {number} id
@@ -452,10 +394,6 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {('采购入库'|'饲喂出库'|'变质出库'|'售卖出库'|'杂用领取'|'手动盘点')} StockLogSourceType
- */
-
 /**
  * @typedef {object} RawMaterialStockLogDTO
  * @property {number} id
@@ -485,13 +423,9 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {('信号强度'|'电池电量'|'温度'|'湿度'|'重量')} SensorType
- */
-
 /**
  * @typedef {object} SensorDataDTO
- * @property {number} regional_controller_id
+ * @property {number} area_controller_id
  * @property {number} device_id
  * @property {SensorType} sensor_type
  * @property {Array<number>} data
@@ -515,13 +449,6 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {object} TaskDTO
- * @property {number} id
- * @property {string} name
- * @property {string} description
- */
-
 /**
  * @typedef {object} TaskExecutionLogDTO
  * @property {number} id
@@ -554,10 +481,6 @@ import http from '../utils/http';
  * @property {string} [end_time]
  */
 
-/**
- * @typedef {('成功'|'失败')} AuditStatus
- */
-
 /**
  * @typedef {object} UserActionLogDTO
  * @property {number} id
@@ -650,26 +573,6 @@ import http from '../utils/http';
  * @property {number} [operator_id]
  */
 
-// --- Enums ---
-
-/**
- * 日志级别, 对应后端的 zapcore.Level
- * @enum {number}
- */
-export const ZapcoreLevel = {
-  Debug: -1,
-  Info: 0,
-  Warn: 1,
-  Error: 2,
-  DPanic: 3,
-  Panic: 4,
-  Fatal: 5,
-  _minLevel: -1,
-  _maxLevel: 5,
-  Invalid: 6,
-  _numLevels: 7,
-};
-
 // --- Functions ---
 
 const processResponse = (responseData) => {
diff --git a/src/api/pen.js b/src/api/pen.js
index 23b74923..28c90d6c 100644
--- a/src/api/pen.js
+++ b/src/api/pen.js
@@ -1,11 +1,5 @@
 import http from '../utils/http';
-
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
+import { Response, PenStatus } from '../enums';
 
 /**
  * @typedef {object} PenResponse
@@ -15,14 +9,14 @@ import http from '../utils/http';
  * @property {number} capacity
  * @property {number} current_pig_count
  * @property {number} pig_batch_id
- * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ * @property {PenStatus} status
  */
 
 /**
  * @typedef {object} CreatePenRequest
  * @property {number} house_id
  * @property {string} pen_number
- * @property {number} capacity
+ * @property {number} capacity 
  */
 
 /**
@@ -30,12 +24,12 @@ import http from '../utils/http';
  * @property {number} house_id
  * @property {string} pen_number
  * @property {number} capacity
- * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ * @property {PenStatus} status
  */
 
 /**
  * @typedef {object} UpdatePenStatusRequest
- * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ * @property {PenStatus} status
  */
 
 /**
diff --git a/src/api/pigBatch.js b/src/api/pigBatch.js
index 06ec3d95..90fcf9ad 100644
--- a/src/api/pigBatch.js
+++ b/src/api/pigBatch.js
@@ -1,22 +1,8 @@
 import http from '../utils/http';
+import { Response, PigBatchOriginType, PigBatchStatus, PigBatchSickPigTreatmentLocation, PenStatus } from '../enums';
 
 // --- Typedefs ---
 
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
-
-/**
- * @typedef {('自繁'|'外购')} PigBatchOriginType
- */
-
-/**
- * @typedef {('保育'|'生长'|'育肥'|'待售'|'已出售'|'已归档')} PigBatchStatus
- */
-
 /**
  * @typedef {object} PigBatchResponseDTO
  * @property {number} id - 批次ID
@@ -115,10 +101,6 @@ import http from '../utils/http';
  * @property {string} [remarks] - 备注
  */
 
-/**
- * @typedef {('原地治疗'|'病猪栏治疗')} PigBatchSickPigTreatmentLocation
- */
-
 /**
  * @typedef {object} RecordSickPigsRequest
  * @property {number} pen_id - 猪栏ID
@@ -179,7 +161,7 @@ import http from '../utils/http';
  * @property {number} capacity
  * @property {number} current_pig_count
  * @property {number} pig_batch_id
- * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ * @property {PenStatus} status
  */
 
 /**
diff --git a/src/api/pigHouse.js b/src/api/pigHouse.js
index 7ea96907..54e27e9c 100644
--- a/src/api/pigHouse.js
+++ b/src/api/pigHouse.js
@@ -1,11 +1,5 @@
 import http from '../utils/http';
-
-/**
- * @typedef {object} Response
- * @property {number} code - 业务状态码
- * @property {object} [data] - 业务数据
- * @property {string} [message] - 提示信息
- */
+import { Response } from '../enums';
 
 /**
  * @typedef {object} PigHouseResponse
diff --git a/src/api/plan.js b/src/api/plan.js
index 15ff518c..2f7e3671 100644
--- a/src/api/plan.js
+++ b/src/api/plan.js
@@ -1,20 +1,13 @@
 import http from '../utils/http';
-
-/**
- * @typedef {('计划分析'|'等待'|'下料'|'全量采集')} TaskType
- */
+import { TaskType, PlanExecutionType, PlanStatus, PlanContentType, PlanType, ExecutionStatus } from '../enums';
 
 /**
  * @typedef {object} TaskRequest
- * @property {string} [name]
+ * @property {string} name
  * @property {string} [description]
- * @property {TaskType} [type]
+ * @property {TaskType} type
  * @property {object} [parameters]
- * @property {number} [execution_order]
- */
-
-/**
- * @typedef {('自动'|'手动')} PlanExecutionType
+ * @property {number} execution_order
  */
 
 /**
@@ -24,15 +17,15 @@ import http from '../utils/http';
  * @property {PlanExecutionType} execution_type
  * @property {string} [cron_expression]
  * @property {number} [execute_num]
- * @property {Array<TaskRequest>} [tasks]
- * @property {Array<number>} [sub_plan_ids]
+ * @property {Array<TaskRequest>} [tasks] - 任务列表
+ * @property {Array<number>} [sub_plan_ids] - 子计划ID列表
  */
 
 /**
  * @typedef {object} UpdatePlanRequest
  * @property {string} [name]
  * @property {string} [description]
- * @property {PlanExecutionType} execution_type
+ * @property {PlanExecutionType} execution_type - 计划执行类型
  * @property {string} [cron_expression]
  * @property {number} [execute_num]
  * @property {Array<TaskRequest>} [tasks]
@@ -45,32 +38,11 @@ import http from '../utils/http';
  * @property {number} plan_id
  * @property {string} name
  * @property {string} description
- * @property {TaskType} type
+ * @property {TaskType} type - 任务类型
  * @property {object} parameters
  * @property {number} execution_order
  */
 
-/**
- * @typedef {object} SubPlanResponse
- * @property {number} id
- * @property {number} parent_plan_id
- * @property {number} child_plan_id
- * @property {number} execution_order
- * @property {PlanResponse} child_plan
- */
-
-/**
- * @typedef {('已禁用'|'已启用'|'执行完毕'|'执行失败')} PlanStatus
- */
-
-/**
- * @typedef {('子计划'|'任务')} PlanContentType
- */
-
-/**
- * @typedef {('自定义任务'|'系统任务')} PlanType
- */
-
 /**
  * @typedef {object} PlanResponse
  * @property {number} id
@@ -87,6 +59,15 @@ import http from '../utils/http';
  * @property {Array<SubPlanResponse>} sub_plans
  */
 
+/**
+ * @typedef {object} SubPlanResponse
+ * @property {number} id
+ * @property {number} parent_plan_id
+ * @property {number} child_plan_id
+ * @property {number} execution_order
+ * @property {PlanResponse} child_plan
+ */
+
 /**
  * @typedef {object} ListPlansResponse
  * @property {Array<PlanResponse>} plans
@@ -102,7 +83,7 @@ import http from '../utils/http';
  * @property {number} plan_id
  * @property {string} plan_name
  * @property {string} started_at
- * @property {string} status
+ * @property {ExecutionStatus} status - 执行状态
  * @property {string} updated_at
  */
 
diff --git a/src/api/user.js b/src/api/user.js
index 90dc8067..724591ae 100644
--- a/src/api/user.js
+++ b/src/api/user.js
@@ -1,4 +1,5 @@
 import http from '../utils/http';
+import { AuditStatus, NotifierType } from '../enums';
 
 /**
  * @typedef {object} CreateUserRequest
@@ -25,10 +26,6 @@ import http from '../utils/http';
  * @property {string} token
  */
 
-/**
- * @typedef {('成功'|'失败')} AuditStatus
- */
-
 /**
  * @typedef {object} UserActionLogDTO
  * @property {number} id
@@ -39,8 +36,8 @@ import http from '../utils/http';
  * @property {string} http_method
  * @property {string} http_path
  * @property {string} source_ip
- * @property {Array<number>} target_resource
- * @property {AuditStatus} status
+ * @property {Array<number>} target_resource - 目标资源ID列表
+ * @property {AuditStatus} status - 审计状态
  * @property {string} result_details
  * @property {string} time
  */
@@ -71,10 +68,6 @@ import http from '../utils/http';
  * @property {string} [username]
  */
 
-/**
- * @typedef {('邮件'|'企业微信'|'飞书'|'日志')} NotifierType
- */
-
 /**
  * @typedef {object} SendTestNotificationRequest
  * @property {NotifierType} type - Type 指定要测试的通知渠道