Laravel 项目开发架构规范

适用范围：新 Laravel 项目、后台系统、多端统一后端、开放接口、运营管理系统、需要权限、审计、队列、定时任务、上线规范的中大型项目。

本文档定义默认工程规范。历史项目可在迁移期兼容，但新代码、Code Review、架构评审、接口设计、测试与上线检查，应以本文档为准。

Table of contents

1. 文档定位与基本原则

1.1 文档目标

本规范用于统一 Laravel 项目的分层、目录、输入输出、认证权限、状态流转、事务并发、缓存、日志审计、队列任务、上线运行和工程门禁。

目标不是解释 Laravel 原理，而是定义团队默认怎么写、什么不能写、评审看什么、上线检查什么。

1.2 默认原则

• 先按端口 / 调用方 / 系统边界拆路由，再按业务模块组织代码。
• Controller 保持薄，只负责接收请求、调用用例、返回响应。
• Application Service 承接用例编排、事务边界和业务流程。
• Domain Service 承接跨用例复用的领域规则、状态机、金额计算、资格判断和算法。
• Model 是 Eloquent 实体表达层，不是业务流程层。
• FormRequest 负责请求校验与轻量预处理，Resource 负责输出映射。
• 统一响应、统一错误码、统一异常出口。
• 资金、库存、权限、状态流转、支付回调、Open API 写接口必须考虑事务、并发和幂等。
• 日志、请求追踪、业务审计、SQL 审计职责分离。
• 生产运行方案必须覆盖发布、回滚、队列、定时任务、备份、监控和健康检查。

1.3 代码示例保留策略

本规范不是纯原则文档。正文保留能解释主链路的最小关键代码；完整可复制的 Middleware、Migration、Service、配置模板和部署脚本统一放入附录。

阅读方式：

• 快速理解：阅读正文。
• 直接落地：按正文规则复制附录模板。
• Code Review：以正文规则为准，以附录模板作为默认实现参考。

2. 架构总览与术语统一

2.1 标准请求链路

Route
  -> Middleware
  -> FormRequest
  -> Controller
  -> Application Service
  -> Domain Service / Model / Repository / Query Object
  -> Event / Listener / Job
  -> Resource / Transformer
  -> ApiResponder
  -> JsonResponse

2.2 术语

历史项目中若存在 Service / CoreService，新规范统一映射为：

旧 Service     -> Application Service
旧 CoreService -> Domain Service

3. 标准目录结构

app/
├── Data/
│   └── {Domain}/
├── Domain/
│   └── {Domain}/
├── Enums/
│   └── {Domain}/
├── Exceptions/
├── Http/
│   ├── Controllers/
│   │   └── {Port}/{Module}/
│   ├── Middleware/
│   ├── Requests/
│   │   └── {Port}/{Module}/
│   └── Resources/
│       └── {Port}/{Module}/
├── Jobs/
│   └── {Domain}/
├── Models/
│   └── {Domain}/
├── Policies/
├── Repositories/
│   └── {Domain}/
├── Rules/
├── Services/
│   └── {Port}/{Module}/
├── Support/
│   ├── Cache/
│   ├── ErrorCodes/
│   └── Http/
└── Validation/
    └── Schemas/

routes/
├── admin.php
├── store.php
├── client.php
├── open.php
├── webhook.php
└── shared.php

目录不为“显得架构完整”而强制创建。项目规模较小时允许简化，但职责边界必须保持清晰。

4. 请求处理主链路规范

4.1 本章定位

本章定义一次 API 请求从入口到响应的标准处理链路，重点约束每一层“做什么、不做什么、向下一层交付什么”。

标准链路：

Route
  -> Middleware
  -> FormRequest
  -> Controller
  -> Application Service
  -> Domain Service / Model / Repository / Query Object
  -> Event / Listener / Job
  -> Resource
  -> ApiResponder
  -> JsonResponse

默认规则：

• Controller 只做 HTTP 编排，不写业务流程。
• Application Service 是业务用例入口，默认承接事务边界。
• Domain Service 只承接跨用例领域规则，不感知 HTTP。
• Resource 只做输出映射，不触发查询和业务副作用。
• ApiResponder 只负责顶层响应协议，不承载业务判断。

4.2 层间交付物

4.3 Route 规范

Route 负责定义接口入口、端口边界、认证策略、签名策略、权限策略和上下文选择规则。

推荐路由文件：

routes/admin.php
routes/store.php
routes/client.php
routes/open.php
routes/webhook.php
routes/shared.php

路由分组示例：

use App\Http\Controllers\Admin\Order\OrderController;
use Illuminate\Support\Facades\Route;

Route::prefix('admin')
    ->as('admin.')
    ->middleware(['api', 'auth:admin', 'request.context', 'request.log'])
    ->group(function (): void {
        Route::prefix('orders')
            ->as('orders.')
            ->controller(OrderController::class)
            ->group(function (): void {
                Route::get('/', 'index')->name('index');
                Route::get('{order}', 'show')->name('show');
                Route::post('{order}/cancel', 'cancel')->name('cancel');
            });
    });

规则：

• 不把后台、客户端、开放接口、Webhook 全部混写在 routes/api.php。
• 有权限校验、审计、菜单绑定需求的路由必须具备稳定 route name。
• 路由只声明入口与中间件，不写业务闭包。
• Webhook / Open API 必须独立路由文件或独立路由组，避免和内部端口共享安全策略。
• 路由参数模型绑定可以使用，但对象级权限仍必须在 Policy、FormRequest 或 Application Service 中校验。

禁止：

Route::post('/orders/{order}/cancel', function (Order $order) {
    $order->update(['status' => 3]);

    return response()->json(['ok' => true]);
});

4.4 Middleware 规范

Middleware 承接横切能力：认证、验签、权限、上下文选择、请求日志、限流、anti-abuse、request_id 注入。

允许：

• 校验 token、签名、权限、IP、限流规则。
• 注入 request_id、trace_id、租户、门店、语言、币种等上下文。
• 对非法请求提前返回统一错误响应。

不允许：

• 编排订单取消、退款审核、支付成功等业务动作。
• 修改核心业务状态。
• 写复杂查询与复杂业务分支。
• 把当前用户权限范围偷偷塞到全局 Scope。

建议拆分：

AssignRequestContextMiddleware  -> 分配 request_id / trace_id
RequestLogMiddleware            -> 请求摘要日志
RoutePermissionMiddleware       -> 路由权限校验
ResolveTenantContextMiddleware  -> 租户 / 门店上下文
VerifyOpenApiSignatureMiddleware -> Open API 验签

中间件顺序建议：

request.context
  -> request.log
  -> auth
  -> signature / permission / tenant-context
  -> controller

4.5 FormRequest 规范

FormRequest 是当前接口的输入校验与授权入口。

推荐目录：

app/Http/Requests/{Port}/{Module}/{Action}Request.php

职责：

• authorize()：当前用户是否允许发起这个请求。
• prepareForValidation()：trim、默认值、类型归一、空字符串归一。
• rules()：字段级合法性校验。
• messages() / attributes()：按需提供错误信息。

示例：

final class CancelOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user('admin') !== null;
    }

    protected function prepareForValidation(): void
    {
        $this->merge([
            'reason' => is_string($this->reason) ? trim($this->reason) : $this->reason,
        ]);
    }

    public function rules(): array
    {
        return [
            'reason' => ['nullable', 'string', 'max:500'],
        ];
    }
}

边界：

• 字段格式、长度、必填、枚举值属于 FormRequest。
• “订单当前状态是否可取消”属于 Application Service / Domain Service。
• “当前管理员是否有这个门店的数据权限”可在 Policy / FormRequest / Application Service 中做，但必须保持项目内一致。

