unopim-plugin-development

UnoPim 插件开发

在 packages/Webkul/{ModuleName}/ 下构建一个独立的 Concord 包——功能模块或第三方连接器（Shopify、Shopware 或任何 REST API）。当前的连接器参考实现是 packages/Webkul/AiAgent；如果此处的模板与该包不一致，以该包为准。

参考文件——仅加载当前阶段所需的文件

文件	何时加载
quickstart.md	开始新模块时——第 1 天的有序检查清单
package-structure.md	目录布局、composer.json、服务提供者、配置合并、迁移
backend.md	模型、契约、仓库、事件、Octane 安全绑定
credentials.md	凭据存储、静态加密、历史记录/审计、连接测试端点
http-client.md	cURL ApiClient、身份验证策略、SSRF 防护、容器绑定
admin-ui.md	Blade 视图——组件、主题令牌、CRUD 概述
crud-patterns.md	管理后台 CRUD 结构——保存栏、创建弹窗、面包屑、页面骨架
acl-security.md	ACL 覆盖范围、FormRequest 授权、上传、CSRF、密钥
mapping.md	连接器的属性映射界面

必需子技能： 所有管理后台列表页面均使用 unopim-datagrid。 必需子技能： Exporter、Importer 和 Validator 类均使用 unopim-data-transfer。 必需子技能： 声明任何更改已完成前，使用 unopim-verify。

关键约定（详情和示例见参考文件）

• 目标为 Laravel 13 / PHP 8.4：构造函数属性提升、显式返回类型、模型使用 #[Fillable]/#[Table]/#[Hidden] 属性以及 casts(): array 方法。
• 提供者在 bootstrap/providers.php 中注册——config/app.php 中没有 providers 数组。
• 菜单配置合并到 'menu.admin' 键，绝不能合并到 'menu'——管理侧边栏只读取 config('menu.admin')，因此合并到 'menu' 的模块永远不会显示。
• 插件包将迁移文件放在根目录下的 Database/Migration/（单数）中；核心包使用 src/Database/Migrations/（复数）。表名直接书写——前缀来自 env('DB_PREFIX', '')，其默认值为空。
• 路由中间件仅使用 ['admin']。ACL 按路由名称采用失败放行策略：每个写入路由（store、update、destroy、mass_*、test-connection）都必须出现在 Config/acl.php 中，否则任何已登录的管理员都可以调用它。请参阅 acl-security.md。
• 历史记录/审计模型必须实现其模块契约、PresentableHistoryInterface（包含 getPresenters()）以及 OwenIt 的 Auditable 契约，使用 HistoryTrait，并定义 $historyTags——遗漏其中任何一项都会在类加载时或首次保存时触发致命错误。
• 静态存储的密钥必须同时使用 'encrypted' cast、#[Hidden] 和 $auditExclude。 仅设置 $auditExclude 会以明文存储。
• 连接器 HTTP 必须使用原生 cURL——绝不能使用 Guzzle 或 Http facade。有状态的客户端使用 scoped() 绑定，绝不能使用 singleton()（此技术栈运行在 Octane 上）。
• 本地化文件位于 Resources/lang/{locale}/，其中 33 种语言环境均以 en_US 为规范格式——单独的 en/ 目录不会加载。
• 方法体、数组字面量、路由组或 Blade 标记中不得包含注释。方法 PHPDoc 应为单行祈使句摘要。
• 不得硬编码面向用户的字符串——所有标签、消息和占位符均使用 trans('{module}::app.…')。