laravel-project-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Project Patterns

Laravel 项目模式

Use this skill before editing Laravel project backend application code, project-supporting PHP, Inertia Blade shells, React Email templates, or choosing tests. The references cover Laravel application code, routes, config, localization, bootstrap/public entrypoints, seeders, root tooling PHP,

resources/views

Blade shells,

resources/react-email

mail templates, schema-backed code, migrations, Eloquent models, factories, resources, actions, console commands, middleware, listeners, policies, support classes, and Pest tests across unit, integration, feature, and architecture suites, with Browser guidance only when a real browser suite is introduced.

This skill is derived from the live repository. When repository evidence disagrees with a generic Laravel habit, the repository wins. Read the exact files in the touched path first, then load the matching reference here, then compare with the nearest sibling module before writing code or tests. For controller-test work, start at

references/tests/Feature/Http/Controllers/README.md

; it is the central map for action order, web/API transport differences, nested

Workspace

boundaries, validation datasets, redirects/toasts, and public-id contracts.

Examples in this skill and its references are canonical synthetic examples. They merge compatible patterns observed across modules and intentionally use placeholder names such as

Workspace

ParentRecord

ChildRecord

LeafRecord

RelatedRecord

Actor

ExampleInput

, and

ExampleResource

. Do not replace those examples with real module/entity names.

在编辑Laravel项目后端应用代码、项目支持PHP、Inertia Blade外壳、React Email模板或选择测试方案前，请遵循本规范。参考内容涵盖Laravel应用代码、路由、配置、本地化、bootstrap/public入口点、种子文件、根工具PHP、

resources/views

Blade外壳、

resources/react-email

邮件模板、基于Schema的代码、迁移、Eloquent模型、工厂、资源、动作、控制台命令、中间件、监听器、策略、支持类，以及Unit、Integration、Feature、Architecture套件下的Pest测试，仅当引入真实浏览器套件时才提供Browser测试指导。

本规范源自实际代码仓库。当仓库实践与通用Laravel习惯冲突时，以仓库规则为准。在编写代码或测试前，先阅读待修改路径下的具体文件，再加载此处匹配的参考内容，最后与最近的同级模块进行对比。对于控制器测试工作，请先查看

references/tests/Feature/Http/Controllers/README.md

；该文件是动作顺序、Web/API传输差异、嵌套

Workspace

边界、验证数据集、重定向/提示信息以及公共ID约定的核心指南。

本规范及其参考内容中的示例为标准合成示例。它们整合了各模块中观察到的兼容模式，并有意使用

Workspace

、

ParentRecord

、

ChildRecord

、

LeafRecord

、

RelatedRecord

、

Actor

、

ExampleInput

和

ExampleResource

等占位符名称。请勿将这些示例替换为真实模块/实体名称。

First Pass

初步检查

Read the nearest
```
AGENTS.md
```
and application guidelines.
Search version-specific docs before code changes when Laravel Boost is available.

Inspect the exact file being changed and sibling files in the same area before generating anything:

```
database/migrations/*
```
```
routes/*.php
```
```
config/*.php
```
```
lang/**/*.php
```
```
bootstrap/*.php
```
```
public/*.php
```
```
database/seeders/*.php
```
root tooling PHP and tracked auxiliary PHP guidance
```
app/**
```
```
resources/views/**
```
```
resources/react-email/**
```
```
database/factories/**
```
```
tests/Unit/**
```
```
tests/Integration/**
```
```
tests/Feature/**
```
```
tests/Browser/**
```
if present

If adding or changing a controller feature test, load
```
references/tests/Feature/Http/Controllers/README.md
```
first, then the matching action, route, mode, and validation references under that directory.
For nested controller tests, compare against the deepest sibling controller tests before deciding a case is unnecessary. Treat Inertia assertions as backend response contracts for page component names, props, redirects, and flashes/toasts.

阅读最近的
```
AGENTS.md
```
文件及应用指南。
当Laravel Boost可用时，在修改代码前先查阅对应版本的文档。

在生成任何内容前，检查待修改的具体文件及同一区域的同级文件：

