# 我的收益页面接口参数说明

## 📋 页面功能概述

**页面路径**：`pages/me/my-earnings-page.vue`

**主要功能**：
1. 显示收益统计（待提取收益、已提取收益）
2. 提现功能（申请提现、查看最高可提现金额）
3. 查看收益规则说明
4. 收益记录列表（时间、房号/房名、房费、收益）
5. 提现记录列表（时间、提现金额、状态）

---

## 🔌 接口需求清单

### 接口1：获取收益统计信息

#### 基本信息
- **接口路径**：建议 `GET /api/user/GetEarningsSummary` 或 `POST /api/user/GetEarningsSummary`
- **调用时机**：
  - 页面初始化时
  - 提现成功后刷新
- **是否需要登录**：是（需要Token）

#### 请求参数
无需参数（从Token中获取用户信息）

#### 返回数据结构

```typescript
interface Response {
  code: number;        // 0=成功
  msg: string;         // 消息
  data: {
    pendingAmount: number;  // 待提取收益（元）
    extractedAmount: number; // 已提取收益（元）
  }
}
```

#### 返回示例

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "pendingAmount": 120.50,
    "extractedAmount": 500.00
  }
}
```

#### 页面映射
- `pendingAmount` → 第19行：待提取收益（元）
- `extractedAmount` → 第23行：已提取收益（元）

---

### 接口2：获取收益规则说明

#### 基本信息
- **接口路径**：建议 `GET /api/user/GetEarningsRule` 或 `POST /api/user/GetEarningsRule`
- **调用时机**：
  - 点击"点击查看收益规则"时（第35-37行）
  - 打开规则弹窗时（第86-96行）
- **是否需要登录**：否（可公开）

#### 请求参数
无需参数

#### 返回数据结构

```typescript
interface Response {
  code: number;        // 0=成功
  msg: string;         // 消息
  data: {
    content: string;   // 规则说明正文
  }
}
```

#### 返回示例

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "content": "收益规则说明：\n1. 收益来源于房间预约成功后的分成\n2. 收益可随时提现\n3. 提现将在3-5个工作日内到账\n4. 最低提现金额为10元"
  }
}
```

#### 页面映射
- `content` → 第89-93行：规则说明弹窗正文

---

### 接口3：获取收益记录列表

#### 基本信息
- **接口路径**：建议 `GET /api/user/GetEarningsRecordList` 或 `POST /api/user/GetEarningsRecordList`
- **调用时机**：
  - 页面初始化时（currentIndex = 0）
  - 切换到"收益记录"标签时
  - 下拉刷新时
- **是否需要登录**：是（需要Token）

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| pageIndex | number | 否 | 页码，从1开始 | 1 |
| pageSize | number | 否 | 每页数量 | 20 |

#### 返回数据结构

```typescript
interface Response {
  code: number;        // 0=成功
  msg: string;         // 消息
  data: EarningsRecordItem[];
}

interface EarningsRecordItem {
  id: number;              // 记录ID（必填）
  date: string;            // 时间，格式：YYYY/MM/DD 或 YYYY-MM-DD（必填）
  roomNumber: string;      // 房号，如：305（必填）
  roomName: string;        // 房名，如：大包（必填）
  roomFee: number;         // 房费（元）（必填）
  earnings: number;        // 收益（元）（必填）
  reservationId?: number;  // 预约ID（可选）
}
```

#### 返回示例

```json
{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "id": 1,
      "date": "2025/1/1",
      "roomNumber": "305",
      "roomName": "大包",
      "roomFee": 12.00,
      "earnings": 0.12,
      "reservationId": 123
    },
    {
      "id": 2,
      "date": "2025/1/2",
      "roomNumber": "306",
      "roomName": "中包",
      "roomFee": 10.00,
      "earnings": 0.10,
      "reservationId": 124
    }
  ]
}
```

