diff --git a/.gitignore b/.gitignore index 9ce15ac..448dbea 100644 --- a/.gitignore +++ b/.gitignore @@ -32,8 +32,8 @@ # ========================================================= # Team shared plans, optional # ========================================================= -!plans/ -!plans/** +plans/ +plans/** # ========================================================= # Do NOT track Cursor projects runtime files diff --git a/plans/create_cursor_workspace_e8a5f935.plan.md b/plans/create_cursor_workspace_e8a5f935.plan.md deleted file mode 100644 index 8f18437..0000000 --- a/plans/create_cursor_workspace_e8a5f935.plan.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: Create Cursor Workspace -overview: 在 `/Users/ray/Documents/project/www/slot` 创建一个 Cursor/VS Code workspace 文件，并把该目录下的一级项目文件夹加入 workspace。默认排除 `.vscode` 和普通文件。 -todos: - - id: check-existing - content: 检查 `/Users/ray/Documents/project/www/slot/slot.code-workspace` 是否已存在 - status: completed - - id: write-workspace - content: 创建或合并 workspace folders 列表 - status: completed - - id: validate-json - content: 校验 `.code-workspace` JSON 格式 - status: completed -isProject: false ---- - -# Create Slot Workspace - -将在 [`/Users/ray/Documents/project/www/slot/slot.code-workspace`](/Users/ray/Documents/project/www/slot/slot.code-workspace) 创建 workspace 文件，内容使用标准 `.code-workspace` JSON 格式。 - -计划加入这些一级非隐藏文件夹： - -- [`backend`](/Users/ray/Documents/project/www/slot/backend) -- [`monitor`](/Users/ray/Documents/project/www/slot/monitor) -- [`slot-foundation`](/Users/ray/Documents/project/www/slot/slot-foundation) -- [`slot_agent`](/Users/ray/Documents/project/www/slot/slot_agent) -- [`slot_agent_vue`](/Users/ray/Documents/project/www/slot/slot_agent_vue) -- [`slot_center`](/Users/ray/Documents/project/www/slot/slot_center) -- [`slot_console`](/Users/ray/Documents/project/www/slot/slot_console) -- [`slot_gateway`](/Users/ray/Documents/project/www/slot/slot_gateway) -- [`slot_hub`](/Users/ray/Documents/project/www/slot/slot_hub) -- [`slot_lib`](/Users/ray/Documents/project/www/slot/slot_lib) -- [`slot_notification`](/Users/ray/Documents/project/www/slot/slot_notification) -- [`slot_pay`](/Users/ray/Documents/project/www/slot/slot_pay) -- [`slot_pwa`](/Users/ray/Documents/project/www/slot/slot_pwa) -- [`slot_risk`](/Users/ray/Documents/project/www/slot/slot_risk) -- [`slot_sdk`](/Users/ray/Documents/project/www/slot/slot_sdk) -- [`slot_user`](/Users/ray/Documents/project/www/slot/slot_user) -- [`slot_wallet`](/Users/ray/Documents/project/www/slot/slot_wallet) - -Workspace 文件结构会类似： - -```json -{ - "folders": [ - { "path": "backend" }, - { "path": "monitor" }, - { "path": "slot-foundation" } - ], - "settings": {} -} -``` - -实施步骤： - -1. 检查目标文件是否已存在，避免覆盖已有 workspace 配置。 -2. 如果不存在，创建 [`slot.code-workspace`](/Users/ray/Documents/project/www/slot/slot.code-workspace)。 -3. 如果已存在，先读取现有内容，再合并缺失的文件夹，保留已有设置。 -4. 校验生成的 JSON 格式可被 Cursor 打开。 \ No newline at end of file diff --git a/plans/docker_环境_cursor_规则_ae19913d.plan.md b/plans/docker_环境_cursor_规则_ae19913d.plan.md deleted file mode 100644 index f88f25a..0000000 --- a/plans/docker_环境_cursor_规则_ae19913d.plan.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -name: Docker 环境 Cursor 规则 -overview: 建议把 Docker 开发环境信息写成 Cursor 规则，但单独一条、尽量简短；优先放在 slot 项目级规则，只有跨多个仓库共用同一套 Docker 时才放到用户级规则。 -todos: - - id: decide-scope - content: 确认 Docker 规则放项目级 (slot) 还是用户级 (~/.cursor/rules) - status: completed - - id: confirm-php-container - content: 确认 slot 后端默认容器 php82 与各服务 working_dir - status: completed - - id: create-dev-rule - content: 新建 dev-environment.mdc（15–30 行，含 compose 路径、容器名、端口、exec 示例） - status: completed -isProject: false ---- - -# Docker 环境是否写入 Cursor 规则 - -## 结论 - -**值得写进 Cursor 规则**，但**不必**和 [`backend-layering.mdc`](/Users/ray/.cursor/rules/backend-layering.mdc) 混在同一条里，也**不必**默认全部塞进「用户级 + alwaysApply」。 - -原因：Agent 在帮你跑 `php`、`composer`、`artisan`、迁移、单测、连 Redis/MySQL 时，若不知道服务在容器里，常会错误地在宿主机执行，或连错端口（例如 MySQL 映射是 `3309:3306`）。 - ---- - -## 用户级 vs 项目级：怎么选 - -| 放置位置 | 路径 | 适用场景 | -| --- | --- | --- | -| **项目级（推荐）** | 例如在 slot 多根工作区根目录建 [`.cursor/rules/dev-environment.mdc`](file:///Users/ray/Documents/project/www/slot/.cursor/rules/dev-environment.mdc) | 只有 slot / `www/slot` 相关仓库用这套 Docker | -| **用户级** | [`~/.cursor/rules/dev-environment.mdc`](/Users/ray/.cursor/rules/dev-environment.mdc) | 多个不相关项目都共用 [`/Users/ray/Documents/project/docker/docker-compose.yml`](file:///Users/ray/Documents/project/docker/docker-compose.yml) | - -你当前用户级只有分层规范一条，且 `alwaysApply: true`。Docker 信息属于**运行环境**，和编码规范是不同关注点： - -- **分层规则**：继续 `alwaysApply: true`（跨项目仍有用） -- **Docker 规则**：建议 `alwaysApply: false`，或仅在 slot 工作区用项目级规则；避免在写前端、文档、Figma 时也占用上下文 - -当前 slot 工作区下**没有** [`.cursor/rules/`](file:///Users/ray/Documents/project/www/slot/.cursor/rules)，更适合为 slot 单独加一条 `dev-environment.mdc`。 - ---- - -## 规则里应写什么（可操作、短） - -根据你的 [`docker-compose.yml`](file:///Users/ray/Documents/project/docker/docker-compose.yml)，建议只写 Agent **执行命令时必需** 的信息： - -1. **Compose 位置**：`/Users/ray/Documents/project/docker/docker-compose.yml` -2. **容器名 → 用途**（执行命令用 `docker exec`，不要用宿主机 PHP/CLI）： - - `php82` — PHP 8.2（slot 后端主环境，按你实际版本确认） - - `php72` — PHP 7.2（若有老项目） - - `goMysql` — MySQL 8（容器内 `3306`，宿主机 **`3309`**） - - `redis` — `6379`；`goredis` — 宿主机 `6378` -3. **挂载路径**：宿主机 `/Users/ray/Documents/project` → 容器内 `/app`（项目在容器内路径如 `/app/www/slot/backend`） -4. **命令约定**（示例，按你项目真实入口改）： - - PHP：`docker exec -w /app/www/slot/backend php82 php ...` - - Composer / artisan：同样在 `php82` 内、对应 `working_dir` 执行 - - MySQL CLI：`docker exec -it goMysql mysql -uroot -proot ...`（或注明用宿主机 `127.0.0.1:3309`） -5. **明确禁止/避免**：不要在 macOS 宿主机直接跑 `php`/`composer`（除非已确认本机也有同版本环境） - -**不建议写进规则的内容**： - -- 完整 `docker-compose.yml` 复制（冗长、易过期） -- 所有服务密码细节（compose 里已有；规则里写「以 compose 为准」即可） -- RabbitMQ、Milvus 等与当前 slot 任务无关的服务（除非经常用到） - ---- - -## 与现有文档的关系 - -- **Cursor 规则**：给 Agent 的「默认假设」，每次对话自动带上（按 `alwaysApply` / `globs`） -- **仓库 README / `docs/dev-setup.md`**：给人看的完整说明；规则可写一句「详细步骤见 xxx」 - -两者可并存：规则 15–30 行，文档可更长。 - ---- - -## 建议的规则骨架（项目级示例） - -```markdown ---- -description: Slot 本地 Docker 开发环境（PHP / MySQL / Redis） -alwaysApply: true ---- - -# Local Dev (Docker) - -- Compose: `/Users/ray/Documents/project/docker/docker-compose.yml` -- Host project root: `/Users/ray/Documents/project` → container `/app` -- Run PHP/Composer/Artisan inside container `php82`, not on macOS host. -- MySQL: container `goMysql`; from host use `127.0.0.1:3309`. -- Redis: container `redis`, host port `6379`. -- Example: `docker exec -w /app/www/slot/backend php82 php artisan ...` -``` - -若放在**用户级**，把 `alwaysApply` 改为 `false`，或标题改成「Project docker (ray)」以免污染非 slot 项目。 - ---- - -## 推荐决策 - -```mermaid -flowchart TD - Q[多个仓库共用同一套 Docker?] - Q -->|是| UserRule["~/.cursor/rules/dev-environment.mdc\nalwaysApply: false"] - Q -->|否 仅 slot| ProjRule["www/slot/.cursor/rules/dev-environment.mdc\nalwaysApply: true 在该工作区"] - Both[保留 backend-layering 在用户级 alwaysApply] - UserRule --> Both - ProjRule --> Both -``` - -**对你当前情况**：slot 多仓库工作区 + Docker 在 `project/docker`，**优先项目级规则**；仅当你打开的其他 Cursor 工作区（非 slot）也依赖同一 compose 时，再复制一份到用户级。 - ---- - -## 下一步（你确认后可执行） - -1. 在 [`www/slot/.cursor/rules/`](file:///Users/ray/Documents/project/www/slot/.cursor/rules) 新建 `dev-environment.mdc`（约 20 行） -2. 确认 slot 后端默认用 `php82` 还是 `php72`，以及各子服务在容器内的 `working_dir` -3. 可选：在 [`docs/`](file:///Users/ray/Documents/project/www/slot/docs) 增加 `dev-setup.md` 供人查阅，规则里链过去 - -无需修改现有的 `backend-layering.mdc`。 diff --git a/plans/firstcashout_合并代码评审_b7afdfc6.plan.md b/plans/firstcashout_合并代码评审_b7afdfc6.plan.md deleted file mode 100644 index 22bb19b..0000000 --- a/plans/firstcashout_合并代码评审_b7afdfc6.plan.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -name: firstCashout 合并代码评审 -overview: 你对「merge post + 统一 WithdrawService::apply」的改法方向正确，但当前 WithdrawService 在 package_id>0 时仍执行 checkInfo/手续费/黑规则，且 Pay 失败无回滚，会导致第一档提现不可用或卡在 processing。 -todos: - - id: fc-early-return - content: WithdrawService::apply 中 package_id>0 走独立 applyFreeCreditsFirstCashout 并 early return - status: completed - - id: skip-checkinfo-fc - content: FC 分支跳过 checkInfo、getAmountAndFee、黑规则（或产品确认保留项） - status: completed - - id: pay-fail-rollback - content: Pay apply 失败时 handleFirstCashoutResult 回滚 processing - status: completed - - id: fc-withdrawal-info - content: FC 使用 package amount_qf、fee=0、auditType=2 组 WithdrawalInfo - status: completed -isProject: false ---- - -# firstCashout 合并改动 — 代码评审 - -## 你的改动（理解正确） - -```mermaid -sequenceDiagram - participant Ctrl as WithdrawController - participant FC as FreeCreditsLogic - participant WS as WithdrawService - participant Pay as slot_pay - - Ctrl->>FC: mergeFirstCashoutIntoPost - Note over FC: amount + bizType + package_id - Ctrl->>WS: apply(DTO) - WS->>FC: firstCashout(uid, packageId, orderId) - Note over FC: markFirstCashoutProcessing - WS->>Pay: apply(WithdrawalInfo) -``` - -- [`WithdrawController::apply`](slot_console/app/api/controller/WithdrawController.php)：有 `package_id` 先 merge，再**同一套** `validate($type)` — 符合预期。 -- [`mergeFirstCashoutIntoPost`](slot_console/app/api/logic/FreeCreditsLogic.php)：补 `amount` / `bizType` / `package_id` — 符合预期。 -- [`firstCashout`](slot_console/app/api/logic/FreeCreditsLogic.php) 收窄为只 `markFirstCashoutProcessing` + 外部统一 `PayService::apply` — 思路可行。 - ---- - -## P0：FC 仍会走 `checkInfo`，大概率直接失败 - -[`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) 当前顺序： - -```php -$bankInfo = $this->checkBankInfo($applyDTO); -$this->checkInfo($applyDTO->type, $applyDTO->amount); // 始终执行 -// ... -if ($applyDTO->package_id > 0) { - firstCashout(...); // 永远走不到（checkInfo 已抛错） -} -``` - -`checkInfo` 会校验**钱包可提现余额** ≥ amount（[`WithdrawService.php` L333-335](slot_console/app/service/WithdrawService.php)）。 -Free Credits 第一档资金在**活动池**，不在普通 `withdraw` 余额里 → 典型报错 **`Insufficient balance`**。 - -**结论**：与需求「不进入普通钱包」冲突，第一档线上基本提不了现。 - -**建议**：`package_id > 0`（或 `bizType === free_credit_first_cashout`）时 **跳过** `checkInfo`（及与之绑定的首提 min/max 规则）。 - ---- - -## P0：Pay 失败时档位已置为 processing，无回滚 - -你现在在 **Pay 之前** 调用 `firstCashout` → `markFirstCashoutProcessing`（status=2）。 - -原实现是：mark → `PayService::apply` → **catch 时** `handleFirstCashoutResult($orderId, false)` 恢复 ready。 - -当前 [`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) L236 调 pay **没有** try/catch 回滚 → 申请失败时 package 会一直 **processing**，用户无法重试。 - -**建议**： - -```php -if ($applyDTO->package_id > 0) { - $orderId = CommonFn::generateOrderId(4, $userTag->uid); - (new FreeCreditsLogic())->firstCashout($userTag->uid, $applyDTO->package_id, $orderId); - $withdrawalInfo->orderId = $orderId; - $withdrawalInfo->bizType = FreeCreditsLogic::BIZ_TYPE_FIRST_CASHOUT; - try { - $res = PayService::getInstance()->apply($withdrawalInfo->toArray()); - return $res; - } catch (\Throwable $e) { - (new FreeCreditsLogic())->handleFirstCashoutResult($orderId, false); - throw $e; - } -} -``` - -（FC 分支应 **early return**，不要继续走下面黑规则 + `getAmountAndFee`。） - ---- - -## P1：FC 仍走普通手续费 / 黑规则 / auditType - -合并后 FC 路径仍执行： - -- `getAuditType($applyDTO->amount)`、`BlackApiService`、提现倍数检测 -- `getAmountAndFee($applyDTO->amount, $this->withdrawal)` — 可能扣手续费、按钱包余额改金额 - -原 [`firstCashout`](slot_console/app/api/logic/FreeCreditsLogic.php) 约定： - -- `fee = 0` -- `auditType = 2`（人工审核） -- `amount = package->amount_qf`（千分位，不经手续费逻辑） - -`merge` 写入的 `amount` 是 **展示大单位**（`getNumberFormat(qf)`），再经 `getAmountAndFee` 可能与 pay 侧期望的千分位不一致。 - -**建议**：FC 分支单独组 `WithdrawalInfo`： - -| 字段 | FC 取值 | -|------|---------| -| amount | 从 package 读 `amount_qf`（或 merge 时额外缓存 `_amount_qf`） | -| fee | 0 | -| auditType | 2 | -| bizType | `free_credit_first_cashout` | -| 黑规则 | 跳过（或产品确认是否要对 FC 也做） | - ---- - -## P1：`firstCashout` 与 `markFirstCashoutProcessing` 重复校验 - -[`firstCashout`](slot_console/app/api/logic/FreeCreditsLogic.php) 内再次查 `STATUS_READY` 后调用 `markFirstCashoutProcessing`，而 `markFirstCashoutProcessing` ** again** 要求 `STATUS_READY`（L343）。 -逻辑重复但无害；可简化为只调 `markFirstCashoutProcessing`，或只保留一处校验。 - -注意：`mergeFirstCashoutIntoPost` 已校验 ready，到 `firstCashout` 时若并发重复提交，第二次会在 mark 阶段失败 — 符合「处理中不可重复提交」。 - ---- - -## P2：行为变化（需产品确认） - -| 项 | 原 FC | 现统一 apply | -|----|--------|----------------| -| `is_bind_name` | 不校验 | **校验**（L157） | -| Redis 5s 频控 | 无 | **有** | -| 返回值 | `{order_id, amount}` | pay `apply` 原始结构 | - -若 C 端依赖 `data.order_id` / `data.amount` 展示，需确认 pay 返回是否一致。 - ---- - -## 做得好的部分 - -- Controller 单入口 + merge post：**正确**。 -- 去掉独立 FC validator scene：**正确**。 -- [`FreeCreditsController::firstCashout`](slot_console/app/api/controller/FreeCreditsController.php) 兼容路径与主入口一致：**正确**。 -- pay 层仍靠 `bizType` 跳过 `withdrawFrozen`：**只要 bizType 确实传到 pay 就没问题**（当前 L184 已设）。 - ---- - -## 推荐修复结构（最小 diff） - -在 [`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) 开头（绑卡、频控之后）： - -```php -if ($applyDTO->package_id > 0) { - return $this->applyFreeCreditsFirstCashout($applyDTO, $bankInfo); -} -// 原有普通提现逻辑不变 -``` - -`applyFreeCreditsFirstCashout` 内： - -1. 跳过 `checkInfo`、黑规则、`getAmountAndFee` -2. `orderId` → `firstCashout`（mark）→ 组 `WithdrawalInfo`（qf amount, fee=0, auditType=2, bizType） -3. try/catch pay + `handleFirstCashoutResult` 回滚 - -**不要**在普通流程中间用 `if ($package_id > 0) { firstCashout; }` 再接着跑普通逻辑 — 这是当前问题的根源。 - ---- - -## 验收清单 - -- [ ] `package_id>0` 且钱包 withdraw=0：能成功提交 pay（不报 Insufficient balance） -- [ ] pay 申请失败：package 回到 ready，可再次提现 -- [ ] pay 成功 + 回调：package completed，player `FIRST_CASH_DONE` -- [ ] 普通提现无 `package_id`：行为与改前一致 -- [ ] `remark`/bizType 在 pay 侧仍为 `free_credit_first_cashout`，不冻结钱包 diff --git a/plans/firstcashout_合并提现_837e2d44.plan.md b/plans/firstcashout_合并提现_837e2d44.plan.md deleted file mode 100644 index c80fcec..0000000 --- a/plans/firstcashout_合并提现_837e2d44.plan.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -name: firstCashout 合并提现 -overview: 可以合并：推荐在 Withdraw 入口与 Pay 下单层统一，用 package_id 区分；活动档位状态机仍留在 FreeCreditsLogic，不能把 FC 逻辑硬塞进 WithdrawService::apply 主流程中间。 -todos: - - id: dto-package-id - content: WithdrawApplyDTO 增加 package_id；WithdrawValidator 增加 FC scene（package_id 替代 amount） - status: completed - - id: withdraw-fc-branch - content: WithdrawService::apply 增加 applyFreeCreditsFirstCashout early return（跳过 checkInfo/手续费/黑规则） - status: completed - - id: controller-unify - content: WithdrawController::apply 统一入口；FreeCreditsController::firstCashout 改为兼容 alias - status: completed - - id: bank-persist - content: FC 分支复用 checkBankInfo，与普通提现绑卡行为一致 - status: completed - - id: pay-rollback-test - content: 补单测/集成测：FC 无 withdraw 余额可提交、Pay 失败回滚 ready - status: completed -isProject: false ---- - -# firstCashout 能否合并进现有提现逻辑 - -## 结论（后端） - -**可以合并，且推荐合并「入口 + 校验 + 绑卡 + Pay 下单」；不应把 Free Credits 编排塞进 [`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) 主流程中间。** - -当前仓库状态：**尚未合并**——仍是双入口： - -| 入口 | 现状 | -|------|------| -| [`POST /api/free-credits/first-cashout`](slot_console/app/api/controller/FreeCreditsController.php) | `FreeCreditsLogic::firstCashout` 完整编排 | -| [`POST /api/withdraw/apply`](slot_console/app/api/controller/WithdrawController.php) | `WithdrawService::apply`，无 `package_id` | - -Pay 层**已经统一**：两类提现最终都走 [`WithdrawalOrderEntity::apply`](slot_pay/app/entity/WithdrawalOrderEntity.php)，靠 `bizType=free_credit_first_cashout` 跳过 `withdrawFrozen` 并走独立 MQ 回调。 - ---- - -## 为什么「可以」合并 - -C 端参数与需求 §11 一致：独立提现页 = 普通提现页精简版，收款字段相同，仅差： - -| 字段 | 普通提现 | Free Credits 第一档 | -|------|----------|----------------------| -| `amount` | 用户输入 | **不传**，服务端取 package | -| `package_id` | 无 | **必填** | - -因此用 **同一 `POST /api/withdraw/apply` + 可选 `package_id`** 区分业务是合理契约。 - ---- - -## 为什么不能「整段并入」WithdrawService::apply - -[`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) 当前顺序（L164–219）： - -1. `checkBankInfo` -2. **`checkInfo`（校验钱包 withdraw 余额 ≥ amount）** -3. 黑规则、`getAmountAndFee`（手续费） -4. `PayService::apply` - -Free Credits 第一档资金在**活动池**，不在普通 `withdraw` 余额。若在中间插入 `firstCashout` 而不 **early return**，会先被 `checkInfo` 打成 `Insufficient balance`（评审计划已记录为 P0）。 - -此外 FC 固定规则与普通提现不同： - -| 项 | 普通提现 | FC 第一档 | -|----|----------|-----------| -| 金额来源 | 用户 `amount` | `package->amount_qf` | -| 手续费 | `getAmountAndFee` | **0** | -| 审核 | 动态 `getAuditType` + 黑规则 | **auditType=2** | -| 钱包冻结 | 有 | **无**（pay 侧 bizType 分支） | -| 活动状态 | 无 | `markFirstCashoutProcessing` / 失败回滚 | -| Pay 失败回滚 | 钱包解冻 | **`handleFirstCashoutResult` 恢复 ready** | - -这些差异属于 **Logic 编排**，符合 [`backend-layering`](file:///Users/ray/.cursor/rules/backend-layering.mdc)：不应把 `FreeCreditsLogic` 整段搬进 `WithdrawService` 当「又一层 Service」。 - ---- - -## 推荐合并结构 - -```mermaid -flowchart TB - Client["POST /api/withdraw/apply"] - Client --> Branch{package_id 存在?} - Branch -->|否| Normal["WithdrawService::apply 原逻辑"] - Branch -->|是| FC["WithdrawService::applyFreeCreditsFirstCashout"] - FC --> Mark["FreeCreditsLogic::markFirstCashoutProcessing"] - FC --> Pay["PayService::apply bizType=free_credit_first_cashout"] - Normal --> Pay2["PayService::apply 普通"] - Pay --> PayEntity["slot_pay WithdrawalOrderEntity"] - Pay2 --> PayEntity -``` - -### 合并层（推荐做） - -1. **[`WithdrawController::apply`](slot_console/app/api/controller/WithdrawController.php)** - - 有 `package_id` → 走 FC 分支（或 DTO 带 `package_id` 后交给 Service early return） - - 无 `package_id` → 现有普通提现 - -2. **[`WithdrawValidator`](slot_console/app/api/validator/WithdrawValidator.php)** - - 新增 FC scene：与普通 apply 对称，把 `amount` 换成 `package_id`（`SCENE_APPLY_CASH_FC` 等） - -3. **[`WithdrawApplyDTO`](slot_console/app/api/dto/request/WithdrawApplyDTO.php)** - - 增加可选 `package_id` - -4. **绑卡** - - FC 复用 `WithdrawService::checkBankInfo`（当前 `firstCashout` 只读绑卡、不写库，合并后应对齐普通提现） - -5. **[`FreeCreditsController::firstCashout`](slot_console/app/api/controller/FreeCreditsController.php)** - - 保留为 **兼容 alias**（内部转调 withdraw apply），或标记 deprecated - -### 保持分离（必须） - -- [`FreeCreditsLogic`](slot_console/app/api/logic/FreeCreditsLogic.php)：`markFirstCashoutProcessing`、`handleFirstCashoutResult`、package 状态机、`assertEligibleParticipant` -- [`WithdrawService::applyFreeCreditsFirstCashout`](slot_console/app/service/WithdrawService.php)（新建私有方法）： - - 跳过 `checkInfo`、黑规则、`getAmountAndFee` - - `amount = package->amount_qf`，`fee = 0`，`auditType = 2` - - try/catch Pay，失败时 `handleFirstCashoutResult($orderId, false)` - -### 已统一、无需再改 - -- **slot_pay**：`bizType` / `remark` 分支（跳过冻结、Success/Fail/Rejected → Console MQ） -- **slot_console EventBus**：`FreeCreditsFirstCashoutSuccess/Fail/Rejected` → `handleFirstCashoutResult` - ---- - -## 不推荐的做法 - -在 [`WithdrawService::apply`](slot_console/app/service/WithdrawService.php) 中间写： - -```php -$this->checkInfo(...); -// ... -if ($package_id > 0) { - (new FreeCreditsLogic())->firstCashout(...); -} -$amountInfo = $this->getAmountAndFee(...); -PayService::apply(...); -``` - -会导致：余额校验失败、手续费错误、Pay 失败不回滚档位（processing 卡死）。 - ---- - -## 与「单独提现」需求的关系 - -| 需求 | 合并后是否满足 | -|------|----------------| -| 不进入普通钱包（§15.3） | 是，仍靠 pay `bizType` | -| 固定第一档金额（§11.3） | 是，服务端取 package | -| 处理中不可重复提交（§5.6） | 是，仍由 package status 控制 | -| 成功/失败/拒绝状态（§20.2） | 是，回调逻辑不变 | - -合并的是 **HTTP 入口与收款参数校验**，不是改掉「独立提现」的账务语义。 - ---- - -## 实施要点（若执行） - -1. `WithdrawApplyDTO` 增加 `package_id` -2. `WithdrawService::apply` 在绑卡 + Redis 频控后 **early return** 到 `applyFreeCreditsFirstCashout` -3. FC 分支内：先 `markFirstCashoutProcessing`，再 Pay，catch 回滚 -4. 单测：FC 在 `withdraw=0` 时可提交；Pay 失败 package 回 ready；普通 apply 无回归 -5. 文档：`/api/free-credits/first-cashout` → 指向 `/api/withdraw/apply` + `package_id` - ---- - -## 验收清单 - -- `package_id>0` 且钱包可提现余额为 0：可成功提交 pay -- pay 申请失败：package 回到 `ready`，可重试 -- pay 回调成功：package `completed`，player `FIRST_CASH_DONE` -- 不传 `package_id`：普通提现与现网一致 -- pay 订单 `remark` 仍为 `free_credit_first_cashout`，不触发 `withdrawFrozen` diff --git a/plans/firstcashout_合并评估_df95dacf.plan.md b/plans/firstcashout_合并评估_df95dacf.plan.md deleted file mode 100644 index b45836a..0000000 --- a/plans/firstcashout_合并评估_df95dacf.plan.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: firstCashout 合并评估 -overview: 客户端入参与普通提现几乎一致（仅多 package_id、不传 amount），推荐在 WithdrawController::apply 做薄入口合并并复用 WithdrawValidator；编排仍留 FreeCreditsLogic，不并入 WithdrawService::apply 内部。 -todos: - - id: merge-withdraw-entry - content: WithdrawController::apply 增加 package_id 分支，委托 FreeCreditsLogic::firstCashout；复用 WithdrawValidator 新增 scene（type 1/2/3/6 + package_id，无 amount） - status: completed - - id: align-bank-persist - content: firstCashout 改为复用 WithdrawService::checkBankInfo（或抽 helper），与普通提现一致写绑卡信息 - status: completed - - id: deprecate-fc-endpoint - content: /api/free-credits/first-cashout 保留作兼容 alias 或标记 deprecated，文档指向 /api/withdraw/apply?package_id= - status: completed - - id: keep-logic-split - content: FreeCreditsLogic 仍负责 package 状态机 + bizType；WithdrawService::apply 不增加 Free Credits 分支 - status: completed -isProject: false ---- - -# firstCashout 合并进现有提现接口 — 修订评估 - -## 用户反馈：客户端参数基本一致 - -对照 [`WithdrawValidator`](slot_console/app/api/validator/WithdrawValidator.php) 与 [`FreeCreditsValidator::SCENE_FIRST_CASHOUT`](slot_console/app/api/validator/FreeCreditsValidator.php)： - -| 字段 | 普通提现 apply | Free Credits firstCashout | -|------|----------------|---------------------------| -| `type` | require (1/2/3/6) | require (1/2/3/6) | -| `pay_net` | require (1/2/3) | Logic 使用，Validator scene 未含（可补齐） | -| `user_name` / `cash_tag` | type=1 时 require | post 传入，Logic 读取 | -| `btc` / `usdt` | type=2/3 时 require | 同上 | -| `paypal_*` / `email` | type=6 时 require | 同上 | -| `amount` | **require，用户输入** | **不传，服务端取 package 金额** | -| `package_id` | 无 | **require，活动档位 id** | - -**结论**：C 端独立提现页（需求 §11）本来就是对普通提现页的精简——同一套收款字段，只是隐藏 amount 输入框。从接口契约看，**完全可以用同一个 apply 入口**，用 `package_id` 有无区分业务类型。 - ---- - -## 仍建议合并的范围：入口 + 校验 + 组单，不是 WithdrawService 内部 - -```mermaid -flowchart TB - Client["C 端 POST /api/withdraw/apply"] - Client --> Branch{package_id 存在?} - Branch -->|是| FC["FreeCreditsLogic::firstCashout"] - Branch -->|否| WS["WithdrawService::apply"] - FC --> Pay["PayService::apply bizType=free_credit_first_cashout"] - WS --> Pay2["PayService::apply 普通"] - Pay --> PayEntity["WithdrawalOrderEntity::apply 已统一"] - Pay2 --> PayEntity -``` - -### 可以合并（推荐） - -1. **统一入口**：[`WithdrawController::apply`](slot_console/app/api/controller/WithdrawController.php) 检测 `package_id`，有则委托 `FreeCreditsLogic::firstCashout`，无则走 `WithdrawService::apply`。 -2. **统一校验**：在 `WithdrawValidator` 新增 scene，与普通 apply 对称，仅把 `amount` 换成 `package_id`： - - `SCENE_APPLY_CASH_FC` => `['package_id', 'type', 'user_name', 'cash_tag']` - - `SCENE_APPLY_BTC_FC` => `['package_id', 'type', 'btc']` - - 等 -3. **统一绑卡写库**：`firstCashout` 目前只读 `UserBankCardModel`；普通提现通过 `WithdrawService::checkBankInfo` 会更新绑卡。合并入口后应 **复用同一绑卡逻辑**，避免两套行为。 -4. **统一 DTO**：`WithdrawApplyDTO` 增加可选 `package_id` 字段即可，不必维护两套 post 结构。 - -### 不应合并进 WithdrawService::apply - -编排差异仍在 Logic 层，不应塞进 [`WithdrawService::apply`](slot_console/app/service/WithdrawService.php)： - -| 仍分离的逻辑 | 原因 | -|-------------|------| -| 金额 | 普通：用户 amount；FC：package->amount_qf | -| 余额/手续费/VIP/黑规则 | 普通：checkInfo + getAmountAndFee；FC：跳过 | -| 活动状态 | FC：markFirstCashoutProcessing / 失败回滚 | -| pay 回调 | 已通过 bizType 在 pay 层分支，无需 console 再分 | - ---- - -## 推荐实现（修订后方案 B） - -[`WithdrawController::apply`](slot_console/app/api/controller/WithdrawController.php)： - -```php -public function apply(Request $request) -{ - $post = $request->post(); - $type = input('type', 1); - - if (!empty($post['package_id'])) { - // 复用 WithdrawValidator 的 FC scene（无 amount） - $error = $this->validate(WithdrawValidator::SCENE_APPLY_CASH_FC /* 按 type */, $post); - if ($error !== true) { - return $this->errorCode(ErrorCode::PARAMS_ERROR, $error); - } - return $this->success( - (new FreeCreditsLogic())->firstCashout( - $request->userEntity->uid, - (int) $post['package_id'], - $post - ), - 'Submitted successfully! ...' - ); - } - - // 原有普通提现 - $error = $this->validate($type, $post); - // ... -} -``` - -[`FreeCreditsLogic::firstCashout`](slot_console/app/api/logic/FreeCreditsLogic.php) 内部改动： - -- 绑卡：改为调用 `WithdrawService` 的 `checkBankInfo`（需将 `checkBankInfo` 改为 `protected` 公开方法，或抽到 helper）。 -- 其余不变：package 校验、固定金额、`bizType`、状态机。 - -[`FreeCreditsController::firstCashout`](slot_console/app/api/controller/FreeCreditsController.php)： - -- 保留为 **兼容 alias**（内部同样调 Logic），或直接 deprecated 指向 withdraw apply。 - ---- - -## 与初版评估的差异 - -| 初版 | 修订 | -|------|------| -| 方案 A 推荐保持双入口 | **方案 B 升为推荐** — 参数一致，双入口无必要 | -| 强调「参数/校验不同故难合并」 | 参数 **高度重合**，差异仅 `package_id` vs `amount`；校验可共用 Validator scene | -| 合并障碍在入口层 | 合并障碍仅在 **WithdrawService 内部编排**，入口层应合并 | - ---- - -## 验收 - -- C 端独立提现页调用 `POST /api/withdraw/apply`，传 `package_id + type + 收款字段`，**不传 amount** -- 普通提现不传 `package_id`，行为与现网一致 -- Free Credits 仍不走 `withdrawFrozen`，回调仍更新 package/player -- 绑卡信息与走普通 apply 后一致落库 diff --git a/plans/free_credits_activity_edit_454064f6.plan.md b/plans/free_credits_activity_edit_454064f6.plan.md deleted file mode 100644 index c8b3cf0..0000000 --- a/plans/free_credits_activity_edit_454064f6.plan.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -name: free credits activity edit -overview: 在管理后台活动配置编辑表单中为活动类型 11（首充前免费余额定格与分档释放 / Free Credits）增加专属表单分支，并补齐字典与服务端校验；金额输入沿用 type==10 的「美元小数 → 千分位整数」模式，写入 ext_config 的 _qf 后缀键，与 slot_console `FreeCreditsLogic::configAmount()` 的读优先级一致。 -todos: - - id: dict-activity-type-11 - content: 字典 sm_system_dict_data 追加 code='activity_type' 的 value=11 / label='Free Credits（首充前免费余额）'（DB 或字典管理页） - status: completed - - id: edit-vue-type11-form - content: edit.vue 增加 v-if=type==11 的表单块（6 字段 + Banner） - status: completed - - id: edit-vue-skip-goods - content: edit.vue 让 type==11 跳过 goods 区块：扩展 onlyGift / 调整「添加赠送」与 goods 卡片的 v-if - status: completed - - id: edit-vue-submit-conv - content: edit.vue submit() 增加 type==11 的金额 ×1000 写入 _qf 键、清空 goods - status: completed - - id: edit-vue-setform-conv - content: edit.vue setFormData() 增加 type==11 的 _qf ÷1000 回填还原 - status: completed - - id: validate-free-credits-ext - content: ActivityValidate 增加 checkFreeCreditsExt(extConfig) 方法，含必填、非负、max_unlock_per_recharge≥1、first_cash ≤ recharge_unlock 约束 - status: completed - - id: controller-trigger-ext-check - content: ActivityController::save / update 在 checkData 后按 type==11 调用 checkFreeCreditsExt；update 兼容仅改状态请求 - status: completed - - id: verify-end-to-end - content: 本地验证：新建/编辑/必填/业务约束/类型切换/C 端 FreeCreditsLogic 读取 - status: completed -isProject: false ---- - -# Free Credits 活动后台编辑落地计划 - -## 目标 - -让运营在「活动管理」编辑弹窗里选活动类型 `11`（首充前免费余额）时，能直接编辑需求文档第 17 节列出的所有配置项；保存后落到 `s_recharge_gift_config.ext_config` JSON 字段，C 端 `FreeCreditsLogic` 立即生效。 - -## 现状要点 - -- `slot_console` 已实现 `RechargeGiftConfigModel::TYPE_FREE_CREDITS = 11`、`FreeCreditsLogic`、运行时配置读取（`ext_config.{key}_qf` 优先）。 -- `slot_admin` 后端 [ActivityController](backend/slot_admin/app/game/controller/ActivityController.php) 走 `slotLib\services\ActivityService` 透传到 `slot_console innerapi/activity/*`，`ext_config` 已原样落库，**不需要改动 slot_console**。 -- 管理前端 [edit.vue](backend/slot_admin_vue/src/views/game/activity/edit.vue) 现仅对 6 / 9 / 10 做了 `v-if` 分支，`type==11` 无任何 UI；字典 `activity_type` 也无 value=11 条目。 - -## 字段映射（type=11 专属 `ext_config`） - -UI 输入用美元小数，提交时 ×1000 写入 `_qf` 键（与 type==10 模式一致；`FreeCreditsLogic::configAmount()` 优先读 `_qf`）： - -- `win_threshold_qf` ← 首笔赢取门槛（默认 $50） -- `recharge_unlock_amount_qf` ← 累计充值解锁第一档（默认 $50） -- `first_cash_amount_qf` ← 第一档免打码金额（默认 $20） -- `package_amount_qf` ← 后续每档拆分金额（默认 $10） -- `subsequent_min_recharge_qf` ← 解锁下一档单笔充值下限（默认 $10） -- `max_unlock_per_recharge` ← 整数，每笔充值最多解锁档数（默认 1，**不走 _qf**） -- `banner_image` ← Free Play to Go 弹窗 Banner 图片 URL（可空） - -## 改动清单 - -### 1. 字典：追加 `activity_type` value=11 - -在系统管理「字典管理 → activity_type」以有，不需要再执行了 - -### 2. 前端：[backend/slot_admin_vue/src/views/game/activity/edit.vue](backend/slot_admin_vue/src/views/game/activity/edit.vue) - -#### 2.1 增加 type==11 表单块 - -参考 [edit.vue line 108-123](backend/slot_admin_vue/src/views/game/activity/edit.vue) type==10 的写法，新增： - -```vue - -``` - -#### 2.2 让 type==11 跳过 goods 区块 - -- [edit.vue line 60](backend/slot_admin_vue/src/views/game/activity/edit.vue) `onlyGift` computed 追加 `|| formData.type == 11`： - -```js -let onlyGift = computed(() => { - return formData.type == 7 || formData.type == 8 || formData.type == 9 || formData.type == 11; -}) -``` - -- [edit.vue line 125](backend/slot_admin_vue/src/views/game/activity/edit.vue) 把「添加赠送」按钮与下方 `` 的 goods 卡片包成一组条件，排除 type==10 和 type==11： - -```vue - - - - ...goods 卡片... - -``` - -（保留原 type==9 的 exchange 表格 v-if 不变。） - -#### 2.3 `submit()` 中追加 type==11 的金额 ×1000 转换 - -[edit.vue line 370](backend/slot_admin_vue/src/views/game/activity/edit.vue) 类似 type==10 的处理，把 6 个美元字段写到 `_qf` 键，整数字段原样保留： - -```js -if (formData.type === 11) { - const e = data.ext_config || {}; - const toQf = (v) => v === '' || v == null ? undefined : Math.round(Number(v) * 1000); - data.ext_config = { - win_threshold_qf: toQf(e.win_threshold), - recharge_unlock_amount_qf: toQf(e.recharge_unlock_amount), - first_cash_amount_qf: toQf(e.first_cash_amount), - package_amount_qf: toQf(e.package_amount), - subsequent_min_recharge_qf: toQf(e.subsequent_min_recharge), - max_unlock_per_recharge: e.max_unlock_per_recharge == null ? undefined : Math.round(Number(e.max_unlock_per_recharge)), - banner_image: e.banner_image || '', - }; - data.goods = []; -} -``` - -#### 2.4 `setFormData()` 中追加 type==11 的回填还原 - -[edit.vue line 344-351](backend/slot_admin_vue/src/views/game/activity/edit.vue) 仿照 type==10： - -```js -if (data.type === 11 && data.ext_config) { - const e = data.ext_config; - formData.ext_config = { - win_threshold: e.win_threshold_qf != null ? e.win_threshold_qf / 1000 : e.win_threshold, - recharge_unlock_amount: e.recharge_unlock_amount_qf != null ? e.recharge_unlock_amount_qf / 1000 : e.recharge_unlock_amount, - first_cash_amount: e.first_cash_amount_qf != null ? e.first_cash_amount_qf / 1000 : e.first_cash_amount, - package_amount: e.package_amount_qf != null ? e.package_amount_qf / 1000 : e.package_amount, - subsequent_min_recharge: e.subsequent_min_recharge_qf != null ? e.subsequent_min_recharge_qf / 1000 : e.subsequent_min_recharge, - max_unlock_per_recharge: e.max_unlock_per_recharge ?? 1, - banner_image: e.banner_image || '', - }; -} -``` - -### 3. 后端校验：[backend/slot_admin/app/game/validate/ActivityValidate.php](backend/slot_admin/app/game/validate/ActivityValidate.php) - -ThinkValidate 对嵌套 JSON 支持有限，采用「在 Controller 按 `type` 触发额外校验」+「Validate 提供专用方法」的模式，避免污染既有 scene。 - -#### 3.1 ActivityValidate 增加一个公开方法 - -```php -/** - * Free Credits（type=11）专用 ext_config 校验。 - * - * @param array $extConfig 前端提交的 ext_config，金额已 ×1000 写入 _qf 键 - * @throws \think\exception\ValidateException - */ -public function checkFreeCreditsExt(array $extConfig): void -{ - $required = [ - 'win_threshold_qf' => '首笔赢取门槛', - 'recharge_unlock_amount_qf' => '充值解锁门槛', - 'first_cash_amount_qf' => '免打码提现额', - 'package_amount_qf' => '解锁拆分金额', - 'subsequent_min_recharge_qf' => '后续解锁最小充值', - 'max_unlock_per_recharge' => '每笔最多解锁档数', - ]; - foreach ($required as $key => $label) { - if (!isset($extConfig[$key]) || $extConfig[$key] === '' || (int)$extConfig[$key] < 0) { - throw new \think\exception\ValidateException("{$label}必须填写且为非负数"); - } - } - if ((int)$extConfig['max_unlock_per_recharge'] < 1) { - throw new \think\exception\ValidateException('每笔最多解锁档数必须 ≥ 1'); - } - // 业务约束：免打码提现额 ≤ 累计充值解锁门槛 - if ((int)$extConfig['first_cash_amount_qf'] > (int)$extConfig['recharge_unlock_amount_qf']) { - throw new \think\exception\ValidateException('免打码提现额不能超过充值解锁门槛'); - } -} -``` - -#### 3.2 ActivityController save / update 触发 - -[ActivityController::save / update](backend/slot_admin/app/game/controller/ActivityController.php) 在 `checkData()` 之后追加： - -```php -if ((int)input('type') === 11) { - $this->validate->checkFreeCreditsExt((array)input('ext_config', [])); -} -``` - -`update` 里同样判断，且要兼容仅改状态的请求（无 `updateData` 时不校验 ext_config）： - -```php -if (!empty(input('updateData')) && (int)input('type') === 11) { - $this->validate->checkFreeCreditsExt((array)input('ext_config', [])); -} -``` - -### 4. 不需要改的部分 - -- `slot_console` 侧 `ActivityConfigEntity::updateConfig` 已原样写入 `ext_config`，无变更。 -- `Consts::ACTIVITY_TYPE_*` 不必新增 11；C 端已通过 `RechargeGiftConfigModel::TYPE_FREE_CREDITS` 引用。 -- 不新增独立菜单页，复用通用「活动管理」编辑弹窗。 - -## 数据流 - -```mermaid -flowchart LR - edit[edit.vue type=11 form] -->|"美元×1000 → _qf"| save["POST /game/activity/save|update"] - save --> ctrl[ActivityController] - ctrl -->|"checkFreeCreditsExt"| validate[ActivityValidate] - ctrl --> svc[ActivityService HTTP] - svc --> console["slot_console innerapi/activity/update"] - console --> entity[ActivityConfigEntity::updateConfig] - entity --> db["s_recharge_gift_config.ext_config"] - db --> fc["FreeCreditsLogic::configAmount key_qf 优先"] -``` - - - -## 验收 - -- 新建 type=11 活动：填写 6 字段 + Banner，保存成功；DB `ext_config` 是 `*_qf` 整数 + `max_unlock_per_recharge` + `banner_image`。 -- 编辑回填：再次打开同一条活动，美元字段显示为原值（如 50 / 20 / 10），整数字段为 1，Banner 显示已上传图。 -- 必填校验：清空任一必填项保存，返回明确错误信息（如「首笔赢取门槛必须填写且为非负数」）。 -- 业务约束：免打码提现额填 60、充值解锁门槛填 50，保存被拒。 -- 类型切换：type 选 11→1，再切回 11，goods 区块不出现，formData 不污染；保存 type==1 时 `_qf` 字段不会被带到 ext_config。 -- C 端：调 `FreeCreditsLogic::status($uid)`，门槛 / 第一档金额 / 解锁拆分金额能读到刚配的值。 -- type 字典：管理后台编辑弹窗活动类型下拉出现「Free Credits（首充前免费余额）」选项。 - diff --git a/plans/free_credits_release_902566c9.plan.md b/plans/free_credits_release_902566c9.plan.md deleted file mode 100644 index c817343..0000000 --- a/plans/free_credits_release_902566c9.plan.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -name: free credits release -overview: 为“首充前免费余额定格与分档释放”准备开发方案，按钱包账务、充值提现事件、客户端 API、后台配置统计分阶段落地。重点遵循现有后端分层规则，避免把业务编排错误地下沉到 Service。 -todos: - - id: confirm-wallet-fields - content: 按已确认口径使用 deposit_balance + withdraw_balance 作为免费余额 - status: completed - - id: design-schema - content: 设计独立 Free Credits 活动主表、档位明细表、流水关联和旧活动 ID 关联 - status: completed - - id: implement-console-core - content: 在 slot_console 实现活动领域模型、定格、解锁、Claim 和状态查询 Logic - status: pending - - id: wire-recharge - content: 接入 slot_pay/slot_console 充值成功链路并保证首充定格幂等 - status: completed - - id: wire-cashout - content: 实现第一档独立提现订单和回调状态同步 - status: completed - - id: add-console-apis - content: 补充大厅状态、活动入口、后台配置统计相关 API - status: completed - - id: test-acceptance - content: 按需求文档核心规则和账务验收补测试/联调用例 - status: completed -isProject: false ---- - -# 首充前免费余额定格与分档释放开发准备 - -## 目标范围 - -本次需求核心实现应以后端账务和状态机为主，前端展示依赖新增/扩展 API。主要涉及： - -- [`/Users/ray/Documents/project/www/slot/slot_console`](slot_console)：Free Credits 活动领域模型、Pool、档位、状态机、定格/释放/Claim 编排、大厅/提现页接口、活动入口、配置读取、后台统计入口。 -- [`/Users/ray/Documents/project/www/slot/slot_wallet`](slot_wallet)：只提供钱包原子能力，例如余额扣减/入账、钱包流水、Deposit Balance 入账、Y1 流水任务创建；不放活动领域模型和活动状态机。 -- [`/Users/ray/Documents/project/www/slot/slot_pay`](slot_pay)：充值成功异步通知、第一档独立提现订单。 -- [`/Users/ray/Documents/project/www/slot/backend/slot_admin`](backend/slot_admin)：运营后台配置和统计页，如该项目负责管理端。 -- 客户端 UI 由前端人员在其它仓库实现，本仓库只提供后端接口和状态数据。 - -已有统一活动管理表可作为关联来源： - -- `s_common.s_recharge_gift_config`：现有充值赠送活动主表。 -- `recharge_gift_player`：现有充值赠送活动参与玩家表。 - -本需求不直接复用这两张表承载 Free Credits 账务状态，采用独立 Free Credits 表设计，并保留与旧活动 ID 的关联，避免把“首充前免费余额定格”与已有充值赠送活动规则混在同一张参与表里。 - -## 数据表 DDL 草案 - -金额字段建议沿用现有活动表中的 `_qf` 口径，按千分位整数保存，避免小数精度问题。 - -```sql -CREATE TABLE `free_credits_player` ( - `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键', - `activity_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT '关联 s_recharge_gift_config.id', - `uid` bigint unsigned NOT NULL DEFAULT '0' COMMENT '用户ID', - `source` varchar(64) NOT NULL DEFAULT '' COMMENT '渠道', - `model_id` int unsigned NOT NULL DEFAULT '0' COMMENT '游戏模型ID', - `home_withdraw_unlocked` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '首页Withdraw是否已解锁 0否 1是', - `frozen_amount_qf` bigint unsigned NOT NULL DEFAULT '0' COMMENT '首充时定格金额，千分位', - `first_cash_amount_qf` bigint unsigned NOT NULL DEFAULT '0' COMMENT '第一档免打码提现金额，千分位', - `first_recharge_order_id` varchar(64) NOT NULL DEFAULT '' COMMENT '触发定格的首笔充值订单号', - `first_recharge_time` datetime DEFAULT NULL COMMENT '首笔充值成功时间', - `first_cashout_order_id` varchar(64) NOT NULL DEFAULT '' COMMENT '第一档独立提现订单号', - `status` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '主状态 0未开始 1首页已解锁 2已定格 3待充值解锁 4第一档可提现 5第一档提现中 6第一档已提现 7后续释放中 10全部完成', - `completed_time` datetime DEFAULT NULL COMMENT '全部完成时间', - `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', - `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', - PRIMARY KEY (`id`), - UNIQUE KEY `uniq_activity_uid` (`activity_id`,`uid`), - KEY `idx_uid` (`uid`), - KEY `idx_activity_status` (`activity_id`,`status`), - KEY `idx_first_recharge_order` (`first_recharge_order_id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Free Credits用户活动主表'; -``` - -```sql -CREATE TABLE `free_credits_package` ( - `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键', - `player_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT 'free_credits_player.id', - `activity_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT '关联 s_recharge_gift_config.id', - `uid` bigint unsigned NOT NULL DEFAULT '0' COMMENT '用户ID', - `package_no` int unsigned NOT NULL DEFAULT '0' COMMENT '档位序号，从1开始', - `package_type` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '档位类型 1第一档免打码提现 2后续释放档', - `amount_qf` bigint unsigned NOT NULL DEFAULT '0' COMMENT '档位金额，千分位', - `status` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '档位状态 0锁定 1可操作 2处理中 3已完成 4失败 5风控拒绝', - `withdraw_order_id` varchar(64) NOT NULL DEFAULT '' COMMENT '第一档提现订单号', - `claim_biz_id` varchar(64) NOT NULL DEFAULT '' COMMENT '后续档Claim入账幂等业务号', - `unlocked_time` datetime DEFAULT NULL COMMENT '解锁时间', - `claimed_time` datetime DEFAULT NULL COMMENT '领取时间', - `completed_time` datetime DEFAULT NULL COMMENT '完成时间', - `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', - `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', - PRIMARY KEY (`id`), - UNIQUE KEY `uniq_player_package` (`player_id`,`package_no`), - UNIQUE KEY `uniq_claim_biz` (`claim_biz_id`), - KEY `idx_uid_status` (`uid`,`status`), - KEY `idx_activity_status` (`activity_id`,`status`), - KEY `idx_withdraw_order` (`withdraw_order_id`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Free Credits档位明细表'; -``` - -## 建议数据流 - -```mermaid -flowchart TD - preDepositUser["未首充用户"] --> winThreshold["免费余额曾达到门槛"] - winThreshold --> homeUnlocked["首页 Withdraw 解锁"] - preDepositUser --> firstRecharge["任意入口首笔真实充值成功"] - firstRecharge --> freezeFreeCredits["定格当前免费余额"] - freezeFreeCredits --> freeCreditsPool["slot_console 保存 Free Credits Pool 与档位"] - firstRecharge --> walletTotalRecharge["查询钱包累计充值总额"] - walletTotalRecharge --> firstReady["累计充值满门槛释放第一档"] - firstReady --> firstCashout["第一档独立提现"] - firstCashout --> laterPackages["后续档位按充值解锁"] - laterPackages --> claimToWallet["Claim 入 Deposit Balance"] - claimToWallet --> y1Task["创建 Y1 流水任务"] -``` - -## 后端落地方案 - -1. 在 `slot_console` 新增独立 Free Credits 活动领域模型。 - - 新增用户池主表，保存 `activity_id`、`uid`、定格金额、首充订单、主状态、首页解锁标记、完成时间等；主表不保存累计充值。 - - 新增档位明细表，一档一行，保存序号、类型、金额、状态、关联提现单/Claim 流水、解锁/完成时间。 - - `activity_id` 关联现有 `s_common.s_recharge_gift_config` 或后台活动配置 ID，但 Free Credits 的进度、档位和账务状态不写入 `recharge_gift_player`。 - - 表归属按 `slot_console` 现有业务库和活动模块规范处理；`slot_wallet` 不新增 Free Credits 活动表。 - -2. 在 `slot_console` 增加 Logic 编排定格、解锁、Claim。 - - Controller 只做请求接收、Validate、DTO、统一响应。 - - Validate 处理参数必填/类型/枚举。 - - DTO 只承载已校验字段。 - - Logic 负责首充定格、查询钱包累计充值总额、档位状态流转、事务和幂等。 - - Model 负责查询/写入和状态条件更新。 - - Service 仅用于已有公共能力，如调用钱包原子 API、配置读取、外部系统封装，不新增单纯转发 Service。 - - 调用 `slot_wallet` 时只请求余额变更、钱包流水、入 Deposit Balance、创建 Y1 任务等钱包能力，不把活动状态写入钱包服务。 - -3. 接入充值成功链路。 - - 现有充值成功链路在 [`/Users/ray/Documents/project/www/slot/slot_pay/app/command/EventRecharge.php`](slot_pay/app/command/EventRecharge.php) 调用钱包充值入账。 - - 充值成功后由 `slot_pay` 或事件消费者通知 `slot_console`，由 `slot_console` 判断是否首笔真实充值并触发定格。 - - 定格需要调用 `slot_wallet` 原子能力扣减当前免费余额并写钱包流水，再由 `slot_console` 落 Free Credits Pool 和档位。 - - 第一档门槛通过调用钱包查询用户累计充值总额判断；`slot_console` 主表不保存累计充值，也不新增充值事件明细表。 - -4. 实现第一档独立提现。 - - 第一档不进入普通钱包余额，创建独立提现订单类型 `free_credit_first_cashout`。 - - 需要在 `slot_pay` 的提现订单模型/实体中支持新订单类型，提现处理中防重复，成功/失败/拒绝回写档位状态。 - - 第一档提现成功后关闭首页状态条，但活动入口保留到所有档位完成。 - -5. 实现后续档位解锁和 Claim。 - - 后续每笔符合条件真实充值最多解锁下一档，按配置控制最小充值金额和每笔最多解锁档数。 - - Claim 由 `slot_console` 校验档位状态和顺序后，调用 `slot_wallet` 将档位金额入 `Deposit Balance`，创建 Deposit Lot 和 Y1 Wager Task。 - - `slot_console` 负责 Claim 幂等和档位状态流转；`slot_wallet` 负责钱包入账幂等和流水一致性。失败时档位保持 `ready`，重复点击不能重复入账。 - -6. 增加客户端查询与操作 API。 - - 查询用户活动状态：首页状态条、活动入口、Free Play to Go 弹窗需要同一份状态数据。 - - 操作 API：第一档提现、后续 Claim、后续 Unlock 跳充值。 - - `slot_console` 可在 [`/Users/ray/Documents/project/www/slot/slot_console/app/napi/controller/LobbyController.php`](slot_console/app/napi/controller/LobbyController.php) 或独立 API 暴露大厅所需数据。 - -7. 增加后台配置与统计。 - - 配置项优先绑定到现有统一活动管理的活动 ID；Free Credits 专属配置包括活动开关、首笔赢取门槛、充值解锁门槛、免打码提现额、拆分金额、后续最小充值、每笔最多解锁档数、Y1 倍数、Banner。 - - 统计项：定格人数、完成提现人数、全部完成人数、定格总金额、已提现金额、已领取金额、待释放金额。 - - 筛选排序按文档要求实现。 - -## 已确认口径 - -- 免费余额 = `deposit_balance + withdraw_balance`，即钱包余额。 -- 第一档不需要流水，完全绕开普通可提现余额计算。 -- 第一档解锁通过充值成功异步通知驱动，并调用钱包查询累计充值总额判断是否达到门槛。 -- Free Credits 定格逻辑以独立活动配置为准。 -- 客户端 UI 由前端人员处理，本仓库不包含对应页面代码。 - -## 关键风险与需确认点 - -- 文档中的 `Deposite Balance / Deposite Lot` 建议统一确认是否为历史命名还是拼写问题。 - -## 建议开发顺序 - -1. 先实现 `slot_console` 活动数据模型、配置读取、状态机和只读查询接口。 -2. 梳理并补齐 `slot_wallet` 需要暴露的钱包原子能力，包括查询累计充值总额、冻结/扣减免费余额、入 Deposit Balance、创建 Y1 任务和幂等流水。 -3. 接入充值成功链路，完成 `slot_pay` 到 `slot_console` 的事件通知、首充定格和调用钱包累计充值总额解锁第一档。 -4. 实现第一档独立提现链路和提现回调到 `slot_console` 的状态同步。 -5. 实现后续档位解锁、Claim 调用钱包入账和 Y1 流水任务创建。 -6. 补 `slot_console` 大厅/活动入口接口、后台统计、客户端 UI、文案、埋点和验收用例。 \ No newline at end of file diff --git a/plans/free_credits_后台统计页_9d6edc45.plan.md b/plans/free_credits_后台统计页_9d6edc45.plan.md deleted file mode 100644 index ade2b63..0000000 --- a/plans/free_credits_后台统计页_9d6edc45.plan.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -name: free credits 后台统计页 -overview: 实现需求 §18 的 Free Credits 后台统计与展示：在 slot_console 增强 innerapi（加筛选、加列表字段、富化累计充值与档位聚合），slot_lib 新增 FreeCreditsService 并给 WalletService 补一个 statistics 批量方法，slot_admin 新增 FreeCreditsStatsController 代理，slot_admin_vue 新增 views/game/freeCreditsStats/index.vue 一页搞定，顶部统计走 sa-table 的 otherData 模式。 -todos: - - id: slot-console-stats-logic - content: slot_console 新建 innerapi/logic/FreeCreditsStatsLogic.php，封装 statistics + list 的查询编排（含 status>=2 口径、批量 package 聚合 SQL） - status: completed - - id: slot-console-list-enrich - content: slot_console FreeCreditsController::list 加筛选 + 字段富化（first_cash_status / progress / claimed / first_cashout / remaining / total_recharge） - status: completed - - id: slot-console-stats-filter - content: slot_console FreeCreditsController::statistics 加 source / first_recharge_time / status 等筛选；frozen_user_count 改为 status>=2 - status: completed - - id: slot-lib-wallet-stats - content: slot_lib WalletService 新增 statistics(uids, currency) 方法 → 调 /api/wallet/statistics - status: completed - - id: slot-lib-free-credits-service - content: slot_lib 新建 FreeCreditsService（basePath=innerapi/free-credits，含 list + statistics） - status: completed - - id: slot-admin-controller - content: slot_admin 新建 game/controller/FreeCreditsStatsController.php，index 一次调两个 service 合并 otherData 返回 - status: completed - - id: slot-admin-vue-api - content: slot_admin_vue 新建 api/game/freeCreditsStats.js，导出 getPageList - status: completed - - id: slot-admin-vue-page - content: "slot_admin_vue 新建 views/game/freeCreditsStats/index.vue：sa-table + #tableAfterButtons 顶部 7 统计 + 12 列表 + 筛选 + 排序白名单" - status: completed - - id: menu-permission - content: 在 sm_system_menu 加 1 条 L 菜单 + 1 条 B 按钮码（/game/freeCreditsStats/index），并分配角色 - status: completed - - id: manual-verify - content: docker 内 A/B/C 三种玩家手测：默认排序、7 项统计、筛选联动、排序白名单、权限拦截 - status: completed -isProject: false ---- - -## 数据流 - -```mermaid -flowchart LR - vue[freeCreditsStats/index.vue sa-table] - vue -->|"POST /game/FreeCreditsStats/index"| ctrl[FreeCreditsStatsController] - ctrl -->|"FreeCreditsService::list"| svc[slot_lib FreeCreditsService] - ctrl -->|"FreeCreditsService::statistics"| svc - svc -->|"POST innerapi/free-credits/list"| console[slot_console FreeCreditsController] - svc -->|"POST innerapi/free-credits/statistics"| console - console -->|"WalletService statistics uids currency"| wallet["slot_wallet api/wallet/statistics"] - console -->|"sum on free_credits_package"| db[(s_common.free_credits_player + free_credits_package)] -``` - -slot_admin Controller 一次代理两个 innerapi，合并成 `{ data, total, otherData: }` 给 sa-table，避免前端两次请求。 - -## 字段契约（最终对外） - -### `/game/FreeCreditsStats/index` 请求 - -筛选（与 §18.3 对齐） - -- `uid` 精确 -- `source` 字符串（沿用 channel_game_model + source 二级选择） -- `activity_id` 可选（默认取当前生效的 type=11 活动） -- `first_recharge_time` 范围 `[start, end]` → `whereBetween` -- `status` 数组（player.status：0/1/2/3/4/5/6/7/10） -- `first_cash_status` 数组（package.status：0/1/2/3/4/5，限定 `package_no=1`） -- `is_completed` 0/1（status=10 与否） -- `page`, `limit`, `orderBy`, `orderType` - -排序 - -- DB 可排序：`frozen_amount_qf`、`first_recharge_time`（默认 `first_recharge_time desc`） -- 其它字段（进度、剩余、累计充值）派生，前端不开启排序 - -### 响应 - -```json -{ - "data": [{ - "uid": 123, - "source": "us_01", - "frozen_amount_qf": 78500, - "first_cash_amount_qf": 20000, - "total_recharge_amount_qf": 30000, - "first_cash_status": 3, - "progress_done": 3, - "progress_total": 7, - "status": 7, - "remaining_amount_qf": 28500, - "claimed_amount_qf": 30000, - "first_recharge_time": "2026-05-12 11:23:01", - "completed_time": null - }], - "total": 240, - "otherData": { - "frozen_user_count": 240, - "first_cashout_user_count": 180, - "completed_user_count": 35, - "frozen_amount_qf": 18650000, - "first_cashout_amount_qf": 3520000, - "claimed_amount_qf": 8800000, - "pending_amount_qf": 6330000 - } -} -``` - -金额字段一律以 `*_qf`（千分位整数）传到 Vue，Vue 用 `/ 1000` + `toFixed(2)` 显示（与 edit.vue 同口径）。 - ---- - -## 改动清单 - -### 1. slot_console — 增强 innerapi - -文件：[slot_console/app/innerapi/controller/FreeCreditsController.php](slot_console/app/innerapi/controller/FreeCreditsController.php) - -#### 1.1 `statistics()` 加筛选 - -参照需求 §18.1，新增可选参数并贯穿到所有子查询： - -- `activity_id`、`source`、`first_recharge_time_start`、`first_recharge_time_end`、`uid` -- 子查询 `frozenTotal / completedCount / firstCashoutCount / firstCashoutAmount / claimedAmount` 全部基于同一个 `playerIds` 数组（按筛选后取出） -- `frozen_user_count` 口径改为 `status >= STATUS_FROZEN(2)` 的玩家数（与需求 "已创建 Free Credits Pool" 一致；当前实现把 status=1 也计入，定义不准） - -#### 1.2 `list()` 加筛选 + 字段富化 - -- 新增筛选参数：`source`、`first_recharge_time` 范围、`status[]`、`first_cash_status[]`、`is_completed`、`orderBy/orderType`（白名单：`first_recharge_time`, `frozen_amount_qf`） -- 输出每行追加： - - `first_cash_status`：对应 `free_credits_package.status` where `player_id=? AND package_no=1` - - `progress_done` / `progress_total`：`SUM(CASE WHEN status=3 THEN 1 ELSE 0 END)` / `COUNT(*)`，一次 `GROUP BY player_id` 跑完 - - `claimed_amount_qf`：`SUM(amount_qf) WHERE package_type=2 AND status=3 GROUP BY player_id` - - `first_cashout_amount_qf`：`SUM(amount_qf) WHERE package_type=1 AND status=3 GROUP BY player_id` - - `remaining_amount_qf`：`frozen_amount_qf - first_cashout_amount_qf - claimed_amount_qf` - - `total_recharge_amount_qf`：调用 `WalletService::statistics(uids, currency='USD')`，把 `total_deposit` 映射进来。currency 默认 'USD'（活动只面向美国 RMG，currency 字段后续如多币种再扩展） -- 一次性聚合查询，避免 N+1： - -```text -SELECT player_id, - SUM(CASE WHEN status=3 THEN 1 ELSE 0 END) AS progress_done, - COUNT(*) AS progress_total, - SUM(CASE WHEN package_type=1 AND status=3 THEN amount_qf ELSE 0 END) AS first_cashout_amount_qf, - SUM(CASE WHEN package_type=2 AND status=3 THEN amount_qf ELSE 0 END) AS claimed_amount_qf, - MAX(CASE WHEN package_no=1 THEN status END) AS first_cash_status -FROM s_common.free_credits_package -WHERE player_id IN (...) -GROUP BY player_id -``` - -#### 1.3 控制器分层 - -按 backend-layering 规则，把 1.1 / 1.2 的查询编排沉到 Logic：新增 [slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php](slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php)（或直接挂在已有 `api/logic/FreeCreditsLogic.php`，建议新建避免膨胀），Controller 只负责接参 / 调 Logic / 返回。 - ---- - -### 2. slot_lib — 新增 FreeCreditsService + 补 WalletService - -#### 2.1 [slot_lib/src/services/FreeCreditsService.php](slot_lib/src/services/FreeCreditsService.php) 新建 - -```php -class FreeCreditsService extends BaseApiService -{ - use SingletonService; - protected $hostKey = 'consoleApiHost'; - protected $basePath = 'innerapi/free-credits'; - - public function statistics(array $params) { return $this->postAction('statistics', $params); } - public function list(array $params) { return $this->postAction('list', $params); } -} -``` - -理由：不与既有 `ActivityService::join/add/update` 混杂；basePath 完全独立，匹配 slot_console 的路由。 - -#### 2.2 [slot_lib/src/services/WalletService.php](slot_lib/src/services/WalletService.php) 补 `statistics` - -```php -public function statistics(array $uids, string $currency) -{ - return $this->postAction('statistics', ['uids' => $uids, 'currency' => $currency]); -} -``` - -action 名 `statistics`，URL `{walletApiHost}/api/wallet/statistics`，对应 slot_wallet `WalletController::statistics`。slot_console 侧 `FreeCreditsStatsLogic` 调用此方法。 - ---- - -### 3. slot_admin — 新增代理 Controller - -文件：[backend/slot_admin/app/game/controller/FreeCreditsStatsController.php](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) - -只做接参 + Service 调用 + 合并： - -```php -class FreeCreditsStatsController extends AdminController -{ - public function index(Request $request): Response - { - $params = $request->all(); - $params['page'] = (int)$request->get('page', 1); - $params['limit'] = (int)$request->get('limit', 20); - - $list = FreeCreditsService::getInstance()->list($params); - $stats = FreeCreditsService::getInstance()->statistics($params); - - $list['otherData'] = $stats; - return $this->success($list); - } -} -``` - -- 不需要 Validate（参数全部可选；非法值 slot_console 侧拦） -- 自动路由路径 `/game/freeCreditsStats/index` -- 不新增 `export()` action（V1 不做导出） - ---- - -### 4. slot_admin_vue — 新页 + API - -#### 4.1 [backend/slot_admin_vue/src/api/game/freeCreditsStats.js](backend/slot_admin_vue/src/api/game/freeCreditsStats.js) 新建 - -```js -import request from '@/utils/request' -const url = '/game/freeCreditsStats' -export default { - getPageList: (params) => request.get(`${url}/index`, params), -} -``` - -#### 4.2 [backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue) 新建 - -骨架仿 `views/game/order/recharge/index.vue`： - -- `defineOptions({ name: 'game/freeCreditsStats/index' })` -- `` `options.api = api.getPageList`，`options.add` / `options.delete` 关闭 -- `searchForm`：`uid`、`source`（用 `commonStore.allSourcesOptionsNoAll`）、`first_recharge_time`（`a-range-picker`）、`status`、`first_cash_status`、`is_completed` -- 顶部统计走 `#tableAfterButtons`： - -```vue - -``` - -- `stats = computed(() => crudRef.value?.getTableOtherData() ?? {})` -- 列定义：12 列对齐 §18.2；`status`、`first_cash_status` 直接用前端 map 表（不新建字典）： - -```js -const PLAYER_STATUS_MAP = { - 0: '未触发', 1: 'Home Withdraw 已解锁', 2: '已定格', 3: '充值进行中', - 4: '第一档可提现', 5: '第一档处理中', 6: '第一档已提现', - 7: '后续档释放中', 10: '全部完成', -} -const PACKAGE_STATUS_MAP = { - 0: '未解锁', 1: '可操作', 2: '处理中', 3: '已完成', 4: '失败', 5: '已拒绝', -} -``` - -- `qfToDollar = (v) => ((Number(v||0))/1000).toFixed(2)` -- 不再调单独的 stats 接口，`tableAfterButtons` 数据从 `otherData` 取 - ---- - -### 5. 字典与菜单 - -#### 5.1 字典：不新增 - -`status` / `first_cash_status` 直接走前端 map 表，避免与 `RechargeGiftConfigModel` 共用字典污染。 - -#### 5.2 菜单：DB 表 `sm_system_menu` 追加（运营在「系统管理 → 菜单管理」操作即可） - -需要的 2 条数据（指引性 SQL，实际可走 UI）： - -```sql -INSERT INTO sm_system_menu (parent_id, type, title, name, path, component, sort) - VALUES (, 'L', 'Free Credits 统计', - 'game/freeCreditsStats/index', '/game/freeCreditsStats', - 'game/freeCreditsStats/index', 50); -INSERT INTO sm_system_menu (parent_id, type, title, code) - VALUES (, 'B', '列表', '/game/freeCreditsStats/index'); -``` - -写完后给「超级管理员 / 运营」角色分配该菜单与按钮码。 - ---- - -## 不动的地方 - -- `slot_console` 既有 `FreeCreditsLogic` C 端逻辑、`free_credits_player` / `free_credits_package` 表结构、`ext_config` 配置读取等不动 -- `s_recharge_gift_config` 不需要新增列 -- `slot_pay` 不新增 innerapi（不需要订单表精确口径，wallet `total_deposit` 已足够） -- 现有 `ActivityController` 编辑表单（type=11 分支）已落地，不动 -- `RechargeOrderController` / `withdrawal` 等无关模块不动 - -## 验收（手测） - -按 [dev-environment](.cursor/rules/dev-environment.mdc) 在 docker 内调试： - -1. 准备 3 个测试账号：A 未定格、B 已定格未提现首档、C 全部完成；各 source 至少一个 -2. 访问 `/game/freeCreditsStats` 列表： - - 不传参 → 默认按 `first_recharge_time desc`，A 不出现（status<2 被过滤），B / C 都在 - - 顶部 7 个统计数字与逐条手算结果一致 - - 列表里 `total_recharge_amount_qf` 与 `slot_wallet.api/wallet/statistics` 直接拉的 `total_deposit` 一致 - - `progress_done/total` 等于 DB 中 `free_credits_package` 实际行数 -3. 筛选： - - 选 `source=us_01` 列表与统计同步收敛 - - 选 `first_recharge_time` 范围，统计 7 项随之变化 - - 选 `is_completed=1`，列表只剩 C - - 选 `first_cash_status=3`，列表只剩第一档已成功的玩家 -4. 排序：分别点击「定格金额」「定格时间」列头，order 切换；其它字段不可排序 -5. 权限：用未授权账号访问 → 403；授权后正常 -6. 仅改活动状态时（已存在的活动编辑场景）回归一遍，确认未触发 type=11 ext 校验路径回归 \ No newline at end of file diff --git a/plans/free_credits_老用户隐藏评审_1c0ab623.plan.md b/plans/free_credits_老用户隐藏评审_1c0ab623.plan.md deleted file mode 100644 index 53482d9..0000000 --- a/plans/free_credits_老用户隐藏评审_1c0ab623.plan.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -name: Free Credits 老用户隐藏评审 -overview: EventBus 写库确定参加、status 只读展示；在此基础上用环境变量 FREE_CREDITS_ENROLL_REG_AFTER 做注册时间门槛——regTime 晚于该时间的用户才有资格参加，否则一律 status=-1 且 EventBus 跳过写池。 -todos: - - id: env-reg-cutoff - content: 新增 FREE_CREDITS_ENROLL_REG_AFTER 环境变量与 FreeCreditsLogic::isEligibleByRegTime(uid) 统一门禁 - status: completed - - id: apply-gate-all-paths - content: 在 status、syncHomeWithdrawUnlocked、handleFreeCreditInit、advanceAfterRecharge、claim、firstCashout 入口应用注册时间门禁 - status: completed - - id: fix-docs-lobby - content: 修正 FreeCreditsController PHPDoc（含 status=-1 含老用户/未达注册门槛）；LobbyController 清理无用 import - status: completed - - id: guard-claim-cashout - content: 无资格或无 player 时 claim/firstCashout 返回明确业务错误 - status: completed - - id: verify-reg-cutoff - content: 联调：regTime 早于门槛 status=-1 且 EventBus 不建池；晚于门槛走 win/首充完整流程 - status: completed -isProject: false ---- - -# Free Credits 老用户隔离：注册时间门槛（计划） - -## 目标 - -C 端全量更新后，**注册时间早于活动上线节点的用户视为老用户，不参加、不展示**；**注册时间晚于该节点的新用户**，在现有「EventBus 写库 = 参加」模型下正常走活动。 - -「默认参加」含义：**有资格参加**（EventBus 允许建池、status 可读），**不是**无需 EventBus 自动插入 `free_credits_player`。 - ---- - -## 分层架构（保持不变） - -```mermaid -flowchart TB - gate{regTime > FREE_CREDITS_ENROLL_REG_AFTER?} - gate -->|否| block[不参加: status=-1 EventBus return] - gate -->|是| eligible[有资格] - eligible --> win[EventBus syncHomeWithdrawUnlocked] - eligible --> init[EventBus free_credit_init] - eligible --> api[status 只读 player 行] - win --> pool[(free_credits_player)] - init --> pool - api --> pool -``` - -| 路径 | 行为 | -| --- | --- | -| **读** `status()` | 未达注册门槛 → `status=-1`；达门槛且无 player 行 → `-1`；有行 → `buildStatus` | -| **写** EventBus | 未达注册门槛 → 各 Logic 方法开头直接 return，不建池、不定格、不推进 | - ---- - -## 实现要点 - -### 1. 环境变量 - -在 [`.env`](slot_console/.env) / 部署说明中增加（示例）： - -```env -# 用户注册时间（Unix 或 Y-m-d H:i:s，建议与 TIMEZONE 一致）晚于此值才可参加 Free Credits -FREE_CREDITS_ENROLL_REG_AFTER=2026-05-20 00:00:00 -``` - -- 在 [`config/app.php`](slot_console/config/app.php) 或新建 `config/free_credits.php` 读取：`getenv('FREE_CREDITS_ENROLL_REG_AFTER')`，`strtotime` 解析为 `enroll_reg_after_ts`（启动时或首次调用缓存）。 -- **未配置时的默认策略（已确认）**：`FREE_CREDITS_ENROLL_REG_AFTER` 为空或未配置 → **全员不参加**（`isEligibleByRegTime` 恒 false，`status=-1`，EventBus 不写池）。 - -### 2. 统一门禁方法（建议放在 [`FreeCreditsLogic`](slot_console/app/api/logic/FreeCreditsLogic.php)） - -```php -/** - * 是否具备 Free Credits 参与资格（注册时间晚于环境变量门槛）。 - */ -protected function isEligibleByRegTime(int $uid): bool -{ - $cutoff = self::enrollRegAfterTimestamp(); // 0 表示未配置 - if ($cutoff <= 0) { - return false; - } - - $userInfo = \app\service\user\UserService::getUserInfoEntity($uid); - if ($userInfo === null || $userInfo->create_at === '') { - return false; - } - - $regTime = strtotime($userInfo->create_at); - return $regTime !== false && $regTime > $cutoff; // 严格「晚于」 -} -``` - -- **数据来源**：[`app\service\user\UserService::getUserInfoEntity`](slot_console/app/service/user/UserService.php)（调 user 服 `/innerapi/user/info`），与 [`EventBus::registerEvent`](slot_console/app/command/EventBus.php) 等同用法。 -- **注册时间字段**：[`app\entity\UserInfoEntity::$create_at`](slot_console/app/entity/UserInfoEntity.php)（`Y-m-d H:i:s`），比较前 `strtotime` 为 Unix 秒。 -- **不用** `UserTagService::tagInfo->regTime`（标签缓存，与账号创建时间可能不一致）。 -- 备选：若 Logic 内已大量使用 slotLib，可用 `\slotLib\services\UserService::getInstance()->setUid($uid)->getUserInfo()?->regTime`（构造函数内由 `create_at` 解析），但 console 侧优先统一 `app\service\user\UserService`。 - -### 3. 调用点（读写对称） - -| 方法 | 未达门槛时 | -| --- | --- | -| `status()` | 直接 `return ['status' => -1]` | -| `syncHomeWithdrawUnlocked()` | `return null` | -| `handleFreeCreditInit()` | `return` | -| `advanceAfterRecharge()` | `return` | -| `claim()` / `firstCashout()` | `throw BusinessException('...')` 或统一文案 | - -**说明**：已达门槛、但库中无 player 行 → 仍为 `status=-1`（尚未被 EventBus 纳入）；达门槛且 win 后 → EventBus 建池 → status 非 `-1`。 - -### 4. 与「已首充」的关系 - -- 注册门槛解决：**老账号 / 老注册** 不进入活动。 -- 钱包侧 [`maybeSendFreeCreditInit`](slot_wallet/app/api/logic/WalletLogic.php) 仍仅 **首充** 发定格，二者叠加，互不替代。 - -### 5. 撤销项 - -- 不再单独做 `total_deposit == 0` 的 EventBus 门禁（由注册时间门槛覆盖「老用户」定义）。 -- 不再要求 `frozen_amount > 0` 才展示（保留 HOME_UNLOCKED 阶段）。 - -### 6. 文档与测试 - -- 更新 [`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php)：`status=-1` = 未参加 / 活动关 / **注册时间早于门槛**。 -- 单测：mock `regTime` 与 env cutoff，覆盖 eligible / ineligible 的 status 与 freeze 是否被调用。 -- 联调矩阵见下。 - ---- - -## 联调矩阵 - -| regTime vs 门槛 | win 达门槛 | 首充定格 | status | EventBus 建池 | -| --- | --- | --- | --- | --- | -| 早于 | - | - | `-1` | 否 | -| 晚于 | 否 | 否 | `-1` | 否 | -| 晚于 | 是 | 否 | `1` | sync 建池 | -| 晚于 | - | 是 | `3/4` + packages | freeze | - ---- - -## 新 C 端约定（不变） - -- **`status === -1`**：隐藏（含老用户、未达注册门槛、未参加）。 -- **`status !== -1`**：已参加，按 `FreeCreditsPlayerModel` 状态渲染。 diff --git a/plans/free_credits_验收核查_c1eade6d.plan.md b/plans/free_credits_验收核查_c1eade6d.plan.md deleted file mode 100644 index 9c98332..0000000 --- a/plans/free_credits_验收核查_c1eade6d.plan.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -name: Free Credits 验收核查 -overview: 「首充前免费余额定格与分档释放」的后端核心链路（定格、分档、首档提现、后续 Claim、充值事件、钱包账务）已在 slot_console / slot_wallet / slot_pay / slot_lib 落地约 70–80%，但尚未达到需求文档 V1.0 全量验收标准；运营后台、客户端 UI、广播、异常风控、部分 API 字段与自动化测试仍缺失或未对齐。 -todos: - - id: p0-wallet-atomicity - content: 补齐 Claim+Y1 原子性/回滚；确认是否需要 Deposit Lot - status: pending - - id: p0-status-api-fields - content: status/buildStatus 增加 total_recharge、show_home_status_bar、show_activity_entry - status: pending - - id: p0-peak-balance - content: 首页解锁「曾达到门槛」：增加峰值记录或可靠触发点 - status: pending - - id: p1-admin-config-stats - content: slot_admin 增加 type=11 配置页与统计页（对接 innerapi） - status: pending - - id: p1-refund-risk - content: 实现充值退款/拒付暂停未释放档位（文档 20.1） - status: pending - - id: p2-frontend-broadcast - content: 前端仓实现 UI/广播；本仓可增加 broadcast API - status: pending - - id: p2-tests - content: 按文档 22.1/22.2 补充自动化或验收用例 - status: pending -isProject: false ---- - -# 首充前免费余额定格与分档释放 — 实现完成度核查 - -**结论：未实现完。** 后端主流程可联调，但对照 [需求文档](file:///Users/ray/Documents/project/www/slot/docs/requirements/首充前免费余额定格与分档释放需求文档.md) 第 22 节验收标准，仍有若干 **P0 账务/规则缺口** 与大量 **前端/运营/统计** 范围未覆盖。 - ---- - -## 实现分布（已落地） - -```mermaid -flowchart TB - subgraph console [slot_console] - RechargeEvent --> FreeCreditsLogic - EventBus --> FreeCreditsLogic - FreeCreditsLogic --> DB[(free_credits_player/package)] - ApiCtrl[FreeCreditsController] --> FreeCreditsLogic - Lobby[LobbyController.frontData] --> FreeCreditsLogic - Inner[innerapi FreeCreditsController] --> DB - end - subgraph wallet [slot_wallet] - FreeCreditsLogic --> WalletLogic - WalletLogic --> freeze[freeCreditsFreeze] - WalletLogic --> claim[freeCreditsClaim] - claim --> Y1[createTask SOURCE_TYPE_FREE] - end - subgraph pay [slot_pay] - firstCashout[firstCashout API] --> WithdrawalOrder - WithdrawalOrder --> MQ[FreeCreditsFirstCashout*] - MQ --> EventBus - end -``` - -| 模块 | 关键文件 | 覆盖的需求章节 | -|------|----------|----------------| -| 领域与状态机 | [FreeCreditsLogic.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/logic/FreeCreditsLogic.php) | 5.3–5.9 核心规则 | -| 数据表 | [install.sql](file:///Users/ray/Documents/project/www/slot/slot_console/db/install.sql) L36–86 | 活动池 + 档位 | -| 活动配置 | [RechargeGiftConfigModel.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/model/common/RechargeGiftConfigModel.php) `TYPE_FREE_CREDITS=11` | 17 配置（读库） | -| 客户端 API | [FreeCreditsController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/controller/FreeCreditsController.php) | status / claim / firstCashout | -| 大厅聚合 | [LobbyController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/napi/controller/LobbyController.php) `free_credits` | 7 状态条数据源（部分） | -| 充值事件 | [RechargeEvent.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/event/RechargeEvent.php) | 5.3 首充定格、5.5 累计充值解锁 | -| 首页解锁 | [EventBus.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/EventBus.php) win/bonus 等 → `syncHomeWithdrawUnlocked` | 5.2 | -| 钱包原子能力 | [WalletLogic.php](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) | 15.2–15.4 | -| 首档提现 | [WithdrawalOrderEntity.php](file:///Users/ray/Documents/project/www/slot/slot_pay/app/entity/WithdrawalOrderEntity.php) + [EventWithdrawal.php](file:///Users/ray/Documents/project/www/slot/slot_pay/app/command/EventWithdrawal.php) | 5.6、15.3、20.2 | -| 运营统计 API | [innerapi/FreeCreditsController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/innerapi/controller/FreeCreditsController.php) | 18.1–18.2（简化版） | - ---- - -## 按需求章节对照（22.1 核心规则） - -| 验收项（文档 22.1） | 实现情况 | 说明 | -|---------------------|----------|------| -| 未达 $50 点 Withdraw 提示 | **前端** | 后端 `status` 返回 `win_threshold` / `home_withdraw_unlocked`，无专用提示 API | -| 曾达 $50 后输回仍解锁 | **部分** | 已解锁用户靠 `home_withdraw_unlocked=1` 保持；**未持久化历史峰值**，仅在 MQ 事件时若 `balance >= threshold` 才写库，存在漏解锁边界（例如达峰后无 win/bonus 类事件即输掉） | -| 任意入口首充定格 | **是** | `RechargeEvent` + `handleRecharge`，`frozenAmount = balance_after - wallet_amount` | -| 首充失败不定格 | **是** | 仅充值成功 MQ 触发 | -| 定格后余额扣除、活动展示 | **是** | `freeCreditsFreeze` + player/package 记录 | -| 累计未满 $50 第一档不可提现 | **是** | 首包 `STATUS_LOCKED` 直至 `wallet.r >= recharge_unlock_amount` | -| 累计满 $50 第一档可提现 | **是** | `advanceByRecharge` 解锁 package_no=1 | -| 定格 < $20 时第一档=定格额 | **是** | `min(frozen, first_cash_amount)` | -| 第一档提现成功后关首页状态条 | **后端未显式字段** | 有 `STATUS_FIRST_CASH_DONE`，但 `buildStatus` **未返回** `show_home_status_bar` 等 UI 开关，需前端自行推断 | -| 后续充值只解锁下一档 | **是** | `max_unlock_per_recharge` + `nextLockedReleasePackage` | -| Claim 入 Deposit + Y1 | **部分** | 入 deposit_balance + `createTask(SOURCE_TYPE_FREE)`；**无 Deposit Lot**（文档 15.4、22.2） | -| 全部完成关活动入口 | **部分** | `STATUS_COMPLETED=10`；API 未返回 `show_activity_entry` 布尔字段 | - ---- - -## 按需求章节对照（22.2 账务） - -| 验收项 | 实现情况 | 风险 | -|--------|----------|------| -| 定格有钱包流水 | **是** | `BIZ_TYPE_FREE_CREDITS_FREEZE` | -| 定格前后余额正确 | **是** | `addLog` 记录 | -| 第一档不进普通钱包 | **是** | 独立 `free_credit_first_cashout`，跳过 `withdrawFrozen` | -| Claim 创建 Deposit Lot | **否** | 全仓库无 `DepositLot`/`deposit_lot` 实现 | -| Claim 创建 Y1 | **是** | 但 `createTask` 在钱包事务 **commit 之后**；失败仅打日志，**不满足** 文档 20.3「流水任务失败整体回滚」 | -| 重复回调不重复定格 | **是** | `frozen_amount_qf > 0` 跳过 | -| 重复 Claim 不重复入账 | **部分** | package 状态 + `claim_biz_id` 唯一；钱包层 **未见 biz_id 幂等查重** | - ---- - -## 明确未实现 / 未对齐项 - -### P0（影响验收或资金一致性） - -1. **Deposit Lot**：文档 15.4 / 22.2 要求 Claim 后创建；当前仅 `inc` deposit + Y1 task。 -2. **Claim 与 Y1 原子性**：`freeCreditsClaim` 先 commit 入账，再 `createTask`；与 20.3 冲突。 -3. **充值退款/拒付暂停档位**（文档 20.1）：`FreeCreditsLogic` 无 refund/chargeback 处理。 -4. **status API 缺累计充值进度**：定格后 UI 需要 `$9.99 / $50`（文档 6.3、7.3），`buildStatus` 未返回 `total_recharge`（内部用 `wallet.r`，未透出）。 -5. **「曾经达到 $50」**：无 `peak_balance` 字段；依赖事件驱动 `syncHomeWithdrawUnlocked`，与 5.2 字面规则不完全一致。 - -### P1（运营与配置） - -6. **后台配置模块**（文档 17）：`backend/slot_admin` / `slot_admin_vue` **无** `TYPE_FREE_CREDITS=11` 的 CRUD 页面；仅能手工维护 `s_recharge_gift_config.ext_config`。 -7. **后台统计页**（文档 18）：仅有 [innerapi](file:///Users/ray/Documents/project/www/slot/slot_console/app/innerapi/controller/FreeCreditsController.php) 简化接口；列表缺 **渠道、时间范围、第一档状态、排序项、累计充值、完成进度** 等字段/筛选项。 -8. **可配置 Y1 倍数**（文档 17 `后续档打码倍数`）：代码写死 `createTask(0, fee, SOURCE_TYPE_FREE)`，未读 `ext_config`。 -9. **状态机 `STATUS_FROZEN=2`**：模型定义了但 Logic **从未赋值**（定格后直接 `DEPOSIT_PENDING` / `FIRST_CASH_READY`）。 - -### P2（产品体验 / 文档其他章节） - -10. **客户端 UI**（文档 6–14）：`slot_pwa` 等仓库 **零引用** `free_credits`；首页状态条、Free Play to Go、独立提现页、广播模块均未实现（原开发计划也标明前端另仓）。 -11. **广播模块**（文档 13）：无最近 10 条提现/领取记录 API。 -12. **注册赠送改 $30**（文档 19）：与本活动解耦，**未在本需求代码变更中验证**是否已改配置/落地页。 -13. **自动化测试**：无 FreeCredits 相关单测/集成测试。 - ---- - -## 与现有开发计划的一致性 - -[free_credits_release 计划](file:///Users/ray/.cursor/plans/free_credits_release_902566c9.plan.md) 中 `implement-console-core` 仍为 **pending**，与代码现状（Logic 已较完整）不一致；`test-acceptance` 标 completed 但仓库内 **无测试文件**，建议以文档 22 节手工/自动化用例重新验收。 - ---- - -## 建议验收顺序（若需补齐） - -1. **手工走通 P0 账务用例**：首充定格幂等、满 $50 解锁、首档提现回调、顺序 Claim、重复 Claim/回调。 -2. **补齐 status 字段**：`total_recharge`、`show_home_status_bar`、`show_activity_entry`、`current_balance`。 -3. **对齐钱包**：Deposit Lot（若钱包规范要求）、Claim+Y1 同事务或补偿回滚。 -4. **运营**：slot_admin 增加 type=11 配置页 + 统计页对接 innerapi。 -5. **前端仓**：按文档 6–14 接 API（本 monorepo 外）。 -6. **补测试**：覆盖 22.1 / 22.2 表格各行。 - ---- - -## 总览评分（仅供沟通） - -| 范围 | 完成度（估） | -|------|-------------| -| 后端核心状态机 + 充值/提现/Claim 链路 | ~75–85% | -| 钱包账务与文档完全一致 | ~60% | -| 客户端 API 字段/UI 支撑 | ~50% | -| 运营后台配置与统计 | ~25% | -| 前端 UI / 文案 / 广播 | ~0%（本仓库） | -| 自动化测试 | ~0% | - -**综合：需求文档 V1.0 不能判定为「已全部实现」；可判定为「后端 MVP 已具备，待补齐账务细节、运营与前端后全量验收」。** diff --git a/plans/is_end派奖结算改造_14ce4dc5.plan.md b/plans/is_end派奖结算改造_14ce4dc5.plan.md deleted file mode 100644 index f2b3c7b..0000000 --- a/plans/is_end派奖结算改造_14ce4dc5.plan.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: is_end派奖结算改造 -overview: 基于现有 BetFunding/WinService 实现，新增 is_end 分支：中间派奖仅累计不入账，结束派奖统一按 Round Final Settlement 入账；并对中间派奖增加 biz_id 严格幂等。 -todos: - - id: dto-validator-is-end - content: 扩展 DTO 与校验器，支持 is_end 并强制 win 场景 round_id 校验 - status: pending - - id: redis-win-keys - content: 新增 pending/dedupe Redis key 生成方法与 TTL 约定 - status: pending - - id: logic-win-branching - content: 在 WalletLogic::win 中实现 is_end=0 累计与 is_end=1 最终结算分支 - status: pending - - id: idempotency-regression - content: 补充关键回归场景说明并验证与现有幂等不冲突 - status: pending -isProject: false ---- - -# is_end 驱动的派奖结算改造计划 - -## 目标 -让 `win` 接口支持第三方 `is_end` 语义： -- `is_end=0`：仅记录/累计本局派奖，不做钱包入账、不做 Lot 终态收敛 -- `is_end=1`：将本次派奖 + 已累计派奖合并后，执行一次 Final Settlement（现有 `WinService::execute`） - -## 现状结论（基于代码） -- 入口路由在 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `type=win -> win()`。 -- Final Settlement 主流程在 [app/service/wallet/WinService.php](app/service/wallet/WinService.php)。 -- 当前 `win` 默认即 Final Settlement，不区分中间派奖事件。 -- 下注资金事实表在 [app/model/multi/WalletBetFundingModel.php](app/model/multi/WalletBetFundingModel.php)。 - -## 实现方案（按你选择） -### 1) 入参扩展与校验 -- 在 [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 增加字段：`is_end`（默认 `1`，仅允许 `0|1`）。 -- 在 [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php)： - - 增加 `is_end` 校验规则（整数且取值 `0/1`）。 - - 将 `win` 也纳入 `round_id` 必传校验（当前仅 bet 必传）。 - -### 2) Redis Key 设计 -- 在 [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php) 新增两个 key 生成器： - - `wallet:win:pending:{uid}:{currency}:{round_id}`：累计未结算派奖金额 - - `wallet:win:dedupe:{uid}:{currency}:{round_id}:{biz_id}`：中间派奖幂等标记 -- 过期策略建议：`pending` 48h，`dedupe` 72h（与重放窗口对齐）。 - -### 3) win 主流程分支 -- 修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`： - - `is_end=0`： - - 命中 dedupe key 则直接返回当前钱包（幂等） - - 未命中则将 `fee` 累加到 pending key，写 dedupe key，返回当前钱包（不写 `BIZ_TYPE_WIN` 流水） - - `is_end=1`： - - 读取 pending 累计并与本次 `fee` 合并为 `finalWinAmount` - - 用 `finalWinAmount` 调用现有 `WinService::execute` - - 事务提交后清理 pending key（失败不清） - -### 4) 幂等与一致性 -- `is_end=1` 继续沿用现有 `wallet_log(uid,biz_id,biz_type=win)` 幂等。 -- `is_end=0` 使用 Redis dedupe key 防重，避免重复累计。 -- 若 `is_end=1` 无待分配 funding，保持当前行为（报错），便于暴露上游时序问题。 - -### 5) 兼容与回归 -- 默认 `is_end=1`，兼容未传该字段的旧调用。 -- 回归场景： - - 单次结算（只发 `is_end=1`） - - 多次派奖（多条 `is_end=0` + 一条 `is_end=1`） - - `is_end=0` 重放同 biz_id 不重复累计 - - `is_end=1` 重放同 biz_id 不重复入账 - - `is_end=1` 失败后 pending 不丢失 - -## 关键改动文件 -- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) -- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php) -- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php) -- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) - -## 风险与边界 -- 该方案不新增 `wallet_game_round` / `wallet_game_round_event` 持久化表；中间派奖仅 Redis 暂存，审计粒度弱于 DB 事件流。 -- 若某局长期无 `is_end=1`，pending 依赖 TTL 过期清理。后续可升级为 DB 事件表方案。 \ No newline at end of file diff --git a/plans/is_end结算回退方案_180cfb46.plan.md b/plans/is_end结算回退方案_180cfb46.plan.md deleted file mode 100644 index e0b5f72..0000000 --- a/plans/is_end结算回退方案_180cfb46.plan.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -name: is_end结算回退方案 -overview: 取消“中间派奖实时余额可见化”调整，回退到严格 Final Settlement 方案：is_end=0 仅累计，is_end=1 才入账与状态收敛。 -todos: - - id: dto-validator-is-end - content: 增加 is_end 字段及 win round_id 强校验 - status: completed - - id: pending-dedupe-keys - content: 新增 pending 与 dedupe Redis key 并接入 is_end=0 累计 - status: completed - - id: win-final-merge - content: is_end=1 合并 pending 后调用现有 WinService 结算并清理缓存 - status: completed - - id: regression-check - content: 回归验证多次派奖累计、最终结算与幂等行为 - status: completed -isProject: false ---- - -# is_end 结算回退方案（不做中间余额更新） - -## 变更决策 -取消这部分： -- 多次派奖期间（`is_end=0`）对第三方返回余额进行实时更新 -- 对 `wallet` 查询叠加 pending 金额 - -保留并执行： -- `is_end=0`：仅做中间派奖累计，不改钱包余额、不做 Lot 收敛 -- `is_end=1`：合并累计派奖后一次 Final Settlement（调用现有 win 主流程） - -## 实现边界 -- 严格遵循 [doc/win.md](doc/win.md) 的“Final Settlement 才做真实入账”原则 -- 不引入展示层余额叠加逻辑，避免展示余额与真实可下注余额不一致 - -## 具体改造 -1. DTO / 校验 -- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 增加 `is_end`（默认 `1`） -- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php) - - 增加 `is_end` 仅允许 `0/1` - - `win` 场景强制 `round_id` 必传 - -2. Redis 累计与幂等（仅中间派奖） -- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php) 增加 key： - - `wallet:win:pending:{uid}:{currency}:{round_id}` - - `wallet:win:dedupe:{uid}:{currency}:{round_id}:{biz_id}` -- `is_end=0` 命中 dedupe 则忽略，未命中则累计 pending - -3. win 结算分支 -- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) - - `is_end=0`：只累计并返回当前真实钱包余额 - - `is_end=1`：读取 pending 并与本次 `fee` 合并后走现有 `WinService::execute`，成功后清理 pending - -## 验收 -- 多条 `is_end=0` 不触发真实入账 -- 一条 `is_end=1` 触发一次最终结算，金额=中间累计+末笔 -- 中间派奖重复 `biz_id` 不重复累计 -- Final 失败时 pending 不丢失，可重试 \ No newline at end of file diff --git a/plans/phpdoc_cursor_规则_1ee55114.plan.md b/plans/phpdoc_cursor_规则_1ee55114.plan.md deleted file mode 100644 index 7916290..0000000 --- a/plans/phpdoc_cursor_规则_1ee55114.plan.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -name: PHPDoc Cursor 规则 -overview: 在 Cursor 全局规则中新增 PHP PHPDoc 严格规范（类、方法、常量全覆盖），与现有 backend-layering 规则并列，并明确适用范围与模板，避免与「不写显而易见注释」的原则冲突。 -todos: - - id: create-php-doc-mdc - content: "新建 /Users/ray/.cursor/rules/php-doc.mdc（globs: **/*.php，严格 PHPDoc 正文 + 示例）" - status: completed - - id: verify-rule-active - content: 在 Cursor 中打开任意 .php 文件，确认规则被注入；用 WalletLogic 缺注释方法做一次试写验证 - status: completed - - id: optional-readme-sync - content: （可选）将 PHPDoc §3.4 同步到 slot_wallet 等 README，与 Cursor 规则保持一致 - status: completed -isProject: false ---- - -# 新增 PHPDoc 严格 Cursor 规则 - -## 结论：要加，但不要写成「所有符号一刀切」的空话 - -你选择了 **严格全覆盖**。建议在 Cursor 里加一条 **独立规则文件**，与现有的 [`backend-layering.mdc`](/Users/ray/.cursor/rules/backend-layering.mdc) 并列，而不是塞进 layering 里（职责不同：一个管分层，一个管文档）。 - -**不建议**写成模糊的「所有都要 PHPDoc」——应写清 **哪些符号、最少哪些 tag、何时可写短句**。否则 Agent 会在 trivial 代码上堆 `@param int $uid uid` 这类无意义注释，与 [`slot_agent/README.md`](/Users/ray/Documents/project/www/slot/slot_agent/README.md) 第 9.3 节「不解释显而易见语句」打架。 - -## 现状 - -| 来源 | PHPDoc 要求 | -|------|-------------| -| [`.cursor/rules/`](/Users/ray/.cursor/rules/) | 仅有 layering + dev-environment，**无 PHPDoc** | -| [`slot_agent/README.md`](/Users/ray/Documents/project/www/slot/slot_agent/README.md) §6.2 | 已要求：业务类说明、公开方法说明、参数/返回值说明 | -| 实际代码（如 [`WalletLogic.php`](/Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php)） | **不一致**：`run`/`register` 有块注释，`initWalletWithoutMoney`、`getBalance` 无 | - -终端里曾出现给 `slot_wallet/README.md` 增加 §3.4 PHPDoc 的 diff，但当前 README **尚未落地**该节——规范应优先进 **Cursor rule**（Agent 每次都会读），README 可作为人类文档二次同步（可选）。 - -## 推荐规则文件 - -**路径**：[`/Users/ray/.cursor/rules/php-doc.mdc`](/Users/ray/.cursor/rules/php-doc.mdc) - -**Frontmatter 建议**： - -```yaml ---- -description: PHP PHPDoc requirements for all classes, methods, and constants -globs: "**/*.php" -alwaysApply: false ---- -``` - -- 用 `globs: **/*.php`：编辑 PHP 时自动注入，不污染 Vue/TS 会话 -- `alwaysApply: false`：与 layering 的 `true` 区分，减少非 PHP 任务 token - -## 规则正文（严格版，建议写入 mdc） - -### 1. 适用范围 - -- **新增或修改**的 PHP 文件中的：**class / interface / trait / enum**、**所有方法**（`public` / `protected` / `private`）、**所有类常量**（`const`） -- 适用目录：`slot_*`、`backend/**` 下 PHP 业务代码 -- **不追溯**改历史未动代码；但 **本次 diff 触及的符号** 若缺 PHPDoc，须一并补齐 - -### 2. 最低 PHPDoc 内容 - -| 符号 | 必须包含 | -|------|----------| -| 类 / 接口 / Trait | 一行职责说明；复杂类可加 `@package`（可选） | -| 方法 | 职责说明 + 每个参数的 `@param` + `@return`；有 `throw` 的须 `@throws` | -| 类常量 | 一行说明业务含义（单位、枚举语义、与配置/表字段对应关系） | -| 属性（若新增） | `@var` 或 typed property + 一行说明（仅当类型/语义不直观时） | - -已有 **PHP 8+ 标量/对象类型声明** 时，`@param`/`@return` 仍要保留（与你选的 strict 一致），但 **描述句可短**，禁止空块或只复制类型名。 - -### 3. 禁止项（与 slot_agent 注释原则对齐） - -- 禁止无 `@param` / `@return` 的空 `/** */` -- 禁止 `@param int $id id` 式同义反复；语义、单位、边界写进描述 -- 禁止用 PHPDoc 替代 Validate / Logic 里的业务校验说明 - -### 4. 分层补充（与 layering 一致） - -对以下层 **额外** 要求写清业务语义（不仅是类型）： - -- **Controller**：接口用途、幂等/鉴权前提（若有） -- **Logic**：用例步骤、事务边界、失败时行为 -- **Service**：复用场景、调用方约束 -- **Model**：查询条件、分表键、金额字段单位 -- **DTO / Validate**：字段含义、与上游参数映射 - -### 5. 示例模板（写入规则供 Agent 照抄） - -```php -/** - * 首充前冻结免费余额。 - * - * @return WalletEntity|null 成功返回钱包实体；无需冻结时返回 null - * @throws WalletException 余额不足或钱包不存在 - */ -public function freeCreditsFreeze(): ?WalletEntity -``` - -```php -/** 释放档位：单位分，对应配置 free_credits.release_tiers */ -public const RELEASE_TIER_MIN = 100; -``` - -## 与工具链的关系（可选，本期可不做的） - -Cursor rule **不能**在 CI 里自动 fail。若以后要机器 enforce，再单独加： - -- PHPStan + `phpstan/phpdoc-parser` 或 -- PHPCS `Squiz.Commenting` / 自定义 sniff - -本期仅 Cursor 规则即可满足「Agent 写码时遵守」。 - -## 实施步骤 - -1. 新建 [`php-doc.mdc`](/Users/ray/.cursor/rules/php-doc.mdc)，按上文写入 frontmatter + 正文 -2. 在 Cursor Settings → Rules 确认该规则对 PHP 文件生效（`globs` 匹配） -3. （可选）把相同 §3.4 同步进 [`slot_wallet/README.md`](/Users/ray/Documents/project/www/slot/slot_wallet/README.md) 与其它服务 README，供人工 review 对照 -4. 用一次小改动验证：例如在 `WalletLogic` 给无注释的 `getBalance` 补 PHPDoc，看 Agent 是否自动遵循 - -## 风险与预期 - -- **Diff 变大**：strict 下每个新方法多 5–15 行注释，属预期成本 -- **历史债**：全库补 doc 工作量巨大；规则应写明 **仅 touch 到的符号**，避免 Agent 一次性重构整文件 -- **类型重复**：strict 仍保留 `@param`/`@return` 类型，利于 IDE/静态分析；描述聚焦「为什么/单位/边界」 - -```mermaid -flowchart LR - subgraph rules [Cursor Rules] - layering[backend-layering.mdc] - phpdoc[php-doc.mdc] - devenv[dev-environment.mdc] - end - subgraph code [PHP 改动] - edit[编辑 PHP 文件] - agent[Agent 生成/修改代码] - end - edit --> phpdoc - edit --> layering - agent --> phpdoc - agent --> layering -``` diff --git a/plans/phpunit_钱包链路测试_003ec505.plan.md b/plans/phpunit_钱包链路测试_003ec505.plan.md deleted file mode 100644 index 9ea4404..0000000 --- a/plans/phpunit_钱包链路测试_003ec505.plan.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: PHPUnit 钱包链路测试 -overview: 补齐本仓库的 PHPUnit 基建，并新增 register/bet/win 集成测试用例，默认在本地 php82 容器执行、连接真实依赖，以 HTTP 结果与余额变化作为核心断言。 -todos: - - id: setup-phpunit - content: 补齐 PHPUnit 基建（composer require-dev、phpunit.xml、tests/bootstrap.php） - status: completed - - id: implement-feature-test - content: 实现 register/bet/win 集成测试与幂等/异常断言 - status: completed - - id: run-in-container - content: 在 php82 容器执行测试并根据结果修正 - status: completed - - id: document-runbook - content: 补充测试执行说明与可选增强项 - status: completed -isProject: false ---- - -# PHPUnit Register/Bet/Win 测试落地计划 - -## 默认口径（基于当前信息） -- 测试框架：PHPUnit（当前仓库尚无 `phpunit.xml` 和 `tests/`）。 -- 执行环境：本地 `php82` 容器。 -- 依赖模式：默认连本地真实 MySQL/Redis（贴近联调）。 -- 断言范围：默认先做 API 返回与余额变化断言；DB 深断言作为第二阶段可选扩展。 - -## 现状结论 -- 缺少 PHPUnit 基建：未发现 `phpunit*.xml` 与 `tests/` 目录。 -- `register/bet/win` 入口与逻辑已具备： - - 接口入口：[app/api/controller/WalletController.php](app/api/controller/WalletController.php) - - 业务编排：[app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) - - 注册服务：[app/service/wallet/RegisterService.php](app/service/wallet/RegisterService.php) - -## 实施步骤 -1. **补测试基建** -- 在 `require-dev` 增加 `phpunit/phpunit`。 -- 新增 `phpunit.xml`（定义 `tests/` 目录、bootstrap、环境变量覆盖）。 -- 新增 `tests/bootstrap.php`（加载自动加载与测试环境初始化）。 - -2. **新增钱包链路集成测试** -- 新建测试文件：[tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) -- 用例覆盖： - - `register` 成功（通过 `wallet/update` + `type=register`） - - `bet` 成功并校验扣款后余额变化 - - `win is_end=0` 中间派奖仅影响待结算展示 - - `win is_end=1` 最终结算落账 - - `bet` 重复 `biz_id` 幂等 - - `win` 重复 `biz_id` 幂等 - - `bet/win` 缺 `round_id` 参数错误 - - `win` 非法 `is_end` 参数错误 - -3. **测试数据与可重复执行设计** -- 每个测试生成独立 `uid/round_id/biz_id/trace_id`（时间戳+随机后缀），避免脏数据冲突。 -- 用例内封装统一请求方法（POST JSON）与响应断言助手，降低重复代码。 -- 优先按顺序单线程执行此特性测试，避免并发串扰。 - -4. **执行与验证** -- 在容器内执行：`docker compose exec -T php82 php vendor/bin/phpunit --filter WalletRegisterBetWinTest` -- 验证输出： - - 所有用例通过 - - 幂等场景无重复记账（通过返回余额不重复变化来断言） - -5. **第二阶段可选增强（不在首版强制）** -- 增加 DB 断言（`wallet_log`、`wallet_fund_lot`、`wallet_bet_funding`）与 Redis pending key 清理断言。 -- 将该测试纳入 CI job（需环境可用性与测试隔离策略先达成一致）。 - -## 目标结构图 -```mermaid -flowchart TD - testBootstrap[phpunitBootstrap] --> featureTest[WalletRegisterBetWinTest] - featureTest --> registerStep[register_update] - registerStep --> betStep[bet] - betStep --> winMidStep[win_is_end_0] - winMidStep --> winFinalStep[win_is_end_1] - winFinalStep --> idemCheck[idempotencyChecks] - idemCheck --> negativeCheck[invalidParamsChecks] -``` - -## 受影响文件（计划新增/修改） -- [composer.json](composer.json) -- [phpunit.xml](phpunit.xml) -- [tests/bootstrap.php](tests/bootstrap.php) -- [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) \ No newline at end of file diff --git a/plans/phpunit_集成测试落地_3c120775.plan.md b/plans/phpunit_集成测试落地_3c120775.plan.md deleted file mode 100644 index 0824bce..0000000 --- a/plans/phpunit_集成测试落地_3c120775.plan.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: PHPUnit 集成测试落地 -overview: 补齐本仓库 PHPUnit 基建，并新增 register/bet/win 集成测试（连接真实 MySQL/Redis）与关键 DB 断言，支持在本地 php82 容器执行。 -todos: [] -isProject: false ---- - -# Register/Bet/Win PHPUnit 实施计划 - -## 目标 -- 新增可 \ No newline at end of file diff --git a/plans/sdk_taskprogress_封装_5c8676e2.plan.md b/plans/sdk_taskprogress_封装_5c8676e2.plan.md deleted file mode 100644 index d97bc91..0000000 --- a/plans/sdk_taskprogress_封装_5c8676e2.plan.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: SDK taskProgress 封装 -overview: 将 slot_sdk（或你们的 SDK 仓库）加入工作区后，可按现有 Wallet Client 模式直接实现 `player-task/task-progress` 的调用封装；wallet 侧接口文档已就绪，可作为契约来源。 -todos: - - id: add-sdk-workspace - content: 用户将 slot_sdk 加入 Cursor 工作区并告知仓库路径 - status: completed - - id: explore-sdk-patterns - content: 阅读 SDK 现有 Wallet Client / HTTP 封装与错误处理约定 - status: completed - - id: implement-client - content: 新增 taskProgress 方法、路径常量、请求/响应类型（对齐 player-task-progress-api.md） - status: completed - - id: add-tests-or-example - content: 按 SDK 惯例补单测或调用示例（若项目有测试目录） - status: completed -isProject: false ---- - -# SDK 工作区加入后的直接开发方案 - -## 结论 - -**可以。** 当前工作区只有 [slot-wallet](file:///Users/ray/Documents/project/www/ray/slot-wallet)，已具备接口契约文档 [doc/player-task-progress-api.md](doc/player-task-progress-api.md) 与实现对照（`PlayerTaskController`、`PlayerTaskQueryService` 等）。把 **SDK 仓库** 作为第二个根目录（或 monorepo 子目录）加入工作区后，我可以： - -1. 阅读 SDK 里现有 Wallet/HTTP Client 的命名、基类、错误处理、DTO 约定； -2. 新增 `taskProgress`（或团队统一命名）方法、路径常量、请求/响应类型； -3. 若有单测/示例，补一条调用示例或 Feature 测试； -4. 保证字段 **snake_case** 与 HTTP JSON 一致，成功判定 `code === 0`。 - -```mermaid -flowchart LR - subgraph workspace [Cursor Workspace] - Wallet[slot-wallet] - SDK[slot_sdk] - end - Doc[player-task-progress-api.md] - Wallet --> Doc - SDK -->|reads patterns| SDK - Doc -->|contract| SDK - SDK -->|POST player-task/task-progress| Wallet -``` - -## 你需要做的准备 - -| 项 | 说明 | -|----|------| -| 加入工作区 | Cursor：**File → Add Folder to Workspace**，选中 SDK 仓库根目录 | -| 告知路径 | 例如 `company/ray/slots/slot_sdk`（与你们实际目录一致即可） | -| 语言确认 | 若是 PHP `slot_sdk`、Go、TS 等，我会跟现有 Client 语言一致，不另起一套风格 | - -无需改 wallet 代码即可开始 SDK 开发；wallet 接口已实现完毕。 - -## 我会按什么写（预期产出） - -以 SDK 现有 Wallet Client 为模板（具体类名需打开 SDK 后确认），典型改动： - -- **路径常量**：`player-task/task-progress` -- **请求**：`uid`, `currency`（可选统一附带 `trace_id` 若其他接口都有） -- **响应模型**：`summary` + `bonus_tasks[]` + `deposit_tasks[]`，字段与 [doc/player-task-progress-api.md](doc/player-task-progress-api.md) §5 一致 -- **错误**：复用 SDK 已有 `WalletApiError` / `code !== 0` 处理 - -## 跨仓库发布（团队规范） - -按 [`.cursor/rules/slot-wallet-layers-and-delivery.mdc`](file:///Users/ray/Documents/project/www/ray/slot-wallet/.cursor/rules/slot-wallet-layers-and-delivery.mdc) §8–9： - -1. **先在 SDK 仓库** `commit` → `push`； -2. 消费方（如 slot-wallet 若通过 composer 依赖 SDK）再 `composer update` 并锁 `composer.lock`。 - -当前 [composer.json](file:///Users/ray/Documents/project/www/ray/slot-wallet/composer.json) **尚未**声明 `slot_sdk` 依赖，说明 SDK 可能独立发布或由其他服务引用——这不影响我在 SDK 仓库内直接编码。 - -## 建议的确认项（加入工作区后第一条消息说明即可） - -1. SDK 仓库在本机的**绝对路径**或文件夹名； -2. 方法命名偏好：`taskProgress` / `getPlayerTaskProgress` / 与现有 `wallet()` 等方法对齐； -3. 是否需要 **foundation 常量**（如 `source_type`）进 SDK，还是仅透传 int。 - -## 不在本次默认范围 - -- 修改 wallet 服务端实现（已满足 PRD §26.1）； -- 自动 `composer update` 到其他服务（除非你明确要求并给出目标仓库）。 diff --git a/plans/slot_workspace_82c92cd4.plan.md b/plans/slot_workspace_82c92cd4.plan.md deleted file mode 100644 index 1bad684..0000000 --- a/plans/slot_workspace_82c92cd4.plan.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: slot workspace -overview: 在 `/Users/ray/Documents/project/www/slot` 创建一个 Cursor/VS Code workspace 文件，并把该目录下一级项目文件夹加入 workspace。默认排除隐藏目录 `.vscode`，不递归加入嵌套子目录。 -todos: [] -isProject: false ---- - -# 创建 Slot Workspace - -将创建 `[slot.code-workspace](/Users/ray/Documents/project/www/slot/slot.code-workspace)`，内容使用标准 VS Code/Cursor workspace JSON： - -```json -{ - "folders": [ - { "path": "backend" }, - { "path": "monitor" } diff --git a/plans/status_接口字段精简_8ba244ad.plan.md b/plans/status_接口字段精简_8ba244ad.plan.md deleted file mode 100644 index aa601e9..0000000 --- a/plans/status_接口字段精简_8ba244ad.plan.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -name: status 接口字段精简 -overview: 对照需求文档精简 C 端 status/claim 响应字段，并将所有金额由千分位（qf）转为大单位（与全站 getNumberFormat 一致）；innerapi 仍返回 qf 全量。 -todos: - - id: package-list-for-client - content: FreeCreditsPackageModel::listForClient() 返回精简字段，amount 经 getNumberFormat 转大单位 - status: completed - - id: slim-build-status - content: buildStatus 去掉 activity_id；顶层金额与 packages 均转大单位 - status: completed - - id: format-first-cashout-amount - content: firstCashout 响应 data.amount 同步转大单位（Pay 入参仍用 qf） - status: completed - - id: update-controller-phpdoc - content: 更新 FreeCreditsController PHPDoc：金额为展示单位 float，非千分位 - status: completed - - id: client-status-test - content: 单测断言字段白名单及 78500 qf → 78.5 等大单位转换 - status: completed -isProject: false ---- - -# Free Credits status 接口字段精简 - -## 结论 - -**可以且应该精简。** 当前 [`buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php) 直接 `toArray()` 透出库表列，超出需求文档中 C 端 UI 所需信息；[`activity_id`](slot_console/app/api/logic/FreeCreditsLogic.php) 仅用于后台/内部关联，C 端无展示或交互用途。 - -你已确认： - -- **只做删减**，不新增 `total_deposit`（累计充值进度由 C 端从钱包侧获取）。 -- **金额转大单位**：C 端接口不再返回千分位整数，统一转为展示金额（与 [`AgentController::formatAmountToFloat`](slot_console/app/api/controller/AgentController.php)、[`CommonFn::getNumberFormat`](slot_lib/src/common/CommonFn.php) 一致，默认 `moneyFormat=1000`、`moneyDot=2`，如 qf `78500` → `78.5`）。 - ---- - -## 需求文档 vs 当前响应 - -需求文档（[首充前免费余额定格与分档释放需求文档.md](docs/requirements/首充前免费余额定格与分档释放需求文档.md)）描述的是 **UI 行为**，未定义 JSON 契约，但可反推 C 端必需数据： - -| UI 场景（文档章节） | C 端需要的数据 | -| --- | --- | -| 是否展示活动（`status === -1` 隐藏） | `status` | -| 首页 Withdraw 是否曾达赢取门槛（§5.2、§7） | `home_withdraw_unlocked` | -| 池总额 / 入口副标题「$78.50 pending」（§6.3–6.6、§9.3、§14.2） | `frozen_amount` | -| 问号弹窗 / 第一档金额（§8、§10） | `first_cash_amount`、`recharge_unlock_amount` | -| 档位列表 Withdraw / Unlock / Claim / Claimed（§9.3、§10–12） | `packages[]`：`id`、`package_type`、`amount`、`status` | -| 发起 claim / 第一档提现（现有 API） | `packages[].id` → POST `package_id` | - -**当前多出的字段：** - -- 顶层：`activity_id`（`recharge_gift_config.id`，仅 innerapi/编排用） -- `packages[]` 全表列：`player_id`、`activity_id`、`uid`、`withdraw_order_id`、`claim_biz_id`、`unlocked_time`、`claimed_time`、`completed_time`、`create_time`、`update_time` -- `package_no` 可保留（便于调试与稳定排序展示），也可仅靠数组顺序；建议 **保留**（成本低、与 DB 序号一致） - -**命名与单位：** packages 字段由 `amount_qf` 改为 **`amount`**；顶层与各档 **`amount` 均为大单位 float**（非 qf），C 端可直接用于 `$78.50` 类文案，无需再 `/1000`。 - ---- - -## 目标响应契约（C 端） - -```json -{ - "status": 4, - "home_withdraw_unlocked": 1, - "frozen_amount": 78.5, - "first_cash_amount": 20, - "recharge_unlock_amount": 50, - "packages": [ - { - "id": 101, - "package_no": 1, - "package_type": 1, - "amount": 20, - "status": 1 - } - ] -} -``` - -`status === -1` 时仍仅 `{ "status": -1 }`（与现逻辑一致）。 - -**转换规则（实现）：** - -```php -// 与全站 C 端金额一致；qf 为库表 / 内部逻辑整数 -private function formatClientAmount(int $amountQf): float -{ - return (float) CommonFn::getNumberFormat($amountQf); -} -``` - -- 应用于：`frozen_amount`、`first_cash_amount`、`recharge_unlock_amount`、`packages[].amount`。 -- **`firstCashout` 成功响应** `data.amount` 同样转大单位；调用 Pay / 钱包时仍传 qf，仅 JSON 对外转换。 -- **innerapi / 单测写库** 仍使用 `_qf` 整数，不在 DB 层改单位。 - ---- - -## 实现方案 - -```mermaid -flowchart LR - statusApi[status_claim_firstCashout] - buildStatus[buildStatus] - clientDto[toClientStatusDto] - modelFull[listByPlayerId_toArray] - innerapi[innerapi_list] - statusApi --> buildStatus --> clientDto - buildStatus --> modelFull - innerapi --> modelFull -``` - -1. **Logic 层统一转换**（[`FreeCreditsLogic`](slot_console/app/api/logic/FreeCreditsLogic.php)） - - 新增 `formatClientAmount(int $amountQf): float`（封装 `CommonFn::getNumberFormat`）。 - - 供 `buildStatus`、`listForClient`（或 Model 回调）、`firstCashout` 响应共用。 - -2. **Model 层 C 端 packages**（[`FreeCreditsPackageModel`](slot_console/app/model/common/FreeCreditsPackageModel.php)） - - 新增 `listForClient(int $playerId, callable $formatAmount): array` 或 Logic 内 `array_map`：只输出 `id`、`package_no`、`package_type`、`amount`（大单位）、`status`。 - - 保留 `listByPlayerId()` 供 innerapi、dev、集成测试。 - -3. **收口 DTO**（`buildStatus`） - - 去掉 `activity_id`。 - - 顶层三金额字段经 `formatClientAmount`；`packages` 用 `listForClient`。 - - `status()`、`claim()` 经 `buildStatus` 返回，结构一致。 - -4. **firstCashout 响应** - - `return ['order_id' => ..., 'amount' => $this->formatClientAmount($package->amount_qf)]`。 - -5. **更新文档**（[`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php) PHPDoc） - - 删除「千分位整数、展示时除以 1000」描述；改为「金额为大单位 float，精度见 `moneyDot`」。 - -6. **单测** - - 新增 `FreeCreditsClientStatusTest`：字段白名单 + `78500` qf → `78.5` 转换断言。 - -7. **不改动** - - [`innerapi/controller/FreeCreditsController`](slot_console/app/innerapi/controller/FreeCreditsController.php) 仍返回全量 `toArray()`。 - - `FreeCreditsFreezeDev` 等内部工具继续用 `listByPlayerId`。 - ---- - -## 字段对照表（精简前后） - -| 字段 | 精简前 | 精简后 | 说明 | -| --- | --- | --- | --- | -| `activity_id` | 有 | **删** | C 端不需要 | -| `status` | 有 | 有 | 主状态机 | -| `home_withdraw_unlocked` | 有 | 有 | §5.2 | -| `frozen_amount` | qf 整数 | **float 大单位** | 如 78.5 | -| `first_cash_amount` | qf 整数 | **float 大单位** | 如 20 | -| `recharge_unlock_amount` | qf 整数 | **float 大单位** | 如 50 | -| `packages[].id` | 有 | 有 | claim/cashout | -| `packages[].package_no` | 有 | 有 | 序号展示 | -| `packages[].package_type` | 有 | 有 | 1=提现档 2=领取档 | -| `packages[].amount` | `amount_qf`（qf） | `amount`（**float 大单位**） | 重命名 + 转换 | -| `firstCashout.data.amount` | qf | **float 大单位** | 与 status 一致 | -| `packages[].status` | 有 | 有 | UI 状态 | -| `packages[].player_id/uid/...` | 有 | **删** | 内部字段 | -| `packages[].withdraw_order_id` 等 | 有 | **删** | 轮询靠主 `status` + package `status` | - ---- - -## 风险与协调 - -- **Breaking change**：C 端需改为直接使用大单位金额（不再 `/1000`）；删除 `activity_id`、`amount_qf` 及 packages 审计字段。 -- **精度**：与 `ShareConfigService::moneyDot` / `moneyFormat` 绑定，勿手写 `/1000`，避免与 VIP/钱包接口不一致。 -- **累计充值进度**：不纳入本次接口；C 端继续从钱包统计接口取（钱包侧金额亦通常为大单位）。 diff --git a/plans/status_返回_help_e344e40a.plan.md b/plans/status_返回_help_e344e40a.plan.md deleted file mode 100644 index e6eb1c5..0000000 --- a/plans/status_返回_help_e344e40a.plan.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: status 返回 help -overview: 在 Free Credits C 端 status 接口（及 claim 同源 buildStatus）中增加 help 字段，读取活动配置表 recharge_gift_config.help，供问号说明弹窗等展示；status=-1 仍不返回 help。 -todos: - - id: build-status-help - content: FreeCreditsLogic::buildStatus 增加 help 字段（读 config->help） - status: completed - - id: update-phpdoc - content: FreeCreditsController::status PHPDoc 补充 help 说明 - status: completed - - id: unit-test-help - content: FreeCreditsClientStatusTest 白名单与透传断言 - status: completed -isProject: false ---- - -# status 接口增加 help 返回 - -## 目标 - -`GET /api/free-credits/status`（以及 `claim` 成功后的同源响应）在 `status !== -1` 时增加 **`help`（string）**，内容来自运营在后台活动编辑里填写的 **「帮助说明」**（[`recharge_gift_config.help`](slot_console/app/model/common/RechargeGiftConfigModel.php)）。 - -`status === -1` 时保持仅 `{ "status": -1 }`，不附带 help。 - -## 改动点 - -### 1. [`FreeCreditsLogic::buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php) - -在现有返回数组中增加： - -```php -'help' => is_null($config) ? '' : strval($config->help ?? ''), -``` - -- `buildStatus` 已接收 `$config`（`activeConfig` 查出的 type=11 活动行），无需额外查库。 -- 不做 §8 模板占位符替换（轻量方案）；C 端可用已有 `frozen_amount` / `recharge_unlock_amount` / `first_cash_amount` 自行替换，或原样展示运营配置的富文本/多行文案。 - -### 2. [`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php) PHPDoc - -在 `status` 方法成功字段列表中补充： - -- `help` (string) 活动规则说明，来自后台「帮助说明」 - -### 3. 单测 [`FreeCreditsClientStatusTest`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) - -- `PLAYER_TOP_KEYS` 增加 `help` -- 用例：`FreeCreditsConfigStub` 设置 `help` 属性，`assertSame` 透传 - -## 数据流 - -```mermaid -flowchart LR - admin[slot_admin 活动编辑 help 文本框] - db[(recharge_gift_config.help)] - logic[buildStatus] - api["/api/free-credits/status"] - admin --> db --> logic --> api -``` - -## 验收 - -- 后台 type=11 活动填写「帮助说明」并保存后，已参加用户 `status` 响应含相同 `help` 字符串 -- `status=-1` 响应无 `help` 字段 -- 单元测试通过；`claim` 返回结构同步含 `help`（复用 `buildStatus`） - -## 不在本次范围 - -- `ext_config` 独立说明模板、动态金额替换服务端拼装 -- `banner_image` 透出（如需可另开） -- 前端问号弹窗 UI diff --git a/plans/status_配置与未充值_f37679fd.plan.md b/plans/status_配置与未充值_f37679fd.plan.md deleted file mode 100644 index 8e7bd76..0000000 --- a/plans/status_配置与未充值_f37679fd.plan.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: status 配置与未充值 -overview: 修复 slot_console FreeCreditsLogic::status：无玩家池时返回 status=0 及活动配置；C 端新增 win_threshold（不含 initial_amount、home_withdraw_unlocked）。Logic 已按需求变更实现，待对齐单测与 PHPDoc。 -todos: - - id: logic-pre-enrollment - content: FreeCreditsLogic：buildPreEnrollmentStatus；status() 无 player 时返回配置态（已完成） - status: completed - - id: logic-build-status-fields - content: buildStatus / buildConfigClientFields 仅透出 win_threshold（不含 initial_amount、home_withdraw_unlocked）（已完成） - status: completed - - id: align-phpdoc - content: FreeCreditsController PHPDoc 与 buildConfigClientFields 注释：删除 initial_amount、home_withdraw_unlocked；移除无用 DEFAULT_INITIAL_AMOUNT - status: completed - - id: align-unit-tests - content: FreeCreditsClientStatusTest / FreeCreditsEligibilityTest 白名单与断言与现实现一致 - status: completed -isProject: false ---- - -# Free Credits status 接口修复计划（需求变更版） - -## 需求确认（2026-05-21） - -**C 端 `GET /api/free-credits/status` 约定：** - -- **包含**：`win_threshold`（来自 `ext_config.win_threshold_qf`） -- **不包含**：`initial_amount`、`home_withdraw_unlocked` - - 注册赠送金额：仍由 `game_base.user_register_reward` 等其它接口提供 - - 首页 Withdraw 解锁：C 端用 `status`（如 `STATUS_HOME_UNLOCKED=1`）或钱包余额 + `win_threshold` 自行判断；库表 `home_withdraw_unlocked` 仍由 `syncHomeWithdrawUnlocked` 维护，仅不下发 API - -后台 type=11 的 `initial_amount_qf` 配置保留（运营后台用），**不**经 status 透出。 - -## 问题根因 - -[`FreeCreditsLogic::status()`](slot_console/app/api/logic/FreeCreditsLogic.php) 原逻辑在无 `free_credits_player` 时返回 `{ status: -1 }`，导致首充前 C 端无法展示活动（`status !== -1` 为展示开关）。 - -## 目标行为 - -| 场景 | status | 返回顶层字段 | -| --- | --- | --- | -| 无资格 / 无 type=11 配置 | `-1` | 仅 `status` | -| 有资格 + 有配置 + **无 player** | `0` | `status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`（空数组） | -| 有资格 + 有配置 + **有 player** | 玩家真实值 | 同上 + 玩家 `frozen_amount` / `first_cash_amount` / `packages` | - -```mermaid -flowchart TD - statusReq[GET status] --> eligible{资格+活动配置?} - eligible -->|否| notVisible["status=-1"] - eligible -->|是| player{有 player 行?} - player -->|无| preConfig["status=0 + win_threshold 等"] - player -->|有| fullStatus["buildStatus 玩家态"] -``` - -## 已实现 Logic（当前代码，无需再改字段集） - -[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) 已与上表一致： - -- `status()`：无 player → `buildPreEnrollmentStatus($config)` -- `buildConfigClientFields()`：仅 `win_threshold`、`recharge_unlock_amount`、`help` -- `buildStatus()` / `buildPreEnrollmentStatus()`：**不**返回 `initial_amount`、`home_withdraw_unlocked` - -## 待办：对齐文档与单测 - -### 1. PHPDoc — [`FreeCreditsController.php`](slot_console/app/api/controller/FreeCreditsController.php) - -- 删除 `initial_amount`、`home_withdraw_unlocked` 字段说明 -- 明确 `status=0` 时仍返回 `win_threshold`、`recharge_unlock_amount`、`help` - -### 2. 清理 Logic 注释/死代码 — [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) - -- 删除未使用的 `DEFAULT_INITIAL_AMOUNT` 常量（若仍保留） -- `buildConfigClientFields` 的 `@return` 改为仅含 `win_threshold`、`recharge_unlock_amount`、`help` - -### 3. 单测 - -| 文件 | 改动 | -| --- | --- | -| [`FreeCreditsClientStatusTest.php`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) | `PLAYER_TOP_KEYS` 改为：`status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`；移除 `initial_amount`、`home_withdraw_unlocked` 断言 | -| [`FreeCreditsEligibilityTest.php`](slot_console/tests/Unit/FreeCreditsEligibilityTest.php) | `testStatusReturnsPreEnrollmentConfigWhenNoPlayer`：断言 `win_threshold=50`，**不**断言 `initial_amount` / `home_withdraw_unlocked` | - -运行： - -```bash -docker exec -w /app/www/slot/slot_console php82 vendor/bin/phpunit tests/Unit/FreeCreditsClientStatusTest.php tests/Unit/FreeCreditsEligibilityTest.php -``` - -## C 端约定（供联调） - -- **展示开关**：`data.status !== -1`；首充前为 `status === 0` -- **进度条上限**：`win_threshold` -- **注册赠送**：**不要**从 status 取；走注册/大厅配置接口 -- **Withdraw 解锁**：**不要**依赖 `home_withdraw_unlocked` 字段；用 `status` 或余额逻辑 - -## 不在本次范围 - -- status 返回 `initial_amount` / `home_withdraw_unlocked` -- 注册发奖改读 `ext_config.initial_amount_qf` -- slot_pwa / gateway 前端改动 -- backend 后台 `initial_amount_qf` 编辑能力（已存在） - -## 验收清单 - -1. 无 player：`status=0`，含 `win_threshold`、`recharge_unlock_amount`、`help`，`packages=[]`，**无** `initial_amount`、`home_withdraw_unlocked` 键 -2. 有 player：含玩家态金额 + 同上配置字段 -3. 无资格/无配置：`status=-1` -4. 单测全部通过 diff --git a/plans/type11_活动初始金额_ee0e1a75.plan.md b/plans/type11_活动初始金额_ee0e1a75.plan.md deleted file mode 100644 index 2f81837..0000000 --- a/plans/type11_活动初始金额_ee0e1a75.plan.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -name: type11 活动初始金额 -overview: 在活动类型 11（Free Credits）后台编辑表单中新增「活动初始金额」字段，以美元小数录入、落库为 ext_config.initial_amount_qf；同步补齐 slot_admin 校验与列表展示。数据经现有 ActivityService 透传至 slot_console，本任务不改 slot_console 业务逻辑。 -todos: - - id: edit-vue-initial-amount - content: edit.vue：type=11 表单项 + setFormData/submit 的 initial_amount ↔ initial_amount_qf 转换 - status: completed - - id: index-vue-display - content: index.vue：type=11 列表 ext_config 展示活动初始金额 - status: completed - - id: validate-initial-amount - content: ActivityValidate::checkFreeCreditsExt 增加 initial_amount_qf 必填与非负校验 - status: completed - - id: manual-verify - content: 本地验证新建/编辑/回填/必填/列表展示 - status: completed -isProject: false ---- - -# 活动类型 11 增加「活动初始金额」后台配置 - -## 背景与范围 - -- 需求来源：[首充前免费余额定格与分档释放需求文档.md](docs/requirements/首充前免费余额定格与分档释放需求文档.md) 第 19 节将注册赠送调整为 `$30`；运营需在 **活动类型 11** 的配置里维护「用户注册时的初始金额」。 -- **已确认键名**：`initial_amount`（表单） / `initial_amount_qf`（落库，千分位整数）。 -- **范围**：仅 [backend/slot_admin](backend/slot_admin) 与 [backend/slot_admin_vue](backend/slot_admin_vue)；`ActivityController` 已透传 `ext_config` 至 `slot_console`，无需改 `slot_console` / `slot_lib`（新字段会原样写入 `s_recharge_gift_config.ext_config` JSON）。 - -## 现状（可复用） - -type=11 专属编辑已在 [edit.vue](backend/slot_admin_vue/src/views/game/activity/edit.vue) 实现 6 个金额字段 + Banner，模式为： - -- 编辑：`setFormData` 将 `*_qf ÷ 1000` 还原为美元小数 -- 提交：`submit` 将美元小数 `× 1000` 写入 `*_qf` -- 校验：[ActivityValidate::checkFreeCreditsExt](backend/slot_admin/app/game/validate/ActivityValidate.php) 在 [ActivityController](backend/slot_admin/app/game/controller/ActivityController.php) `save` / `update(updateData)` 时触发 - -```mermaid -flowchart LR - editVue["edit.vue submit"] --> adminApi["slot_admin ActivityController"] - adminApi --> activitySvc["slotLib ActivityService"] - activitySvc --> consoleInner["slot_console innerapi/activity"] - consoleInner --> extConfig["ext_config JSON"] -``` - -## 字段定义 - -| UI 标签 | 表单字段 | 落库字段 | 说明 | -| --- | --- | --- | --- | -| 活动初始金额($) | `ext_config.initial_amount` | `initial_amount_qf` | 用户注册时赠送的免费余额金额；placeholder 建议 `30`（对齐需求文档 $30） | - -金额处理与现有 6 项一致：`Math.round(Number(v) * 1000)`，回填优先读 `_qf`。 - -## 改动清单 - -### 1. 编辑表单 — [edit.vue](backend/slot_admin_vue/src/views/game/activity/edit.vue) - -在 `v-if="formData.type == 11"` 区块 **最上方** 增加表单项（置于「首笔赢取门槛」之前）： - -```vue - - - -``` - -**`setFormData`（type===11 分支）** 增加映射： - -```js -initial_amount: e.initial_amount_qf != null ? e.initial_amount_qf / 1000 : e.initial_amount, -``` - -**`submit`（type===11 分支）** 在 `data.ext_config` 中增加： - -```js -initial_amount_qf: toQf(e.initial_amount), -``` - -### 2. 列表展示（可选但建议）— [index.vue](backend/slot_admin_vue/src/views/game/activity/index.vue) - -在 type===11 的 `ext_config` 模板中增加一行，复用已有 `formatExtAmount`： - -```vue -
活动初始金额: ${{ formatExtAmount(record.ext_config.initial_amount_qf, record.ext_config.initial_amount) }}
-``` - -### 3. 后端校验 — [ActivityValidate.php](backend/slot_admin/app/game/validate/ActivityValidate.php) - -在 `checkFreeCreditsExt()` 的 `$required` 数组追加： - -```php -'initial_amount_qf' => '活动初始金额', -``` - -校验规则与现有金额字段一致：必填、非负整数（千分位）。若业务要求注册赠送必须大于 0，可将条件改为 `(int)$extConfig[$key] <= 0` 时报错（与运营确认；默认可先仅要求 `>= 0`，与「首笔赢取门槛」等一致）。 - -更新方法 PHPDoc：由「6 个金额字段」改为「7 个金额相关字段」。 - -### 4. 无需改动的文件 - -- [ActivityController.php](backend/slot_admin/app/game/controller/ActivityController.php)：已按 type===11 调用 `checkFreeCreditsExt`，无需新增分支。 -- `slot_console` / `slot_lib`：本任务只落库配置；注册发奖仍走 `game_base.user_register_reward`，后续若要从 type=11 的 `initial_amount_qf` 读配置，属独立 console 改造。 - -## 数据流示意 - -```mermaid -sequenceDiagram - participant Op as 运营后台 - participant Vue as edit.vue - participant Val as ActivityValidate - participant DB as ext_config JSON - - Op->>Vue: 填写 initial_amount=30 - Vue->>Val: submit initial_amount_qf=30000 - Val->>DB: 校验通过并保存 - Note over DB: 后续 console 可用 configAmount(config,'initial_amount',default) -``` - -## 验证步骤 - -1. 新建/编辑 type=11 活动：可见「活动初始金额」，默认 placeholder 30。 -2. 保存后 DB/API 返回的 `ext_config` 含 `initial_amount_qf`（如 30 → 30000）。 -3. 再次打开编辑：回填为 30（美元）。 -4. 必填校验：留空提交应被 `checkFreeCreditsExt` 拦截。 -5. 列表页 type=11 行展示「活动初始金额」。 -6. 仅改状态（`updateData` 为空）的 update 请求仍不触发 ext 校验（现有逻辑保持不变）。 - -## 风险与说明 - -- **与注册发奖未联动**：本任务只完成后台配置录入；`UserRegisterEventService` 仍读 `game_base.user_register_reward`，改活动配置不会自动改变注册到账，需后续 console 改造读取 `initial_amount_qf`。 -- **全量覆盖 ext_config**：`edit.vue` submit 对 type=11 会重建整个 `ext_config` 对象；新增字段必须同时写入 submit 与 setFormData，避免编辑时丢失其它键（当前实现已是全量重建，与现有一致）。 diff --git a/plans/wallet-bet-win-api-split_8d6f7dea.plan.md b/plans/wallet-bet-win-api-split_8d6f7dea.plan.md deleted file mode 100644 index 753d8fd..0000000 --- a/plans/wallet-bet-win-api-split_8d6f7dea.plan.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: wallet-bet-win-api-split -overview: 评估并规划将 bet/win 从统一 update 入口中显式拆分为独立 API，同时保留兼容性与幂等语义。 -todos: - - id: add-bet-win-controller-endpoints - content: 新增 wallet/bet 与 wallet/win 控制器入口，保留 update 兼容 - status: completed - - id: split-validator-dto - content: 拆分 bet/win DTO 与校验场景，减少 type 分支耦合 - status: completed - - id: proxy-update-for-compat - content: 让 update 的 bet/win 分支复用新入口流程，确保行为完全一致 - status: completed - - id: docs-and-migration - content: 补充 README/doc 迁移说明与灰度/下线节奏 - status: completed -isProject: false ---- - -# Bet/Win API 拆分评估与迁移计划 - -## 结论 -- 对资金域来说，**对外 API 语义上拆分 `bet` / `win` 会更好**：可读性、接入防错、风控审计与权限隔离都会更清晰。 -- 但不建议直接废弃 `update`；建议采用“**新增独立接口 + `update` 兼容转发 + 渐进下线**”的迁移路线，避免影响现有上游与历史幂等键。 - -## 现状依据 -- 当前只有一个入口 [`app/api/controller/WalletController.php`](app/api/controller/WalletController.php) 的 `update()`，通过 `type` 分发。 -- 分发逻辑在 [`app/api/logic/WalletLogic.php`](app/api/logic/WalletLogic.php) 的 `ACTION_METHOD_MAP`，`bet/win` 已是独立业务方法。 -- 入参模型 [`app/api/dto/request/wallet/WalletUpdateRequestDTO.php`](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 同时承载多类交易，`round_id`、`is_end` 仅对 bet/win 有意义。 -- 校验器 [`app/validator/Wallet2Validator.php`](app/validator/Wallet2Validator.php) 也是“单场景 + 按 type 条件校验”，存在语义混杂。 - -## 目标形态 -- 提供显式 API：`wallet/bet`、`wallet/win`（自动路由下对应 Controller 方法）。 -- `wallet/update` 保留为兼容入口：内部仅做 DTO 转换与分发，不承载新能力。 -- 资金与幂等规则保持不变：仍以 `biz_id` + `type`（必要时叠加 `round_id`）确保可追溯与幂等。 - -## 实施步骤 -1. 在 [`app/api/controller/WalletController.php`](app/api/controller/WalletController.php) 新增 `bet()` 与 `win()` 方法，复用统一返回封装。 -2. 拆分请求 DTO 与校验场景： - - 新增 bet/win 专用 DTO（从 `WalletUpdateRequestDTO` 中抽取必要字段）。 - - 在 [`app/validator/Wallet2Validator.php`](app/validator/Wallet2Validator.php) 增加 `SCENE_BET`、`SCENE_WIN`，去掉“按 type 再二次判断”的耦合。 -3. 在 Logic 层保持复用： - - Controller 仍调用 [`app/api/logic/WalletLogic.php`](app/api/logic/WalletLogic.php) 现有 `bet()` / `win()` 实现，避免资金路径重写。 - - `update()` 对 bet/win 请求改为调用新入口共享流程（或内部代理），确保行为一致。 -4. 文档与对接迁移： - - 在 [`README.md`](README.md) 与 [`doc/wallet.md`](doc/wallet.md) 补充“新接口 + 兼容期 + 下线节奏”。 - - 给上游约定迁移窗口，监控 `update(type=bet|win)` 调用量后再决定是否下线。 - -## 验证要点 -- 幂等：重复 `biz_id` 命中行为与现状一致。 -- Round：`win` 的 `is_end=0/1` 中间派奖与最终结算语义不变。 -- 资金正确性：下注扣款顺序、派奖分配、流水字段不变。 -- 可回滚：任一阶段可回退为仅使用 `update` 入口。 \ No newline at end of file diff --git a/plans/win返回余额叠加pending_151a7ce9.plan.md b/plans/win返回余额叠加pending_151a7ce9.plan.md deleted file mode 100644 index 68e1fd2..0000000 --- a/plans/win返回余额叠加pending_151a7ce9.plan.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: win返回余额叠加pending -overview: 仅在 win 派奖流程中，对返回给第三方的余额叠加本局 pending 派奖，解决连续派奖期间玩家看到余额不增长的问题；不改其他接口。 -todos: - - id: win-response-overlay - content: 仅在 win is_end=0 返回值叠加 pendingRoundAmount 到 w/withdraw - status: completed - - id: idempotent-display-check - content: 确认 dedupe 命中时返回余额不重复增长 - status: completed - - id: final-settlement-regression - content: 确认 is_end=1 结算与 pending 清理行为不受影响 - status: completed -isProject: false ---- - -# win 派奖返回余额叠加 pending（仅 win 场景） - -## 目标 -在不改变真实账务入账时机（仍以 `is_end=1` Final Settlement 为准）的前提下，让第三方在连续派奖时拿到“可展示余额”： -- `is_end=0`：返回余额包含本局 pending -- 其他场景：不改 - -## 当前问题定位 -在 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()` 中： -- `is_end=0` 已做 pending 累计 -- 但返回值仍是 DB 真实余额（未叠加 pending），导致第三方展示不变 - -## 最小改动方案 -仅修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`： -1. 在 `is_end=0` 分支中，累计完成后读取 `pendingRoundAmount = getPendingWinByRound()`。 -2. 返回给第三方时，将 `withdraw`/`w` 做展示叠加： - - `w = wallet.withdraw_balance + pendingRoundAmount` - - `withdraw = wallet.withdraw_balance + pendingRoundAmount` -3. `deposit` / `bonus` 保持真实值（不动）。 -4. `is_end=1` 维持现有逻辑：合并 pending 后走真实结算并清理 pending。 - -## 兼容与风险 -- 仅影响 `type=win` 的返回体，不影响 DB、Lot、流水、下注规则。 -- 若第三方把 `w` 当“可立即下注余额”，会产生语义差异（展示值 > 真实可用）；但你当前业务前提是第三方只负责展示。 - -## 验收点 -- 连续 `is_end=0`：返回 `w/withdraw` 逐次增长（包含 pending） -- 重复 `biz_id` 的 `is_end=0`：返回值不重复增长 -- `is_end=1` 后：返回值与真实结算后余额一致，pending 被清理 \ No newline at end of file diff --git a/plans/中间派奖余额可见化_175ab934.plan.md b/plans/中间派奖余额可见化_175ab934.plan.md deleted file mode 100644 index 7292b64..0000000 --- a/plans/中间派奖余额可见化_175ab934.plan.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: 中间派奖余额可见化 -overview: 在保持 Final Settlement 真账口径不变的前提下，让 is_end=0 中间派奖实时反映到三方读取的余额（接口返回和钱包查询）。 -todos: - - id: pending-win-keys - content: 设计并接入 pending round/total 与 dedupe Redis key - status: pending - - id: win-is-end-branch - content: 实现 is_end=0 累计展示、is_end=1 合并结算与清理 - status: pending - - id: wallet-query-overlay - content: 让 wallet 查询叠加 pending total 返回最新展示余额 - status: pending - - id: dto-validator-update - content: 补齐 is_end DTO 与 win round_id 校验 - status: pending - - id: regression-cases - content: 验证多次派奖余额可见、最终结算、幂等与失败重试场景 - status: pending -isProject: false ---- - -# 中间派奖余额可见化（is_end）改造计划 - -## 目标 -解决“多次派奖时三方读取余额不更新”的问题，同时保持 `win.md` 的核心原则： -- 真正入账、Lot 回流、转化/解锁只在 `is_end=1`（Final Settlement）执行 -- `is_end=0` 仅做中间派奖累计与展示余额更新 - -## 核心思路 -在 Redis 维护“待结算派奖池（Pending Win）”，并把它叠加到对外返回余额： -- DB 里的 `withdraw/deposit/bonus` 仍保持真实账 -- 对外给三方的余额 = 真实账 + pendingWin - -这样能保证： -- 三方实时看到余额变化 -- 不破坏现有 `WinService` 的 Round Final Settlement 账务逻辑 - -## 具体改造 - -### 1) 新增 Pending Win 缓存层 -修改 [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php)：新增 key -- `wallet:win:pending:round:{uid}:{currency}:{round_id}`（每局中间派奖累计） -- `wallet:win:pending:total:{uid}:{currency}`（用户币种维度累计，供快速读余额） -- `wallet:win:dedupe:{uid}:{currency}:{round_id}:{biz_id}`（中间派奖严格幂等） - -### 2) win 分支行为 -修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `win()`： -- `is_end=0`： - - 命中 dedupe 直接返回 - - 未命中则 `INCRBY pending:round` 与 `INCRBY pending:total` - - 返回余额时把 `pending:total` 叠加到 `withdraw`（仅对外展示） - - 不调用 `WinService::execute`、不写 `BIZ_TYPE_WIN` -- `is_end=1`： - - 读取 `pending:round`，`finalWin = fee + pendingRound` - - 用 `finalWin` 调用现有 [app/service/wallet/WinService.php](app/service/wallet/WinService.php) - - 成功后清理 `pending:round` 并从 `pending:total` 扣除对应值 - - 返回余额按真实账（此时 pending 已回收） - -### 3) 钱包查询返回也要可见化 -修改 [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) 的 `query()` 返回： -- 将 `pending:total` 叠加到返回字段 `w/withdraw` -- 这样第三方无论读 `win` 返回还是调用 `wallet` 查询，都看到“最新展示余额” - -### 4) DTO/校验补齐 -- 在 [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) 增加 `is_end`（默认 1） -- 在 [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php) 增加： - - `is_end` 仅允许 `0/1` - - `win` 场景强制 `round_id` 必传 - -## 一致性与幂等 -- `is_end=0`：Redis dedupe（biz_id 级）防重复累计 -- `is_end=1`：延续现有 `wallet_log(uid,biz_id,biz_type=win)` 幂等 -- 若 Final 失败，不清 pending，便于重试恢复 - -## 风险说明（需明确） -- 该方案是“展示余额实时、真账延后”：若上游把展示余额当可立即可下注余额，可能出现下注时余额校验不一致。 -- 若你需要“中间派奖立即可下注”，则要走另一套方案（中间账临时入库 + Final 对冲重分配），改动会显著更大。 - -## 改动文件 -- [app/service/RedisKeyManagerService.php](app/service/RedisKeyManagerService.php) -- [app/api/dto/request/wallet/WalletUpdateRequestDTO.php](app/api/dto/request/wallet/WalletUpdateRequestDTO.php) -- [app/validator/Wallet2Validator.php](app/validator/Wallet2Validator.php) -- [app/api/logic/WalletLogic.php](app/api/logic/WalletLogic.php) - -## 验收场景 -- 多次 `is_end=0` 后，`win` 返回余额递增 -- 多次 `is_end=0` 后，`wallet` 查询余额递增 -- `is_end=1` 触发后，final 入账金额 = 中间累计 + 最后一笔 -- 重放同一 `is_end=0` `biz_id` 不重复累计 -- 重放同一 `is_end=1` `biz_id` 不重复结算 \ No newline at end of file diff --git a/plans/任务进度筛选对接_acbb7213.plan.md b/plans/任务进度筛选对接_acbb7213.plan.md deleted file mode 100644 index 919643b..0000000 --- a/plans/任务进度筛选对接_acbb7213.plan.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -name: 任务进度筛选对接 -overview: 新增独立分页接口 `player-task/task-list`（筛选 task_type + status + page/page_size），供前端双下拉表格使用；保留现有 `player-task/task-progress` 全量快照不变。同步 slot_sdk 与 API 文档。 -todos: - - id: wallet-model-paginate - content: WalletFundLotModel 新增 paginatePlayerTaskLots（按 lot_type/status 分页） - status: completed - - id: wallet-task-list-api - content: 新增 taskList 全链路（Validator/DTO/Logic/Service/Controller） - status: completed - - id: sdk-task-list - content: slot_sdk 新增 taskList 请求/响应实体与 WalletService 方法 - status: completed - - id: api-doc-list - content: 新增 doc/player-task-list-api.md（含前端双下拉 + 分页说明） - status: completed - - id: feature-tests-list - content: Feature 测试：筛选、分页、参数校验；task-progress 回归不变 - status: completed -isProject: false ---- - -# 玩家任务进度：新增分页列表接口 - -## 背景与目标 - -- **现有** [`player-task/task-progress`](doc/player-task-progress-api.md)：只读全量快照（`bonus_tasks` + `deposit_tasks` + `summary`），**不改契约**，继续给大厅/SDK 轻量查询用。 -- **新增** `player-task/task-list`：面向 **前端操作页**（双下拉 + 表格），支持 **类型筛选、状态筛选、分页**。 - -前端操作区： - -| 下拉框 | 选项 | 说明 | -|--------|------|------| -| 任务类型 | **Bonus** / **Deposit** | 必填，二选一 | -| 状态 | **全部** + Waiting / Active / PendingConversion / PlayedOut | `status=0` 或不传 = 全部可见态 | - -```mermaid -flowchart TB - subgraph keep [保持不变] - TP["POST task-progress"] - TP --> Full["bonus_tasks + deposit_tasks 全量"] - end - subgraph newApi [新增] - TL["POST task-list"] - TL --> Filter["task_type + status"] - TL --> Page["page + page_size"] - Page --> List["list + 分页元数据"] - end - UI[前端表格页] --> TL - Lobby[大厅轻量展示] --> TP -``` - ---- - -## 1. 新接口契约 - -### 1.1 路由 - -| 项 | 值 | -|----|-----| -| Method | `POST` | -| Path | `player-task/task-list` | -| Controller | [`PlayerTaskController::taskList`](app/api/controller/PlayerTaskController.php)（新增方法） | - -### 1.2 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `uid` | int | 是 | 用户 ID | -| `currency` | string | 是 | 币种，如 `TGO` | -| `task_type` | string | **是** | `bonus` \| `deposit` | -| `status` | int | 否 | `0` 或省略 = 全部玩家可见态；`1`/`2`/`3`/`5` = 单态 | -| `page` | int | 否 | 页码，默认 `1`，最小 `1` | -| `page_size` | int | 否 | 每页条数，默认 `20`，建议上限 `100` | - -校验（[`PlayerTaskValidator`](app/validator/PlayerTaskValidator.php) 新 scene `list`）： - -- `uid`：`require|integer` -- `currency`：`require` -- `task_type`：`require|in:bonus,deposit` -- `status`：`integer|in:0,1,2,3,5`（可空，默认 0） -- `page`：`integer|egt:1`（可空） -- `page_size`：`integer|between:1,100`（可空） - -**前端映射**： - -| UI | 请求 | -|----|------| -| Bonus | `"task_type": "bonus"` | -| Deposit | `"task_type": "deposit"` | -| 全部 | 不传 `status` 或 `"status": 0` | -| Waiting / Active / … | `status` = `1` / `2` / `3` / `5` | -| 翻页 | 修改 `page`（切换筛选时重置 `page=1`） | - -### 1.3 成功响应 `data` - -与仓库 [`SearchShardService`](app/service/search/shard/SearchShardService.php) 分页习惯对齐（`data` → `list`）： - -```json -{ - "task_type": "bonus", - "list": [ /* PlayerTaskItem，与 task-progress 任务项字段相同 */ ], - "total": 15, - "page": 1, - "page_size": 20, - "last_page": 1 -} -``` - -- `list[]` 元素结构 **复用** [`PlayerTaskItemEntity::toApiArray()`](app/entity/wallet/PlayerTaskItemEntity.php)（与 `task-progress` 单条一致）。 -- 排序：`consume_priority_at ASC`, `lot_id ASC`（与现 [`listPlayerTaskLots`](app/model/multi/WalletFundLotModel.php) 一致）。 -- 状态范围：默认仍为 PRD §26.1 四态 `[1,2,3,5]`；**不含** Completed/Cancelled/Reversed（与 `task-progress` 一致）。 - -### 1.4 与 `task-progress` 的分工 - -| 接口 | 场景 | 返回 | -|------|------|------| -| `task-progress` | 一次拿全量两类任务 + 计数汇总 | `summary` + `bonus_tasks` + `deposit_tasks` | -| `task-list` | 表格页：选定类型 + 状态 + 翻页 | 单维 `list` + 分页字段 | - ---- - -## 2. wallet 实现要点 - -### 2.1 Model - -在 [`WalletFundLotModel`](app/model/multi/WalletFundLotModel.php) 新增： - -```php -/** - * 分页查询玩家任务 Lot。 - * @return array{list: array, total: int, page: int, page_size: int, last_page: int} - */ -public function paginatePlayerTaskLots( - string $currency, - int $lotType, - array $statuses, - int $page, - int $pageSize -): array -``` - -- `statuses` 为空时直接返回空分页（与 `listPlayerTaskLots` 一致）。 -- 使用 ThinkORM `paginate($pageSize, false, ['page' => $page])`，再将 `data` 重命名为 `list`。 - -### 2.2 Service - -在 [`PlayerTaskQueryService`](app/service/wallet/PlayerTaskQueryService.php) 新增 `queryTaskList(...)`： - -- `task_type` 字符串 → `LOT_TYPE_BONUS` / `LOT_TYPE_DEPOSIT` -- `status` → `PLAYER_VISIBLE_STATUSES` 或单元素数组 -- 调用 Model 分页后，`buildTaskItems()` 组装 `list` - -### 2.3 分层文件（新增/扩展） - -| 层级 | 文件 | -|------|------| -| DTO | `app/api/dto/request/PlayerTaskListRequestDTO.php`（新建） | -| Validator | `PlayerTaskValidator` 增加 `SCENE_LIST` | -| Logic | `PlayerTaskLogic::taskList()` | -| Controller | `PlayerTaskController::taskList()` | - -**不修改** `PlayerTaskProgressRequestDTO` / `taskProgress` 逻辑。 - ---- - -## 3. slot_sdk - -新增（与 wallet 字段 snake_case 一致）： - -| 类型 | 文件 | -|------|------| -| 请求 | `PlayerTaskListRequestEntity.php` | -| 响应 | `PlayerTaskListResponseEntity.php`（含 `list`、`total`、`page`、`page_size`、`last_page`、`task_type`） | - -[`WalletService`](slot_sdk/src/service/wallet/WalletService.php) 新增： - -```php -public function taskList(PlayerTaskListRequestEntity $entity): ?PlayerTaskListResponseEntity -// POST api/player-task/task-list -``` - -`taskProgress` / `PlayerTaskProgressRequestEntity` **保持不变**。 - -发布：slot_sdk commit → push → slot-wallet `composer update`。 - ---- - -## 4. 文档 - -- **新建** [`doc/player-task-list-api.md`](doc/player-task-list-api.md)：路由、入参、响应、前端双下拉 + 翻页交互、与 `task-progress` 对比、curl 示例。 -- [`doc/player-task-progress-api.md`](doc/player-task-progress-api.md) 顶部增加「列表分页请用 task-list」交叉引用。 -- [`doc/wallet.md`](doc/wallet.md) §26.1 补充 `task-list` 一行说明。 - ---- - -## 5. 测试 - -新建 `tests/Feature/PlayerTaskListTest.php`（造数参考 [`WalletRegisterBetWinTest`](tests/Feature/WalletRegisterBetWinTest.php)）： - -| 用例 | 断言 | -|------|------| -| `task_type=bonus` + 默认分页 | `list` 非空项字段完整；`total >= len(list)` | -| `status=2` | `list` 内 `status` 均为 2 | -| `page=2` + `page_size=1` | 第二页与总数一致 | -| 缺 `task_type` | `40003` | -| `page_size=101` | `40003` | -| `task-progress` 仍返回双数组 | 回归，不受新接口影响 | - -容器内执行：`docker compose exec -T php82` + 项目 PHPUnit 命令。 - ---- - -## 6. 不在本次范围 - -- 修改 `task-progress` 入参或响应 -- 任务类型「全部」合并在一个列表 -- 运营后台终态（Completed 等）纳入筛选 -- 前端页面实现（本仓库无前端） - ---- - -## 7. 关键文件一览 - -| 仓库 | 变更 | -|------|------| -| slot-wallet | `PlayerTaskController`、`PlayerTaskLogic`、`PlayerTaskQueryService`、`WalletFundLotModel`、`PlayerTaskValidator`、新 DTO、`doc/player-task-list-api.md`、Feature 测试 | -| slot_sdk | 新 Entity ×2、`WalletService::taskList`、`readme.md` | diff --git a/plans/异步事件单元测试_0dbff6a0.plan.md b/plans/异步事件单元测试_0dbff6a0.plan.md deleted file mode 100644 index 3f22169..0000000 --- a/plans/异步事件单元测试_0dbff6a0.plan.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -name: 异步事件单元测试 -overview: 结合 slot_console 现有 Free Credits 测试实践，说明异步 MQ 事件应分层测试：不直连 RabbitMQ，优先测 Logic 编排，再补 Event 解析与 EventBus 路由；并给出可新增的示例用例结构。 -todos: - - id: entity-test - content: 新增 FreeCreditInitEntityTest：字段映射与 resolveWalletAmount 回退 - status: completed - - id: bus-factory - content: 新增 tests/Support/ConsoleBusMessageFactory 统一构造 MQBusEntity 载荷 - status: completed - - id: extend-logic-tests - content: 扩展 FreeCreditsHandleFreeCreditInitTest：幂等、无配置、异常路径 - status: completed - - id: optional-event-inject - content: （可选）FreeCreditInitEvent 注入 Logic + Event 单测 - status: completed - - id: optional-eventbus-nack - content: （可选）EventBus deal 单测：TYPE_FREE_CREDIT_INIT 成功 ack / 失败 nack - status: completed -isProject: false ---- - -# 异步事件单元测试写法（slot_console） - -## 当前架构 - -```mermaid -sequenceDiagram - participant Wallet as slot_wallet - participant MQ as RabbitMQ_console_bus - participant Bus as EventBus_deal - participant Ev as FreeCreditInitEvent - participant Logic as FreeCreditsLogic - - Wallet->>MQ: JSON uid/type/data - MQ->>Bus: AMQPMessage - Bus->>Ev: case TYPE_FREE_CREDIT_INIT - Ev->>Ev: FreeCreditInitEntity - Ev->>Logic: handleFreeCreditInit - Logic->>Logic: freezeFirstRecharge + wallet RPC -``` - -**结论**：异步只发生在 MQ 传输层；单测应测 **消息解析 → 路由 → 业务编排**，而不是启动真实 `event:bus` 或 RabbitMQ。 - ---- - -## 项目里已有的做法（推荐延续） - -### 1. 单元测试：直接测 Logic（主路径） - -现有 [`tests/Unit/FreeCreditsHandleFreeCreditInitTest.php`](/Users/ray/Documents/project/www/slot/slot_console/tests/Unit/FreeCreditsHandleFreeCreditInitTest.php) 已覆盖 `free_credit_init` 的**业务结果**，等价于事件消费后的效果： - -- [`FreeCreditsLogicHarness`](/Users/ray/Documents/project/www/slot/slot_console/tests/Support/FreeCreditsLogicHarness.php)：注入 `userContext` / `activeConfig` / `walletService` -- [`RecordingWalletService`](/Users/ray/Documents/project/www/slot/slot_console/tests/Support/RecordingWalletService.php)：记录 `freeCreditsFreeze`，不发 HTTP -- [`FreeCreditsConfigStub`](/Users/ray/Documents/project/www/slot/slot_console/tests/Support/FreeCreditsConfigStub.php)：活动配置桩 - -断言示例（已有）： - -- 定格金额 = `balance_before_qf` -- `biz_id` = `free_credits_freeze:{orderId}` -- `balance_before_qf <= 0` 时不调用 freeze - -**运行**： - -```bash -cd slot_console && ./vendor/bin/phpunit --testsuite Unit -``` - -提现三类事件同理：[`tests/Integration/FreeCreditsLogicCashoutResultTest.php`](/Users/ray/Documents/project/www/slot/slot_console/tests/Integration/FreeCreditsLogicCashoutResultTest.php) 直接调 `handleFirstCashoutResult`，不经过 EventBus。 - -### 2. 集成测试：需要 DB 时 - -[`FreeCreditsDbTestCase`](/Users/ray/Documents/project/www/slot/slot_console/tests/Integration/FreeCreditsDbTestCase.php)：`RUN_DB_TESTS=1` 才跑，默认事务回滚。 - -```bash -RUN_DB_TESTS=1 ./vendor/bin/phpunit --testsuite Integration --filter FreeCredits -``` - ---- - -## 建议的分层（按投入产出排序） - -| 层级 | 测什么 | 是否必需 | 依赖 | -|------|--------|----------|------| -| A. Entity | `FreeCreditInitEntity` 字段映射、`resolveWalletAmount()` 回退 | 推荐 | 无 | -| B. Logic | `handleFreeCreditInit` / `handleFirstCashoutResult` 编排 | **已有，继续扩展** | Harness + RecordingWallet | -| C. Event | `FreeCreditInitEvent::handle` 把 `MQBusEntity` 转成 Logic 参数 | 可选 | 需可注入 Logic（见下） | -| D. EventBus | `deal()` 按 `type` 分发、失败 nack | 少量即可 | Mock `AMQPMessage` | -| E. E2E | 真 MQ + wallet 发消息 | 手工/脚本，非单测 | 环境 | - -**原则**：B 覆盖 90% 风险；A 防 payload 字段错；C/D 防「路由写错 type」和「实体解析漏字段」。 - ---- - -## 可新增的测试示例 - -### A. Entity 单测（纯数组 → 实体） - -新建 `tests/Unit/FreeCreditInitEntityTest.php`： - -```php -$entity = new FreeCreditInitEntity([ - 'balance_before_qf' => 15000, - 'wallet_amount' => 0, - 'amount' => 5000, - 'biz_id' => 'order_1', -]); -$this->assertSame(15000, $entity->balance_before_qf); -$this->assertSame(5000, $entity->resolveWalletAmount()); // wallet_amount 为 0 时回退 amount -``` - -对应生产代码：[`app/entity/mq/FreeCreditInitEntity.php`](/Users/ray/Documents/project/www/slot/slot_console/app/entity/mq/FreeCreditInitEntity.php)。 - -### B. 构造 MQ 载荷辅助方法 - -在 `tests/Support/` 增加工厂，统一模拟 wallet 发出的 body： - -```php -public static function consoleBusMessage(int $uid, string $type, array $data): MQBusEntity -{ - return new MQBusEntity(['uid' => $uid, 'type' => $type, 'data' => $data]); -} - -// free_credit_init 示例 -public static function freeCreditInitBus(int $uid, int $balanceBefore, int $walletAmount, string $bizId): MQBusEntity -{ - return self::consoleBusMessage($uid, MQBusEntity::TYPE_FREE_CREDIT_INIT, [ - 'balance_before_qf' => $balanceBefore, - 'wallet_amount' => $walletAmount, - 'biz_id' => $bizId, - 'source' => 'test', - 'currency' => 'INR', - ]); -} -``` - -与 [`WalletLogic::sendConsoleBus`](/Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) 字段保持一致。 - -### C. Event 层单测（当前结构的限制） - -[`FreeCreditInitEvent`](/Users/ray/Documents/project/www/slot/slot_console/app/command/event/FreeCreditInitEvent.php) 内部写死 `new FreeCreditsLogic()`，**无法在不改代码的情况下 mock Logic**。 - -两种做法（二选一）： - -1. **小重构（推荐）**：Event 构造函数注入 `FreeCreditsLogic`，单测传入 `FreeCreditsLogicHarness`。 -2. **不测 Event**：认为 Event 只有 5 行胶水，由 B 层保证；仅加 A 层测 data 解析。 - -若采用 1，示例： - -```php -$bus = ConsoleBusMessageFactory::freeCreditInitBus($uid, 15000, 5000, 'order_1'); -$harness = (new FreeCreditsLogicHarness())->inject($context, $config, $wallet); -(new FreeCreditInitEvent($harness))->handle($bus); -$this->assertCount(1, $wallet->freezeCalls); -``` - -### D. EventBus 路由单测（少量） - -Mock `PhpAmqpLib\Message\AMQPMessage`： - -```php -$message = $this->createMock(AMQPMessage::class); -$message->method('getBody')->willReturn(json_encode([ - 'uid' => 90088002, - 'type' => MQBusEntity::TYPE_FREE_CREDIT_INIT, - 'data' => ['balance_before_qf' => 15000, 'wallet_amount' => 5000, 'biz_id' => 'x'], -])); -$message->expects($this->once())->method('ack'); // 成功应 ack - -$bus = new EventBus(); -// 若 Logic 仍 new 在 Event 内，需配合 C 的注入或接受集成测 -$bus->deal($message); -``` - -**nack 场景**（[`EventBus.php` L164-167](/Users/ray/Documents/project/www/slot/slot_console/app/command/EventBus.php)）：Logic 抛异常时，`TYPE_FREE_CREDIT_INIT` 应 `nack(true)` 且不 `ack`。可让 Harness 的 `freeCreditsFreeze` 抛异常，断言 `$message->expects($this->once())->method('nack')->with(true)`。 - -注意：`EventBus` 依赖多，路由测试宜 **只测 switch 分支 + ack/nack**，业务细节仍放 B。 - ---- - -## 四个 Free Credits 相关 type 怎么测 - -| MQ type（常量） | 单测重点 | 现有覆盖 | -|-----------------|----------|----------| -| `TYPE_FREE_CREDIT_INIT` | 定格金额、biz_id、幂等跳过 | `FreeCreditsHandleFreeCreditInitTest` | -| `TYPE_FREE_CREDITS_FIRST_CASHOUT_SUCCESS` | 档位 completed、player 状态 | `FreeCreditsLogicCashoutResultTest` | -| `TYPE_FREE_CREDITS_FIRST_CASHOUT_FAIL` | 失败回滚逻辑 | 可补 case | -| `TYPE_FREE_CREDITS_FIRST_CASHOUT_REJECTED` | rejected → ready | 已有 reject case | - -EventBus 里前三类目前 **直接调 Logic**（未走独立 Event 类），单测继续打 Logic 即可；常量定义在 [`MQBusEntity`](/Users/ray/Documents/project/www/slot/slot_console/app/entity/mq/MQBusEntity.php)。 - ---- - -## 不建议在单测里做的 - -- 启动 `php webman event:bus` 或连接真实 RabbitMQ -- 跨服务联调 wallet → console（留给脚本如 `scripts/run_free_credits_first_freeze.php` 或手工验收） -- 在单测里依赖 `UserTagService::getByUid`（用 Harness 注入 context） - ---- - -## 推荐落地顺序（若你要补测试） - -1. 补 `FreeCreditInitEntityTest`（A） -2. 补 `ConsoleBusMessageFactory`（B 辅助） -3. 扩展 `FreeCreditsHandleFreeCreditInitTest`：无活动配置、已定格幂等、Logic 抛错 -4. （可选）`FreeCreditInitEvent` 注入 Logic + Event 单测（C） -5. （可选）`EventBusFreeCreditInitTest` 只测 ack/nack（D） - -```mermaid -flowchart TD - subgraph unit [Unit 无 MQ] - E[EntityTest] - L[LogicHarnessTest] - end - subgraph optional [Optional] - Ev[EventTest] - Bus[EventBusRoutingTest] - end - subgraph integration [Integration RUN_DB_TESTS] - DB[DbTestCase] - end - E --> L - L --> Ev - Ev --> Bus - L --> DB -``` diff --git a/plans/拆分win派奖文档_adbf09a1.plan.md b/plans/拆分win派奖文档_adbf09a1.plan.md deleted file mode 100644 index d4bacb2..0000000 --- a/plans/拆分win派奖文档_adbf09a1.plan.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: 拆分win派奖文档 -overview: 将 wallet PRD 中与 win（派奖）强相关的需求从主文档拆分到独立文档，降低耦合并保持规则可追踪。计划默认采用“从 wallet.md 迁移到 win.md，并在原处保留索引入口”的方式。 -todos: - - id: identify-win-sections - content: 标记 wallet.md 中所有 win（派奖）主规则与引用依赖段落 - status: completed - - id: create-win-doc - content: 创建 win.md 并迁移/重组派奖规则、流程与示例 - status: completed - - id: refactor-wallet-doc - content: 在 wallet.md 用摘要+链接替换已迁移内容并更新目录 - status: completed - - id: consistency-pass - content: 统一术语与交叉引用，确保无重复冲突定义 - status: completed -isProject: false ---- - -# 将 win（派奖）需求拆分到独立文档 - -## 目标 -把 [doc/wallet.md](doc/wallet.md) 中“win（派奖）”相关需求整理到新文档 [doc/win.md](doc/win.md)，并保证两份文档职责清晰： -- `wallet.md` 保留钱包总规则与对外索引 -- `win.md` 承载派奖、Round 结算、出资分配等细则 - -## 拆分范围（默认） -从 [doc/wallet.md](doc/wallet.md) 迁移以下“win 主体”内容到 [doc/win.md](doc/win.md)： -- §12 `Slots 多次派奖与最终结算规则` -- §20 中 win 强相关子流程： - - `20.4 Round 多次派奖` - - `20.5 Round 最终结算` -- 与派奖直接相关且需避免重复维护的规则片段（在 `wallet.md` 中改为引用）： - - §10.3 `派奖归属规则` - - §11 中 `Round 总派奖` 分配示例 - - §16.2 `派奖按比例拆分余数` - -## 文档结构调整 -- 在 [doc/wallet.md](doc/wallet.md)： - - 保留“钱包主规则”定位 - - 将迁移段落替换为简要摘要 + 指向 [doc/win.md](doc/win.md) 的链接 - - 更新目录，新增 `win` 文档入口 -- 在 [doc/win.md](doc/win.md)： - - 新建“win（派奖）需求”专题文档 - - 按“背景 → 结算时序 → 分配规则 → 边界条件 → 示例流程”重组内容 - - 明确与 `Lot`、`Task`、`Withdrawable` 的关系，保留必要术语一致性（Round/FinalSettlement/AllocatedPayout） - -## 一致性与可维护性约束 -- 术语与口径与 [doc/wallet.md](doc/wallet.md) 保持一致（Bonus/Deposit/Withdrawable、Final Settlement、PlayedOut） -- 避免双份正文维护：同一规则只在一个文档定义，另一侧做引用 -- 若保留示例在两文档同时出现，仅保留“简版示意”在 `wallet.md`，完整口径放 `win.md` - -## 验收标准 -- [doc/win.md](doc/win.md) 可单独说明“派奖”完整业务规则 -- [doc/wallet.md](doc/wallet.md) 删除/替换原 win 细节后仍可作为钱包总览 -- 两文档目录和交叉链接可直接跳转，且不存在明显冲突描述 \ No newline at end of file diff --git a/plans/测试_register_bet_win_6f8e8ea1.plan.md b/plans/测试_register_bet_win_6f8e8ea1.plan.md deleted file mode 100644 index d879ad0..0000000 --- a/plans/测试_register_bet_win_6f8e8ea1.plan.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: 测试 register bet win -overview: 设计一套不改代码的联调测试方案，覆盖 register、bet、win（含中间派奖+最终结算）主流程、幂等与关键校验。输出可直接执行的请求序列和验收点。 -todos: - - id: collect-endpoints - content: 整理 register/bet/win 的可调用入口与参数最小集合 - status: completed - - id: define-test-cases - content: 设计主链路、幂等、参数异常三类用例 - status: completed - - id: prepare-request-templates - content: 产出按执行顺序排列的请求模板与预期结果 - status: completed -isProject: false ---- - -# Register/Bet/Win 测试计划 - -## 目标 -- 用最小链路验证 `register -> bet -> win` 的资金变更与返回口径。 -- 覆盖 `win` 的两阶段结算（`is_end=0` 中间派奖、`is_end=1` 最终结算）。 -- 覆盖关键风控点：幂等（重复 `biz_id`）、参数校验（`round_id`、`is_end`、金额）。 - -## 关键实现依据（用于制定用例） -- 接口入口与兼容关系：[`app/api/controller/WalletController.php`](app/api/controller/WalletController.php) - - `wallet/bet`、`wallet/win` 为独立入口；`wallet/update(type=bet|win)` 复用同链路。 -- 业务分发与资金处理：[`app/api/logic/WalletLogic.php`](app/api/logic/WalletLogic.php) - - `register` 走 `RegisterService::execute`。 - - `bet` 按 `biz_id` 做幂等。 - - `win`：`is_end=0` 只累计待结算金额，`is_end=1` 才真正入账并清理缓存。 -- 注册落账与 Lot 初始化：[`app/service/wallet/RegisterService.php`](app/service/wallet/RegisterService.php) - - 注册会初始化钱包、统计行，并按 `fee/bonus` 创建 Deposit/Bonus Lot。 -- 请求参数约束：[`app/validator/Wallet2Validator.php`](app/validator/Wallet2Validator.php) - - bet/win 必传 `round_id`，`is_end` 仅支持 `0/1`。 - -## 测试范围与步骤 -1. **准备阶段** -- 选一个全新 `uid`（避免历史账干扰）。 -- 固定 `currency/source/organization`，并准备唯一 `biz_id` 生成规则（例如带时间戳）。 - -2. **主链路测试（Happy Path）** -- 调 `wallet/update` 发起 `register`（`type=register`，带 `fee` 与 `bonus`）。 -- 调 `wallet/wallet` 查询余额基线。 -- 调 `wallet/bet`（带 `round_id`）验证扣款与返回结构。 -- 调 `wallet/win` 且 `is_end=0`：确认返回中 `withdraw` 临时增加（待结算展示），但不落最终账。 -- 调 `wallet/win` 且 `is_end=1`：确认最终入账，并清理该 `round_id` 的待结算累计。 - -3. **幂等与异常场景** -- 重放同一 `bet.biz_id`：应命中幂等，余额不重复变化。 -- 重放同一 `win.biz_id`：应命中幂等，余额不重复变化。 -- 缺失 `round_id` 调 bet/win：应返回参数错误。 -- 传非法 `is_end`（如 2）：应返回参数错误。 - -4. **验收口径** -- 余额变化符合顺序：下注优先扣 Bonus，再 Deposit，再 Withdraw。 -- `win` 仅在最终结算时落地资金结果；中间派奖只累计。 -- 重复请求无重复记账，返回语义稳定。 - -## 建议请求流（逻辑顺序图） -```mermaid -flowchart TD - registerCall[register(update)] --> walletCheck1[wallet_query] - walletCheck1 --> betCall[bet] - betCall --> winMid[win_is_end_0] - winMid --> walletCheck2[wallet_query] - walletCheck2 --> winFinal[win_is_end_1] - winFinal --> walletCheck3[wallet_query] - walletCheck3 --> idemReplay[replay_same_biz_id] -``` - -## 交付物 -- 一份可直接在 Postman/curl 执行的请求模板（含示例 body）。 -- 一份对照清单：每一步的“预期返回 + 余额期望 + 幂等期望”。 \ No newline at end of file diff --git a/plans/测试报告可追踪输出_4fd907ad.plan.md b/plans/测试报告可追踪输出_4fd907ad.plan.md deleted file mode 100644 index de5c839..0000000 --- a/plans/测试报告可追踪输出_4fd907ad.plan.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: 测试报告可追踪输出 -overview: 在现有 WalletRegisterBetWinTest 上增加“可追踪测试报告”：每次执行输出并落盘 uid/round_id/biz_id/余额快照，失败时可直接按用户复现。 -todos: - - id: add-reporter-support - content: 新增 WalletTestRunContext 与 WalletTestReporter（JSON+Markdown 落盘） - status: completed - - id: wire-test-class - content: 改造 WalletRegisterBetWinTest：记录 uid/round/biz_id，tearDown 输出摘要 - status: completed - - id: config-and-doc - content: phpunit.xml 增加 WALLET_TEST_UID/REPORT_DIR；更新 doc 执行说明 - status: completed - - id: verify-run - content: 容器执行 phpunit 并确认控制台+报告文件含 uid - status: completed -isProject: false ---- - -# 钱包集成测试可追踪报告方案 - -## 问题 -当前 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 每个用例都会 `makeUid()` 生成随机用户，PHPUnit 默认只显示 `OK (3 tests, 37 assertions)`，**看不到本次用了哪个 `uid`、`round_id`、`biz_id`**，联调排障和 DB 核对都不方便。 - -## 目标 -- 跑完测试后，**控制台**能看到每个用例的测试用户与关键业务 ID。 -- **落盘一份报告**（JSON + 可读 Markdown），便于复制 `uid` 去查库或手工 curl 复现。 -- 可选：通过环境变量固定 `uid`，便于反复验证同一用户。 - -## 实现方案 - -### 1. 新增测试上下文与报告器 -新增 [tests/Support/WalletTestRunContext.php](tests/Support/WalletTestRunContext.php)： -- 字段：`testName`, `uid`, `currency`, `roundId`, `bizIds`（register/bet/win_mid/win_final）, `traceId`, `steps[]`（每步 API、code、余额快照）, `status`, `errorMsg`。 - -新增 [tests/Support/WalletTestReporter.php](tests/Support/WalletTestReporter.php)： -- `startRun()` / `recordStep()` / `finishTest()` / `writeReport()` -- 报告目录：`runtime/test-reports/`（文件名含时间戳，如 `wallet-register-bet-win-20260515-160530.json` 与同名 `.md`） -- Markdown 表格示例列：用例名 | uid | round_id | biz_id 列表 | 结果 | 最终余额(deposit/withdraw/b) - -### 2. 改造现有 Feature 测试 -在 [tests/Feature/WalletRegisterBetWinTest.php](tests/Feature/WalletRegisterBetWinTest.php) 中： -- `setUp()`：初始化 reporter；若存在 `WALLET_TEST_UID` 则使用该固定 uid（否则继续随机）。 -- 每个 `test*` 开始：创建 `WalletTestRunContext` 并记录 uid/round_id/biz_id。 -- `postJson()` / `wallet()`：成功后把 `code`、关键 `data`、查询余额写入 `steps`。 -- `tearDown()`：标记 pass/fail，调用 `writeReport()`；**向 STDOUT 打印一行摘要**（PHPUnit 控制台可见），例如： - - `[WalletTest] testRegisterBetWinFlow uid=90012345 round=r_... bet=bet_... => PASS` - -失败时 assertion message 附带 context 摘要，便于一眼定位用户。 - -### 3. 配置与文档 -- [phpunit.xml](phpunit.xml) 增加可选 env： - - `WALLET_TEST_UID`（空=随机） - - `WALLET_TEST_REPORT_DIR`（默认 `runtime/test-reports`） - - `WALLET_TEST_VERBOSE`（`1` 时打印每步明细） -- 更新 [doc/register-bet-win-test.md](doc/register-bet-win-test.md) §7： - - 报告路径说明 - - 固定 uid 复现示例：`WALLET_TEST_UID=90012345 docker compose exec ... phpunit ...` - -### 4. 执行验证 -容器内执行： -```bash -docker compose exec -T -w /app/www/ray/slot-wallet php82 php vendor/bin/phpunit --filter WalletRegisterBetWinTest -``` -验收： -- 控制台出现每个用例的 `uid` 摘要行 -- `runtime/test-reports/` 生成 `.json` + `.md` -- 测试仍全部通过（3 tests） - -## 报告结构示意 -```mermaid -flowchart LR - testCase[WalletRegisterBetWinTest] --> context[WalletTestRunContext] - context --> reporter[WalletTestReporter] - reporter --> stdout[ConsoleSummary] - reporter --> jsonFile[runtime/test-reports/*.json] - reporter --> mdFile[runtime/test-reports/*.md] -``` - -## 不在本阶段做的（可选后续） -- HTML 可视化报告、CI artifact 上传 -- DB 直连断言（wallet_log / wallet_fund_lot） \ No newline at end of file diff --git a/plans/玩家任务进度查询_bf651c60.plan.md b/plans/玩家任务进度查询_bf651c60.plan.md deleted file mode 100644 index 69e6ef3..0000000 --- a/plans/玩家任务进度查询_bf651c60.plan.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: 玩家任务进度查询 -overview: 新增一个面向玩家的只读接口，返回当前 Bonus/Deposit 任务及其打码进度与详情，数据口径以 PRD 定义的 `wallet_fund_lot` 为准。保持现有资金主流程不变，仅补充查询链路与文档说明。 -todos: - - id: define-player-task-endpoint - content: 新建独立玩家任务查询 Controller（不改 WalletController），并完成入参校验与统一返回 - status: pending - - id: add-lot-query-service - content: 在 wallet 域新增只读查询服务，按 PRD 聚合 bonus/deposit 当前任务视图并计算进度字段 - status: pending - - id: extend-fund-lot-model - content: 在 WalletFundLotModel 增加面向玩家任务页的查询方法（按币种、lot_type、状态过滤与排序） - status: pending - - id: document-api-contract - content: 更新 doc/wallet.md，补充玩家任务进度查询接口契约与状态语义 - status: pending - - id: verify-key-scenarios - content: 按基础与边界场景验证返回结构、进度计算和状态映射 - status: pending -isProject: false ---- - -# 玩家查看Bonus/Deposit任务与打码进度计划 - -## 目标与口径 -- 提供玩家侧查询能力：查看“当前仍在生命周期内”的 `Bonus` 与 `Deposit` 任务，以及每条任务的进度与关键详情。 -- 数据源以 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php) 为准，不再使用旧 `wager_task` 作为玩家任务主视图。 -- 任务状态遵循 PRD（`Waiting/Active/PendingConversion/PlayedOut` 等），并输出前端可直接消费的进度字段。 - -## 接口设计（新增） -- 新建独立 Controller 承载玩家查询接口（建议新增 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/PlayerTaskController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/PlayerTaskController.php) 并提供 `taskProgress` 方法），不在 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/WalletController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/WalletController.php) 增加行为。 -- 入参：`uid`、`currency`（可复用 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/validator/WalletValidator.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/validator/WalletValidator.php) 现有校验，或为新 Controller 补充专用 scene/validator）。 -- 出参建议： - - `summary`：当前 `bonus_task_count`、`deposit_task_count`。 - - `bonus_tasks[]` 与 `deposit_tasks[]`：每条含 `lot_id`、`lot_no`、`status`、`status_text`、`source_type`、`source_id`、`original_amount`、`remaining_amount`、`required_wager`、`current_wager`、`left_wager`、`progress_rate`、`created_at`、`completed_at`、`brief`。 -- “当前任务”默认筛选为：`status in (Waiting, Active, PendingConversion, PlayedOut)`；不返回 `Completed/Cancelled/Reversed`（避免历史噪音）。 - -## 分层落地 -- Logic/Service 层新增只读查询编排（建议放在 wallet 域 service，控制器不直接拼查询）： - - 查询指定用户指定币种的 Deposit/Bonus Lots； - - 按类型分组并按 `consume_priority_at, id` 排序； - - 统一计算衍生字段： - - `left_wager = max(required_wager - current_wager, 0)` - - `progress_rate = required_wager > 0 ? min(current_wager / required_wager, 1) : 1` - - 统一状态文案映射（与 PRD 对齐）。 -- Model 层在 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php) 补充专用查询方法（如按币种+lot_type+status 列表查询），保持 Controller/Logic 不下沉 SQL 细节。 - -## 文档与兼容 -- 在 [`/Users/ray/Documents/project/www/ray/slot-wallet/doc/wallet.md`](/Users/ray/Documents/project/www/ray/slot-wallet/doc/wallet.md) 的 API 建议章节补充“玩家任务进度查询”示例（字段说明与状态语义）。 -- 明确该接口是玩家视图；旧 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/TaskController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/TaskController.php) 维持兼容，不做破坏式改造。 - -## 验证计划 -- 基础场景：同时存在 Bonus/Deposit Active 任务，返回分组正确、进度计算正确。 -- 边界场景： - - `required_wager=0`（进度应视为 100%）； - - `current_wager > required_wager`（进度封顶 100%）； - - 仅有 PlayedOut Bonus（仍应展示，方便玩家理解“已用完未转化”）； - - 无当前任务（返回空数组与计数 0）。 -- 一致性检查：字段值与 `wallet_fund_lot` 原始记录一致，且状态解释符合 PRD。 \ No newline at end of file diff --git a/plans/跨服务_slot_sdk_约束_4e4faf5a.plan.md b/plans/跨服务_slot_sdk_约束_4e4faf5a.plan.md deleted file mode 100644 index 5a2a2ec..0000000 --- a/plans/跨服务_slot_sdk_约束_4e4faf5a.plan.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -name: 跨服务 slot_sdk 约束 -overview: 在用户级 Cursor 规则目录新增一条「跨服务通信」约束，用统一、可操作的术语规定：业务服务之间的 HTTP 互调必须经 `slot/sdk`（`slotsdk`）完成，并与现有 `backend-layering` 规则互补而不重复。 -todos: - - id: create-mdc - content: 新建 /Users/ray/.cursor/rules/cross-service-sdk.mdc（alwaysApply + 术语与调用规范） - status: completed - - id: consistency-check - content: 对照 backend-layering.mdc 确认交叉引用一致、无重复分层表 - status: completed - - id: optional-readme - content: （可选）在 slot_sdk/readme.md 增加简短架构说明 - status: completed -isProject: false ---- - -# 跨服务通信 Cursor 用户级约束 - -## 背景与目标 - -当前用户级规则在 [`/Users/ray/.cursor/rules/`](file:///Users/ray/.cursor/rules/) 已有： - -- [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) — 单服务内 Controller / Logic / Service 分层 -- [`dev-environment.mdc`](file:///Users/ray/.cursor/rules/dev-environment.mdc) — Docker 本地开发 -- [`php-doc.mdc`](file:///Users/ray/.cursor/rules/php-doc.mdc) — PHPDoc 规范 - -[`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) 仅在 Service 层职责里顺带提到「sdk」，**没有**规定跨服务 HTTP 的入口、命名与新增 API 的流程。本次新增**独立规则**（单一职责，符合 create-rule 实践），`alwaysApply: true`，与现有三条规则一致。 - -代码库事实（供规则用语对齐）： - -- 包名：`slot/sdk`，命名空间 `slotsdk\`，仓库 [`slot_sdk`](file:///Users/ray/Documents/project/www/slot/slot_sdk) -- 典型消费方：`slot_admin`、`slot_agent`、`slot_console`、`slot_pwa`（composer 依赖 `slot/sdk`） -- 典型被调方：`slot_wallet`、`slot_user`、`slot_center` 等，对外暴露 `innerapi/*`、`api/*` -- 推荐调用链：`new {Domain}Client($config)->service()->{method}(...)` -- 项目内已有表述：[`slot_agent/doc/feature_agent.md`](file:///Users/ray/Documents/project/www/slot/slot_agent/doc/feature_agent.md) —「代理服不直连用户域表，统一通过 `slot_sdk` 调用户服 innerapi」 - -按你的选择：**规则只约束新代码走 slot_sdk，不写 InnerCurlService / slot_lib 等 legacy 迁移条款。** - ---- - -## 术语优化（写入规则正文） - -| 避免说法 | 推荐说法 | 说明 | -| --- | --- | --- | -| 后端服务之间调用 / 中转 | **跨服务 HTTP 调用** | 明确是进程间 HTTP，不是本地 Logic/Service | -| 通过 slot/sdk 中转 | **经 slot_sdk 调用** | `slot_sdk` = 客户端库；被调服务仍直接处理请求，库不做业务中转 | -| SDK / 封装 | **slot_sdk（`slot/sdk`）** | 与 composer 包名、仓库目录一致 | -| 各服务自己拼 URL | **在 slot_sdk 增加 `{Domain}Service` 方法** | 路径与 DTO 单点维护 | -| `app\service\WalletService` | **本地 WalletService** vs **slotsdk WalletService** | 防止与 SDK 类名混淆 | - -核心定义（规则开篇 1 段）： - -> **slot_sdk** 是跨服务 HTTP 客户端库（`composer` 包 `slot/sdk`，命名空间 `slotsdk\`），用于**调用方服务**访问**被调服务**的 `innerapi/*` 或 `api/*` 接口。它不是独立部署的微服务。 - ---- - -## 拟新增文件 - -**路径：** [`/Users/ray/.cursor/rules/cross-service-sdk.mdc`](/Users/ray/.cursor/rules/cross-service-sdk.mdc) - -**Frontmatter：** - -```yaml ---- -description: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连 -alwaysApply: true ---- -``` - -**正文结构（约 35–45 行，中文为主）：** - -### 1. 适用范围 - -- 一个 Webman 服务需要 HTTP 访问另一个服务的 `innerapi` / `api` 时适用。 -- **被调服务**自身实现 Controller/Logic/Model，**不**为「被别人调」而引入 `slot/sdk`。 -- **调用方**若需调第三个服务，必须通过 `slot/sdk`（不在业务代码里手写 Guzzle/curl/拼 host+path）。 - -### 2. 标准调用方式 - -```php -use slotsdk\Config as SDKConfig; -use slotsdk\service\wallet\WalletClient; - -$config = new SDKConfig([ - 'host' => ShareConfigService::get('walletApiHost'), - 'headers' => ['server-name' => config('app.server_name')], -]); -$result = (new WalletClient($config))->service()->getStatistics($uids, $currency); -``` - -要点： - -- Host 来自 center 下发的 `*ApiHost`（如 `walletApiHost`、`userApiHost`）。 -- 请求头带 `server-name`，值为**当前调用方**服务名。 -- 非零 `code` 由 `slotsdk\exception\ApiException` 抛出，调用方在 Logic/Gateway 层处理。 - -### 3. 新增 / 变更远程接口的流程 - -1. 在 [`slot_sdk/src/service/{domain}/`](file:///Users/ray/Documents/project/www/slot/slot_sdk/src/service/) 增加 `{Domain}Service` 方法、路径常量、必要时 `entity/*Entity`。 -2. 在调用方 Logic 或 `*GatewayService` 中调用；Controller 保持薄。 -3. **禁止**在 `slot_admin` / `slot_agent` 等多仓库重复写同一路径字符串。 - -### 4. 与 backend-layering 的衔接（1–2 句） - -- 跨服务访问在调用方落在 **Service 或 `*GatewayService`**，Logic 编排用例；不把 HTTP 细节散落在 Controller。 -- 与 [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) 中「Service 可承载 sdk」一致；本规则专门约束**跨服务边界**，不重复写分层表。 - -### 5. 命名与混淆规避 - -- SDK：`slotsdk\service\{domain}\{Domain}Client`、`{Domain}Service`、`entity\{Name}Entity`。 -- 本地：`app\service\*`；若同名，用 `SDKConfig`、完整 namespace 或 import alias。 -- 消费方封装重复调用：`UserReferralGatewayService` 这类 `*GatewayService` 模式。 - ---- - -## 与现有规则的关系 - -```mermaid -flowchart LR - subgraph userRules [用户级 .cursor/rules] - layering[backend-layering] - crossSdk[cross-service-sdk 新增] - docker[dev-environment] - phpdoc[php-doc] - end - layering -->|"单服务内分层"| Logic - crossSdk -->|"服务间 HTTP"| slot_sdk - slot_sdk --> innerapi[被调服务 innerapi/api] -``` - -- **不修改** [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc)：避免一条规则过长；仅在 `cross-service-sdk` 末尾用交叉引用衔接。 -- **不修改** [`dev-environment.mdc`](file:///Users/ray/.cursor/rules/dev-environment.mdc) / [`php-doc.mdc`](file:///Users/ray/.cursor/rules/php-doc.mdc)。 - ---- - -## 实施步骤（确认计划后执行） - -1. 创建 [`cross-service-sdk.mdc`](/Users/ray/.cursor/rules/cross-service-sdk.mdc)，填入上述 frontmatter 与正文。 -2. 通读四条 `alwaysApply` 规则，确认无矛盾表述（尤其 Service 层与 Gateway 分工）。 -3. （可选）在 [`slot_sdk/readme.md`](file:///Users/ray/Documents/project/www/slot/slot_sdk/readme.md) 补 5–10 行架构说明并链到 Cursor 规则 — **仅当你希望仓库内也有文档镜像**；非本次必需。 - ---- - -## 验收标准 - -- 新开 Cursor 会话、编辑任意 slot PHP 文件时，Agent 应自动带上「跨服务须经 slot_sdk、新 API 先改 slot_sdk」约束。 -- 术语统一使用：**跨服务 HTTP**、**调用方 / 被调方**、**slot_sdk**，避免「中转」「服务间随便 HTTP」等模糊说法。 -- 规则正文不含 legacy 迁移条款（按你的选择）。 diff --git a/plans/首充定格资金修复_ac2c16c6.plan.md b/plans/首充定格资金修复_ac2c16c6.plan.md deleted file mode 100644 index aa0dc4f..0000000 --- a/plans/首充定格资金修复_ac2c16c6.plan.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -name: 首充定格资金修复 -overview: 本次仅改 slot_wallet 与 slot_console。wallet 删除 Recharge bus、首充发 free_credit_init；console 消费该事件完成定格。pay 等其它服务不在本次范围。 -todos: - - id: wallet-remove-recharge-bus - content: 删除 WalletLogic recharge/rechargeSign 中 sendConsoleBus('Recharge') - status: completed - - id: wallet-send-free-credit-init - content: recharge + rechargeSign 首充时发送 free_credit_init（inc/改账前采 balance_before_qf） - status: completed - - id: wallet-remove-create-wager-first-recharge - content: CreateWagerTask 删除 version1/version2 首充特殊打码分支，首充走普通充值打码 - status: completed - - id: console-event-bus-handler - content: EventBus case free_credit_init + FreeCreditInitEvent - status: completed - - id: console-free-credit-init-logic - content: handleFreeCreditInit；RechargeEvent 移除首充定格，保留档位推进 - status: completed - - id: console-safe-freeze-order - content: freezeFirstRecharge 先 RPC 后落库；上限与幂等 - status: completed - - id: mq-reliability - content: free_credit_init 失败 nack/requeue（仅 console EventBus） - status: completed - - id: tests-and-repair - content: wallet/console 单测与集成测；FreeCreditsFreezeDev 补偿（console） - status: completed -isProject: false ---- - -# 首充定格资金操作修复方案（修订 v4） - -## 变更范围（硬约束） - -**本次仅编辑以下仓库/服务，不修改任何其它服务（含 slot_pay、slot_lib 等）：** - -| 在范围内 | 不在范围内 | -|----------|------------| -| `slot_wallet` | `slot_pay` | -| `slot_console` | `slot_lib`、`slot_agent`、… | - -> `Recharge` 总线消息假定由 **pay 或其它既有链路** 发送；本次不从 wallet 重复发送，也**不改 pay** 去补发。若线上 pay 未发 `Recharge`，统计/档位问题需另开 pay 任务，**不纳入本 PR**。 - ---- - -## 设计原则 - -> **情愿用户定格失败，也不能让系统亏钱。** - -| 服务（本次） | 职责 | -|--------------|------| -| **slot_wallet** | 入账；首充发 **`free_credit_init`**；**删除** `Recharge` bus；**移除** `CreateWagerTask` 旧首充打码拆分 | -| **slot_console** | 消费 `free_credit_init` → 定格扣款 + 活动落库；`RechargeEvent` **不再**做首充定格 | - ---- - -## 目标架构 - -```mermaid -sequenceDiagram - participant Ext as 外部_pay等_本次不改 - participant Wallet as slot_wallet - participant MQ as console_bus - participant Console as slot_console - - Ext->>Wallet: recharge / rechargeSign - Wallet->>Wallet: 采 balance_before_qf，入账 - Wallet->>MQ: free_credit_init - Ext->>MQ: Recharge（本次不实现） - MQ->>Console: FreeCreditInitEvent - Console->>Wallet: freeCreditsFreeze RPC - Console->>Console: player/package 落库 - MQ->>Console: RechargeEvent（既有逻辑，无定格） -``` - ---- - -## 实现步骤 - -### 1. slot_wallet - -#### 1.1 删除 `Recharge` bus - -从 [`WalletLogic::recharge()`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php)、[`rechargeSign()`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) 移除： - -```php -$this->sendConsoleBus('Recharge', $this->requestDTO->recharge); -``` - -保留 `sendConsoleBus('reward', ...)` 及其它非 Recharge 类型（本次不动）。 - -#### 1.2 `maybeSendFreeCreditInit()` + 扩展 `sendConsoleBus` - -- 改账/ `inc()` **前**：`balance_before_qf`、`is_first_recharge`（`total_deposit == 0`，在 `statModel->inc` 之前判断）。 -- 改账成功后：`is_first_recharge && balance_before_qf > 0` 时发送： - -```php -$this->sendConsoleBus('free_credit_init', 0, [ - 'balance_before_qf' => $balanceBeforeQf, - 'recharge_amount' => $this->requestDTO->recharge, -]); -``` - -- [`sendConsoleBus()`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) 增加可选参数 `array $extraData = []`。 - -#### 1.3 `recharge()` 与 `rechargeSign()` 均接入 - -签到购买 [`rechargeSign()`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) 与普通 [`recharge()`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) 使用同一套 `maybeSendFreeCreditInit()` 逻辑。 - -#### 1.4 移除 `CreateWagerTask` 旧首充打码逻辑（已废弃） - -[`app/command/CreateWagerTask.php`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/command/CreateWagerTask.php) 在 **Free Credits 上线前** 于首充时本地拆分余额打码，与现「console 定格 + 分档释放」重复且易冲突，**本次删除**。 - -**旧逻辑位置**（条件均为 `RechargeExchangeService::total` 累计充值等于本笔 `recharge_amount`，即首充）： - -| 方法 | 行号（约） | 行为 | -|------|-----------|------| -| `version1()` | L87–140 | `SOURCE_TYPE_FIRST_RECHARGE` 任务 + `SOURCE_TYPE_FREE` 免打码任务 + `SOURCE_TYPE_FIRST_LEFT`「首充剩余」打码 | -| `version2()` | L186–244 | 首充充值/赠送打码 + `SOURCE_TYPE_FIRST_LEFT`（`first_recharge_left` 系数） | - -**与新方案关系**： - -- 充值前免费余额 → 由 console `free_credit_init` → `freeCreditsFreeze` 扣出活动池（不再在 wallet 侧拆 `FREE` / `FIRST_LEFT` 任务）。 -- 免打码第一档 / 后续释放 → 由 console `FreeCreditsLogic` + `freeCreditsClaim` 创建 Y1（`WalletLogic::freeCreditsClaim` 内 `createTask`）。 -- 首充**本笔充值金额**的打码 → 与其它充值相同，走 `elseif ($dto->required_wager > 0)` 通用分支即可。 - -**改动要点**： - -1. 删除 `version1` / `version2` 中整段 `if ($entity->recharge > 0 && $entity->recharge == $dto->recharge_amount) { ... }`。 -2. 首充与普通充值统一落入后续 `elseif ($dto->required_wager > 0)`（`version1` L142+、`version2` L246+）。 -3. **保留**其中对 `SOURCE_TYPE_BUY_SIGN`（购买签到解锁额度为 0）的处理——该逻辑在 `elseif` 分支内已有，无需首充专用块。 -4. 删除后确认无引用孤立的 `SOURCE_TYPE_FIRST_RECHARGE` / `SOURCE_TYPE_FIRST_LEFT` 首充专用路径（常量可保留供历史任务读）。 - ---- - -### 2. slot_console - -#### 2.1 EventBus 注册 `free_credit_init` - -[`EventBus::deal()`](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/EventBus.php) 增加显式分支（类名不能走 default 动态加载）： - -```php -case 'free_credit_init': - (new FreeCreditInitEvent())->handle($busEntity); - break; -``` - -新建 [`app/command/event/FreeCreditInitEvent.php`](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/event/FreeCreditInitEvent.php)。 - -#### 2.2 `FreeCreditsLogic::handleFreeCreditInit` - -- 入参：`uid`、`balance_before_qf`、`wallet_amount`、`orderId`（来自 bus `data`）。 -- `frozenAmount = max(balance_before_qf, 0)`；**不以**充值后再读余额反推为主路径。 -- 活动未开启 / 已定格 → 幂等 return。 -- 调用调整后的 `freezeFirstRecharge()`。 - -#### 2.3 调整 `freezeFirstRecharge`（先扣款、后落库） - -[`freezeFirstRecharge()`](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/logic/FreeCreditsLogic.php)： - -1. 幂等：已有 `free_credits_freeze:{orderId}` 流水则跳过 RPC。 -2. `frozenAmount = min(事件金额, RPC 前当前可扣余额)`；≤0 不扣。 -3. **先** `freeCreditsFreeze` RPC，**后** `Db::transaction` 写 player/packages。 -4. RPC 失败 → 不落库，**抛异常**。 - -#### 2.4 `RechargeEvent` 去掉首充定格 - -[`RechargeEvent::handle()`](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/event/RechargeEvent.php) **删除** L73-82 对 `handleRecharge` 的调用（首充定格改由 `free_credit_init` 触发）。 - -保留并可继续调用 **仅档位推进** 的逻辑，例如： - -- 新增 `FreeCreditsLogic::advanceAfterRecharge($uid, $walletAmount)`，或 -- `handleRecharge` 内去掉首充 `freezeFirstRecharge` 分支，仅保留 `advanceByRecharge`（供既有 `Recharge` 消息使用）。 - -统计、黑名单、代理首充等 **RechargeEvent 现有代码不动**（本次范围外行为保持）。 - -#### 2.5 MQ 可靠性（仅 console） - -- `FreeCreditInitEvent` / `free_credit_init`：异常上抛；`EventBus` 对该 type 失败时 **nack/requeue**（需对齐现有 consumer）。 -- `Recharge` 路径统计块仍可独立 try/catch（本次不改 pay 发消息前提）。 - ---- - -### 3. 测试（仅 wallet + console） - -| 用例 | 位置 | -|------|------| -| wallet 删除 Recharge bus | slot_wallet | -| wallet 首充发 `free_credit_init`（含 rechargeSign） | slot_wallet | -| 首充不再走 CreateWagerTask 特殊分支 | slot_wallet CreateWagerTask | -| `FreeCreditInitEvent` 定格成功 | slot_console 集成测 | -| RPC 失败不落库 / 先扣后落库 / 幂等 | slot_console | -| `RechargeEvent` 不再触发定格 | 调整 [`FreeCreditsHandleRechargeTest`](file:///Users/ray/Documents/project/www/slot/slot_console/tests/Unit/FreeCreditsHandleRechargeTest.php) 等 | - -**不新增** pay 侧联调用例。 - ---- - -## 关键改动文件（仅此两份） - -**slot_wallet** - -- [`app/api/logic/WalletLogic.php`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) -- [`app/command/CreateWagerTask.php`](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/command/CreateWagerTask.php) - -**slot_console** - -- [`app/command/EventBus.php`](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/EventBus.php) -- `app/command/event/FreeCreditInitEvent.php`（新建） -- [`app/api/logic/FreeCreditsLogic.php`](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/logic/FreeCreditsLogic.php) -- [`app/command/event/RechargeEvent.php`](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/event/RechargeEvent.php) -- 相关 tests（console 仓内） - ---- - -## 验收标准（本 PR） - -- **wallet**：`recharge` / `rechargeSign` 不再发送 `type=Recharge`；首充且 inc 前有免费余额时发送 `free_credit_init`，`balance_before_qf` 正确。 -- **wallet**：首充不再触发 `CreateWagerTask` 的 `FIRST_RECHARGE` / `FREE` / `FIRST_LEFT` 拆分，仅按本笔充值/赠送金额走通用打码任务。 -- **console**：收到 `free_credit_init` 后完成定格扣款与落库；扣款 ≤ 事件金额且 ≤ 可扣余额；幂等。 -- **console**：`RechargeEvent` 不再执行首充定格；已定格用户经 `Recharge` 仍可 `advanceByRecharge`（依赖外部 pay 发消息，**本 PR 不验证 pay**）。 -- **范围**：`git diff` 仅涉及 `slot_wallet`、`slot_console` 路径。