ok

2026-05-29 11:21:40 +08:00
parent 5d6d482efe
commit f71a5c59af
447 changed files with 32245 additions and 116 deletions
--- a/plans/walletuserstat_model_c0f7d053.plan.md
+++ b/plans/walletuserstat_model_c0f7d053.plan.md
@@ -0,0 +1,132 @@
+---
+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）。