重构认证系统和订单支付功能，新增邮箱验证、密码重置及支付流程
This commit is contained in:
478
docs/动物认领系统API文档.md
Normal file
478
docs/动物认领系统API文档.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# 动物认领系统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);
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
Reference in New Issue
Block a user