cursor/plans/旧提现接口兼容_package_id_9ba88779.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
旧提现接口兼容 package_id	在已落地的 `POST /api/free-credits/withdraw-first-cash` 基础上，恢复 `POST /api/withdraw/apply` 对 `package_id` 的兼容：参数校验与业务编排与新接口一致，内部转发 `applyFreeCreditsFirstCash`，不重复维护 WithdrawValidator 的 `*_fc` scene。	id content status withdraw-controller-compat WithdrawController::apply 恢复 package_id 分支，校验用 FreeCreditsValidator，调用 applyFreeCreditsFirstCash completed id content status comments-sync FreeCreditsController / WithdrawApplyDTO 注释标明兼容与推荐路径 completed id content status regression-test 跑相关 PHPUnit 确认无回归 completed	false

旧提现接口兼容 package_id

背景

第一档提现独立接口 已实现新路径，但 WithdrawController::apply 当前一律走普通提现（amount 必填），旧 C 端若仍调用 POST /api/withdraw/apply + package_id 会校验失败或走错逻辑。

需求：保留原接口，传 package_id 时行为与 withdraw-first-cash 一致（兼容期转发，不删新接口）。

flowchart TD
  apply["POST /api/withdraw/apply"]
  apply -->|"package_id > 0"| fcPath["FreeCreditsValidator + applyFreeCreditsFirstCash"]
  apply -->|"无 package_id"| normalPath["WithdrawValidator + apply"]
  newApi["POST /api/free-credits/withdraw-first-cash"]
  newApi --> fcPath

改动（仅 slot_console）

1. WithdrawController::apply

• use app\api\validator\FreeCreditsValidator
• 分支逻辑（与拆分前一致，编排指向新方法）：

$post = $request->post();
$type = intval($post['type'] ?? input('type', 1));

if (!empty($post['package_id'])) {
    $error = (new FreeCreditsValidator())->scene(FreeCreditsValidator::firstCashoutScene($type))->check($post);
    // 失败 return PARAMS_ERROR
    $this->service->setUid($uid);
    $res = $this->service->applyFreeCreditsFirstCash(new WithdrawApplyDTO($post));
    return $this->success($res, 'Submitted successfully! Your order is under review...');
}

$error = $this->validate((string) $type, $post);
// 现有普通提现 apply + 'Submit successfully'

• 方法 PHPDoc 注明：package_id 为兼容字段，推荐改用 /api/free-credits/withdraw-first-cash。

不在 WithdrawValidator 恢复 *_fc scene，避免两套校验重复；兼容路径复用 FreeCreditsValidator。

2. 注释同步

文件	内容
FreeCreditsController 类注释	补充：旧路径 withdraw/apply + package_id 仍可用，建议迁移新接口
WithdrawApplyDTO	package_id 注释改为「新接口首选；withdraw/apply 兼容」

3. 单测（可选、建议加）

在 tests/Unit/ 或扩展现有 Controller 测：

• 仅验证 WithdrawController 在 package_id 非空时选用 FreeCreditsValidator::firstCashoutScene（可 mock validate，或沿用 validator 单测 + 文档约定）。

集成行为已由 FreeCreditsFirstCashoutApplyTest 覆盖 applyFreeCreditsFirstCash，兼容层无额外 Service 逻辑，可不新增 DB 集成测。

运行回归：

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

不变项

• WithdrawService::applyFreeCreditsFirstCash 实现不动
• POST /api/free-credits/withdraw-first-cash 仍为推荐入口
• 普通 withdraw/apply（无 package_id）行为不变

验收

1. withdraw/apply + package_id + 绑卡 → 与 withdraw-first-cash 相同返回与档位状态
2. withdraw/apply 无 package_id → 仍须 amount，走余额/手续费校验
3. 新接口行为无回归