fynd-extension

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fynd Extension (FDK) — Rules and context for the AI

Fynd扩展（FDK）——AI参考的规则与上下文

When working on a Fynd extension codebase, follow these rules and use this context so your suggestions stay correct and consistent with FDK.

在开发Fynd扩展代码库时，请遵循以下规则并参考此上下文，确保您的建议符合FDK的规范且保持一致性。

Rules (always apply)

规则（始终适用）

Company context: Every Fynd Platform API call must be scoped to a company. Always obtain
```
companyId
```
from the request (
```
x-company-id
```
header,
```
company_id
```
in query/body, or your DB) and use
```
getPlatformClient(companyId)
```
— never call platform APIs without a company-scoped client.
Route mount order: Custom webhooks and extension API routes must be mounted before
```
fdkExtension.fdkHandler
```
. If you add a new route, place it before the FDK handler in the server file so it is not swallowed by the catch-all.
Fynd API access: Use only
```
fdkExtension.getPlatformClient(companyId)
```
to get a client for Fynd Platform APIs (catalog, order, application, etc.). Do not construct API clients manually.
Webhook handlers (Fynd → extension): Handlers registered in
```
webhook_config.event_map
```
must have the signature
```
(event_name, request_body, company_id, application_id)
```
. Always use
```
company_id
```
and
```
application_id
```
to scope any DB writes or API calls inside the handler.
Inbound webhooks (external → extension): Any POST route that receives callbacks from an external system must be mounted before the FDK handler. Resolve
```
companyId
```
from the payload or your DB before calling
```
getPlatformClient(companyId)
```
; if you cannot resolve it, return 4xx and do not call Fynd APIs.
Extension-owned entities: When listing or returning platform entities that belong to an extension (e.g. schemes, accounts), always filter by
```
extension_id === process.env.EXTENSION_API_KEY
```
so only this extension’s resources are shown.
Backend entrypoint: FDK is configured in a single backend module (e.g.
```
backend/fdk.js
```
) via
```
setupFdk()
```
. The server mounts
```
fdkHandler
```
,
```
platformApiRoutes
```
,
```
partnerApiRoutes
```
, and the webhook route; do not duplicate FDK setup or mount the same paths twice.

**企业上下文：**所有Fynd Platform API调用都必须限定在单个企业的作用域内。务必从请求中获取
```
companyId
```
（来自
```
x-company-id
```
请求头、查询参数/请求体中的
```
company_id
```
，或您的数据库），并使用
```
getPlatformClient(companyId)
```
——绝对不能在没有企业作用域客户端的情况下调用平台API。
**路由挂载顺序：**自定义webhooks和扩展API路由必须在
```
fdkExtension.fdkHandler
```
之前挂载。如果您添加新路由，请将其放在服务器文件中的FDK处理程序之前，避免被兜底的捕获逻辑覆盖。
**Fynd API访问：**仅使用
```
fdkExtension.getPlatformClient(companyId)
```
获取Fynd Platform APIs（目录、订单、应用等）的客户端。请勿手动构建API客户端。
**Webhook处理程序（Fynd → 扩展）：**在
```
webhook_config.event_map
```
中注册的处理程序必须符合签名
```
(event_name, request_body, company_id, application_id)
```
。处理程序内部的所有数据库写入或API调用，都必须使用
```
company_id
```
和
```
application_id
```
限定作用域。
**入站Webhook（外部 → 扩展）：**所有接收外部系统回调的POST路由必须在FDK处理程序之前挂载。在调用
```
getPlatformClient(companyId)
```
之前，务必从负载或数据库中解析出
```
companyId
```
；如果无法解析，请返回4xx状态码，且不要调用Fynd APIs。
**扩展自有实体：**当列出或返回属于某个扩展的平台实体（如方案、账户）时，必须始终通过
```
extension_id === process.env.EXTENSION_API_KEY
```
进行过滤，确保只显示当前扩展的资源。
**后端入口：**FDK在单个后端模块（如
```
backend/fdk.js
```
）中通过
```
setupFdk()
```
进行配置。服务器会挂载
```
fdkHandler
```
、
```
platformApiRoutes
```
、
```
partnerApiRoutes
```
和webhook路由；请勿重复配置FDK，也不要重复挂载相同的路径。

