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

## 📌 需求概述

实现"我的收益"功能，包含以下核心功能：
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);
```