ok
This commit is contained in:
ray zhou
122
plans/c端_packages_响应精简_b2ac407a.plan.md
Normal file
122
plans/c端_packages_响应精简_b2ac407a.plan.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
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，除非你希望一并补齐。
|
||||
Reference in New Issue
Block a user