线下活动 activity

# 活动模块 API 接口文档

> 模块标识：`activity`
> 基础路径：`/api/`

---

## 通用说明

### 请求头

| 参数 | 说明 |
|---|---|
| `Authorization` | `Bearer {token}`（需登录的接口必填） |

### 通用参数

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `shopid` | int | `0` | 店铺ID，Base 基类自动获取 |
| `app` | string | 当前模块名 | 应用名，Base 基类自动获取 |

### 响应结构

```json
{
    "code": 200,
    "msg": "success",
    "data": {},
    "url": "",
    "time": 1732233600,
    "wait": 3
}
```

| 字段 | 说明 |
|---|---|
| `code` | `200`=成功，`0`=失败 |
| `data` | 数据载体，登录失效时值为字符串 `"login"` |

---

## 一、配置

### 1.1 获取活动配置

`GET /api/config`

无需登录

**请求参数**：无

**响应示例**：
```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "status": 1,
        "thumb": "4:3",
        "map": "{...}",
        "show": "{...}"
    }
}
```

---

## 二、分类

### 2.1 分类树

`GET /api/category/tree`

无需登录

**请求参数**：无

**响应示例**：
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "pid": 0,
            "title": "分类名称",
            "children": []
        }
    ]
}
```

---

## 三、筛选

### 3.1 筛选属性树

`GET /api/attribute/tree`

无需登录

**请求参数**：无

**响应示例**：
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "pid": 0,
            "title": "属性名称",
            "children": []
        }
    ]
}
```

---

## 四、活动

### 4.1 活动列表

`GET /api/activity/lists`

无需登录

**请求参数**：

| 参数 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| `rows` | int | `20` | 否 | 每页数量 |
| `keyword` | string | - | 否 | 关键词搜索 |
| `category_id` | int | `0` | 否 | 分类ID |
| `attribute_ids` | string | - | 否 | 筛选值ID（逗号分隔） |
| `author_id` | int | `0` | 否 | 创作者ID |
| `order_field` | string | `id` | 否 | 排序字段 |
| `order_type` | string | `desc` | 否 | 排序方向（desc/asc） |

**响应示例**：
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 100,
        "per_page": 20,
        "current_page": 1,
        "last_page": 5,
        "data": [
            {
                "id": 1,
                "title": "活动标题",
                "description": "简短描述",
                "cover": "/uploads/cover.jpg",
                "cover_400": "/uploads/cover_400.jpg",
                "images": "/uploads/1.jpg,/uploads/2.jpg",
                "price": "9.90",
                "marking_price": "19.80",
                "sales_method": "pay",
                "sales_method_str": "付费",
                "minus_score": 0,
                "start_time": 1732233600,
                "end_time": 1732320000,
                "start_time_str": "2024-11-22 09:00",
                "end_time_str": "2024-11-23 09:00",
                "province": "广东省",
                "city": "深圳市",
                "district": "南山区",
                "address": "XX路XX大厦",
                "quantity": 100,
                "remainder_quantity": 50,
                "score": 10,
                "view": 200,
                "sales": 50,
                "favorites": 30,
                "purchase": 0,
                "favorites_yesno": 0,
                "activity_status": 2,
                "activity_status_str": "进行中"
            }
        ]
    }
}
```

### 4.2 活动详情

`GET /api/activity/detail`

无需登录（已登录用户会写入浏览记录）

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 活动ID |

**错误码**：

| msg | 说明 |
|---|---|
| `缺少参数` | id 为空 |
| `error` | 数据不存在 |

**响应示例**：同列表单条数据结构

### 4.3 报名记录列表

`GET /api/activity/record`

无需登录

**请求参数**：

| 参数 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| `rows` | int | `20` | 否 | 每页数量 |
| `order_field` | string | `id` | 否 | 排序字段 |
| `order_type` | string | `desc` | 否 | 排序方向 |

---

## 五、收藏

### 5.1 收藏/取消收藏

`POST /api/favorite/edit`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `info_id` | int | **是** | 活动ID |
| `info_type` | string | **是** | 内容类型（`activity`） |

**错误码**：

| msg | 说明 |
|---|---|
| `数据异常` | info_id 为空 |
| `内容不存在` | 活动不存在 |
| `收藏失败` / `取消失败` | 操作失败 |

**响应示例**：
```json
{
    "code": 200,
    "msg": "收藏成功",
    "data": "",
    "url": ""
}
```

---

## 六、我的订单

### 6.1 我的订单列表

`GET /api/my/lists`

**需要登录**

**请求参数**：

> 仅返回已付款且未过期的订单（排除 VIP 卡类型）

**响应示例**：
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 10,
        "per_page": 20,
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                "order_no": "202411220001",
                "paid": 1,
                "paid_fee": 990,
                "status": 4,
                "products": "{...}",
                "create_time": 1732233600
            }
        ]
    }
}
```