4.6 Controller 规范

Controller 是 HTTP 编排层，只负责把请求接入主链路。

推荐写法：

final class OrderController extends BaseApiController
{
    public function index(
        ListOrderRequest $request,
        ListOrderService $service,
    ): JsonResponse {
        $query = OrderListQueryData::fromArray($request->validated());
        $paginator = $service->handle($query, $request->user('admin'));

        return $this->paginated(
            data: OrderResource::collection($paginator->getCollection()),
            paginator: $paginator,
        );
    }

    public function cancel(
        CancelOrderRequest $request,
        Order $order,
        CancelOrderService $service,
    ): JsonResponse {
        $order = $service->handle(
            order: $order,
            reason: $request->validated('reason'),
            actor: $request->user('admin'),
        );

        return $this->success(
            data: new OrderResource($order),
            message: 'Order cancelled successfully.',
        );
    }
}

Controller 可以做：

• 从 FormRequest 获取 validated()。
• 构造 Input Data / Query Data。
• 调用 Application Service。
• 包装 Resource。
• 调用 success()、created()、paginated()。

Controller 禁止：

• DB::transaction()。
• 复杂 where / join / orderBy 查询。
• 状态流转判断。
• 直接调用外部接口。
• 直接写业务审计。
• 长期手写复杂 JSON 响应。

4.7 Application Service 规范

Application Service 是一个业务用例的主入口。

推荐目录：

app/Services/{Port}/{Module}/{Action}Service.php

命名示例：

CreateOrderService
CancelOrderService
ApproveRefundService
ListOrderService
ExportOrderService

职责：

• 编排一个业务动作。
• 控制事务边界。
• 调用 Domain Service / Repository / Query Object。
• 触发 Event、Job、业务操作审计。
• 返回业务结果，不返回 HTTP 响应。

示例：

final class CancelOrderService
{
    public function __construct(
        private readonly OrderStatusTransitionService $transitionService,
        private readonly OperationAuditService $auditService,
    ) {
    }

    public function handle(Order $order, ?string $reason, AdminUser $actor): Order
    {
        return DB::transaction(function () use ($order, $reason, $actor) {
            $order = Order::query()
                ->whereKey($order->id)
                ->lockForUpdate()
                ->firstOrFail();

            $this->transitionService->ensureCanCancel($order);

            $order->update([
                'status' => OrderStatus::Canceled,
                'cancel_reason' => $reason,
                'canceled_at' => now(),
            ]);

            $this->auditService->success(
                subject: $order,
                reason: $reason,
                eventKey: 'order.cancelled',
                eventLabel: '取消订单',
            );

            OrderCancelled::dispatch($order->id)->afterCommit();

            return $order->refresh();
        }, attempts: 3);
    }
}

规则：

• 一个复杂业务动作优先一个 Service 类。
• 事务默认放在 Application Service。
• Service 返回 Model、DTO、Collection、Paginator、标量或空值。
• Service 不返回 JsonResponse。
• Service 不拼顶层响应协议。
• 跨用例复用规则下沉到 Domain Service。

4.8 Domain Service 规范

Domain Service 承接跨用例复用的领域规则。

适合放入：

• 状态机与状态流转规则。
• 金额、折扣、结算、库存算法。
• 资格判断。
• 时间区间规则。
• 第三方领域能力适配。

示例：

final class OrderStatusTransitionService
{
    public function ensureCanCancel(Order $order): void
    {
        if (! in_array($order->status, [OrderStatus::PendingPay, OrderStatus::Paid], true)) {
            throw ApiHttpException::fromError(
                OrderError::STATUS_NOT_CANCELABLE,
                errors: [
                    'order_id' => $order->id,
                    'current_status' => $order->status->value,
                ],
            );
        }
    }
}

规则：

• 不依赖 Request、Response、Session。
• 不直接读取当前登录用户；必要上下文由调用方显式传入。
• 不控制事务提交与回滚。
• 不拼 API 响应结构。
• 不写 UI 逻辑。

4.9 Repository / Query Object 规范

Repository 是可选层，Query Object 是复杂查询的推荐落点。

引入 Repository 的条件：

• 一个领域对象背后有多数据源。
• 需要读写隔离。
• 需要隐藏持久化细节。
• 查询策略稳定复用且跨多个用例。

引入 Query Object 的条件：

• 列表筛选复杂。
• 列表与导出复用同一套条件。
• 需要封装排序、include、数据范围、统计字段。

普通 CRUD 不强制 Repository。

推荐：

final class OrderListQuery
{
    public function build(OrderListQueryData $query, AdminUser $actor): Builder
    {
        return Order::query()
            ->whereIn('orders.store_id', $actor->accessibleStoreIds())
            ->when($query->status !== null, fn (Builder $builder) => $builder->where('orders.status', $query->status))
            ->when($query->keyword, fn (Builder $builder) => $this->applyKeyword($builder, $query->keyword));
    }
}

4.10 Event / Listener / Job 规范

Event / Listener 用于解耦主流程后的副作用，Job 用于异步、重试、耗时任务。

适合放到 Event / Listener / Job：

• 邮件、短信、站内信、推送。
• ERP / CRM / 第三方系统同步。
• 缓存刷新。
• 异步统计。
• 文件处理。

不适合隐藏到 Event：

• 主流程强依赖步骤。
• 必须按固定顺序执行的核心业务动作。
• 失败后必须阻断当前请求的逻辑。

事务后副作用必须使用 afterCommit() 或事务提交后的调度方式：

SyncOrderToErpJob::dispatch($order->id)->afterCommit();

4.11 Resource 与 Response 边界

Resource 负责“业务数据怎么映射成 JSON 字段”。

ApiResponder 负责“顶层响应协议怎么输出”。

Application Service -> Model / DTO / Paginator
Controller          -> Resource
ApiResponder        -> code / message / data / meta / links

禁止：

• Application Service 返回 Resource。
• Application Service 返回 JsonResponse。
• Resource 触发数据库查询。
• Resource 拼 code / message 顶层响应壳。

4.12 本章检查清单

Code Review 时必须确认：

• 路由是否按端口拆分，后台路由是否具备稳定 route name。
• Middleware 是否只处理横切能力。
• 写接口和复杂列表是否使用 FormRequest。
• Controller 是否保持薄，是否没有事务和复杂查询。
• Application Service 是否是业务动作主入口。
• Domain Service 是否不依赖 HTTP 上下文。
• Resource 是否没有触发数据库查询。
• 事务后副作用是否使用 afterCommit()。

5. 输入校验与 Data 对象规范

5.1 本章定位

本章定义请求输入从 HTTP 参数进入应用层之前的处理方式。

目标：

• 字段校验集中在 FormRequest。
• 字段规则复用沉淀到 Schema / Ruleset。
• 复杂单字段规则使用 Rule Object。
• Application Service 接收明确结构，不长期接收大体量裸数组。

5.2 校验三层职责

业务流程合法性不属于校验层。

示例边界：

5.3 FormRequest 标准写法

final class CreateUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user('admin')?->can('admin.users.create') === true;
    }

    protected function prepareForValidation(): void
    {
        $this->merge([
            'nickname' => is_string($this->nickname) ? trim($this->nickname) : $this->nickname,
            'email' => is_string($this->email) ? strtolower(trim($this->email)) : $this->email,
        ]);
    }

    public function rules(): array
    {
        return [
            'nickname' => UserSchema::nickname(),
            'email' => UserSchema::email(),
            'password' => UserSchema::password(),
        ];
    }
}

规则：