```
database/migrations/*
```
```
routes/*.php
```
```
config/*.php
```
```
lang/**/*.php
```
```
bootstrap/*.php
```
```
public/*.php
```
```
database/seeders/*.php
```
根工具PHP及已跟踪的辅助PHP指南
```
app/**
```
```
resources/views/**
```
```
resources/react-email/**
```
```
database/factories/**
```
```
tests/Unit/**
```
```
tests/Integration/**
```
```
tests/Feature/**
```
若存在则检查
```
tests/Browser/**
```

若添加或修改控制器功能测试，请先加载
```
references/tests/Feature/Http/Controllers/README.md
```
，再查看该目录下匹配的动作、路由、模式及验证参考内容。
对于嵌套控制器测试，在判定某测试用例不必要前，先与最深层的同级控制器测试进行对比。将Inertia断言视为后端响应契约，涵盖页面组件名称、属性、重定向及闪现/提示信息。

Reference Skeleton

参考框架

All

references/**

markdown files follow the canonical structure documented in

references/README.md

. Preserve existing pattern coverage, examples, datasets, and snippets while converting real module/entity examples to synthetic placeholders.

所有

references/**

下的Markdown文件均遵循

references/README.md

中记录的标准结构。在将真实模块/实体示例转换为合成占位符时，保留现有模式覆盖范围、示例、数据集及代码片段。

Non-Negotiables

不可协商规则

Preserve concurrent changes. Re-read a file immediately before patching it.
Keep new code aligned to the existing architecture. Do not add base folders, dependencies, or broad abstractions unless the task explicitly needs them.
Use
```
php artisan make:* --no-interaction
```
for Laravel-created files when practical, then rewrite generated output to match local patterns.
Do not add database foreign key constraints when the repository uses schema-planning tools or application-level relationships instead. Use indexed
```
foreignId
```
columns only.
Do not add migration
```
down()
```
methods when existing migrations intentionally omit them.
Do not add
```
$fillable
```
or
```
$guarded
```
on models when the app globally calls
```
Model::unguard()
```
.
Because models are globally unguarded, use
```
$model->update([...])
```
for normal persisted attribute mutations in app-owned code. Do not use
```
forceFill(...)->save()
```
as a mass-assignment workaround.
Every behavioral change needs a focused programmatic test.
Every new test must prove changed behavior, an interface contract, a regression risk, or a changed owner surface. Do not add tests only because an action template contains a similar example.
Name action integration tests after the observable behavior. For the primary create success case, use a direct name such as
```
creates a child record
```
; do not append the parent or owner merely because the persisted row includes its ID. Add a scope qualifier only when that scope is the behavior under test, such as cross-parent isolation or an active-parent guard.
Assert durable database effects with
```
assertDatabaseHas()
```
,
```
assertDatabaseMissing()
```
,
```
assertSoftDeleted()
```
, or
```
assertModelMissing()
```
according to the persistence contract. Do not assert fixture setup; if a test needs a soft-deleted fixture, create it with the factory
```
trashed()
```
state instead of creating an active model and calling
```
delete()
```
. Keep the soft-deleted parent in a local variable for route/login arguments because normal
```
belongsTo
```
queries may filter it out. If a child factory derives ownership through a normal parent query that cannot see trashed rows, pass only the minimum FK/owner IDs needed to create the child under that trashed parent. Use
```
$model->refresh()
```
with
```
expect()
```
only when the test is proving reloaded Eloquent model behavior, such as casts, accessors, relationships, timestamps, or dirty/original state.
Controller feature tests are the exception when the mutation delegates persistence to a Data input-backed action: mock the action and assert the HTTP boundary plus the request-to-input mapping needed by the scenario. For create/store primary success, a required-only payload may assert the required input mapping. For partial update, keep cases partial and assert submitted fields plus request-normalized fields only where relevant. Leave persistence, optional/default behavior, nullable clearing, and side effects to
```
tests/Integration/Actions
```
.
Controller feature tests remain required for delegated mutations because the controller is an entry point. Do not remove controller tests as duplicate only because
```
tests/Integration/Actions
```
covers the internal guard. Keep the controller assertions for authentication, authorization, scoped binding, request validation, action invocation, request-to-input mapping, redirects/toasts, and exception-to-validation mapping.
For delegated destroy or lifecycle actions, keep controller feature tests at the HTTP boundary: mock the action, assert the bound model is passed, and assert exception-to-validation mapping. Do not use one generic mock as a reason to delete concrete route-contract tests for distinct dependency families, such as configuration rows versus operational rows that make deletion invalid. When those cases remain in the controller suite, set up the minimum fixture that names the route scenario, mock the action to throw, and preserve historical active and soft-deleted dependency variants when they protect the route contract. Leave deletion state, transaction internals, and guard truth to
```
tests/Integration/Actions
```
.
Actions must accept only the models, payloads, and independent values that are business inputs to the operation. Do not pass route hierarchy solely to repeat ownership checks already enforced by scoped bindings and policies at the entrypoint.
Do not re-query a model passed to an action solely to prove ownership, existence, or soft-delete state. Query fresh state only when the action owns a transactional guard, lock, or required relationship read.
A parent or owner belongs in the action signature only when the operation needs it as a business input, such as creating a row through that parent. Otherwise derive required business relationships from the target model instead of making callers reconstruct the route hierarchy.
When a controller test mocks a create/store action and the controller needs the returned model for a redirect route, return a persisted factory model with
```
createOne()
```
. Do not set generated route keys such as
```
public_id
```
,
```
slug
```
, or generated codes unless the literal value is asserted. Set only required relationships and the minimum non-conflicting domain attributes needed to let validation reach the mocked action.
Do not put Pest
```
expect()
```
chains inside Mockery argument matchers. Mock callbacks should return booleans and check only the arguments needed for that controller contract.
Keep
```
tests/Integration/Models/**
```
limited to project/system behavior. Use
```
references/tests/Integration/Models/README.md
```
for the canonical boundary and avoid generic Laravel relationship, FK/ID equality, related-model type, or factory/count smoke tests.
Do not create only the most obvious test file. Update related tests when a change alters a related model, resource, controller, action, middleware, console command, or support surface.
Controller feature tests follow the action-first, failure-to-success matrix in
```
references/tests/Feature/Http/Controllers/README.md
```
. Nested routes must cover every scoped binding boundary, including redundant ownership mismatches when a child stores denormalized
```
Workspace
```
or ancestor IDs.
Store/update validation uses public IDs when the form contract exposes public IDs. Convert to internal integer IDs after validation in the controller only when persistence requires it; do not force
```
prepareForValidation()
```
solely to make public IDs fit integer columns.
For Form Request rules that mention server-managed or unknown fields, inspect the application service-provider form-request bootstrap first. The app calls
```
FormRequest::failOnUnknownFields()
```
, so do not add
```
exclude
```
to silently drop submitted input; leave non-contract fields out of
```
rules()
```
.
Prefer database constraints for invariants that PostgreSQL can enforce. Add an explicit lock only for a documented cross-row invariant that cannot reasonably live in the database, and make every competing action lock the same parent row in the same order.
Put web/resource request validation, normalization, and domain validation in Form Requests. Domain guards that require action-owned transactional state or dependent-record checks should live in the action and be mapped by the controller when a sibling action-delegation pattern does that; do not duplicate the same guard in the Form Request. Avoid
```
ValidationException::withMessages()
```
in web controllers unless a live sibling has the same controller-owned domain failure pattern. Current API session controllers may throw validation exceptions for external-token or session-domain failures.
When a controller catches an action-owned domain exception and maps it to validation, the controller test that mocks the action only proves exception-to-validation mapping. Cover the action guard itself in
```
tests/Integration/Actions
```
.
Name controller tests after the observable rejected behavior with verbs such as
```
rejects
```
or
```
prevents
```
; do not name them after the internal exception-to-validation mapping mechanism.

保留并发修改内容。在修改文件前立即重新读取该文件。
保持新代码与现有架构一致。除非任务明确需要，否则不要添加基础文件夹、依赖项或宽泛的抽象层。
实际可行时，使用
```
php artisan make:* --no-interaction
```
创建Laravel生成的文件，然后重写生成的输出以匹配本地模式。
当仓库使用Schema规划工具或应用级关联而非数据库外键约束时，请勿添加数据库外键约束。仅使用带索引的
```
foreignId
```
列。
当现有迁移有意省略
```
down()
```
方法时，请勿添加该方法。
当应用全局调用
```
Model::unguard()
```
时，请勿在模型上添加
```
$fillable
```
或
```
$guarded
```
属性。
由于模型全局无保护，在应用自有代码中使用
```
$model->update([...])
```
进行常规持久化属性变更。请勿使用
```
forceFill(...)->save()
```
作为批量赋值的变通方案。
每一项行为变更都需要针对性的程序化测试。
每一个新测试都必须验证变更后的行为、接口契约、回归风险或变更的所有者范围。不要仅因为动作模板包含类似示例就添加测试。
动作集成测试以可观察的行为命名。对于主要的创建成功场景，使用直接名称如
```
creates a child record
```
；不要仅因为持久化行包含父级或所有者ID就追加父级或所有者名称。仅当作用域是测试的行为对象时才添加作用域限定符，例如跨父级隔离或活跃父级防护。
根据持久化契约，使用
```
assertDatabaseHas()
```
、
```
assertDatabaseMissing()
```
、
```
assertSoftDeleted()
```
或
```
assertModelMissing()
```
断言持久化的数据库影响。不要断言夹具设置；如果测试需要软删除的夹具，请使用工厂的
```
trashed()
```
状态创建，而非创建活跃模型后调用
```
delete()
```
。将软删除的父级保存在局部变量中用于路由/登录参数，因为常规
```
belongsTo
```
查询可能会过滤掉它。如果子工厂通过无法查看软删除行的常规父级查询获取所有权，则仅传递在该软删除父级下创建子级所需的最小FK/所有者ID。仅当测试要验证重新加载的Eloquent模型行为（如转换、访问器、关联、时间戳或脏数据/原始状态）时，才结合
```
expect()
```
使用
```
$model->refresh()
```
。
当变更操作将持久化委托给基于Data输入的动作时，控制器功能测试是例外情况：模拟该动作，并断言HTTP边界以及场景所需的请求到输入的映射。对于创建/存储的主要成功场景，仅含必填项的负载可断言必填输入映射。对于部分更新，保持测试用例为部分更新，并仅在相关情况下断言提交字段及请求规范化字段。将持久化、可选/默认行为、可空字段清空及副作用留给
```
tests/Integration/Actions
```
测试。
对于委托式变更，控制器功能测试仍然是必需的，因为控制器是入口点。不要仅因为
```
tests/Integration/Actions
```
覆盖了内部防护就删除控制器测试，将其视为重复内容。保留控制器断言以验证身份验证、授权、作用域绑定、请求验证、动作调用、请求到输入的映射、重定向/提示信息以及异常到验证的映射。
对于委托式销毁或生命周期动作，控制器功能测试仅关注HTTP边界：模拟动作，断言传递了绑定的模型，并断言异常到验证的映射。不要使用一个通用模拟作为删除不同依赖族（如配置行与使删除无效的操作行）的具体路由契约测试的理由。当这些用例保留在控制器套件中时，设置命名路由场景的最小夹具，模拟动作抛出异常，并保留历史上的活跃和软删除依赖变体（如果它们保护路由契约）。将删除状态、事务内部逻辑及防护真实性留给
```
tests/Integration/Actions
```
测试。
动作仅接受作为操作业务输入的模型、负载及独立值。不要仅为了重复入口点已通过作用域绑定和策略强制执行的所有权检查而传递路由层级。
不要仅为了验证所有权、存在性或软删除状态而重新查询传递给动作的模型。仅当动作拥有事务防护、锁或必需的关联读取时，才查询最新状态。
父级或所有者仅在操作需要将其作为业务输入（如通过该父级创建行）时才出现在动作签名中。否则，从目标模型派生所需的业务关联，而非让调用者重构路由层级。
当控制器测试模拟创建/存储动作且控制器需要返回的模型用于重定向路由时，使用
```
createOne()
```
返回持久化的工厂模型。除非要断言字面量值，否则不要设置生成的路由键如
```
public_id
```
、
```
slug
```
或生成的代码。仅设置必需的关联及让验证能到达模拟动作所需的最小非冲突域属性。
不要在Mockery参数匹配器中放入Pest
```
expect()
```
链。模拟回调应返回布尔值，且仅检查该控制器契约所需的参数。
将
```
tests/Integration/Models/**
```
限制为项目/系统行为。使用
```
references/tests/Integration/Models/README.md
```
作为标准边界，避免通用的Laravel关联、FK/ID相等性、关联模型类型或工厂/计数冒烟测试。
不要仅创建最明显的测试文件。当变更影响到关联模型、资源、控制器、动作、中间件、控制台命令或支持面时，更新相关测试。
控制器功能测试遵循
```
references/tests/Feature/Http/Controllers/README.md
```
中的动作优先、从失败到成功的矩阵。嵌套路由必须覆盖所有作用域绑定边界，包括当子级存储非规范化的
```
Workspace
```
或祖先ID时的冗余所有权不匹配情况。
当表单契约暴露公共ID时，存储/更新验证使用公共ID。仅当持久化需要时，才在控制器验证后转换为内部整数ID；不要仅为了让公共ID适配整数列而强制使用
```
prepareForValidation()
```
。
对于提及服务器管理或未知字段的Form Request规则，请先检查应用服务提供者的表单请求引导代码。应用调用
```
FormRequest::failOnUnknownFields()
```
，因此不要添加
```
exclude
```
来静默丢弃提交的输入；将非契约字段排除在
```
rules()
```
之外。
对于PostgreSQL可以强制执行的不变量，优先使用数据库约束。仅当存在无法合理在数据库中实现的跨行列不变量时，才添加显式锁，并确保所有竞争动作以相同顺序锁定同一父行。
将Web/资源请求验证、规范化及域验证放在Form Requests中。需要动作自有事务状态或依赖记录检查的域防护应放在动作中，当存在同级动作委托模式时由控制器进行映射；不要在Form Request中重复相同的防护。除非现有同级控制器有相同的控制器自有域失败模式，否则避免在Web控制器中使用
```
ValidationException::withMessages()
```
。当前API会话控制器可能会为外部令牌或会话域失败抛出验证异常。
当控制器捕获动作自有域异常并将其映射到验证时，模拟该动作的控制器测试仅验证异常到验证的映射。在
```
tests/Integration/Actions
```
中覆盖动作防护本身。
控制器测试以可观察的拒绝行为命名，使用
```
rejects
```
或
```
prevents
```
等动词；不要以内部异常到验证的映射机制命名。

Reference Map

参考映射

Load only the references needed for the task:

```
references/database/migrations/README.md
```
for migration layout, indexes, route keys, soft deletes, and database inspection.
```
references/database/factories/README.md
```
for factory defaults, relationship factories, states, and after-creating hooks.
```
references/project/README.md
```
for routes, config, localization, bootstrap/public entrypoints, seeders, root tooling PHP, and auxiliary PHP guidance.
```
references/app/README.md
```
for patterns from the application layer under
```
app/
```
.
```
references/app/Actions/README.md
```
for action classes.

references/app/Console/Commands/README.md

for Artisan commands.

```
references/app/Enums/README.md
```
for enums.
```
references/app/Exceptions/README.md
```
for domain exceptions.

references/app/Http/Controllers/README.md

for controllers.

```
references/app/Http/Controllers/lifecycle-resources.md
```
for CRUDdy/resourceful controller naming, activation/deactivation, enable/disable, confirm/unconfirm, session/login/logout, regeneration, and other lifecycle actions.

references/app/Http/Middleware/README.md

for middleware.

```
references/app/Http/Requests/README.md
```
for form requests.
```
references/app/Http/Resources/README.md
```
for JSON resources.
```
references/app/Listeners/README.md
```
for event listeners.
```
references/app/Models/README.md
```
for Eloquent model structure, casts, docblocks, route keys, traits, and relationships.

references/app/Models/Concerns/README.md

for reusable model concerns.

```
references/app/Models/World/README.md
```
for models backed by a non-default reference-data connection.
```
references/app/Notifications/README.md
```
for notifications.
```
references/app/Policies/README.md
```
for policies.
```
references/app/Providers/README.md
```
for service providers.
```
references/app/Support/README.md
```
for support classes.
```
references/app/functions.php.md
```
for global helpers.
```
references/resources/views/README.md
```
for Inertia root Blade shells and hand-authored app views.
```
references/resources/react-email/README.md
```
for React Email templates, Nub commands, export lifecycle, generated Blade views, and mail assets.

Use the path-matched test references before editing or adding tests:

```
references/tests/README.md
```
for suite routing and the complete path map.

references/tests/Pest.md

and

references/tests/TestCase.md

for global Pest helpers and base test behavior.

```
references/tests/.pest/shards.md
```
for shard metadata expectations.
```
references/tests/ArchitectureTest.md
```
for architecture rules.

references/tests/Unit/Enums/README.md

for

tests/Unit/Enums/*Test.php

references/tests/Unit/Models/README.md

for

tests/Unit/Models/*Test.php

references/tests/Integration/Actions/README.md

for

tests/Integration/Actions/*Test.php

references/tests/Integration/Http/Resources/README.md

for

tests/Integration/Http/Resources/*ResourceTest.php

references/tests/Integration/Listeners/README.md

for

tests/Integration/Listeners/*Test.php

references/tests/Integration/Models/README.md

and

references/tests/Integration/Models/Concerns/README.md

for persisted model behavior.

references/tests/Integration/Support/Media/README.md

for media support integration tests.

references/tests/Feature/Console/README.md

for console command feature tests.

references/tests/Feature/Http/Controllers/README.md

for web controller feature tests.

references/tests/Feature/Http/Controllers/Api/README.md

for API controller feature tests.

references/tests/Feature/Http/Controllers/actions/*.md

modes/api-json.md

route-patterns.md

, and

validation/*.md

for controller action matrices.

references/tests/Feature/Http/Middleware/README.md

for middleware feature tests.

references/tests/Feature/Models/Concerns/README.md

for route-binding feature tests on model concerns.

references/tests/migrations/README.md

and

references/tests/testfiles/README.md

for test-only schema and binary/text fixtures.

references/tests/Support/Models/README.md

and

references/tests/TestSupport/README.md

for test-only support utilities.

仅加载任务所需的参考内容：

```
references/database/migrations/README.md
```
：迁移布局、索引、路由键、软删除及数据库检查。
```
references/database/factories/README.md
```
：工厂默认值、关联工厂、状态及创建后钩子。
```
references/project/README.md
```
：路由、配置、本地化、bootstrap/public入口点、种子文件、根工具PHP及辅助PHP指南。
```
references/app/README.md
```
：
```
app/
```
下应用层的模式。
```
references/app/Actions/README.md
```
：动作类。

references/app/Console/Commands/README.md

：Artisan命令。

```
references/app/Enums/README.md
```
：枚举。
```
references/app/Exceptions/README.md
```
：域异常。

references/app/Http/Controllers/README.md

：控制器。

```
references/app/Http/Controllers/lifecycle-resources.md
```
：CRUD式/资源控制器命名、激活/停用、启用/禁用、确认/取消确认、会话/登录/登出、重新生成及其他生命周期动作。

references/app/Http/Middleware/README.md

：中间件。

```
references/app/Http/Requests/README.md
```
：表单请求。
```
references/app/Http/Resources/README.md
```
：JSON资源。
```
references/app/Listeners/README.md
```
：事件监听器。
```
references/app/Models/README.md
```
：Eloquent模型结构、转换、文档块、路由键、 trait及关联。

references/app/Models/Concerns/README.md

：可复用的模型关注点。

```
references/app/Models/World/README.md
```
：基于非默认参考数据连接的模型。
```
references/app/Notifications/README.md
```
：通知。
```
references/app/Policies/README.md
```
：策略。
```
references/app/Providers/README.md
```
：服务提供者。
```
references/app/Support/README.md
```
：支持类。
```
references/app/functions.php.md
```
：全局助手函数。
```
references/resources/views/README.md
```
：Inertia根Blade外壳及手动编写的应用视图。
```
references/resources/react-email/README.md
```
：React Email模板、Nub命令、导出生命周期、生成的Blade视图及邮件资源。

在编辑或添加测试前，使用路径匹配的测试参考内容：

```
references/tests/README.md
```
：套件路由及完整路径映射。

references/tests/Pest.md

和

references/tests/TestCase.md

：全局Pest助手函数及基础测试行为。

```
references/tests/.pest/shards.md
```
：分片元数据要求。
```
references/tests/ArchitectureTest.md
```
：架构规则。

references/tests/Unit/Enums/README.md

：

tests/Unit/Enums/*Test.php

相关内容。

references/tests/Unit/Models/README.md

：

tests/Unit/Models/*Test.php

相关内容。

references/tests/Integration/Actions/README.md

：

tests/Integration/Actions/*Test.php

相关内容。

references/tests/Integration/Http/Resources/README.md

：

tests/Integration/Http/Resources/*ResourceTest.php

相关内容。

references/tests/Integration/Listeners/README.md

：

tests/Integration/Listeners/*Test.php

相关内容。

references/tests/Integration/Models/README.md

和

references/tests/Integration/Models/Concerns/README.md

：持久化模型行为。

references/tests/Integration/Support/Media/README.md

：媒体支持集成测试。

references/tests/Feature/Console/README.md

：控制台命令功能测试。

references/tests/Feature/Http/Controllers/README.md

：Web控制器功能测试。

references/tests/Feature/Http/Controllers/Api/README.md

：API控制器功能测试。

references/tests/Feature/Http/Controllers/actions/*.md

、

modes/api-json.md

、

route-patterns.md

及

validation/*.md

：控制器动作矩阵。

references/tests/Feature/Http/Middleware/README.md

：中间件功能测试。

references/tests/Feature/Models/Concerns/README.md

：模型关注点的路由绑定功能测试。

references/tests/migrations/README.md

和

references/tests/testfiles/README.md

：仅用于测试的Schema及二进制/文本夹具。

references/tests/Support/Models/README.md

和

references/tests/TestSupport/README.md

：仅用于测试的支持工具。

Completion Checklist

完成检查清单

Before finalizing:

New migration matches the local style and avoids unsupported rollback/FK patterns.
New or changed model has typed relationships, casts, docblock properties, and the expected route-key/public-id behavior.
Factory can create a valid row with realistic defaults and coherent relationship ownership.
```
resources/views
```
shell changes preserve Inertia head/app slots, Vite entrypoints, font directives, locale/html metadata, and production/authenticated third-party scripts.
```
resources/react-email
```
changes keep source templates under
```
resources/react-email/mail
```
, use Nub commands, and treat exported Blade views/assets as generated output.
Tests are placed in the correct suite and cover every touched surface: unit-level configuration/pure logic, integration-level persisted behavior/resources/support, feature-level HTTP/console/middleware behavior, and browser coverage when real browser UX is touched.
Related model/resource/controller tests are updated when system behavior or serialized contracts change; do not add paired model relationship tests just to prove Laravel relationship wiring.
Controller coverage was checked against live nested siblings, not only action templates. If a nested child stores redundant
```
Workspace
```
/ancestor ownership, the controller tests include a same-parent mismatched-ownership
```
404
```
case and list actions exclude those records.
Run the smallest relevant tests, for example:

bash

php artisan test --compact tests/Unit/Models/<Model>Test.php tests/Integration/Models/<Model>Test.php
php artisan test --compact tests/Integration/Http/Resources/<Resource>Test.php
php artisan test --compact tests/Feature/Http/Controllers/<Controller>Test.php

If PHP files changed, run:

bash

vendor/bin/pint --dirty --format agent

最终确定前，请检查：

新迁移符合本地风格，避免不支持的回滚/FK模式。
新模型或修改后的模型具有类型化关联、转换、文档块属性及预期的路由键/公共ID行为。
工厂能够使用真实默认值及连贯的关联所有权创建有效行。
```
resources/views
```
外壳变更保留了Inertia头部/应用插槽、Vite入口点、字体指令、区域设置/HTML元数据以及生产环境/已认证第三方脚本。
```
resources/react-email
```
变更将源模板保留在
```
resources/react-email/mail
```
下，使用Nub命令，并将导出的Blade视图/资源视为生成输出。
测试放置在正确的套件中，覆盖所有涉及的层面：单元级配置/纯逻辑、集成级持久化行为/资源/支持、功能级HTTP/控制台/中间件行为，以及当涉及真实浏览器UX时的浏览器覆盖。
当系统行为或序列化契约变更时，更新关联的模型/资源/控制器测试；不要仅为了验证Laravel关联 wiring而添加配对的模型关联测试。
控制器覆盖范围已与现有嵌套同级进行核对，而非仅依赖动作模板。如果嵌套子级存储冗余的
```
Workspace
```
/祖先所有权，控制器测试需包含同父级所有权不匹配的
```
404
```
用例，且列表动作需排除这些记录。
运行最小相关测试，例如：

bash

php artisan test --compact tests/Unit/Models/<Model>Test.php tests/Integration/Models/<Model>Test.php
php artisan test --compact tests/Integration/Http/Resources/<Resource>Test.php
php artisan test --compact tests/Feature/Http/Controllers/<Controller>Test.php

若PHP文件有变更，运行：

bash

vendor/bin/pint --dirty --format agent