aureuserp-api-builder

API 构建器

按照此工作流生成符合 AureusERP 插件通用约定的 API。

工作流

1. 阅读约定参考文档：references/api-conventions.md。
2. 检查目标插件模块（模型、现有策略、现有路由，以及 Filament 资源／页面）。
3. 在生成 API 类之前，先分析 Filament 资源：

• 根据 Filament 页面和操作（创建／编辑／查看／列表及自定义操作）梳理工作流／状态转换
• 提取 Filament 表单／组件中的验证规则，包括条件必填项和嵌套重复器
• 仅根据用户可编辑的字段构建请求负载字段定义（排除只读、计算得出或由系统管理的字段）
• 如果模块扩展了其他插件中的资源，识别其父级 Filament 资源／类
• 识别可选插件依赖项：检测仅在安装其他插件时才存在的列、关系或功能（检查使用 Schema::hasTable 或 Schema::hasColumn 保护的条件迁移）

4. 按以下顺序实现 API 文件：

• 在 routes/api.php 中添加路由条目
• 在 src/Http/Controllers/API/V1 中添加控制器
• 在 src/Http/Requests 中添加表单请求
• 在 src/Http/Resources/V1 中添加资源
• 使用软删除时，添加策略方法（restore、forceDelete）

5. 如果 Filament／API 类扩展了其他插件中的父类，请在生成的 API 类中镜像此继承关系：

• 如果父插件提供了针对相同 API 概念的请求类，生成的请求类必须继承该类
• 如果父插件提供了针对相同 API 概念的 HTTP 资源类，生成的 HTTP 资源类必须继承该类
• 子类应仅处理插件特有的差异，避免重复父类的验证／序列化逻辑

6. 命名和响应消息应与目标插件中的现有 API 保持一致。
7. 通过检查路由注册并运行现有的针对性测试进行验证。
8. 注释只能写在函数定义上方。函数体内不得包含任何注释。

必需约定

• 使用路由组模式：Route::name('admin.api.v1.<plugin>.')->prefix('admin/api/v1/<plugin>')->middleware(['auth:sanctum'])->group(...)。
• 对软删除资源使用 Route::softDeletableApiResource(...)；在控制器中实现 restore() 和 forceDestroy()。
• 在控制器和端点上使用 Scribe PHP 属性（Group、Subgroup、Authenticated、Endpoint、QueryParam、UrlParam、Response、ResponseFromApiResource）。
• 在每个端点中使用 Gate::authorize(...)。
• 使用 Spatie\QueryBuilder\QueryBuilder，并显式指定 allowedFilters、allowedSorts 和 allowedIncludes。
• CRUD 响应返回 API 资源；删除和强制删除成功时返回 JSON { "message": "..." }。
• 在 FormRequest 中，始终将验证规则定义为数组（例如 ['required', 'email']），而不是使用竖线分隔的字符串。
• 对于更新处理（PUT/PATCH），定义 $isUpdate = $this->isMethod('PUT') || $this->isMethod('PATCH');，并使用逐字段三元规则条目（例如 $isUpdate ? ['sometimes', 'required'] : ['required']），不要使用规则转换循环。
• 使用规则数组中的规则对象进行枚举验证（例如 Rule::enum(Status::class)），不要拼接 'in:...' 字符串。
• 确保每个 FormRequest 都一致支持部分更新：创建时必填的字段在更新时必须变为 $isUpdate ? ['sometimes', 'required'] : ['required']，除非该字段不可变。
• 在 FormRequest 中，只公开对应 Filament 表单工作流中的可写载荷字段。不要接受或记录系统计算、只读、隐藏或由生命周期管理的列。
• 对于嵌套行数组，遵循相同的仅可写字段规则：只包含用户可编辑的字段；除非在 Filament 中明确可编辑，否则绝不验证或记录计算总额、利润率、状态字段或服务器派生的关联列。
• 根据全面的 Filament 分析推导 FormRequest 规则：包含特定工作流的要求、条件验证、嵌套载荷结构和操作专属的可写字段。
• 当某个模块扩展了另一个插件中的 Filament/资源类时，如果存在对应的父插件请求类，生成的请求类必须继承该类；只追加或覆盖子插件所需的增量规则。
• 包含用于文档说明的 bodyParameters()，并确保示例仅限于可写字段。
• 在 JsonResource 中包含标量 ID/时间戳，以及通过 whenLoaded(...) 条件加载的关联。
• 当某个模块扩展了另一个插件中的 Filament/资源类时，如果存在对应的父插件 HTTP 资源类，生成的 HTTP 资源必须继承该类；只在子类中添加插件专属的序列化字段/关联。
• 插件依赖处理：当控制器操作依赖可选插件中的功能（例如来自 inventories 插件的配送操作）时，应使用 Package::isPluginInstalled('<plugin>') 对执行进行保护，并在插件缺失时返回正常的空响应/默认响应。绝不要让请求执行查询可能不存在的表。

参考文件

• references/api-conventions.md：规范约定和实施检查清单。