olakunlevpn-filament-skills

Filament PHP v5 编码规范

用于构建生产级 Filament v5 管理面板的综合规范。Filament v5 要求 PHP 8.3+、Laravel 13+、Livewire 4+、Tailwind CSS 4.1+。请严格遵循这些规则。详细代码示例请参阅 REFERENCE.md。

适用范围

适用于所有 Filament 工作：资源、表单、表格、信息列表、操作、组件、仪表板、面板、关联管理器、导入/导出、自定义页面、多租户、测试和部署。

---

1. 项目结构

目录布局

• 按领域分组并使用复数名称：Resources/Shop/、Resources/Blog/、Resources/HR/
• 资源放在复数目录中：Resources/Shop/Products/ProductResource.php
• 将架构提取到独立文件：Resources/Shop/Products/Schemas/ProductSchema.php
• 将表格提取到独立文件：Resources/Shop/Products/Tables/ProductsTable.php
• 多个面板：Providers/Filament/AdminPanelProvider.php、AppPanelProvider.php

资源复杂度等级

• 简单（ManageRecords）——模态 CRUD、单页、无关联管理器
• 标准（List+Create+Edit）——分离页面、基础 CRUD
• 完整（List+Create+Edit+View）——子导航、关联管理器、组件

命名规则

• 资源目录使用复数：Products/，而非 Product/
• 文件名与类名一致：ProductResource.php
• Slug 使用 kebab-case：order-items
• 命名空间与目录路径完全一致

---

2. 资源架构

委托模式

资源委托给专用的 Schema 和 Table 类。资源类应保持精简。

class ProductResource extends Resource
{
    protected static ?string $model = Product::class;
    protected static ?string $slug = 'products';
    protected static ?string $recordTitleAttribute = 'name';
    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedShoppingBag;
    protected static ?string $navigationGroup = 'Shop';
    protected static ?int $navigationSort = 1;

    public static function form(Schema $schema): Schema
    {
        return ProductSchema::configure($schema);
    }

    public static function table(Table $table): Table
    {
        return ProductsTable::configure($table);
    }
}

关键规则

• 始终为全局搜索设置 $recordTitleAttribute
• 导航图标始终使用 Heroicon::Outlined*（导航中不要使用 Solid）
• 使用 Heroicon 枚举，绝不使用字符串图标名称
• 所有操作仅从 Filament\Actions\* 命名空间导入
• 表格方法：使用 recordActions() 而非 actions()，使用 groupedBulkActions() 而非 bulkActions()

---

3. 表单设计

• 顶层使用 $schema->components([...])，并用 Section 包裹
• Section 来自 Filament\Schemas\Components\Section
• 布局组件（Section、Grid、Tabs、Flex）来自 Filament\Schemas\Components\*
• Slug 字段：->live(onBlur: true)，仅在创建时使用 Operation::Create，并使用 ->disabled()->dehydrated()
• 带关联的 Select：始终使用 ->searchable() 和 ->preload()
• 文件上传：设置 ->disk()、->directory()、->visibility()
• 条件逻辑使用 Operation 枚举：Operation::Create、Operation::Edit
• 使用 Repeater 处理具有计算字段的行项目
• 复杂的多分区表单使用 Tabs
• 所有文本标签都通过语言文件定义，绝不硬编码

---

4. 表格设计

• 列：TextColumn、IconColumn（布尔值）、BadgeColumn（枚举）、ImageColumn
• 可切换列：对不太重要的列使用 ->toggleable(isToggledHiddenByDefault: true)
• 筛选器：SelectFilter、TernaryFilter（布尔值），日期范围使用自定义筛选器
• 使用 ActionGroup 包装操作：将 View、Edit、Delete 分组
• 批量操作通过 groupedBulkActions() 实现：删除、导出、状态变更
• 工具栏操作通过 toolbarActions() 实现：创建、导入、导出
• 默认排序：->defaultSort('created_at', 'desc')
• 可搜索列：对关键文本列使用 ->searchable()
• 金额：使用 ->money('USD')，或使用 ->formatStateUsing() 自定义格式

---

5. 信息列表（查看）模式

