pet-api/docs/goods-api.md

物品信息接口文档

概述

物品信息管理接口用于处理与物品相关的二维码信息，包括创建、更新、查询等操作。

基础路径: /api/goods

二维码类型: goods

---

接口列表

1. 创建物品信息

创建新的物品信息并激活二维码。

接口地址: POST /api/goods/create

权限要求: 无需认证（公开接口）

请求参数:

参数名	类型	必填	说明	示例
qrCode	string	是	二维码编码	"QR123456789"
photoUrl	string	否	物品照片 URL	"uploads/goods/photo.jpg"
name	string	是	物品名称	"苹果笔记本电脑"
contactName	string	是	联系人姓名	"张三"
contactPhone	string	是	联系电话	"13800138000"
contactEmail	string	否	联系邮箱	"zhangsan@example.com"

请求示例:

{
  "qrCode": "QR123456789",
  "photoUrl": "https://example.com/uploads/goods/laptop.jpg",
  "name": "苹果笔记本电脑",
  "contactName": "张三",
  "contactPhone": "13800138000",
  "contactEmail": "zhangsan@example.com"
}

成功响应 (201):

{
  "message": "物品信息创建成功",
  "data": {
    "id": 1,
    "qrCodeId": 100,
    "photoUrl": "uploads/goods/laptop.jpg",
    "name": "苹果笔记本电脑",
    "contactName": "张三",
    "contactPhone": "13800138000",
    "contactEmail": "zhangsan@example.com",
    "remark": null,
    "createdAt": "2024-01-01T10:00:00.000Z",
    "updatedAt": "2024-01-01T10:00:00.000Z"
  }
}

错误响应 (400):

{
  "message": "二维码不存在"
}

{
  "message": "二维码类型不匹配"
}

{
  "message": "二维码已激活，无法重复填写"
}

---

2. 更新物品信息

通过维护码更新已有的物品信息。

接口地址: PUT /api/goods/update

权限要求: 无需认证（需要维护码验证）

请求参数:

参数名	类型	必填	说明	示例
qrCode	string	是	二维码编码	"QR123456789"
maintenanceCode	string	是	维护码	"MAINT123456"
photoUrl	string	否	物品照片 URL	"uploads/goods/photo.jpg"
name	string	否	物品名称	"苹果笔记本电脑"
contactName	string	否	联系人姓名	"张三"
contactPhone	string	否	联系电话	"13800138000"
contactEmail	string	否	联系邮箱	"zhangsan@example.com"

请求示例:

{
  "qrCode": "QR123456789",
  "maintenanceCode": "MAINT123456",
  "name": "苹果笔记本电脑 MacBook Pro",
  "contactPhone": "13900139000"
}

成功响应 (200):

{
  "message": "物品信息更新成功",
  "data": {
    "id": 1,
    "qrCodeId": 100,
    "photoUrl": "uploads/goods/laptop.jpg",
    "name": "苹果笔记本电脑 MacBook Pro",
    "contactName": "张三",
    "contactPhone": "13900139000",
    "contactEmail": "zhangsan@example.com",
    "remark": null,
    "createdAt": "2024-01-01T10:00:00.000Z",
    "updatedAt": "2024-01-01T11:00:00.000Z"
  }
}

错误响应 (400):

{
  "message": "维护码错误"
}

{
  "message": "二维码不存在"
}

---

3. 获取物品信息

根据二维码获取物品详细信息。

接口地址: GET /api/goods/get

权限要求: 无需认证（公开接口）

请求参数:

参数名	类型	必填	说明	示例
qrCode	string	是	二维码编码	"QR123456789"

请求示例:

GET /api/goods/get?qrCode=QR123456789

成功响应 (200):

{
  "id": 1,
  "qrCodeId": 100,
  "photoUrl": "uploads/goods/laptop.jpg",
  "name": "苹果笔记本电脑",
  "contactName": "张三",
  "contactPhone": "13800138000",
  "contactEmail": "zhangsan@example.com",
  "remark": null,
  "createdAt": "2024-01-01T10:00:00.000Z",
  "updatedAt": "2024-01-01T10:00:00.000Z"
}

错误响应 (400):

{
  "message": "请提供二维码参数"
}

错误响应 (404):

{
  "message": "物品信息不存在"
}

---

4. 查询物品列表（管理员）

分页查询物品信息列表，支持多条件筛选。

接口地址: GET /api/goods/list

权限要求: 需要管理员权限

请求头:

Authorization: Bearer <token>

请求参数:

参数名	类型	必填	说明	示例
name	string	否	物品名称（模糊查询）	"笔记本"
contactName	string	否	联系人姓名（模糊查询）	"张三"
contactPhone	string	否	联系电话（模糊查询）	"138"
startDate	string	否	开始日期（ISO 格式）	"2024-01-01"
endDate	string	否	结束日期（ISO 格式）	"2024-12-31"
page	number	否	页码（从 1 开始）	1
pageSize	number	否	每页数量	20

请求示例:

GET /api/goods/list?name=笔记本&page=1&pageSize=20

成功响应 (200):

