# 财务系统数据库设计文档

> **最后更新**: 2024-01-XX - 账户体系重构完成  
> **版本**: v2.0

## 概述

本文档描述了租房平台财务系统的数据库设计，包括账户体系、资金流转和数据一致性保障机制。

## 数据库表与 Entity 映射关系

| 数据库表 | Entity 文件 | 说明 | 状态 |
|---------|------------|------|------|
| `system_accounts` | `system-account.entity.ts` | 系统总账户表 | ✅ v2.0 新增 |
| `system_transactions` | `system-transaction.entity.ts` | 系统总账户交易流水表 | ✅ v2.0 新增 |
| `platform_accounts` | `platform-account.entity.ts` | 平台账户表 | ✅ v2.0 重构 |
| `platform_transactions` | `platform-transaction.entity.ts` | 平台交易流水表 | ✅ 已完成 |
| `merchant_accounts` | `merchant-account.entity.ts` | 商家账户表 | ✅ 已完成 |
| `merchant_transactions` | `merchant-transaction.entity.ts` | 商家交易流水表 | ✅ 已完成 |
| `user_accounts` | `user-account.entity.ts` | 用户账户表 | ✅ 已完成 |
| `user_transactions` | `user-transaction.entity.ts` | 用户交易流水表 | ✅ 已完成 |
| `user_withdrawals` | `user-withdrawal.entity.ts` | 用户提现表 | ✅ 已完成 |
| `merchant_withdrawals` | `merchant-withdrawal.entity.ts` | 商家提现表 | ✅ 已完成 |
| `settlements` | `settlement.entity.ts` | 结算单表 | ✅ 已完成 |
| `settlement_items` | `settlement-item.entity.ts` | 结算明细表 | ✅ 已完成 |

## 账户体系设计

### 四层账户结构

系统采用四层账户结构，确保资金流转清晰、职责明确：

#### 1. 系统总账户 (System Account) - v2.0 新增

**职责**: 记录平台内所有未提现的资金总额

**计算公式**:
```
系统总账户余额 = 用户实付总额 - 累计退款 - 累计提现
```

**字段说明**:
- `balance`: 当前余额
- `total_income`: 累计收入（用户实付总额）
- `total_refund`: 累计退款
- `total_withdrawn`: 累计提现

#### 2. 平台账户 (Platform Account) - v2.0 重构

**职责**: 记录平台净收益（服务费收入 - 邀请返现支出）

**计算公式**:
```
平台账户余额 = 累计服务费收入 - 累计邀请返现支出
```

**字段说明**:
- `balance`: 当前余额
- `total_income`: 累计收入（服务费收入）
- `total_expense`: 累计支出（邀请返现支出）

**v2.0 变更**:
- ❌ 删除字段: `total_order_income`, `total_service_fee`, `total_cashback`, `total_settlement`
- ✅ 字段含义变更: `total_income` 从"订单收入"改为"服务费收入"
- ✅ 字段含义变更: `total_expense` 从"所有支出"改为"邀请返现支出"

#### 3. 商家账户 (Merchant Account)

**职责**: 记录商家的订单收入和提现

**计算公式**:
```
商家账户余额 = 累计订单收入 - 累计提现
订单收入 = 订单金额 - 服务费
```

#### 4. 用户账户 (User Account)

**职责**: 记录用户的邀请返现收入和提现

**计算公式**:
```
用户账户余额 = 累计邀请返现 - 累计提现
```

### 资金守恒验证

系统通过以下公式验证资金守恒：

```
系统总账户余额 = 商家账户余额总和 + 用户账户余额总和 + 平台账户余额
```

这个公式确保平台内所有资金都有明确的归属，不会出现资金丢失或凭空产生的情况。

## 数据表结构详解

### system_accounts（系统总账户表）- v2.0 新增

```sql
CREATE TABLE IF NOT EXISTS `system_accounts` (
  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `account_name` VARCHAR(50) NOT NULL COMMENT '账户名称',
  `balance` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '可用余额',
  `total_income` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '累计收入（用户实付总额）',
  `total_refund` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '累计退款',
  `total_withdrawn` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '累计提现',
  `version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_account_name` (`account_name`)
) COMMENT='系统总账户表';
```

**关键点**:
- 记录平台内所有未提现的资金
- `balance` = `total_income` - `total_refund` - `total_withdrawn`
- 用于验证资金守恒

### system_transactions（系统总账户交易流水表）- v2.0 新增