• 所有写接口必须使用 FormRequest。
• 列表接口必须使用 FormRequest 校验筛选、排序、分页参数。
• authorize() 不应长期直接写复杂业务流程。
• prepareForValidation() 只做轻量归一，不写数据库查询。
• rules() 不写业务状态流转判断。

5.4 Schema / Ruleset 规范

Schema 用于复用实体字段规则，避免字段长度、格式、枚举规则散落在多个 Request。

推荐目录：

app/Validation/Schemas/{Domain}/{Entity}Schema.php

示例：

final class UserSchema
{
    public static function nickname(bool $required = true): array
    {
        return [
            $required ? 'required' : 'nullable',
            'string',
            'min:2',
            'max:30',
        ];
    }

    public static function email(bool $required = true): array
    {
        return [
            $required ? 'required' : 'nullable',
            'email:rfc,dns',
            'max:64',
        ];
    }

    public static function password(bool $required = true): array
    {
        return [
            $required ? 'required' : 'nullable',
            'string',
            'min:8',
            'max:64',
        ];
    }
}

规则：

• Schema 只返回规则数组。
• Schema 不读取 Request。
• Schema 不查询数据库。
• Schema 不承载业务流程合法性。

5.5 Rule Object 规范

复杂单字段校验使用 Rule Object。

适用场景：

• 规则复杂，多个 Request 复用。
• 需要封装正则、算法、格式校验。
• 需要清晰错误消息。

推荐目录：

app/Rules/{Name}Rule.php

不建议把大段复杂正则和判断直接塞进 FormRequest。

5.6 Data 对象定位

Data 用于承接应用层输入或输出结构。

Data 不替代：

• FormRequest。
• Resource。
• Model。
• DTO 之外的业务服务。

三类 Data：

推荐目录：

app/Data/{Domain}/{Name}Data.php

5.7 Input Data 示例

final class CreateUserData
{
    public function __construct(
        public readonly string $nickname,
        public readonly string $email,
        public readonly string $password,
    ) {
    }

    public static function fromArray(array $data): self
    {
        return new self(
            nickname: $data['nickname'],
            email: $data['email'],
            password: $data['password'],
        );
    }
}

规则：

• Data 不依赖 Request。
• Data 不查询数据库。
• Data 不写业务逻辑。
• 可在 fromArray() 中做安全的类型转换，但不做业务判断。

5.8 Query Data 示例

final class OrderListQueryData
{
    public function __construct(
        public readonly ?string $keyword = null,
        public readonly ?int $status = null,
        public readonly ?string $createdFrom = null,
        public readonly ?string $createdTo = null,
        public readonly string $sort = 'id',
        public readonly string $order = 'desc',
        public readonly int $page = 1,
        public readonly int $pageSize = 20,
    ) {
    }

    public static function fromArray(array $data): self
    {
        return new self(
            keyword: $data['keyword'] ?? null,
            status: isset($data['status']) ? (int) $data['status'] : null,
            createdFrom: $data['created_from'] ?? null,
            createdTo: $data['created_to'] ?? null,
            sort: $data['sort'] ?? 'id',
            order: $data['order'] ?? 'desc',
            page: (int) ($data['page'] ?? 1),
            pageSize: (int) ($data['page_size'] ?? 20),
        );
    }
}

5.9 Output Data 示例

当一个接口返回多个区块、统计汇总、权限布尔值等复合结果时，使用 Output Data。

final class OrderDetailPageData
{
    public function __construct(
        public readonly Order $order,
        public readonly bool $canCancel,
        public readonly bool $canApplyRefund,
        public readonly array $timeline,
    ) {
    }
}

Resource 消费 Output Data：

final class OrderDetailPageResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'order' => new OrderResource($this->resource->order),
            'permissions' => [
                'can_cancel' => $this->resource->canCancel,
                'can_apply_refund' => $this->resource->canApplyRefund,
            ],
            'timeline' => $this->resource->timeline,
        ];
    }
}

5.10 本章检查清单

• 写接口是否使用 FormRequest。
• 列表接口是否校验分页、筛选、排序。
• 字段规则是否沉淀到 Schema / Ruleset。
• 复杂单字段规则是否使用 Rule Object。
• Service 入参数量较多时是否使用 Input Data / Query Data。
• Data 是否没有依赖 Request、数据库、Response。
• 业务流程合法性是否没有塞进 rules。

6. Model、Eloquent 与数据库规范

6.1 本章定位

本章定义 Model、Eloquent、Migration、数据库字段与索引的默认写法。

核心原则：

Model 是 Eloquent 实体表达层，不是业务流程层。
数据库是核心事实来源，不把一致性寄托在前端、缓存或临时代码判断上。

6.2 Model 职责边界

Model 负责：

• 表映射。
• 字段白名单。
• 字段类型转换。
• 关联关系。
• 简单 Scope。
• 简单状态判断。
• 简单实体辅助方法。

Model 不负责：

• HTTP Request / Response。
• Controller 流程。
• 事务编排。
• 跨模型业务流程。
• 外部接口调用。
• 业务操作审计。
• 复杂状态流转。
• 当前用户权限上下文判断。

允许：

$order->isPaid();
$order->isCancelable();
$order->user();
Order::query()->paid();

禁止：

$order->approveRefundAndNotifyUser();
$order->payWithBalanceAndCreateTransaction();
$order->cancelAndRestoreStockAndWriteAudit();

6.3 Model 目录与文件顺序

推荐目录：

app/Models/{Domain}/{ModelName}.php

示例：

app/Models/Order/Order.php
app/Models/Order/OrderItem.php
app/Models/Refund/RefundOrder.php
app/Models/Permission/UiNode.php

Model 内部顺序：

1. $table / $connection / $primaryKey
2. $fillable
3. $hidden
4. casts()
5. 关联关系
6. Scope
7. 简单状态判断
8. 简单实体辅助方法

6.4 $fillable 与写入字段规范

新项目默认使用 $fillable 白名单。

protected $fillable = [
    'user_id',
    'order_no',
    'status',
    'total_amount',
    'paid_at',
];

规则：

• Controller / Service 不得直接使用 $request->all() 创建或更新模型。
• 写入字段必须来自 validated()、Input Data 或 Service 中显式组装的数组。
• 系统字段、权限字段、金额字段、审核字段、状态流转字段不得随意加入 $fillable。

敏感字段示例：

id
created_by
updated_by
deleted_by
is_admin
balance
paid_at
approved_at
role_id
permission_version

禁止：

User::query()->create($request->all());

推荐：

User::query()->create([
    'nickname' => $data->nickname,
    'email' => $data->email,
    'status' => UserStatus::Enabled,
]);

6.5 casts 规范

Laravel 11 新代码推荐使用 casts() 方法。

protected function casts(): array
{
    return [
        'status' => OrderStatus::class,
        'is_paid' => 'boolean',
        'snapshot' => 'array',
        'paid_at' => 'datetime',
        'total_amount' => 'integer',
        'settings' => 'array',
    ];
}

必须显式 cast 的字段：

禁止长期手工转换：

$isPaid = (int) $order->is_paid === 1;
$snapshot = json_decode($order->snapshot, true);
$paidAt = Carbon::parse($order->paid_at);

6.6 Enum 状态字段规范

核心业务状态字段推荐使用 int backed enum。

enum OrderStatus: int
{
    case PendingPay = 1;
    case Paid = 2;
    case Canceled = 3;
    case Finished = 4;

    public function key(): string
    {
        return match ($this) {
            self::PendingPay => 'pending_pay',
            self::Paid => 'paid',
            self::Canceled => 'canceled',
            self::Finished => 'finished',
        };
    }

