ok

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

@@ -0,0 +1,94 @@
+---
+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. 新接口行为无回归