```sql
CREATE TABLE IF NOT EXISTS `system_transactions` (
  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `transaction_no` VARCHAR(64) NOT NULL COMMENT '交易流水号',
  `account_id` BIGINT UNSIGNED NOT NULL COMMENT '账户ID',
  `direction` ENUM('income','expense') NOT NULL COMMENT '交易方向',
  `amount` DECIMAL(12,2) NOT NULL COMMENT '交易金额',
  `balance_before` DECIMAL(12,2) NOT NULL COMMENT '交易前余额',
  `balance_after` DECIMAL(12,2) NOT NULL COMMENT '交易后余额',
  `transaction_type` VARCHAR(50) NOT NULL COMMENT '交易类型',
  `business_type` VARCHAR(50) NOT NULL COMMENT '业务类型',
  `business_id` BIGINT UNSIGNED NOT NULL COMMENT '业务ID',
  `business_no` VARCHAR(64) NOT NULL COMMENT '业务单号',
  `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_transaction_no` (`transaction_no`),
  KEY `idx_account_id` (`account_id`),
  KEY `idx_business` (`business_type`, `business_id`),
  KEY `idx_created_at` (`created_at`)
) COMMENT='系统总账户交易流水表';
```

**交易类型**:
- `用户支付`: 用户支付订单（income）
- `订单退款`: 订单退款（expense）
- `用户提现`: 用户提现（expense）
- `商家提现`: 商家提现（expense）

### platform_accounts（平台账户表）- v2.0 重构

```sql
CREATE TABLE IF NOT EXISTS `platform_accounts` (
  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `account_name` VARCHAR(50) NOT NULL COMMENT '账户名称',
  `balance` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '可用余额',
  `total_income` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '累计收入（服务费收入）',
  `total_expense` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '累计支出（邀请返现支出）',
  `version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_account_name` (`account_name`)
) COMMENT='平台账户表';
```

**v2.0 变更**:
- `total_income` 含义变更: 从"订单收入"改为"服务费收入"
- `total_expense` 含义变更: 从"所有支出"改为"邀请返现支出"
- 删除冗余字段: `total_order_income`, `total_service_fee`, `total_cashback`, `total_settlement`

### user_accounts（用户账户表）

```sql
CREATE TABLE `user_accounts` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `user_id` BIGINT UNSIGNED,                          -- 用户ID
  `balance` DECIMAL(12,2) DEFAULT 0.00,               -- 可用余额
  `frozen_balance` DECIMAL(12,2) DEFAULT 0.00,        -- 冻结余额（提现中）
  `total_income` DECIMAL(12,2) DEFAULT 0.00,          -- 累计收入（邀请返现）
  `total_expense` DECIMAL(12,2) DEFAULT 0.00,         -- 累计支出（提现）
  `version` INT UNSIGNED DEFAULT 0,                   -- 乐观锁版本号
  `status` ENUM('active','frozen','closed'),          -- 状态
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_id` (`user_id`)
);
```

**关键点**:
- 用户账户主要用于邀请返现
- `balance` = `total_income` - `total_expense`
- 提现时先冻结余额，打款后扣减

### merchant_accounts（商家账户表）

```sql
CREATE TABLE `merchant_accounts` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `merchant_id` BIGINT UNSIGNED,                      -- 商家ID
  `balance` DECIMAL(12,2) DEFAULT 0.00,               -- 可用余额
  `frozen_balance` DECIMAL(12,2) DEFAULT 0.00,        -- 冻结余额（提现中）
  `debt_amount` DECIMAL(12,2) DEFAULT 0.00,           -- 欠款金额（退款扣回）
  `total_income` DECIMAL(12,2) DEFAULT 0.00,          -- 累计收入（订单结算）
  `total_expense` DECIMAL(12,2) DEFAULT 0.00,         -- 累计支出（提现+退款扣回）
  `total_settlement` DECIMAL(12,2) DEFAULT 0.00,      -- 累计结算金额
  `total_withdraw` DECIMAL(12,2) DEFAULT 0.00,        -- 累计提现金额
  `last_settlement_at` DATETIME,                      -- 最后结算时间
  `pending_settlement` DECIMAL(12,2) DEFAULT 0.00,    -- 待结算金额
  `version` INT UNSIGNED DEFAULT 0,                   -- 乐观锁版本号
  `status` ENUM('active','frozen','closed'),          -- 状态
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_merchant_id` (`merchant_id`)
);
```

