fcode-examples

Factorial Code — 参考实现

完整 Factorial Code 应用的、贴近生产环境的示例。references/ 中的每份参考文档都会介绍一个真实示例：其架构、关键代码，以及如何调整。它们与侧重规则的技能（fcode-core-concepts、fcode-javascript/fcode-python、fcode-json-schema、fcode-forms、fcode-cli）相辅相成：那些技能告诉你 如何编写 fcode 代码，而这份文档展示 完整的应用是什么样子。

调整，而不是直接复制。 这些模式应根据用户的实际供应商和需求重新构建——重命名 slug、变量和映射；移除用例不需要的内容。

应阅读哪份参考文档

你正在构建……	阅读
将 Factorial 数据（薪资、休假等）传送到外部系统的市场集成	references/integration-acme.md
具有安装/卸载生命周期的自定义应用：设置表单、webhook、计划任务	references/custom-app-linear.md
一次性自动化：导出/生成报告、文件处理	references/utility-processes.md
通过表单使用 OAuth 连接第三方账户的应用（无需粘贴 API 令牌）	references/oauth-connect.md

模式索引

无论你构建哪种应用，都可以在此查找特定模式：

模式	参考文档
扩展 outbound-sync 基类（OutboundSync）	integration-acme
逐项 API 推送与汇总后交付文件	integration-acme
报告每项同步状态（success / invalid / failed）	integration-acme
由平台进行身份验证、而非在进程代码中验证的 webhook 入口点	integration-acme、custom-app-linear
在 metadata.json 中激活 webhook / 表单触发器，并保护 webhook（webhook.authMode 加工作区的 webhookAuth，以及市场的 appRole）	integration-acme、custom-app-linear
多步骤设置表单（nextProcessId 链接）	custom-app-linear
通过 preRenderProcess + #/variables 实现动态表单下拉选项	custom-app-linear
表单中的 OAuth 连接按钮（ui:widget: "oauth"）：预渲染会调用 fcode.oauth.start()，平台会处理重定向的两个阶段并调用完成进程；该进程会交换代码，并重定向到 SDK 回调页面（HTTP 302）；onComplete: "reload" 会重新渲染已连接状态	oauth-connect
安装时创建 webhook 和计划任务，并记录以便卸载时清理	custom-app-linear
使用数据存储游标进行轮询，并实现幂等性（去重映射，或在可用时使用供应商的 upsert）	custom-app-linear
尽力完成卸载/拆除	custom-app-linear
上传存储文件 + 生成签名下载 URL + 使用 fcode.sendMail 发送邮件	utility-processes
从表单上传的文件中读取存储内容	utility-processes
调用 Factorial API SDK（factorial-sdk 模块）	以上三份文档

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

每个 fcode App 工作区都会继承基础应用中的共享模块。使用 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-integration-app 继承 base-app）；自定义应用则直接继承 base-app。

注意：上方的 fcode-forms 模块（通过 fcode.import 导入的表单架构构建器）与 fcode-forms 技能无关；后者介绍如何在网页中嵌入表单。

参考代码保持简洁，省略了常规日志记录；实际实现应通过共享的 fcode-logs 模块进行详细日志记录（参见 fcode-javascript / fcode-python）。

语言变体

每个示例都提供 JavaScript（Node.js v22）和 Python（3.13）版本，结构和行为完全相同。参考内容展示 JavaScript；Python 版本仅在惯用写法上有所不同（main.py、fcode.import_module、fcode.send_mail、snake_case）——参见 fcode-python。