    public function label(): string
    {
        return match ($this) {
            self::PendingPay => '待支付',
            self::Paid => '已支付',
            self::Canceled => '已取消',
            self::Finished => '已完成',
        };
    }
}

规则：

• 数据库存储稳定数字值。
• 业务代码使用 Enum case。
• value 是数据库值和机器判断值。
• key() 是稳定英文标识。
• label() 是展示文案，不用于条件判断。
• 二值开关字段使用 boolean cast，不强制 Enum。

不推荐：

enum OrderStatus: string
{
    case Paid = '已支付';
}

6.7 关系方法规范

关系方法必须声明返回类型。

public function user(): BelongsTo
{
    return $this->belongsTo(User::class);
}

public function items(): HasMany
{
    return $this->hasMany(OrderItem::class);
}

关系方法可以包含简单稳定条件：

public function enabledItems(): HasMany
{
    return $this->hasMany(OrderItem::class)
        ->where('is_enabled', true);
}

禁止在关系方法中依赖当前登录用户：

public function visibleItemsForCurrentAdmin(): HasMany
{
    return $this->hasMany(OrderItem::class)
        ->whereIn('store_id', auth('admin')->user()->store_ids);
}

6.8 Scope 规范

Scope 只放单一、稳定、可复用、无 HTTP 感知的查询条件。

public function scopePaid(Builder $query): Builder
{
    return $query->where('status', OrderStatus::Paid->value);
}

public function scopeOfStore(Builder $query, int $storeId): Builder
{
    return $query->where('store_id', $storeId);
}

不推荐把完整后台列表查询塞进 Model：

public function scopeAdminOrderList(Builder $query, array $filters, AdminUser $user): Builder
{
    // 关键词、状态、时间、门店、权限、排序、关联、统计全部写这里
}

复杂列表查询应放到 Application Service、Query Object 或 Repository。

6.9 Accessor / Mutator 规范

Accessor / Mutator 只用于简单字段转换。

protected function nickname(): Attribute
{
    return Attribute::make(
        set: fn (?string $value) => is_string($value) ? trim($value) : $value,
    );
}

禁止：

• 查询数据库。
• 调外部接口。
• 依赖当前登录用户。
• 写日志。
• 修改其他模型。
• 承载复杂业务规则。

展示型字段优先交给 Resource，不建议大量塞入 $appends。

6.10 Observer、软删除与全局 Scope

Observer 只适合低业务语义、稳定、通用的生命周期逻辑。

可以放 Observer：

• 自动生成 UUID / 编号。
• 自动填充 created_by、updated_by。
• 删除附件后的低风险清理任务。
• 清理模型相关缓存。

不建议放 Observer：

• 订单支付成功后发货。
• 退款审核通过后打款。
• 权限变更后通知用户。
• 商品删除后同步第三方系统。

SoftDeletes 不默认全表使用：

全局 Scope 必须谨慎。不得用全局 Scope 做后台权限过滤、当前用户过滤或复杂业务状态隐藏。

6.11 Migration 与字段规范

默认规则：

• 主键默认使用 $table->id()。
• 金额以整数存储，单位为分。
• 状态字段使用 unsignedTinyInteger 或 unsignedSmallInteger，并按查询需要建索引。
• 业务唯一约束必须落数据库唯一索引。
• 时间字段使用明确业务命名，如 paid_at、approved_at、cancelled_at。
• JSON 字段用于扩展快照、配置、低频查询数据，不作为高频筛选主条件。
• 字段注释按团队规范使用，不替代代码中的 Enum / 文档。

示例：

Schema::create('orders', function (Blueprint $table): void {
    $table->id();
    $table->foreignId('user_id')->index();
    $table->string('order_no', 64)->unique();
    $table->unsignedTinyInteger('status')->default(OrderStatus::PendingPay->value)->index();
    $table->unsignedBigInteger('total_amount')->default(0);
    $table->timestamp('paid_at')->nullable()->index();
    $table->json('snapshot')->nullable();
    $table->timestamps();

    $table->index(['user_id', 'status']);
});

6.12 索引与唯一约束

必须使用唯一索引兜底的场景：

• 订单号。
• 支付流水号。
• 第三方回调事件 ID。
• Open API 调用方请求号。
• 用户领取优惠券记录。
• 幂等键。

示例：

$table->unique(['provider', 'event_id']);
$table->unique(['scope', 'idempotency_key']);
$table->unique(['user_id', 'coupon_id', 'source_id']);

规则：

• 代码层 exists() 只能作为提前提示，不是唯一性最终保障。
• 高风险唯一业务约束必须由数据库保证。
• 捕获唯一冲突后应转换为稳定业务异常或幂等成功结果。

6.13 本章检查清单

• Model 是否没有依赖 request()、auth()、response()。
• Model 是否没有编排跨模型业务流程。
• 是否使用 $fillable 白名单。
• 是否显式声明 casts()。
• 核心状态字段是否使用 int backed enum。
• 关系方法是否声明返回类型。
• Scope 是否保持简单稳定。
• 复杂列表查询是否没有塞进 Model。
• 强唯一业务约束是否有数据库唯一索引。
• 金额是否使用整数存储。

7. 查询、筛选、排序、分页与导出规范

7.1 本章定位

本章约束列表页、搜索页、导出、统计查询的统一写法。

核心目标：

• Controller 不写复杂查询。
• 查询参数必须校验。
• 排序、include、数据范围必须白名单控制。
• Resource 不触发数据库查询。
• 列表和导出复用同一套查询条件。

标准链路：

FormRequest
  -> Query Data
  -> ListXxxService / ExportXxxService
  -> Query Object / Repository / Builder
  -> Paginator / Collection / cursor
  -> Resource / Export Writer

7.2 查询参数命名规范

7.3 列表 FormRequest 示例

final class ListOrderRequest extends FormRequest
{
    protected function prepareForValidation(): void
    {
        $this->merge([
            'keyword' => is_string($this->keyword) ? trim($this->keyword) : $this->keyword,
            'page' => $this->input('page', 1),
            'page_size' => $this->input('page_size', 20),
            'order' => strtolower((string) $this->input('order', 'desc')),
        ]);
    }

    public function rules(): array
    {
        return [
            'keyword' => ['nullable', 'string', 'max:100'],
            'status' => ['nullable', 'integer', Rule::in(array_column(OrderStatus::cases(), 'value'))],
            'store_id' => ['nullable', 'integer', 'min:1'],
            'created_from' => ['nullable', 'date'],
            'created_to' => ['nullable', 'date', 'after_or_equal:created_from'],
            'sort' => ['nullable', 'string', 'max:50'],
            'order' => ['nullable', Rule::in(['asc', 'desc'])],
            'include' => ['nullable', 'string', 'max:255'],
            'page' => ['nullable', 'integer', 'min:1'],
            'page_size' => ['nullable', 'integer', 'min:1', 'max:100'],
        ];
    }
}

规则：

• 所有列表接口必须校验分页、筛选、排序参数。
• page_size 必须有上限。
• 前端传入字段不得直接进入 where、orderBy、with。

7.4 Query Data 与 Query Object

查询条件较多、需要导出复用、涉及数据范围过滤时，必须使用 Query Data + Query Object。

final class OrderListQuery
{
    public function build(OrderListQueryData $query, AdminUser $actor): Builder
    {
        $builder = Order::query()
            ->select([
                'orders.id',
                'orders.order_no',
                'orders.user_id',
                'orders.status',
                'orders.total_amount',
                'orders.created_at',
            ])
            ->whereIn('orders.store_id', $actor->accessibleStoreIds());

        $this->applyKeyword($builder, $query);
        $this->applyStatus($builder, $query);
        $this->applyCreatedRange($builder, $query);
        $this->applyIncludes($builder, $query);
        $this->applySort($builder, $query);

        return $builder;
    }
}

