# 停车场激励小程序 API 文档

## 基础信息

- **Base URL**: `https://your-domain.com/api/v1`
- **认证方式**: JWT Bearer Token（除登录接口外，所有接口需在 Header 中携带 `Authorization: Bearer <token>`）
- **Content-Type**: `application/json`

## 通用返回格式

### 成功
```json
{
  "success": true,
  "data": { ... }
}
```

### 失败
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
}
```

---

## 1. 健康检查

### GET /health

无需认证。

**响应示例**:
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 12345.6
}
```

---

## 2. 认证

### POST /auth/login

微信登录/注册合一接口。

**请求体**:
```json
{
  "code": "wx.login()返回的code",
  "licensePlate": "京A12345",
  "nickname": "用户昵称（选填）",
  "avatarUrl": "头像URL（选填）",
  "referralCode": "邀请码（选填）"
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "nickname": "张三",
      "avatarUrl": "https://...",
      "licensePlate": "京A12345",
      "referralCode": "AB3XK9L2",
      "availablePoints": 30,
      "totalEarnedPoints": 30,
      "uplineId": 2,
      "hasUpline": true
    },
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "isNew": true
  }
}
```

**错误码**:
- `VALIDATION_ERROR` - 参数校验失败
- `WECHAT_ERROR` - 微信API调用失败

---

## 3. 用户

### GET /user/profile

获取当前用户完整信息。

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "nickname": "张三",
    "avatarUrl": "https://...",
    "licensePlate": "京A12345",
    "referralCode": "AB3XK9L2",
    "availablePoints": 130,
    "totalEarnedPoints": 150,
    "totalRedeemedPoints": 20,
    "upline": {
      "id": 2,
      "nickname": "李四",
      "licensePlate": "京B54321"
    },
    "downlineCount": 5,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### GET /user/stats

获取统计数据。

**响应示例**:
```json
{
  "success": true,
  "data": {
    "availablePoints": 130,
    "totalEarnedPoints": 150,
    "totalRedeemedPoints": 20,
    "downlineCount": 5
  }
}
```

### GET /user/downlines?page=1&pageSize=20

获取下家列表（分页）。

**响应示例**:
```json
{
  "success": true,
  "data": {
    "list": [
      {
        "id": 3,
        "nickname": "王五",
        "avatar_url": "https://...",
        "license_plate": "京C11111",
        "available_points": 0,
        "created_at": "2024-01-02T00:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}
```

---

## 4. 积点

### GET /points/balance

获取积点余额。

**响应示例**:
```json
{
  "success": true,
  "data": {
    "availablePoints": 130,
    "totalEarnedPoints": 150,
    "totalRedeemedPoints": 20
  }
}
```

### GET /points/transactions?page=1&pageSize=20&type=earn

获取积点流水（分页，可按类型筛选）。

**类型可选值**: `earn`（邀请奖励）、`redeem`（兑换优惠券）、`commission`（停车佣金）、`admin_adjust`（系统调整）

**响应示例**:
```json
{
  "success": true,
  "data": {
    "list": [
      {
        "id": 1,
        "type": "earn",
        "points": 30,
        "balance_after": 30,
        "description": "邀请新用户奖励 +30积点",
        "reference_type": "referral",
        "reference_id": 3,
        "created_at": "2024-01-02T00:00:00.000Z"
      }
    ],
    "total": 10,
    "page": 1,
    "pageSize": 20
  }
}
```

---

## 5. 优惠券

### GET /coupons/catalog

获取可兑换优惠券列表。

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "5元停车券",
      "denominationCents": 500,
      "denominationYuan": "5.00",
      "pointsRequired": 50,
      "validDays": 30
    }
  ]
}
```

### POST /coupons/redeem

积点兑换优惠券。

**请求体**:
```json
{
  "couponId": 1
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 10,
    "couponName": "5元停车券",
    "denominationCents": 500,
    "pointsCost": 50,
    "newBalance": 80
  }
}
```

**错误码**:
- `INSUFFICIENT_POINTS` - 积点不足
- `NOT_FOUND` - 优惠券模板不存在

### GET /coupons/my?status=available

获取我的优惠券（可按状态筛选）。

**状态可选值**: `available`（可使用）、`used`（已使用）、`expired`（已过期）、`cancelled`（已取消）

---

## 6. 停车

### POST /parking/check-in

停车入场。

**请求体**:
```json
{
  "licensePlate": "京A12345",
  "parkingLotId": "P1",
  "entryTime": "2024-01-01T08:00:00"
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "licensePlate": "京A12345",
    "entryTime": "2024-01-01T08:00:00.000Z",
    "status": "active"
  }
}
```

### POST /parking/check-out

停车出场结算。

**请求体**:
```json
{
  "sessionId": 1,
  "couponIds": [10],
  "parkingFeeCents": 1500
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "sessionId": 1,
    "totalFeeCents": 1500,
    "couponDiscountCents": 500,
    "cashPaymentCents": 1000,
    "commissionGenerated": true,
    "totalFeeYuan": "15.00",
    "couponDiscountYuan": "5.00",
    "cashPaymentYuan": "10.00",
    "appliedCoupons": [
      {
        "id": 10,
        "name": "5元停车券",
        "denominationCents": 500
      }
    ]
  }
}
```

### GET /parking/sessions?page=1&pageSize=20

获取停车记录列表。

### GET /parking/sessions/:id

获取单条停车记录详情。

---

## 业务规则说明

### 积点汇率
- 10 积点 = 1 元
- 兑换: 50积点 → 5元优惠券, 100积点 → 10元优惠券, 200积点 → 20元优惠券, 500积点 → 50元优惠券

### 邀请奖励
- 每邀请 1 位新用户注册 → 邀请人获得 30 积点
- 自主注册（无邀请码）→ 0 积点

### 佣金计算
```
佣金积点 = FLOOR(实付金额(分) × 20% ÷ 10)
```
- 例：下家实付 15 元 = 1500 分 → 1500 × 0.20 ÷ 10 = 30 积点
- 只对直接上家（一级）生成佣金
- 实付金额为 0（优惠券完全抵扣）→ 无佣金