数字无极小程序接口设计

小程序后端接口文档

公共说明

  • 所有接口统一前缀：/api/v1
  • 所有需要身份验证的接口需携带 Authorization: Bearer <token>
  • 接口统一响应格式：
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
  • code 为 0 表示成功，其他值表示失败
  • message 为错误信息
  • data 为接口返回的数据

1. 用户模块

1.1 微信登录

  • 接口名称：微信登录
  • 方法：POST
  • 路径：/auth/login
  • 描述：通过微信 code 获取用户信息，生成登录 token
  • 请求参数：
{
  "code": "微信临时登录凭证（wx.login 获取）"
}
  • 响应参数：
{
  "token": "登录令牌",
  "user_info": {
    "openid": "微信用户唯一标识",
    "nickname": "张三",
    "avatar": "https://...",
    "phone": "138xxxx0000"
  }
}

1.2 获取手机号

  • 方法：POST
  • 路径：/user/phone
  • 描述：解密微信手机号或校验手机号验证码
  • 请求参数（方式一：微信加密数据）：
{
  "encryptedData": "",
  "iv": ""
}
  • 请求参数（方式二：验证码校验）：
{
  "phone": "138xxxxxxx",
  "code": "1234"
}
  • 响应参数：
{
  "phone": "138xxxxxxx"
}

1.3 获取验证码

  • 方法：POST
  • 路径：/auth/send_code
  • 描述：向手机号发送短信验证码
  • 请求参数：
{
  "phone": "138xxxxxxx"
}
  • 响应参数：
{
  "message": "验证码已发送"
}

1.4 验证验证码

  • 方法：POST
  • 路径：/user/verify_code
  • 描述：验证用户验证码是否正确
  • 请求参数：
{
  "phone": "138xxxxxxx",
  "code": "1234"
}
  • 响应参数：
{
  "message": "验证码验证通过"
}

1.5 获取用户信息

  • 方法：GET

  • 路径：/user/info

  • 描述：返回当前登录用户信息

  • 响应参数：

{
  "openid": "微信用户唯一标识",
  "nickname": "张三",
  "avatar": "",
  "phone": "138xxxxxxx"
}

1.6 更新用户信息

  • 方法：POST
  • 路径：/user/update
  • 描述：更新用户昵称、头像等
  • 请求参数：
{
  "nickname": "张三",
  "avatar": "https://..."
}
  • 响应参数：
{
  "message": "用户信息更新成功"
}

2. 展览模块

2.1 获取展览列表

  • 方法：GET

  • 路径：/exhibitions

  • 描述：分页获取展览信息

  • 请求参数（Query）：

    • page: 页码，默认 1
    • page_size: 每页条数，默认 10
    • keyword: （可选）搜索关键词

  • 响应参数：

