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

# 旧提现接口兼容 package_id

## 背景

[第一档提现独立接口](第一档提现独立接口_6b3aaf7e.plan.md) 已实现新路径，但 [`WithdrawController::apply`](slot_console/app/api/controller/WithdrawController.php) 当前**一律**走普通提现（`amount` 必填），旧 C 端若仍调用 `POST /api/withdraw/apply` + `package_id` 会校验失败或走错逻辑。

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

```mermaid
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`](slot_console/app/api/controller/WithdrawController.php)

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

```php
$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`](slot_console/app/api/validator/WithdrawValidator.php) 恢复 `*_fc` scene，避免两套校验重复；兼容路径复用 [`FreeCreditsValidator`](slot_console/app/api/validator/FreeCreditsValidator.php)。

### 2. 注释同步

| 文件 | 内容 |
| --- | --- |
| [`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php) 类注释 | 补充：旧路径 `withdraw/apply` + `package_id` 仍可用，建议迁移新接口 |
| [`WithdrawApplyDTO`](slot_console/app/api/dto/request/WithdrawApplyDTO.php) | `package_id` 注释改为「新接口首选；withdraw/apply 兼容」 |

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

在 [`tests/Unit/`](slot_console/tests/Unit/) 或扩展现有 Controller 测：

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

集成行为已由 [`FreeCreditsFirstCashoutApplyTest`](slot_console/tests/Integration/FreeCreditsFirstCashoutApplyTest.php) 覆盖 `applyFreeCreditsFirstCash`，兼容层无额外 Service 逻辑，**可不新增 DB 集成测**。

运行回归：

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

## 不变项

- [`WithdrawService::applyFreeCreditsFirstCash`](slot_console/app/service/WithdrawService.php) 实现不动
- `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. 新接口行为无回归