北牧文档集

Appearance

爪印守护（PawGuard）- API接口 ​

文档说明 ​

本文档用于API调试工具（如Postman、Apifox、Insomnia等）进行接口调试和前端对接使用。

基础信息：

  • 基础URL：http://localhost:3000（开发环境）
  • API前缀：/api/v1
  • 完整URL示例：http://localhost:3000/api/v1/auth/login
  • API文档地址：http://localhost:3000/api-docs（Swagger UI）

认证方式：

  • 大部分接口需要JWT Token认证
  • Token获取方式：通过登录接口获取
  • Token使用方式：在请求头中添加 Authorization: Bearer {token}

响应格式： 所有接口统一返回格式：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

状态码说明：

  • 200：成功
  • 201：创建成功
  • 400：参数错误
  • 401：未登录或Token失效
  • 403：权限不足
  • 404：资源不存在
  • 500：服务器错误

目录 ​

  1. 认证模块
  2. 用户模块
  3. 救助信息模块
  4. 领养申请模块
  5. 志愿者模块
  6. 捐赠模块
  7. 物资管理模块
  8. 消息模块
  9. 系统设置模块
  10. 救助故事模块
  11. 评论模块
  12. 收藏模块
  13. 搜索模块
  14. 管理员模块
  15. 批量操作模块
  16. 健康检查模块
  17. 操作日志模块

1. 认证模块 ​

1.1 用户注册 ​

接口地址： POST /api/v1/auth/register

是否需要认证： 否

请求参数：

参数名类型必填说明示例
accountstring是账号（手机号/用户名/邮箱）"13800138000"
passwordstring是密码（至少8位，需包含小写字母和数字）"password123"
emailstring否邮箱"user@example.com"
nicknamestring否昵称"爱心人士"

请求示例：

json
{
  "account": "13800138000",
  "password": "password123",
  "email": "user@example.com",
  "nickname": "爱心人士"
}

响应示例：

json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "userId": 1,
    "account": "13800138000",
    "nickname": "爱心人士"
  }
}

错误响应：

  • 密码长度不足8位：{"code": 400, "message": "密码长度至少8位"}
  • 密码过于简单：{"code": 400, "message": "密码过于简单，请使用更复杂的密码"}
  • 账号已存在：{"code": 400, "message": "账号已存在"}

1.2 用户登录 ​

接口地址： POST /api/v1/auth/login

是否需要认证： 否

请求参数：

参数名类型必填说明示例
accountstring是账号（手机号/用户名/邮箱）"13800138000"
passwordstring是密码"password123"

请求示例：

json
{
  "account": "13800138000",
  "password": "password123"
}

响应示例：

json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "account": "13800138000",
      "nickname": "爱心人士",
      "role": "user"
    }
  }
}

错误响应：

  • 账号或密码错误：{"code": 401, "message": "账号或密码错误"}

重要提示：

  • 登录成功后，请保存返回的 token 值
  • 后续需要认证的接口，请在请求头中添加：Authorization: Bearer {token}

2. 用户模块 ​

2.1 获取个人资料 ​

接口地址： GET /api/v1/user/profile

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数： 无

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "account": "13800138000",
    "nickname": "爱心人士",
    "phone": "13800138000",
    "email": "user@example.com",
    "avatar": "/uploads/avatar.jpg",
    "address": "北京市朝阳区",
    "role": "user",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

2.2 编辑个人资料 ​

接口地址： PUT /api/v1/user/profile

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
nicknamestring否昵称（1-50字符）"新昵称"
phonestring否手机号"13800138000"
emailstring否邮箱"newemail@example.com"
avatarstring否头像URL"/uploads/avatar.jpg"
addressstring否地址（最多255字符）"北京市朝阳区"

请求示例：

json
{
  "nickname": "新昵称",
  "phone": "13800138000",
  "email": "newemail@example.com",
  "address": "北京市朝阳区"
}

响应示例：

json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "nickname": "新昵称",
    "phone": "13800138000",
    "email": "newemail@example.com",
    "address": "北京市朝阳区"
  }
}

3. 救助信息模块 ​

3.1 分页查询救助信息（公开） ​

接口地址： GET /api/v1/rescue/list

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
animalTypeinteger否动物类型（1-猫，2-狗）1
emergencyLevelinteger否紧急程度（1-紧急，2-一般，3-非紧急）1

请求示例：

GET /api/v1/rescue/list?page=1&size=10&animalType=1&emergencyLevel=1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "animalType": 1,
        "animalName": "小白",
        "age": "2个月",
        "healthStatus": 1,
        "emergencyLevel": 1,
        "rescueAddress": "北京市朝阳区xxx",
        "description": "发现一只受伤的小猫",
        "images": ["/uploads/rescue1.jpg"],
        "auditStatus": 1,
        "isTop": false,
        "viewCount": 100,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10,
    "totalPages": 5
  }
}

3.2 获取救助信息详情 ​

接口地址： GET /api/v1/rescue/detail/:id

是否需要认证： 否

路径参数：

参数名类型必填说明
idinteger是救助信息ID

请求示例：

GET /api/v1/rescue/detail/1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "animalType": 1,
    "animalName": "小白",
    "age": "2个月",
    "healthStatus": 1,
    "emergencyLevel": 1,
    "rescueAddress": "北京市朝阳区xxx",
    "description": "发现一只受伤的小猫",
    "images": ["/uploads/rescue1.jpg"],
    "auditStatus": 1,
    "isTop": false,
    "viewCount": 101,
    "publisher": {
      "id": 1,
      "nickname": "爱心人士"
    },
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

3.3 获取热门救助信息 ​

接口地址： GET /api/v1/rescue/hot

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
limitinteger否返回数量（默认10，最多50）10

