outsource/mahjong_group

Fork 0

zpc 316d1e2b5d 231

2025-12-08 00:23:20 +08:00

15 KiB

Raw Blame History

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

📋 页面功能概述

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

主要功能：

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

🔌 接口需求清单

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

基本信息

接口路径：建议 GET /api/sq/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
调用时机：
- 点击"点击查看收益规则"时（第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：获取收益记录列表

基本信息

接口路径： POST /api/sq/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：获取提现记录列表

基本信息

接口路径：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/sq/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元"
}

📝 页面数据映射总览

收益统计卡片（第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/earnings.js 中添加：

/**
 * 获取收益统计信息
 * @returns {Promise<{pendingAmount: number, extractedAmount: number}>}
 */
export const getEarningsSummary = async () => {
    const res = await request.getOrCache("sq/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("sq/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(
        "sq/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(
        "sq/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("sq/ApplyWithdraw", { amount });
    if (res.code == 0) {
        return true;
    }
    return false;
}

2. 页面调用示例

import { 
    getEarningsSummary, 
    getEarningsRule, 
    getEarningsRecordList, 
    getWithdrawRecordList,
    applyWithdraw 
} from '@/common/server/interface/earnings.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：申请提现

基本信息

请求参数

返回数据结构

返回示例

📝 页面数据映射总览

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

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

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

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

🔄 接口调用建议

1. 接口定义位置

2. 页面调用示例

✅ 必填字段总结

接口1：获取收益统计

接口2：获取收益规则

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

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

接口5：申请提现

📌 注意事项

🔍 后续扩展建议

15 KiB

Raw Blame History