bagisto-api-admin

在 Bagisto Admin API 上构建管理应用

通过 Bagisto Admin API（/api/admin/* REST + POST /api/admin/graphql）实现任意管理/后台界面。该 API 与 Bagisto 管理面板的菜单一一对应，因此可以通过它重建任意管理界面。本技能是一个路由指南：它提供操作流程，并指向各菜单的参考页面；参考页面包含端点、UI/UX 和检查清单。

⚠️ 先加载以下内容（编写任何代码之前）

1. reference/connecting-to-the-api.md — 管理员身份验证（Integration Bearer 令牌）、{data,meta} 列表封装、列表→详情→操作模式、权限、错误，以及编码前验证流程。
2. reference/graphql.md — 如果客户端选择 GraphQL：管理端点、结果字段/id 规则、camelCase 输入 + 筛选参数、游标分页。

api-docs 是精确数据结构的权威来源 — https://api-docs.bagisto.com（Admin API 部分）及其 /llms.txt 索引。参考页面会列出端点和流程；编写调用前，请打开链接的文档页面，查看精确的请求体/响应。切勿凭记忆臆造请求负载。

第 1 步 — 询问客户端（关键，构建之前）

1. 平台 — Web、移动端（原生/跨平台）还是桌面端？
2. 框架/技术栈 — React/Next、Vue/Nuxt、Flutter、React Native 还是纯 JS？
3. 需要哪些管理菜单 — Sales、Catalog、Customers、Marketing、CMS、Settings、Configuration、Dashboard/Reporting，还是先做其中一个？
4. 传输方式 — REST 还是 GraphQL？（REST 适用于列表/详情/操作界面；当界面需要在一次往返中获取多个相关字段时，使用 GraphQL。两者均完全支持。）
5. 首个界面/流程 — 订单列表 + 操作、商品管理、Create-Order、仪表板，还是其他？

确认后，根据答案定制所有内容。不要自行假设技术栈。

核心管理模式：列表 → 详情 → 操作

几乎所有管理界面都采用相同结构（详见 connecting-to-the-api.md）：

• 列表 — GET /api/admin/<resource> → { data, meta } 封装；使用 ?page= + ?per_page= + 界面筛选条件驱动表格。
• 详情 — GET /api/admin/<resource>/{id} → 完整记录，内嵌关联数据（无需后续调用）。
• 操作 — 使用 POST/PUT/DELETE 创建/更新/删除，以及针对单条记录的操作（取消订单、创建发票、批量更新等），每项操作都有自己的执行条件。

第 2 步 — 打开对应菜单的参考页面

标志性流程

页面	构建内容
reference/flows/create-order.md	管理员 Create-Order 流程（通过购物车草稿为客户下单）

菜单（与管理侧边栏对应）

页面	涵盖内容
reference/menus/sales.md	订单（列表/详情 + 取消/评论/发票/发货/退款）、发票、发货、退款、交易、预约、CSV 导出
reference/menus/catalog.md	商品（数据网格 + CRUD + 图片/库存/客户组价格 + 批量操作）、分类（+树形结构）、属性（+选项）、属性族
reference/menus/customers.md	客户（CRUD + 地址/备注/模拟登录）、群组、评论、GDPR
reference/menus/marketing.md	购物车规则（+优惠券）、目录规则、电子邮件模板、活动、营销活动、订阅者、搜索词/同义词、URL 重写、站点地图
reference/menus/cms.md	CMS 页面
reference/menus/settings.md	货币、渠道、本地化区域、汇率、库存来源、税率/类别、角色、用户、主题、数据传输导入
reference/menus/configuration.md	商店配置（架构/值/更新）
reference/menus/dashboard-reporting.md	仪表板统计 + 报表（销售/客户/商品 + 导出）

发现 — 不要硬编码导航或权限

两个只读端点（REST + GraphQL）可告知你当前令牌能执行哪些操作 — 应根据它们驱动导航和操作权限判断，而不是硬编码：

• GET /api/admin/menu (getAdminMenu) — 管理侧边栏，呈现经过权限筛选的树形结构；每个节点都对应一个 API 端点（apiResource: { rest, graphql }，或对于分组标题 / 仅面板页面则为 null）。
• GET /api/admin/permissions (getAdminPermissions) — 令牌的有效 { permissionType, permissions }（["*"] = 完全访问权限）。

详情见 reference/connecting-to-the-api.md。

汇总的关键规则

• 编码前先验证。 暂停 → 打开端点的文档页面（或查询 MCP）→ 确认方法 / 字段 → 实现 → 检查类型。
• 身份验证： 每次调用都要发送 Authorization: Bearer <id>|<token>（预先签发的管理员 Integration 令牌）。没有登录端点 — 令牌在商店的管理面板中创建。管理员 GraphQL 端点是 POST /api/admin/graphql（仅限管理员令牌；不是商店端点，也不使用 storefront key）。
• 权限： 令牌权限受其管理员角色限制 — 角色无权访问的端点会返回 403。请针对这种情况进行处理。
• 列表响应为 { data, meta }（另有 X-Total-* 标头）；使用 ?page=/?per_page=（默认值为 10，上限为 50）和各页面的筛选条件进行分页。
• GraphQL 操作变更（取消 / 开具发票 / 发货 / 退款 / 下单 / 购物车写入 / 批量操作）返回的是结果字段，而不是通用的 id；输入字段采用 camelCase；自定义筛选参数按页面分别记录。参见 reference/graphql.md。
• 不要硬编码动态数据（创建订单中的配送 / 支付方式、配置选项）— 应通过获取来获取这些数据。