**关键点**:
- 商家账户记录订单结算收入
- 结算金额 = 订单金额 - 服务费
- 每周一凌晨2点自动执行周结算

## 资金流转流程

### 1. 订单支付流程 - v2.0 更新

```
用户支付订单
  ↓
系统总账户 +实付金额 (income)
  ↓
订单状态：pending_pay → pending_confirm
```

**涉及表**:
- `system_accounts`: balance += 实付金额, total_income += 实付金额
- `system_transactions`: 插入交易流水（income）

**代码位置**: `apps/server/src/modules/app/order/order.service.ts`

### 2. 订单结算流程 - v2.0 更新

```
订单完成（用户离店）
  ↓
商家账户 +（实付金额 - 服务费）
  ↓
平台账户 +服务费
  ↓
如果有邀请关系：
  用户账户（邀请人）+返现金额
  平台账户 -返现金额
```

**涉及表**:
- `merchant_accounts`: balance += 结算金额
- `merchant_transactions`: 插入交易流水
- `platform_accounts`: balance += 服务费, total_income += 服务费
- `platform_transactions`: 插入交易流水
- `user_accounts`: balance += 返现金额（如有邀请）
- `user_transactions`: 插入交易流水（如有邀请）
- `platform_accounts`: balance -= 返现金额, total_expense += 返现金额（如有邀请）
- `settlements`: 插入结算单记录
- `settlement_items`: 插入结算明细

**代码位置**: 
- `apps/server/src/modules/shared/finance/settlement.service.ts`
- `apps/server/src/modules/app/activity/activity.service.ts`

### 3. 订单退款流程 - v2.0 更新

```
用户申请退款
  ↓
调用第三方支付退款API
  ↓
系统总账户 +退款金额 (expense)
  ↓
订单状态：pending_confirm/pending_checkin → refunded
```

**涉及表**:
- `system_accounts`: balance -= 退款金额, total_refund += 退款金额
- `system_transactions`: 插入交易流水（expense）

**代码位置**: `apps/server/src/modules/shared/finance/refund.service.ts`

### 4. 提现流程 - v2.0 更新

#### 用户提现

```
用户申请提现
  ↓
用户账户：balance → frozen_balance
  ↓
管理员审核通过
  ↓
管理员确认打款
  ↓
用户账户 -提现金额（从frozen_balance扣减）
系统总账户 +提现金额 (expense)
  ↓
提现状态：pending → approved → paid
```

#### 商家提现

```
商家申请提现
  ↓
商家账户：balance → frozen_balance
  ↓
管理员审核通过
  ↓
管理员确认打款
  ↓
商家账户 -提现金额（从frozen_balance扣减）
系统总账户 +提现金额 (expense)
  ↓
提现状态：pending → approved → paid
```

**涉及表**:
- `user_accounts` / `merchant_accounts`: frozen_balance → balance扣减
- `user_transactions` / `merchant_transactions`: 插入交易流水
- `system_accounts`: balance -= 提现金额, total_withdrawn += 提现金额
- `system_transactions`: 插入交易流水
- `user_withdrawals` / `merchant_withdrawals`: 更新提现状态

**代码位置**: `apps/server/src/modules/shared/finance/withdrawal.service.ts`

### platform_accounts（平台账户表）

```sql
CREATE TABLE `platform_accounts` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `account_name` VARCHAR(50),                         -- 账户名称
  `balance` DECIMAL(12,2) DEFAULT 0.00,               -- 可用余额
  `frozen_balance` DECIMAL(12,2) DEFAULT 0.00,        -- 冻结余额
  `total_income` DECIMAL(12,2) DEFAULT 0.00,          -- 累计收入（订单收入）
  `total_expense` DECIMAL(12,2) DEFAULT 0.00,         -- 累计支出（商家结算+退款）
  `total_service_fee` DECIMAL(12,2) DEFAULT 0.00,     -- 累计服务费收入
  `version` INT UNSIGNED DEFAULT 0,                   -- 乐观锁版本号
  `status` ENUM('active','frozen','closed'),          -- 状态
  PRIMARY KEY (`id`)
);
```

**关键点**:
- 账户按角色分离：用户、商家、平台各有独立的账户表
- 每个账户表都有 `version` 字段用于乐观锁，防止并发问题
- `balance` 和 `frozen_balance` 有 CHECK 约束，不能为负数

