# 动物认领系统API文档

## 概述

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

## 基础信息

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

## 数据模型

### 认领申请 (AnimalClaim)

```json
{
  "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)

```json
{
  "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
```

**请求参数**:
```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` (必填): 联系方式

**响应示例**:
```json
{
  "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)

**响应示例**:
```json
{
  "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

**响应示例**:
```json
{
  "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`

**权限要求**: 管理员或经理

**请求参数**:
```json
{
  "status": "approved",
  "review_remark": "申请材料完整，同意认领"
}
```

**参数说明**:
- `status` (必填): 审核状态 (approved/rejected)
- `review_remark` (可选): 审核备注

**响应示例**:
```json
{
  "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

**响应示例**:
```json
{
  "success": true,
  "message": "检查认领权限成功",
  "data": {
    "can_claim": true
  }
}
```

### 8. 续期认领

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

**请求参数**:
```json
{
  "duration": 6,
  "payment_method": "wechat"
}
```

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

**响应示例**:
```json
{
  "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` (可选): 动物类型

**响应示例**:
```json
{
  "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示例

```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();
}
```

### 前端状态管理示例

```javascript
// 认领申请状态管理
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);
      }
    }
  }
};
```