637 lines
34 KiB
Markdown
637 lines
34 KiB
Markdown
# M12 平台与集成 — Chatwoot 功能梳理文档
|
||
|
||
> 基于 Chatwoot 源码深度阅读 + CodeGraph 上下文梳理
|
||
> 生成日期：2026-05-22
|
||
> 参照仓库：chatwoot-reference
|
||
> 模块覆盖：PlatformApp · AgentBot · DashboardApp · DataImport · Webhook · AccessToken认证 · InstallationConfig
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [PlatformApp（平台应用 / Partner API）](#1-platformapp平台应用--partner-api)
|
||
2. [PlatformAppPermissible（权限授权）](#2-platformapppermissible权限授权)
|
||
3. [Platform API 路由体系](#3-platform-api-路由体系)
|
||
4. [AccessToken 与 AccessTokenable（API令牌认证）](#4-accesstoken-与-accesstokenableapi令牌认证)
|
||
5. [AccessTokenAuthHelper（令牌鉴权中间件）](#5-accesstokenauthhelper令牌鉴权中间件)
|
||
6. [AgentBot（智能机器人）](#6-agentbot智能机器人)
|
||
7. [AgentBotInbox（Bot-Inbox绑定）](#7-agentbotinboxbot-inbox绑定)
|
||
8. [AgentBotListener（Bot事件监听）](#8-agentbotlistenerbot事件监听)
|
||
9. [AgentBots::WebhookJob（Bot Webhook投递）](#9-agentbotswebhookjobbot-webhook投递)
|
||
10. [DashboardApp（仪表盘扩展应用）](#10-dashboardapp仪表盘扩展应用)
|
||
11. [DataImport（数据导入）](#11-dataimport数据导入)
|
||
12. [DataImportJob + ContactManager（导入处理流程）](#12-dataimportjob--contactmanager导入处理流程)
|
||
13. [Webhook（账户级Webhook）](#13-webhook账户级webhook)
|
||
14. [WebhookSecretable（签名密钥机制）](#14-webhooksecretable签名密钥机制)
|
||
15. [Webhooks::Trigger（Webhook投递引擎）](#15-webhookstriggerwebhook投递引擎)
|
||
16. [InstallationConfig（平台级配置）](#16-installationconfig平台级配置)
|
||
17. [GlobalConfig + GlobalConfigService（配置缓存层）](#17-globalconfig--globalconfigservice配置缓存层)
|
||
|
||
---
|
||
|
||
## 1. PlatformApp（平台应用 / Partner API）
|
||
|
||
### 功能描述
|
||
PlatformApp 是 Chatwoot 为第三方合作伙伴（Partner）提供的平台级 API 认证主体。每个 PlatformApp 拥有一个 AccessToken，通过该令牌可调用 Platform API（独立于普通 Account API），实现对用户、账户、AgentBot、AccountUser 等资源的 CRUD 管理。PlatformApp 与被操作资源之间通过 `PlatformAppPermissible` 多态关联授权——只有被授权的资源才能被该 PlatformApp 访问/修改。
|
||
|
||
### 用户操作流程
|
||
1. Super Admin 在后台创建 PlatformApp，系统自动生成 AccessToken
|
||
2. 第三方系统持有该 AccessToken，通过 `api_access_token` Header 调用 Platform API
|
||
3. PlatformController 验证令牌 → 解析出 PlatformApp → 校验 Permissible 授权范围
|
||
4. 通过授权校验后，第三方可操作被授权的 Account / User / AgentBot 等资源
|
||
5. 第三方可通过 `POST /platform/api/v1/users/:id/token` 获取用户的 SSO 登录令牌
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| Super Admin CRUD | `/super_admin/platform_apps` | 管理后台管理 PlatformApp |
|
||
| GET | `/platform/api/v1/users` | 列出授权用户（需 Permissible） |
|
||
| POST | `/platform/api/v1/users` | 创建用户并自动授权 |
|
||
| GET | `/platform/api/v1/users/:id` | 查看（需 Permissible） |
|
||
| PATCH | `/platform/api/v1/users/:id` | 更新（需 Permissible） |
|
||
| DELETE | `/platform/api/v1/users/:id` | 删除（需 Permissible） |
|
||
| GET | `/platform/api/v1/users/:id/login` | 获取用户 SSO 登录 URL |
|
||
| POST | `/platform/api/v1/users/:id/token` | 获取用户 API Token |
|
||
| GET | `/platform/api/v1/accounts` | 列出授权账户 |
|
||
| POST | `/platform/api/v1/accounts` | 创建账户并授权 |
|
||
| GET | `/platform/api/v1/accounts/:id` | 查看授权账户 |
|
||
| PATCH | `/platform/api/v1/accounts/:id` | 更新授权账户（含 features/limits） |
|
||
| DELETE | `/platform/api/v1/accounts/:id` | 删除授权账户 |
|
||
| GET | `/platform/api/v1/accounts/:account_id/account_users` | 列出账户成员 |
|
||
| POST | `/platform/api/v1/accounts/:account_id/account_users` | 添加账户成员 |
|
||
| DELETE | `/platform/api/v1/accounts/:account_id/account_users` | 移除账户成员 |
|
||
| GET | `/platform/api/v1/agent_bots` | 列出授权 AgentBot |
|
||
| POST | `/platform/api/v1/agent_bots` | 创建 AgentBot 并授权 |
|
||
| GET | `/platform/api/v1/agent_bots/:id` | 查看授权 AgentBot |
|
||
| PATCH | `/platform/api/v1/agent_bots/:id` | 更新授权 AgentBot |
|
||
| DELETE | `/platform/api/v1/agent_bots/:id` | 删除授权 AgentBot |
|
||
| DELETE | `/platform/api/v1/agent_bots/:id/avatar` | 删除 AgentBot 头像 |
|
||
| POST | `/platform/api/v1/accounts/:account_id/email_channel_migrations` | 执行邮箱渠道迁移 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **PlatformApp**（`platform_apps` 表）：
|
||
- `id` (bigint, PK)
|
||
- `name` (string, NOT NULL) — 应用名称
|
||
- `created_at`, `updated_at` (datetime)
|
||
- 关联：`has_many :platform_app_permissibles, dependent: :destroy_async`
|
||
- Concern：`include AccessTokenable`（创建时自动生成 AccessToken）
|
||
- 验证：`validates :name, presence: true`
|
||
|
||
### 涉及的业务逻辑
|
||
- **PlatformApp 创建时**：`AccessTokenable` concern 的 `after_create :create_access_token` 自动创建 AccessToken
|
||
- **PlatformController**（`app/controllers/platform_controller.rb`）：全局鉴权基类
|
||
- `ensure_access_token` — 从 Header 中解析 `api_access_token`
|
||
- `set_platform_app` — 从 AccessToken owner 解析出 PlatformApp，否则返回 401
|
||
- `validate_platform_app_permissible` — 校验当前资源是否在 Permissible 授权范围内
|
||
- **各子 Controller**：继承 PlatformController，在 create 操作时自动创建 Permissible 授权关系
|
||
|
||
---
|
||
|
||
## 2. PlatformAppPermissible（权限授权）
|
||
|
||
### 功能描述
|
||
PlatformAppPermissible 是 PlatformApp 与被授权资源之间的多态授权桥梁。每个 Permissible 记录代表"某 PlatformApp 可以操作某资源"。资源类型可以是 Account、User、AgentBot 等。创建用户/账户/AgentBot 时，子控制器会自动为 PlatformApp 添加 Permissible 记录。
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **PlatformAppPermissible**（`platform_app_permissibles` 表）：
|
||
- `id` (bigint, PK)
|
||
- `platform_app_id` (bigint, NOT NULL) — 所属 PlatformApp
|
||
- `permissible_id` (bigint, NOT NULL) — 被授权资源 ID
|
||
- `permissible_type` (string, NOT NULL) — 被授权资源类型（Account / User / AgentBot 等）
|
||
- `created_at`, `updated_at` (datetime)
|
||
- 索引：
|
||
- `index_platform_app_permissibles_on_permissibles` — (permissible_type, permissible_id)
|
||
- `index_platform_app_permissibles_on_platform_app_id` — (platform_app_id)
|
||
- `unique_permissibles_index` — (platform_app_id, permissible_id, permissible_type) UNIQUE
|
||
- 关联：`belongs_to :platform_app`, `belongs_to :permissible, polymorphic: true`
|
||
- 验证：`validates :platform_app, presence: true`; uniqueness scoped by `[permissible_id, permissible_type]`
|
||
|
||
### 涉及的业务逻辑
|
||
- **授权校验**：`PlatformController#validate_platform_app_permissible` 查询 `platform_app_permissibles.find_by(permissible: @resource)`，不在授权范围内返回 401
|
||
- **自动授权**：
|
||
- `UsersController#create` → `find_or_create_by(permissible: @resource)`
|
||
- `AccountsController#create` → `find_or_create_by(permissible: @resource)`
|
||
- `AgentBotsController#create` → `find_or_create_by(permissible: @resource)`
|
||
- **查询授权资源**：
|
||
- `AccountsController#index` → 查询 `where(permissible_type: 'Account')` 并 includes permissible
|
||
- `AgentBotsController#index` → 查询 `where(permissible_type: 'AgentBot')`
|
||
|
||
---
|
||
|
||
## 3. Platform API 路由体系
|
||
|
||
### 功能描述
|
||
Platform API 是 Chatwoot 提供给合作伙伴的独立 API 套件，使用 AccessToken（而非 User session）鉴权，路由独立于 Account API 体系。所有 Platform API 控制器继承 `PlatformController`，统一走 AccessToken + Permissible 双重校验。
|
||
|
||
### 路由结构
|
||
```
|
||
namespace :platform, defaults: { format: 'json' } do
|
||
namespace :api do
|
||
namespace :v1 do
|
||
resources :users, only: [:create, :show, :update, :destroy]
|
||
member do
|
||
get :login # SSO 登录链接
|
||
post :token # 获取用户 API token
|
||
end
|
||
resources :agent_bots, only: [:index, :create, :show, :update, :destroy]
|
||
member do
|
||
delete :avatar # 删除头像
|
||
end
|
||
resources :accounts, only: [:index, :create, :show, :update, :destroy]
|
||
resources :account_users, only: [:index, :create]
|
||
collection do
|
||
delete :destroy # 移除成员
|
||
end
|
||
resources :email_channel_migrations, only: [:create]
|
||
end
|
||
end
|
||
end
|
||
```
|
||
|
||
### 控制器矩阵
|
||
| Controller | 基类 | 特殊 before_action |
|
||
|------|------|------|
|
||
| `Platform::Api::V1::UsersController` | PlatformController | `set_resource` + `validate_platform_app_permissible`（含 login/token） |
|
||
| `Platform::Api::V1::AccountsController` | PlatformController | 标准 set_resource + validate |
|
||
| `Platform::Api::V1::AgentBotsController` | PlatformController | 标准 set_resource + validate |
|
||
| `Platform::Api::V1::AccountUsersController` | PlatformController | 手动 set_resource + validate |
|
||
| `Platform::Api::V1::EmailChannelMigrationsController` | PlatformController | validate_account_permissible + validate_feature_flag + validate_params |
|
||
|
||
---
|
||
|
||
## 4. AccessToken 与 AccessTokenable（API令牌认证）
|
||
|
||
### 功能描述
|
||
AccessToken 是 Chatwoot 中多态令牌模型，服务于两类场景：① PlatformApp 的 Partner API 鉴权；② AgentBot 的 Bot API 鉴权。AccessToken 通过 `AccessTokenable` concern 自动创建——任何包含此 concern 的模型在创建后自动生成一条 AccessToken 记录。Token 通过 `has_secure_token` 生成，唯一且不可预测。
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **AccessToken**（`access_tokens` 表）：
|
||
- `id` (bigint, PK)
|
||
- `owner_type` (string) — 令牌所属者类型（PlatformApp / AgentBot）
|
||
- `owner_id` (bigint) — 令牌所属者 ID
|
||
- `token` (string, UNIQUE) — 令牌值（`has_secure_token` 自动生成）
|
||
- `created_at`, `updated_at` (datetime)
|
||
- 索引：`index_access_tokens_on_owner_type_and_owner_id` — (owner_type, owner_id)；`index_access_tokens_on_token` — UNIQUE
|
||
- 关联：`belongs_to :owner, polymorphic: true`
|
||
|
||
### AccessTokenable Concern
|
||
```ruby
|
||
module AccessTokenable
|
||
extend ActiveSupport::Concern
|
||
included do
|
||
has_one :access_token, as: :owner, dependent: :destroy_async
|
||
after_create :create_access_token
|
||
end
|
||
def create_access_token
|
||
AccessToken.create!(owner: self)
|
||
end
|
||
end
|
||
```
|
||
- 自动在模型创建后生成一条 AccessToken
|
||
- `dependent: :destroy_async` — 父模型删除时异步删除令牌
|
||
- 包含此 concern 的模型：**PlatformApp**、**AgentBot**
|
||
|
||
### Token 再生成
|
||
- `AgentBotsController#reset_access_token` — 调用 `@agent_bot.access_token.regenerate_token`
|
||
- `has_secure_token` 提供了 `regenerate_token` 方法
|
||
|
||
---
|
||
|
||
## 5. AccessTokenAuthHelper（令牌鉴权中间件）
|
||
|
||
### 功能描述
|
||
AccessTokenAuthHelper 是用于 Account API（非 Platform API）场景的 AccessToken 鉴权 concern。它允许 AgentBot 通过 AccessToken 代替用户 session 调用特定 Account API 端点。但 Bot 仅能访问有限的端点集合（BOT_ACCESSIBLE_ENDPOINTS），防止越权。
|
||
|
||
### 核心逻辑
|
||
- **ensure_access_token** — 从 Header 解析 `api_access_token`，查找对应 AccessToken 记录
|
||
- **authenticate_access_token!** — 验证令牌存在，设置 `@resource = @access_token.owner`，如 owner 是 User 则设置 `Current.user`
|
||
- **validate_bot_access_token!** — 如果 owner 是 AgentBot，则检查当前端点是否在 `BOT_ACCESSIBLE_ENDPOINTS` 白名单内
|
||
- **BOT_ACCESSIBLE_ENDPOINTS 白名单**：
|
||
- `api/v1/accounts/conversations` → `toggle_status, toggle_typing_status, toggle_priority, create, update, custom_attributes`
|
||
- `api/v1/accounts/conversations/messages` → `create`
|
||
- `api/v1/accounts/conversations/assignments` → `create`
|
||
- **allowed_current_user_type?** — 仅 User 和 AgentBot 可设置为 Current.user
|
||
|
||
---
|
||
|
||
## 6. AgentBot（智能机器人）
|
||
|
||
### 功能描述
|
||
AgentBot 是 Chatwoot 的智能机器人模型，支持 Webhook 类型（将对话事件推送到外部 URL）。AgentBot 可绑定到 Inbox（通过 AgentBotInbox），也可被直接分配为会话的 assignee（`assignee_agent_bot_id`）。Bot 创建时自动获得 AccessToken 和 Secret（用于 Webhook 签名），支持头像管理。Bot 分为账户级（`account_id` 有值）和全局级（`account_id = nil`）。
|
||
|
||
### 用户操作流程
|
||
1. 管理员在 Agent Bot 设置页创建 AgentBot，填写名称、描述、outgoing_url
|
||
2. 系统自动生成 AccessToken + Secret
|
||
3. 管理员将 Bot 绑定到 Inbox（AgentBotInbox），Bot 开始监听该 Inbox 的对话事件
|
||
4. 事件触发 → AgentBotListener 收集该 Inbox 的 Bot → 通过 AgentBots::WebhookJob 将 payload 推送到 outgoing_url
|
||
5. 外部 Bot 服务处理后，通过 AccessToken 鉴权调用 Account API 回写消息/更新会话状态
|
||
6. 管理员也可将 Bot 直接设置为会话的 assignee
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/:account_id/agent_bots` | 列出 accessible Bot（含全局 + 本账户） |
|
||
| POST | `/api/v1/accounts/:account_id/agent_bots` | 创建账户级 Bot |
|
||
| GET | `/api/v1/accounts/:account_id/agent_bots/:id` | 查看某 Bot |
|
||
| PATCH | `/api/v1/accounts/:account_id/agent_bots/:id` | 更新 Bot |
|
||
| DELETE | `/api/v1/accounts/:account_id/agent_bots/:id` | 删除 Bot |
|
||
| DELETE | `/api/v1/accounts/:account_id/agent_bots/:id/avatar` | 删除头像 |
|
||
| POST | `/api/v1/accounts/:account_id/agent_bots/:id/reset_access_token` | 重置 AccessToken |
|
||
| POST | `/api/v1/accounts/:account_id/agent_bots/:id/reset_secret` | 重置 Webhook Secret |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **AgentBot**（`agent_bots` 表）：
|
||
- `id` (bigint, PK)
|
||
- `name` (string) — Bot 名称
|
||
- `description` (string) — Bot 描述
|
||
- `outgoing_url` (string) — Webhook 推送 URL
|
||
- `bot_type` (integer, default: webhook) — Bot 类型枚举（目前仅 webhook: 0）
|
||
- `bot_config` (jsonb) — Bot 自定义配置
|
||
- `secret` (string) — Webhook 签名密钥（`has_secure_token` + 可选加密）
|
||
- `account_id` (bigint, nullable) — 所属账户（nil = 全局 Bot）
|
||
- 关联：
|
||
- `has_many :agent_bot_inboxes, dependent: :destroy_async`
|
||
- `has_many :inboxes, through: :agent_bot_inboxes`
|
||
- `has_many :messages, as: :sender, dependent: :nullify`
|
||
- `has_many :platform_app_permissibles, as: :permissible, dependent: :destroy`
|
||
- `has_many :assigned_conversations`（foreign_key: `assignee_agent_bot_id`）
|
||
- `belongs_to :account, optional: true`
|
||
- Concern：
|
||
- `AccessTokenable` — 自动创建 AccessToken
|
||
- `Avatarable` — 支持头像
|
||
- `WebhookSecretable` — 自动生成 Secret（可加密）
|
||
- Scope：`accessible_to(account)` → `where(account_id: [nil, account.id])`
|
||
- 方法：
|
||
- `push_event_data(inbox)` → `{ id, name, avatar_url, type: 'agent_bot' }`
|
||
|
||
### 涉及的业务逻辑
|
||
- **AgentBotPolicy** — index/show 需 administrator 或 agent；create/update/destroy/reset_access_token/reset_secret/avatar 仅 administrator
|
||
- **AgentBotPresenter** — `access_token` 方法：仅当 `Current.account.id == account_id` 时返回 token（跨账户不暴露令牌）
|
||
- **AvatarFromUrlJob** — 支持 `avatar_url` 参数远程拉取头像
|
||
|
||
---
|
||
|
||
## 7. AgentBotInbox（Bot-Inbox绑定）
|
||
|
||
### 功能描述
|
||
AgentBotInbox 是 AgentBot 与 Inbox 之间的绑定关系模型。每个绑定记录表示"某 Bot 监听某 Inbox"。支持 active/inactive 状态控制，允许管理员在不删除绑定的情况下暂停 Bot 对某 Inbox 的监听。`account_id` 由 Inbox 自动继承。
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **AgentBotInbox**（`agent_bot_inboxes` 表）：
|
||
- `id` (bigint, PK)
|
||
- `agent_bot_id` (integer, NOT NULL)
|
||
- `inbox_id` (integer, NOT NULL)
|
||
- `account_id` (integer) — 从 inbox.account_id 自动填充
|
||
- `status` (integer, default: active) — 状态枚举：active(0), inactive(1)
|
||
- 关联：`belongs_to :inbox`, `belongs_to :agent_bot`, `belongs_to :account`
|
||
- `before_validation :ensure_account_id` — 自动从 inbox 继承 account_id
|
||
|
||
---
|
||
|
||
## 8. AgentBotListener（Bot事件监听）
|
||
|
||
### 功能描述
|
||
AgentBotListener 是事件驱动的 Bot Webhook 推送监听器，继承 BaseListener。监听对话和消息相关事件，将 payload 推送给与 Inbox 绑定的 Bot。Bot 来源分两种：① Inbox 绑定的活跃 Bot（`AgentBotInbox.active`）；② 会话的 assignee Bot（`conversation.assignee_agent_bot`）。
|
||
|
||
### 监听的事件
|
||
| 事件 | 推送内容 |
|
||
|------|------|
|
||
| `conversation_resolved` | `conversation.webhook_data.merge(event: 'conversation_resolved')` |
|
||
| `conversation_opened` | `conversation.webhook_data.merge(event: 'conversation_opened')` |
|
||
| `conversation_status_changed` | webhook_data + changed_attributes |
|
||
| `conversation_updated` | webhook_data + changed_attributes |
|
||
| `message_created` | `message.webhook_data.merge(event: 'message_created')` |
|
||
| `message_updated` | `message.webhook_data.merge(event: 'message_updated')` |
|
||
| `webwidget_triggered` | inbox 数据 + contact 信息 |
|
||
|
||
### 涉及的业务逻辑
|
||
- **agent_bots_for(inbox, conversation)** — 收集活跃 Bot 列表：
|
||
- 会话 assignee Bot（`conversation.assignee_agent_bot`）
|
||
- Inbox 绑定的活跃 Bot（`inbox.agent_bot`，仅当 `agent_bot_inbox.active?`）
|
||
- 去重合并
|
||
- **process_webhook_bot_event** — 如果 Bot 的 `outgoing_url` 不为空，通过 `AgentBots::WebhookJob.perform_later` 异步推送
|
||
- 推送参数：`(outgoing_url, payload, :agent_bot_webhook, secret: agent_bot.secret, delivery_id: SecureRandom.uuid)`
|
||
|
||
---
|
||
|
||
## 9. AgentBots::WebhookJob（Bot Webhook投递）
|
||
|
||
### 功能描述
|
||
AgentBots::WebhookJob 是 AgentBot 专用的 Webhook 推送 Job，继承 WebhookJob，队列优先级为 `high`。支持 `RetryableError`（HTTP 429/500）的3次重试，每次间隔 3秒。重试失败后调用 `Webhooks::Trigger#handle_failure` 处理。
|
||
|
||
### 核心逻辑
|
||
- `perform(url, payload, webhook_type = :agent_bot_webhook, secret:, delivery_id:)` → 调用 `Webhooks::Trigger.execute`
|
||
- 重试策略：`retry_on Webhooks::Trigger::RetryableError, wait: 3.seconds, attempts: 3`
|
||
- 失败日志：`Rails.logger.warn("[AgentBots::WebhookJob] attempt #{executions} failed")`
|
||
|
||
---
|
||
|
||
## 10. DashboardApp（仪表盘扩展应用）
|
||
|
||
### 功能描述
|
||
DashboardApp 是 Chatwoot 仪表盘侧边栏的 iframe 扩展应用模型。每个 DashboardApp 由账户内用户创建，包含一个 `content` jsonb 字段，存储一个数组——数组中的每个元素定义一个 iframe 面板（type: 'frame', url: 指定 iframe URL）。DashboardApp 用于第三方将自建界面嵌入 Chatwoot 仪表盘侧边栏。
|
||
|
||
### 用户操作流程
|
||
1. 管理员在设置页创建 DashboardApp，填写 title 和 iframe URL 列表
|
||
2. 系统验证 content 格式（必须是数组，每个元素包含 type:'frame' + 合法 http/https URL）
|
||
3. DashboardApp 创建后关联到创建者和所属账户
|
||
4. 仪表盘侧边栏渲染时加载该账户的所有 DashboardApp，每个 app 以 iframe 嵌入
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/:account_id/dashboard_apps` | 列出账户所有 DashboardApp |
|
||
| GET | `/api/v1/accounts/:account_id/dashboard_apps/:id` | 查看单个 |
|
||
| POST | `/api/v1/accounts/:account_id/dashboard_apps` | 创建（自动绑定 user_id） |
|
||
| PATCH | `/api/v1/accounts/:account_id/dashboard_apps/:id` | 更新 |
|
||
| DELETE | `/api/v1/accounts/:account_id/dashboard_apps/:id` | 删除 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **DashboardApp**（`dashboard_apps` 表）：
|
||
- `id` (bigint, PK)
|
||
- `title` (string, NOT NULL) — 应用标题
|
||
- `content` (jsonb) — iframe 配置数组，格式：`[{ type: 'frame', url: 'https://...' }]`
|
||
- `account_id` (bigint, NOT NULL) — 所属账户
|
||
- `user_id` (bigint) — 创建者
|
||
- 关联：`belongs_to :user`, `belongs_to :account`
|
||
|
||
### Content 验证规则
|
||
- 必须是数组（`is_a?(Array)`），非空（`minItems: 1`）
|
||
- 每个元素必须包含 `type`（仅允许 `'frame'`）和 `url`（必须 http/https URI）
|
||
- 使用 JSONSchemer 校验 schema
|
||
- 空白/非数组数据自动重置为 `[]`
|
||
|
||
---
|
||
|
||
## 11. DataImport（数据导入）
|
||
|
||
### 功能描述
|
||
DataImport 是 Chatwoot 的批量数据导入模型，目前仅支持 contacts 导入。用户上传 CSV 文件后，系统创建 DataImport 记录并自动触发 DataImportJob 异步处理。DataImport 跟踪导入状态（pending → processing → completed/failed）、已处理记录数、错误信息，并可附加 `import_file`（源 CSV）和 `failed_records`（失败记录 CSV）。
|
||
|
||
### 用户操作流程
|
||
1. 管理员在联系人页面点击"导入"，上传 CSV 文件
|
||
2. 系统创建 DataImport 记录（`data_type: 'contacts'`），附上 `import_file`
|
||
3. `after_create_commit` 触发 `DataImportJob.set(wait: 1.minute).perform_later`（等待文件上传到云存储）
|
||
4. Job 解析 CSV → 查找/创建联系人（支持 identifier/email/phone_number 去重合并）
|
||
5. 处理完成后更新 `processed_records` / `total_records` / `status`
|
||
6. 失败记录保存为 `failed_records` CSV 附件
|
||
7. 发送导入完成/失败通知邮件给管理员
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/v1/accounts/:account_id/contacts/import` | 上传 CSV 导入联系人 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **DataImport**（`data_imports` 表）：
|
||
- `id` (bigint, PK)
|
||
- `data_type` (string, NOT NULL) — 导入类型（目前仅 `'contacts'`）
|
||
- `status` (integer, default: pending) — 状态枚举：pending(0), processing(1), completed(2), failed(3)
|
||
- `total_records` (integer) — 总记录数
|
||
- `processed_records` (integer) — 成功处理记录数
|
||
- `processing_errors` (text) — 处理错误描述
|
||
- `account_id` (bigint, NOT NULL)
|
||
- 附件：`has_one_attached :import_file`，`has_one_attached :failed_records`
|
||
- 关联：`belongs_to :account`
|
||
- 验证：`data_type` inclusion `{ in: ['contacts'] }`
|
||
- 回调：`after_create_commit :process_data_import` → 延迟1分钟触发 DataImportJob
|
||
|
||
---
|
||
|
||
## 12. DataImportJob + ContactManager（导入处理流程）
|
||
|
||
### 功能描述
|
||
DataImportJob 是异步 CSV 导入处理器，使用 `DataImport::ContactManager` 执行联系人查找/去重/创建。流程：解析CSV → 查找已有联系人（按 identifier → email → phone_number 优先级） → 合并属性 → 批量创建 → 标签关联 → 失败记录导出 → 邮件通知。
|
||
|
||
### 核心逻辑
|
||
- **DataImportJob**（`app/jobs/data_import_job.rb`）：
|
||
- 队列：`low`
|
||
- 重试：`retry_on ActiveStorage::FileNotFoundError, wait: 1.minute, attempts: 3`
|
||
- 流程：
|
||
1. 更新 `status: :processing`
|
||
2. 解析 CSV → `ContactManager.build_contact` 逐行处理
|
||
3. 每行提取 labels，校验是否在账户已批准标签内
|
||
4. 不合法标签行 → 加入 `rejected_contacts`
|
||
5. 合法行 → 构建联系人属性（name, email, phone_number, identifier, custom_attributes 等）
|
||
6. 批量导入联系人（`Contact.import`，batch_size: 1000）
|
||
7. 批量应用标签（`ActsAsTaggableOn::Tagging.import`）
|
||
8. 保存失败记录 CSV 为 `failed_records` 附件
|
||
9. 发送 `AdministratorNotificationsMailer.contact_import_complete` 或 `contact_import_failed`
|
||
|
||
- **DataImport::ContactManager**（`app/services/data_import/contact_manager.rb`）：
|
||
- 查找优先级：`identifier → email → phone_number`
|
||
- 合并策略：
|
||
- `update_contact_with_merged_attributes` — 去重时合并 identifier/name/phone_number/email/custom_attributes
|
||
- `format_phone_number` — 自动加 `+` 前缀
|
||
- `from_email` — 使用 Contact scope 查询邮箱
|
||
- `find_or_initialize_contact` — 如找不到则初始化新联系人
|
||
|
||
---
|
||
|
||
## 13. Webhook（账户级Webhook）
|
||
|
||
### 功能描述
|
||
Webhook 是 Chatwoot 的账户级事件推送模型。管理员可在账户或 Inbox 级别创建 Webhook，订阅特定事件（conversation_status_changed, message_created 等），当事件发生时由 WebhookListener 触发 WebhookJob 投递 payload 到指定 URL。Webhook 支持 account_type（账户级）和 inbox_type（Inbox级）两种类型，每个 Webhook 包含 `secret` 用于 HMAC 签名验证。
|
||
|
||
### 用户操作流程
|
||
1. 管理员在设置页创建 Webhook，填写 URL、名称、订阅事件列表
|
||
2. 系统自动生成 Secret，验证 URL 格式和订阅事件合法性
|
||
3. 事件发生时 → WebhookListener 触发 → WebhookJob 异步推送
|
||
4. 推送使用 HMAC-SHA256 签名（`x-chatwoot-signature` Header）
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/accounts/:account_id/webhooks` | 列出账户 Webhook |
|
||
| POST | `/api/v1/accounts/:account_id/webhooks` | 创建 Webhook |
|
||
| PATCH | `/api/v1/accounts/:account_id/webhooks/:id` | 更新 |
|
||
| DELETE | `/api/v1/accounts/:account_id/webhooks/:id` | 删除 |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **Webhook**（`webhooks` 表）：
|
||
- `id` (bigint, PK)
|
||
- `name` (string) — Webhook 名称
|
||
- `url` (text) — 推送 URL（account_id + url 联合唯一）
|
||
- `secret` (string) — HMAC 签名密钥（WebhookSecretable）
|
||
- `subscriptions` (jsonb) — 订阅事件数组
|
||
- `webhook_type` (integer, default: account_type) — 类型枚举：account_type(0), inbox_type(1)
|
||
- `account_id` (integer) — 所属账户
|
||
- `inbox_id` (integer, nullable) — 所属 Inbox（仅 inbox_type）
|
||
- 关联：`belongs_to :account`, `belongs_to :inbox, optional: true`
|
||
- Concern：`WebhookSecretable`
|
||
- 验证：`url` 格式（http/https URI regex）；`subscriptions` 必须是数组且所有事件在 `ALLOWED_WEBHOOK_EVENTS` 内
|
||
|
||
### ALLOWED_WEBHOOK_EVENTS
|
||
```
|
||
conversation_status_changed, conversation_updated, conversation_created,
|
||
contact_created, contact_updated,
|
||
message_created, message_updated,
|
||
webwidget_triggered, inbox_created, inbox_updated,
|
||
conversation_typing_on, conversation_typing_off
|
||
```
|
||
|
||
---
|
||
|
||
## 14. WebhookSecretable（签名密钥机制）
|
||
|
||
### 功能描述
|
||
WebhookSecretable 是为 Webhook 和 AgentBot 提供签名密钥的 concern。使用 `has_secure_token :secret` 自动生成密钥，并支持加密存储（`encrypts :secret`，依赖 `Chatwoot.encryption_configured?`）。提供 `reset_secret!` 方法用于密钥轮换。
|
||
|
||
### 核心逻辑
|
||
```ruby
|
||
module WebhookSecretable
|
||
extend ActiveSupport::Concern
|
||
included do
|
||
has_secure_token :secret
|
||
encrypts :secret if Chatwoot.encryption_configured?
|
||
end
|
||
def reset_secret!
|
||
regenerate_secret
|
||
reload
|
||
end
|
||
end
|
||
```
|
||
- 包含此 concern 的模型：**Webhook**、**AgentBot**
|
||
- 签名使用：Webhooks::Trigger 中 `OpenSSL::HMAC.hexdigest('SHA256', secret, body)` → 生成 `x-chatwoot-signature` Header
|
||
|
||
---
|
||
|
||
## 15. Webhooks::Trigger（Webhook投递引擎）
|
||
|
||
### 功能描述
|
||
Webhooks::Trigger 是 Chatwoot 所有 Webhook 推送的核心执行引擎。负责构建 HTTP 请求、设置签名 Header、执行请求、处理失败和重试。支持三种 webhook_type：`account_webhook`、`inbox_webhook`、`agent_bot_webhook`。
|
||
|
||
### 核心逻辑
|
||
- **请求构建**：
|
||
- `SafeFetch.fetch(url, method: :post, body: payload.to_json, headers: request_headers)`
|
||
- Headers：`Content-Type: application/json`, `Accept: application/json`
|
||
- `X-Chatwoot-Delivery` — delivery_id（UUID）
|
||
- `x-chatwoot-signature` — HMAC-SHA256 签名（使用 secret + body）
|
||
- **超时**：`webhook_timeout`（根据 webhook_type 区分：agent_bot 默认更长）
|
||
- **重试机制**：
|
||
- `RetryableError` — AgentBot 场景下 HTTP 429/500 触发重试
|
||
- AgentBots::WebhookJob：`retry_on RetryableError, wait: 3.seconds, attempts: 3`
|
||
- 失败处理：`handle_failure(error)` → 日志记录
|
||
- **三种 Job**：
|
||
- `WebhookJob`（queue: medium）— account/inbox webhook
|
||
- `AgentBots::WebhookJob`（queue: high）— agent_bot webhook，支持重试
|
||
- 两者均调用 `Webhooks::Trigger.execute`
|
||
|
||
---
|
||
|
||
## 16. InstallationConfig（平台级配置）
|
||
|
||
### 功能描述
|
||
InstallationConfig 是 Chatwoot 的平台级全局配置模型，存储在数据库中，通过 GlobalConfig 缓存层提供高效读取。每个配置项由 `name`（唯一键）和 `serialized_value`（jsonb）组成。配置项分两类：`locked`（不可通过 API 修改）和 `editable`（可通过 Super Admin API 修改）。部分配置修改后需要重启应用（RESTART_REQUIRED_CONFIG_KEYS）。
|
||
|
||
### 关键配置项
|
||
| 配置名 | 说明 | 类型 |
|
||
|------|------|------|
|
||
| `ENABLE_ACCOUNT_SIGNUP` | 是否允许自助注册 | boolean |
|
||
| `ENABLE_SAML_SSO_LOGIN` | 是否启用 SAML SSO | boolean（修改前校验是否有 SAML 用户） |
|
||
| `CAPTAIN_OPEN_AI_API_KEY` | Captain AI LLM 密钥 | string（需重启） |
|
||
| `CAPTAIN_OPEN_AI_ENDPOINT` | Captain AI LLM Endpoint | string（需重启） |
|
||
| `CAPTAIN_OPEN_AI_MODEL` | Captain AI LLM 模型名 | string（需重启） |
|
||
| `LANGFUSE_BASE_URL` / `PUBLIC_KEY` / `SECRET_KEY` | Langfuse 可观测配置 | string（需重启） |
|
||
| `OTEL_PROVIDER` | OpenTelemetry Provider | string（需重启） |
|
||
| `DISPLAY_MANIFEST` | 是否展示 app manifest | boolean |
|
||
|
||
### 涉及的数据模型+关键字段
|
||
- **InstallationConfig**（`installation_configs` 表）：
|
||
- `id` (bigint, PK)
|
||
- `name` (string, NOT NULL, UNIQUE) — 配置键名
|
||
- `serialized_value` (jsonb, NOT NULL) — 配置值（serialize YAML，默认 `{}`）
|
||
- `locked` (boolean, default: TRUE, NOT NULL) — 是否锁定（锁定项不可通过 API 编辑）
|
||
- `created_at`, `updated_at` (datetime)
|
||
- 索引：`index_installation_configs_on_name` (UNIQUE)，`index_installation_configs_on_name_and_created_at` (UNIQUE)
|
||
- Scope：`editable` → `where(locked: false)`
|
||
- `default_scope` → `order(created_at: :desc)`
|
||
- `before_validation :set_lock` — 新建时默认锁定
|
||
- `after_commit :clear_cache` — 修改后清除 GlobalConfig Redis 缓存
|
||
- 验证：`validates :name, presence: true`; `saml_sso_users_check` — 关闭 SAML SSO 前检查是否有 SAML 用户
|
||
|
||
### 涉及的API端点
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| Super Admin CRUD | `/super_admin/installation_configs` | 管理后台管理 InstallationConfig（全量 CRUD） |
|
||
|
||
### 涉及的业务逻辑
|
||
- **value accessor** — `InstallationConfig#value` 读 `serialized_value[:value]`；`InstallationConfig#value=` 写 `{ value: ... }`
|
||
- **GlobalConfig 缓存** — 通过 Redis $alfred 缓存，1天过期，fallback 到数据库
|
||
- **GlobalConfigService.load(key, default)** — 先查 GlobalConfig 缓存，再 fallback ENV，最后创建 InstallationConfig 记录
|
||
- **配置修改需要重启的标记** — `RESTART_REQUIRED_CONFIG_KEYS` 数组
|
||
|
||
---
|
||
|
||
## 17. GlobalConfig + GlobalConfigService（配置缓存层）
|
||
|
||
### 功能描述
|
||
GlobalConfig 是 InstallationConfig 的 Redis 缓存读取层，通过 `$alfred`（Redis 连接）缓存配置值，默认1天过期。当 InstallationConfig 修改时，`after_commit :clear_cache` 自动清除缓存，确保读取到最新值。GlobalConfigService 提供便捷方法，支持 ENV fallback 和自动创建 InstallationConfig。
|
||
|
||
### GlobalConfig 核心逻辑
|
||
- **缓存键**：`V1:GLOBAL_CONFIG:{config_key}`
|
||
- **读取流程**：
|
||
1. 查 Redis 缓存 → 如有直接返回
|
||
2. 缓存不存在 → 查 InstallationConfig DB → 写入 Redis（1天过期）
|
||
- **类型转换**：通过 ConfigLoader 加载 general_configs 元数据，对 boolean 类型做 `ActiveModel::Type::Boolean.new.cast`
|
||
- **clear_cache**：扫描 `$alfred.keys("V1:GLOBAL_CONFIG:*")` 并逐个 expire(0)
|
||
|
||
### GlobalConfigService 核心逻辑
|
||
- **load(key, default)**：
|
||
1. `GlobalConfig.get(key)` → 如有值返回
|
||
2. fallback `ENV.fetch(key) { default }`
|
||
3. `InstallationConfig.where(name: key).first_or_create(value: env_value, locked: false)`
|
||
4. `GlobalConfig.clear_cache` → 下次读取走 DB
|
||
- **account_signup_enabled?** — `load('ENABLE_ACCOUNT_SIGNUP', 'false')` 转 boolean
|
||
|
||
---
|
||
|
||
## 跨模块交互关系
|
||
|
||
```
|
||
PlatformApp ──1:1──→ AccessToken (认证)
|
||
PlatformApp ──1:N──→ PlatformAppPermissible (授权)
|
||
↕ polymorphic
|
||
├── Account
|
||
├── User
|
||
└── AgentBot
|
||
|
||
AgentBot ──1:1──→ AccessToken (Bot API认证)
|
||
AgentBot ──1:1──→ Secret (Webhook签名)
|
||
AgentBot ──1:N──→ AgentBotInbox → Inbox (监听绑定)
|
||
AgentBot ──1:N──→ PlatformAppPermissible (Partner授权)
|
||
AgentBot ──1:N──→ AssignedConversations (assignee)
|
||
AgentBotListener ──→ AgentBots::WebhookJob → Webhooks::Trigger
|
||
|
||
Webhook ──1:1──→ Secret (HMAC签名)
|
||
WebhookListener ──→ WebhookJob → Webhooks::Trigger
|
||
|
||
DashboardApp ──1:N──→ Account
|
||
DashboardApp ──1:1──→ User (创建者)
|
||
|
||
DataImport ──1:1──→ Account
|
||
DataImport ──1:1──→ ImportFile (ActiveStorage)
|
||
DataImport ──1:1──→ FailedRecords (ActiveStorage)
|
||
DataImportJob ──→ DataImport::ContactManager → Contact
|
||
|
||
InstallationConfig ──→ GlobalConfig (Redis缓存) ──→ GlobalConfigService (ENV fallback)
|
||
```
|
||
|
||
---
|
||
|
||
## GoChat 实现建议
|
||
|
||
| 模块 | 优先级 | 实现要点 |
|
||
|------|--------|----------|
|
||
| AccessToken + AccessTokenable | P0 | 多态令牌，支持 PlatformApp 和 AgentBot 两种 owner；`has_secure_token` 生成唯一 token |
|
||
| PlatformApp + Permissible | P1 | Partner API 认证主体；多态授权矩阵；建议 Go 中用 interface + 泛型实现 polymorphic |
|
||
| PlatformController 鉴权 | P1 | Token → PlatformApp 解析 → Permissible 校验；建议中间件链实现 |
|
||
| AgentBot + AgentBotInbox | P1 | Bot 模型核心；AccessToken + Secret 双令牌；account_id nullable 支持全局 Bot |
|
||
| AgentBotListener | P2 | 事件驱动推送；建议 EventBus + Handler 模式 |
|
||
| AgentBots::WebhookJob | P2 | 异步推送 + 重试；建议消息队列 + 指数退避 |
|
||
| Webhook + WebhookSecretable | P1 | HMAC-SHA256 签名验证；WebhookJob 异步推送；account/inbox 两种 scope |
|
||
| Webhooks::Trigger | P2 | 统一推送引擎；签名 + 超时 + 重试 + 错误处理 |
|
||
| DashboardApp | P3 | iframe 扩展；content schema 校验；前端侧边栏 iframe 渲染 |
|
||
| DataImport | P2 | CSV 异步导入；联系人去重合并；标签批量关联；进度追踪 |
|
||
| InstallationConfig | P1 | 平台级配置 DB 存储；Redis 缓存层；ENV fallback；locked/editable 分类 |
|
||
| GlobalConfig | P2 | Redis 缓存 + DB fallback；类型转换；after_commit 清缓存 | |