|
|
@@ -0,0 +1,488 @@
|
|
|
+# 物品信息接口文档
|
|
|
+
|
|
|
+## 概述
|
|
|
+
|
|
|
+物品信息管理接口用于处理与物品相关的二维码信息，包括创建、更新、查询等操作。
|
|
|
+
|
|
|
+**基础路径**: `/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 <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):
|
|
|
+
|
|
|
+```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 <token>
|
|
|
+```
|
|
|
+
|
|
|
+**请求参数**:
|
|
|
+
|
|
|
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
|
|
+| ------------ | ------ | ---- | ------------ | ------------------------- |
|
|
|
+| 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)
|