7.5 排序白名单

禁止：

$builder->orderBy($request->input('sort'), $request->input('order'));

推荐：

private function applySort(Builder $builder, OrderListQueryData $query): void
{
    $sortMap = [
        'id' => 'orders.id',
        'created_at' => 'orders.created_at',
        'paid_at' => 'orders.paid_at',
        'total_amount' => 'orders.total_amount',
    ];

    $column = $sortMap[$query->sort] ?? 'orders.id';
    $direction = $query->order === 'asc' ? 'asc' : 'desc';

    $builder->orderBy($column, $direction);

    if ($column !== 'orders.id') {
        $builder->orderByDesc('orders.id');
    }
}

规则：

• sort 必须通过白名单映射为真实数据库字段。
• 涉及 join 的排序字段必须显式带表名。
• 默认排序必须稳定，推荐 id desc 或 created_at desc + id desc。

7.6 keyword 搜索规范

private function escapeLike(string $value): string
{
    return addcslashes($value, '%_\\');
}

private function applyKeyword(Builder $builder, OrderListQueryData $query): void
{
    if (! $query->keyword) {
        return;
    }

    $keyword = $this->escapeLike($query->keyword);

    $builder->where(function (Builder $builder) use ($keyword): void {
        $builder->where('orders.order_no', 'like', '%' . $keyword . '%')
            ->orWhere('orders.receiver_phone', 'like', '%' . $keyword . '%')
            ->orWhereHas('user', function (Builder $builder) use ($keyword): void {
                $builder->where('nickname', 'like', '%' . $keyword . '%');
            });
    });
}

规则：

• keyword 必须 trim 并限制长度。
• LIKE 查询建议转义 %、_、\。
• 多字段 OR 必须用 where(function) 包裹。
• 高频复杂搜索应迁移到专门搜索方案，不应无限叠加 LIKE。

7.7 时间范围规范

日期型参数必须明确边界：

created_from = 2026-04-01 -> 2026-04-01 00:00:00
created_to   = 2026-04-29 -> 2026-04-29 23:59:59

示例：

$createdFrom = $query->createdFrom
    ? CarbonImmutable::parse($query->createdFrom)->startOfDay()
    : null;

$createdTo = $query->createdTo
    ? CarbonImmutable::parse($query->createdTo)->endOfDay()
    : null;

$builder
    ->when($createdFrom, fn (Builder $builder) => $builder->where('orders.created_at', '>=', $createdFrom))
    ->when($createdTo, fn (Builder $builder) => $builder->where('orders.created_at', '<=', $createdTo));

规则：

• 日期型参数扩展到当天开始和结束。
• 完整时间型参数尊重前端传入时间。
• 涉及时区时，接口合同必须明确前端传入时区和后端存储时区。

7.8 数据范围过滤

数据范围必须在 Query Builder 阶段完成。

推荐：

Order::query()
    ->whereIn('orders.store_id', $actor->accessibleStoreIds())
    ->latest('orders.id')
    ->paginate($query->pageSize);

禁止：

• 先查全量，再在 PHP 内存中过滤。
• 先返回给前端，再让前端隐藏越权数据。
• 只在详情和更新接口做权限，列表接口不做数据范围。

7.9 N+1 与 select 字段

Resource 不得触发数据库查询。

不推荐：

return [
    'user_name' => $this->user->nickname,
    'item_count' => $this->items()->count(),
];

推荐查询阶段处理：

$builder = Order::query()
    ->select([
        'orders.id',
        'orders.order_no',
        'orders.user_id',
        'orders.status',
        'orders.total_amount',
        'orders.created_at',
    ])
    ->with(['user:id,nickname'])
    ->withCount('items');

Resource：

return [
    'id' => $this->id,
    'order_no' => $this->order_no,
    'user_name' => $this->user?->nickname,
    'item_count' => $this->items_count,
];

7.10 include 白名单

支持 include=user,items,payment 时，必须白名单映射。

private function applyIncludes(Builder $builder, OrderListQueryData $query): void
{
    $allowedIncludes = [
        'user' => 'user:id,nickname',
        'items' => 'items:id,order_id,sku_name,quantity',
        'payment' => 'payment:id,order_id,pay_no,amount',
    ];

    $includes = collect(explode(',', $query->include ?? ''))
        ->map(fn (string $item) => trim($item))
        ->filter()
        ->intersect(array_keys($allowedIncludes))
        ->map(fn (string $item) => $allowedIncludes[$item])
        ->values()
        ->all();

    $builder->with($includes);
}

禁止：

$builder->with(explode(',', $request->input('include')));

7.11 列表与导出复用

列表和导出应复用同一个 Query Data 和 Query Object。

OrderListQueryData
  -> OrderListQuery::build()
      -> ListOrderService
      -> ExportOrderService

列表：

$builder = $this->orderListQuery->build($query, $actor);

return $builder->paginate(
    perPage: $query->pageSize,
    page: $query->page,
);

导出：

$builder = $this->orderListQuery->build($query, $actor);

$builder->chunkById(500, function (Collection $orders): void {
    // 写入 Excel / CSV
});

规则：

• 导出不通过 paginate() 循环全部页实现。
• 大数据导出必须使用 chunkById、cursor 或队列任务。
• 导出仍必须执行权限校验、数据范围过滤、请求日志和必要业务审计。
• 导出字段可以和列表不同，但筛选条件和数据范围应共用。

7.12 本章检查清单

• Controller 是否没有复杂查询。
• 列表参数是否全部经过 FormRequest 校验。
• page_size 是否有上限。
• sort、include 是否白名单。
• keyword 是否 trim、限长、LIKE 转义。
• 数据范围是否在 Query Builder 阶段应用。
• Resource 是否没有触发查询。
• 列表和导出是否复用查询条件。
• 导出是否没有使用 paginate 循环全量数据。

8. 统一响应、异常处理与业务错误码

8.1 本章定位

本章定义 API 成功响应、失败响应、分页响应、异常渲染和业务错误码的统一协议。

核心目标：

• 前端永远收到稳定 JSON 协议。
• 成功和失败出口复用同一个 ApiResponder。
• HTTP 状态码和业务错误码分层。
• 错误码、错误标识、错误文案有唯一事实来源。

8.2 成功响应结构

{
  "code": 0,
  "message": "success",
  "data": {},
  "meta": {},
  "links": {}
}

字段职责：

规则：

• data 不混入分页元信息。
• meta 承载扩展元信息。
• links 无需求时可为空对象或省略，但项目内必须统一。

8.3 错误响应结构

{
  "code": 120101,
  "error_key": "ORDER_STATUS_NOT_CANCELABLE",
  "message": "Order status does not allow cancellation.",
  "errors": {
    "order_id": 123,
    "current_status": 4
  },
  "meta": {}
}

字段职责：

规则：

• 前端不得基于 message 做业务分支判断。
• 程序判断优先使用 code 或 error_key。
• error_key 使用全大写蛇形命名。
• HTTP 状态码表达协议层结果，业务错误码表达业务语义。

8.4 Resource、Controller、ApiResponder 边界

Application Service -> 返回业务结果
Resource            -> 映射 data 内容
ApiResponder        -> 包装顶层响应协议
Exception Handler   -> 复用 ApiResponder 输出错误

禁止：

• Application Service 返回 JsonResponse。
• Resource 拼 code / message / meta / links 顶层协议。
• Controller 长期手写复杂响应数组。
• 异常渲染绕过 ApiResponder。

