bagisto-api-develop

开发 Bagisto API 包

当你在 bagisto-api 包（packages/Webkul/BagistoApi，命名空间 Webkul\BagistoApi）内部工作时，请参考本指南，包括安装或移除该包、添加或修改端点／资源，或修复包行为。本指南列出了权威规范所在位置、必须遵守的规则，以及详细参考文档的入口。

重要——仅在收到请求时安装／移除

安装或移除该包绝不能作为自动操作。发现包文件、composer.json 或 Bagisto 项目，并不代表你应该安装、重新安装、优化或卸载任何内容。只有在客户端明确提出请求时，才执行安装（reference/install.md）或移除（reference/uninstall.md）；安装前，先询问他们想用 Composer（稳定版） 还是 手动（最新版本） 方法。

权威来源——请先阅读

该包附带完整文档。编写代码前，请先阅读相关部分——几乎每个菜单／资源都已明确规定其行为、验证、事件和特殊情况：

来源	内容
CLAUDE.md（包根目录）	权威约定 + 涵盖每个端点的覆盖表，其中列出了各资源的决策和特殊情况。处理资源时，请先阅读此文件。
docs/superpowers/specs/	较大型功能的设计规范。
CHANGELOG.md	已发布的面向使用者的变更，位于 [Unreleased] 下。
PERFORMANCE.md	缓存／IRI／架构构建性能说明。
GitHub bagisto/bagisto-api	标准代码——请复制最接近的现有资源，而不是从头编写模式。
https://api-docs.bagisto.com（+ /llms.txt）	面向使用者的请求／响应结构 + 完整端点索引。

**规则：不要自行设想 CLAUDE.md 已规定的行为。**先在其中搜索相应资源／菜单。

参考索引——按需打开

主题	参考文件	适用场景
安装该包	reference/install.md	客户端要求安装／设置 API 时
移除该包	reference/uninstall.md	客户端要求移除／卸载该包时
文件放置位置	reference/structure.md	添加任何文件；查找正确目录和基类时
接口、传输方式、资源声明	reference/api-structure.md	设计新端点；了解 5 文件模式和功能接口时
编码规范 + 检查清单	reference/conventions.md	按规则编写／审查资源时
易踩的坑	reference/precautions.md	发布前——那些会悄无声息导致问题的事项
API 会／不会做什么	reference/limitations.md	确定功能范围；判断“是否支持此功能？”时
测试 + 缓存周期	reference/testing.md	运行／添加测试；执行缓存命令时

5 文件模式（每个资源的骨架）

Model（#[ApiResource]——REST + GraphQL 操作 + OpenAPI 区块）→ DTO（类型化输入）→ Provider（读取路径）→ Processor（写入路径）→ lang（src/Resources/lang/en/app.php）。Storefront 资源位于 src/ 下；admin 资源位于 src/Admin/ 下。请在 BagistoApiServiceProvider::register() 中为每个 Provider／Processor 添加标签——未添加标签的对象会被静默跳过（404／数据错误）。详见 reference/api-structure.md 和 reference/structure.md。

两项不可妥协的要求

1. REST 改动可能破坏 GraphQL——两者共用同一个 Provider/Processor。始终先运行该资源的 GraphQL 测试，再运行 REST 测试，并确认测试通过后再认为改动已完成。这是最重要的一条规则。
2. **与 Bagisto 管理面板保持一致，而非超出其功能范围。**与管理界面的行为保持一致；核心功能缺失时，应通过明确的错误提示阻止操作，而不是只扩展一半。请参阅 reference/limitations.md。

其他所有内容——完整清单、按风险排序的常见陷阱，以及测试和缓存命令——都在上述参考资料中。请打开查看，不要自行猜测。