mahjong_group/docs/1.0.0/我的收益开发任务清单.md

我的收益页面 - 开发任务清单

📌 需求概述

实现"我的收益"功能，包含以下核心功能：

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)	已提现收益（历史累计）

/// <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

服务方法：

// 获取收益统计
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脚本（参考）

-- 修改用户表
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);