ray604638018/cursor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f71a5c59af9c88bc7904ebeae4e63dceed729ad4
cursor/plans/第一档提现独立接口_6b3aaf7e.plan.md
ray zhou f71a5c59af ok
2026-05-29 11:21:40 +08:00

7.8 KiB
Raw Blame History

name, overview, todos, isProject
name overview todos isProject
第一档提现独立接口 将 Free Credits 第一档免打码提现从 `POST /api/withdraw/apply` 拆出，新增 `POST /api/free-credits/withdraw-first-cash`（与 `keep-first-cash` 并列）；普通提现接口保持原样，不再识别 `package_id`。
id content status
validator-migrate FreeCreditsValidator 增加 withdraw-first-cash 各支付 scene；WithdrawValidator 移除 *_fc completed
id content status
controller-endpoint FreeCreditsController::withdrawFirstCash + 注释更新 completed
id content status
withdraw-service-split WithdrawService 抽出 public applyFreeCreditsFirstCash；apply() 去掉 package_id 分支 completed
id content status
withdraw-controller-clean WithdrawController::apply 仅保留普通提现校验与文案 completed
id content status
tests-update 迁移/更新 Validator 与 FreeCreditsFirstCashoutApplyTest 单测 completed
false

第一档提现独立接口

现状

第一档独立提现与普通钱包提现共用同一入口：

flowchart LR
  client[C端]
  withdrawApply["POST /api/withdraw/apply"]
  withdrawSvc[WithdrawService::apply]
  fcLogic[FreeCreditsLogic::applyFirstCashoutWithdraw]
  pay[PayService::apply]
  client --> withdrawApply
  withdrawApply -->|"package_id > 0"| withdrawSvc
  withdrawApply -->|"无 package_id"| withdrawSvc
  withdrawSvc --> fcLogic --> pay

关键代码：

目标形态：

flowchart LR
  normal["POST /api/withdraw/apply\namount + 绑卡"]
  fcWithdraw["POST /api/free-credits/withdraw-first-cash\npackage_id + 绑卡"]
  keep["POST /api/free-credits/keep-first-cash\npackage_id"]
  normal --> walletWithdraw[余额/手续费/黑规则]
  fcWithdraw --> fcLogic[FreeCreditsLogic]
  keep --> walletKeep[freeCreditsFirstCashKeep]

新接口契约

项 约定
路径 POST /api/free-credits/withdraw-first-cash（Webman 默认路由 → FreeCreditsController::withdrawFirstCash）
入参 package_id（必填）、type（1/2/3/6）、各支付方式绑卡字段（与现 WithdrawValidator 的 *_fc scene 一致）、可选 pay_net
成功 data { order_id, amount }（与现第一档走 withdraw/apply 的返回一致，不改 buildStatus）
成功 msg 沿用现第一档文案：Submitted successfully! Your order is under review...
业务逻辑 复用 FreeCreditsLogic::applyFirstCashoutWithdraw；Pay 回调、handleFirstCashoutResult、档位状态机不变

与 keep-first-cash 对称：同属 Free Credits 活动域，第一档二选一：

  • Withdraw → POST /api/free-credits/withdraw-first-cash
  • Keep → POST /api/free-credits/keep-first-cash

实现步骤（仅 slot_console）

1. 新 Controller 方法

文件：FreeCreditsController.php

  • 新增 withdrawFirstCash(Request $request)
  • 校验 → 构建 WithdrawApplyDTO（复用现有 DTO，含 package_id + 绑卡字段）→ 调用提现编排（见下）
  • 更新类注释：第一档提现改指向新路径

2. 校验迁移到 FreeCreditsValidator

文件：FreeCreditsValidator.php

从 WithdrawValidator 迁入：

  • SCENE_WITHDRAW_FIRST_CASH_CASH / _BTC / _USDT / _PAYPAL（命名可与原 *_fc 对齐或重命名）
  • type、user_name、cash_tag、btc、usdt、paypal_*、email 等 rule（原 *_fc scene 字段集）
  • 静态方法 firstCashoutScene(int $type): string（原 firstCashoutScene）

WithdrawValidator：删除 SCENE_APPLY_*_FC、firstCashoutScene 及对应 scene 配置。

3. 提现编排仍放 WithdrawService（绑卡 + 锁）

文件：WithdrawService.php

  • 将现有 applyFreeCreditsFirstCashout 提升为 public function applyFreeCreditsFirstCash(WithdrawApplyDTO $applyDTO): array，内容包含：
    • is_bind_name 校验
    • Redis 防重复提交锁（与 apply 相同 key）
    • checkBankInfo + FreeCreditsLogic::applyFirstCashoutWithdraw
  • apply()：删除 if ($applyDTO->package_id > 0) 分支，仅保留普通提现路径

说明：绑卡逻辑仍在 WithdrawService 私有方法中，Logic 层不重复实现，避免违反分层「不中转 Service」时仍复用已有绑卡能力。

4. 精简 WithdrawController

文件：WithdrawController.php

  • apply() 仅按 type 选普通 scene（(string) $type）
  • 移除 package_id 分支与差异化 msg

不对旧接口传 package_id 做拒绝或转发（按你的确认：无需处理）。

5. DTO / 字段

WithdrawApplyDTO：package_id 字段可保留供新接口使用；注释改为「仅 free-credits/withdraw-first-cash 使用」。普通 withdraw/apply 不再读取该字段。

6. 单测与文档注释

文件 改动
WithdrawValidatorFreeCreditsTest.php 迁至 FreeCreditsValidatorWithdrawFirstCashTest（或合并进 FreeCreditsValidatorTest），断言新 scene
FreeCreditsFirstCashoutApplyTest.php 改为调用 WithdrawService::applyFreeCreditsFirstCash（或经新 Controller harness）；断言仍是不走余额校验、Pay 失败回滚 ready
FreeCreditsController.php / FreeCreditsValidator.php 注释同步新路径

运行：

docker exec -w /app/www/slot/slot_console php82 ./vendor/bin/phpunit \
  tests/Unit/FreeCreditsValidatorTest.php \
  tests/Unit/WithdrawValidatorFreeCreditsTest.php \
  tests/Integration/FreeCreditsFirstCashoutApplyTest.php

（迁移后调整具体测试文件名。）

不在本次范围

  • slot_pwa / gateway 前端改 URL（联调时 C 端将 Withdraw 按钮从 /api/withdraw/apply 改为 /api/free-credits/withdraw-first-cash）
  • slot_pay / wallet / EventBus 回调逻辑
  • keep-first-cash、claim、status 行为

C 端联调要点

第一档 packages[0].status === 1 时：

  • Withdraw → POST /api/free-credits/withdraw-first-cash + package_id + 支付方式字段
  • Keep → 现有 POST /api/free-credits/keep-first-cash

普通提现页仍用 POST /api/withdraw/apply（amount 必填，不传 package_id）。

验收

  1. 新接口：第一档 ready + 合法绑卡 → 返回 order_id/amount，package → processing，Pay 失败回滚 ready
  2. 新接口：非 ready / 无资格 / processing 中 → 业务异常与现逻辑一致
  3. POST /api/withdraw/apply：仅普通提现；带 amount 走余额/手续费校验；不再因 package_id 进入 Free Credits 分支
  4. keep-first-cash / claim / 提现结果回调回归不受影响
  5. 相关单测通过