aureuserp-plugin-builder

插件构建器

遵循此工作流，构建与现有 plugins/webkul/* 模块完全一致的插件。

工作流

1. 首先阅读 references/plugin-patterns.md。
2. 检查目标插件及其最接近的同级模块（通常是 purchases、sales、projects、website、accounts）。
3. 首先实现或调整服务提供者（*ServiceProvider），使用 PackageServiceProvider 和 Package 链式调用。
4. 实现或调整插件类（*Plugin），以支持面板感知注册（admin、customer）。
5. 确保包的 composer 配置正确（composer.json 中的 PSR-4、extra.laravel.providers、插件工厂和 Seeder 命名空间）。
6. 在 config/filament-shield.php 中注册 ACL 接口。
7. 在 src/Policies 下添加或调整策略，确保生成的权限能够正确解析。
8. 当需要功能标志或配置时，添加设置迁移、设置类和设置页面。
9. 根据面板和模块范围添加仪表板、页面、组件、集群和资源。
10. 使用 HasTableViews 和 PresetView 为列表或管理页面添加表格视图。
11. 按照插件语言文件夹约定和嵌套键结构添加或更新翻译。
12. 使用安装命令验证安装和权限生命周期。

必需约定

• 每个插件服务提供者都要扩展 Webkul\PluginManager\PackageServiceProvider。
• 使用 Package 的链式方法配置包元数据： name、hasViews、hasTranslations、hasRoute/hasRoutes、hasMigrations、runsMigrations、hasSettings、runsSettings、hasSeeder、hasDependencies、hasInstallCommand、hasUninstallCommand、icon。
• 在以下两个位置添加安装依赖： ->hasDependencies([...]) 和安装命令中的 ->installDependencies()。
• 使用插件安装命令模式： ->hasInstallCommand(fn (InstallCommand $command) => $command->installDependencies()->runsMigrations()->runsSeeders()) （如果插件没有 Seeder，则相应调整）。
• 使用 Panel::configureUsing(fn (Panel $panel) => $panel->plugin(YourPlugin::make())); 将插件注册到 Filament。
• 在插件类中使用安装状态控制插件注册： if (! Package::isPluginInstalled($this->getId())) { return; }。
• 确保插件包的 composer.json 包含： autoload.psr-4 中的插件命名空间、extra.laravel.providers 中的服务提供者条目，以及使用到的插件数据库工厂和 Seeder 命名空间。
• 对于管理端和前端分离的情况，在 register(Panel $panel) 中使用面板条件： $panel->when($panel->getId() == 'admin', ...) 和/或 ... == 'customer'。
• 从特定面板的文件夹中发现 Filament 组件： discoverResources、discoverPages、discoverClusters、discoverWidgets。
• 在 config/filament-shield.php 中为资源和页面注册 ACL 管理或排除项。
• 确保 RoleResource/Shield 流程与 PluginManager\PermissionManager 中的插件键命名兼容。
• 使用 Spatie Laravel Settings 管理设置： 设置迁移位于 database/settings/*，设置类位于 src/Settings/*，需要时将设置 UI 实现为 SettingsPage。
• 在列表或管理页面上使用表格视图： use HasTableViews; 并实现 getPresetTableViews(): array，返回 PresetView 条目。
• 在 resources/lang/en 下遵循插件翻译结构，并按 UI 界面使用嵌套键（navigation、form.sections、table.columns、table.filters、infolist.sections、actions、notifications）。

管理面板 + 前台面板设置

当插件需要同时使用两个面板时，参照 purchases、website 和 blogs：

• 按面板组织 Filament 文件夹： src/Filament/Admin/... 和 src/Filament/Customer/...。
• 在插件的 register() 中：
• 在 customer 条件下配置客户面板的资源/页面/集群/小组件。
• 在 admin 条件下配置管理面板的资源/页面/集群/小组件。
• 添加面板专属的导航项（例如设置快捷方式），并添加可见性检查。
• 如果客户身份验证体验是自定义的（例如 website），请在插件注册时配置面板身份验证页面。
• 对于前台/客户体验，还需确保插件的 routes/web.php、前端视图和 Livewire 组件与面板行为保持一致（当模块提供面向客户的页面时）。

翻译约定

• 将插件翻译根目录保留在 plugins/<vendor>/<plugin>/resources/lang/en。
• 在翻译路径中映射 Filament 的位置： filament/resources/...、filament/admin/...、filament/customer/...、filament/clusters/...、filament/pages/...、filament/widgets/...，以及需要时的 models、enums 和顶层 app.php。
• 明确保留资源/页面翻译文件的布局。例如：
• resources/lang/en/filament/resources/product.php（资源级标签）
• resources/lang/en/filament/resources/product/pages/create-product.php
• resources/lang/en/filament/resources/product/pages/edit-product.php
• resources/lang/en/filament/resources/product/pages/list-products.php
• resources/lang/en/filament/resources/product/pages/view-product.php
• 对于管理/客户面板拆分，将路径加在面板路径下：
• resources/lang/en/filament/admin/...
• resources/lang/en/filament/customer/...
• 文件名使用 kebab-case，并与资源/页面/操作名称保持一致。
• 优先使用深层嵌套、结构清晰的数组，按 UI 界面分组：
• navigation.title、navigation.group
• form.sections.<section>.title
• form.sections.<section>.fieldsets.<fieldset>.title
• form.sections.<section>.fields.<field>.label|helper-text
• table.columns、table.groups、table.filters
• table.record-actions.<action>.notifications.<state>.title|body
• table.toolbar-actions.<action>.notifications.<state>.title|body
• table.empty-state.heading|description
• infolist.sections.<section>.entries.<entry>.label|helper-text
• 统一键名拼写（使用 filters，而不是 fileters）。
• 保持翻译键稳定，并通过 __('plugin::path.to.key') 在代码中使用。
• __() 用法示例：
• 资源标签：__('products::filament/resources/product.navigation.title')
• 页面标题：__('products::filament/resources/product/pages/create-product.title')
• 字段标签：__('products::filament/resources/product.form.sections.general.fields.name')

扩展基础资源和模型

当基础模块已定义领域行为时，优先扩展而不是重复实现。

• 扩展源插件中的基础 Filament 资源（常见于 accounting、invoices、sales、purchases、contacts、recruitments）。
• 子资源仅处理差异：集群分配、页面映射、少量架构/表格覆盖以及额外操作。
• 对于模型，遵循插件本地模型命名空间和现有 Trait 约定（HasFactory、软删除、可排序，以及适用时的权限 Trait）。

ACL、角色和权限生命周期

• 在插件的 config/filament-shield.php 中定义插件资源/页面权限范围。
• 更新集群/页面排除项，确保只生成预期的权限键。
• 确保策略方法与预期的权限键相匹配。
• 依靠安装生命周期重新生成/同步权限（插件安装命令和 ERP 安装流程）。
• 更改 ACL 范围时，通过安全角色管理 UI/逻辑验证角色权限分配。

设置、仪表盘和表格视图

• 设置：
• 在 database/settings 中添加设置迁移。
• 添加继承自 Spatie\LaravelSettings\Settings 的设置类。
• 添加继承自 Filament\Pages\SettingsPage 的设置页面（通常归入 settings 集群）。
• 仪表盘／页面／小组件：
• 在自定义仪表盘／页面上使用 page shield traits。
• 通过仪表盘页面的 getWidgets()/getHeaderWidgets() 注册小组件组。
• 将页面／小组件放在适用于相应面板的文件夹中。
• 表格视图：
• 将 HasTableViews 添加到列表／管理页面。
• 使用 PresetView::make(...)->modifyQueryUsing(...) 定义命名预设标签页。
• 在适用的情况下使用收藏／默认预设。

验证清单

1. 插件会显示在插件管理器中，并通过 <plugin>:install --no-interaction 安装。
2. 依赖项会按正确顺序自动安装。
3. 管理员和／或客户面板组件只会显示在指定面板中。
4. Shield 权限包含新增资源／页面，并排除指定的集群／页面。
5. 策略可正常解析，UI 操作遵循授权规则。
6. 设置可持久保存，设置页面可正常加载。
7. 仪表盘页面／小组件正常渲染，且权限不会出现回退。
8. 表格预设视图会应用预期的查询行为。