• 条目类型：TextEntry、IconEntry（布尔值）、ImageEntry、BadgeEntry（枚举）
• 紧凑显示时使用行内标签：->inlineLabel()
• 富文本内容：对格式化文本使用 ->prose()->markdown()
• 复杂的查看页面使用 Tabs
• 查看页面上的上下文操作需设置可见性条件
• 元数据使用键值条目

6. 枚举设计系统

每个状态／类型／类别都使用实现 Filament 契约的 PHP 8.1 字符串支持枚举：

• HasLabel -- 显示名称
• HasColor -- 语义颜色
• HasIcon -- Heroicon

语义颜色： success（正向）、danger（负向）、warning（警示）、info（新内容）、primary（特殊）、gray（中性）

命名： Case 名称使用 PascalCase，支持值使用 snake_case。在模型中进行转换：'status' => OrderStatus::class

---

7. 操作与通知

• 所有操作：Filament\Actions\Action、Filament\Actions\CreateAction 等
• 切勿从 Filament\Tables\Actions\* 导入（已在 v5 中移除）
• 操作模态框使用 ->schema()，而不是 ->form()
• ActionGroup 排序：View、Edit、Delete（最常用的放在前面）
• 通知：Notification::make()->title()->success()->send()
• 操作后刷新：$this->dispatch('$refresh') 或返回重定向
• 批量操作：对于受策略控制的批量操作，使用 ->authorizeIndividualRecords()

---

8. 关系管理器

• 标准方式：扩展 RelationManager，定义 form() 和 table()
• 替代方式：对于复杂关系，使用 ManageRelatedRecords 页面
• 操作位置：headerActions（创建）、recordActions（逐行）、groupedBulkActions（选中项）
• 同一关系出现在多个位置时，在各资源间复用
• 为相关记录设置默认排序

---

9. 小组件与仪表板

• StatsOverview：多个统计卡片、可选的内嵌图表、描述和图标
• 图表小组件：折线图、柱状图、圆环图、饼图 -- 扩展 ChartWidget
• 延迟加载：默认开启（$isLazy = true）
• 轮询：默认间隔为 5s，可通过 $pollingInterval 自定义，或设为 null 以禁用
• 仪表板筛选器：实现 HasFiltersForm，以支持可筛选的仪表板
• 资源页面小组件：使用 ExposesTableToWidgets trait
• 通过 $sort 属性设置小组件排序

---

10. 多租户

• 面板：在 PanelProvider 中使用 ->tenant(Team::class)
• 用户模型：实现 HasTenants，并提供 getTenants() 和 canAccessTenant()
• 对所有资源自动限定查询范围（通过 $isScopedToTenant = false 退出限定）
• **重要：**表单选择项不会自动限定范围——添加带有 Filament::getTenant() 的 modifyQueryUsing
• 验证：租户相关规则使用 ->scopedUnique() 和 ->scopedExists()
• 基于域名：->tenantDomain('{tenant:slug}.example.com')
• 基于路径并使用 slug：->tenant(Team::class, slugAttribute: 'slug')
• 注册页面：扩展 RegisterTenant
• 个人资料页面：扩展 EditTenantProfile

---

11. 多面板架构

• 每个面板（admin、app、vendor）使用独立的 PanelProvider
• 每个面板都有自己的身份验证、资源、页面、小组件、中间件和主题
• FilamentUser::canAccessPanel() 控制各面板的访问权限
• 通过 Plugin 类或静态辅助方法共享配置
• 使用 Filament::setCurrentPanel('app') 测试非默认面板

---

12. 自定义页面与集群

• 自定义页面：php artisan make:filament-page Settings
• 访问控制：canAccess() 方法
• 页眉操作、页眉／页脚小组件，以及小组件数据传递
• 集群：将相关页面分组到子导航下
• 使用 SubNavigationPosition::Top 设置水平标签页
• 资源子导航：使用 getRecordSubNavigation() 创建 View/Edit/Related 页面

---

13. 测试（Pest + Livewire）

• 通过 livewire(PageClass::class) 测试——页面是 Livewire 组件
• 身份验证：在 beforeEach 中使用 actingAs(User::factory()->create())
• 多租户：Filament::setTenant($team) + Filament::bootCurrentPanel()
• 多面板：Filament::setCurrentPanel('admin')

