文档

FrugalDomain 集成文档

平台技术指南：对接店铺、集成移动应用、发布您自己的应用以及 REST API。

平台概览

FrugalDomain 是一个把商品目录、库存、内容和订单操作集中到一个系统中的平台。

在同一个控制面板中管理店铺数据。
以单一的商务引擎作为唯一数据源。
为网页和 Flutter 移动应用提供简洁的 API。

FrugalDomain 的价值

该平台专为需要通过单一后台高效完成日常运营的团队设计。

让日常员工更快地处理商品和库存。
结构化的同步流水线，支持监控与重试。
可复用的 API 约定，适用于前端、移动端和各类集成。
店铺级隔离，每个店铺只能看到自己的数据。

核心工作流程

商品目录管理

商品、变体、集合、标签、供应商、商品类型。
按仓库控制商品可见性，实现渠道细分。

库存与定价

变体级别的库存与可售状态管理。
批量或定向调价，并触发同步。

订单与结账

由后端计算购物车合计。
创建草稿订单，作为结账前的步骤。
启用后，通过跳转到已配置的结账地址完成支付阶段。

如何对接店铺

1. 在您的系统中创建并启用店铺记录。
2. 安全保存店铺域名和访问令牌。
3. 对商品、变体、内容和客户执行首次全量同步。
4. 启用持续同步任务和 webhook 订阅。
5. 在向店铺员工开放访问之前，先在控制台检查同步状态是否正常。

每个店铺使用独立的店铺身份，切勿在不同店铺间复用令牌。

Flutter 移动端集成

移动应用接口位于 /mobile 下，需要店铺上下文。请始终发送 store_id，如需获取特定渠道的商品，可再发送 warehouse_name。

按 warehouse_name 筛选时，结果包含对应仓库的商品以及全局商品（null/empty/all）。
请先调用 bootstrap 接口，预加载店铺品牌信息、精选商品和支付方式。
创建草稿订单前，请调用 quote 接口以显示准确的合计金额。

代码

GET /mobile/bootstrap?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/products?store_id={uuid}&warehouse_name=BRAND VIP WEB&per_page=20
GET /mobile/collections?store_id={uuid}&warehouse_name=BRAND VIP WEB
GET /mobile/search?store_id={uuid}&warehouse_name=BRAND VIP WEB&q=lip
POST /mobile/checkout/quote
POST /mobile/checkout/place-draft-order

站内工具

除控制台之外，网站还提供一组基于浏览器的工具。它们完全在访问者的设备上运行，不会上传任何内容，因此页面加载后即使离线也能使用。

图标库

324 个 SVG 和 PNG 图标，通过 CDN 提供。
复制类名、下载单个文件，或创建图标集。
只需两行即可使用：引入样式表，然后使用图标类名。

转换器

在常见位图格式之间转换图片。
由浏览器中的 WebAssembly 驱动的音频和文档转换。
文件不会离开您的设备，因此大文件只受可用内存限制。

画板与模拟器

支持图层、撤销和重做的矢量画板。
记录手势笔画并识别阿拉伯文字符的触控模拟器。

发布应用

应用可以与网站一同发布。每个应用都有一张应用库卡片、独立的文档页面和内嵌的在线预览，并从自己的文件夹提供服务，因此保留各自的路由和资源。

1. 在控制台（Apps）中添加条目，并选择类型和预览模式。
2. 编写显示在应用页面上的文档章节。
3. 使用与其文件夹匹配的 base 路径构建应用，例如 --base=/apps/my-app/
4. 将构建输出的内容上传到服务器上的 apps/<slug>/ 中。
5. 将条目设为“已发布”，保存目录，然后重新构建前端。

预览模式

子文件夹：在 /apps/<slug> 提供服务。只需上传，无需任何托管配置。
子域名：将子域名的文档根目录指向应用文件夹，并以 base "/" 构建。
外部：应用托管在其他地方，应用库只提供跳转链接。

路由

网站的重写规则会排除 /apps/<slug>/...，使深层链接在应用内部解析。
自带客户端路由的应用，需要在其文件夹中放置 .htaccess，指向它自己的 index.html。

从子文件夹提供服务的 React 或 Vue 构建产物，必须使用匹配的 base 路径构建。若使用默认 base 构建，它会从网站根目录请求资源，所有请求都会返回 404，预览将显示空白。

REST API 指南（当前公开的集成接口）

请求和响应均使用 JSON。当路由需要受保护的上下文时，请发送 Authorization 令牌。对于移动店面路由，请求中必须包含 store_id。

GET/mobile/bootstrap
返回店铺资料、精选目录模块和支付方式引用。
GET/mobile/products
分页的商品列表，可选搜索和仓库筛选。
GET/mobile/products/{id}
商品详情，包含变体、集合和标签。
GET/mobile/collections
列出当前店铺上下文中的集合。
GET/mobile/collections/{id}
集合详情，包含集合内的商品。
GET/mobile/pages
店面应用的已发布静态页面。
GET/mobile/blogs
已发布的博客。
GET/mobile/blogs/{blogId}/articles
供内容页面使用的博客文章列表。
GET/mobile/payment-methods
返回已启用的本地支付开关和支持的支付方式引用。
POST/mobile/checkout/quote
根据变体行计算报价合计。
POST/mobile/checkout/place-draft-order
创建本地草稿订单，作为结账前的步骤。

方法	路径	用途
GET	/mobile/bootstrap	返回店铺资料、精选目录模块和支付方式引用。
GET	/mobile/products	分页的商品列表，可选搜索和仓库筛选。
GET	/mobile/products/{id}	商品详情，包含变体、集合和标签。
GET	/mobile/collections	列出当前店铺上下文中的集合。
GET	/mobile/collections/{id}	集合详情，包含集合内的商品。
GET	/mobile/pages	店面应用的已发布静态页面。
GET	/mobile/blogs	已发布的博客。
GET	/mobile/blogs/{blogId}/articles	供内容页面使用的博客文章列表。
GET	/mobile/payment-methods	返回已启用的本地支付开关和支持的支付方式引用。
POST	/mobile/checkout/quote	根据变体行计算报价合计。
POST	/mobile/checkout/place-draft-order	创建本地草稿订单，作为结账前的步骤。

请求示例

{
  "store_id": "your-store-uuid",
  "warehouse_name": "BRAND VIP WEB",
  "lines": [
    { "variant_id": 1201, "quantity": 2 },
    { "variant_id": 1202, "quantity": 1 }
  ]
}

响应示例

{
  "status": "success",
  "data": {
    "totals": {
      "subtotal": 45.0,
      "tax": 0,
      "shipping": 0,
      "discount": 0,
      "grand_total": 45.0
    }
  }
}

安全与最佳实践

校验 store_id，切勿信任来自客户端的租户范围。
生产环境只使用 HTTPS，并定期轮换凭据。
访问令牌只保存在服务端。
关键的创建和更新操作应保证幂等性。
记录同步失败并附带关联标识，便于诊断。

故障排查

某个移动渠道缺少商品。

检查应用发送的 warehouse_name，并核对商品表中的 warehouse_location 值。

quote 接口返回空行。

确保变体 ID 属于同一店铺，并符合所选仓库的可见性规则。

同步计数器看起来没有更新。

刷新合作伙伴控制台，并确认后台队列进程正在运行。