{
  "total": 100,
  "page": 1,
  "page_size": 10,
  "list": [
    {
      "id": 1,
      "title": "展览标题",
      "description": "展览简介",
      "cover": "https://...",
      "location": "展览地点",
      "date": "2024-08-01",
      "status": "upcoming",
      "favorites": 100,
      "likes": 50,
      "shares": 20
    }
}
  • status 可选值：upcoming（即将开始）、ongoing（进行中）、ended（已结束）

2.2 获取展览详情

  • 方法：GET

  • 路径：/exhibitions/:id

  • 描述：根据 ID 获取展览详情

  • 响应参数：

{
  "id": 1,
  "title": "展览标题",
  "description": "展览简介",
  "cover": "https://...",
  "location": "展览地点",
  "date": "2024-08-01",
  "status": "upcoming",
  "favorites": 100,
  "likes": 50,
  "shares": 20
}

2.3 收藏展览

  • 方法：POST

  • 路径：/exhibitions/:id/favorite

  • 描述：收藏或取消收藏展览

  • 响应参数：

{
  "message": "收藏成功"
}

2.4 点赞展览

  • 方法：POST

  • 路径：/api/exhibitions/:id/like

  • 描述：点赞或取消点赞

  • 响应参数：

{
  "message": "点赞成功"
}

2.5 分享展览

  • 方法：POST

  • 路径：/api/exhibitions/:id/share

  • 描述：记录用户分享行为

  • 响应参数：

{
  "message": "分享成功"
}

2.6 获取收藏列表

  • 方法：GET

  • 路径：/user/favorites

  • 描述：获取当前用户收藏的展览列表

  • 请求参数：

    • page: 页码，默认 1
    • page_size: 每页条数，默认 10

  • 响应参数：

[
  {
    "id": 1,
    "title": "收藏标题",
    "cover": "https://...",
    "date": "2024-08-01",
    "location": "收藏地点"
  }
]

3. 预约模块

3.1 提交预约

  • 方法：POST
  • 路径：/reservations
  • 描述：提交展览预约申请
  • 请求参数：
{
  "exhibition_id": 1,
  "visitor_phone": "138xxxxxxx"
}
  • 响应参数：
{
  "message": "预约成功"
}

3.2 取消预约

  • 方法：DELETE

  • 路径：/reservations/:id

  • 描述：取消预约记录

  • 响应参数：

{
  "message": "预约取消成功"
}

3.3 我的预约记录

  • 方法：GET

  • 路径：/reservations/my

  • 描述：获取当前用户预约记录列表

  • 响应参数：

[
  {
    "id": 1,
    "exhibition_id": 1,
    "title": "预约标题",
    "date": "2024-08-01",
    "location": "预约地点",
    "status": "pending"
  }
]
  • status 可选值：pending（待处理）、confirmed（已确认）、cancelled（已取消）、completed（已完成）、expired（已过期）

4. 票务模块

4.1 创建订单

  • 方法：POST
  • 路径：/api/orders
  • 描述：提交门票订单
  • 请求参数：
{
  "exhibition_id": 1,
  "ticket_type": "standard",
  "quantity": 2
}
  • 响应参数：
{
  "order_id": "1234567890"
}

4.2 支付回调

  • 方法：POST
  • 路径：/api/orders/pay_callback
  • 描述：处理支付平台回调
  • 请求参数：
{
  "order_id": "1234567890",
  "status": "success"
}
  • 响应参数：
{
  "message": "支付成功"
}

4.3 获取订单详情

  • 方法：GET

  • 路径：/api/orders/:id

  • 描述：获取订单详细信息

  • 响应参数：

{
  "order_id": "1234567890",
  "exhibition_id": 1,
  "title": "订单标题",
  "date": "2024-08-01",
  "location": "订单地点",
  "status": "success",
  "tickets": [
    {
      "ticket_id": "ticket123",
      "status": "valid"
    }
  ]
}
  • status 可选值：pending（待支付）、success（支付成功）、cancelled（已取消）、expired（已过期）
  • ticket_status 可选值：valid（有效）、used（已使用）、expired（已过期）、cancelled（已取消）、refunded（已退款）、invalid（无效）

4.4 我的订单列表

  • 方法：GET
  • 路径：/api/orders/my
  • 描述：返回当前用户的订单记录
  • 请求参数：
    • page: 页码，默认 1
    • page_size: 每页条数，默认 10
  • 响应参数：
[
  {
    "order_id": "1234567890",
    "exhibition_id": 1,
    "title": "订单标题",
    "date": "2024-08-01",
    "location": "订单地点",
    "status": "success",
    "tickets": [
      {
        "ticket_id": "ticket123",
        "status": "valid"
      }
    ]
  }
]

4.5 核销门票

  • 方法：POST
  • 路径：/api/tickets/:id/verify
  • 描述：通过核销员扫码核销门票
  • 请求参数：
{
  "verifier_id": "admin123",
  "verify_code": "123456"
}
  • 响应参数：
{
  "message": "核销成功"
}

4.6 获取门票二维码

  • 方法：GET

  • 路径：/api/tickets/:id/qrcode

  • 描述：返回二维码 URL 或 base64 数据

  • 响应参数：

{
  "qrcode": "https://...",
  "ticket_id": "ticket123"
}

5. 通用模块

5.1 上传图片

  • 方法：POST

  • 路径：/api/upload/image

  • 描述：上传展览封面图等图片（使用 multipart/form-data）

  • 请求参数：

    • file: 图片文件

  • 响应参数：

{
  "url": ""
}

5.2 获取配置项

  • 方法：GET

  • 路径：/api/configs

  • 描述：返回客服电话、页面配置等

  • 响应参数：

{
  "contact_phone": "138xxxxxxx",
  "page_config": {
    "title": "页面标题",
    "description": "页面描述"
  }
}