From d7d68684e4dec2d8e7af521b59c477f6219defc1 Mon Sep 17 00:00:00 2001
From: huang <1724659546@qq.com>
Date: Thu, 23 Oct 2025 15:17:31 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0jsdoc?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/api/areaController.js |  40 ++-
 src/api/device.js         |  97 +++++-
 src/api/deviceTemplate.js |  61 +++-
 src/api/monitor.js        | 682 +++++++++++++++++++++++++++++++++++---
 src/api/pen.js            |  47 ++-
 src/api/pigBatch.js       | 226 +++++++++++--
 src/api/pigHouse.js       |  31 +-
 src/api/plan.js           |  95 +++++-
 src/api/user.js           |  83 ++++-
 9 files changed, 1250 insertions(+), 112 deletions(-)

diff --git a/src/api/areaController.js b/src/api/areaController.js
index 5cc2f3ca..1a11fa00 100644
--- a/src/api/areaController.js
+++ b/src/api/areaController.js
@@ -1,8 +1,36 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {object} AreaControllerResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} location
+ * @property {string} status
+ * @property {object} properties
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} CreateAreaControllerRequest
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} [location]
+ * @property {object} [properties]
+ */
+
+/**
+ * @typedef {object} UpdateAreaControllerRequest
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} [location]
+ * @property {object} [properties]
+ */
+
 /**
  * 获取系统中所有区域主控的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<AreaControllerResponse>>}
  */
 export const getAreaControllers = () => {
   return http.get('/api/v1/area-controllers');
@@ -10,8 +38,8 @@ export const getAreaControllers = () => {
 
 /**
  * 根据提供的信息创建一个新区域主控
- * @param {object} areaControllerData - 区域主控信息，对应 dto.CreateAreaControllerRequest
- * @returns {Promise<*>}
+ * @param {CreateAreaControllerRequest} areaControllerData - 区域主控信息
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const createAreaController = (areaControllerData) => {
   return http.post('/api/v1/area-controllers', areaControllerData);
@@ -20,7 +48,7 @@ export const createAreaController = (areaControllerData) => {
 /**
  * 根据ID获取单个区域主控的详细信息
  * @param {string} id - 区域主控ID
- * @returns {Promise<*>}
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const getAreaControllerById = (id) => {
   return http.get(`/api/v1/area-controllers/${id}`);
@@ -29,8 +57,8 @@ export const getAreaControllerById = (id) => {
 /**
  * 根据ID更新一个已存在的区域主控信息
  * @param {string} id - 区域主控ID
- * @param {object} areaControllerData - 要更新的区域主控信息，对应 dto.UpdateAreaControllerRequest
- * @returns {Promise<*>}
+ * @param {UpdateAreaControllerRequest} areaControllerData - 要更新的区域主控信息
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const updateAreaController = (id, areaControllerData) => {
   return http.put(`/api/v1/area-controllers/${id}`, areaControllerData);
diff --git a/src/api/device.js b/src/api/device.js
index 16fd36cf..5538ab6a 100644
--- a/src/api/device.js
+++ b/src/api/device.js
@@ -1,10 +1,78 @@
 import http from '../utils/http';
 
+// --- Typedefs ---
+
+/**
+ * @typedef {object} DeviceResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} location
+ * @property {number} area_controller_id
+ * @property {string} area_controller_name
+ * @property {number} device_template_id
+ * @property {string} device_template_name
+ * @property {object} properties
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} CreateDeviceRequest
+ * @property {string} name
+ * @property {string} [location]
+ * @property {number} area_controller_id
+ * @property {number} device_template_id
+ * @property {object} [properties]
+ */
+
+/**
+ * @typedef {object} UpdateDeviceRequest
+ * @property {string} name
+ * @property {string} [location]
+ * @property {number} area_controller_id
+ * @property {number} device_template_id
+ * @property {object} [properties]
+ */
+
+/**
+ * @typedef {object} ManualControlDeviceRequest
+ * @property {string} [action] - Action 不传表示这是一个传感器, 会触发一次采集
+ */
+
+/**
+ * @typedef {object} AreaControllerResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} location
+ * @property {string} status
+ * @property {object} properties
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} CreateAreaControllerRequest
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} [location]
+ * @property {object} [properties]
+ */
+
+/**
+ * @typedef {object} UpdateAreaControllerRequest
+ * @property {string} name
+ * @property {string} network_id
+ * @property {string} [location]
+ * @property {object} [properties]
+ */
+
+
 // --- Device API Functions ---
 
 /**
  * 获取系统中所有设备的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<DeviceResponse>>}
  */
 export const getDevices = () => {
   return http.get('/api/v1/devices');
@@ -12,8 +80,8 @@ export const getDevices = () => {
 
 /**
  * 根据提供的信息创建一个新设备
- * @param {object} deviceData - 设备信息，对应 dto.CreateDeviceRequest
- * @returns {Promise<*>}
+ * @param {CreateDeviceRequest} deviceData - 设备信息
+ * @returns {Promise<DeviceResponse>}
  */
 export const createDevice = (deviceData) => {
   return http.post('/api/v1/devices', deviceData);
@@ -22,7 +90,7 @@ export const createDevice = (deviceData) => {
 /**
  * 根据设备ID获取单个设备的详细信息
  * @param {string} id - 设备ID
- * @returns {Promise<*>}
+ * @returns {Promise<DeviceResponse>}
  */
 export const getDeviceById = (id) => {
   return http.get(`/api/v1/devices/${id}`);
@@ -31,8 +99,8 @@ export const getDeviceById = (id) => {
 /**
  * 根据设备ID更新一个已存在的设备信息
  * @param {string} id - 设备ID
- * @param {object} deviceData - 要更新的设备信息，对应 dto.UpdateDeviceRequest
- * @returns {Promise<*>}
+ * @param {UpdateDeviceRequest} deviceData - 要更新的设备信息
+ * @returns {Promise<DeviceResponse>}
  */
 export const updateDevice = (id, deviceData) => {
   return http.put(`/api/v1/devices/${id}`, deviceData);
@@ -50,7 +118,7 @@ export const deleteDevice = (id) => {
 /**
  * 根据设备ID和指定的动作（开启或关闭）来手动控制设备
  * @param {string} id - 设备ID
- * @param {object} manualControlData - 手动控制指令，对应 dto.ManualControlDeviceRequest
+ * @param {ManualControlDeviceRequest} manualControlData - 手动控制指令
  * @returns {Promise<*>}
  */
 export const manualControlDevice = (id, manualControlData) => {
@@ -62,7 +130,7 @@ export const manualControlDevice = (id, manualControlData) => {
 
 /**
  * 获取系统中所有区域主控的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<AreaControllerResponse>>}
  */
 export const getAreaControllers = () => {
   return http.get('/api/v1/area-controllers');
@@ -70,8 +138,8 @@ export const getAreaControllers = () => {
 
 /**
  * 创建一个新区域主控
- * @param {object} areaControllerData - 区域主控信息
- * @returns {Promise<*>}
+ * @param {CreateAreaControllerRequest} areaControllerData - 区域主控信息
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const createAreaController = (areaControllerData) => {
   return http.post('/api/v1/area-controllers', areaControllerData);
@@ -80,7 +148,7 @@ export const createAreaController = (areaControllerData) => {
 /**
  * 根据ID获取单个区域主控的详细信息
  * @param {string} id - 区域主控ID
- * @returns {Promise<*>}
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const getAreaControllerById = (id) => {
   return http.get(`/api/v1/area-controllers/${id}`);
@@ -89,8 +157,8 @@ export const getAreaControllerById = (id) => {
 /**
  * 根据ID更新一个已存在的区域主控信息
  * @param {string} id - 区域主控ID
- * @param {object} areaControllerData - 要更新的区域主控信息
- * @returns {Promise<*>}
+ * @param {UpdateAreaControllerRequest} areaControllerData - 要更新的区域主控信息
+ * @returns {Promise<AreaControllerResponse>}
  */
 export const updateAreaController = (id, areaControllerData) => {
   return http.put(`/api/v1/area-controllers/${id}`, areaControllerData);
@@ -123,5 +191,6 @@ export const DeviceApi = {
   create: createDevice,
   getById: getDeviceById,
   update: updateDevice,
-  delete: deleteDevice
+  delete: deleteDevice,
+  manualControl: manualControlDevice
 };
diff --git a/src/api/deviceTemplate.js b/src/api/deviceTemplate.js
index d45f9d55..bb2db9ec 100644
--- a/src/api/deviceTemplate.js
+++ b/src/api/deviceTemplate.js
@@ -1,8 +1,57 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {('执行器'|'传感器')} DeviceCategory
+ */
+
+/**
+ * @typedef {('信号强度'|'电池电量'|'温度'|'湿度'|'重量')} SensorType
+ */
+
+/**
+ * @typedef {object} ValueDescriptor
+ * @property {SensorType} type
+ * @property {number} [multiplier] - 乘数，用于原始数据转换
+ * @property {number} [offset] - 偏移量，用于原始数据转换
+ */
+
+/**
+ * @typedef {object} DeviceTemplateResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} [manufacturer]
+ * @property {DeviceCategory} category
+ * @property {object} commands
+ * @property {Array<ValueDescriptor>} values
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} CreateDeviceTemplateRequest
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} [manufacturer]
+ * @property {DeviceCategory} category
+ * @property {object} commands
+ * @property {Array<ValueDescriptor>} [values]
+ */
+
+/**
+ * @typedef {object} UpdateDeviceTemplateRequest
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} [manufacturer]
+ * @property {DeviceCategory} category
+ * @property {object} commands
+ * @property {Array<ValueDescriptor>} [values]
+ */
+
+
 /**
  * 获取系统中所有设备模板的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<DeviceTemplateResponse>>}
  */
 const getDeviceTemplates = () => {
   return http.get('/api/v1/device-templates');
@@ -10,8 +59,8 @@ const getDeviceTemplates = () => {
 
 /**
  * 根据提供的信息创建一个新设备模板
- * @param {object} deviceTemplateData - 设备模板信息，对应 dto.CreateDeviceTemplateRequest
- * @returns {Promise<*>}
+ * @param {CreateDeviceTemplateRequest} deviceTemplateData - 设备模板信息
+ * @returns {Promise<DeviceTemplateResponse>}
  */
 const createDeviceTemplate = (deviceTemplateData) => {
   return http.post('/api/v1/device-templates', deviceTemplateData);
@@ -20,7 +69,7 @@ const createDeviceTemplate = (deviceTemplateData) => {
 /**
  * 根据设备模板ID获取单个设备模板的详细信息
  * @param {string} id - 设备模板ID
- * @returns {Promise<*>}
+ * @returns {Promise<DeviceTemplateResponse>}
  */
 const getDeviceTemplateById = (id) => {
   return http.get(`/api/v1/device-templates/${id}`);
@@ -29,8 +78,8 @@ const getDeviceTemplateById = (id) => {
 /**
  * 根据设备模板ID更新一个已存在的设备模板信息
  * @param {string} id - 设备模板ID
- * @param {object} deviceTemplateData - 要更新的设备模板信息，对应 dto.UpdateDeviceTemplateRequest
- * @returns {Promise<*>}
+ * @param {UpdateDeviceTemplateRequest} deviceTemplateData - 要更新的设备模板信息
+ * @returns {Promise<DeviceTemplateResponse>}
  */
 const updateDeviceTemplate = (id, deviceTemplateData) => {
   return http.put(`/api/v1/device-templates/${id}`, deviceTemplateData);
diff --git a/src/api/monitor.js b/src/api/monitor.js
index bd83c578..ba0072fa 100644
--- a/src/api/monitor.js
+++ b/src/api/monitor.js
@@ -1,30 +1,636 @@
 import http from '../utils/http';
 
-// 这个辅助函数现在接收后端返回的JSON数据本身，而不是整个axios响应
+// --- Typedefs ---
+
+/**
+ * @typedef {object} PaginationDTO
+ * @property {number} page
+ * @property {number} pageSize
+ * @property {number} total
+ */
+
+/**
+ * @typedef {object} DeviceCommandLogDTO
+ * @property {string} message_id
+ * @property {number} device_id
+ * @property {string} sent_at
+ * @property {string} acknowledged_at
+ * @property {boolean} received_success
+ */
+
+/**
+ * @typedef {object} ListDeviceCommandLogResponse
+ * @property {Array<DeviceCommandLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} DeviceCommandLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [device_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @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
+ * @property {number} pen_id
+ * @property {PenDTO} pen
+ * @property {number} feed_formula_id
+ * @property {FeedFormulaDTO} feed_formula
+ * @property {number} amount
+ * @property {string} recorded_at
+ * @property {string} remarks
+ * @property {number} operator_id
+ */
+
+/**
+ * @typedef {object} ListFeedUsageRecordResponse
+ * @property {Array<FeedUsageRecordDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} FeedUsageRecordsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pen_id]
+ * @property {number} [feed_formula_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {('预防'|'治疗'|'保健')} MedicationReasonType
+ */
+
+/**
+ * @typedef {object} MedicationDTO
+ * @property {number} id
+ * @property {string} name
+ */
+
+/**
+ * @typedef {object} MedicationLogDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {number} medication_id
+ * @property {MedicationDTO} medication
+ * @property {number} dosage_used
+ * @property {number} target_count
+ * @property {MedicationReasonType} reason
+ * @property {string} description
+ * @property {string} happened_at
+ * @property {number} operator_id
+ */
+
+/**
+ * @typedef {object} ListMedicationLogResponse
+ * @property {Array<MedicationLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} MedicationLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {number} [medication_id]
+ * @property {string} [reason]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {('等待中'|'已完成'|'已超时')} PendingCollectionStatus
+ */
+
+/**
+ * @typedef {object} PendingCollectionDTO
+ * @property {string} correlation_id
+ * @property {number} device_id
+ * @property {Array<number>} command_metadata
+ * @property {PendingCollectionStatus} status
+ * @property {string} created_at
+ * @property {string} fulfilled_at
+ */
+
+/**
+ * @typedef {object} ListPendingCollectionResponse
+ * @property {Array<PendingCollectionDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PendingCollectionsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [device_id]
+ * @property {string} [status]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {('死亡'|'淘汰'|'销售'|'购买'|'转入'|'转出'|'盘点校正')} LogChangeType
+ */
+
+/**
+ * @typedef {object} PigBatchLogDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {LogChangeType} change_type
+ * @property {number} before_count
+ * @property {number} after_count
+ * @property {number} change_count
+ * @property {string} reason
+ * @property {number} operator_id
+ * @property {string} happened_at
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPigBatchLogResponse
+ * @property {Array<PigBatchLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PigBatchLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {string} [change_type]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {object} PigPurchaseDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {number} quantity
+ * @property {number} unit_price
+ * @property {number} total_price
+ * @property {string} supplier
+ * @property {string} purchase_date
+ * @property {string} remarks
+ * @property {number} operator_id
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPigPurchaseResponse
+ * @property {Array<PigPurchaseDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PigPurchasesParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {string} [supplier]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {object} PigSaleDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {number} quantity
+ * @property {number} unit_price
+ * @property {number} total_price
+ * @property {string} buyer
+ * @property {string} sale_date
+ * @property {string} remarks
+ * @property {number} operator_id
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPigSaleResponse
+ * @property {Array<PigSaleDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PigSalesParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {string} [buyer]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {('患病'|'康复'|'死亡'|'淘汰'|'转入'|'转出'|'其他')} PigBatchSickPigReasonType
+ */
+
+/**
+ * @typedef {('原地治疗'|'病猪栏治疗')} PigBatchSickPigTreatmentLocation
+ */
+
+/**
+ * @typedef {object} PigSickLogDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {number} pen_id
+ * @property {PigBatchSickPigReasonType} reason
+ * @property {PigBatchSickPigTreatmentLocation} treatment_location
+ * @property {number} before_count
+ * @property {number} after_count
+ * @property {number} change_count
+ * @property {string} remarks
+ * @property {number} operator_id
+ * @property {string} happened_at
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPigSickLogResponse
+ * @property {Array<PigSickLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PigSickLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {number} [pen_id]
+ * @property {string} [reason]
+ * @property {string} [treatment_location]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {('群内调栏'|'跨群调栏'|'销售'|'死亡'|'淘汰'|'新购入'|'产房转入')} PigTransferType
+ */
+
+/**
+ * @typedef {object} PigTransferLogDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {number} pen_id
+ * @property {PigTransferType} type
+ * @property {number} quantity
+ * @property {string} remarks
+ * @property {string} correlation_id
+ * @property {number} operator_id
+ * @property {string} transfer_time
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPigTransferLogResponse
+ * @property {Array<PigTransferLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PigTransferLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {number} [pen_id]
+ * @property {string} [transfer_type]
+ * @property {string} [correlation_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+/**
+ * @typedef {('已开始'|'已完成'|'失败'|'已取消'|'等待中')} ExecutionStatus
+ */
+
+/**
+ * @typedef {object} PlanExecutionLogDTO
+ * @property {number} id
+ * @property {number} plan_id
+ * @property {ExecutionStatus} status
+ * @property {string} started_at
+ * @property {string} ended_at
+ * @property {string} error
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListPlanExecutionLogResponse
+ * @property {Array<PlanExecutionLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} PlanExecutionLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [plan_id]
+ * @property {string} [status]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {object} RawMaterialDTO
+ * @property {number} id
+ * @property {string} name
+ */
+
+/**
+ * @typedef {object} RawMaterialPurchaseDTO
+ * @property {number} id
+ * @property {number} raw_material_id
+ * @property {RawMaterialDTO} raw_material
+ * @property {number} amount
+ * @property {number} unit_price
+ * @property {number} total_price
+ * @property {string} supplier
+ * @property {string} purchase_date
+ * @property {string} created_at
+ */
+
+/**
+ * @typedef {object} ListRawMaterialPurchaseResponse
+ * @property {Array<RawMaterialPurchaseDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} RawMaterialPurchasesParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [raw_material_id]
+ * @property {string} [supplier]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {('采购入库'|'饲喂出库'|'变质出库'|'售卖出库'|'杂用领取'|'手动盘点')} StockLogSourceType
+ */
+
+/**
+ * @typedef {object} RawMaterialStockLogDTO
+ * @property {number} id
+ * @property {number} raw_material_id
+ * @property {number} change_amount
+ * @property {StockLogSourceType} source_type
+ * @property {number} source_id
+ * @property {string} remarks
+ * @property {string} happened_at
+ */
+
+/**
+ * @typedef {object} ListRawMaterialStockLogResponse
+ * @property {Array<RawMaterialStockLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} RawMaterialStockLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [raw_material_id]
+ * @property {string} [source_type]
+ * @property {number} [source_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {('信号强度'|'电池电量'|'温度'|'湿度'|'重量')} SensorType
+ */
+
+/**
+ * @typedef {object} SensorDataDTO
+ * @property {number} regional_controller_id
+ * @property {number} device_id
+ * @property {SensorType} sensor_type
+ * @property {Array<number>} data
+ * @property {string} time
+ */
+
+/**
+ * @typedef {object} ListSensorDataResponse
+ * @property {Array<SensorDataDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} SensorDataParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [device_id]
+ * @property {string} [sensor_type]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {object} TaskDTO
+ * @property {number} id
+ * @property {string} name
+ * @property {string} description
+ */
+
+/**
+ * @typedef {object} TaskExecutionLogDTO
+ * @property {number} id
+ * @property {number} plan_execution_log_id
+ * @property {number} task_id
+ * @property {TaskDTO} task
+ * @property {ExecutionStatus} status
+ * @property {string} output
+ * @property {string} started_at
+ * @property {string} ended_at
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListTaskExecutionLogResponse
+ * @property {Array<TaskExecutionLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} TaskExecutionLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [plan_execution_log_id]
+ * @property {number} [task_id]
+ * @property {string} [status]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {('成功'|'失败')} AuditStatus
+ */
+
+/**
+ * @typedef {object} UserActionLogDTO
+ * @property {number} id
+ * @property {number} user_id
+ * @property {string} username
+ * @property {string} action_type
+ * @property {string} description
+ * @property {string} http_method
+ * @property {string} http_path
+ * @property {string} source_ip
+ * @property {Array<number>} target_resource
+ * @property {AuditStatus} status
+ * @property {string} result_details
+ * @property {string} time
+ */
+
+/**
+ * @typedef {object} ListUserActionLogResponse
+ * @property {Array<UserActionLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} UserActionLogsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [user_id]
+ * @property {string} [username]
+ * @property {string} [action_type]
+ * @property {string} [status]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {object} WeighingBatchDTO
+ * @property {number} id
+ * @property {number} pig_batch_id
+ * @property {string} description
+ * @property {string} weighing_time
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListWeighingBatchResponse
+ * @property {Array<WeighingBatchDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} WeighingBatchesParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [pig_batch_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ */
+
+/**
+ * @typedef {object} WeighingRecordDTO
+ * @property {number} id
+ * @property {number} weighing_batch_id
+ * @property {number} pen_id
+ * @property {number} weight
+ * @property {string} remark
+ * @property {number} operator_id
+ * @property {string} weighing_time
+ * @property {string} created_at
+ * @property {string} updated_at
+ */
+
+/**
+ * @typedef {object} ListWeighingRecordResponse
+ * @property {Array<WeighingRecordDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} WeighingRecordsParams
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [order_by]
+ * @property {number} [weighing_batch_id]
+ * @property {number} [pen_id]
+ * @property {string} [start_time]
+ * @property {string} [end_time]
+ * @property {number} [operator_id]
+ */
+
+
+// --- Functions ---
+
 const processResponse = (responseData) => {
-  // 后端数据在responseData.data中
   const data = responseData.data;
   return {
     list: data.list || [],
-    total: data.pagination.total || 0,
+    total: data.pagination ? data.pagination.total : 0,
   };
 };
 
 /**
  * 获取设备命令日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {DeviceCommandLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<DeviceCommandLogDTO>, total: number}>}
  */
 export const getDeviceCommandLogs = async (params) => {
-  // http.get 通常被封装为返回 response.data
   const responseData = await http.get('/api/v1/monitor/device-command-logs', { params });
   return processResponse(responseData);
 };
 
 /**
  * 获取饲料使用记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {FeedUsageRecordsParams} params - 查询参数
+ * @returns {Promise<{list: Array<FeedUsageRecordDTO>, total: number}>}
  */
 export const getFeedUsageRecords = async (params) => {
   const responseData = await http.get('/api/v1/monitor/feed-usage-records', { params });
@@ -33,8 +639,8 @@ export const getFeedUsageRecords = async (params) => {
 
 /**
  * 获取用药记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {MedicationLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<MedicationLogDTO>, total: number}>}
  */
 export const getMedicationLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/medication-logs', { params });
@@ -43,8 +649,8 @@ export const getMedicationLogs = async (params) => {
 
 /**
  * 获取待采集请求列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PendingCollectionsParams} params - 查询参数
+ * @returns {Promise<{list: Array<PendingCollectionDTO>, total: number}>}
  */
 export const getPendingCollections = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pending-collections', { params });
@@ -53,8 +659,8 @@ export const getPendingCollections = async (params) => {
 
 /**
  * 获取猪批次日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PigBatchLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<PigBatchLogDTO>, total: number}>}
  */
 export const getPigBatchLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pig-batch-logs', { params });
@@ -63,8 +669,8 @@ export const getPigBatchLogs = async (params) => {
 
 /**
  * 获取猪只采购记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PigPurchasesParams} params - 查询参数
+ * @returns {Promise<{list: Array<PigPurchaseDTO>, total: number}>}
  */
 export const getPigPurchases = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pig-purchases', { params });
@@ -73,8 +679,8 @@ export const getPigPurchases = async (params) => {
 
 /**
  * 获取猪只售卖记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PigSalesParams} params - 查询参数
+ * @returns {Promise<{list: Array<PigSaleDTO>, total: number}>}
  */
 export const getPigSales = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pig-sales', { params });
@@ -83,8 +689,8 @@ export const getPigSales = async (params) => {
 
 /**
  * 获取病猪日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PigSickLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<PigSickLogDTO>, total: number}>}
  */
 export const getPigSickLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pig-sick-logs', { params });
@@ -93,8 +699,8 @@ export const getPigSickLogs = async (params) => {
 
 /**
  * 获取猪只迁移日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PigTransferLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<PigTransferLogDTO>, total: number}>}
  */
 export const getPigTransferLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/pig-transfer-logs', { params });
@@ -103,8 +709,8 @@ export const getPigTransferLogs = async (params) => {
 
 /**
  * 获取计划执行日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {PlanExecutionLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<PlanExecutionLogDTO>, total: number}>}
  */
 export const getPlanExecutionLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/plan-execution-logs', { params });
@@ -113,8 +719,8 @@ export const getPlanExecutionLogs = async (params) => {
 
 /**
  * 获取原料采购记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {RawMaterialPurchasesParams} params - 查询参数
+ * @returns {Promise<{list: Array<RawMaterialPurchaseDTO>, total: number}>}
  */
 export const getRawMaterialPurchases = async (params) => {
   const responseData = await http.get('/api/v1/monitor/raw-material-purchases', { params });
@@ -123,8 +729,8 @@ export const getRawMaterialPurchases = async (params) => {
 
 /**
  * 获取原料库存日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {RawMaterialStockLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<RawMaterialStockLogDTO>, total: number}>}
  */
 export const getRawMaterialStockLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/raw-material-stock-logs', { params });
@@ -133,8 +739,8 @@ export const getRawMaterialStockLogs = async (params) => {
 
 /**
  * 获取传感器数据列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {SensorDataParams} params - 查询参数
+ * @returns {Promise<{list: Array<SensorDataDTO>, total: number}>}
  */
 export const getSensorData = async (params) => {
   const responseData = await http.get('/api/v1/monitor/sensor-data', { params });
@@ -143,8 +749,8 @@ export const getSensorData = async (params) => {
 
 /**
  * 获取任务执行日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {TaskExecutionLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<TaskExecutionLogDTO>, total: number}>}
  */
 export const getTaskExecutionLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/task-execution-logs', { params });
@@ -153,8 +759,8 @@ export const getTaskExecutionLogs = async (params) => {
 
 /**
  * 获取用户操作日志列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {UserActionLogsParams} params - 查询参数
+ * @returns {Promise<{list: Array<UserActionLogDTO>, total: number}>}
  */
 export const getUserActionLogs = async (params) => {
   const responseData = await http.get('/api/v1/monitor/user-action-logs', { params });
@@ -163,8 +769,8 @@ export const getUserActionLogs = async (params) => {
 
 /**
  * 获取批次称重记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {WeighingBatchesParams} params - 查询参数
+ * @returns {Promise<{list: Array<WeighingBatchDTO>, total: number}>}
  */
 export const getWeighingBatches = async (params) => {
   const responseData = await http.get('/api/v1/monitor/weighing-batches', { params });
@@ -173,8 +779,8 @@ export const getWeighingBatches = async (params) => {
 
 /**
  * 获取单次称重记录列表
- * @param {object} params - 查询参数
- * @returns {Promise<{list: Array, total: number}>}
+ * @param {WeighingRecordsParams} params - 查询参数
+ * @returns {Promise<{list: Array<WeighingRecordDTO>, total: number}>}
  */
 export const getWeighingRecords = async (params) => {
   const responseData = await http.get('/api/v1/monitor/weighing-records', { params });
diff --git a/src/api/pen.js b/src/api/pen.js
index e446b8c8..20838cd5 100644
--- a/src/api/pen.js
+++ b/src/api/pen.js
@@ -1,8 +1,39 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {object} PenResponse
+ * @property {number} id
+ * @property {number} house_id
+ * @property {string} pen_number
+ * @property {number} capacity
+ * @property {number} current_pig_count
+ * @property {number} pig_batch_id
+ * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ */
+
+/**
+ * @typedef {object} CreatePenRequest
+ * @property {number} house_id
+ * @property {string} pen_number
+ * @property {number} capacity
+ */
+
+/**
+ * @typedef {object} UpdatePenRequest
+ * @property {number} house_id
+ * @property {string} pen_number
+ * @property {number} capacity
+ * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ */
+
+/**
+ * @typedef {object} UpdatePenStatusRequest
+ * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ */
+
 /**
  * 获取所有猪栏的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<PenResponse>>}
  */
 export const getPens = () => {
   return http.get('/api/v1/pens');
@@ -10,8 +41,8 @@ export const getPens = () => {
 
 /**
  * 创建一个新的猪栏
- * @param {object} penData - 猪栏信息，对应 dto.CreatePenRequest
- * @returns {Promise<*>}
+ * @param {CreatePenRequest} penData - 猪栏信息
+ * @returns {Promise<PenResponse>}
  */
 export const createPen = (penData) => {
   return http.post('/api/v1/pens', penData);
@@ -20,7 +51,7 @@ export const createPen = (penData) => {
 /**
  * 根据ID获取单个猪栏信息
  * @param {number} id - 猪栏ID
- * @returns {Promise<*>}
+ * @returns {Promise<PenResponse>}
  */
 export const getPenById = (id) => {
   return http.get(`/api/v1/pens/${id}`);
@@ -29,8 +60,8 @@ export const getPenById = (id) => {
 /**
  * 更新一个已存在的猪栏信息
  * @param {number} id - 猪栏ID
- * @param {object} penData - 猪栏信息，对应 dto.UpdatePenRequest
- * @returns {Promise<*>}
+ * @param {UpdatePenRequest} penData - 猪栏信息
+ * @returns {Promise<PenResponse>}
  */
 export const updatePen = (id, penData) => {
   return http.put(`/api/v1/pens/${id}`, penData);
@@ -48,8 +79,8 @@ export const deletePen = (id) => {
 /**
  * 更新指定猪栏的当前状态
  * @param {number} id - 猪栏ID
- * @param {object} statusData - 新的猪栏状态，对应 dto.UpdatePenStatusRequest
- * @returns {Promise<*>}
+ * @param {UpdatePenStatusRequest} statusData - 新的猪栏状态
+ * @returns {Promise<PenResponse>}
  */
 export const updatePenStatus = (id, statusData) => {
   return http.put(`/api/v1/pens/${id}/status`, statusData);
diff --git a/src/api/pigBatch.js b/src/api/pigBatch.js
index 92d9ca3c..65881214 100644
--- a/src/api/pigBatch.js
+++ b/src/api/pigBatch.js
@@ -1,11 +1,193 @@
 import http from '../utils/http';
 
+// --- Typedefs ---
+
+/**
+ * @typedef {('自繁'|'外购')} PigBatchOriginType
+ */
+
+/**
+ * @typedef {('保育'|'生长'|'育肥'|'待售'|'已出售'|'已归档')} PigBatchStatus
+ */
+
+/**
+ * @typedef {object} PigBatchResponseDTO
+ * @property {number} id - 批次ID
+ * @property {string} batch_number - 批次编号
+ * @property {PigBatchOriginType} origin_type - 批次来源
+ * @property {string} start_date - 批次开始日期
+ * @property {string} [end_date] - 批次结束日期
+ * @property {number} initial_count - 初始数量
+ * @property {PigBatchStatus} status - 批次状态
+ * @property {boolean} is_active - 是否活跃
+ * @property {string} create_time - 创建时间
+ * @property {string} update_time - 更新时间
+ * @property {number} currentTotalQuantity - 当前总数
+ * @property {number} currentTotalPigsInPens - 当前存栏总数
+ */
+
+/**
+ * @typedef {object} PigBatchesParams
+ * @property {boolean} [is_active] - 是否活跃 (true/false)
+ */
+
+/**
+ * @typedef {object} PigBatchCreateDTO
+ * @property {string} batch_number - 批次编号，必填
+ * @property {PigBatchOriginType} origin_type - 批次来源，必填
+ * @property {string} start_date - 批次开始日期，必填
+ * @property {number} initial_count - 初始数量，必填，最小为1
+ * @property {PigBatchStatus} status - 批次状态，必填
+ */
+
+/**
+ * @typedef {object} PigBatchUpdateDTO
+ * @property {string} [batch_number] - 批次编号，可选
+ * @property {PigBatchOriginType} [origin_type] - 批次来源，可选
+ * @property {string} [start_date] - 批次开始日期，可选
+ * @property {string} [end_date] - 批次结束日期，可选
+ * @property {number} [initial_count] - 初始数量，可选
+ * @property {PigBatchStatus} [status] - 批次状态，可选
+ */
+
+/**
+ * @typedef {object} AssignEmptyPensToBatchRequest
+ * @property {Array<number>} pen_ids - 待分配的猪栏ID列表
+ */
+
+/**
+ * @typedef {object} BuyPigsRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 买入猪只数量
+ * @property {number} unitPrice - 单价
+ * @property {number} totalPrice - 总价
+ * @property {string} traderName - 交易方名称
+ * @property {string} tradeDate - 交易日期
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} SellPigsRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 卖出猪只数量
+ * @property {number} unitPrice - 单价
+ * @property {number} totalPrice - 总价
+ * @property {string} traderName - 交易方名称
+ * @property {string} tradeDate - 交易日期
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} MovePigsIntoPenRequest
+ * @property {number} toPenID - 目标猪栏ID
+ * @property {number} quantity - 移入猪只数量
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} TransferPigsWithinBatchRequest
+ * @property {number} fromPenID - 源猪栏ID
+ * @property {number} toPenID - 目标猪栏ID
+ * @property {number} quantity - 调栏猪只数量
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} TransferPigsAcrossBatchesRequest
+ * @property {number} fromPenID - 源猪栏ID
+ * @property {number} destBatchID - 目标猪批次ID
+ * @property {number} toPenID - 目标猪栏ID
+ * @property {number} quantity - 调栏猪只数量
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} ReclassifyPenToNewBatchRequest
+ * @property {number} penID - 待划拨的猪栏ID
+ * @property {number} toBatchID - 目标猪批次ID
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {('原地治疗'|'病猪栏治疗')} PigBatchSickPigTreatmentLocation
+ */
+
+/**
+ * @typedef {object} RecordSickPigsRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 病猪数量
+ * @property {PigBatchSickPigTreatmentLocation} treatmentLocation - 治疗地点
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} RecordSickPigRecoveryRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 康复猪数量
+ * @property {PigBatchSickPigTreatmentLocation} treatmentLocation - 治疗地点
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} RecordSickPigDeathRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 死亡猪数量
+ * @property {PigBatchSickPigTreatmentLocation} treatmentLocation - 治疗地点
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} RecordSickPigCullRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 淘汰猪数量
+ * @property {PigBatchSickPigTreatmentLocation} treatmentLocation - 治疗地点
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} RecordDeathRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 死亡猪数量
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} RecordCullRequest
+ * @property {number} penID - 猪栏ID
+ * @property {number} quantity - 淘汰猪数量
+ * @property {string} happenedAt - 发生时间
+ * @property {string} [remarks] - 备注
+ */
+
+/**
+ * @typedef {object} PenResponse
+ * @property {number} id
+ * @property {number} house_id
+ * @property {string} pen_number
+ * @property {number} capacity
+ * @property {number} current_pig_count
+ * @property {number} pig_batch_id
+ * @property {('空闲'|'使用中'|'病猪栏'|'康复栏'|'清洗消毒'|'维修中')} status
+ */
+
+/**
+ * @typedef {object} PigHouseResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} description
+ */
+
 // --- 猪批次基础操作 ---
 
 /**
  * 获取所有猪批次的列表
- * @param {object} params - 查询参数，例如 { is_active: true }
- * @returns {Promise<*>}
+ * @param {PigBatchesParams} params - 查询参数
+ * @returns {Promise<Array<PigBatchResponseDTO>>}
  */
 export const getPigBatches = (params) => {
   return http.get('/api/v1/pig-batches', { params });
@@ -13,8 +195,8 @@ export const getPigBatches = (params) => {
 
 /**
  * 创建一个新的猪批次
- * @param {object} batchData - 猪批次信息，对应 dto.PigBatchCreateDTO
- * @returns {Promise<*>}
+ * @param {PigBatchCreateDTO} batchData - 猪批次信息
+ * @returns {Promise<PigBatchResponseDTO>}
  */
 export const createPigBatch = (batchData) => {
   return http.post('/api/v1/pig-batches', batchData);
@@ -23,7 +205,7 @@ export const createPigBatch = (batchData) => {
 /**
  * 根据ID获取单个猪批次信息
  * @param {number} id - 猪批次ID
- * @returns {Promise<*>}
+ * @returns {Promise<PigBatchResponseDTO>}
  */
 export const getPigBatchById = (id) => {
   return http.get(`/api/v1/pig-batches/${id}`);
@@ -32,8 +214,8 @@ export const getPigBatchById = (id) => {
 /**
  * 更新一个已存在的猪批次信息
  * @param {number} id - 猪批次ID
- * @param {object} batchData - 猪批次信息，对应 dto.PigBatchUpdateDTO
- * @returns {Promise<*>}
+ * @param {PigBatchUpdateDTO} batchData - 猪批次信息
+ * @returns {Promise<PigBatchResponseDTO>}
  */
 export const updatePigBatch = (id, batchData) => {
   return http.put(`/api/v1/pig-batches/${id}`, batchData);
@@ -53,7 +235,7 @@ export const deletePigBatch = (id) => {
 /**
  * 为猪批次分配空栏
  * @param {number} id - 猪批次ID
- * @param {object} pensData - 待分配的猪栏ID列表，对应 dto.AssignEmptyPensToBatchRequest
+ * @param {AssignEmptyPensToBatchRequest} pensData - 待分配的猪栏ID列表
  * @returns {Promise<*>}
  */
 export const assignPensToBatch = (id, pensData) => {
@@ -73,7 +255,7 @@ export const removePenFromBatch = (batchID, penID) => {
 /**
  * 处理买猪的业务逻辑
  * @param {number} id - 猪批次ID
- * @param {object} buyData - 买猪请求信息，对应 dto.BuyPigsRequest
+ * @param {BuyPigsRequest} buyData - 买猪请求信息
  * @returns {Promise<*>}
  */
 export const buyPigsForBatch = (id, buyData) => {
@@ -83,7 +265,7 @@ export const buyPigsForBatch = (id, buyData) => {
 /**
  * 处理卖猪的业务逻辑
  * @param {number} id - 猪批次ID
- * @param {object} sellData - 卖猪请求信息，对应 dto.SellPigsRequest
+ * @param {SellPigsRequest} sellData - 卖猪请求信息
  * @returns {Promise<*>}
  */
 export const sellPigsFromBatch = (id, sellData) => {
@@ -93,7 +275,7 @@ export const sellPigsFromBatch = (id, sellData) => {
 /**
  * 将猪只从“虚拟库存”移入指定猪栏
  * @param {number} id - 猪批次ID
- * @param {object} moveData - 移入猪只请求信息，对应 dto.MovePigsIntoPenRequest
+ * @param {MovePigsIntoPenRequest} moveData - 移入猪只请求信息
  * @returns {Promise<*>}
  */
 export const movePigsIntoPen = (id, moveData) => {
@@ -103,7 +285,7 @@ export const movePigsIntoPen = (id, moveData) => {
 /**
  * 群内调栏
  * @param {number} id - 猪批次ID
- * @param {object} transferData - 群内调栏请求信息，对应 dto.TransferPigsWithinBatchRequest
+ * @param {TransferPigsWithinBatchRequest} transferData - 群内调栏请求信息
  * @returns {Promise<*>}
  */
 export const transferPigsWithinBatch = (id, transferData) => {
@@ -113,7 +295,7 @@ export const transferPigsWithinBatch = (id, transferData) => {
 /**
  * 跨猪群调栏
  * @param {number} sourceBatchID - 源猪批次ID
- * @param {object} transferData - 跨群调栏请求信息，对应 dto.TransferPigsAcrossBatchesRequest
+ * @param {TransferPigsAcrossBatchesRequest} transferData - 跨群调栏请求信息
  * @returns {Promise<*>}
  */
 export const transferPigsAcrossBatches = (sourceBatchID, transferData) => {
@@ -123,7 +305,7 @@ export const transferPigsAcrossBatches = (sourceBatchID, transferData) => {
 /**
  * 将猪栏划拨到新批次
  * @param {number} fromBatchID - 源猪批次ID
- * @param {object} reclassifyData - 划拨请求信息，对应 dto.ReclassifyPenToNewBatchRequest
+ * @param {ReclassifyPenToNewBatchRequest} reclassifyData - 划拨请求信息
  * @returns {Promise<*>}
  */
 export const reclassifyPenToNewBatch = (fromBatchID, reclassifyData) => {
@@ -135,7 +317,7 @@ export const reclassifyPenToNewBatch = (fromBatchID, reclassifyData) => {
 /**
  * 记录新增病猪事件
  * @param {number} id - 猪批次ID
- * @param {object} sickData - 记录病猪请求信息，对应 dto.RecordSickPigsRequest
+ * @param {RecordSickPigsRequest} sickData - 记录病猪请求信息
  * @returns {Promise<*>}
  */
 export const recordSickPigsInBatch = (id, sickData) => {
@@ -145,7 +327,7 @@ export const recordSickPigsInBatch = (id, sickData) => {
 /**
  * 记录病猪康复事件
  * @param {number} id - 猪批次ID
- * @param {object} recoveryData - 记录病猪康复请求信息，对应 dto.RecordSickPigRecoveryRequest
+ * @param {RecordSickPigRecoveryRequest} recoveryData - 记录病猪康复请求信息
  * @returns {Promise<*>}
  */
 export const recordSickPigRecoveryInBatch = (id, recoveryData) => {
@@ -155,7 +337,7 @@ export const recordSickPigRecoveryInBatch = (id, recoveryData) => {
 /**
  * 记录病猪死亡事件
  * @param {number} id - 猪批次ID
- * @param {object} deathData - 记录病猪死亡请求信息，对应 dto.RecordSickPigDeathRequest
+ * @param {RecordSickPigDeathRequest} deathData - 记录病猪死亡请求信息
  * @returns {Promise<*>}
  */
 export const recordSickPigDeathInBatch = (id, deathData) => {
@@ -165,7 +347,7 @@ export const recordSickPigDeathInBatch = (id, deathData) => {
 /**
  * 记录病猪淘汰事件
  * @param {number} id - 猪批次ID
- * @param {object} cullData - 记录病猪淘汰请求信息，对应 dto.RecordSickPigCullRequest
+ * @param {RecordSickPigCullRequest} cullData - 记录病猪淘汰请求信息
  * @returns {Promise<*>}
  */
 export const recordSickPigCullInBatch = (id, cullData) => {
@@ -175,7 +357,7 @@ export const recordSickPigCullInBatch = (id, cullData) => {
 /**
  * 记录正常猪只死亡事件
  * @param {number} id - 猪批次ID
- * @param {object} deathData - 记录正常猪只死亡请求信息，对应 dto.RecordDeathRequest
+ * @param {RecordDeathRequest} deathData - 记录正常猪只死亡请求信息
  * @returns {Promise<*>}
  */
 export const recordDeathInBatch = (id, deathData) => {
@@ -185,7 +367,7 @@ export const recordDeathInBatch = (id, deathData) => {
 /**
  * 记录正常猪只淘汰事件
  * @param {number} id - 猪批次ID
- * @param {object} cullData - 记录正常猪只淘汰请求信息，对应 dto.RecordCullRequest
+ * @param {RecordCullRequest} cullData - 记录正常猪只淘汰请求信息
  * @returns {Promise<*>}
  */
 export const recordCullInBatch = (id, cullData) => {
@@ -196,7 +378,7 @@ export const recordCullInBatch = (id, cullData) => {
 
 /**
  * 获取所有猪栏的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<PenResponse>>}
  */
 export const getAllPens = () => {
   return http.get('/api/v1/pens');
@@ -204,7 +386,7 @@ export const getAllPens = () => {
 
 /**
  * 获取所有猪舍的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<PigHouseResponse>>}
  */
 export const getAllPigHouses = () => {
   return http.get('/api/v1/pig-houses');
diff --git a/src/api/pigHouse.js b/src/api/pigHouse.js
index ee314541..b2c7c08f 100644
--- a/src/api/pigHouse.js
+++ b/src/api/pigHouse.js
@@ -1,8 +1,27 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {object} PigHouseResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} description
+ */
+
+/**
+ * @typedef {object} CreatePigHouseRequest
+ * @property {string} name
+ * @property {string} [description]
+ */
+
+/**
+ * @typedef {object} UpdatePigHouseRequest
+ * @property {string} name
+ * @property {string} [description]
+ */
+
 /**
  * 获取所有猪舍的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<PigHouseResponse>>}
  */
 export const getPigHouses = () => {
   return http.get('/api/v1/pig-houses');
@@ -10,8 +29,8 @@ export const getPigHouses = () => {
 
 /**
  * 创建一个新的猪舍
- * @param {object} pigHouseData - 猪舍信息，对应 dto.CreatePigHouseRequest
- * @returns {Promise<*>}
+ * @param {CreatePigHouseRequest} pigHouseData - 猪舍信息
+ * @returns {Promise<PigHouseResponse>}
  */
 export const createPigHouse = (pigHouseData) => {
   return http.post('/api/v1/pig-houses', pigHouseData);
@@ -20,7 +39,7 @@ export const createPigHouse = (pigHouseData) => {
 /**
  * 根据ID获取单个猪舍信息
  * @param {number} id - 猪舍ID
- * @returns {Promise<*>}
+ * @returns {Promise<PigHouseResponse>}
  */
 export const getPigHouseById = (id) => {
   return http.get(`/api/v1/pig-houses/${id}`);
@@ -29,8 +48,8 @@ export const getPigHouseById = (id) => {
 /**
  * 更新一个已存在的猪舍信息
  * @param {number} id - 猪舍ID
- * @param {object} pigHouseData - 猪舍信息，对应 dto.UpdatePigHouseRequest
- * @returns {Promise<*>}
+ * @param {UpdatePigHouseRequest} pigHouseData - 猪舍信息
+ * @returns {Promise<PigHouseResponse>}
  */
 export const updatePigHouse = (id, pigHouseData) => {
   return http.put(`/api/v1/pig-houses/${id}`, pigHouseData);
diff --git a/src/api/plan.js b/src/api/plan.js
index 28db6e86..bd37a776 100644
--- a/src/api/plan.js
+++ b/src/api/plan.js
@@ -1,8 +1,91 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {('计划分析'|'等待'|'下料')} TaskType
+ */
+
+/**
+ * @typedef {object} TaskRequest
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {TaskType} [type]
+ * @property {object} [parameters]
+ * @property {number} [execution_order]
+ */
+
+/**
+ * @typedef {('自动'|'手动')} PlanExecutionType
+ */
+
+/**
+ * @typedef {object} CreatePlanRequest
+ * @property {string} name
+ * @property {string} [description]
+ * @property {PlanExecutionType} execution_type
+ * @property {string} [cron_expression]
+ * @property {number} [execute_num]
+ * @property {Array<TaskRequest>} [tasks]
+ * @property {Array<number>} [sub_plan_ids]
+ */
+
+/**
+ * @typedef {object} UpdatePlanRequest
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {PlanExecutionType} execution_type
+ * @property {string} [cron_expression]
+ * @property {number} [execute_num]
+ * @property {Array<TaskRequest>} [tasks]
+ * @property {Array<number>} [sub_plan_ids]
+ */
+
+/**
+ * @typedef {object} TaskResponse
+ * @property {number} id
+ * @property {number} plan_id
+ * @property {string} name
+ * @property {string} description
+ * @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 {object} PlanResponse
+ * @property {number} id
+ * @property {string} name
+ * @property {string} description
+ * @property {PlanExecutionType} execution_type
+ * @property {string} cron_expression
+ * @property {number} execute_num
+ * @property {number} execute_count
+ * @property {PlanStatus} status
+ * @property {PlanContentType} content_type
+ * @property {Array<TaskResponse>} tasks
+ * @property {Array<SubPlanResponse>} sub_plans
+ */
+
+
 /**
  * 获取所有计划的列表
- * @returns {Promise<*>}
+ * @returns {Promise<Array<PlanResponse>>}
  */
 const getPlans = () => {
   return http.get('/api/v1/plans');
@@ -10,8 +93,8 @@ const getPlans = () => {
 
 /**
  * 创建一个新的计划
- * @param {object} planData - 计划信息，对应 dto.CreatePlanRequest
- * @returns {Promise<*>}
+ * @param {CreatePlanRequest} planData - 计划信息
+ * @returns {Promise<PlanResponse>}
  */
 const createPlan = (planData) => {
   return http.post('/api/v1/plans', planData);
@@ -20,7 +103,7 @@ const createPlan = (planData) => {
 /**
  * 根据计划ID获取单个计划的详细信息
  * @param {number} id - 计划ID
- * @returns {Promise<*>}
+ * @returns {Promise<PlanResponse>}
  */
 const getPlanById = (id) => {
   return http.get(`/api/v1/plans/${id}`);
@@ -29,8 +112,8 @@ const getPlanById = (id) => {
 /**
  * 根据计划ID更新计划的详细信息
  * @param {number} id - 计划ID
- * @param {object} planData - 更新后的计划信息，对应 dto.UpdatePlanRequest
- * @returns {Promise<*>}
+ * @param {UpdatePlanRequest} planData - 更新后的计划信息
+ * @returns {Promise<PlanResponse>}
  */
 const updatePlan = (id, planData) => {
   return http.put(`/api/v1/plans/${id}`, planData);
diff --git a/src/api/user.js b/src/api/user.js
index 54fcb500..3d0d96cd 100644
--- a/src/api/user.js
+++ b/src/api/user.js
@@ -1,9 +1,80 @@
 import http from '../utils/http';
 
+/**
+ * @typedef {object} CreateUserRequest
+ * @property {string} username
+ * @property {string} password
+ */
+
+/**
+ * @typedef {object} CreateUserResponse
+ * @property {number} id
+ * @property {string} username
+ */
+
+/**
+ * @typedef {object} LoginRequest
+ * @property {string} identifier - Identifier 可以是用户名、邮箱、手机号、微信号或飞书账号
+ * @property {string} password
+ */
+
+/**
+ * @typedef {object} LoginResponse
+ * @property {number} id
+ * @property {string} username
+ * @property {string} token
+ */
+
+/**
+ * @typedef {('成功'|'失败')} AuditStatus
+ */
+
+/**
+ * @typedef {object} UserActionLogDTO
+ * @property {number} id
+ * @property {number} user_id
+ * @property {string} username
+ * @property {string} action_type
+ * @property {string} description
+ * @property {string} http_method
+ * @property {string} http_path
+ * @property {string} source_ip
+ * @property {Array<number>} target_resource
+ * @property {AuditStatus} status
+ * @property {string} result_details
+ * @property {string} time
+ */
+
+/**
+ * @typedef {object} PaginationDTO
+ * @property {number} page
+ * @property {number} pageSize
+ * @property {number} total
+ */
+
+/**
+ * @typedef {object} ListUserActionLogResponse
+ * @property {Array<UserActionLogDTO>} list
+ * @property {PaginationDTO} pagination
+ */
+
+/**
+ * @typedef {object} UserHistoryParams
+ * @property {string} [action_type]
+ * @property {string} [end_time]
+ * @property {string} [order_by]
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ * @property {string} [start_time]
+ * @property {string} [status]
+ * @property {number} [user_id]
+ * @property {string} [username]
+ */
+
 /**
  * 创建一个新用户
- * @param {object} userData - 用户信息，对应 dto.CreateUserRequest
- * @returns {Promise<*>}
+ * @param {CreateUserRequest} userData - 用户信息
+ * @returns {Promise<CreateUserResponse>}
  */
 const createUser = (userData) => {
   return http.post('/api/v1/users', userData);
@@ -11,8 +82,8 @@ const createUser = (userData) => {
 
 /**
  * 用户登录
- * @param {object} credentials - 登录凭证，对应 dto.LoginRequest
- * @returns {Promise<*>}
+ * @param {LoginRequest} credentials - 登录凭证
+ * @returns {Promise<LoginResponse>}
  */
 const login = (credentials) => {
   return http.post('/api/v1/users/login', credentials);
@@ -21,8 +92,8 @@ const login = (credentials) => {
 /**
  * 获取指定用户的操作历史
  * @param {number} id - 用户ID
- * @param {object} params - 查询参数
- * @returns {Promise<*>}
+ * @param {UserHistoryParams} params - 查询参数
+ * @returns {Promise<ListUserActionLogResponse>}
  */
 const getUserHistory = (id, params) => {
   return http.get(`/api/v1/users/${id}/history`, { params });