From cb5f5ed4aab888a9947c8aa0b2dbb08ada7053e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 18:13:34 +0000 Subject: [PATCH] =?UTF-8?q?docs(guides):=20=E6=8C=89=E5=AE=9E=E9=99=85?= =?UTF-8?q?=E8=90=BD=E5=9C=B0=E8=83=BD=E5=8A=9B=E9=87=8D=E8=BF=B0=20integr?= =?UTF-8?q?ations=20=E9=A1=B5=EF=BC=8C=E5=B9=B6=E6=A0=A1=E6=AD=A3=E6=8C=87?= =?UTF-8?q?=E5=8D=97=E7=B4=A2=E5=BC=95=E6=8F=8F=E8=BF=B0=E8=A1=8C=20(#756)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `guides/integrations.mdx` 把 10 类连接器列为「Built-in」，每行还给了一个 `Setup → Integrations → X` 的菜单路径。对着源码实测：`src/` 里没有任何连接器 元数据，平台包里也没有任何一家厂商的连接器插件，应用里更没有 `Setup → Integrations` 菜单——这些设置路径把读者指向了一个不存在的界面，是本页 最具误导性的部分。 按 #755 确立的姿态处理：整表作为设计意图保留并标注「尚未落地」、链到路线图 （路线图上本来就写着「更多连接器」），同时给表格加第三列，逐行写明今天最接近的 落地能力。 其余各节同样逐条实测： - **Webhooks** 是本页唯一真实的能力，而且原文错在另一个方向： `@objectstack/plugin-webhooks` 确实提供出站 webhook 服务，但 HotCRM 从未启用它 —— `objectstack.config.ts` 的 `requires` 里没有 `webhooks`，它也不属于平台对每个 应用都会加载的那一批能力，本应用也没有声明任何 webhook。现在改述为一个部署侧的 决定，重试次数 / 载荷结构 / 投递日志这些细节交还给平台自己的文档。 - **GraphQL** 删除：它不在产品规划内，平台已把 `/graphql` 从服务表移除。杜撰的 `POST /api/v1/leads` 示例一并删除——对象名是 `crm_lead`，路由形态取决于运行时版本。 - **事件总线**（Kafka / EventBridge / Pub-Sub）、**密钥存储**（Vault / AWS Secrets Manager / GCP Secret Manager、90 天 OAuth 轮换）与原生 **`*.connector.ts` 插件** 形态在平台能力清单里都没有对应词条，各自标注「尚未落地」，并点明真正相邻的机制 （记录变更流程、`secret` 字段失败关闭地加密写入 `sys_secret`、钩子 / 流程 / 操作体）。 - 新增 **今天已落地的能力** 一节：HTTP 数据 API、客户 / 联系人 / 线索 / 商机列表视图 的 CSV / XLSX 导出、电子表格导入、出站发送邮件，以及 `notify` 节点的应用内通知。 指南索引里 **邮件与日历** 和 **集成** 两行随之改写：邮件行原先仍写着 「连接 Gmail / Outlook、双向同步、邮件追踪」，而该页自己已经把这些标为尚未落地。 zh-Hans / zh-Hant 同步。 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa --- .../integrations-connectors-measured.md | 46 +++++ content/docs/guides/index.mdx | 4 +- content/docs/guides/index.zh-Hans.mdx | 4 +- content/docs/guides/index.zh-Hant.mdx | 4 +- content/docs/guides/integrations.mdx | 164 +++++++++--------- content/docs/guides/integrations.zh-Hans.mdx | 162 ++++++++--------- content/docs/guides/integrations.zh-Hant.mdx | 162 ++++++++--------- 7 files changed, 299 insertions(+), 247 deletions(-) create mode 100644 .changeset/integrations-connectors-measured.md diff --git a/.changeset/integrations-connectors-measured.md b/.changeset/integrations-connectors-measured.md new file mode 100644 index 000000000..1b5fef4eb --- /dev/null +++ b/.changeset/integrations-connectors-measured.md @@ -0,0 +1,46 @@ +--- +'hotcrm': patch +--- + +Docs: restate the Integrations guide against what the app actually exposes. + +The page listed ten connector families as **Built-in** — Slack, Teams, DocuSign, +Stripe, Twilio, Aircall / RingCentral / Five9, Intercom / Zendesk Chat, Gmail / +Outlook, Snowflake / BigQuery / Redshift, Zapier / Make / n8n — each with a +`Setup → Integrations → X` path to configure it at. Measured against the source: +`src/` carries no connector metadata of any kind, no platform package ships a +connector for any of those vendors, and there is no `Setup → Integrations` menu, +so every one of those paths sent the reader looking for a screen that does not +exist. The table is kept as design intent, marked *(not shipped yet)*, pointed at +the roadmap (whose own line already reads "More connectors"), and given a third +column naming the closest thing that does ship for each row. + +The rest of the page was measured the same way: + +- **Webhooks** are the one real capability here, and the page was wrong in the + other direction: `@objectstack/plugin-webhooks` genuinely ships an outbound + webhook service, but HotCRM never enables it — `webhooks` is absent from + `requires` in `objectstack.config.ts` and is not one of the always-loaded + capabilities, and the app declares no webhook. Now stated as a deployment + decision rather than a menu path, with the retry / payload / delivery-log + specifics handed back to the platform's own docs. +- **GraphQL** is removed: it is not in the product plan and the platform dropped + the `/graphql` route from its service table. The invented `POST /api/v1/leads` + example is gone too — objects are `crm_lead` and the route shape follows the + runtime version. +- **Event bus** (Kafka / EventBridge / Pub-Sub), the **secrets store** + (Vault / AWS Secrets Manager / GCP Secret Manager, 90-day OAuth rotation) and + the native **`*.connector.ts` plugin** shape have no counterpart in the + platform's capability list; each is marked *(not shipped yet)* with the real + adjacent mechanism named (record-change flows, `secret` fields encrypted into + `sys_secret` fail-closed, hooks / flows / action bodies). +- A **What ships today** section was added: the HTTP data API, CSV / XLSX export + from the account / contact / lead / opportunity list views, spreadsheet import, + outbound Send Email, and the `notify` node's in-app notification. + +The Guides index rows for **Email & calendar** and **Integrations** were restated +to match their corrected pages — the email row still advertised "Connect Gmail / +Outlook, two-way sync, email tracking", which the page itself now marks as not +shipped. + +zh-Hans and zh-Hant pages updated with the same content. diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx index 032cad91c..74968717c 100644 --- a/content/docs/guides/index.mdx +++ b/content/docs/guides/index.mdx @@ -11,10 +11,10 @@ The pages in this section apply **across the whole product** — they're not spe | --- | --- | | [**Search & navigation**](/docs/guides/search-and-navigation) | Global search, keyboard shortcuts, saved views, list filters | | [**Files & comments**](/docs/guides/files-and-comments) | Attaching documents to a record, who can download them, and the record discussion feed | -| [**Email & calendar**](/docs/guides/email-and-calendar) | Connect Gmail / Outlook, two-way sync, email tracking | +| [**Email & calendar**](/docs/guides/email-and-calendar) | Send Email from a contact, calls and meetings as real records — and which inbox / calendar connectors are still on the roadmap | | [**Mobile**](/docs/guides/mobile) | Using HotCRM on phone and tablet | | [**Import your own data**](/docs/guides/importing-your-data) | Load accounts, contacts and leads from a spreadsheet — dry-run, then undo | | [**Import & export**](/docs/guides/import-and-export) | Importing from CSV, migrating from Salesforce / HubSpot, exporting data | -| [**Integrations**](/docs/guides/integrations) | Slack, Teams, DocuSign, Stripe, telephony, and how to build your own | +| [**Integrations**](/docs/guides/integrations) | The data API, exports and outbound email that exist today — and which packaged connectors are still design intent | These are the "first week of use" pages — bookmark them. diff --git a/content/docs/guides/index.zh-Hans.mdx b/content/docs/guides/index.zh-Hans.mdx index 8d45cb439..3554650e2 100644 --- a/content/docs/guides/index.zh-Hans.mdx +++ b/content/docs/guides/index.zh-Hans.mdx @@ -11,10 +11,10 @@ description: 适用于销售、服务、营销和收入各领域的跨领域操 | --- | --- | | [**搜索与导航**](/zh-Hans/docs/guides/search-and-navigation) | 全局搜索、键盘快捷键、已保存视图、列表筛选 | | [**文件与评论**](/zh-Hans/docs/guides/files-and-comments) | 把文档附加到记录上、谁能下载它们，以及记录讨论流 | -| [**邮件与日历**](/zh-Hans/docs/guides/email-and-calendar) | 连接 Gmail / Outlook、双向同步、邮件追踪 | +| [**邮件与日历**](/zh-Hans/docs/guides/email-and-calendar) | 从联系人发送邮件、把通话与会议写成真实记录——以及哪些收件箱 / 日历连接器仍在路线图上 | | [**移动端**](/zh-Hans/docs/guides/mobile) | 在手机和平板上使用 HotCRM | | [**导入你自己的数据**](/zh-Hans/docs/guides/importing-your-data) | 从电子表格加载客户、联系人和潜在客户 —— 先试运行，再撤销 | | [**导入与导出**](/zh-Hans/docs/guides/import-and-export) | 从 CSV 导入、从 Salesforce / HubSpot 迁移、导出数据 | -| [**集成**](/zh-Hans/docs/guides/integrations) | Slack、Teams、DocuSign、Stripe、电话系统，以及如何构建自己的集成 | +| [**集成**](/zh-Hans/docs/guides/integrations) | 今天真实存在的数据 API、导出与对外邮件——以及哪些成套连接器仍是设计意图 | 这些是"使用第一周"的页面 —— 把它们加入书签。 diff --git a/content/docs/guides/index.zh-Hant.mdx b/content/docs/guides/index.zh-Hant.mdx index 3cbcb2e19..39f7a01e8 100644 --- a/content/docs/guides/index.zh-Hant.mdx +++ b/content/docs/guides/index.zh-Hant.mdx @@ -11,10 +11,10 @@ description: 適用於銷售、服務、行銷和收入各領域的跨領域操 | --- | --- | | [**搜尋與導覽**](/zh-Hant/docs/guides/search-and-navigation) | 全域搜尋、鍵盤快速鍵、已儲存檢視、清單篩選 | | [**檔案與評論**](/zh-Hant/docs/guides/files-and-comments) | 把文件附加到記錄上、誰能下載它們，以及記錄討論流 | -| [**郵件與行事曆**](/zh-Hant/docs/guides/email-and-calendar) | 連接 Gmail / Outlook、雙向同步、郵件追蹤 | +| [**郵件與行事曆**](/zh-Hant/docs/guides/email-and-calendar) | 從聯絡人傳送郵件、把通話與會議寫成真實記錄——以及哪些收件匣 / 行事曆連接器仍在路線圖上 | | [**行動版**](/zh-Hant/docs/guides/mobile) | 在手機和平板上使用 HotCRM | | [**匯入你自己的資料**](/zh-Hant/docs/guides/importing-your-data) | 從試算表載入客戶、聯絡人與潛在客戶 —— 先試算，再復原 | | [**匯入與匯出**](/zh-Hant/docs/guides/import-and-export) | 從 CSV 匯入、從 Salesforce / HubSpot 遷移、匯出資料 | -| [**整合**](/zh-Hant/docs/guides/integrations) | Slack、Teams、DocuSign、Stripe、電話系統，以及如何建構自己的整合 | +| [**整合**](/zh-Hant/docs/guides/integrations) | 今天真實存在的資料 API、匯出與對外郵件——以及哪些成套連接器仍是設計意圖 | 這些是「使用第一週」的頁面 —— 把它們加入書籤。 diff --git a/content/docs/guides/integrations.mdx b/content/docs/guides/integrations.mdx index 01ceeec2b..a79f12fe9 100644 --- a/content/docs/guides/integrations.mdx +++ b/content/docs/guides/integrations.mdx @@ -1,137 +1,139 @@ --- title: Integrations -description: Connect HotCRM to Slack, Teams, DocuSign, Stripe, telephony, and other tools — and how to build your own integration. +description: What HotCRM actually exposes to the outside world today — the data API, list-view exports, outbound email — and which packaged connectors are still design intent on the roadmap. --- # Integrations -HotCRM is designed to **fit into your stack**, not replace it. This page lists the supported integrations and how to plug HotCRM into the rest of your business systems. +HotCRM is designed to **fit into your stack**, not replace it. Today it does that through the platform's own edges: a data API, spreadsheet import and export, outbound email, and automation you write yourself. What it does not do yet is ship **packaged vendor connectors** — `src/` carries no connector metadata of any kind, and there is no **Setup → Integrations** menu to configure one under. -## Built-in connectors +> **Read this before following a setup step.** Every heading below marked *(not shipped yet)* describes an integration **as designed** — it is on the [roadmap](/docs/whats-new#roadmap), not a switch you can turn on today. The unmarked sections describe what the app actually exposes. The roadmap's own line for this reads *"More connectors — Slack, Microsoft Teams, Google Workspace, HubSpot import"*. -| Tool | What it does | Setup at | +## What ships today + +- 🔌 **The platform data API** — every CRM object is reachable over the runtime's HTTP API, with ObjectQL-shaped filters and field selection. See [API reference](/docs/customization/api-reference). +- 📤 **CSV / XLSX export** from a list view — the account, contact, lead and opportunity list views each declare `exportOptions: ['csv', 'xlsx']`. +- 📥 **Spreadsheet import** with reusable column mappings and a dry-run first. See [Import your own data](/docs/guides/importing-your-data). +- ✉️ **Outbound email** — **Send Email** on a contact, queued through the platform email service. Outbound only, and it leaves the building only if the deployment configures a transport. See [Email & Calendar](/docs/guides/email-and-calendar). +- 🔔 **In-app notification** — the `notify` flow node delivers through the platform messaging service to the Console bell. Inside HotCRM, not into Slack or an inbox. +- 🧩 **Your own code** — hooks, flows and action bodies run in-process against the same objects and the same permission checks. See [Customization › Extending Objects](/docs/customization/extending-objects). + +## Built-in connectors (not shipped yet) + +The line-up below is **design intent** — kept here because it is the shape the product is aimed at. None of it is in the box: no connector metadata in `src/`, no connector plugin among the platform packages, and **no `Setup → Integrations` menu**. The setup paths this table used to print were the most misleading thing on the page, because someone following one went looking for a screen that does not exist. + +| Tool | Intended behaviour | Closest thing that ships today | | --- | --- | --- | -| 💬 **Slack** | Notifications, slash-commands, deal-room channels | Setup → Integrations → Slack | -| 💬 **Microsoft Teams** | Same as Slack | Setup → Integrations → Teams | -| ✍️ **DocuSign** | Send quotes/contracts for e-signature; status flows back | Setup → Integrations → DocuSign | -| 💳 **Stripe** | Customers, subscriptions, invoices sync to accounts/contracts | Setup → Integrations → Stripe | -| 📞 **Twilio Voice** | Click-to-call, call recording, AI transcript | Setup → Integrations → Twilio | -| 📞 **Aircall / RingCentral / Five9** | Same as Twilio | Setup → Integrations → Telephony | -| 💬 **Intercom / Zendesk Chat** | Live-chat conversations land as cases | Setup → Integrations → Chat | -| 📧 **Gmail / Outlook** | Email & calendar sync (see [Email & Calendar](/docs/guides/email-and-calendar)) | Settings → Email & Calendar | -| 📊 **Snowflake / BigQuery / Redshift** | Data warehouse export | Setup → Data → Scheduled Exports | -| 🔗 **Zapier / Make / n8n** | No-code automation to 5,000+ apps | Setup → Integrations → Webhooks | - -## What each connector does +| 💬 **Slack** | Notifications, slash-commands, deal-room channels | In-app notification only — the `notify` flow node reaches the Console bell, not Slack | +| 💬 **Microsoft Teams** | Same as Slack | Same | +| ✍️ **DocuSign** | Send quotes / contracts for e-signature; status flows back | Nothing — a quote's or contract's status is a field someone sets by hand | +| 💳 **Stripe** | Customers, subscriptions, invoices sync to accounts / contracts | Nothing — contracts are authored in HotCRM | +| 📞 **Twilio Voice** | Click-to-call, call recording, AI transcript | **Log a Call** records the call as a real Event *after* it happens; nothing dials, records or transcribes | +| 📞 **Aircall / RingCentral / Five9** | Same as Twilio | Same | +| 💬 **Intercom / Zendesk Chat** | Live-chat conversations land as cases | A case's **Origin** picklist carries *Chat*, but a person selects it when logging the case | +| 📧 **Gmail / Outlook** | Two-way email and calendar sync | **Send Email** on a contact — outbound only, no inbox connector. See [Email & Calendar](/docs/guides/email-and-calendar) | +| 📊 **Snowflake / BigQuery / Redshift** | Nightly incremental warehouse export with dbt models | CSV / XLSX export from a list view, run by hand | +| 🔗 **Zapier / Make / n8n** | No-code automation to 5,000+ apps | Nothing in this app — the platform's webhook outbox exists, but HotCRM does not enable it (see below) | + +## What each connector would do (not shipped yet) + +Kept as the design brief for each family. Read it as a specification, not as instructions. ### 💬 Slack -- **Notifications**: deal wins, case escalations, approvals, @mentions → DM or channel. -- **Slash commands**: `/hotcrm lookup acme` to fetch an account; `/hotcrm log call` to log activity from Slack. -- **Deal rooms**: auto-create a Slack channel per opportunity over a threshold, with the account team and product specialists invited. -- **Approval actions**: approve/reject discount requests directly from Slack. +The intended behaviour: deal wins, case escalations, approvals and @mentions pushed to a DM or a channel; slash-commands (`/hotcrm lookup acme`, `/hotcrm log call`); a channel auto-created per opportunity over a threshold, with the account team and product specialists invited; and approve / reject on a discount request straight from Slack. + +Those events do fire today — as flows — but they end at the Console bell, and an approval is decided on the record. ### ✍️ DocuSign -1. From a quote or contract → click **Send for Signature**. -2. Choose recipients, signing order, fields. -3. DocuSign emails the customer; status (sent → viewed → signed) flows back into HotCRM. -4. Once signed, the executed PDF is attached and the record's status auto-updates. +The intended behaviour: **Send for Signature** from a quote or contract, recipients and signing order and fields chosen in HotCRM, status (sent → viewed → signed) flowing back, and the executed PDF landing on the record with its status updated for you. + +Today a quote or contract carries status fields and file attachments, and a person moves them. ### 💳 Stripe -- **Customers** in Stripe sync to HotCRM **accounts** by email or external ID. -- **Subscriptions** sync to **contracts** — status, MRR, billing frequency. -- **Invoices** appear on the account's activity timeline. -- **Failed payments** create a high-priority case for the account owner / CSM. -- **Cancellations** alert the CSM and create a churn opportunity. +The intended behaviour: Stripe customers matched onto accounts by email or external ID; subscriptions mirrored onto contracts with status, MRR and billing frequency; invoices on the account timeline; a failed payment raising a high-priority case for the owner or CSM; a cancellation alerting the CSM and opening a churn opportunity. + +Today none of that arrives on its own. Contracts, and the tasks that chase them, are written in HotCRM — see [Contracts](/docs/revenue/contracts). ### 📞 Telephony (Twilio / Aircall / RingCentral / Five9) -- Click any phone number to dial — call is logged automatically. -- Inbound calls pop a screen-pop showing the contact, account, recent cases, recent emails. -- Optional **call recording** — saved as audio file on the activity. -- AI **transcription** + **call summary** delivered after each call. +The intended behaviour: click a phone number to dial and have the call logged for you; an inbound call popping a screen with the contact, account, recent cases and recent emails; optional call recording saved as an audio file on the activity; and an AI transcript plus summary after each call. + +What is real is the other half of that loop: **Log a Call** on any record writes the call as an Event with attendee rows and a timeline entry — after the call, by hand. See [Meetings & Calls](/docs/sales/meetings-and-calls). -### 💬 Live chat (Intercom, Zendesk Chat, etc.) +### 💬 Live chat (Intercom, Zendesk Chat, …) -- Chat conversations land as cases automatically. -- Visitor identified by email → linked to existing contact + account. -- Anonymous chats become leads. +The intended behaviour: chat conversations landing as cases automatically, the visitor identified by email and linked to an existing contact and account, and anonymous chats becoming leads. + +Today a case is created by a person or by the API. Its **Origin** picklist offers *Chat*, which is a value someone selects, not evidence a chat arrived. ### 📊 Data warehouse -- Nightly incremental export of every CRM object. -- Pre-built dbt models for Snowflake / BigQuery / Redshift. -- Powers BI tools (Tableau, Looker, Power BI, Metabase, Hex). +The intended behaviour: a nightly incremental export of every CRM object, pre-built dbt models for Snowflake / BigQuery / Redshift, and BI tools reading from there. -## Webhooks (outbound) +Today the export that exists is manual: open a list view, export CSV or XLSX. Anything scheduled is something your deployment builds on the HTTP data API. -Trigger external systems when CRM records change. +## Webhooks (outbound) — not enabled in this app -1. **Setup → Integrations → Webhooks → New**. -2. Pick the **object** and **event** (`created`, `updated`, `deleted`, custom). -3. Add **conditions** (e.g., *only when opportunity stage = Closed Won*). -4. Set the **target URL** and authentication (Bearer / Basic / HMAC signature). -5. Choose the **payload schema** — full record, diff only, or custom. -6. Test → activate. +This one is not vapour. The platform **does** ship an outbound webhook service: `@objectstack/plugin-webhooks` keeps one subscription per `sys_webhook` row — authored either through that object's own admin UI or declared in code with `defineStack({ webhooks })` / `defineWebhook()` — matches record events against those rows, and hands each match to the shared messaging HTTP outbox for delivery. -Webhooks retry up to 5 times with exponential back-off. Failures are visible in the **delivery log**. +**HotCRM does not turn it on.** `objectstack.config.ts` declares `requires: ['automation', 'triggers', 'analytics', 'auth', 'ui', 'approvals', 'sharing']`. `webhooks` is not in that list, and it is not one of the capabilities the platform loads for every app regardless. The app authors no webhook either. So there is no webhook surface in HotCRM today, and no `Setup → Integrations → Webhooks` screen to find one under. -## Inbound webhooks / HTTP API +> **This is a deployment decision, not a roadmap item.** Add `webhooks` to `requires`, declare your subscriptions, and delivery is the platform's job from there. The retry counts, payload-shape choices and delivery-log screen this page used to promise were never HotCRM's to define — read them from the platform's own webhook documentation for the version you run, not from here. -External systems can create / update HotCRM records via REST / GraphQL. See the [API reference](/docs/customization/api-reference) for endpoints and authentication. +## HTTP API -Common patterns: +External systems can create and update HotCRM records over the runtime's HTTP data API. See [API reference](/docs/customization/api-reference) for the object inventory, the ObjectQL filter shape and authentication. Object names are the ones this app registers — `crm_lead`, `crm_account`, `crm_opportunity` — and the route shape follows your runtime version rather than anything this app pins, so read it from your own environment instead of a path hard-coded into a guide. -- A **website form** → POST to `/api/v1/leads` → new lead with source = *Web*. -- A **product** sending usage data → PATCH a custom usage field on the account. -- A **finance system** → POST contract activation, which triggers the standard contract workflow. +There is **no GraphQL endpoint**. GraphQL is not in the product plan, and the platform removed the `/graphql` route from its service table rather than advertise a path nobody serves. -## Event bus (Kafka / EventBridge / Pub/Sub) +Common patterns: + +- A **website form** creates a `crm_lead` with source = *Web* — enough to fire the lead-assignment flow, which runs on lead creation. +- A **product** patches a custom usage field on `crm_account`. +- A **finance system** writes a `crm_contract` as activated. The contract flows are daily sweeps (renewal reminders, expiry), not record-change triggers, so an activation is picked up on the next run rather than the instant it lands. -For high-volume integrations, HotCRM publishes events to a configurable event bus. +## Event bus (not shipped yet) -- **All record lifecycle events** (`created`, `updated`, `deleted`). -- **Domain events** (opportunity_won, contract_activated, case_escalated, approval_granted). -- **Schema-validated** with versioned schemas in the [@objectstack/spec](/docs/customization/index) repo. +The intended behaviour: HotCRM publishing every record lifecycle event, plus domain events (`opportunity_won`, `contract_activated`, `case_escalated`, `approval_granted`), onto a configurable Kafka / EventBridge / Pub-Sub bus, schema-validated with versioned schemas. -Configure at **Setup → Integrations → Event Bus**. +There is no such capability. The platform's capability list carries no event-bus token, so there is nothing to configure and no `Setup → Integrations → Event Bus` screen. Record events themselves are real — they drive record-change flows in-process — and the webhook outbox above is the out-of-process path, once a deployment enables it. ## Building a custom integration -If the connector you need isn't built-in, you have three options ordered from easy to powerful: +Two routes are real today. One is not. + +### 1. Server-to-server scripting (real) -### 1. Zapier / Make / n8n (no-code) +Call the HTTP data API from a script — a cron job, a Lambda, a GitHub Action. See [API reference](/docs/customization/api-reference). -Set up webhooks at **Setup → Integrations → Webhooks** and an inbound endpoint, then use Zapier to bridge to any app. +Best for: scheduled syncs, internal tools, anything whose reliability you want to own. -Best for: simple field-sync between systems, small teams. +### 2. In-process extension code (real) -### 2. Server-to-server scripting +Hooks, flows and action bodies run inside HotCRM, against the same objects and the same permission checks. See [Customization › Extending Objects](/docs/customization/extending-objects). -Use the REST API to call HotCRM from a script (cron job, AWS Lambda, GitHub Action). See [API reference](/docs/customization/api-reference). +Best for: logic that must run on every write, whoever made it. -Best for: scheduled syncs, internal tools, anything more reliable than a no-code tool. +### 3. No-code bridges — Zapier / Make / n8n (needs webhooks enabled first) -### 3. Native plugin +A no-code bridge needs an outbound trigger, so it depends on the webhook service above being enabled in your deployment. Turn it on and the Zapier side is ordinary work; leave it off and there is nothing for Zapier to subscribe to. -Build a `*.connector.ts` plugin that lives inside HotCRM with first-class lifecycle (auth, sync, monitoring). See [Customization › Extending Objects](/docs/customization/extending-objects). +### A native `*.connector.ts` plugin (not shipped) -Best for: integrations you'll ship to other HotCRM customers; integrations where bi-directional sync and observability matter. +Earlier versions of this page offered a connector plugin shape with a first-class lifecycle — auth, sync, monitoring — for integrations you would ship to other HotCRM customers. No such authoring surface exists. The spec does carry a `connector_action` flow node, but nothing registers a connector for it to call: this app's own approval flow records that its pre-ADR-0019 `connectorId: 'approval'` node stopped being registered and had to be rewritten as a native approval node. -## Auth & secrets +## Auth & secrets (not shipped yet) -All integration credentials are stored in the platform's secrets store (HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager — configurable). +The intended behaviour: every integration credential held in the platform's secrets store (HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager, configurable) and referenced rather than pasted into workflow or hook code, OAuth refresh tokens rotated automatically every 90 days, and an audit log entry for each secret access. -- **Never** paste a token into a workflow / hook code — always reference from secrets. -- **Rotate** OAuth refresh tokens automatically every 90 days. -- **Audit log** records every secret access. +HotCRM holds no integration credentials — there is no connector to hold one for, and no OAuth grant to rotate — and the platform's capability list has no secrets-store capability to configure. What is real sits one level down: a field of type `secret` is encrypted through the deployment's registered crypto provider (a local one in development, a KMS or Vault provider in production) and persisted to `sys_secret`, and the write **fails closed** rather than storing cleartext when no provider is registered. This app authors no `secret` field today. ## Tips for admins -- ✅ **Connect Slack** first — biggest day-1 adoption boost. -- ✅ **Connect telephony** for call-heavy teams — eliminates the "did Alex log the call?" gap. -- ✅ **DocuSign** for closing — the gap between "signed in DocuSign" and "marked Won in CRM" is where deals die. -- ✅ For each integration, **monitor the delivery log** weekly — webhook failures pile up silently. -- ✅ Use **event bus** rather than webhooks once you have >3 downstream consumers — scales better. +- ✅ Plan integrations around the **HTTP data API** — it is the surface that exists, and it reaches every object. +- ✅ Want outbound events? Enable the platform's **webhook** capability in your deployment, rather than waiting for a vendor connector. +- ✅ Configure a real email transport before telling reps that **Send Email** delivers. With none configured the platform logs the message and sends nothing. +- ✅ Read every *(not shipped yet)* section above as a requirements document, not a configuration guide — and watch the [roadmap](/docs/whats-new#roadmap). diff --git a/content/docs/guides/integrations.zh-Hans.mdx b/content/docs/guides/integrations.zh-Hans.mdx index 265005df4..10ea9cd79 100644 --- a/content/docs/guides/integrations.zh-Hans.mdx +++ b/content/docs/guides/integrations.zh-Hans.mdx @@ -1,137 +1,139 @@ --- title: 集成 -description: 将 HotCRM 连接到 Slack、Teams、DocuSign、Stripe、电话系统和其他工具 —— 以及如何构建你自己的集成。 +description: HotCRM 今天真正对外暴露了什么——数据 API、列表视图导出、对外邮件——以及哪些成套连接器仍是路线图上的设计意图。 --- # 集成 -HotCRM 的设计目标是**融入你的技术栈**，而非取代它。本页列出了受支持的集成，以及如何将 HotCRM 接入你业务系统的其余部分。 +HotCRM 的设计目标是**融入你的技术栈**，而非取代它。今天它靠平台自身的几条边界做到这一点：数据 API、电子表格导入与导出、对外邮件，以及你自己编写的自动化。它目前还做不到的，是提供**成套的厂商连接器**——`src/` 里没有任何连接器元数据，也不存在可用来配置连接器的 **设置 → 集成** 菜单。 -## 内置连接器 +> **在照着任何设置步骤操作之前，先读这一段。** 下文所有标注 *（尚未落地）* 的小节，描述的是相应集成的**设计意图**——它在[路线图](/zh-Hans/docs/whats-new)上，而不是今天可以打开的开关。未标注的小节，才是应用当前真正对外暴露的能力。路线图上对应的那一行写的是：*"更多连接器 —— Slack、Microsoft Teams、Google Workspace、HubSpot 导入"*。 -| 工具 | 功能 | 设置位置 | +## 今天已落地的能力 + +- 🔌 **平台数据 API**——每个 CRM 对象都可以通过运行时的 HTTP API 访问，支持 ObjectQL 形态的筛选与字段选择。参见 [API 参考](/zh-Hans/docs/customization/api-reference)。 +- 📤 **列表视图的 CSV / XLSX 导出**——客户、联系人、线索与商机的列表视图各自声明了 `exportOptions: ['csv', 'xlsx']`。 +- 📥 **电子表格导入**，带可复用的列映射，并可先试运行。参见[导入你自己的数据](/zh-Hans/docs/guides/importing-your-data)。 +- ✉️ **对外邮件**——联系人上的**发送邮件**，把邮件排入平台邮件服务。只有出站方向，而且只有在部署配置了传输方式时才真的发得出去。参见[邮件与日历](/zh-Hans/docs/guides/email-and-calendar)。 +- 🔔 **应用内通知**——`notify` 流程节点经平台消息服务送达 Console 铃铛。是在 HotCRM 内部，而不是送进 Slack 或某个收件箱。 +- 🧩 **你自己的代码**——钩子、流程与操作体在进程内针对同一批对象、同一套权限校验运行。参见[自定义 › 扩展对象](/zh-Hans/docs/customization/extending-objects)。 + +## 内置连接器（尚未落地） + +下面这份阵容是**设计意图**——保留它，是因为它标出了产品要去的方向。这些东西一样都不在盒子里：`src/` 里没有连接器元数据，平台包里也没有对应的连接器插件，更**没有 `设置 → 集成` 菜单**。这张表原先印出的那些设置路径，是本页最具误导性的部分：照着走的人，去找的是一个并不存在的界面。 + +| 工具 | 设计意图中的行为 | 今天最接近的落地能力 | | --- | --- | --- | -| 💬 **Slack** | 通知、斜杠命令、交易室频道 | 设置 → 集成 → Slack | -| 💬 **Microsoft Teams** | 与 Slack 相同 | 设置 → 集成 → Teams | -| ✍️ **DocuSign** | 发送报价/合同进行电子签名；状态会回流 | 设置 → 集成 → DocuSign | -| 💳 **Stripe** | 客户、订阅、发票同步到客户/合同 | 设置 → 集成 → Stripe | -| 📞 **Twilio Voice** | 点击拨号、通话录音、AI 转录 | 设置 → 集成 → Twilio | -| 📞 **Aircall / RingCentral / Five9** | 与 Twilio 相同 | 设置 → 集成 → 电话系统 | -| 💬 **Intercom / Zendesk Chat** | 在线聊天会话作为工单落地 | 设置 → 集成 → 聊天 | -| 📧 **Gmail / Outlook** | 邮件与日历同步（参见 [邮件与日历](/zh-Hans/docs/guides/email-and-calendar)） | 设置 → 邮件与日历 | -| 📊 **Snowflake / BigQuery / Redshift** | 数据仓库导出 | 设置 → 数据 → 计划导出 | -| 🔗 **Zapier / Make / n8n** | 通向 5,000+ 应用的无代码自动化 | 设置 → 集成 → Webhooks | - -## 每个连接器的功能 +| 💬 **Slack** | 通知、斜杠命令、交易室频道 | 只有应用内通知——`notify` 流程节点送达的是 Console 铃铛，不是 Slack | +| 💬 **Microsoft Teams** | 与 Slack 相同 | 同上 | +| ✍️ **DocuSign** | 发送报价 / 合同进行电子签名；状态回流 | 没有——报价或合同的状态是一个由人手工设置的字段 | +| 💳 **Stripe** | 客户、订阅、发票同步到客户 / 合同 | 没有——合同是在 HotCRM 里编写的 | +| 📞 **Twilio Voice** | 点击拨号、通话录音、AI 转录 | **记录通话** 会在通话*之后*把它写成一条真实的事件；没有任何东西负责拨号、录音或转录 | +| 📞 **Aircall / RingCentral / Five9** | 与 Twilio 相同 | 同上 | +| 💬 **Intercom / Zendesk Chat** | 在线聊天会话作为工单落地 | 工单的**来源**选项列表里有*聊天*，但那是有人建工单时自己选的 | +| 📧 **Gmail / Outlook** | 双向邮件与日历同步 | 联系人上的**发送邮件**——只有出站，没有收件箱连接器。参见[邮件与日历](/zh-Hans/docs/guides/email-and-calendar) | +| 📊 **Snowflake / BigQuery / Redshift** | 每晚增量导出到数据仓库，并配 dbt 模型 | 从列表视图手工导出 CSV / XLSX | +| 🔗 **Zapier / Make / n8n** | 通向 5,000+ 应用的无代码自动化 | 本应用里没有——平台的 webhook 出站队列是存在的，但 HotCRM 没有启用它（见下文） | + +## 每个连接器"本应"做什么（尚未落地） + +作为每一类连接器的设计说明保留下来。请把它当作需求规格来读，而不是操作步骤。 ### 💬 Slack -- **通知**：交易赢单、工单升级、审批、@提及 → 私信或频道。 -- **斜杠命令**：`/hotcrm lookup acme` 获取一个客户；`/hotcrm log call` 从 Slack 记录活动。 -- **交易室**：为超过某个阈值的每个商机自动创建一个 Slack 频道，并邀请客户团队和产品专家加入。 -- **审批操作**：直接从 Slack 批准/拒绝折扣请求。 +设计意图是这样的：交易赢单、工单升级、审批与 @提及推送到私信或频道；斜杠命令（`/hotcrm lookup acme`、`/hotcrm log call`）；为超过某个阈值的每个商机自动创建一个频道，并邀请客户团队与产品专家加入；以及直接在 Slack 里批准 / 拒绝折扣请求。 + +这些事件今天确实会触发——以流程的形式——但它们止步于 Console 铃铛，而审批是在记录上做出的。 ### ✍️ DocuSign -1. 从报价或合同 → 点击 **发送以签名**。 -2. 选择收件人、签署顺序、字段。 -3. DocuSign 向客户发送邮件；状态（已发送 → 已查看 → 已签署）会回流到 HotCRM。 -4. 一旦签署，已签署的 PDF 会作为附件添加，记录的状态会自动更新。 +设计意图是这样的：从报价或合同点击 **发送以签名**，在 HotCRM 里选择收件人、签署顺序与字段，状态（已发送 → 已查看 → 已签署）回流，签署完成的 PDF 落到记录上并自动更新其状态。 + +今天，报价或合同带有状态字段与附件，而推动它们的是人。 ### 💳 Stripe -- Stripe 中的**客户**会按邮件或外部 ID 同步到 HotCRM **客户**。 -- **订阅**同步到**合同** —— 状态、MRR、计费频率。 -- **发票**会显示在客户的活动时间线上。 -- **付款失败**会为客户所有者 / 客户成功经理（CSM）创建一个高优先级工单。 -- **取消**会提醒 CSM 并创建一个流失商机。 +设计意图是这样的：Stripe 的客户按邮件或外部 ID 匹配到客户记录；订阅镜像到合同，带状态、MRR 与计费频率；发票出现在客户的活动时间线上；付款失败为负责人或客户成功经理（CSM）创建高优先级工单；取消则提醒 CSM 并开出一个流失商机。 + +今天这些都不会自己送上门。合同、以及追进合同的任务，都是在 HotCRM 里写出来的——参见[合同](/zh-Hans/docs/revenue/contracts)。 ### 📞 电话系统（Twilio / Aircall / RingCentral / Five9） -- 点击任何电话号码即可拨打 —— 通话会自动记录。 -- 来电会弹出屏幕弹窗，显示联系人、客户、近期工单、近期邮件。 -- 可选的**通话录音** —— 作为音频文件保存在活动上。 -- 每次通话后提供 AI **转录** + **通话摘要**。 +设计意图是这样的：点击电话号码即可拨出，并自动为你记录通话；来电弹出屏幕，显示联系人、客户、近期工单与近期邮件；可选的通话录音作为音频文件保存在活动上；每通电话结束后给出 AI 转录与通话摘要。 + +真实存在的是这个闭环的另一半：任何记录上的**记录通话**都会写入一条事件、参会人行与一条时间线条目——在通话之后，由人手动完成。参见[会议与通话](/zh-Hans/docs/sales/meetings-and-calls)。 ### 💬 在线聊天（Intercom、Zendesk Chat 等） -- 聊天会话会自动作为工单落地。 -- 访客按邮件识别 → 关联到现有联系人 + 客户。 -- 匿名聊天会变成潜在客户。 +设计意图是这样的：聊天会话自动作为工单落地，访客按邮件识别并关联到既有联系人与客户，匿名聊天则变成线索。 + +今天，工单由人或由 API 创建。它的**来源**选项列表里确实提供了*聊天*，但那是有人选中的值，并不能证明真有一场聊天到达过。 ### 📊 数据仓库 -- 每晚对每个 CRM 对象进行增量导出。 -- 为 Snowflake / BigQuery / Redshift 预构建的 dbt 模型。 -- 为 BI 工具（Tableau、Looker、Power BI、Metabase、Hex）提供支持。 +设计意图是这样的：每晚对每个 CRM 对象做增量导出，为 Snowflake / BigQuery / Redshift 提供预构建的 dbt 模型，再由 BI 工具从那里读取。 -## Webhooks（出站） +今天存在的导出是手工的：打开列表视图，导出 CSV 或 XLSX。任何"定时"的部分，都是你的部署基于 HTTP 数据 API 自己搭出来的。 -当 CRM 记录发生变化时触发外部系统。 +## Webhooks（出站）——本应用未启用 -1. **设置 → 集成 → Webhooks → 新建**。 -2. 选择**对象**和**事件**（`created`、`updated`、`deleted`、自定义）。 -3. 添加**条件**（例如，*仅当商机阶段 = Closed Won 时*）。 -4. 设置**目标 URL** 和身份验证（Bearer / Basic / HMAC 签名）。 -5. 选择**载荷结构** —— 完整记录、仅差异，或自定义。 -6. 测试 → 激活。 +这一项不是空话。平台**确实**提供了出站 webhook 服务：`@objectstack/plugin-webhooks` 为每条订阅保存一行 `sys_webhook`——既可以通过该对象自己的管理界面编写，也可以用 `defineStack({ webhooks })` / `defineWebhook()` 在代码里声明——它把记录事件与这些行做匹配，并把每次命中交给共享的消息 HTTP 出站队列去投递。 -Webhooks 会以指数退避方式重试最多 5 次。失败可在**投递日志**中查看。 +**HotCRM 没有启用它。** `objectstack.config.ts` 声明的是 `requires: ['automation', 'triggers', 'analytics', 'auth', 'ui', 'approvals', 'sharing']`。`webhooks` 不在这个列表里，也不属于平台对每个应用都会加载的那一批能力。本应用同样没有声明任何 webhook。因此 HotCRM 今天没有任何 webhook 界面，也没有 `设置 → 集成 → Webhooks` 这样一个页面可去。 -## 入站 Webhooks / HTTP API +> **这是一个部署侧的决定，不是路线图项。** 把 `webhooks` 加进 `requires`，声明你的订阅，此后投递就是平台的事了。本页原先承诺的重试次数、载荷结构选项与投递日志界面，从来就不由 HotCRM 定义——请按你所运行的版本去读平台自己的 webhook 文档，而不是这里。 -外部系统可以通过 REST / GraphQL 创建 / 更新 HotCRM 记录。请参阅 [API 参考](/zh-Hans/docs/customization/api-reference) 了解端点和身份验证。 +## HTTP API -常见模式： +外部系统可以通过运行时的 HTTP 数据 API 创建与更新 HotCRM 记录。对象清单、ObjectQL 筛选形态与身份验证请参见 [API 参考](/zh-Hans/docs/customization/api-reference)。对象名就是本应用注册的那些——`crm_lead`、`crm_account`、`crm_opportunity`——而路由形态取决于你的运行时版本，而非本应用钉住的任何东西，所以请从你自己的环境里读它，而不是从一篇指南里硬编码的路径。 -- 一个**网站表单** → POST 到 `/api/v1/leads` → 创建来源 = *Web* 的新潜在客户。 -- 一个**产品**发送使用数据 → PATCH 客户上的自定义使用字段。 -- 一个**财务系统** → POST 合同激活，从而触发标准合同工作流。 +**没有 GraphQL 端点。** GraphQL 不在产品规划内，平台已经把 `/graphql` 从服务表里移除，而不是继续公告一条没人提供服务的路径。 -## 事件总线（Kafka / EventBridge / Pub/Sub） +常见模式： + +- 一个**网站表单**创建来源 = *Web* 的 `crm_lead`——这已足以触发线索分配流程，它在线索创建时运行。 +- 一个**产品**向 `crm_account` 上的自定义使用量字段发 PATCH。 +- 一个**财务系统**把 `crm_contract` 写成已激活。合同相关的流程是每日扫描（续约提醒、到期），而不是记录变更触发器，因此激活是在下一次扫描时被捕捉到的，而不是落库那一刻。 -对于大批量集成，HotCRM 会将事件发布到可配置的事件总线。 +## 事件总线（尚未落地） -- **所有记录生命周期事件**（`created`、`updated`、`deleted`）。 -- **领域事件**（opportunity_won、contract_activated、case_escalated、approval_granted）。 -- 在 [@objectstack/spec](/zh-Hans/docs/customization/index) 仓库中使用版本化的结构进行**结构校验**。 +设计意图是这样的：HotCRM 把所有记录生命周期事件、以及领域事件（`opportunity_won`、`contract_activated`、`case_escalated`、`approval_granted`）发布到一个可配置的 Kafka / EventBridge / Pub-Sub 总线上，并用版本化的结构做校验。 -在 **设置 → 集成 → 事件总线** 中配置。 +并不存在这样一项能力。平台的能力清单里没有事件总线这个词条，因此既没有可配置的东西，也没有 `设置 → 集成 → 事件总线` 这个页面。记录事件本身是真实的——它们在进程内驱动记录变更流程——而上文那个 webhook 出站队列，就是部署一旦启用后的进程外通路。 ## 构建自定义集成 -如果你需要的连接器不是内置的，你有三种选择，从简单到强大排列： +其中两条路今天是真的，一条不是。 + +### 1. 服务器到服务器脚本（真实） -### 1. Zapier / Make / n8n（无代码） +从脚本（cron 作业、Lambda、GitHub Action）调用 HTTP 数据 API。参见 [API 参考](/zh-Hans/docs/customization/api-reference)。 -在 **设置 → 集成 → Webhooks** 中设置 webhooks 和一个入站端点，然后使用 Zapier 桥接到任何应用。 +最适合：计划内的同步、内部工具，以及任何你希望自己掌控可靠性的场景。 -最适合：系统之间简单的字段同步、小型团队。 +### 2. 进程内扩展代码（真实） -### 2. 服务器到服务器脚本 +钩子、流程与操作体在 HotCRM 内部运行，针对同一批对象、同一套权限校验。参见[自定义 › 扩展对象](/zh-Hans/docs/customization/extending-objects)。 -使用 REST API 从脚本（cron 作业、AWS Lambda、GitHub Action）调用 HotCRM。请参阅 [API 参考](/zh-Hans/docs/customization/api-reference)。 +最适合：无论是谁发起的写入都必须执行的逻辑。 -最适合：计划同步、内部工具，以及任何比无代码工具更可靠的需求。 +### 3. 无代码桥接 —— Zapier / Make / n8n（需先启用 webhooks） -### 3. 原生插件 +无代码桥接需要一个出站触发器，因此它依赖上文那个 webhook 服务在你的部署里被启用。启用它，Zapier 那一侧就是常规工作；不启用，Zapier 就没有任何东西可以订阅。 -构建一个 `*.connector.ts` 插件，它驻留在 HotCRM 内部，具有一流的生命周期（认证、同步、监控）。请参阅 [自定义 › 扩展对象](/zh-Hans/docs/customization/extending-objects)。 +### 原生 `*.connector.ts` 插件（尚未落地） -最适合：你将交付给其他 HotCRM 客户的集成；需要双向同步和可观测性的集成。 +本页较早的版本曾提供一种连接器插件形态，带一流的生命周期——认证、同步、监控——面向你要交付给其他 HotCRM 客户的集成。并不存在这样一个编写面。规格里确实带有 `connector_action` 流程节点，但没有任何东西为它注册连接器：本应用自己的审批流程就记录着，它那个 ADR-0019 之前的 `connectorId: 'approval'` 节点已不再被注册，只能改写成原生的审批节点。 -## 认证与密钥 +## 认证与密钥（尚未落地） -所有集成凭据都存储在平台的密钥存储中（HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager —— 可配置）。 +设计意图是这样的：所有集成凭据都存放在平台的密钥存储中（HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager，可配置），只做引用而不粘贴进工作流或钩子代码，OAuth 刷新令牌每 90 天自动轮换，并为每一次密钥访问留下审计日志条目。 -- **切勿**将令牌粘贴到工作流 / 钩子代码中 —— 始终从密钥存储引用。 -- 每 90 天自动**轮换** OAuth 刷新令牌。 -- **审计日志**记录每一次密钥访问。 +HotCRM 并不持有任何集成凭据——既没有连接器需要它，也没有 OAuth 授权可轮换——而平台的能力清单里也没有可供配置的密钥存储能力。真实存在的东西在低一层：类型为 `secret` 的字段会经由部署所注册的加密提供方（开发期用本地的，生产环境用 KMS 或 Vault 提供方）加密后写入 `sys_secret`，且当没有注册任何提供方时，写入会**失败关闭**，而不是存明文。本应用今天没有编写任何 `secret` 字段。 ## 给管理员的提示 -- ✅ **首先连接 Slack** —— 对第 1 天采用率的提升最大。 -- ✅ 为通话频繁的团队**连接电话系统** —— 消除"Alex 到底有没有记录这通电话？"的盲区。 -- ✅ 用 **DocuSign** 来成交 —— "在 DocuSign 中已签署"与"在 CRM 中标记为赢单"之间的鸿沟正是交易夭折之处。 -- ✅ 对每个集成，每周**监控投递日志** —— webhook 失败会悄无声息地堆积。 -- ✅ 一旦你有 >3 个下游消费者，就使用**事件总线**而非 webhooks —— 扩展性更好。 +- ✅ 围绕 **HTTP 数据 API** 来规划集成——它是真实存在的那个面，而且触达每一个对象。 +- ✅ 需要出站事件？请在你的部署里启用平台的 **webhook** 能力，而不是等某个厂商连接器。 +- ✅ 在告诉销售代表**发送邮件**能送达之前，先配置好真正的邮件传输方式。什么都没配时，平台只会把消息记进日志，什么也不发。 +- ✅ 把上文每一个 *（尚未落地）* 小节当作需求文档来读，而不是配置指南——并关注[路线图](/zh-Hans/docs/whats-new)。 diff --git a/content/docs/guides/integrations.zh-Hant.mdx b/content/docs/guides/integrations.zh-Hant.mdx index d2b1a3de8..c92cf2d04 100644 --- a/content/docs/guides/integrations.zh-Hant.mdx +++ b/content/docs/guides/integrations.zh-Hant.mdx @@ -1,137 +1,139 @@ --- title: 整合 -description: 將 HotCRM 連接到 Slack、Teams、DocuSign、Stripe、電話系統和其他工具 —— 以及如何建構你自己的整合。 +description: HotCRM 今天真正對外暴露了什麼——資料 API、清單檢視匯出、對外郵件——以及哪些成套連接器仍是路線圖上的設計意圖。 --- # 整合 -HotCRM 的設計目標是**融入你的技術棧**，而非取代它。本頁列出了受支援的整合，以及如何將 HotCRM 接入你業務系統的其餘部分。 +HotCRM 的設計目標是**融入你的技術堆疊**，而非取代它。今天它靠平台自身的幾條邊界做到這一點：資料 API、試算表匯入與匯出、對外郵件，以及你自己撰寫的自動化。它目前還做不到的，是提供**成套的廠商連接器**——`src/` 裡沒有任何連接器中繼資料，也不存在可用來設定連接器的 **設定 → 整合** 選單。 -## 內建連接器 +> **在照著任何設定步驟操作之前，先讀這一段。** 下文所有標註 *（尚未落地）* 的小節，描述的是相應整合的**設計意圖**——它在[路線圖](/zh-Hant/docs/whats-new)上，而不是今天可以打開的開關。未標註的小節，才是應用當前真正對外暴露的能力。路線圖上對應的那一行寫的是：*「更多連接器 —— Slack、Microsoft Teams、Google Workspace、HubSpot 匯入」*。 -| 工具 | 功能 | 設定位置 | +## 今天已落地的能力 + +- 🔌 **平台資料 API**——每個 CRM 物件都可以透過執行階段的 HTTP API 存取，支援 ObjectQL 形態的篩選與欄位選擇。參見 [API 參考](/zh-Hant/docs/customization/api-reference)。 +- 📤 **清單檢視的 CSV / XLSX 匯出**——客戶、聯絡人、潛在客戶與商機的清單檢視各自宣告了 `exportOptions: ['csv', 'xlsx']`。 +- 📥 **試算表匯入**，帶可重複使用的欄位對應，並可先試算。參見[匯入你自己的資料](/zh-Hant/docs/guides/importing-your-data)。 +- ✉️ **對外郵件**——聯絡人上的**傳送郵件**，把郵件排入平台郵件服務。只有出站方向，而且只有在部署設定了傳輸方式時才真的寄得出去。參見[郵件與行事曆](/zh-Hant/docs/guides/email-and-calendar)。 +- 🔔 **應用內通知**——`notify` 流程節點經平台訊息服務送達 Console 鈴鐺。是在 HotCRM 內部，而不是送進 Slack 或某個收件匣。 +- 🧩 **你自己的程式碼**——掛鉤、流程與操作主體在行程內針對同一批物件、同一套權限檢查執行。參見[自訂 › 擴充物件](/zh-Hant/docs/customization/extending-objects)。 + +## 內建連接器（尚未落地） + +下面這份陣容是**設計意圖**——保留它，是因為它標出了產品要去的方向。這些東西一樣都不在盒子裡：`src/` 裡沒有連接器中繼資料，平台套件裡也沒有對應的連接器外掛，更**沒有 `設定 → 整合` 選單**。這張表原先印出的那些設定路徑，是本頁最具誤導性的部分：照著走的人，去找的是一個並不存在的畫面。 + +| 工具 | 設計意圖中的行為 | 今天最接近的落地能力 | | --- | --- | --- | -| 💬 **Slack** | 通知、斜線命令、交易室頻道 | 設定 → 整合 → Slack | -| 💬 **Microsoft Teams** | 與 Slack 相同 | 設定 → 整合 → Teams | -| ✍️ **DocuSign** | 傳送報價/合約進行電子簽名；狀態會回流 | 設定 → 整合 → DocuSign | -| 💳 **Stripe** | 客戶、訂閱、發票同步到客戶/合約 | 設定 → 整合 → Stripe | -| 📞 **Twilio Voice** | 點擊撥號、通話錄音、AI 轉錄 | 設定 → 整合 → Twilio | -| 📞 **Aircall / RingCentral / Five9** | 與 Twilio 相同 | 設定 → 整合 → 電話系統 | -| 💬 **Intercom / Zendesk Chat** | 線上聊天會話作為工單落地 | 設定 → 整合 → 聊天 | -| 📧 **Gmail / Outlook** | 郵件與行事曆同步（參見 [郵件與行事曆](/zh-Hant/docs/guides/email-and-calendar)） | 設定 → 郵件與行事曆 | -| 📊 **Snowflake / BigQuery / Redshift** | 資料倉儲匯出 | 設定 → 資料 → 排程匯出 | -| 🔗 **Zapier / Make / n8n** | 通向 5,000+ 應用的無程式碼自動化 | 設定 → 整合 → Webhooks | - -## 每個連接器的功能 +| 💬 **Slack** | 通知、斜線命令、交易室頻道 | 只有應用內通知——`notify` 流程節點送達的是 Console 鈴鐺，不是 Slack | +| 💬 **Microsoft Teams** | 與 Slack 相同 | 同上 | +| ✍️ **DocuSign** | 傳送報價 / 合約進行電子簽名；狀態回流 | 沒有——報價或合約的狀態是一個由人手動設定的欄位 | +| 💳 **Stripe** | 客戶、訂閱、發票同步到客戶 / 合約 | 沒有——合約是在 HotCRM 裡撰寫的 | +| 📞 **Twilio Voice** | 點擊撥號、通話錄音、AI 轉錄 | **記錄通話** 會在通話*之後*把它寫成一筆真實的活動事件；沒有任何東西負責撥號、錄音或轉錄 | +| 📞 **Aircall / RingCentral / Five9** | 與 Twilio 相同 | 同上 | +| 💬 **Intercom / Zendesk Chat** | 線上聊天會話作為工單落地 | 工單的**來源**選項清單裡有*聊天*，但那是有人建立工單時自己選的 | +| 📧 **Gmail / Outlook** | 雙向郵件與行事曆同步 | 聯絡人上的**傳送郵件**——只有出站，沒有收件匣連接器。參見[郵件與行事曆](/zh-Hant/docs/guides/email-and-calendar) | +| 📊 **Snowflake / BigQuery / Redshift** | 每晚增量匯出到資料倉儲，並配 dbt 模型 | 從清單檢視手動匯出 CSV / XLSX | +| 🔗 **Zapier / Make / n8n** | 通往 5,000+ 應用的無程式碼自動化 | 本應用裡沒有——平台的 webhook 出站佇列是存在的，但 HotCRM 沒有啟用它（見下文） | + +## 每個連接器「本應」做什麼（尚未落地） + +作為每一類連接器的設計說明保留下來。請把它當作需求規格來讀，而不是操作步驟。 ### 💬 Slack -- **通知**：交易贏單、工單升級、審核、@提及 → 私訊或頻道。 -- **斜線命令**：`/hotcrm lookup acme` 取得一個客戶；`/hotcrm log call` 從 Slack 記錄活動。 -- **交易室**：為超過某個閾值的每個商機自動建立一個 Slack 頻道，並邀請客戶團隊和產品專家加入。 -- **審核操作**：直接從 Slack 核准/拒絕折扣請求。 +設計意圖是這樣的：交易贏單、工單升級、簽核與 @提及推送到私訊或頻道；斜線命令（`/hotcrm lookup acme`、`/hotcrm log call`）；為超過某個門檻的每個商機自動建立一個頻道，並邀請客戶團隊與產品專家加入；以及直接在 Slack 裡核准 / 拒絕折扣請求。 + +這些事件今天確實會觸發——以流程的形式——但它們止步於 Console 鈴鐺，而簽核是在記錄上做出的。 ### ✍️ DocuSign -1. 從報價或合約 → 點擊 **傳送以簽名**。 -2. 選擇收件人、簽署順序、欄位。 -3. DocuSign 向客戶傳送郵件；狀態（已傳送 → 已查看 → 已簽署）會回流到 HotCRM。 -4. 一旦簽署，已簽署的 PDF 會作為附件新增，記錄的狀態會自動更新。 +設計意圖是這樣的：從報價或合約點擊 **傳送以簽名**，在 HotCRM 裡選擇收件人、簽署順序與欄位，狀態（已傳送 → 已檢視 → 已簽署）回流，簽署完成的 PDF 落到記錄上並自動更新其狀態。 + +今天，報價或合約帶有狀態欄位與附件，而推動它們的是人。 ### 💳 Stripe -- Stripe 中的**客戶**會按郵件或外部 ID 同步到 HotCRM **客戶**。 -- **訂閱**同步到**合約** —— 狀態、MRR、計費頻率。 -- **發票**會顯示在客戶的活動時間軸上。 -- **付款失敗**會為客戶擁有者 / 客戶成功經理（CSM）建立一個高優先級工單。 -- **取消**會提醒 CSM 並建立一個流失商機。 +設計意圖是這樣的：Stripe 的客戶按郵件或外部 ID 比對到客戶記錄；訂閱鏡像到合約，帶狀態、MRR 與計費頻率；發票出現在客戶的活動時間軸上；付款失敗為負責人或客戶成功經理（CSM）建立高優先級工單；取消則提醒 CSM 並開出一個流失商機。 + +今天這些都不會自己送上門。合約、以及追進合約的任務，都是在 HotCRM 裡寫出來的——參見[合約](/zh-Hant/docs/revenue/contracts)。 ### 📞 電話系統（Twilio / Aircall / RingCentral / Five9） -- 點擊任何電話號碼即可撥打 —— 通話會自動記錄。 -- 來電會彈出螢幕彈窗，顯示聯絡人、客戶、近期工單、近期郵件。 -- 可選的**通話錄音** —— 作為音訊檔案儲存在活動上。 -- 每次通話後提供 AI **轉錄** + **通話摘要**。 +設計意圖是這樣的：點擊電話號碼即可撥出，並自動為你記錄通話；來電彈出畫面，顯示聯絡人、客戶、近期工單與近期郵件；可選的通話錄音作為音訊檔案保存在活動上；每通電話結束後給出 AI 轉錄與通話摘要。 + +真實存在的是這個閉環的另一半：任何記錄上的**記錄通話**都會寫入一筆活動事件、與會人列與一條時間軸條目——在通話之後，由人手動完成。參見[會議與通話](/zh-Hant/docs/sales/meetings-and-calls)。 ### 💬 線上聊天（Intercom、Zendesk Chat 等） -- 聊天會話會自動作為工單落地。 -- 訪客按郵件識別 → 關聯到現有聯絡人 + 客戶。 -- 匿名聊天會變成潛在客戶。 +設計意圖是這樣的：聊天會話自動作為工單落地，訪客按郵件識別並關聯到既有聯絡人與客戶，匿名聊天則變成潛在客戶。 + +今天，工單由人或由 API 建立。它的**來源**選項清單裡確實提供了*聊天*，但那是有人選中的值，並不能證明真有一場聊天到達過。 ### 📊 資料倉儲 -- 每晚對每個 CRM 物件進行增量匯出。 -- 為 Snowflake / BigQuery / Redshift 預先建構的 dbt 模型。 -- 為 BI 工具（Tableau、Looker、Power BI、Metabase、Hex）提供支援。 +設計意圖是這樣的：每晚對每個 CRM 物件做增量匯出，為 Snowflake / BigQuery / Redshift 提供預先建置的 dbt 模型，再由 BI 工具從那裡讀取。 -## Webhooks（出站） +今天存在的匯出是手動的：打開清單檢視，匯出 CSV 或 XLSX。任何「定時」的部分，都是你的部署基於 HTTP 資料 API 自己搭出來的。 -當 CRM 記錄發生變化時觸發外部系統。 +## Webhooks（出站）——本應用未啟用 -1. **設定 → 整合 → Webhooks → 新增**。 -2. 選擇**物件**和**事件**（`created`、`updated`、`deleted`、自訂）。 -3. 新增**條件**（例如，*僅當商機階段 = Closed Won 時*）。 -4. 設定**目標 URL** 和身分驗證（Bearer / Basic / HMAC 簽名）。 -5. 選擇**載荷結構** —— 完整記錄、僅差異，或自訂。 -6. 測試 → 啟用。 +這一項不是空話。平台**確實**提供了出站 webhook 服務：`@objectstack/plugin-webhooks` 為每筆訂閱保存一列 `sys_webhook`——既可以透過該物件自己的管理介面撰寫，也可以用 `defineStack({ webhooks })` / `defineWebhook()` 在程式碼裡宣告——它把記錄事件與這些列做比對，並把每次命中交給共享的訊息 HTTP 出站佇列去投遞。 -Webhooks 會以指數退避方式重試最多 5 次。失敗可在**投遞日誌**中查看。 +**HotCRM 沒有啟用它。** `objectstack.config.ts` 宣告的是 `requires: ['automation', 'triggers', 'analytics', 'auth', 'ui', 'approvals', 'sharing']`。`webhooks` 不在這個清單裡，也不屬於平台對每個應用都會載入的那一批能力。本應用同樣沒有宣告任何 webhook。因此 HotCRM 今天沒有任何 webhook 介面，也沒有 `設定 → 整合 → Webhooks` 這樣一個頁面可去。 -## 入站 Webhooks / HTTP API +> **這是一個部署側的決定，不是路線圖項目。** 把 `webhooks` 加進 `requires`，宣告你的訂閱，此後投遞就是平台的事了。本頁原先承諾的重試次數、酬載結構選項與投遞紀錄畫面，從來就不由 HotCRM 定義——請按你所執行的版本去讀平台自己的 webhook 文件，而不是這裡。 -外部系統可以透過 REST / GraphQL 建立 / 更新 HotCRM 記錄。請參閱 [API 參考](/zh-Hant/docs/customization/api-reference) 了解端點和身分驗證。 +## HTTP API -常見模式： +外部系統可以透過執行階段的 HTTP 資料 API 建立與更新 HotCRM 記錄。物件清單、ObjectQL 篩選形態與身分驗證請參見 [API 參考](/zh-Hant/docs/customization/api-reference)。物件名稱就是本應用註冊的那些——`crm_lead`、`crm_account`、`crm_opportunity`——而路由形態取決於你的執行階段版本，而非本應用釘住的任何東西，所以請從你自己的環境裡讀它，而不是從一篇指南裡硬編碼的路徑。 -- 一個**網站表單** → POST 到 `/api/v1/leads` → 建立來源 = *Web* 的新潛在客戶。 -- 一個**產品**傳送使用資料 → PATCH 客戶上的自訂使用欄位。 -- 一個**財務系統** → POST 合約啟用，從而觸發標準合約工作流。 +**沒有 GraphQL 端點。** GraphQL 不在產品規劃內，平台已經把 `/graphql` 從服務表裡移除，而不是繼續公告一條沒人提供服務的路徑。 -## 事件匯流排（Kafka / EventBridge / Pub/Sub） +常見模式： + +- 一個**網站表單**建立來源 = *Web* 的 `crm_lead`——這已足以觸發潛在客戶指派流程，它在潛在客戶建立時執行。 +- 一個**產品**向 `crm_account` 上的自訂使用量欄位發 PATCH。 +- 一個**財務系統**把 `crm_contract` 寫成已啟用。合約相關的流程是每日掃描（續約提醒、到期），而不是記錄變更觸發器，因此啟用是在下一次掃描時被捕捉到的，而不是落庫那一刻。 -對於大批量整合，HotCRM 會將事件發布到可配置的事件匯流排。 +## 事件匯流排（尚未落地） -- **所有記錄生命週期事件**（`created`、`updated`、`deleted`）。 -- **領域事件**（opportunity_won、contract_activated、case_escalated、approval_granted）。 -- 在 [@objectstack/spec](/zh-Hant/docs/customization/index) 儲存庫中使用版本化的結構進行**結構校驗**。 +設計意圖是這樣的：HotCRM 把所有記錄生命週期事件、以及領域事件（`opportunity_won`、`contract_activated`、`case_escalated`、`approval_granted`）發布到一個可設定的 Kafka / EventBridge / Pub-Sub 匯流排上，並用版本化的結構做驗證。 -在 **設定 → 整合 → 事件匯流排** 中配置。 +並不存在這樣一項能力。平台的能力清單裡沒有事件匯流排這個詞條，因此既沒有可設定的東西，也沒有 `設定 → 整合 → 事件匯流排` 這個頁面。記錄事件本身是真實的——它們在行程內驅動記錄變更流程——而上文那個 webhook 出站佇列，就是部署一旦啟用後的行程外通路。 ## 建構自訂整合 -如果你需要的連接器不是內建的，你有三種選擇，從簡單到強大排列： +其中兩條路今天是真的，一條不是。 + +### 1. 伺服器對伺服器腳本（真實） -### 1. Zapier / Make / n8n（無程式碼） +從腳本（cron 作業、Lambda、GitHub Action）呼叫 HTTP 資料 API。參見 [API 參考](/zh-Hant/docs/customization/api-reference)。 -在 **設定 → 整合 → Webhooks** 中設定 webhooks 和一個入站端點，然後使用 Zapier 橋接到任何應用。 +最適合：計畫內的同步、內部工具，以及任何你希望自己掌控可靠性的場景。 -最適合：系統之間簡單的欄位同步、小型團隊。 +### 2. 行程內擴充程式碼（真實） -### 2. 伺服器到伺服器指令碼 +掛鉤、流程與操作主體在 HotCRM 內部執行，針對同一批物件、同一套權限檢查。參見[自訂 › 擴充物件](/zh-Hant/docs/customization/extending-objects)。 -使用 REST API 從指令碼（cron 作業、AWS Lambda、GitHub Action）呼叫 HotCRM。請參閱 [API 參考](/zh-Hant/docs/customization/api-reference)。 +最適合：無論是誰發起的寫入都必須執行的邏輯。 -最適合：排程同步、內部工具，以及任何比無程式碼工具更可靠的需求。 +### 3. 無程式碼橋接 —— Zapier / Make / n8n（需先啟用 webhooks） -### 3. 原生外掛 +無程式碼橋接需要一個出站觸發器，因此它依賴上文那個 webhook 服務在你的部署裡被啟用。啟用它，Zapier 那一側就是常規工作；不啟用，Zapier 就沒有任何東西可以訂閱。 -建構一個 `*.connector.ts` 外掛，它駐留在 HotCRM 內部，具有一流的生命週期（認證、同步、監控）。請參閱 [自訂 › 擴充物件](/zh-Hant/docs/customization/extending-objects)。 +### 原生 `*.connector.ts` 外掛（尚未落地） -最適合：你將交付給其他 HotCRM 客戶的整合；需要雙向同步和可觀測性的整合。 +本頁較早的版本曾提供一種連接器外掛形態，帶一流的生命週期——認證、同步、監控——面向你要交付給其他 HotCRM 客戶的整合。並不存在這樣一個撰寫面。規格裡確實帶有 `connector_action` 流程節點，但沒有任何東西為它註冊連接器：本應用自己的簽核流程就記錄著，它那個 ADR-0019 之前的 `connectorId: 'approval'` 節點已不再被註冊，只能改寫成原生的簽核節點。 -## 認證與密鑰 +## 認證與密鑰（尚未落地） -所有整合憑證都儲存在平台的密鑰儲存中（HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager —— 可配置）。 +設計意圖是這樣的：所有整合憑證都存放在平台的密鑰儲存中（HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager，可設定），只做引用而不貼進工作流或掛鉤程式碼，OAuth 更新權杖每 90 天自動輪換，並為每一次密鑰存取留下稽核紀錄條目。 -- **切勿**將權杖貼到工作流 / 鉤子程式碼中 —— 始終從密鑰儲存引用。 -- 每 90 天自動**輪換** OAuth 重新整理權杖。 -- **稽核日誌**記錄每一次密鑰存取。 +HotCRM 並不持有任何整合憑證——既沒有連接器需要它，也沒有 OAuth 授權可輪換——而平台的能力清單裡也沒有可供設定的密鑰儲存能力。真實存在的東西在低一層：型別為 `secret` 的欄位會經由部署所註冊的加密提供者（開發期用本機的，正式環境用 KMS 或 Vault 提供者）加密後寫入 `sys_secret`，且當沒有註冊任何提供者時，寫入會**失敗關閉**，而不是存明文。本應用今天沒有撰寫任何 `secret` 欄位。 ## 給管理員的提示 -- ✅ **首先連接 Slack** —— 對第 1 天採用率的提升最大。 -- ✅ 為通話頻繁的團隊**連接電話系統** —— 消除「Alex 到底有沒有記錄這通電話？」的盲區。 -- ✅ 用 **DocuSign** 來成交 —— 「在 DocuSign 中已簽署」與「在 CRM 中標記為贏單」之間的鴻溝正是交易夭折之處。 -- ✅ 對每個整合，每週**監控投遞日誌** —— webhook 失敗會悄無聲息地堆積。 -- ✅ 一旦你有 >3 個下游消費者，就使用**事件匯流排**而非 webhooks —— 擴展性更好。 +- ✅ 圍繞 **HTTP 資料 API** 來規劃整合——它是真實存在的那個面，而且觸達每一個物件。 +- ✅ 需要出站事件？請在你的部署裡啟用平台的 **webhook** 能力，而不是等某個廠商連接器。 +- ✅ 在告訴業務代表**傳送郵件**能送達之前，先設定好真正的郵件傳輸方式。什麼都沒設定時，平台只會把訊息記進日誌，什麼也不寄。 +- ✅ 把上文每一個 *（尚未落地）* 小節當作需求文件來讀，而不是設定指南——並關注[路線圖](/zh-Hant/docs/whats-new)。