---
name: 定格冻结用户流水
overview: 在 slot_wallet 的 `freeCreditsFreeze` 成功扣款后，补充 `addTransactionRecord` 写入 C 端可见的 `user_transaction_log`；并在 slot_pwa 注册新 `transaction_type` 与列表筛选映射。
todos:
  - id: wallet-add-transaction
    content: WalletLogic::freeCreditsFreeze 增加 addTransactionRecord（type=65，负金额）
    status: pending
  - id: pwa-type-map
    content: slot_pwa UserTransactionLogService 注册 type 65 与展示名
    status: pending
  - id: wallet-unit-test
    content: wallet 单测断言 freeCreditsFreeze 写入用户流水
    status: pending
  - id: run-phpunit
    content: php82 跑 wallet 相关单测验证
    status: pending
isProject: false
---

# freeCreditsFreeze 补充用户可见流水

## 问题

[`WalletLogic::freeCreditsFreeze()`](slot_wallet/app/api/logic/WalletLogic.php) 当前仅：

1. `minus()` 扣减 deposit/withdraw
2. [`addLog()`](slot_wallet/app/api/logic/WalletLogic.php) 写入分表 **wallet_log**（`biz_type=freeCreditsFreeze`）

**未**调用 [`addTransactionRecord()`](slot_wallet/app/api/logic/WalletLogic.php)，因此 MQ 不会投递到 PWA，用户在 **Transaction / 流水页** 看不到定格扣款记录。

对比：普通提现冻结在同文件内已有：

```402:402:slot_wallet/app/api/logic/WalletLogic.php
                $this->addTransactionRecord('withdraw frozen', $this->requestDTO->fee * -1, $balance, 7);
```

需求文档 §15.2 要求「必须写钱包流水」——`wallet_log` 已满足后台审计；本需求补齐 **C 端展示流水**。

```mermaid
flowchart LR
  freeze[freeCreditsFreeze]
  addLog[addLog wallet_log]
  addTx[addTransactionRecord]
  mq[PWA MQ]
  ui[用户流水列表]
  freeze --> addLog
  freeze --> addTx --> mq --> ui
```

说明：`freeCreditsFreeze` 是**扣款**（金额为负），不是入账；用户列表里应显示为负向变动（与 type 7「Withdraw」冻结类似）。

## 实现方案（slot_wallet + slot_pwa）

### 1. slot_wallet — `freeCreditsFreeze` 增加用户流水

文件：[`WalletLogic.php`](slot_wallet/app/api/logic/WalletLogic.php)

在事务内、`addLog` 成功之后、`commit` 之前增加（与 `withdrawFrozen` 一致，失败仅记日志不回滚主事务）：

```php
$this->addTransactionRecord(
    'Free Credits Freeze',
    $this->requestDTO->fee * -1,
    $balance,
    self::TRANSACTION_TYPE_FREE_CREDITS_FREEZE  // 新常量，建议 65
);
```

在 `WalletLogic` 类内新增常量（或集中放在与 PWA 对齐的注释块）：

```php
/** 用户流水类型：首充定格冻结扣款，对应 freeCreditsFreeze */
private const TRANSACTION_TYPE_FREE_CREDITS_FREEZE = 65;
```

字段约定（与现有 `addTransactionRecord` 一致）：

| 字段 | 值 |
| --- | --- |
| `subject` | `Free Credits Freeze`（C 端 `name` 映射用） |
| `amount` | `-fee`（千分位，负数为扣款） |
| `balance_after` | 扣款后 `deposit + withdraw` 总余额 |
| `transaction_id` | 已有规则：`substr(uid,0,3) + biz_id`（幂等键 `free_credits_freeze:{orderId}`） |
| `transaction_type` | `65` |

**不**改 `addLog` / 余额扣减逻辑；**不**改 slot_console / slot_lib。

### 2. slot_pwa — 注册 transaction_type=65

文件：[`UserTransactionLogService.php`](slot_pwa/app/service/UserTransactionLogService.php)

- `$typeMaps[-1]`（All）增加 `65`
- `$typeMaps[1]`（Withdraw 分类，已含 7/8）增加 `65`（定格扣款与提现类支出归同一 tab，可按产品再调）
- `$typeToClient[65] = 'Free Credits Freeze'`（或简短文案 `Free Credits`）

可选：在 [`UserTransactionLogShardModel.php`](slot_pwa/app/model/shard/UserTransactionLogShardModel.php) 增加 `TRANSACTION_TYPE_FREE_CREDITS_FREEZE = 65` 常量与注释，wallet 侧用相同数字（wallet 不依赖 pwa 类，注释对齐即可）。

### 3. 单测

| 仓库 | 文件 | 内容 |
| --- | --- | --- |
| slot_wallet | 扩展 [`WalletLogicHarness`](slot_wallet/tests/Support/WalletLogicHarness.php) 或新建用例 | 覆写/桩 `addTransactionRecord`，断言 `freeCreditsFreeze` 成功后调用一次，且 `amount < 0`、`type=65` |
| slot_wallet | 现有 freeze 相关测 | 回归通过 |

运行：

```bash
docker exec -w /app/www/slot/slot_wallet php82 ./vendor/bin/phpunit tests/Unit/WalletFreeCreditsFirstKeepTest.php tests/Unit/WalletFreeCreditInitBusTest.php
# 若有新增 FreezeTransactionTest 则一并跑
```

## 不在本次范围

- `freeCreditsClaim` / `freeCreditsFirstCashKeep` 的用户流水（若也要在流水页展示入账，可另开任务，同样走 `addTransactionRecord` + 新 type）
- 修改 `wallet_log` 表结构
- C 端 UI 文案多语言（仅后端 `name` 英文字段）

## 验收

1. 首充定格成功后，用户流水列表（All / Withdraw）出现一条 **负金额** 记录，`name` 为 Free Credits Freeze
2. `transaction_id` 与 `biz_id`（`free_credits_freeze:{orderId}`）可追溯
3. 幂等重试 freeze：wallet_log 幂等不变；若 MQ 重复需依赖现有消费端去重（与 type 7 行为一致，本次不单独改 MQ）
4. wallet 单测通过