请求示例：

GET /api/v1/rescue/hot?limit=10

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "animalType": 1,
      "animalName": "小白",
      "emergencyLevel": 1,
      "viewCount": 1000,
      "images": ["/uploads/rescue1.jpg"]
    }
  ]
}

3.4 发布救助信息 ​

接口地址： POST /api/v1/rescue/publish

是否需要认证： 是

请求头：

Authorization: Bearer {token}
Content-Type: multipart/form-data

请求参数（Form Data）：

参数名类型必填说明示例
animalTypeinteger是动物类型（1-猫，2-狗）1
animalNamestring否动物名称（最多50字符）"小白"
agestring否动物年龄（最多20字符）"2个月"
healthStatusinteger是健康状况（1-健康，2-轻微伤病，3-严重伤病）2
emergencyLevelinteger否紧急程度（1-紧急，2-一般，3-非紧急，默认2）1
rescueAddressstring是救助地点（最多255字符）"北京市朝阳区xxx"
descriptionstring否救助详情（最多5000字符）"发现一只受伤的小猫"
imagesfile[]否动物照片（可多张，最多10张）-

请求示例（Postman）：

  • 选择 POST 方法
  • URL: http://localhost:3000/api/v1/rescue/publish
  • Headers: Authorization: Bearer {token}
  • Body: 选择 form-data
  • 添加字段：
    • animalType: 1
    • animalName: 小白
    • healthStatus: 2
    • rescueAddress: 北京市朝阳区xxx
    • description: 发现一只受伤的小猫
    • images: 选择文件（可多选，最多10张）

响应示例：

json
{
  "code": 201,
  "message": "发布成功",
  "data": {
    "id": 1,
    "animalType": 1,
    "animalName": "小白",
    "auditStatus": 0,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

3.5 管理员查询救助信息列表 ​

接口地址： GET /api/v1/rescue/admin/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
animalTypeinteger否动物类型（1-猫，2-狗）1
emergencyLevelinteger否紧急程度（1-紧急，2-一般，3-非紧急）1
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0
keywordstring否搜索关键词"小白"

请求示例：

GET /api/v1/rescue/admin/list?page=1&size=10&auditStatus=0

3.6 审核救助信息（管理员） ​

接口地址： PUT /api/v1/rescue/admin/audit

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idinteger是救助信息ID1
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring否驳回理由（驳回时必填）"信息不完整"

请求示例：

json
{
  "id": 1,
  "auditStatus": 1
}

或驳回：

json
{
  "id": 1,
  "auditStatus": 2,
  "rejectReason": "信息不完整"
}

响应示例：

json
{
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "auditStatus": 1
  }
}

3.7 置顶/取消置顶（管理员） ​

接口地址： PUT /api/v1/rescue/admin/top/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是救助信息ID

请求示例：

PUT /api/v1/rescue/admin/top/1

响应示例：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "isTop": true
  }
}

3.8 删除救助信息（管理员） ​

接口地址： DELETE /api/v1/rescue/admin/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是救助信息ID

请求示例：

DELETE /api/v1/rescue/admin/1

响应示例：

json
{
  "code": 200,
  "message": "删除成功",
  "data": {}
}

4. 领养申请模块 ​

4.1 提交领养申请 ​

接口地址： POST /api/v1/adoption/apply

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
rescueIdinteger是救助信息ID1
livingEnvstring是居住环境描述"有独立住房，有院子"
economicStatusstring是经济情况（最多100字符）"月收入5000元"
feedingExperiencestring否饲养经验（最多2000字符）"有3年养猫经验"
contactWaystring是紧急联系方式（最多50字符）"13800138000"

请求示例：

json
{
  "rescueId": 1,
  "livingEnv": "有独立住房，有院子",
  "economicStatus": "月收入5000元",
  "feedingExperience": "有3年养猫经验",
  "contactWay": "13800138000"
}

响应示例：

json
{
  "code": 201,
  "message": "申请提交成功",
  "data": {
    "id": 1,
    "rescueId": 1,
    "auditStatus": 0,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

错误响应：

  • 已申请过：{"code": 400, "message": "您已申请过该救助信息的领养"}
  • 救助信息不存在：{"code": 404, "message": "救助信息不存在"}

4.2 查看我的领养申请 ​

接口地址： GET /api/v1/adoption/my-list

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0

请求示例：

GET /api/v1/adoption/my-list?page=1&size=10&auditStatus=0

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "rescueId": 1,
        "rescueInfo": {
          "id": 1,
          "animalName": "小白",
          "animalType": 1
        },
        "auditStatus": 0,
        "auditRemark": null,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "size": 10,
    "totalPages": 1
  }
}

4.3 管理员查询领养申请列表 ​

接口地址： GET /api/v1/adoption/admin/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0
rescueIdinteger否救助信息ID1
keywordstring否搜索关键词（申请人昵称、用户名）"爱心"

请求示例：

GET /api/v1/adoption/admin/list?page=1&size=10&auditStatus=0

4.4 审核领养申请（管理员） ​

接口地址： PUT /api/v1/adoption/admin/audit

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idinteger是领养申请ID1
auditStatusinteger是审核状态（1-通过，2-驳回）1
auditRemarkstring否审核备注（最多500字符）"审核通过"

请求示例：

json
{
  "id": 1,
  "auditStatus": 1,
  "auditRemark": "审核通过"
}

响应示例：

json
{
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "auditStatus": 1
  }
}

4.5 更新跟踪记录（管理员） ​

接口地址： PUT /api/v1/adoption/admin/follow-up/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是领养申请ID

请求头：

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

请求参数：

参数名类型必填说明示例
followUpstring否跟踪记录（最多5000字符）"已成功领养，状态良好"

