---
name: WalletUserStat Model
overview: 为 rh_wallet.wallet_user_stat 新增继承 think\Model 的 WalletUserStatModel；通过 mysql 连接 + 库名.表名 的 $table 绑定跨库表；提供 inc/version 及充提首末次等领域方法；不改 thinkorm 配置与 WalletLogic。
todos:
  - id: wallet-user-stat-model
    content: 新增 WalletUserStatModel extends think\Model（connection/table、PHPDoc、inc/apply* 方法）
    status: completed
  - id: smoke-verify
    content: Docker 内冒烟验证 find/applyDeposit 与 version 行为
    status: completed
isProject: false
---

# rh_wallet.wallet_user_stat Model 实现计划

## 背景与约束

- 表：`rh_wallet.wallet_user_stat`，**单库单表、非分片**；主键 `(uid, currency)`；金额为 **x1000 整数**；含 `version` 乐观锁。
- 与现有 [`WalletStatModel`](app/model/multi/WalletStatModel.php)（`SelfBaseModel` + 分片）**并存**，本次不替换其调用链。
- **直接继承 `think\Model`**；库表绑定参考项目内惯例：`$connection` + **`$table = '库名.表名'`**（与你提供的 `s_statistics.gm_stat_summary` 写法一致）。

```mermaid
flowchart LR
  Logic["Logic / Service"]
  Model["WalletUserStatModel"]
  Conn["connection mysql"]
  Table["table rh_wallet.wallet_user_stat"]

  Logic --> Model
  Model --> Conn
  Model --> Table
```

## 实现方案

### 单文件：[`app/model/WalletUserStatModel.php`](app/model/WalletUserStatModel.php)

```php
namespace app\model;

use think\Model;
use think\facade\Db;

/**
 * 用户钱包累计统计（rh_wallet.wallet_user_stat）
 *
 * @property int $uid
 * @property string $currency
 * ...
 */
class WalletUserStatModel extends Model
{
    /**
     * The connection name for the model.
     *
     * @var string|null
     */
    protected $connection = 'mysql';

    /**
     * The table associated with the model.
     * 跨库：库名.表名
     *
     * @var string
     */
    protected $table = 'rh_wallet.wallet_user_stat';

    /**
     * 复合主键
     *
     * @var array<int, string>|string
     */
    protected $pk = ['uid', 'currency'];
}
```

**说明：**

- **不改** [`config/thinkorm.php`](config/thinkorm.php)：沿用现有 `mysql` 连接（`database` 可为空，与分片库同一实例），由 `$table` 全限定名定位 `rh_wallet`。
- 主键使用 ThinkORM **数组形式** `['uid', 'currency']`，与表 `PRIMARY KEY (uid, currency)` 一致；`find` / `update` / `destroy` 等可传复合键数组。

### PHPDoc `@property`

与表字段一致：`total_deposit_*`、`first/last_deposit_*`、提现/促销/返利/退款/拒付字段、`version`、`created_at`、`updated_at`；金额单位 x1000。

### 查询与初始化

| 方法 | 说明 |
|------|------|
| `findByUidCurrency(int $uid, string $currency = 'USD'): ?static` | `static::find(['uid' => $uid, 'currency' => $currency])` 或等价 where |
| `lockByUidCurrency(int $uid, string $currency): ?static` | 复合 where + `lock(true)->find()` |
| `insertInitRow(int $uid, string $currency = 'USD'): static` | `static::create(['uid' => $uid, 'currency' => $currency])` |

### 统计更新（参考 [`WalletStatModel::inc`](app/model/multi/WalletStatModel.php)）

**通用累加 `incField`：**

- `$field` 白名单：仅可 `inc` 的 `*_amount` / `*_count` 列
- `static::where(['uid','currency'])->inc($field, $amount)`，可选 `version` 条件与 `version + 1`

**领域方法（静态，单次 `update`）：**

| 方法 | 行为 |
|------|------|
| `applyDeposit` | 累加充值金额/次数；更新 `last_deposit_*`；首充写 `first_deposit_*` |
| `applyWithdraw` | 提现对称 |
| `applyPromoBonus` / `applyCashback` / `applyRefund` / `applyChargeback` | 对应累计字段 |

- 金额参数 `int`，禁止 `float`
- 首充/首提用 `Db::raw('IF(...)')` 保证原子性
- 返回影响行数

### 暂不包含

- 不改 [`WalletLogic.php`](app/api/logic/WalletLogic.php)、[`RegisterService.php`](app/service/wallet/RegisterService.php)

## 验证（实现后）

```bash
docker exec -w /app/www/slot/slot_wallet php82 php -r "
// bootstrap 后
var_export(app\model\WalletUserStatModel::findByUidCurrency(1, 'USD'));
"
```

## 文件清单

| 操作 | 路径 |
|------|------|
| 新增 | `app/model/WalletUserStatModel.php` |

**无配置变更**（不新增 `rh_wallet` connection）。