282 lines
8.5 KiB
Markdown
282 lines
8.5 KiB
Markdown
# 我的收益页面 - 开发任务清单
|
||
|
||
## 📌 需求概述
|
||
|
||
实现"我的收益"功能，包含以下核心功能：
|
||
1. 收益统计展示（待提现、已提现）
|
||
2. 收益记录列表
|
||
3. 提现申请与记录
|
||
4. 收益规则说明
|
||
5. 后台赴约审核功能
|
||
|
||
---
|
||
|
||
## 📊 收益来源说明
|
||
|
||
| 类型 | 来源 | 获得者 | 触发方式 |
|
||
|------|------|--------|----------|
|
||
| 佣金 | 房费10% | 发起者 | 后台员工手动添加 |
|
||
| 鸽子费 | 参与者押金 | 已赴约的参与者 | 后台审核通过后自动发放 |
|
||
|
||
---
|
||
|
||
## 🗃️ 数据库修改
|
||
|
||
### 1. 修改用户表 `CoreCmsUser`
|
||
|
||
**文件**：`CoreCms.Net.Model\Entities\User\CoreCmsUser.cs`
|
||
|
||
新增字段：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `pending_earnings` | decimal(18,2) | 待提现收益 |
|
||
| `withdrawn_earnings` | decimal(18,2) | 已提现收益（历史累计） |
|
||
|
||
```csharp
|
||
/// <summary>
|
||
/// 待提现收益
|
||
/// </summary>
|
||
[Display(Name = "待提现收益")]
|
||
[SugarColumn(ColumnDescription = "待提现收益")]
|
||
public System.Decimal pending_earnings { get; set; }
|
||
|
||
/// <summary>
|
||
/// 已提现收益（历史累计）
|
||
/// </summary>
|
||
[Display(Name = "已提现收益")]
|
||
[SugarColumn(ColumnDescription = "已提现收益")]
|
||
public System.Decimal withdrawn_earnings { get; set; }
|
||
```
|
||
|
||
### 2. 新增收益记录表 `SQEarningsRecord`
|
||
|
||
**文件**：`CoreCms.Net.Model\Entities\SQ\SQEarningsRecord.cs`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `id` | int | 主键，自增 |
|
||
| `user_id` | int | 用户ID |
|
||
| `reservation_id` | int | 预约ID（可为空，手动添加时） |
|
||
| `room_id` | int | 房间ID（可为空） |
|
||
| `room_number` | string | 房号 |
|
||
| `room_name` | string | 房名 |
|
||
| `room_fee` | decimal | 房费 |
|
||
| `earnings` | decimal | 收益金额 |
|
||
| `type` | int | 类型：1=佣金，2=鸽子费 |
|
||
| `remark` | string | 备注 |
|
||
| `create_time` | datetime | 创建时间 |
|
||
| `operator_id` | int | 操作员ID（后台添加时） |
|
||
|
||
### 3. 新增提现记录表 `SQWithdrawRecord`
|
||
|
||
**文件**：`CoreCms.Net.Model\Entities\SQ\SQWithdrawRecord.cs`
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `id` | int | 主键，自增 |
|
||
| `user_id` | int | 用户ID |
|
||
| `amount` | decimal | 提现金额 |
|
||
| `status` | int | 状态：0=提现中，1=已到账，2=已拒绝/取消 |
|
||
| `apply_time` | datetime | 申请时间 |
|
||
| `process_time` | datetime | 处理时间（可为空） |
|
||
| `operator_id` | int | 处理人ID（可为空） |
|
||
| `remark` | string | 备注（拒绝原因等） |
|
||
|
||
---
|
||
|
||
## 🔧 后端开发任务
|
||
|
||
### 1. 实体层 `CoreCms.Net.Model`
|
||
|
||
- [ ] 修改 `CoreCmsUser.cs`：新增 `pending_earnings`、`withdrawn_earnings` 字段
|
||
- [ ] 新建 `SQEarningsRecord.cs`：收益记录实体
|
||
- [ ] 新建 `SQWithdrawRecord.cs`：提现记录实体
|
||
|
||
### 2. 仓储层 `CoreCms.Net.Repository`
|
||
|
||
- [ ] 新建 `ISQEarningsRecordRepository.cs`
|
||
- [ ] 新建 `SQEarningsRecordRepository.cs`
|
||
- [ ] 新建 `ISQWithdrawRecordRepository.cs`
|
||
- [ ] 新建 `SQWithdrawRecordRepository.cs`
|
||
|
||
### 3. 服务层 `CoreCms.Net.Services`
|
||
|
||
- [ ] 新建 `ISQEarningsServices.cs`
|
||
- [ ] 新建 `SQEarningsServices.cs`
|
||
|
||
服务方法：
|
||
```csharp
|
||
// 获取收益统计
|
||
Task<(decimal pendingAmount, decimal extractedAmount)> GetEarningsSummary(int userId);
|
||
|
||
// 获取收益记录列表
|
||
Task<List<EarningsRecordDto>> GetEarningsRecordList(int userId, int pageIndex, int pageSize);
|
||
|
||
// 获取提现记录列表
|
||
Task<List<WithdrawRecordDto>> GetWithdrawRecordList(int userId, int pageIndex, int pageSize);
|
||
|
||
// 申请提现
|
||
Task<WebApiCallBack> ApplyWithdraw(int userId, decimal amount);
|
||
|
||
// 添加收益（后台调用）
|
||
Task<WebApiCallBack> AddEarnings(int userId, int reservationId, decimal roomFee, decimal earnings, int type, string remark, int operatorId);
|
||
|
||
// 发放鸽子费收益（审核通过后调用）
|
||
Task<WebApiCallBack> DistributePigeonFee(int reservationId, int operatorId);
|
||
```
|
||
|
||
### 4. 前端API `CoreCms.Net.Web.WebApi`
|
||
|
||
**文件**：`SQController.cs` 或新建 `UserEarningsController.cs`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/SQ/GetEarningsSummary` | GET | 获取收益统计 |
|
||
| `/api/SQ/GetEarningsRule` | GET | 获取收益规则说明 |
|
||
| `/api/SQ/GetEarningsRecordList` | POST | 获取收益记录列表 |
|
||
| `/api/SQ/GetWithdrawRecordList` | POST | 获取提现记录列表 |
|
||
| `/api/SQ/ApplyWithdraw` | POST | 申请提现 |
|
||
|
||
### 5. 后台管理 `CoreCms.Net.Web.Admin`
|
||
|
||
#### 5.1 收益管理
|
||
|
||
- [ ] 新建 `SQEarningsController.cs`：收益管理控制器
|
||
- [ ] 新建 `wwwroot/views/sq/sqearnings/index.html`：收益记录列表页
|
||
- [ ] 新建 `wwwroot/views/sq/sqearnings/add.html`：手动添加收益页
|
||
|
||
功能点：
|
||
- 查看所有用户的收益记录
|
||
- 手动为用户添加佣金（发起者）
|
||
- 筛选：用户、时间、类型
|
||
|
||
#### 5.2 提现管理
|
||
|
||
- [ ] 新建 `SQWithdrawController.cs`：提现管理控制器
|
||
- [ ] 新建 `wwwroot/views/sq/sqwithdraw/index.html`：提现申请列表页
|
||
|
||
功能点：
|
||
- 查看所有提现申请
|
||
- 同意/拒绝申请
|
||
- 标记已打款
|
||
- 筛选：状态、用户、时间
|
||
|
||
#### 5.3 赴约审核功能 ⚠️ 缺失
|
||
|
||
**文件**：修改 `SQReservationsController.cs` 或新建独立控制器
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 查看待审核列表 | `is_arrive = 2` 的参与者记录 |
|
||
| 审核通过 | 将 `is_arrive` 改为 `3`，扣除鸽子费，发放给已赴约者 |
|
||
| 审核拒绝 | 将 `is_arrive` 改回其他状态，退还押金 |
|
||
|
||
---
|
||
|
||
## 📝 配置项
|
||
|
||
### 收益规则说明
|
||
|
||
需要在系统配置中新增一项配置：
|
||
|
||
| 配置Key | 说明 |
|
||
|---------|------|
|
||
| `earnings_rule_content` | 收益规则说明内容（富文本） |
|
||
|
||
可使用现有的 `CoreCmsSetting` 表存储。
|
||
|
||
---
|
||
|
||
## 🔄 业务流程
|
||
|
||
### 流程1：手动添加佣金
|
||
```
|
||
后台员工 → 选择用户 → 输入房间信息和房费 → 系统计算佣金(10%) → 保存收益记录 → 更新用户待提现收益
|
||
```
|
||
|
||
### 流程2：鸽子费发放
|
||
```
|
||
预约完成 → 发起者标记参与者未赴约(is_arrive=2) → 后台审核(is_arrive=3) →
|
||
扣除未赴约者押金(不退) → 按比例发放给已赴约者 → 保存收益记录 → 更新用户待提现收益
|
||
```
|
||
|
||
### 流程3：用户提现
|
||
```
|
||
用户申请提现 → 生成提现记录(status=0) → 扣减待提现收益 →
|
||
后台审核 → 线下打款 → 标记已到账(status=1) → 增加已提现收益
|
||
```
|
||
|
||
### 流程4：提现拒绝
|
||
```
|
||
用户申请提现 → 生成提现记录(status=0) → 扣减待提现收益 →
|
||
后台拒绝(status=2) → 退还待提现收益
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 开发优先级
|
||
|
||
| 优先级 | 任务 | 预估工时 |
|
||
|--------|------|----------|
|
||
| P0 | 数据库表结构（实体创建） | 1h |
|
||
| P0 | 仓储层和服务层基础代码 | 2h |
|
||
| P1 | 前端API（5个接口） | 3h |
|
||
| P1 | 后台-提现管理 | 3h |
|
||
| P1 | 后台-收益管理（手动添加） | 2h |
|
||
| P2 | 后台-赴约审核功能 | 3h |
|
||
| P2 | 鸽子费自动发放逻辑 | 2h |
|
||
|
||
---
|
||
|
||
## 📌 注意事项
|
||
|
||
1. **金额精度**：所有金额使用 `decimal(18,2)`，保留两位小数
|
||
2. **并发控制**：提现时需要加锁，防止重复提现
|
||
3. **数据一致性**：收益增减需要同时更新收益记录表和用户表
|
||
4. **审计日志**：后台操作需要记录操作员ID和时间
|
||
5. **事务处理**：涉及多表更新的操作需要使用事务
|
||
|
||
---
|
||
|
||
## 🗄️ SQL脚本（参考）
|
||
|
||
```sql
|
||
-- 修改用户表
|
||
ALTER TABLE CoreCmsUser ADD pending_earnings decimal(18,2) NOT NULL DEFAULT 0;
|
||
ALTER TABLE CoreCmsUser ADD withdrawn_earnings decimal(18,2) NOT NULL DEFAULT 0;
|
||
|
||
-- 创建收益记录表
|
||
CREATE TABLE SQEarningsRecord (
|
||
id INT IDENTITY(1,1) PRIMARY KEY,
|
||
user_id INT NOT NULL,
|
||
reservation_id INT NULL,
|
||
room_id INT NULL,
|
||
room_number NVARCHAR(50) NULL,
|
||
room_name NVARCHAR(100) NULL,
|
||
room_fee DECIMAL(18,2) NOT NULL DEFAULT 0,
|
||
earnings DECIMAL(18,2) NOT NULL DEFAULT 0,
|
||
type INT NOT NULL DEFAULT 1, -- 1=佣金，2=鸽子费
|
||
remark NVARCHAR(500) NULL,
|
||
create_time DATETIME NOT NULL DEFAULT GETDATE(),
|
||
operator_id INT NULL
|
||
);
|
||
|
||
-- 创建提现记录表
|
||
CREATE TABLE SQWithdrawRecord (
|
||
id INT IDENTITY(1,1) PRIMARY KEY,
|
||
user_id INT NOT NULL,
|
||
amount DECIMAL(18,2) NOT NULL,
|
||
status INT NOT NULL DEFAULT 0, -- 0=提现中，1=已到账，2=已拒绝
|
||
apply_time DATETIME NOT NULL DEFAULT GETDATE(),
|
||
process_time DATETIME NULL,
|
||
operator_id INT NULL,
|
||
remark NVARCHAR(500) NULL
|
||
);
|
||
|
||
-- 创建索引
|
||
CREATE INDEX IX_SQEarningsRecord_UserId ON SQEarningsRecord(user_id);
|
||
CREATE INDEX IX_SQWithdrawRecord_UserId ON SQWithdrawRecord(user_id);
|
||
CREATE INDEX IX_SQWithdrawRecord_Status ON SQWithdrawRecord(status);
|
||
```
|