请求示例：

json
{
  "followUp": "已成功领养，状态良好"
}

响应示例：

json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "followUp": "已成功领养，状态良好"
  }
}

5. 志愿者模块 ​

5.1 查询志愿者活动列表（公开） ​

接口地址： GET /api/v1/volunteer/activity/list

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
statusinteger否活动状态（1-招募中，2-进行中，3-已结束）1

请求示例：

GET /api/v1/volunteer/activity/list?page=1&size=10&status=1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "周末救助活动",
        "description": "帮助流浪猫狗",
        "startTime": "2024-01-15T09:00:00.000Z",
        "endTime": "2024-01-15T17:00:00.000Z",
        "location": "北京市朝阳区",
        "needNumber": 10,
        "currentNumber": 5,
        "status": 1,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 20,
    "page": 1,
    "size": 10,
    "totalPages": 2
  }
}

5.2 获取活动详情（公开） ​

接口地址： GET /api/v1/volunteer/activity/detail/:id

是否需要认证： 否

路径参数：

参数名类型必填说明
idinteger是活动ID

请求示例：

GET /api/v1/volunteer/activity/detail/1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "title": "周末救助活动",
    "description": "帮助流浪猫狗",
    "startTime": "2024-01-15T09:00:00.000Z",
    "endTime": "2024-01-15T17:00:00.000Z",
    "location": "北京市朝阳区",
    "needNumber": 10,
    "currentNumber": 5,
    "status": 1,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

5.3 志愿者报名 ​

接口地址： POST /api/v1/volunteer/apply

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
activityIdinteger是活动ID1
serviceTimestring是可服务时间（最多100字符）"周末全天"
skillsstring否技能特长（最多200字符）"开车、摄影"

请求示例：

json
{
  "activityId": 1,
  "serviceTime": "周末全天",
  "skills": "开车、摄影"
}

响应示例：

