jiebanke/docs/动物认领系统API文档.md

动物认领系统API文档

概述

动物认领系统提供了完整的动物认领申请、审核、管理功能，支持用户申请认领动物、管理员审核申请、认领续期等功能。

基础信息

• 基础URL: /api/v1/animal-claims
• 认证方式: Bearer Token
• 数据格式: JSON
• 字符编码: UTF-8

数据模型

认领申请 (AnimalClaim)

{
  "id": 1,
  "claim_no": "CLAIM20241201001",
  "animal_id": 1,
  "animal_name": "小白",
  "animal_type": "狗",
  "animal_image": "/uploads/animals/dog1.jpg",
  "user_id": 2,
  "username": "张三",
  "user_phone": "13800138001",
  "claim_reason": "我很喜欢这只小狗",
  "claim_duration": 12,
  "total_amount": 1200.00,
  "contact_info": "手机：13800138001，微信：user001",
  "status": "pending",
  "start_date": "2024-12-01T11:30:00.000Z",
  "end_date": "2025-12-01T11:30:00.000Z",
  "reviewed_by": 1,
  "reviewer_name": "管理员",
  "review_remark": "申请材料完整，同意认领",
  "reviewed_at": "2024-12-01T11:30:00.000Z",
  "approved_at": "2024-12-01T11:30:00.000Z",
  "cancelled_at": null,
  "cancel_reason": null,
  "created_at": "2024-12-01T10:00:00.000Z",
  "updated_at": "2024-12-01T11:30:00.000Z"
}

认领统计 (ClaimStatistics)

{
  "basic": {
    "total_claims": 100,
    "pending_claims": 10,
    "approved_claims": 80,
    "rejected_claims": 8,
    "cancelled_claims": 2,
    "total_amount": 120000.00,
    "avg_duration": 12.5
  },
  "by_type": [
    {
      "type": "狗",
      "claim_count": 50,
      "approved_count": 45,
      "total_amount": 60000.00
    }
  ],
  "by_month": [
    {
      "month": "2024-12",
      "claim_count": 20,
      "approved_count": 18,
      "total_amount": 24000.00
    }
  ]
}

API接口

1. 申请认领动物

接口地址: POST /api/v1/animal-claims

请求头:

Authorization: Bearer {token}
Content-Type: application/json

请求参数:

{
  "animal_id": 1,
  "claim_reason": "我很喜欢这只小狗，希望能够认领它",
  "claim_duration": 12,
  "contact_info": "手机：13800138001，微信：user001"
}

参数说明:

• animal_id (必填): 动物ID
• claim_reason (可选): 认领理由
• claim_duration (可选): 认领时长（月），默认12个月，范围1-60
• contact_info (必填): 联系方式

响应示例:

{
  "success": true,
  "message": "认领申请提交成功",
  "data": {
    "id": 1,
    "claim_no": "CLAIM20241201001",
    "animal_id": 1,
    "user_id": 2,
    "status": "pending",
    "total_amount": 1200.00
  }
}

2. 获取我的认领申请列表

接口地址: GET /api/v1/animal-claims/my

请求参数:

• page (可选): 页码，默认1
• limit (可选): 每页数量，默认10，最大100
• status (可选): 申请状态 (pending/approved/rejected/cancelled)
• animal_type (可选): 动物类型
• start_date (可选): 开始日期 (YYYY-MM-DD)
• end_date (可选): 结束日期 (YYYY-MM-DD)

响应示例:

