增加jsdoc

2025-10-23 15:17:31 +08:00
parent d85cfb303b
commit d7d68684e4
9 changed files with 1250 additions and 112 deletions
--- 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');