json
{
  "code": 201,
  "message": "报名成功",
  "data": {
    "id": 1,
    "activityId": 1,
    "auditStatus": 0,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

错误响应：

  • 已报名过：{"code": 400, "message": "您已报名过该活动"}
  • 活动不在招募中：{"code": 400, "message": "活动不在招募中"}

5.4 查看我的报名记录 ​

接口地址： GET /api/v1/volunteer/my-apply

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0

请求示例：

GET /api/v1/volunteer/my-apply?page=1&size=10

5.5 创建志愿者活动（管理员） ​

接口地址： POST /api/v1/volunteer/admin/activity

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
titlestring是活动标题（最多100字符）"周末救助活动"
descriptionstring是活动详情"帮助流浪猫狗"
startTimestring是活动开始时间（ISO8601格式）"2024-01-15T09:00:00.000Z"
endTimestring是活动结束时间（ISO8601格式）"2024-01-15T17:00:00.000Z"
locationstring是活动地点（最多255字符）"北京市朝阳区"
needNumberinteger是所需志愿者人数（非负整数）10

请求示例：

json
{
  "title": "周末救助活动",
  "description": "帮助流浪猫狗",
  "startTime": "2024-01-15T09:00:00.000Z",
  "endTime": "2024-01-15T17:00:00.000Z",
  "location": "北京市朝阳区",
  "needNumber": 10
}

响应示例：

json
{
  "code": 201,
  "message": "活动创建成功",
  "data": {
    "id": 1,
    "title": "周末救助活动",
    "status": 1
  }
}

5.6 编辑活动（管理员） ​

接口地址： PUT /api/v1/volunteer/admin/activity/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是活动ID

请求头：

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

请求参数：

参数名类型必填说明示例
titlestring否活动标题"周末救助活动"
descriptionstring否活动详情"帮助流浪猫狗"
startTimestring否活动开始时间"2024-01-15T09:00:00.000Z"
endTimestring否活动结束时间"2024-01-15T17:00:00.000Z"
locationstring否活动地点"北京市朝阳区"
needNumberinteger否所需志愿者人数10
statusinteger否活动状态（1-招募中，2-进行中，3-已结束）1

请求示例：

json
{
  "title": "周末救助活动（更新）",
  "status": 2
}

5.7 管理员查询报名记录 ​

接口地址： GET /api/v1/volunteer/admin/apply-list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0
activityIdinteger否活动ID1
keywordstring否搜索关键词（申请人昵称、用户名）"爱心"

5.8 审核志愿者报名（管理员） ​

接口地址： PUT /api/v1/volunteer/admin/audit

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idinteger是报名ID1
auditStatusinteger是审核状态（1-通过，2-驳回）1

请求示例：

json
{
  "id": 1,
  "auditStatus": 1
}

5.9 分配任务（管理员） ​

接口地址： PUT /api/v1/volunteer/admin/assign-task/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是报名ID

请求头：

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

请求参数：

参数名类型必填说明示例
taskAssignedstring否分配的任务（最多500字符）"负责拍照记录"

请求示例：

json
{
  "taskAssigned": "负责拍照记录"
}

5.10 更新服务记录（管理员） ​

接口地址： PUT /api/v1/volunteer/admin/service-record/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是报名ID

请求头：

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

请求参数：

参数名类型必填说明示例
serviceRecordstring否服务记录（最多5000字符）"服务表现优秀"

请求示例：

json
{
  "serviceRecord": "服务表现优秀"
}

6. 捐赠模块 ​

6.1 提交捐赠 ​

接口地址： POST /api/v1/donation/submit

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
donationTypeinteger是捐赠类型（1-资金，2-物资）1
amountnumber条件必填捐赠金额（资金捐赠时必填，单位：元）100.00
materialNamestring条件必填物资名称（物资捐赠时必填，最多100字符）"猫粮"
materialQuantityinteger条件必填物资数量（物资捐赠时必填）10
materialUnitstring否物资单位（最多20字符）"袋"
proofImagestring否捐赠凭证图片URL（多个URL用逗号分隔，最多1000字符）"/uploads/proof1.jpg,/uploads/proof2.jpg"
remarkstring否备注（最多500字符）"希望帮助更多小动物"

请求示例（资金捐赠）：

json
{
  "donationType": 1,
  "amount": 100.00,
  "proofImage": "/uploads/proof1.jpg",
  "remark": "希望帮助更多小动物"
}

请求示例（物资捐赠）：

json
{
  "donationType": 2,
  "materialName": "猫粮",
  "materialQuantity": 10,
  "materialUnit": "袋",
  "remark": "希望帮助更多小动物"
}

响应示例：

json
{
  "code": 201,
  "message": "捐赠提交成功",
  "data": {
    "id": 1,
    "donationType": 1,
    "auditStatus": 0,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

6.2 查看捐赠公示（公开） ​

接口地址： GET /api/v1/donation/public-list

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
donationTypeinteger否捐赠类型（1-资金，2-物资）1

请求示例：

GET /api/v1/donation/public-list?page=1&size=10&donationType=1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "donationType": 1,
        "amount": 100.00,
        "donor": {
          "nickname": "爱心人士"
        },
        "auditStatus": 1,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10,
    "totalPages": 5
  }
}

6.3 查看我的捐赠 ​

接口地址： GET /api/v1/donation/my-donation

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
donationTypeinteger否捐赠类型（1-资金，2-物资）1
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0

请求示例：

GET /api/v1/donation/my-donation?page=1&size=10

6.4 管理员查询捐赠列表 ​

接口地址： GET /api/v1/donation/admin/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
donationTypeinteger否捐赠类型（1-资金，2-物资）1
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）0
keywordstring否搜索关键词（捐赠人昵称、用户名）"爱心"

6.5 审核捐赠（管理员） ​

接口地址： PUT /api/v1/donation/admin/audit

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idinteger是捐赠ID1
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring条件必填驳回理由（驳回时必填，最多500字符）"凭证不清晰"

请求示例：

json
{
  "id": 1,
  "auditStatus": 1
}

或驳回：

json
{
  "id": 1,
  "auditStatus": 2,
  "rejectReason": "凭证不清晰"
}

6.6 更新使用明细（管理员） ​

接口地址： PUT /api/v1/donation/admin/use-detail/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是捐赠ID

请求头：

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

请求参数：

参数名类型必填说明示例
useDetailstring否使用明细（最多5000字符）"用于购买猫粮和医疗用品"

请求示例：

json
{
  "useDetail": "用于购买猫粮和医疗用品"
}

6.7 导出捐赠记录（Excel） ​

接口地址： GET /api/v1/donation/admin/export

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
donationTypeinteger否捐赠类型（1-资金，2-物资）1
auditStatusinteger否审核状态（0-待审核，1-通过，2-驳回）1
startDatestring否开始日期（YYYY-MM-DD）"2024-01-01"
endDatestring否结束日期（YYYY-MM-DD）"2024-12-31"

请求示例：

GET /api/v1/donation/admin/export?donationType=1&startDate=2024-01-01&endDate=2024-12-31

响应：

  • 返回Excel文件（Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）

7. 物资管理模块 ​

7.1 新增物资（管理员） ​

接口地址： POST /api/v1/material/create

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
materialNamestring是物资名称（最多100字符）"猫粮"
materialTypeinteger是物资类型（1-食品，2-用品，3-药品，4-其他）1
unitstring否单位（最多20字符）"袋"
minStockinteger否最低库存（预警值，非负整数）10
remarkstring否备注（最多500字符）"优质猫粮"

请求示例：

json
{
  "materialName": "猫粮",
  "materialType": 1,
  "unit": "袋",
  "minStock": 10,
  "remark": "优质猫粮"
}

响应示例：

json
{
  "code": 201,
  "message": "物资创建成功",
  "data": {
    "id": 1,
    "materialName": "猫粮",
    "materialType": 1,
    "stock": 0,
    "minStock": 10
  }
}

错误响应：

  • 物资名称已存在：{"code": 400, "message": "物资名称已存在"}

7.2 查询物资列表（管理员） ​

接口地址： GET /api/v1/material/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
materialTypeinteger否物资类型（1-食品，2-用品，3-药品，4-其他）1
keywordstring否搜索关键词（物资名称）"猫粮"

请求示例：

GET /api/v1/material/list?page=1&size=10&materialType=1

7.3 编辑物资（管理员） ​

接口地址： PUT /api/v1/material/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是物资ID

请求头：

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

请求参数：

参数名类型必填说明示例
materialNamestring否物资名称"猫粮（更新）"
materialTypeinteger否物资类型1
unitstring否单位"袋"
minStockinteger否最低库存10
remarkstring否备注"优质猫粮"

请求示例：

json
{
  "materialName": "猫粮（更新）",
  "minStock": 20
}

7.4 删除物资（管理员） ​

接口地址： DELETE /api/v1/material/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是物资ID

请求头：

Authorization: Bearer {token}

请求示例：

DELETE /api/v1/material/1

错误响应：

  • 物资仍有库存：{"code": 400, "message": "物资仍有库存，无法删除"}

7.5 物资入库（管理员） ​

接口地址： POST /api/v1/material/inbound

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
materialIdinteger是物资ID1
quantityinteger是入库数量（正整数）100
remarkstring否备注（最多500字符）"采购入库"

请求示例：

json
{
  "materialId": 1,
  "quantity": 100,
  "remark": "采购入库"
}

响应示例：

json
{
  "code": 200,
  "message": "入库成功",
  "data": {
    "id": 1,
    "materialName": "猫粮",
    "stock": 100,
    "beforeStock": 0
  }
}

7.6 物资出库（管理员） ​

接口地址： POST /api/v1/material/outbound

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
materialIdinteger是物资ID1
quantityinteger是出库数量（正整数）10
remarkstring否备注（最多500字符）"用于救助"

请求示例：

json
{
  "materialId": 1,
  "quantity": 10,
  "remark": "用于救助"
}

错误响应：

  • 库存不足：{"code": 400, "message": "库存不足"}

7.7 库存查询（管理员） ​

接口地址： GET /api/v1/material/stock

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
materialTypeinteger否物资类型（1-食品，2-用品，3-药品，4-其他）1
lowStockboolean否是否只显示库存预警的物资true

请求示例：

GET /api/v1/material/stock?page=1&size=10&lowStock=true

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "materialName": "猫粮",
        "materialType": 1,
        "stock": 5,
        "minStock": 10,
        "unit": "袋",
        "isLowStock": true
      }
    ],
    "total": 1,
    "page": 1,
    "size": 10,
    "totalPages": 1
  }
}

