增加jsdoc

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);