关键测试模式：

• 列表：->assertCanSeeTableRecords()、->searchTable()、->sortTable()、->filterTable()
• 创建：->fillForm([...])->call('create')->assertHasNoFormErrors()->assertNotified()
• 编辑：->assertSchemaStateSet([...])->fillForm([...])->call('save')
• 操作：->callAction(TestAction::make('send')->table($record))
• 批量操作：->selectTableRecords($ids)->callAction(TestAction::make('delete')->table()->bulk())
• 关联关系：livewire(RelationManager::class, ['ownerRecord' => $record, 'pageClass' => EditPage::class])

---

14. 导入与导出

• 导出器：定义 ExportColumn，放在 app/Filament/Exports/ 中
• 导入器：使用带有规则、示例、类型转换和关联关系解析的 ImportColumn
• 操作：在工具栏中使用 ExportAction::make()、ImportAction::make()
• 记录解析：使用 firstOrNew、new Model，或返回 null 以跳过

---

15. 授权

• 生产环境（APP_ENV != local）必须实现 FilamentUser 接口
• 自动发现模型策略：viewAny、create、update、delete、restore、forceDelete、reorder
• 跳过授权：$shouldSkipAuthorization = true
• 批量操作授权：->authorizeIndividualRecords()
• 按面板控制访问：使用带面板 ID 检查的 canAccessPanel(Panel $panel)

---

16. 性能与部署

生产环境：

php artisan optimize
php artisan filament:optimize

面板配置：

• 使用 ->spa() 启用 SPA 模式
• 使用 ->unsavedChangesAlerts() 保护数据
• 使用 ->databaseTransactions() 确保操作安全

组件： 默认延迟加载。设置轮询间隔，或设为 null 以禁用。使用 wire:init 延迟加载 API 数据。

切勿在本地开发环境运行 filament:optimize——新组件将无法被发现。

Tailwind v4： 通过 Vite 插件进行基于 CSS 的配置。没有 tailwind.config.js。使用 @source 指令。

---

17. Livewire 4 功能（通过 Filament v5）

• Islands：使用 @island 指令创建隔离的重新渲染区域
• 异步操作：使用 #[Async] 属性执行即发即弃操作（分析、日志记录）
• wire:model.deep：依赖子元素事件冒泡时必须使用
• wire:sort：内置拖放功能，无需外部包
• 并行请求：wire:model.live 不再阻塞
• 必须使用自闭合标签：<livewire:component />

---

18. 严格规则

• 切勿发布 Blade 视图。使用带 fi- 前缀的 CSS 钩子。
• 切勿硬编码品牌名称、徽标或货币。使用动态设置。
• 所有面向用户的文本都必须通过语言文件和翻译键提供。
• 每个资源都必须设置 $recordTitleAttribute。
• 操作弹窗：使用 ->schema()，不要使用 ->form()
• 表格：使用 recordActions()，不要使用 actions()；使用 groupedBulkActions()，不要使用 bulkActions()
• Schema：在顶层使用 $schema->components([...])
• 图标：仅使用 Heroicon:: 枚举，切勿使用字符串名称
• 操作类型：使用 Operation::Create、Operation::Edit，切勿进行字符串比较

总结检查清单

• 资源将工作委托给 Schema 和 Table 类
• 每个资源都已设置 $recordTitleAttribute
• 所有图标都使用 Heroicon:: 枚举；导航图标使用 Outlined
• 所有操作都来自 Filament\Actions\* 命名空间
• 表格使用 recordActions()、groupedBulkActions()、toolbarActions()
• 枚举实现 HasLabel、HasColor、HasIcon，并使用语义化颜色
• 表单选择项可搜索且已预加载
• 多租户表单选择项需手动限定到对应租户
• 已实现 FilamentUser 接口及 canAccessPanel()
• 每个资源都配置了用于授权的模型策略
• 生产环境部署脚本中包含 filament:optimize
• 测试使用 livewire()，多租户场景使用 Filament::setTenant()
• 没有硬编码文本——所有文本都通过语言文件提供
• 没有已发布的 Blade 视图——仅使用 CSS 钩子