133 lines
4.3 KiB
Markdown
133 lines
4.3 KiB
Markdown
---
|
||
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）。
|