outsource/mahjong_group

Fork 0

zpc 63aedaf041 调整文件结构

2026-01-01 14:39:23 +08:00

15 KiB

Raw Blame History

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

📋 页面功能概述

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

主要功能：

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

🔌 接口需求清单

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

基本信息

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

请求参数

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

返回数据结构

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

返回示例

{
  "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行）
是否需要登录：否（可公开）

请求参数

无需参数

返回数据结构

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

返回示例

{
  "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

返回数据结构

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（可选）
}

返回示例

{
  "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

返回数据结构

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;         // 备注（可选）
}

返回示例

{
  "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

返回数据结构

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

返回示例

// 成功
{
  "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 中添加：

/**
 * 获取收益统计信息
 * @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. 页面调用示例

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) - 提现金额

📌 注意事项

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

🔍 后续扩展建议

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

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

15 KiB Raw Blame History Unescape Escape

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

📋 页面功能概述

🔌 接口需求清单

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

基本信息

请求参数

返回数据结构

返回示例

页面映射

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

基本信息

请求参数

返回数据结构

返回示例

页面映射

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

基本信息

请求参数

返回数据结构

返回示例

页面映射

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

基本信息

请求参数

返回数据结构

返回示例

页面映射

接口5：申请提现

基本信息

请求参数

返回数据结构

返回示例

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

基本信息

说明

📝 页面数据映射总览

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

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

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

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

🔄 接口调用建议

1. 接口定义位置

2. 页面调用示例

✅ 必填字段总结

接口1：获取收益统计

接口2：获取收益规则

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

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

接口5：申请提现

📌 注意事项

🔍 后续扩展建议

15 KiB

Raw Blame History