8.5 ApiResponder 标准模板

final class ApiResponder
{
    public function success(
        mixed $data = null,
        string $message = 'success',
        int $code = 0,
        array $meta = [],
        array $links = [],
        int $status = 200,
    ): JsonResponse {
        return response()->json([
            'code' => $code,
            'message' => $message,
            'data' => $this->normalizeData($data),
            'meta' => $meta,
            'links' => $links,
        ], $status);
    }

    public function created(
        mixed $data = null,
        string $message = 'created',
        int $code = 0,
        array $meta = [],
        array $links = [],
    ): JsonResponse {
        return $this->success(
            data: $data,
            message: $message,
            code: $code,
            meta: $meta,
            links: $links,
            status: 201,
        );
    }

    public function paginated(
        mixed $data,
        LengthAwarePaginator|Paginator $paginator,
        string $message = 'success',
        int $code = 0,
        array $meta = [],
        array $links = [],
        int $status = 200,
    ): JsonResponse {
        $meta['pagination'] = array_filter([
            'page' => method_exists($paginator, 'currentPage') ? $paginator->currentPage() : null,
            'page_size' => method_exists($paginator, 'perPage') ? $paginator->perPage() : null,
            'total' => method_exists($paginator, 'total') ? $paginator->total() : null,
            'has_more' => method_exists($paginator, 'hasMorePages') ? $paginator->hasMorePages() : null,
        ], static fn (mixed $value) => $value !== null);

        $links = array_merge([
            'next' => method_exists($paginator, 'nextPageUrl') ? $paginator->nextPageUrl() : null,
            'prev' => method_exists($paginator, 'previousPageUrl') ? $paginator->previousPageUrl() : null,
        ], $links);

        return $this->success(
            data: $data,
            message: $message,
            code: $code,
            meta: $meta,
            links: $links,
            status: $status,
        );
    }

    public function error(
        string $message = 'error',
        int $code = 1,
        ?string $errorKey = null,
        array $errors = [],
        array $meta = [],
        int $status = 400,
    ): JsonResponse {
        return response()->json([
            'code' => $code,
            'error_key' => $errorKey,
            'message' => $message,
            'errors' => $errors,
            'meta' => $meta,
        ], $status);
    }

    private function normalizeData(mixed $data): mixed
    {
        if ($data instanceof JsonResource || $data instanceof AnonymousResourceCollection) {
            return $data->resolve(request());
        }

        return $data;
    }
}

8.6 BaseApiController 标准模板

abstract class BaseApiController extends Controller
{
    protected function success(
        mixed $data = null,
        string $message = 'success',
        int $code = 0,
        array $meta = [],
        array $links = [],
        int $status = 200,
    ): JsonResponse {
        return app(ApiResponder::class)->success($data, $message, $code, $meta, $links, $status);
    }

    protected function created(
        mixed $data = null,
        string $message = 'created',
        int $code = 0,
        array $meta = [],
        array $links = [],
    ): JsonResponse {
        return app(ApiResponder::class)->created($data, $message, $code, $meta, $links);
    }

    protected function paginated(
        mixed $data,
        LengthAwarePaginator|Paginator $paginator,
        string $message = 'success',
        int $code = 0,
        array $meta = [],
        array $links = [],
        int $status = 200,
    ): JsonResponse {
        return app(ApiResponder::class)->paginated($data, $paginator, $message, $code, $meta, $links, $status);
    }
}

8.7 分页响应规范

分页响应：

{
  "code": 0,
  "message": "success",
  "data": [{ "id": 1, "name": "A" }],
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "has_more": true
    }
  },
  "links": {
    "next": "https://example.com/orders?page=2",
    "prev": null
  }
}

规则：

• 当前页数据放 data。
• 分页信息统一放 meta.pagination。
• 不直接嵌入 Laravel 默认分页结构，避免响应合同不稳定。

8.8 业务错误码体系

业务错误码必须全局唯一。

推荐目录：

app/Support/ErrorCodes/
├── Contracts/BusinessError.php
├── Common/CommonError.php
├── Auth/AuthError.php
├── Permission/PermissionError.php
├── Order/OrderError.php
└── Coupon/CouponError.php

接口：

interface BusinessError
{
    public function code(): int;

    public function key(): string;

    public function httpStatus(): int;

    public function defaultMessage(): string;
}

示例：

enum OrderError: int implements BusinessError
{
    case STATUS_NOT_CANCELABLE = 120101;
    case ALREADY_PAID = 120102;
    case NOT_FOUND = 120103;

    public function code(): int
    {
        return $this->value;
    }

    public function key(): string
    {
        return match ($this) {
            self::STATUS_NOT_CANCELABLE => 'ORDER_STATUS_NOT_CANCELABLE',
            self::ALREADY_PAID => 'ORDER_ALREADY_PAID',
            self::NOT_FOUND => 'ORDER_NOT_FOUND',
        };
    }

    public function httpStatus(): int
    {
        return match ($this) {
            self::STATUS_NOT_CANCELABLE => 422,
            self::ALREADY_PAID => 409,
            self::NOT_FOUND => 404,
        };
    }

    public function defaultMessage(): string
    {
        return match ($this) {
            self::STATUS_NOT_CANCELABLE => 'Order status does not allow cancellation.',
            self::ALREADY_PAID => 'Order has already been paid.',
            self::NOT_FOUND => 'Order not found.',
        };
    }
}

规则：

• 不在业务代码中手写裸数字错误码。
• 不让前端依赖 message 做判断。
• 不复用旧错误码表达新语义。
• 新增错误码必须同步文档和测试。

8.9 ApiHttpException 标准模板

final class ApiHttpException extends Exception
{
    public function __construct(
        private readonly BusinessError $businessError,
        private readonly ?string $apiMessage = null,
        private readonly array $errors = [],
        ?Throwable $previous = null,
    ) {
        parent::__construct($apiMessage ?? $businessError->defaultMessage(), 0, $previous);
    }

    public static function fromError(
        BusinessError $businessError,
        array $errors = [],
        ?string $message = null,
        ?Throwable $previous = null,
    ): self {
        return new self($businessError, $message, $errors, $previous);
    }

    public function getBusinessCode(): int
    {
        return $this->businessError->code();
    }

    public function getErrorKey(): string
    {
        return $this->businessError->key();
    }

    public function getStatusCode(): int
    {
        return $this->businessError->httpStatus();
    }

    public function getErrors(): array
    {
        return $this->errors;
    }
}

抛出示例：

throw ApiHttpException::fromError(
    OrderError::STATUS_NOT_CANCELABLE,
    errors: [
        'order_id' => $order->id,
        'current_status' => $order->status->value,
    ],
);

8.10 Laravel 11 异常渲染

在 bootstrap/app.php 中统一渲染 JSON 异常。

$exceptions->render(function (ValidationException $e, Request $request) {
    if (! $request->expectsJson()) {
        return null;
    }

    return app(ApiResponder::class)->error(
        message: 'The given data was invalid.',
        code: 42200,
        errorKey: 'VALIDATION_ERROR',
        errors: $e->errors(),
        status: 422,
    );
});

$exceptions->render(function (ApiHttpException $e, Request $request) {
    if (! $request->expectsJson()) {
        return null;
    }

    return app(ApiResponder::class)->error(
        message: $e->getMessage(),
        code: $e->getBusinessCode(),
        errorKey: $e->getErrorKey(),
        errors: $e->getErrors(),
        status: $e->getStatusCode(),
    );
});

规则：

• API 异常必须输出 JSON，不返回框架 HTML 错误页。
• 成功响应和失败响应都复用 ApiResponder。
• 未认证、无权限、签名失败、限流等异常也应映射到统一错误协议。
• 生产环境不得向前端暴露异常堆栈。

