邹方成
04791789c9
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 15s
235 lines
4.6 KiB
Markdown
235 lines
4.6 KiB
Markdown
# 接口文档：商城与积分
|
||
|
||
本文档描述了商城商品、积分兑换及优惠券相关接口。
|
||
|
||
## 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)**:
|
||
|
||
```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)**:
|
||
|
||
```json
|
||
{
|
||
"product_id": 1001,
|
||
"quantity": 1
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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)**:
|
||
|
||
```json
|
||
{
|
||
"card_id": 2001,
|
||
"quantity": 1
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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)**:
|
||
|
||
```json
|
||
{
|
||
"coupon_id": 3001
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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`: 注册时间范围
|