#### 页面映射
- `date` → 第68行：时间
- `roomNumber + roomName` → 第69行：305（大包）
- `roomFee` → 第70行：￥12
- `earnings` → 第71行：￥0.12

**注意**：页面显示格式为 `{roomNumber}（{roomName}）`，如：`305（大包）`

---

### 接口4：获取提现记录列表

#### 基本信息
- **接口路径**：建议 `GET /api/user/GetWithdrawRecordList` 或 `POST /api/user/GetWithdrawRecordList`
- **调用时机**：
  - 切换到"提现记录"标签时（currentIndex = 1）
  - 下拉刷新时
- **是否需要登录**：是（需要Token）

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| pageIndex | number | 否 | 页码，从1开始 | 1 |
| pageSize | number | 否 | 每页数量 | 20 |

#### 返回数据结构

```typescript
interface Response {
  code: number;        // 0=成功
  msg: string;         // 消息
  data: WithdrawRecordItem[];
}

interface WithdrawRecordItem {
  id: number;              // 记录ID（必填）
  date: string;            // 时间，格式：YYYY/MM/DD 或 YYYY-MM-DD（必填）
  amount: number;          // 提现金额（元）（必填）
  status: string;          // 状态：提现中/已到账/已拒绝（必填）
  statusCode?: number;     // 状态码：0=提现中，1=已到账，2=已拒绝（可选）
  remark?: string;         // 备注（可选）
}
```

#### 返回示例

```json
{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "id": 1,
      "date": "2025/1/1",
      "amount": 100.00,
      "status": "提现中",
      "statusCode": 0
    },
    {
      "id": 2,
      "date": "2024/12/30",
      "amount": 50.00,
      "status": "已到账",
      "statusCode": 1
    },
    {
      "id": 3,
      "date": "2024/12/28",
      "amount": 200.00,
      "status": "已拒绝",
      "statusCode": 2,
      "remark": "银行卡信息错误"
    }
  ]
}
```

#### 页面映射
- `date` → 第77行：时间
- `amount` → 第78行：￥12
- `status` → 第79行：提现中

---

### 接口5：申请提现

#### 基本信息
- **接口路径**：建议 `POST /api/user/ApplyWithdraw`
- **调用时机**：
  - 点击"申请提现"按钮时（第114行）
- **是否需要登录**：是（需要Token）

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|-------|------|------|------|------|
| amount | number | 是 | 提现金额（元） | 100.00 |

#### 返回数据结构

```typescript
interface Response {
  code: number;        // 0=成功，其他=失败
  msg: string;         // 消息说明
  data?: {
    withdrawId?: number; // 提现记录ID（可选）
  }
}
```

#### 返回示例

```json
// 成功
{
  "code": 0,
  "msg": "提现申请已提交",
  "data": {
    "withdrawId": 123
  }
}

// 失败 - 余额不足
{
  "code": 500,
  "msg": "提现金额不能超过待提取收益"
}

// 失败 - 金额过小
{
  "code": 500,
  "msg": "最低提现金额为10元"
}
```

---

### 接口6：获取最高可提现金额（可选）

#### 基本信息
- **接口路径**：建议 `GET /api/user/GetMaxWithdrawAmount` 或使用接口1的 `pendingAmount`
- **调用时机**：
  - 打开提现弹窗时（第98-118行）
  - 用于显示"最高可提现0.00元"（第108行）
- **是否需要登录**：是（需要Token）

#### 说明
此接口可以复用**接口1（获取收益统计信息）**中的 `pendingAmount` 字段，无需单独接口。

如果后端需要单独接口，可参考接口1的返回结构，只返回 `pendingAmount`。

---

## 📝 页面数据映射总览

### 收益统计卡片（第13-32行）

| 显示位置 | 数据来源 | 字段名 |
|---------|---------|--------|
| 第19行：待提取收益 | 接口1 | `pendingAmount` |
| 第23行：已提取收益 | 接口1 | `extractedAmount` |
| 第108行：最高可提现 | 接口1 | `pendingAmount` |