8.11 错误码测试要求

至少覆盖：

• 错误码唯一性。
• error_key 唯一性。
• 关键业务异常响应结构。
• ValidationException 响应结构。
• ApiHttpException 到 ApiResponder 的映射。

示例：

public function test_order_error_codes_are_unique(): void
{
    $codes = array_map(fn (OrderError $error) => $error->code(), OrderError::cases());

    $this->assertSame($codes, array_unique($codes));
}

8.12 本章检查清单

• Controller 是否不直接 response()->json()。
• 成功响应和失败响应是否都经过 ApiResponder。
• 分页信息是否放在 meta.pagination。
• 业务错误是否使用 BusinessError 定义。
• 是否没有手写裸数字错误码。
• 前端判断是否依赖 code 或 error_key，而不是 message。
• 异常渲染是否覆盖 Validation、认证、权限、业务异常和 500。
• 错误码是否有唯一性测试。

9. 认证、权限与 API 安全

9.1 本章定位

认证、权限与 API 安全用于回答三个问题：

认证：当前调用方是谁。
权限：当前调用方能不能执行这个动作。
API 安全：这个入口是否具备验签、限流、防重放、幂等和审计能力。

本章只规定默认安全链路，不替代具体业务规则。业务规则仍由 Application Service / Domain Service 判断，最终执行接口必须再次校验权限与状态。

默认链路：

Route
  -> authentication middleware
  -> signature / csrf / throttle / anti-abuse
  -> route permission middleware
  -> FormRequest::authorize()
  -> Application Service business check
  -> operation audit

9.2 认证默认方案

新项目默认使用 Laravel Sanctum 承接后台 SPA 和普通 API Token 认证。

规范要求：

• 认证只确认“调用方是谁”，不表达“能做什么”。
• Token abilities 只做粗粒度能力限制，不替代后台权限、对象级授权和业务状态校验。
• 后台 SPA 使用 Cookie Session 时，必须正确配置 SANCTUM_STATEFUL_DOMAINS、SESSION_DOMAIN、CORS 和 CSRF。
• Token 模式下，Token 必须支持过期、吊销、设备标识和最后使用时间记录。
• 登录、刷新 Token、退出登录、重置密码等入口必须限流并记录安全日志。

后台 SPA 环境变量示例：

SESSION_DRIVER=redis
SESSION_DOMAIN=.example.com
SANCTUM_STATEFUL_DOMAINS=admin.example.com,api.example.com,localhost:5173

Token 模式调用示例：

Authorization: Bearer 1|xxxxxxxxxxxxxxxxxxxxxxxx

9.3 Guard 与用户边界

不同调用方必须使用明确 Guard，不得混用后台用户、前台用户和开放平台调用方。

推荐 Guard：

admin  -> 管理后台用户
web    -> 普通 Web 用户
api    -> App / 小程序 / 客户端用户
open   -> 开放平台调用方

规则：

• 管理后台接口默认使用 auth:admin 或团队统一命名的后台 guard。
• 前台用户接口不得复用后台 AdminUser 模型。
• Open API 调用方应使用独立 ApiClient / OpenClient 模型，不应伪装成后台用户。
• 审计日志必须记录 actor_type，避免不同用户表的 id 冲突。
• 多 Guard 项目中，Policy、FormRequest、RoutePermissionMiddleware 必须明确使用哪个 guard。

路由分组示例：

Route::prefix('admin')
    ->name('admin.')
    ->middleware(['auth:admin', 'route.permission', 'request.log'])
    ->group(function () {
        Route::get('users', [UserController::class, 'index'])->name('users.index');
        Route::post('users', [UserController::class, 'store'])->name('users.store');
    });

Route::prefix('open')
    ->name('open.')
    ->middleware(['open.signature', 'throttle:open-api'])
    ->group(function () {
        Route::post('orders', [OpenOrderController::class, 'store'])->name('orders.store');
    });

9.4 权限推荐架构

后台权限默认采用以下四层结构：

spatie/laravel-permission
  -> UI 语义层 ui_nodes
  -> UI 节点与权限绑定
  -> 路由与权限绑定
  -> Middleware / Policy / Gate / FormRequest::authorize

各层定位：

规范要求：

• 前端菜单和按钮显隐只能提升体验，不能作为安全边界。
• 所有敏感写接口必须有后端权限校验。
• 权限事实源以 spatie 权限表为准，不以 ui_nodes 为准。
• ui_nodes 只表达 UI 入口语义，可用于菜单、按钮、审计摘要和前端权限树。
• 路由权限绑定必须稳定，不应依赖 Controller 方法名临时拼接。

推荐表：

permissions
roles
model_has_roles
model_has_permissions
role_has_permissions
ui_nodes
ui_node_permission_bindings
route_permission_bindings

9.5 权限命名规范

权限名使用稳定英文标识，不使用中文，不跟随前端文案变化。

推荐格式：

{domain}.{resource}.{action}

示例：

admin.user.view
admin.user.create
admin.user.update
admin.user.delete
order.refund.approve
product.stock.adjust
system.config.update

动作命名建议：

禁止：

• 一个权限名覆盖多个高风险动作。
• 权限名包含中文、页面标题或按钮文案。
• 为了省事使用 admin.* 作为普通角色权限。
• 前端自定义权限字符串后端不校验。

9.6 RoutePermissionMiddleware 标准流程

后台路由必须命名。权限中间件根据当前 route name 查找权限绑定，再调用用户权限判断。

推荐流程：

request route name
  -> route_permission_bindings.route_name
  -> permission name
  -> current admin user can(permission)
  -> allow / deny

最小实现示例：

<?php

namespace App\Http\Middleware;

use App\Exceptions\ApiHttpException;
use App\Models\Permission\RoutePermissionBinding;
use App\Support\ErrorCodes\Permission\PermissionError;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class RoutePermissionMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $routeName = $request->route()?->getName();

        if (! $routeName) {
            throw ApiHttpException::fromError(PermissionError::ROUTE_NAME_MISSING);
        }

        $permission = RoutePermissionBinding::query()
            ->where('route_name', $routeName)
            ->where('is_active', true)
            ->value('permission_name');

        if (! $permission) {
            throw ApiHttpException::fromError(PermissionError::ROUTE_PERMISSION_NOT_BOUND);
        }

        $user = $request->user('admin');

        if (! $user || ! $user->can($permission)) {
            throw ApiHttpException::fromError(PermissionError::FORBIDDEN);
        }

        return $next($request);
    }
}

规则：

• 查不到路由权限绑定时，生产环境默认拒绝。
• 开发环境可以通过配置允许临时放行，但必须记录 warning 日志。
• Super Admin 可以绕过普通权限，但必须进入业务操作审计。
• 权限绑定变更后必须清理 spatie 权限缓存，并让前端权限树缓存失效。

9.7 Policy、Gate 与 FormRequest::authorize 边界

不同授权能力的边界必须清楚。

示例：对象级授权放 Policy。

public function update(AdminUser $admin, Order $order): bool
{
    return $admin->can('order.update')
        && in_array($order->store_id, $admin->accessibleStoreIds(), true);
}

FormRequest 示例：

public function authorize(): bool
{
    $order = $this->route('order');

    return $order
        ? $this->user('admin')?->can('update', $order) === true
        : $this->user('admin')?->can('order.create') === true;
}

规则：

• Middleware 解决路由级权限，不解决对象级授权。
• Policy / Gate 解决对象级授权，不替代业务状态机。
• Application Service 执行核心业务前仍需校验业务状态。
• 列表、详情、导出、更新接口必须使用同一套数据范围规则。