### user_transactions / merchant_transactions / platform_transactions（交易流水表）

交易流水表也按角色分离，结构类似：

```sql
CREATE TABLE `user_transactions` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `transaction_no` VARCHAR(32) UNIQUE,                -- 交易流水号（全局唯一）
  `user_id` BIGINT UNSIGNED,                          -- 用户ID
  `account_id` BIGINT UNSIGNED,                       -- 用户账户ID
  `direction` ENUM('income','expense'),               -- 方向
  `amount` DECIMAL(12,2),                             -- 金额
  `balance_before` DECIMAL(12,2),                     -- 交易前余额
  `balance_after` DECIMAL(12,2),                      -- 交易后余额
  `transaction_type` VARCHAR(50),                     -- 交易类型
  `business_type` VARCHAR(50),                        -- 业务类型
  `business_id` BIGINT UNSIGNED,                      -- 业务ID
  `business_no` VARCHAR(32),                          -- 业务单号
  `related_account_type` ENUM('platform','merchant'), -- 对方账户类型
  `related_account_id` BIGINT UNSIGNED,               -- 对方账户ID
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_transaction_no` (`transaction_no`)
);
```

**关键点**:
- 所有账户操作都记录详细的交易流水
- `transaction_no` 全局唯一，用于追踪资金流向
- 记录交易前后余额，便于对账和审计

### settlements（结算单表）

```sql
CREATE TABLE `settlements` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `settlement_no` VARCHAR(32) UNIQUE,                 -- 结算单号
  `merchant_id` BIGINT UNSIGNED,                      -- 商家ID
  `period_start` DATE,                                -- 周期开始
  `period_end` DATE,                                  -- 周期结束
  `order_count` INT UNSIGNED DEFAULT 0,               -- 订单数量
  `order_amount` DECIMAL(12,2) DEFAULT 0.00,          -- 订单总额
  `service_fee` DECIMAL(12,2) DEFAULT 0.00,           -- 服务费
  `settlement_amount` DECIMAL(12,2) DEFAULT 0.00,     -- 结算金额
  `status` ENUM('pending','settled','failed'),        -- 状态
  `settled_at` DATETIME,                              -- 结算时间
  PRIMARY KEY (`id`)
);
```

**关键点**:
- 每周一凌晨2点自动生成上周的结算单
- `settlement_amount` = `order_amount` - `service_fee`
- 结算时执行转账：给商家账户增加余额，给平台账户增加服务费

## 数据一致性保证

### 1. 事务保证

所有涉及金额变动的操作都在事务中执行：

```typescript
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();

try {
  // 账户操作
  await queryRunner.commitTransaction();
} catch (error) {
  await queryRunner.rollbackTransaction();
  throw error;
} finally {
  await queryRunner.release();
}
```

### 2. 悲观锁

在查询账户时使用悲观锁，防止并发修改：

```typescript
const account = await queryRunner.manager.findOne(SystemAccount, {
  where: { account_name: 'SYSTEM_MAIN' },
  lock: { mode: 'pessimistic_write' },
});
```

### 3. 乐观锁

使用 `version` 字段实现乐观锁，检测并发冲突：

```typescript
account.version += 1;
await queryRunner.manager.save(account);
```

### 4. 金额精度控制

所有金额计算都使用 `Number()` 转换和 `toFixed(2)` 保留两位小数：

```typescript
const amountNum = Number(amount);
const balanceBefore = Number(account.balance);
const balanceAfter = parseFloat((balanceBefore + amountNum).toFixed(2));
```

### 5. 余额校验

在扣减余额前检查余额是否足够：

```typescript
if (balanceBefore < amount) {
  throw new BadRequestException('账户余额不足');
}
```

### 6. CHECK 约束

```sql
CONSTRAINT `chk_balance` CHECK (`balance` >= 0)
CONSTRAINT `chk_frozen_balance` CHECK (`frozen_balance` >= 0)
```

确保余额不会为负数。

### 7. 触发器

- 用户注册时自动创建账户
- 商家审核通过时自动创建账户

## 数据库初始化

### 1. 迁移脚本位置

`database/migrations/001_init_schema.sql` 包含完整的财务系统表结构

### 2. 初始化步骤

```bash
# 1. 执行数据库迁移脚本（会清空所有数据）
mysql -u root -p < database/migrations/001_init_schema.sql

