fcode-examples

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Factorial Code — reference implementations

Factorial Code — 参考实现

Worked, production-shaped examples of complete Factorial Code apps. Each reference in

references/

walks through one real sample: its architecture, the key code, and how to adapt it. They complement the rule-focused skills (

fcode-core-concepts

fcode-javascript

fcode-python

fcode-json-schema

fcode-forms

fcode-cli

): those tell you how to write fcode code, this one shows what a finished app looks like.

Adapt, don't paste. These are patterns to rebuild for the user's actual vendor/requirements — rename slugs, variables, and mappings; drop what the use case doesn't need.

这些是成型的、可用于生产环境的Factorial Code应用示例。

references/

目录下的每一份参考文档都会详细介绍一个真实案例：其架构、核心代码以及如何进行适配。它们与侧重规则的技能文档（

fcode-core-concepts

、

fcode-javascript

fcode-python

、

fcode-json-schema

、

fcode-forms

、

fcode-cli

）互为补充：后者告诉你如何编写fcode代码，而本项目展示一个完整应用的最终形态。

适配改造，而非直接复制粘贴。这些是可根据用户实际供应商/需求重构的模式——重命名别名、变量和映射关系，移除用例不需要的部分。

Which reference to read

选择对应的参考文档

You are building…	Read
A marketplace integration that delivers Factorial data (payroll, leaves, …) to an external system	`references/integration-acme.md`
A custom app with install/uninstall lifecycle: setup form, webhooks, schedules	`references/custom-app-linear.md`
A one-shot automation: export/report generation, file processing	`references/utility-processes.md`

你正在构建…	阅读文档
将Factorial数据（薪资、休假等）同步至外部系统的市场集成	`references/integration-acme.md`
包含安装/卸载生命周期的自定义应用：设置表单、Webhook、定时任务	`references/custom-app-linear.md`
一次性自动化流程：导出/报表生成、文件处理	`references/utility-processes.md`

Pattern index

模式索引

Where to find a specific pattern, regardless of which app you build:

Pattern	Reference
Extending the `outbound-sync` base class ( `OutboundSync` )	integration-acme
Per-item API push vs aggregate-to-file delivery	integration-acme
Reporting per-item sync status ( `success` / `invalid` / `failed` )	integration-acme
Webhook entry point authenticated by the platform, not in process code	integration-acme, custom-app-linear
Activating and protecting webhook / form triggers in `metadata.json` ( `webhook.authMode` + the workspace `webhookAuth` , `form.authMode` , marketplace `appRole` )	integration-acme, custom-app-linear
Multi-step setup form ( `nextProcessId` chaining)	custom-app-linear
Dynamic form dropdowns via `preRenderProcess` + `#/variables`	custom-app-linear
Creating webhooks + schedules at install, recording them for uninstall	custom-app-linear
Polling with a datastore cursor + idempotency (dedup map, or vendor upsert when available)	custom-app-linear
Best-effort uninstall / teardown	custom-app-linear
Storage upload + signed download URL + email with `fcode.sendMail`	utility-processes
Reading a form-uploaded file from Storage	utility-processes
Calling the Factorial API SDK ( `factorial-sdk` module)	all three

无论你构建何种应用，均可在此找到特定模式的位置：

模式	参考文档
扩展 `outbound-sync` 基类（ `OutboundSync` ）	integration-acme
单条数据API推送 vs 批量数据文件交付	integration-acme
上报单条数据同步状态（ `success` / `invalid` / `failed` ）	integration-acme
由平台而非进程代码进行认证的Webhook入口	integration-acme, custom-app-linear
在 `metadata.json` 中激活并保护Webhook/表单触发器（ `webhook.authMode` + 工作区 `webhookAuth` 、 `form.authMode` 、市场 `appRole` ）	integration-acme, custom-app-linear
多步骤设置表单（通过 `nextProcessId` 链式跳转）	custom-app-linear
通过 `preRenderProcess` + `#/variables` 实现动态表单下拉选项	custom-app-linear
在安装时创建Webhook+定时任务，并记录以便卸载时清理	custom-app-linear
使用数据存储游标+幂等性（去重映射，或供应商提供的upsert功能）进行轮询	custom-app-linear
尽力而为的卸载/清理操作	custom-app-linear
存储上传+签名下载URL+使用 `fcode.sendMail` 发送邮件	utility-processes
从存储中读取表单上传的文件	utility-processes
调用Factorial API SDK（ `factorial-sdk` 模块）	全部三个文档

