bindbox-game/docs/接口文档_商城与积分.md

接口文档：商城与积分

本文档描述了商城商品、积分兑换及优惠券相关接口。

1. 商城接口 (APP 端)

1.1 获取商城物品列表

统一获取商城中的可兑换物品，支持商品、道具卡、优惠券三种类型。

• URL: /api/app/store/items
• Method: GET
• Auth: Required (Bearer Token)

请求参数 (Query):

参数名	类型	必填	默认值	说明
kind	string	否	product	物品类型，可选值：product (商品), item_card (道具卡), coupon (优惠券)
page	int	否	1	页码
page_size	int	否	20	每页数量 (最大100)

响应示例 (JSON):

{
  "total": 100,
  "page": 1,
  "page_size": 20,
  "list": [
    {
      "id": 1001,
      "kind": "product",
      "name": "IPhone 15",
      "main_image": "http://.../img.jpg",
      "price": 100000,
      "points_required": 1000,
      "in_stock": true,
      "status": 1,
      "supported": true
    },
    {
      "id": 2001,
      "kind": "item_card",
      "name": "免运费卡",
      "price": 500,
      "points_required": 5,
      "status": 1,
      "supported": true
    },
    {
      "id": 3001,
      "kind": "coupon",
      "name": "10元代金券",
      "discount_type": 1,
      "discount_value": 1000,
      "min_spend": 0,
      "points_required": 10,
      "status": 1,
      "supported": true
    }
  ]
}

字段说明:

• kind: product | item_card | coupon
• price: 售价（分），仅 product 和 item_card 有效。
• points_required: 兑换所需积分。
• discount_type: 优惠券类型，1: 直减金额券。
• discount_value: 优惠面额（分）。
• supported: 是否支持积分兑换（当前仅直减券支持）。

---

2. 积分兑换接口 (APP 端)

所有兑换接口均需登录，URL 中的 :user_id 仅作路由占位，实际操作以 Token 中的用户 ID 为准。

2.1 积分兑换商品

• URL: /api/app/users/:user_id/points/redeem-product
• Method: POST
• Auth: Required

请求参数 (Body):

{
  "product_id": 1001,
  "quantity": 1
}

响应参数:

{
  "success": true,
  "ledger_id": 123456,
  "order_id": 987654,
  "inventory_ids": [111, 222],
  "message": "ok"
}

说明:

• ledger_id: 积分扣减流水 ID。
• order_id: 生成的发货订单 ID。
• inventory_ids: 发放到用户资产中的 ID 列表。

2.2 积分兑换道具卡

• URL: /api/app/users/:user_id/points/redeem-item-card
• Method: POST
• Auth: Required

请求参数 (Body):

{
  "card_id": 2001,
  "quantity": 1
}

响应参数:

{
  "success": true,
  "card_id": 2001,
  "ledger_id": 123457,
  "message": "ok"
}

2.3 积分兑换优惠券

仅支持兑换直减金额券 (discount_type=1)。

• URL: /api/app/users/:user_id/points/redeem-coupon
• Method: POST
• Auth: Required

请求参数 (Body):

{
  "coupon_id": 3001
}

响应参数:

{
  "success": true,
  "coupon_id": 3001,
  "ledger_id": 123458,
  "message": "ok"
}

---

3. 优惠券使用流水接口

记录优惠券的核销、抵扣详情。

3.1 查询优惠券使用记录 (APP 端)

• URL: /api/app/users/:user_id/coupons/:user_coupon_id/usage
• Method: GET
• Auth: Required

请求参数 (Query):

• page: 页码 (默认1)
• page_size: 每页数量 (默认20)

响应参数:

{
  "total": 5,
  "page": 1,
  "page_size": 20,
  "list": [
    {
      "id": 101,
      "change_amount": -100,
      "balance_after": 900,
      "order_id": 88888,
      "action": "apply",
      "created_at": "2025-01-01 12:00:00"
    }
  ]
}

说明:

• change_amount: 变动金额（分），负数表示扣减。
• balance_after: 变动后余额（分）。一次性券核销后余额为0。
• order_id: 关联的订单 ID。

3.2 查询优惠券使用记录 (管理端)

• URL: /api/admin/users/:user_id/coupons/:user_coupon_id/usage
• Method: GET
• Auth: Required (Admin Token)

响应参数: 与 APP 端类似，但在 List Item 中额外包含 user_id 和 user_coupon_id 字段。

---

4. 玩家管理接口 (管理端)

4.1 玩家列表搜索

支持按 ID 精确搜索玩家。

• URL: /api/admin/users
• Method: GET
• Auth: Required

新增请求参数 (Query):

• id: int64 (可选) 用户 ID，精确匹配。

原有参数:

• nickname: 昵称模糊搜索
• inviteCode: 邀请码精确搜索
• startDate / endDate: 注册时间范围