609 lines
15 KiB
Markdown
609 lines
15 KiB
Markdown
# 我的收益页面接口参数说明
|
||
|
||
## 📋 页面功能概述
|
||
|
||
**页面路径**：`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` 字段
|
||
- **提现方式**：如果支持多种提现方式，需要增加提现方式字段
|
||
- **收益统计图表**：如果需要图表展示，可以增加按时间段的统计数据
|
||
|