### 收益记录列表（第65-73行，currentIndex = 0）

| 显示位置 | 数据来源 | 字段名 | 显示格式 |
|---------|---------|--------|---------|
| 第68行：时间 | 接口3 | `date` | 直接显示 |
| 第69行：房号/房名 | 接口3 | `roomNumber` + `roomName` | `{roomNumber}（{roomName}）` |
| 第70行：房费 | 接口3 | `roomFee` | `￥{roomFee}` |
| 第71行：收益 | 接口3 | `earnings` | `￥{earnings}` |

### 提现记录列表（第74-81行，currentIndex = 1）

| 显示位置 | 数据来源 | 字段名 | 显示格式 |
|---------|---------|--------|---------|
| 第77行：时间 | 接口4 | `date` | 直接显示 |
| 第78行：提现金额 | 接口4 | `amount` | `￥{amount}` |
| 第79行：状态 | 接口4 | `status` | 直接显示 |

### 规则说明弹窗（第86-96行）

| 显示位置 | 数据来源 | 字段名 |
|---------|---------|--------|
| 第89-93行：规则正文 | 接口2 | `content` |

---

## 🔄 接口调用建议

### 1. 接口定义位置

建议在 `common/server/interface/user.js` 中添加：

```javascript
/**
 * 获取收益统计信息
 * @returns {Promise<{pendingAmount: number, extractedAmount: number}>}
 */
export const getEarningsSummary = async () => {
    const res = await request.getOrCache("user/GetEarningsSummary", {}, 1);
    if (res.code == 0) {
        return res.data;
    }
    return { pendingAmount: 0, extractedAmount: 0 };
}

/**
 * 获取收益规则说明
 * @returns {Promise<string>}
 */
export const getEarningsRule = async () => {
    const res = await request.getOrCache("user/GetEarningsRule", {}, 300);
    if (res.code == 0) {
        return res.data.content;
    }
    return '';
}

/**
 * 获取收益记录列表
 * @param {number} pageIndex 页码
 * @param {number} pageSize 每页数量
 * @returns {Promise<EarningsRecordItem[]>}
 */
export const getEarningsRecordList = async (pageIndex = 1, pageSize = 20) => {
    const res = await request.getOrCache(
        "user/GetEarningsRecordList", 
        { pageIndex, pageSize }, 
        1
    );
    if (res.code == 0) {
        return res.data;
    }
    return [];
}

/**
 * 获取提现记录列表
 * @param {number} pageIndex 页码
 * @param {number} pageSize 每页数量
 * @returns {Promise<WithdrawRecordItem[]>}
 */
export const getWithdrawRecordList = async (pageIndex = 1, pageSize = 20) => {
    const res = await request.getOrCache(
        "user/GetWithdrawRecordList", 
        { pageIndex, pageSize }, 
        1
    );
    if (res.code == 0) {
        return res.data;
    }
    return [];
}

/**
 * 申请提现
 * @param {number} amount 提现金额
 * @returns {Promise<boolean>}
 */
export const applyWithdraw = async (amount) => {
    const res = await request.post("user/ApplyWithdraw", { amount });
    if (res.code == 0) {
        return true;
    }
    return false;
}
```

### 2. 页面调用示例

