123 lines
5.7 KiB
Markdown
123 lines
5.7 KiB
Markdown
---
|
||
name: C端 packages 响应精简
|
||
overview: 在 slot_console 的 Free Credits 定格状态接口（`/api/free-credits/status` 与 `claim` 共用 `buildStatus`）中，精简 `packages[]` 每项字段，并将档位 status 4/5 映射为 3，使 C 端仅见 0–3。后台 innerapi 与库表语义不变。
|
||
todos:
|
||
- id: model-list-for-client
|
||
content: 在 FreeCreditsPackageModel 实现 mapStatusForClient，并精简 listForClient 返回字段
|
||
status: in_progress
|
||
- id: update-phpdoc
|
||
content: 更新 FreeCreditsLogic、FreeCreditsController 的 packages/status PHPDoc
|
||
status: pending
|
||
- id: update-unit-tests
|
||
content: 调整 FreeCreditsClientStatusTest / Harness，并补充 status 4/5→3 用例
|
||
status: pending
|
||
- id: run-phpunit
|
||
content: 在 php82 容器内跑 FreeCreditsClientStatusTest 验证
|
||
status: pending
|
||
isProject: false
|
||
---
|
||
|
||
# C 端定格状态 packages 响应调整
|
||
|
||
## 背景与范围
|
||
|
||
目标接口在 [slot_console/app/api/controller/FreeCreditsController.php](slot_console/app/api/controller/FreeCreditsController.php)：
|
||
|
||
- `POST /api/free-credits/status` → `FreeCreditsLogic::status()` → `buildStatus()`
|
||
- `POST /api/free-credits/claim` 成功后的 `data` 结构相同
|
||
|
||
`packages[]` 当前由 [slot_console/app/model/common/FreeCreditsPackageModel.php](slot_console/app/model/common/FreeCreditsPackageModel.php) 的 `listForClient()` 组装，经 `FreeCreditsLogic::clientPackagesForPlayer()` 注入响应：
|
||
|
||
```72:86:slot_console/app/model/common/FreeCreditsPackageModel.php
|
||
public static function listForClient(int $playerId, callable $formatAmount): array
|
||
{
|
||
// ...
|
||
$packages[] = [
|
||
'id' => intval($row->id),
|
||
'package_no' => intval($row->package_no),
|
||
'package_type' => intval($row->package_type),
|
||
'amount' => $formatAmount(intval($row->amount_qf)),
|
||
'status' => intval($row->status),
|
||
];
|
||
```
|
||
|
||
库表档位 status（[install.sql](slot_console/db/install.sql)）：`0` 锁定、`1` 可操作、`2` 处理中、`3` 已完成、`4` 失败、`5` 风控拒绝。
|
||
|
||
**不在本次范围**：`innerapi/free-credits/*`（后台仍用 `package_no` / `package_type` 聚合）、库表与 Logic 内按 `package_no` / `package_type` 的业务判断。
|
||
|
||
## 目标契约
|
||
|
||
`packages[]` 每项仅保留：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | int | 档位主键；claim / 第一档提现仍传 `package_id` |
|
||
| `amount` | float | 展示大单位，逻辑不变 |
|
||
| `status` | int | **仅可能为 0、1、2、3**；DB 为 4 或 5 时对外返回 3 |
|
||
|
||
列表仍按 `package_no` 升序（查询不变，仅响应不暴露 `package_no`）。C 端可用数组下标区分第一档（`[0]`）与后续档。
|
||
|
||
Status 映射（仅 C 端展示层）：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
db0[DB 0 locked] --> c0[C 0]
|
||
db1[DB 1 ready] --> c1[C 1]
|
||
db2[DB 2 processing] --> c2[C 2]
|
||
db3[DB 3 completed] --> c3[C 3]
|
||
db4[DB 4 failed] --> c3
|
||
db5[DB 5 rejected] --> c3
|
||
```
|
||
|
||
## 实现步骤
|
||
|
||
### 1. 修改 `FreeCreditsPackageModel::listForClient()`
|
||
|
||
文件：[FreeCreditsPackageModel.php](slot_console/app/model/common/FreeCreditsPackageModel.php)
|
||
|
||
- 新增私有/公有静态方法（建议 `mapStatusForClient(int $status): int`），将 `STATUS_FAILED(4)`、`STATUS_REJECTED(5)` 转为 `STATUS_COMPLETED(3)`，其余原样返回。
|
||
- `listForClient()` 返回项改为 `{ id, amount, status }`，`status` 走映射方法。
|
||
- 更新 `@return` PHPDoc：`list<array{id:int,amount:float,status:int}>`，并注明 C 端 status 取值 0–3。
|
||
|
||
### 2. 同步 Logic / Controller 文档
|
||
|
||
- [FreeCreditsLogic.php](slot_console/app/api/logic/FreeCreditsLogic.php)：`clientPackagesForPlayer()` 的 `@return` 与注释。
|
||
- [FreeCreditsController.php](slot_console/app/api/controller/FreeCreditsController.php)：`status()` / `claim()` 中 `packages` 字段说明——去掉 `package_no`、`package_type`；`status` 改为 `0 locked ~ 3 completed（失败/拒绝对外亦为 3）`。
|
||
|
||
### 3. 单测
|
||
|
||
- [FreeCreditsClientStatusTest.php](slot_console/tests/Unit/FreeCreditsClientStatusTest.php)：`PACKAGE_KEYS` 改为 `['id','amount','status']`；注入样例去掉 `package_no` / `package_type`。
|
||
- 新增用例（二选一或都做）：
|
||
- 对 `mapStatusForClient`：断言 `4→3`、`5→3`、`0–3` 不变；
|
||
- 或在 harness 注入 `status=4/5` 的 package，断言 `buildStatus` 输出为 `3`。
|
||
- [FreeCreditsLogicHarness.php](slot_console/tests/Support/FreeCreditsLogicHarness.php)：更新 `injectClientPackages` 相关 PHPDoc 类型。
|
||
|
||
运行（Docker）：
|
||
|
||
```bash
|
||
docker exec -w /app/www/slot/slot_console php82 ./vendor/bin/phpunit tests/Unit/FreeCreditsClientStatusTest.php
|
||
```
|
||
|
||
## 数据流（变更后）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as C端
|
||
participant API as FreeCreditsController
|
||
participant Logic as FreeCreditsLogic
|
||
participant Model as FreeCreditsPackageModel
|
||
|
||
C->>API: status / claim
|
||
API->>Logic: buildStatus
|
||
Logic->>Model: listForClient
|
||
Model->>Model: mapStatusForClient
|
||
Model-->>Logic: id, amount, status
|
||
Logic-->>C: packages[]
|
||
```
|
||
|
||
## 风险与说明
|
||
|
||
- **C 端若已依赖 `package_no` / `package_type` 或区分 4/5**：需同步改 UI；服务端 claim 仍用 `package_id`，顺序校验仍在 Logic/DB，不依赖响应里的 `package_no`。
|
||
- **失败/拒绝与成功完成在 UI 上同为 status=3**：符合当前需求；若以后要区分展示，需另加字段或改映射规则。
|
||
- 单测 [FreeCreditsClientStatusTest](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) 期望顶层含 `first_cash_amount`，但 [buildStatus](slot_console/app/api/logic/FreeCreditsLogic.php) 当前未返回该字段——与本次改动无关，不纳入本 PR，除非你希望一并补齐。
|