# 2. 初始化系统总账户
mysql -u root -p
USE your_database_name;
INSERT INTO system_accounts (account_name, balance, total_income, total_refund, total_withdrawn, status)
VALUES ('SYSTEM_MAIN', 0.00, 0.00, 0.00, 0.00, 'active');

# 3. 初始化平台账户
INSERT INTO platform_accounts (account_name, balance, frozen_balance, total_income, total_expense, status)
VALUES ('PLATFORM_MAIN', 0.00, 0.00, 0.00, 0.00, 'active');
```

### 3. 自动创建的数据

执行迁移脚本后会自动创建：

1. **触发器**
   - `trg_user_create_account`: 用户注册时自动创建用户账户
   - `trg_merchant_create_account`: 商家审核通过时自动创建商家账户

## 索引说明

### 关键索引

1. **system_accounts 表**
   - `uk_account_name`: 唯一索引，确保账户名称唯一

2. **system_transactions 表**
   - `uk_transaction_no`: 唯一索引，防止重复交易
   - `idx_account_id`: 按账户查询流水
   - `idx_business`: 按业务类型和业务ID查询
   - `idx_created_at`: 按时间范围查询

3. **platform_accounts 表**
   - `uk_account_name`: 唯一索引，确保账户名称唯一

4. **user_accounts / merchant_accounts 表**
   - `uk_user_id` / `uk_merchant_id`: 唯一索引，确保每个用户/商家只有一个账户
   - `idx_status`: 按状态查询

5. **transactions 表**
   - `uk_transaction_no`: 唯一索引，防止重复交易
   - `idx_account_id`: 按账户查询流水
   - `idx_business`: 按业务类型和业务ID查询
   - `idx_created_at`: 按时间范围查询

6. **settlements 表**
   - `uk_settlement_no`: 唯一索引
   - `idx_merchant_id`: 按商家查询
   - `idx_period`: 按周期查询

7. **withdrawals 表**
   - `uk_withdraw_no`: 唯一索引
   - `idx_status`: 按状态查询（待审核、已打款等）

## 版本更新记录

### v2.0 (2024-01-XX) - 账户体系重构

**重大变更**:
1. ✅ 新增 `system_accounts` 表 - 记录系统总资金
2. ✅ 新增 `system_transactions` 表 - 系统总账户交易流水
3. ✅ 重构 `platform_accounts` 表 - 只记录平台净收益
   - 字段含义变更: `total_income` 改为"服务费收入"
   - 字段含义变更: `total_expense` 改为"邀请返现支出"
   - 删除冗余字段: `total_order_income`, `total_service_fee`, `total_cashback`, `total_settlement`
4. ✅ 修改订单支付逻辑 - 更新系统总账户
5. ✅ 修改订单结算逻辑 - 同时更新商家账户和平台账户
6. ✅ 修改邀请返现逻辑 - 从平台账户扣减
7. ✅ 修改退款逻辑 - 更新系统总账户
8. ✅ 修改提现逻辑 - 更新系统总账户

**资金守恒验证**:
```
系统总账户余额 = 商家账户余额总和 + 用户账户余额总和 + 平台账户余额
```

**升级步骤**:
1. 备份现有数据库
2. 执行新的数据库迁移脚本
3. 初始化系统总账户和平台账户
4. 更新后端代码
5. 重启服务
6. 验证资金守恒

### v1.0 (2024-04-24) - 初始版本

**功能**:
- 用户账户、商家账户、平台账户
- 交易流水记录
- 周结算功能
- 提现功能
- 日对账功能

## 相关文档

- [财务系统完整设计文档](../finance-system.md) - 包含业务流程、核心服务、前端展示等完整内容
- [项目需求文档](../requirements/项目需求文档.md) - 了解项目功能和业务逻辑
- [开发总结](../DEVELOPMENT_SUMMARY.md) - 查看项目完成情况

## 注意事项

1. **执行迁移脚本**: 确保按顺序执行 `001_init_schema.sql`，会自动创建所有表和触发器。

2. **初始化账户**: 迁移脚本执行后需要手动初始化系统总账户和平台账户。

3. **定时任务**: 需要在 NestJS 中启用 `@nestjs/schedule` 模块，定时任务才会执行。

4. **资金安全**: 所有账户操作都使用事务、悲观锁和乐观锁保证数据一致性。

5. **金额精度**: 所有金额计算使用 `Number()` 和 `toFixed(2)` 确保精度。

---

**维护团队**: 开发团队  
**最后更新**: 2024-01-XX