```javascript
import { 
    getEarningsSummary, 
    getEarningsRule, 
    getEarningsRecordList, 
    getWithdrawRecordList,
    applyWithdraw 
} from '@/common/server/interface/user.js'

export default {
    data() {
        return {
            currentIndex: 0,
            show: false,
            reflectShow: false,
            dataList: [],
            value: '',
            pendingAmount: 0.00,
            extractedAmount: 0.00,
            maxWithdrawAmount: 0.00,
            ruleContent: ''
        }
    },
    onLoad() {
        this.loadEarningsSummary();
        this.loadRuleContent();
        this.loadDataList();
    },
    methods: {
        // 加载收益统计
        async loadEarningsSummary() {
            const data = await getEarningsSummary();
            if (data) {
                this.pendingAmount = data.pendingAmount || 0.00;
                this.extractedAmount = data.extractedAmount || 0.00;
                this.maxWithdrawAmount = data.pendingAmount || 0.00;
            }
        },
        
        // 加载规则内容
        async loadRuleContent() {
            this.ruleContent = await getEarningsRule();
        },
        
        // 加载列表数据
        async loadDataList() {
            if (this.currentIndex === 0) {
                // 收益记录
                this.dataList = await getEarningsRecordList(1, 20);
            } else {
                // 提现记录
                this.dataList = await getWithdrawRecordList(1, 20);
            }
        },
        
        // 切换标签
        clickTab(index) {
            this.currentIndex = index;
            this.loadDataList();
        },
        
        // 打开提现弹窗
        openWithdrawPopup() {
            this.reflectShow = true;
            this.loadEarningsSummary(); // 刷新最高可提现金额
        },
        
        // 申请提现
        async submitWithdraw() {
            const amount = parseFloat(this.value);
            if (!amount || amount <= 0) {
                uni.showToast({
                    title: '请输入正确的提现金额',
                    icon: 'none'
                });
                return;
            }
            
            if (amount > this.maxWithdrawAmount) {
                uni.showToast({
                    title: '提现金额不能超过待提取收益',
                    icon: 'none'
                });
                return;
            }
            
            const success = await applyWithdraw(amount);
            if (success) {
                uni.showToast({
                    title: '提现申请已提交',
                    icon: 'success'
                });
                this.reflectShow = false;
                this.value = '';
                // 刷新数据
                this.loadEarningsSummary();
                if (this.currentIndex === 1) {
                    this.loadDataList();
                }
            } else {
                uni.showToast({
                    title: '提现申请失败',
                    icon: 'none'
                });
            }
        },
        
        // 全部提现
        allWithdraw() {
            this.value = this.maxWithdrawAmount.toFixed(2);
        }
    }
}
```

---

## ✅ 必填字段总结

### 接口1：获取收益统计
- `pendingAmount` (number) - 待提取收益
- `extractedAmount` (number) - 已提取收益

### 接口2：获取收益规则
- `content` (string) - 规则说明正文

### 接口3：获取收益记录列表
- `id` (number) - 记录ID
- `date` (string) - 时间
- `roomNumber` (string) - 房号
- `roomName` (string) - 房名
- `roomFee` (number) - 房费
- `earnings` (number) - 收益

### 接口4：获取提现记录列表
- `id` (number) - 记录ID
- `date` (string) - 时间
- `amount` (number) - 提现金额
- `status` (string) - 状态

### 接口5：申请提现
- 请求参数：`amount` (number) - 提现金额

---

## 📌 注意事项

1. **金额格式**：所有金额字段建议使用 `number` 类型，保留2位小数
2. **时间格式**：建议后端返回格式化的时间字符串（如：`2025/1/1` 或 `2025-01-01`）
3. **分页支持**：收益记录和提现记录建议支持分页加载
4. **空数据处理**：当没有记录时，返回空数组 `[]`
5. **错误处理**：接口失败时返回 `code != 0`，前端需要处理错误情况
6. **提现金额验证**：
   - 前端需要验证：不能超过 `pendingAmount`
   - 后端需要验证：最低提现金额、余额是否充足等
7. **状态显示**：提现状态建议使用中文显示（提现中/已到账/已拒绝）

---

## 🔍 后续扩展建议

如果后续需要添加以下功能，可以考虑增加字段：

- **收益详情**：点击收益记录查看详情，需要 `reservationId` 字段
- **提现详情**：点击提现记录查看详情，需要 `remark` 字段
- **提现方式**：如果支持多种提现方式，需要增加提现方式字段
- **收益统计图表**：如果需要图表展示，可以增加按时间段的统计数据