{
  "success": true,
  "message": "获取认领申请列表成功",
  "data": [
    {
      "id": 1,
      "claim_no": "CLAIM20241201001",
      "animal_name": "小白",
      "status": "pending"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}

3. 取消认领申请

接口地址: PUT /api/v1/animal-claims/{id}/cancel

路径参数:

• id: 认领申请ID

响应示例:

{
  "success": true,
  "message": "认领申请已取消",
  "data": {
    "id": 1,
    "status": "cancelled",
    "cancelled_at": "2024-12-01T15:00:00.000Z",
    "cancel_reason": "用户主动取消"
  }
}

4. 审核认领申请（管理员）

接口地址: PUT /api/v1/animal-claims/{id}/review

权限要求: 管理员或经理

请求参数:

{
  "status": "approved",
  "review_remark": "申请材料完整，同意认领"
}

参数说明:

• status (必填): 审核状态 (approved/rejected)
• review_remark (可选): 审核备注

响应示例:

{
  "success": true,
  "message": "认领申请审核通过",
  "data": {
    "id": 1,
    "status": "approved",
    "reviewed_at": "2024-12-01T11:30:00.000Z",
    "start_date": "2024-12-01T11:30:00.000Z",
    "end_date": "2025-12-01T11:30:00.000Z"
  }
}

5. 获取所有认领申请列表（管理员）

接口地址: GET /api/v1/animal-claims

权限要求: 管理员或经理

请求参数:

• page (可选): 页码，默认1
• limit (可选): 每页数量，默认10，最大100
• status (可选): 申请状态
• animal_type (可选): 动物类型
• user_id (可选): 用户ID
• start_date (可选): 开始日期
• end_date (可选): 结束日期
• keyword (可选): 关键词搜索（订单号、动物名称、用户名）

6. 获取动物的认领申请列表（管理员）

接口地址: GET /api/v1/animal-claims/animal/{animal_id}

权限要求: 管理员或经理

路径参数:

• animal_id: 动物ID

7. 检查认领权限

接口地址: GET /api/v1/animal-claims/check-permission/{animal_id}

路径参数:

• animal_id: 动物ID

响应示例:

{
  "success": true,
  "message": "检查认领权限成功",
  "data": {
    "can_claim": true
  }
}

8. 续期认领

接口地址: POST /api/v1/animal-claims/{id}/renew

请求参数:

{
  "duration": 6,
  "payment_method": "wechat"
}

参数说明:

• duration (必填): 续期时长（月），范围1-60
• payment_method (必填): 支付方式 (wechat/alipay/bank_transfer)

响应示例:

{
  "success": true,
  "message": "续期申请已提交，请完成支付",
  "data": {
    "renewal": {
      "id": 1,
      "claim_id": 1,
      "duration": 6,
      "amount": 600.00,
      "status": "pending"
    },
    "amount": 600.00,
    "message": "续期申请已提交，请完成支付"
  }
}

9. 获取认领统计信息（管理员）

接口地址: GET /api/v1/animal-claims/statistics

权限要求: 管理员或经理

请求参数:

• start_date (可选): 开始日期
• end_date (可选): 结束日期
• animal_type (可选): 动物类型

响应示例:

{
  "success": true,
  "message": "获取认领统计信息成功",
  "data": {
    "basic": {
      "total_claims": 100,
      "pending_claims": 10,
      "approved_claims": 80,
      "rejected_claims": 8,
      "cancelled_claims": 2,
      "total_amount": 120000.00,
      "avg_duration": 12.5
    },
    "by_type": [...],
    "by_month": [...]
  }
}

状态说明

认领申请状态

• pending: 待审核
• approved: 已通过
• rejected: 已拒绝
• cancelled: 已取消
• expired: 已过期（系统自动设置）

续期状态

• pending: 待支付
• paid: 已支付
• cancelled: 已取消

支付方式

• wechat: 微信支付
• alipay: 支付宝
• bank_transfer: 银行转账

错误码说明

错误码	说明
400	请求参数错误
401	未授权，需要登录
403	权限不足
404	资源不存在
500	服务器内部错误
503	服务不可用（无数据库模式）

业务规则

认领申请规则

1. 每个用户对同一动物只能有一个有效的认领申请
2. 只有状态为"可认领"的动物才能被申请认领
3. 认领时长范围为1-60个月
4. 认领申请通过后，动物状态自动变为"已认领"

审核规则

1. 只有待审核状态的申请才能被审核
2. 审核通过后自动设置开始和结束时间
3. 审核拒绝后动物状态保持不变

续期规则

1. 只有已通过的认领申请才能续期
2. 距离到期30天内才能申请续期
3. 续期需要完成支付才能生效

取消规则

1. 待审核和已通过的申请可以取消
2. 取消已通过的申请会恢复动物为可认领状态

注意事项

1. 所有时间字段均为UTC时间，前端需要根据时区进行转换
2. 金额字段为浮点数，建议前端使用专门的货币处理库
3. 图片路径为相对路径，需要拼接完整的URL
4. 分页查询建议设置合理的limit值，避免一次性查询过多数据
5. 关键词搜索支持模糊匹配，会搜索订单号、动物名称、用户名

集成示例

JavaScript示例

// 申请认领动物
async function claimAnimal(animalId, claimData) {
  const response = await fetch('/api/v1/animal-claims', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      animal_id: animalId,
      ...claimData
    })
  });
  
  return await response.json();
}

// 获取我的认领申请列表
async function getMyClaimList(params = {}) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`/api/v1/animal-claims/my?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  return await response.json();
}

// 取消认领申请
async function cancelClaim(claimId) {
  const response = await fetch(`/api/v1/animal-claims/${claimId}/cancel`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  return await response.json();
}

前端状态管理示例

// 认领申请状态管理
const claimStore = {
  state: {
    myClaimList: [],
    currentClaim: null,
    loading: false
  },
  
  mutations: {
    SET_CLAIM_LIST(state, list) {
      state.myClaimList = list;
    },
    
    SET_CURRENT_CLAIM(state, claim) {
      state.currentClaim = claim;
    },
    
    UPDATE_CLAIM_STATUS(state, { claimId, status }) {
      const claim = state.myClaimList.find(c => c.id === claimId);
      if (claim) {
        claim.status = status;
      }
    }
  },
  
  actions: {
    async fetchMyClaimList({ commit }, params) {
      commit('SET_LOADING', true);
      try {
        const result = await getMyClaimList(params);
        if (result.success) {
          commit('SET_CLAIM_LIST', result.data);
        }
      } finally {
        commit('SET_LOADING', false);
      }
    }
  }
};