bagisto-package-development

Bagisto 中的包开发

Bagisto 包是在 packages/Webkul/<Name>/ 下的独立 Laravel 模块。 核心包采用一套共享布局，但只选用所需部分 — 请复制最接近的现有包，而不是搭建通用的 Laravel 包。

参考文件 — 仅加载当前任务所需的文件

文件	何时加载
core.md	创建包时 — 目录布局、composer.json、提供程序、Concord 注册
data-layer.md	迁移、模型、契约、代理、仓库
ui.md	路由、控制器、Blade 视图
features.md	管理菜单、ACL、系统配置

包的结构

packages/Webkul/<Name>/src/
├── Config/           # system.php, admin-menu.php, acl.php
├── Contracts/        # one interface per model
├── Database/         # Migrations/, Seeders/, Factories/
├── DataGrids/        # admin listings
├── Http/Controllers/ # separate Admin/ and Shop/
├── Models/           # Eloquent models + Proxy classes
├── Providers/        # <Name>ServiceProvider + ModuleServiceProvider
├── Repositories/     # all database access
├── Resources/        # views/, lang/{23 locales}/, assets/
└── Routes/           # web.php (api.php for API routes)

大多数包只包含其中一部分，这是有意为之。 只有 Providers/ 是通用的。在核心包中，大约有 25 个包含 Contracts/Models/Repositories，14 个包含 Config/，11 个包含 Http/Controllers/，8 个包含 Routes/ — 同时具备全部三种 UI 组件的少数包是 Admin、Shop 和支付网关（Stripe、PayU、 Razorpay、PayGlocal、PhonePe）。

像 Category、CartRule、CMS 或 Marketing 这样的领域包仅包含 数据层 — 契约、模型和仓库。其管理界面位于 Admin，店面页面位于 Shop。除非某项功能确实拥有自己的路由（如支付网关）， 否则不要在这些包中添加 Routes/ 或 Http/Controllers/。决定需要哪些目录之前，请先检查最接近的现有包。

不容妥协的规则

• 双重注册。 每个包都要注册两次：在 bootstrap/providers.php 中注册主 ServiceProvider，并在 config/concord.php 中注册 ModuleServiceProvider。漏掉任何一个都会导致包只加载一半，且难以诊断。参见 core.md。
• 模型由三部分组成。 每个实体都由一个契约、一个实现该契约的模型，以及一个代理组成。仓库从 model() 返回 契约，跨包类型提示使用 代理 — 这样无需编辑核心代码即可替换模型。参见 data-layer.md。
• 文档块、成员顺序、注释、仓库规则和翻译 均由 bagisto-coding-standards 技能负责。它们适用于每个 Bagisto 文件，而不仅是包，并且是代码审查中最常见的拒绝原因。
• 修复你改动的内容。 你编辑的文件中任何预先存在的违规都由你负责： 检查整个类的成员顺序和文档块，而不只是你新增的代码行。

相关技能

• bagisto-coding-standards — 文档块、成员顺序、注释、仓库访问、 本地化。处理任何 PHP 代码时，请与本技能一同加载。
• bagisto-datagrid-development — 管理端列表页。features.md 概述了 DataGrid；该技能负责列、筛选器、操作、导出和安全规则。
• bagisto-coding-standards — 还包括 Blade 层：任何包中的任意 .blade.php 文件。
• bagisto-pest-testing / bagisto-playwright-testing — 为你构建的内容编写测试。
• bagisto-change-verification — 完成前的验证关卡。

必需子技能： 宣布任何更改完成之前，请使用 bagisto-change-verification。