7.8 导出物资记录（Excel） ​

接口地址： GET /api/v1/material/admin/export

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
materialTypeinteger否物资类型（1-食品，2-用品，3-药品，4-其他）1
lowStockboolean否是否只导出库存预警的物资true

请求示例：

GET /api/v1/material/admin/export?materialType=1&lowStock=true

响应：

  • 返回Excel文件

8. 消息模块 ​

8.1 获取消息列表 ​

接口地址： GET /api/v1/message/list

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10

请求示例：

GET /api/v1/message/list?page=1&size=10

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "您的领养申请已通过",
        "content": "恭喜您，您的领养申请已通过审核",
        "type": "adoption",
        "isRead": false,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "size": 10,
    "totalPages": 1
  }
}

8.2 获取未读消息数量 ​

接口地址： GET /api/v1/message/unread-count

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数： 无

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "unreadCount": 3
  }
}

8.3 标记消息为已读 ​

接口地址： PUT /api/v1/message/read/:id

是否需要认证： 是

路径参数：

参数名类型必填说明
idinteger是消息ID

请求头：

Authorization: Bearer {token}

请求示例：

PUT /api/v1/message/read/1

响应示例：

json
{
  "code": 200,
  "message": "标记成功",
  "data": {
    "id": 1,
    "isRead": true
  }
}

8.4 批量标记消息为已读 ​

接口地址： PUT /api/v1/message/batch-read

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是要标记为已读的消息ID列表[1, 2, 3]

请求示例：

json
{
  "ids": [1, 2, 3]
}

响应示例：

json
{
  "code": 200,
  "message": "标记成功",
  "data": {
    "count": 3
  }
}

9. 系统设置模块 ​

9.1 获取系统设置（公开） ​

接口地址： GET /api/v1/system/settings

是否需要认证： 否

请求参数： 无

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "site_name": "爪印守护",
    "site_logo": "/uploads/system/logo-xxx.jpg",
    "site_icon": "/uploads/system/icon-xxx.ico",
    "site_keywords": "流浪猫,流浪狗,动物救助,领养",
    "site_description": "爪印守护 - 专业的流浪猫狗救助平台",
    "site_copyright": "© 2024 爪印守护",
    "site_contact": {
      "phone": "400-123-4567",
      "email": "contact@pawguard.com",
      "address": "北京市朝阳区"
    }
  }
}

9.2 获取所有系统设置（管理员） ​

接口地址： GET /api/v1/system/settings/all

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "setting_key": "site_name",
      "setting_value": "爪印守护",
      "description": "网站名称"
    },
    {
      "setting_key": "site_logo",
      "setting_value": "/uploads/system/logo-xxx.jpg",
      "description": "网站Logo"
    }
  ]
}

9.3 更新单个设置项（管理员） ​

接口地址： PUT /api/v1/system/settings/:key

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
keystring是设置键名

请求头：

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

请求参数：

参数名类型必填说明示例
setting_valuestring是设置值（site_contact为JSON对象）"新网站名称"
descriptionstring否设置说明"网站名称"

请求示例：

json
{
  "setting_value": "新网站名称",
  "description": "网站名称"
}

特殊说明：

  • site_contact 需要传入JSON字符串，例如：{"phone":"400-123-4567","email":"contact@pawguard.com","address":"北京市朝阳区"}

9.4 批量更新设置（管理员） ​

接口地址： PUT /api/v1/system/settings/batch

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
settingsarray是设置项数组-

settings数组元素：

参数名类型必填说明示例
setting_keystring是设置键名"site_name"
setting_valuestring是设置值"新网站名称"
descriptionstring否设置说明"网站名称"

请求示例：

json
{
  "settings": [
    {
      "setting_key": "site_name",
      "setting_value": "新网站名称",
      "description": "网站名称"
    },
    {
      "setting_key": "site_keywords",
      "setting_value": "流浪猫,流浪狗,动物救助",
      "description": "网站关键词"
    }
  ]
}

9.5 上传Logo/图标（管理员） ​

接口地址： POST /api/v1/system/upload-logo

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}
Content-Type: multipart/form-data

请求参数（Form Data）：

参数名类型必填说明示例
filefile是图片文件（jpeg、jpg、png、gif、webp、ico、svg，最大2MB）-
typestring是类型（logo或icon）"logo"

请求示例（Postman）：

  • 选择 POST 方法
  • URL: http://localhost:3000/api/v1/system/upload-logo
  • Headers: Authorization: Bearer {token}
  • Body: 选择 form-data
  • 添加字段：
    • file: 选择文件
    • type: logo 或 icon