{
  "content": [
    {
      "id": 1,
      "qrCodeId": 100,
      "photoUrl": "uploads/goods/laptop.jpg",
      "name": "苹果笔记本电脑",
      "contactName": "张三",
      "contactPhone": "13800138000",
      "contactEmail": "zhangsan@example.com",
      "remark": null,
      "createdAt": "2024-01-01T10:00:00.000Z",
      "updatedAt": "2024-01-01T10:00:00.000Z"
    },
    {
      "id": 2,
      "qrCodeId": 101,
      "photoUrl": "uploads/goods/laptop2.jpg",
      "name": "联想笔记本电脑",
      "contactName": "李四",
      "contactPhone": "13900139000",
      "contactEmail": "lisi@example.com",
      "remark": null,
      "createdAt": "2024-01-02T10:00:00.000Z",
      "updatedAt": "2024-01-02T10:00:00.000Z"
    }
  ],
  "metadata": {
    "total": 50,
    "page": 1,
    "size": 20
  }
}

错误响应 (401):

{
  "message": "未授权"
}

错误响应 (403):

{
  "message": "权限不足"
}

---

5. 管理员更新物品信息

管理员直接通过二维码 ID 更新物品信息，无需维护码。

接口地址: POST /api/goods/admin/update

权限要求: 需要管理员权限

请求头:

Authorization: Bearer <token>

请求参数:

参数名	类型	必填	说明	示例
qrCodeId	number	是	二维码 ID	100
photoUrl	string	否	物品照片 URL	"uploads/goods/photo.jpg"
name	string	否	物品名称	"苹果笔记本电脑"
contactName	string	否	联系人姓名	"张三"
contactPhone	string	否	联系电话	"13800138000"
contactEmail	string	否	联系邮箱	"zhangsan@example.com"

请求示例:

{
  "qrCodeId": 100,
  "name": "苹果笔记本电脑 MacBook Pro 2024",
  "contactPhone": "13900139000"
}

成功响应 (200):

{
  "message": "物品信息更新成功",
  "data": {
    "id": 1,
    "qrCodeId": 100,
    "photoUrl": "uploads/goods/laptop.jpg",
    "name": "苹果笔记本电脑 MacBook Pro 2024",
    "contactName": "张三",
    "contactPhone": "13900139000",
    "contactEmail": "zhangsan@example.com",
    "remark": null,
    "createdAt": "2024-01-01T10:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

错误响应 (400):

{
  "message": "请提供二维码ID"
}

{
  "message": "物品信息不存在"
}

错误响应 (401):

{
  "message": "未授权"
}

错误响应 (403):

{
  "message": "权限不足"
}

---

数据模型

GoodsInfo 物品信息

字段名	类型	说明
id	number	物品信息 ID（主键）
qrCodeId	number	关联的二维码 ID（唯一）
photoUrl	string	物品照片 URL（可选）
name	string	物品名称（最长 100 字符）
contactName	string	联系人姓名（最长 100 字符）
contactPhone	string	联系电话（最长 20 字符）
contactEmail	string	联系邮箱（可选，最长 100 字符）
remark	string	备注信息（可选，最长 500 字符）
createdAt	Date	创建时间
updatedAt	Date	更新时间

---

业务流程

创建物品信息流程

1. 用户扫描二维码获取 qrCode 参数
2. 调用创建接口 POST /api/goods/create
3. 系统验证二维码是否存在
4. 系统验证二维码类型是否为 goods
5. 系统验证二维码是否已激活
6. 创建物品信息并激活二维码
7. 返回创建成功的物品信息

更新物品信息流程

1. 用户扫描二维码获取 qrCode 参数
2. 用户输入维护码 maintenanceCode
3. 调用更新接口 PUT /api/goods/update
4. 系统验证维护码是否正确
5. 系统验证二维码是否存在
6. 如果物品信息不存在，则创建新记录
7. 如果物品信息存在，则更新记录
8. 返回更新后的物品信息

查询物品信息流程

1. 用户扫描二维码获取 qrCode 参数
2. 调用查询接口 GET /api/goods/get?qrCode=xxx
3. 系统根据二维码查找物品信息
4. 返回物品详细信息

---

注意事项

1. 照片 URL 处理:

   • 如果传入完整 URL（如 https://example.com/uploads/goods/photo.jpg），系统会自动提取路径部分（uploads/goods/photo.jpg）
   • 建议直接传入相对路径

2. 二维码激活:

   • 创建物品信息时会自动激活二维码
   • 已激活的二维码无法重复创建物品信息
   • 可以通过维护码更新已激活的二维码信息

3. 维护码:

   • 维护码在创建二维码时生成
   • 用于验证用户是否有权限更新物品信息
   • 请妥善保管维护码

4. 分页查询:

   • 默认页码为 1，每页 20 条记录
   • 页码从 1 开始计数
   • 支持多条件组合查询

5. 权限控制:

   • 创建、更新、查询接口为公开接口
   • 列表查询和管理员更新需要管理员权限
   • 需要在请求头中携带有效的 JWT Token

---

错误码说明

HTTP 状态码	说明
200	请求成功
201	创建成功
400	请求参数错误或业务逻辑错误
401	未授权（未登录或 Token 无效）
403	权限不足
404	资源不存在
500	服务器内部错误

---

相关接口

• 二维码管理接口
• 宠物信息接口
• 人员信息接口
• 扫描记录接口