---
description: Laravel 后端分层、目录结构与编码规范
globs: backend/**/*.php
alwaysApply: false
---
# Laravel 后端规范

详见 `docs/06-backend-laravel.md`。

## 分层
Controller → FormRequest → Application Action/Service → Domain → Model → DB

- Controller 只做：接收请求、调用 FormRequest 验证、调用 Action/Service、返回 API Resource。
- 复杂业务放 `app/Application/{Module}/Actions`，一个 Action 一个用例（如 `AllocateOutboundAction`）。
- 业务规则、状态机、Enum、值对象放 `app/Domain/{Module}`，不依赖 Http 与第三方平台。
- 第三方平台 / 物流商实现放 `app/Infrastructure/`；租户上下文、统一响应等放 `app/Support/`。
- 事务边界在 Application 层；跨模块协作走 Application Service 或 Events。

```php
// ❌ Controller 中直接写业务与查询
public function ship(string $outboundNo) {
    $o = Outbound::where('outbound_no', $outboundNo)->first();
    if ($o->status == 'packed') { $o->status = 'shipped'; $o->save(); }
}

// ✅
public function ship(ShipOutboundRequest $request, string $outboundNo, ShipOrderAction $action) {
    return ApiResponse::success(new OutboundResource($action->execute($outboundNo, $request->toDto())));
}
```

## 编码
- `declare(strict_types=1);`，参数与返回值写明类型；DTO 在层间传递，不传裸数组。
- 状态、类型一律用 PHP Enum，非法状态转换抛业务异常。
- 授权用 Policies / Gates；认证用 Sanctum。
- 避免超大 Controller / Service；不重复 SQL，查询复用 Scope。