响应示例：

json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "/uploads/system/logo-xxx.jpg",
    "type": "logo"
  }
}

10. 救助故事模块 ​

10.1 分页查询救助故事（公开） ​

接口地址： GET /api/v1/story/list

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
statusinteger否状态（0-待审核，1-已发布，2-已删除，默认1）1

请求示例：

GET /api/v1/story/list?page=1&size=10

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "小白的新家",
        "content": "小白成功被领养，找到了温暖的家...",
        "images": ["/uploads/story/story1.jpg"],
        "likeCount": 100,
        "commentCount": 20,
        "viewCount": 500,
        "author": {
          "id": 1,
          "nickname": "爱心人士"
        },
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 10,
    "totalPages": 5
  }
}

10.2 获取故事详情 ​

接口地址： GET /api/v1/story/detail/:id

是否需要认证： 否

路径参数：

参数名类型必填说明
idinteger是故事ID

请求示例：

GET /api/v1/story/detail/1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": 1,
    "title": "小白的新家",
    "content": "小白成功被领养，找到了温暖的家...",
    "images": ["/uploads/story/story1.jpg"],
    "rescueId": 1,
    "rescueInfo": {
      "id": 1,
      "animalName": "小白"
    },
    "likeCount": 100,
    "commentCount": 20,
    "viewCount": 501,
    "author": {
      "id": 1,
      "nickname": "爱心人士"
    },
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

10.3 获取热门救助故事（公开） ​

接口地址： GET /api/v1/story/hot

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
limitinteger否返回数量（默认10，最多50）10

请求示例：

GET /api/v1/story/hot?limit=10

10.4 发布救助故事 ​

接口地址： POST /api/v1/story/publish

是否需要认证： 是

请求头：

Authorization: Bearer {token}
Content-Type: multipart/form-data

请求参数（Form Data）：

参数名类型必填说明示例
titlestring是故事标题（最多100字符）"小白的新家"
contentstring是故事内容"小白成功被领养..."
rescueIdinteger否关联救助信息ID1
imagesfile[]否图片文件（最多10张，每张最大5MB）-

请求示例（Postman）：

  • 选择 POST 方法
  • URL: http://localhost:3000/api/v1/story/publish
  • Headers: Authorization: Bearer {token}
  • Body: 选择 form-data
  • 添加字段：
    • title: 小白的新家
    • content: 小白成功被领养，找到了温暖的家...
    • rescueId: 1（可选）
    • images: 选择文件（可多选，最多10张）

响应示例：

json
{
  "code": 201,
  "message": "发布成功",
  "data": {
    "id": 1,
    "title": "小白的新家",
    "status": 0,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

10.5 点赞故事 ​

接口地址： PUT /api/v1/story/like/:id

是否需要认证： 是

路径参数：

参数名类型必填说明
idinteger是故事ID

请求头：

Authorization: Bearer {token}

请求示例：

PUT /api/v1/story/like/1

响应示例：

json
{
  "code": 200,
  "message": "点赞成功",
  "data": {
    "id": 1,
    "likeCount": 101,
    "isLiked": true
  }
}

10.6 管理员查询故事列表 ​

接口地址： GET /api/v1/story/admin/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
statusinteger否状态（0-待审核，1-已发布，2-已删除）0
keywordstring否搜索关键词（标题、内容）"小白"

10.7 审核故事（管理员） ​

接口地址： PUT /api/v1/story/admin/audit/:id

是否需要认证： 是（管理员）

路径参数：

参数名类型必填说明
idinteger是故事ID

请求头：

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

请求参数：

参数名类型必填说明示例
statusinteger是状态（1-通过，2-删除）1

请求示例：

json
{
  "status": 1
}

响应示例：

json
{
  "code": 200,
  "message": "审核成功",
  "data": {
    "id": 1,
    "status": 1
  }
}

11. 评论模块 ​

11.1 获取评论列表（公开） ​

接口地址： GET /api/v1/comment/list

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
targetTypeinteger是目标类型（1-救助信息，2-救助故事，3-志愿者活动）1
targetIdinteger是目标ID1
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认20，最大100）20

请求示例：

GET /api/v1/comment/list?targetType=1&targetId=1&page=1&size=20

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "content": "希望小猫能找到好人家",
        "likeCount": 10,
        "author": {
          "id": 1,
          "nickname": "爱心人士"
        },
        "parentId": null,
        "replies": [],
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "size": 20,
    "totalPages": 3
  }
}

11.2 添加评论 ​

接口地址： POST /api/v1/comment/add

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
targetTypeinteger是目标类型（1-救助信息，2-救助故事，3-志愿者活动）1
targetIdinteger是目标ID1
contentstring是评论内容（最多2000字符）"希望小猫能找到好人家"
parentIdinteger否父评论ID（回复评论时使用）1

请求示例：

json
{
  "targetType": 1,
  "targetId": 1,
  "content": "希望小猫能找到好人家"
}

回复评论示例：

json
{
  "targetType": 1,
  "targetId": 1,
  "content": "我也这么希望",
  "parentId": 1
}

响应示例：