The base workspaces (always present — never recreate)

基础工作区（始终存在——切勿重复创建）

Every fcode App workspace inherits shared modules from the base apps. Import them with

fcode.import(...)

fcode.import_module(...)

; do not reimplement them:

Module	From	Provides
`factorial-sdk`	base-app	`createFactorialClient()` — authenticated `@factorialco/api-client` / `factorial-api-client` instance
`factorial-utils`	base-app	`getCompanyId()` , `setupWebhook()` , `listWebhookSubscriptions()` , `deleteWebhookSubscription()`
`fcode-forms`	base-app	Form-schema builders: `selectField()` , `toOptions()` , …
`mail-helper`	base-app	`brandedHtml()` for styled email bodies
`error-handler`	base-app	Shared error handling
`outbound-sync`	base-integration-app	`OutboundSync` base class for marketplace syncs

Integration apps inherit base-integration-app (which inherits base-app); custom apps inherit base-app directly.

Note: the

fcode-forms

module above (form-schema builders you

fcode.import

) is unrelated to the

fcode-forms

skill, which documents embedding forms on webpages.

The references keep code compact and omit routine logging; real implementations should log verbosely through the shared

fcode-logs

module (see

fcode-javascript

fcode-python

每个fcode应用工作区都会继承基础应用中的共享模块。使用

fcode.import(...)

fcode.import_module(...)

导入它们；不要重新实现：

模块	来源	提供功能
`factorial-sdk`	base-app	`createFactorialClient()` — 已认证的 `@factorialco/api-client` / `factorial-api-client` 实例
`factorial-utils`	base-app	`getCompanyId()` 、 `setupWebhook()` 、 `listWebhookSubscriptions()` 、 `deleteWebhookSubscription()`
`fcode-forms`	base-app	表单构建器： `selectField()` 、 `toOptions()` 等
`mail-helper`	base-app	用于生成样式化邮件正文的 `brandedHtml()`
`error-handler`	base-app	共享错误处理逻辑
`outbound-sync`	base-integration-app	用于市场同步的 `OutboundSync` 基类

集成应用继承自base-integration-app（后者继承自base-app）；自定义应用直接继承自base-app。

注意：上述的

fcode-forms

模块（通过

fcode.import

导入的表单构建器）与

fcode-forms

技能文档无关，后者记录的是如何在网页中嵌入表单。

参考文档会简化代码并省略常规日志记录；实际实现应通过共享的

fcode-logs

模块进行详细日志记录（详见

fcode-javascript

fcode-python

）。

Language variants

语言版本

Every sample exists in JavaScript (Node.js v22) and Python (3.13) with identical structure and behavior. References show JavaScript; the Python variant differs only in idiom:

JavaScript	Python
`processes/<slug>/index.js`	`processes/<slug>/main.py`
`fcode.import("slug")`	`fcode.import_module("slug")`
`fcode.sendMail(...)`	`fcode.send_mail(...)`
`module.exports = { main }`	top-level `def main():`
camelCase helpers	snake_case helpers

每个示例都有JavaScript（Node.js v22）和Python（3.13）版本，结构和行为完全一致。参考文档展示的是JavaScript版本；Python版本仅在语法习惯上有所不同：

JavaScript	Python
`processes/<slug>/index.js`	`processes/<slug>/main.py`
`fcode.import("slug")`	`fcode.import_module("slug")`
`fcode.sendMail(...)`	`fcode.send_mail(...)`
`module.exports = { main }`	顶层 `def main():`
驼峰式命名的工具函数	蛇形命名的工具函数