# 物品信息接口文档 ## 概述 物品信息管理接口用于处理与物品相关的二维码信息，包括创建、更新、查询等操作。 **基础路径**: `/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" | **请求示例**: ```json { "qrCode": "QR123456789", "photoUrl": "https://example.com/uploads/goods/laptop.jpg", "name": "苹果笔记本电脑", "contactName": "张三", "contactPhone": "13800138000", "contactEmail": "zhangsan@example.com" } ``` **成功响应** (201): ```json { "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): ```json { "message": "二维码不存在" } ``` ```json { "message": "二维码类型不匹配" } ``` ```json { "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" | **请求示例**: ```json { "qrCode": "QR123456789", "maintenanceCode": "MAINT123456", "name": "苹果笔记本电脑 MacBook Pro", "contactPhone": "13900139000" } ``` **成功响应** (200): ```json { "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): ```json { "message": "维护码错误" } ``` ```json { "message": "二维码不存在" } ``` --- ### 3. 获取物品信息 根据二维码获取物品详细信息。 **接口地址**: `GET /api/goods/get` **权限要求**: 无需认证（公开接口） **请求参数**: | 参数名 | 类型 | 必填 | 说明 | 示例 | | ------ | ------ | ---- | ---------- | ------------- | | qrCode | string | 是 | 二维码编码 | "QR123456789" | **请求示例**: ``` GET /api/goods/get?qrCode=QR123456789 ``` **成功响应** (200): ```json { "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): ```json { "message": "请提供二维码参数" } ``` **错误响应** (404): ```json { "message": "物品信息不存在" } ``` --- ### 4. 查询物品列表（管理员） 分页查询物品信息列表，支持多条件筛选。 **接口地址**: `GET /api/goods/list` **权限要求**: 需要管理员权限 **请求头**: ``` Authorization: Bearer ``` **请求参数**: | 参数名 | 类型 | 必填 | 说明 | 示例 | | ------------ | ------ | ---- | ---------------------- | ------------ | | 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): ```json { "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): ```json { "message": "未授权" } ``` **错误响应** (403): ```json { "message": "权限不足" } ``` --- ### 5. 管理员更新物品信息 管理员直接通过二维码 ID 更新物品信息，无需维护码。 **接口地址**: `POST /api/goods/admin/update` **权限要求**: 需要管理员权限 **请求头**: ``` Authorization: Bearer ``` **请求参数**: | 参数名 | 类型 | 必填 | 说明 | 示例 | | ------------ | ------ | ---- | ------------ | ------------------------- | | qrCodeId | number | 是 | 二维码 ID | 100 | | photoUrl | string | 否 | 物品照片 URL | "uploads/goods/photo.jpg" | | name | string | 否 | 物品名称 | "苹果笔记本电脑" | | contactName | string | 否 | 联系人姓名 | "张三" | | contactPhone | string | 否 | 联系电话 | "13800138000" | | contactEmail | string | 否 | 联系邮箱 | "zhangsan@example.com" | **请求示例**: ```json { "qrCodeId": 100, "name": "苹果笔记本电脑 MacBook Pro 2024", "contactPhone": "13900139000" } ``` **成功响应** (200): ```json { "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): ```json { "message": "请提供二维码ID" } ``` ```json { "message": "物品信息不存在" } ``` **错误响应** (401): ```json { "message": "未授权" } ``` **错误响应** (403): ```json { "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 | 服务器内部错误 | --- ## 相关接口 - [二维码管理接口](./qr-code-api.md) - [宠物信息接口](./pet-info-api.md) - [人员信息接口](./person-info-api.md) - [扫描记录接口](./scan-record-api.md)