json
{
  "code": 201,
  "message": "评论成功",
  "data": {
    "id": 1,
    "content": "希望小猫能找到好人家",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

11.3 点赞评论 ​

接口地址： PUT /api/v1/comment/like/:id

是否需要认证： 是

路径参数：

参数名类型必填说明
idinteger是评论ID

请求头：

Authorization: Bearer {token}

请求示例：

PUT /api/v1/comment/like/1

响应示例：

json
{
  "code": 200,
  "message": "点赞成功",
  "data": {
    "id": 1,
    "likeCount": 11,
    "isLiked": true
  }
}

11.4 删除评论 ​

接口地址： DELETE /api/v1/comment/:id

是否需要认证： 是（本人或管理员）

路径参数：

参数名类型必填说明
idinteger是评论ID

请求头：

Authorization: Bearer {token}

请求示例：

DELETE /api/v1/comment/1

响应示例：

json
{
  "code": 200,
  "message": "删除成功",
  "data": {}
}

错误响应：

  • 无权限：{"code": 403, "message": "无权限删除该评论"}

11.5 管理员查询所有评论 ​

接口地址： GET /api/v1/comment/admin/list

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认20，最大100）20
targetTypeinteger否目标类型（1-救助信息，2-救助故事，3-志愿者活动）1
targetIdinteger否目标ID1
statusinteger否状态（1-正常，0-已删除）1
keywordstring否搜索关键词（评论内容）"希望"

12. 收藏模块 ​

12.1 获取我的收藏列表 ​

接口地址： GET /api/v1/favorite/list

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认20，最大100）20
targetTypeinteger否目标类型（1-救助信息，2-救助故事）1

请求示例：

GET /api/v1/favorite/list?page=1&size=20&targetType=1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "targetType": 1,
        "targetId": 1,
        "target": {
          "id": 1,
          "animalName": "小白",
          "animalType": 1
        },
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 10,
    "page": 1,
    "size": 20,
    "totalPages": 1
  }
}

12.2 添加收藏 ​

接口地址： POST /api/v1/favorite/add

是否需要认证： 是

请求头：

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

请求参数：

参数名类型必填说明示例
targetTypeinteger是目标类型（1-救助信息，2-救助故事）1
targetIdinteger是目标ID1

请求示例：

json
{
  "targetType": 1,
  "targetId": 1
}

响应示例：

json
{
  "code": 201,
  "message": "收藏成功",
  "data": {
    "id": 1,
    "targetType": 1,
    "targetId": 1
  }
}

错误响应：

  • 已收藏：{"code": 400, "message": "已收藏"}

12.3 取消收藏 ​

接口地址： DELETE /api/v1/favorite/:id

是否需要认证： 是

路径参数：

参数名类型必填说明
idinteger是收藏ID

请求头：

Authorization: Bearer {token}

请求示例：

DELETE /api/v1/favorite/1

响应示例：

json
{
  "code": 200,
  "message": "取消收藏成功",
  "data": {}
}

12.4 检查是否已收藏 ​

接口地址： GET /api/v1/favorite/check

是否需要认证： 是

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
targetTypeinteger是目标类型（1-救助信息，2-救助故事）1
targetIdinteger是目标ID1

请求示例：

GET /api/v1/favorite/check?targetType=1&targetId=1

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "isFavorited": true,
    "favoriteId": 1
  }
}

13. 搜索模块 ​

13.1 全局搜索 ​

接口地址： GET /api/v1/search

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
keywordstring是搜索关键词（1-100字符）"小白"
typestring否搜索类型（all-全部，rescue-救助信息，story-救助故事，activity-志愿者活动，默认all）"all"
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认20，最大100）20

请求示例：

GET /api/v1/search?keyword=小白&type=all&page=1&size=20

响应示例：

json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "keyword": "小白",
    "type": "all",
    "list": [
      {
        "type": "rescue",
        "id": 1,
        "animalName": "小白",
        "matchedFields": ["animalName", "description"]
      },
      {
        "type": "story",
        "id": 1,
        "title": "小白的新家",
        "matchedFields": ["title", "content"]
      }
    ],
    "total": 50,
    "page": 1,
    "size": 20,
    "totalPages": 3,
    "counts": {
      "rescue": 30,
      "story": 15,
      "activity": 5
    }
  }
}

13.2 获取搜索建议 ​

接口地址： GET /api/v1/search/suggestions

是否需要认证： 否

请求参数（Query参数）：

参数名类型必填说明示例
keywordstring否搜索关键词（最多100字符）"小白"

请求示例：

GET /api/v1/search/suggestions?keyword=小白

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "suggestions": [
      "小白",
      "小白的新家",
      "救助小白的故事"
    ]
  }
}

14. 管理员模块 ​

14.1 获取后台Dashboard统计数据 ​

接口地址： GET /api/v1/admin/dashboard

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalUsers": 1000,
    "totalRescues": 500,
    "totalAdoptions": 300,
    "totalDonations": 200,
    "totalVolunteers": 100,
    "pendingAudits": {
      "rescue": 10,
      "adoption": 5,
      "volunteer": 3,
      "donation": 8,
      "story": 2
    }
  }
}

14.2 获取捐赠统计数据 ​

接口地址： GET /api/v1/admin/stats/donation

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalAmount": 100000.00,
    "totalCount": 200,
    "monthlyTrend": [
      {
        "month": "2024-01",
        "amount": 10000.00,
        "count": 20
      }
    ]
  }
}

14.3 获取物资库存与出入库统计数据 ​

接口地址： GET /api/v1/admin/stats/material

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "totalMaterials": 50,
    "lowStockCount": 5,
    "totalInbound": 1000,
    "totalOutbound": 800,
    "currentStock": 200
  }
}

14.4 获取救助信息趋势统计 ​

接口地址： GET /api/v1/admin/charts/rescue-trend

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "daily": [
      {
        "date": "2024-01-01",
        "count": 10
      }
    ],
    "monthly": [
      {
        "month": "2024-01",
        "count": 300
      }
    ]
  }
}

14.5 获取捐赠趋势统计 ​

接口地址： GET /api/v1/admin/charts/donation-trend

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

响应示例：

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "daily": [
      {
        "date": "2024-01-01",
        "amount": 1000.00,
        "count": 5
      }
    ],
    "monthly": [
      {
        "month": "2024-01",
        "amount": 30000.00,
        "count": 150
      }
    ]
  }
}

