cursor/plans/walletuserstat_model_c0f7d053.plan.md

name, overview, todos, isProject

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

rh_wallet.wallet_user_stat Model 实现计划

背景与约束

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

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

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：沿用现有 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）

通用累加 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、RegisterService.php

验证（实现后）

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）。