# 接口文档：商城与积分

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

## 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`: 注册时间范围