9.8 UI 节点 Header 与审计上下文

前端统一通过 Header 传递 UI 节点：

X-Ui-Node-Id: 1001

用途：

• 补全业务操作审计中的页面、按钮、路径语义。
• 关联 ui_nodes，生成“用户在某页面点击某按钮”的摘要。
• 与 request_id 一起串联请求日志、业务审计、SQL 执行审计。

规则：

• X-Ui-Node-Id 不作为授权依据。
• 后端不得因为前端传入某个 UI 节点就认为用户有权限。
• UI 节点不存在时，审计可以降级为 route name / event key。
• 高风险操作必须有 event_key，不能完全依赖 UI 节点自动推断。

9.9 SPA API 安全规范

SPA 的前端代码、接口地址、请求参数都可以被用户看到。不要把“接口只给我的前端调用”理解为安全边界。

默认规则：

• CORS 只控制浏览器跨域访问，不阻止 curl、Postman、脚本直接请求。
• 所有敏感接口必须认证、授权、限流和审计。
• Cookie Session 模式必须启用 CSRF。
• Token 模式必须保护 Token 存储和过期策略。
• 公共接口必须限流、缓存、Bot 防护和请求日志。
• 展示型公共接口可以加入短期签名、Referer / Origin 检查、设备指纹、验证码等提高滥用成本，但不能视为绝对安全。
• 不得把内部管理数据做成“无鉴权但只在指定前端展示”的裸接口。

CORS 配置原则：

允许域名：精确列出后台和前台域名
允许 Header：只开放实际需要的 Header
允许 Credentials：仅 Cookie Session 场景开启
生产环境：不得使用 * 搭配 credentials

公共接口最低要求：

throttle
request log
response cache 按需
anti-abuse 按需
敏感字段不返回
错误响应不泄露内部异常细节

9.10 Open API 签名规范

Open API 写接口必须具备身份识别、验签、防重放、限流和幂等。

推荐 Header：

X-Client-Id: client_1001
X-Timestamp: 1760000000
X-Nonce: 2f4f5a7c8c
X-Signature: hex_hmac_sha256_signature
Idempotency-Key: order-create-20260429-0001

推荐签名串：

METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY_SHA256

验签流程：

1. 根据 X-Client-Id 查找调用方和 secret
2. 校验调用方状态、IP 白名单、权限范围
3. 校验 X-Timestamp 是否在允许窗口内
4. 校验 X-Nonce 是否已使用，防重放
5. 计算 body sha256
6. 计算 HMAC-SHA256 签名并使用 hash_equals 比较
7. 校验 Idempotency-Key
8. 进入业务处理

验签骨架示例：

$payloadHash = hash('sha256', $request->getContent());

$signaturePayload = implode("\n", [
    strtoupper($request->method()),
    '/' . ltrim($request->path(), '/'),
    $request->header('X-Timestamp'),
    $request->header('X-Nonce'),
    $payloadHash,
]);

$expected = hash_hmac('sha256', $signaturePayload, $client->secret);

if (! hash_equals($expected, (string) $request->header('X-Signature'))) {
    throw ApiHttpException::fromError(OpenApiError::INVALID_SIGNATURE);
}

规则：

• 签名密钥不得明文返回给前端。
• 时间戳窗口建议 5 分钟以内。
• nonce 必须短期缓存或落库防重放。
• 写接口必须要求幂等键或外部业务单号。
• 签名失败、重放、限流、幂等冲突都必须记录安全日志。

9.11 Webhook 安全规范

Webhook 必须先验签，再处理业务。

规则：

• 平台事件 ID 必须建立唯一索引。
• 同一个事件重复到达时，返回幂等成功或明确“已处理”。
• 回调原始 payload 应保存摘要或完整内容，按安全和隐私要求决定。
• 业务处理必须在事务内完成核心状态变更。
• 外部副作用必须 afterCommit。
• Webhook 不应依赖前端登录态和 CSRF。

推荐处理链路：

Webhook Route
  -> provider signature middleware
  -> callback FormRequest
  -> callback Data
  -> HandleWebhookService
  -> event unique record
  -> transaction + lockForUpdate
  -> state transition
  -> afterCommit Job

9.12 本章检查清单

• 后台敏感接口是否全部有认证、权限和 route name。
• 权限名是否稳定、英文、可检索。
• 前端按钮隐藏是否没有替代后端权限校验。
• RoutePermissionMiddleware 查不到绑定时生产环境是否默认拒绝。
• Policy / Gate 是否覆盖对象级授权。
• 列表、详情、导出是否使用同一套数据范围。
• X-Ui-Node-Id 是否只用于审计，不用于授权。
• SPA 公共接口是否限流、缓存、脱敏和记录日志。
• Open API 是否具备签名、时间戳、nonce、幂等和限流。
• Webhook 是否先验签、再幂等、再处理业务。

10. 状态枚举与状态机规范

10.1 本章定位

状态规范用于统一数据库状态值、后端判断、API 输出、前端判断和状态流转规则。

默认结构：

int backed enum
  -> Model casts()
  -> Domain 状态机 / 状态流转服务
  -> Application Service 事务执行
  -> Resource 显式输出 status / status_key / status_label / can_xxx
  -> Test 覆盖允许与禁止流转

适合状态机的对象：订单、支付、退款、售后、优惠券、发货、审核、结算、导入导出任务、工单、权限审批。

普通二值开关，例如 is_active、is_default、is_deleted，使用 boolean cast 即可。

判断原则：

只表示开关：boolean cast。
驱动业务流程：Enum + 状态机。
涉及钱、库存、权益、权限、结算：必须集中管理流转规则。

10.2 状态字段数据库规范

核心状态字段推荐使用 unsignedTinyInteger 或 unsignedSmallInteger，并建立必要索引。

$table->unsignedTinyInteger('status')
    ->default(OrderStatus::PendingPay->value)
    ->index();

规则：

• 核心状态字段不建议 nullable。
• 数据库存储稳定数字值，不存中文文案。
• 新增状态值时不得复用历史状态值。
• 删除状态值必须考虑历史数据兼容。
• 状态字段参与列表筛选时必须建索引。

10.3 Enum 职责与标准模板

Enum 负责表达“状态是什么”，不负责执行业务流程。

Enum 可以包含：

• 数据库存储值。
• 稳定英文 key。
• 展示 label。
• 是否终态。
• 状态分组。
• 前端 options 输出。
• 简单纯状态判断。

标准模板：

<?php

namespace App\Enums\Order;

enum OrderStatus: int
{
    case PendingPay = 1;
    case Paid = 2;
    case Canceled = 3;
    case Finished = 4;
    case Refunding = 5;
    case Refunded = 6;

    public function key(): string
    {
        return match ($this) {
            self::PendingPay => 'pending_pay',
            self::Paid => 'paid',
            self::Canceled => 'canceled',
            self::Finished => 'finished',
            self::Refunding => 'refunding',
            self::Refunded => 'refunded',
        };
    }

    public function label(): string
    {
        return match ($this) {
            self::PendingPay => '待支付',
            self::Paid => '已支付',
            self::Canceled => '已取消',
            self::Finished => '已完成',
            self::Refunding => '退款中',
            self::Refunded => '已退款',
        };
    }

    public function isTerminal(): bool
    {
        return in_array($this, [
            self::Canceled,
            self::Finished,
            self::Refunded,
        ], true);
    }

    public static function options(): array
    {
        return array_map(
            fn (self $status) => [
                'value' => $status->value,
                'key' => $status->key(),
                'label' => $status->label(),
            ],
            self::cases(),
        );
    }
}