Quick context

快速上下文

FDK module: Exports

fdkHandler

getPlatformClient(companyId)

platformApiRoutes

partnerApiRoutes

webhookRegistry

. Use the same instance everywhere.

Routers: Platform routes (e.g. catalog) under
```
/api
```
; partner routes under
```
/apipartner
```
; extension-specific routes under
```
/apibasic
```
or your own prefix. All need
```
companyId
```
and
```
getPlatformClient(companyId)
```
when calling Fynd.
Event names and payloads: Depend on extension type. Refer to Fynd Partner docs when adding or debugging webhooks.

**FDK模块：**导出

fdkHandler

、

getPlatformClient(companyId)

、

platformApiRoutes

、

partnerApiRoutes

、

webhookRegistry

。请在所有地方使用同一个实例。

**路由：**平台路由（如目录）位于
```
/api
```
下；合作伙伴路由位于
```
/apipartner
```
下；扩展专属路由位于
```
/apibasic
```
或您自定义的前缀下。调用Fynd API时，所有路由都需要
```
companyId
```
和
```
getPlatformClient(companyId)
```
。
**事件名称与负载：**取决于扩展类型。添加或调试webhooks时，请参考Fynd合作伙伴文档。

When adding or changing behavior

添加或修改行为时的注意事项

New API route: Add a router in the backend, mount it in the server before the FDK handler; in the route, read
```
companyId
```
(e.g. from
```
x-company-id
```
), call
```
getPlatformClient(companyId)
```
, then call Fynd APIs.

New Fynd webhook: Add the event to

webhook_config.event_map

in the FDK module with

{ handler, version }

; implement the handler with signature

(event_name, request_body, company_id, application_id)

New inbound webhook: Add a POST route and mount it before
```
fdkHandler
```
; in the handler, resolve
```
companyId
```
, then
```
getPlatformClient(companyId)
```
and Fynd APIs as needed.
Extension-specific logic: Attach to the appropriate router (platform/partner/basic); when returning lists from the platform that are extension-scoped, filter by
```
extension_id === process.env.EXTENSION_API_KEY
```
.

新增API路由：在后端添加一个路由，并在服务器中于FDK处理程序之前挂载该路由；在路由逻辑中，读取
```
companyId
```
（例如来自
```
x-company-id
```
请求头），调用
```
getPlatformClient(companyId)
```
，然后再调用Fynd APIs。
**新增Fynd Webhook：**在FDK模块的
```
webhook_config.event_map
```
中添加事件，配置
```
{ handler, version }
```
；处理程序必须符合签名
```
(event_name, request_body, company_id, application_id)
```
。
**新增入站Webhook：**添加一个POST路由并在
```
fdkHandler
```
之前挂载；在处理程序中解析出
```
companyId
```
，然后根据需要调用
```
getPlatformClient(companyId)
```
和Fynd APIs。
**扩展专属逻辑：**将逻辑附加到对应的路由（平台/合作伙伴/基础路由）；当从平台返回属于扩展作用域的列表时，请通过
```
extension_id === process.env.EXTENSION_API_KEY
```
进行过滤。

References (load when needed)

参考资料（按需查阅）

references/fdk-setup.md — FDK setup rules, env vars, route order.
references/webhooks.md — Webhook registration and inbound webhook rules.
references/extension-patterns.md — Rules by extension type (catalog, platform-scoped, custom).

references/fdk-setup.md — FDK配置规则、环境变量、路由顺序。
references/webhooks.md — Webhook注册与入站Webhook规则。
references/extension-patterns.md — 按扩展类型分类的规则（目录型、平台作用域型、自定义型）。