15. 批量操作模块 ​

15.1 批量审核救助信息 ​

接口地址： PUT /api/v1/admin/batch/audit/rescue

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是救助信息ID数组[1, 2, 3]
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring条件必填驳回理由（驳回时必填）"信息不完整"

请求示例：

json
{
  "ids": [1, 2, 3],
  "auditStatus": 1
}

响应示例：

json
{
  "code": 200,
  "message": "批量审核成功",
  "data": {
    "successCount": 3,
    "failedCount": 0
  }
}

15.2 批量审核领养申请 ​

接口地址： PUT /api/v1/admin/batch/audit/adoption

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是领养申请ID数组[1, 2, 3]
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring条件必填驳回理由（驳回时必填）"不符合条件"

15.3 批量审核志愿者申请 ​

接口地址： PUT /api/v1/admin/batch/audit/volunteer

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是报名ID数组[1, 2, 3]
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring条件必填驳回理由（驳回时必填）"不符合条件"

15.4 批量审核捐赠 ​

接口地址： PUT /api/v1/admin/batch/audit/donation

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是捐赠ID数组[1, 2, 3]
auditStatusinteger是审核状态（1-通过，2-驳回）1
rejectReasonstring条件必填驳回理由（驳回时必填）"凭证不清晰"

15.5 批量删除救助信息 ​

接口地址： DELETE /api/v1/admin/batch/delete/rescue

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是救助信息ID数组[1, 2, 3]

请求示例：

json
{
  "ids": [1, 2, 3]
}

响应示例：

json
{
  "code": 200,
  "message": "批量删除成功",
  "data": {
    "successCount": 3,
    "failedCount": 0
  }
}

15.6 批量删除救助故事 ​

接口地址： DELETE /api/v1/admin/batch/delete/story

是否需要认证： 是（管理员）

请求头：

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

请求参数：

参数名类型必填说明示例
idsinteger[]是故事ID数组[1, 2, 3]

16. 健康检查模块 ​

16.1 健康检查 ​

接口地址： GET /api/v1/health

是否需要认证： 否

请求参数： 无

响应示例（健康状态）：

json
{
  "code": 200,
  "message": "Service is healthy",
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-01T00:00:00.000Z",
    "uptime": 3600,
    "environment": "production",
    "services": {
      "database": {
        "status": "healthy",
        "message": "Database connection successful"
      },
      "redis": {
        "status": "healthy",
        "message": "Redis connection successful"
      }
    },
    "system": {
      "nodeVersion": "v18.0.0",
      "memory": {
        "used": "50 MB",
        "total": "100 MB",
        "rss": "150 MB"
      }
    }
  }
}

响应示例（降级状态）：

json
{
  "code": 503,
  "message": "Service is degraded",
  "data": {
    "status": "degraded",
    "services": {
      "database": {
        "status": "unhealthy",
        "message": "Database connection failed"
      }
    }
  }
}

17. 操作日志模块 ​

17.1 分页查询操作日志（管理员） ​

接口地址： GET /api/v1/admin/logs

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数（Query参数）：

参数名类型必填说明示例
pageinteger否页码（默认1）1
sizeinteger否每页数量（默认10，最大100）10
modulestring否模块名称过滤"rescue"
operatorstring否操作人账号/昵称"admin"

请求示例：

GET /api/v1/admin/logs?page=1&size=10&module=rescue

响应示例：

json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "module": "rescue",
        "action": "audit",
        "operator": "admin",
        "operatorId": 1,
        "targetId": 1,
        "description": "审核救助信息",
        "ip": "127.0.0.1",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 100,
    "page": 1,
    "size": 10,
    "totalPages": 10
  }
}

17.2 导出操作日志为Excel（管理员） ​

接口地址： GET /api/v1/admin/logs/export

是否需要认证： 是（管理员）

请求头：

Authorization: Bearer {token}

请求参数： 无

请求示例：

GET /api/v1/admin/logs/export

响应：

  • 返回Excel文件（Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）

附录 ​

A. 常见错误码说明 ​

错误码说明解决方案
200成功-
201创建成功-
400参数错误检查请求参数是否符合要求
401未登录或Token失效重新登录获取Token
403权限不足确认用户是否有相应权限
404资源不存在检查资源ID是否正确
500服务器错误联系管理员

B. 文件上传说明 ​

  1. 图片上传限制：

    • 救助信息图片：最多10张，每张最大5MB
    • 救助故事图片：最多10张，每张最大5MB
    • Logo/图标：最大2MB
    • 支持格式：jpeg、jpg、png、gif、webp（Logo还支持ico、svg）

  2. 上传方式：

    • 使用 multipart/form-data 格式
    • 字段名根据接口要求设置（如 images、file 等）

C. 分页参数说明 ​

所有分页接口统一使用以下参数：

  • page: 页码，从1开始
  • size: 每页数量，默认10，最大100

响应格式：

json
{
  "list": [],
  "total": 100,
  "page": 1,
  "size": 10,
  "totalPages": 10
}

D. 审核状态说明 ​

  • 0: 待审核
  • 1: 通过
  • 2: 驳回

E. 使用Postman调试建议 ​

  1. 设置环境变量：

    • base_url: http://localhost:3000
    • token: 登录后获取的Token

  2. 设置全局Header：

    • Authorization: Bearer
    • Content-Type: application/json（JSON请求时）

  3. 文件上传：

    • 选择 Body -> form-data
    • 文件字段选择 File 类型

  4. 测试流程：

    • 先调用登录接口获取Token
    • 将Token保存到环境变量
    • 使用Token调用其他需要认证的接口