---

## 七、订单操作

### 7.1 订单详情

`GET /api/Orders/detail`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `order_no` | string | **是** | 订单号 |

### 7.2 确认收货

`POST /api/Orders/confirm`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 订单ID |

**业务规则**：仅 `status == 3`（已发货）的订单可确认收货

**错误码**：

| msg | 说明 |
|---|---|
| `参数错误，无法确认收货！` | 订单状态不是3 |
| `确认收货失败！` | 更新失败 |

**响应示例**：
```json
{
    "code": 200,
    "msg": "确认收货成功！",
    "data": {},
    "url": "refresh"
}
```

### 7.3 取消订单

`POST /api/Orders/cancel`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 订单ID |

**业务规则**：仅未付款且属于当前用户的订单可取消，取消后 `status = 0`

**错误码**：

| msg | 说明 |
|---|---|
| `订单无法取消！` | 已付款或非本人订单 |
| `订单取消失败！` | 更新失败 |

### 7.4 删除订单

`POST /api/Orders/delete`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 订单ID |

**业务规则**：仅未付款且属于当前用户的订单可删除，删除后 `status = -1`

**错误码**：

| msg | 说明 |
|---|---|
| `订单无法删除！` | 已付款或非本人订单 |
| `订单删除失败！` | 更新失败 |

### 7.5 退款申请

`POST /api/Orders/refund`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 订单ID |

**业务规则**：已付款 + 本人订单 + `status < 5`，申请后 `refund = 1`

**错误码**：

| msg | 说明 |
|---|---|
| `该订单暂时无法申请退款！` | 不满足退款条件 |
| `退款申请失败！` | 更新失败 |

**响应示例**：
```json
{
    "code": 200,
    "msg": "退款申请成功！",
    "data": {},
    "url": "refresh"
}
```

---

## 八、核销

### 8.1 获取核销数据

`GET /api/Verification/verification`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `products_id` | int | **是** | 活动ID |

**响应示例**：
```json
{
    "code": 200,
    "msg": "获取成功！",
    "data": {
        "id": 1,
        "order_no": "202411220001",
        "uid": 1001,
        "verification_code": "20241122...",
        "status": 0
    }
}
```

### 8.2 扫码核销

`GET|POST /api/Verification/action`

**需要登录**（且需为核销员）

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 核销记录ID |

**请求方式区别**：

| 方式 | 说明 |
|---|---|
| `GET` | 获取核销记录预览数据 |
| `POST` | 执行核销操作（`status=1`，记录核销员和时间） |

**错误码**：

| msg | 说明 |
|---|---|
| `扫码无效，非核销工作人员！` | 当前用户非核销员 |
| `核销失败` | POST 更新失败 |
| `error` | GET 数据不存在 |

### 8.3 验证核销员身份

`GET /api/Verification/check`

**需要登录**

**请求参数**：无

**响应示例**：
```json
// 是核销员
{
    "code": 200,
    "msg": "核销工作人员！",
    "data": { "id": 1, "uid": 1001, "status": 1 }
}
// 不是
{
    "code": 0,
    "msg": "非核销工作人员！",
    "data": ""
}
```

### 8.4 生成核销二维码URL

`GET /api/Verification/qrcode`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 核销记录ID |

**响应示例**：
```json
{
    "code": 200,
    "msg": "success",
    "data": "https://domain.com/h5/index#/activity/pages/activity/manage?id=123"
}
```

### 8.5 核销状态轮询

`GET /api/Verification/verify`

**需要登录**

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | int | **是** | 核销记录ID |

**响应示例**：
```json
// 已核销
{
    "code": 200,
    "msg": "核销完成",
    "data": { "id": 1, "status": 1, "verification_time": 1732233600 }
}
// 未核销
{
    "code": 0,
    "msg": "未核销",
    "data": ""
}
```

---

## 附录：售卖方式枚举

| 值 | 说明 | 下单逻辑 |
|---|---|---|
| `free` | 免费 | 直接完成，`paid=1` |
| `pay` | 付费 | 走正常支付流程，支持会员折扣 |
| `score` | 积分 | 校验积分余额，立即扣减积分并完成 |
| `password` | 密码 | 校验密码是否匹配，匹配则直接完成 |

## 附录：活动状态枚举

| 值 | 说明 |
|---|---|
| 1 | 未开始 |
| 2 | 进行中 |
| 3 | 已结束 |

## 附录：订单状态枚举

| 值 | 说明 |
|---|---|
| 0 | 已取消 |
| 1 | 待支付 |
| 2 | 已支付（待发货） |
| 3 | 已发货（待收货） |
| 4 | 已收货（已完成） |
| -1 | 已删除 |

全文搜索