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