479 lines
29 KiB
Markdown
479 lines
29 KiB
Markdown
# M4 联系人管理 — Chatwoot 功能梳理文档
|
||
|
||
> 基于 Chatwoot 源码深度阅读 + CodeGraph 上下文梳理
|
||
> 生成日期：2026-05-22
|
||
> 参照仓库：chatwoot-reference
|
||
|
||
---
|
||
|
||
## 模块概述
|
||
|
||
本模块覆盖 Chatwoot 的联系人（Contact）全生命周期管理，包括联系人 CRUD、搜索、合并、ContactInbox（联系人-收件箱关联）、CustomAttribute（自定义属性）、CustomFilter（自定义筛选器）、Note（笔记）、Label（标签）以及企业版 Company（公司）功能。核心目标是构建完整的 CRM 体系，让客服团队可以对客户信息进行精细化管理、分类和检索。
|
||
|
||
---
|
||
|
||
## 1. 联系人 CRUD + 状态管理
|
||
|
||
### 联系人创建
|
||
- **功能描述**：联系人（Contact）是 Chatwoot CRM 的核心实体，代表一个客户/潜在客户。创建时可指定邮箱、电话、姓名等基本信息，并可同时关联到一个 Inbox（通过 ContactInbox）。联系人通过渠道消息自动创建，也可由坐席手动创建。
|
||
- **用户操作流程**：
|
||
1. 客户通过渠道（WhatsApp/Facebook/Telegram/WebWidget 等）发消息，系统自动创建联系人 + ContactInbox
|
||
2. 坐席可在 Contacts 页面手动创建联系人（`POST /api/v1/accounts/{account_id}/contacts`），可同时指定 `inbox_id` 和 `source_id`
|
||
3. CSV 批量导入联系人（`POST /api/v1/accounts/{account_id}/contacts/import`），仅管理员可操作
|
||
4. 创建后触发 `dispatch_create_event`（ActionCable）和 `ip_lookup`（如 feature flag 启用）
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts` — 创建联系人
|
||
- 请求参数：`{ name, identifier, email, phone_number, avatar, avatar_url, inbox_id, source_id, additional_attributes: {}, custom_attributes: {} }`
|
||
- `POST /api/v1/accounts/{account_id}/contacts/import` — CSV 导入（管理员）
|
||
- `POST /api/v1/accounts/{account_id}/contacts/export` — CSV 导出（管理员）
|
||
- 响应：联系人对象 `{ id, name, email, phone_number, identifier, avatar_url, additional_attributes, custom_attributes, contact_type, blocked, ... }`
|
||
- **涉及的数据模型**：
|
||
- **Contact**（`contacts` 表）核心字段：
|
||
- `id, name, email, phone_number, identifier, middle_name, last_name, country_code, location, contact_type, blocked`
|
||
- `additional_attributes`（jsonb）— 存放 city, company_name, social_* 等扩展信息
|
||
- `custom_attributes`（jsonb）— 存放自定义属性键值对
|
||
- `account_id, company_id`（企业版）, `last_activity_at, created_at, updated_at`
|
||
- `contact_type` enum：`visitor(0), lead(1), customer(2)`
|
||
- 索引：
|
||
- `index_contacts_on_account_id_and_contact_type` — 按账户+类型查询
|
||
- `index_contacts_on_lower_email_account_id` — 邮箱大小写不敏感唯一
|
||
- `index_contacts_on_name_email_phone_number_identifier` — GIN 全文搜索
|
||
- `index_contacts_on_nonempty_fields` — 过滤有标识信息的联系人
|
||
- **涉及的业务逻辑**：
|
||
- **ContactInboxBuilder**（`app/builders/contact_inbox_builder.rb`）：创建联系人时若指定 inbox_id，自动创建 ContactInbox。根据渠道类型智能生成 source_id（Email→邮箱、WhatsApp→去掉+的电话、Twilio→带+的电话、WebWidget/API→UUID）
|
||
- **Contacts::SyncAttributes**（`app/services/contacts/sync_attributes.rb`）：
|
||
- 从 `additional_attributes` 同步 `location` 和 `country_code` 到主字段
|
||
- 自动升级 `contact_type`：visitor → lead（当有 email/phone/social 信息时）
|
||
- **Avatarable** concern：自动从 Gravatar 拉取头像（邮箱变更时异步执行）
|
||
- `before_validation :prepare_contact_attributes` — 清理空属性
|
||
- `before_save :sync_contact_attributes` — 同步联系人属性
|
||
- `after_create_commit :dispatch_create_event, :ip_lookup`
|
||
- `after_update_commit :dispatch_update_event`
|
||
- `after_destroy_commit :dispatch_destroy_event`
|
||
- **涉及的权限策略**：
|
||
- **ContactPolicy**：`index?, active?, search?, filter?, show?, create?, update?, contactable_inboxes?, destroy_custom_attributes?, avatar?` → 所有坐席可操作；`import?, export?, destroy?` → 仅管理员
|
||
- **涉及的事件/通知**：
|
||
- ActionCable：创建/更新/删除事件推送
|
||
- `CONTACT_MERGED` 事件（合并时触发）
|
||
|
||
### 联系人列表 + 排序 + 分页
|
||
- **功能描述**：支持按账户获取联系人列表，支持多字段排序和分页。默认只展示有标识信息的"resolved contacts"（CRM V2 模式下只展示 lead 类型）。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/contacts` — 分页列表（默认 15 条/页）
|
||
- `GET /api/v1/accounts/{account_id}/contacts/active` — 最近活跃联系人
|
||
- 请求参数：`page, sort, include_contact_inboxes`
|
||
- **排序支持（Sift gem）**：
|
||
- `email, name, phone_number, last_activity_at, created_at, company_name, city, country` — 支持 asc/desc
|
||
- **resolved_contacts 逻辑**：
|
||
- 默认模式：`WHERE email <> '' OR phone_number <> '' OR identifier <> ''`
|
||
- CRM V2 模式：`WHERE contact_type = 'lead'`
|
||
- **标签过滤**：支持 `labels` 参数（ActsAsTaggableOn `tagged_with`，any: true）
|
||
|
||
### 联系人搜索
|
||
- **功能描述**：对联系人的 name/email/phone_number/identifier 进行 ILIKE 模糊搜索，返回分页结果。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/contacts/search?q=xxx` — 搜索
|
||
- 响应包含 `has_more` 标识（多取一条判断是否还有更多数据）
|
||
|
||
### 联系人更新
|
||
- **涉及的API端点**：
|
||
- `PUT /api/v1/accounts/{account_id}/contacts/{id}` — 更新联系人
|
||
- 更新时 custom_attributes 和 additional_attributes 采用 merge（合并）策略而非覆盖
|
||
- 支持 `avatar_url` 参数，从 URL 拉取头像
|
||
|
||
### 联系人删除
|
||
- **涉及的API端点**：
|
||
- `DELETE /api/v1/accounts/{account_id}/contacts/{id}` — 删除联系人（仅管理员）
|
||
- 删除前检查在线状态（OnlineStatusTracker），在线联系人不可删除
|
||
- 关联的 conversations, contact_inboxes, messages, notes 等通过 `dependent: :destroy_async` 异步级联删除
|
||
|
||
### 联系人头像管理
|
||
- **涉及的API端点**：
|
||
- `DELETE /api/v1/accounts/{account_id}/contacts/{id}/avatar` — 删除头像
|
||
|
||
---
|
||
|
||
## 2. 联系人高级筛选（Filter）
|
||
|
||
### 筛选器运行
|
||
- **功能描述**：基于 `Contacts::FilterService`，支持多条件组合筛选联系人。筛选条件来自 `filter_keys.yml` 中的 contact 字段定义 + 自定义属性。支持标准属性、additional_attributes 和自定义属性三种类型。
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/filter` — 执行筛选
|
||
- 请求参数：`{ payload: { contacts: [ { attribute_key, filter_operator, values, attribute_type, data_type } ... ] } }`
|
||
- **筛选字段（filter_keys.yml → contacts）**：
|
||
| 字段 | attribute_type | data_type | filter_operators |
|
||
|------|---------------|-----------|-----------------|
|
||
| name | standard | text_case_insensitive | equal_to, not_equal_to, contains, does_not_contain |
|
||
| phone_number | standard | text | equal_to, not_equal_to, contains, does_not_contain, starts_with |
|
||
| email | standard | text_case_insensitive | equal_to, not_equal_to, contains, does_not_contain |
|
||
| identifier | standard | text_case_insensitive | equal_to, not_equal_to |
|
||
| country_code | additional_attributes | text_case_insensitive | equal_to, not_equal_to |
|
||
| city | additional_attributes | text_case_insensitive | equal_to, not_equal_to, contains, does_not_contain |
|
||
| company_name | additional_attributes | text_case_insensitive | equal_to, not_equal_to, contains, does_not_contain |
|
||
| labels | standard | labels | equal_to, not_equal_to, is_present, is_not_present |
|
||
| created_at | standard | date | is_greater_than, is_less_than, days_before |
|
||
| last_activity_at | standard | date | is_greater_than, is_less_than, days_before |
|
||
| blocked | standard | boolean | equal_to, not_equal_to |
|
||
| *(自定义属性)* | custom_attribute | 对应类型 | 对应操作符 |
|
||
- **涉及的业务逻辑**：
|
||
- **Contacts::FilterService** 继承 **FilterService**：
|
||
- `base_relation` → `account.contacts.resolved_contacts`
|
||
- 支持 `phone_number` 特殊处理（自动加 +）
|
||
- 支持 `country_code` 特殊处理（自动 downcase）
|
||
- 支持 `crm_v2` feature flag
|
||
- FilterService 核心逻辑：解析 filter payload → 逐条件构建 SQL → 组合 `query_string` + `filter_values` → 执行查询
|
||
- 自定义属性筛选通过 `Filters::CustomAttributeFilterHelper`，查询 `custom_attribute_definitions` 表获取属性定义，动态构建 JOIN + WHERE 条件
|
||
- **涉及的权限策略**：
|
||
- ContactPolicy `filter?` → 所有坐席可用
|
||
|
||
---
|
||
|
||
## 3. 联系人合并（Merge）
|
||
|
||
### 合并操作
|
||
- **功能描述**：将两个联系人合并为一个。base_contact 保留为主联系人，mergee_contact 的数据被合并后删除。合并操作在事务中执行，迁移所有关联数据。
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/actions/contact_merge` — 合并联系人
|
||
- 请求参数：`{ base_contact_id, mergee_contact_id }`
|
||
- **涉及的数据模型 + 关键字段**：无独立数据模型，纯 Action 类
|
||
- **涉及的业务逻辑**：
|
||
- **ContactMergeAction**（`app/actions/contact_merge_action.rb`）：
|
||
1. `validate_contacts` — 校验两个联系人属于同一账户
|
||
2. `merge_conversations` — 将 mergee 的所有 Conversation 的 contact_id 改为 base
|
||
3. `merge_messages` — 将 mergee 作为 sender 的所有 Message 改为 base
|
||
4. `merge_contact_inboxes` — 将 mergee 的所有 ContactInbox 改为 base
|
||
5. `merge_contact_notes` — 将 mergee 的所有 Note 改为 base
|
||
6. `merge_and_remove_mergee_contact` — 合并属性策略：
|
||
- 可合并字段：`identifier, name, email, phone_number, additional_attributes, custom_attributes`
|
||
- 使用 `deep_merge`：base_contact 的值优先，mergee 的空值被跳过
|
||
- 合并后删除 mergee_contact
|
||
7. 触发 `CONTACT_MERGED` 事件（Dispatcher dispatch）
|
||
- **涉及的权限策略**：
|
||
- ContactMergesController 继承 BaseController，需要 `check_authorization`
|
||
- **注意事项**：
|
||
- 如果 base_contact.id == mergee_contact.id，直接返回 base_contact（防止重复合并）
|
||
- 合并是事务性操作，失败则回滚
|
||
|
||
---
|
||
|
||
## 4. ContactInbox（联系人-收件箱关联）
|
||
|
||
### ContactInbox 创建
|
||
- **功能描述**：ContactInbox 是联系人与收件箱的中间关联表，记录联系人在某个渠道的外部标识（source_id）。一个联系人可以关联多个 Inbox（多渠道联系）。
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/{contact_id}/contact_inboxes` — 创建 ContactInbox
|
||
- 请求参数：`{ inbox_id, source_id }`
|
||
- **涉及的数据模型**：
|
||
- **ContactInbox**（`contact_inboxes` 表）核心字段：
|
||
- `id, contact_id, inbox_id, source_id, hmac_verified, pubsub_token`
|
||
- 索引：`inbox_id + source_id` UNIQUE（同一收件箱+source唯一）
|
||
- `pubsub_token` UNIQUE（用于 ActionCable 推送）
|
||
- **涉及的业务逻辑**：
|
||
- **ContactInboxBuilder**（`app/builders/contact_inbox_builder.rb`）：
|
||
- 若已有相同 inbox_id + source_id 的 ContactInbox，直接返回（不重复创建）
|
||
- 若未指定 source_id，根据渠道类型自动生成：
|
||
- Email → 使用 `contact.email`
|
||
- WhatsApp → 使用 `contact.phone_number`（去掉 +）
|
||
- Twilio SMS → 根据渠道 medium 生成（SMS→带+的电话，WhatsApp→去掉+）
|
||
- SMS → 使用 `contact.phone_number`
|
||
- WebWidget/API → `SecureRandom.uuid`
|
||
- 支持 `hmac_verified` 参数（Website 渠道 HMAC 校验标识）
|
||
- `valid_source_id_format?` — 校验 source_id 格式（使用 RegexHelper）
|
||
- `current_conversation` — 返回该 ContactInbox 的最新对话
|
||
- `webhook_data` — 包含 contact/inbox/account/current_conversation 的完整推送数据
|
||
- **ContactableInboxes（可用收件箱）**：
|
||
- `GET /api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes` — 获取该联系人可以发消息的收件箱列表
|
||
- **Contacts::ContactableInboxesService**：遍历账户所有 Inbox，根据渠道类型和联系人信息判断可用性：
|
||
- Email → 需要有 email
|
||
- WhatsApp/SMS/Twilio → 需要有 phone_number
|
||
- WebWidget → 需要已有 ContactInbox 且无活跃对话
|
||
- API → 直接可用（可用已有 source_id 或生成 UUID）
|
||
|
||
### ContactInbox 清理（Stale Cleanup）
|
||
- **功能描述**：系统定期清理没有关联对话且创建时间过久的 ContactInbox 和无标识信息的联系人。
|
||
- **涉及的业务逻辑**：
|
||
- `ContactInbox.stale_without_conversations(time_period)` — scope 查找无对话的旧 ContactInbox
|
||
- `Contact.stale_without_conversations(time_period)` — scope 查找无标识、无对话的旧联系人
|
||
- `Internal::RemoveStaleContactInboxesJob/Service` — 定期清理
|
||
- `Internal::RemoveStaleContactsJob/Service` — 定期清理
|
||
|
||
---
|
||
|
||
## 5. CustomAttributeDefinition（自定义属性定义）
|
||
|
||
### 自定义属性定义 CRUD
|
||
- **功能描述**：自定义属性定义（CustomAttributeDefinition）是账户级别的配置，定义可用于 Contact/Conversation/Company 的扩展字段。每个定义指定属性键、显示名称、显示类型、所属模型等。定义后，对应实体的 `custom_attributes` jsonb 字段即可存储该键值对。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/custom_attribute_definitions` — 按模型类型列出定义
|
||
- `GET /api/v1/accounts/{account_id}/custom_attribute_definitions/{id}` — 获取单个定义
|
||
- `POST /api/v1/accounts/{account_id}/custom_attribute_definitions` — 创建定义
|
||
- `PUT /api/v1/accounts/{account_id}/custom_attribute_definitions/{id}` — 更新定义
|
||
- `DELETE /api/v1/accounts/{account_id}/custom_attribute_definitions/{id}` — 删除定义
|
||
- **涉及的数据模型**：
|
||
- **CustomAttributeDefinition**（`custom_attribute_definitions` 表）核心字段：
|
||
- `id, attribute_display_name, attribute_description, attribute_key, attribute_display_type, attribute_model, attribute_values(jsonb), default_value, regex_pattern, regex_cue, account_id`
|
||
- `attribute_model` enum：`conversation_attribute(0), contact_attribute(1), company_attribute(2)`
|
||
- `attribute_display_type` enum：`text(0), number(1), currency(2), percent(3), link(4), date(5), list(6), checkbox(7)`
|
||
- 索引：`attribute_key + attribute_model + account_id` UNIQUE
|
||
- **标准属性（不可覆盖）**：
|
||
- Contact 标准属性：`name, email, phone_number, identifier, country_code, city, company_name, created_at, last_activity_at, referer, blocked`
|
||
- Conversation 标准属性：`status, priority, assignee_id, inbox_id, team_id, display_id, campaign_id, labels, browser_language, country_code, referer, created_at, last_activity_at`
|
||
- Company 标准属性：`name, domain, description, contacts_count, created_at, updated_at, last_activity_at`
|
||
- **涉及的校验**：
|
||
- `attribute_must_not_conflict` — attribute_key 不能与标准属性冲突（on :create）
|
||
- `normalize_attribute_fields` — attribute_key 自动 downcase
|
||
- `regex_pattern/regex_cue` — 企业版扩展，支持正则校验提示
|
||
- `attribute_values` — list 类型时存储可选值列表
|
||
- **涉及的业务逻辑**：
|
||
- `after_update :update_widget_pre_chat_custom_fields` — 更新时同步到 Widget 的预聊天自定义字段（非 company_attribute）
|
||
- `after_destroy :sync_widget_pre_chat_custom_fields` — 删除时同步
|
||
- 企业版 **Enterprise::Concerns::CustomAttributeDefinition**：
|
||
- `after_destroy :cleanup_conversation_required_attributes` — 删除定义后清理 `account.conversation_required_attributes`
|
||
- **涉及的权限策略**：
|
||
- **CustomAttributeDefinitionPolicy**：`index?, show?` → 坐席+管理员；`create?, update?, destroy?` → 仅管理员
|
||
|
||
### 联系人自定义属性操作
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/{id}/destroy_custom_attributes` — 删除指定的自定义属性键
|
||
- 请求参数：`{ custom_attributes: ["key1", "key2"] }`
|
||
- 实际是排除（excluding）指定键，保留其余
|
||
- 更新联系人时通过 `custom_attributes: {}` 参数 merge 到已有属性
|
||
|
||
---
|
||
|
||
## 6. CustomFilter（自定义筛选器）
|
||
|
||
### 自定义筛选器 CRUD
|
||
- **功能描述**：自定义筛选器（CustomFilter）是用户级别的筛选条件保存机制，允许坐席保存常用筛选条件以便快速复用。每个筛选器属于一个用户+账户，可按类型区分（对话/联系人/报告）。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/custom_filters?filter_type=contact` — 列出用户的联系人筛选器
|
||
- `GET /api/v1/accounts/{account_id}/custom_filters/{id}` — 获取单个筛选器
|
||
- `POST /api/v1/accounts/{account_id}/custom_filters` — 创建筛选器
|
||
- `PUT /api/v1/accounts/{account_id}/custom_filters/{id}` — 更新筛选器
|
||
- `DELETE /api/v1/accounts/{account_id}/custom_filters/{id}` — 删除筛选器
|
||
- **涉及的数据模型**：
|
||
- **CustomFilter**（`custom_filters` 表）核心字段：
|
||
- `id, name, filter_type, query(jsonb), account_id, user_id`
|
||
- `filter_type` enum：`conversation(0), contact(1), report(2)`
|
||
- **涉及的校验**：
|
||
- `validate_number_of_filters` — 每用户每账户最多 `Limits::MAX_CUSTOM_FILTERS_PER_USER` 个筛选器
|
||
- **创建筛选器请求**：
|
||
- `{ custom_filter: { name: "VIP Contacts", filter_type: "contact", query: { contacts: [{ attribute_key: "email", filter_operator: "contains", values: ["@vip.com"] }] } } }`
|
||
|
||
---
|
||
|
||
## 7. Note（笔记）
|
||
|
||
### 笔记 CRUD
|
||
- **功能描述**：笔记（Note）是联系人级别的内部备忘信息，供坐席记录与客户相关的备注。笔记按创建时间倒序排列。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/contacts/{contact_id}/notes` — 列出笔记（倒序）
|
||
- `GET /api/v1/accounts/{account_id}/contacts/{contact_id}/notes/{id}` — 获取单条笔记
|
||
- `POST /api/v1/accounts/{account_id}/contacts/{contact_id}/notes` — 创建笔记
|
||
- `PUT /api/v1/accounts/{contact_id}/accounts/{account_id}/contacts/{contact_id}/notes/{id}` — 更新笔记
|
||
- `DELETE /api/v1/accounts/{account_id}/contacts/{contact_id}/notes/{id}` — 删除笔记
|
||
- **涉及的数据模型**：
|
||
- **Note**（`notes` 表）核心字段：
|
||
- `id, content(text, not null), account_id, contact_id, user_id, created_at, updated_at`
|
||
- `user_id` optional — 可匿名笔记
|
||
- **涉及的业务逻辑**：
|
||
- `before_validation :ensure_account_id` — 自动从 contact 取 account_id
|
||
- `scope :latest` → `order(created_at: :desc)`
|
||
- 创建时自动注入 `user_id: Current.user.id`
|
||
- 删除联系人时级联删除（`dependent: :destroy_async`）
|
||
- 合并联系人时笔记迁移到 base_contact
|
||
|
||
---
|
||
|
||
## 8. Label（标签）
|
||
|
||
### 标签 CRUD
|
||
- **功能描述**：标签（Label）是账户级别的分类标记，可用于联系人和对话。标签通过 ActsAsTaggableOn 实现多对多关联。标签有颜色、描述、是否在侧边栏显示等属性。
|
||
- **涉及的API端点**（账户级别标签管理）：
|
||
- `GET /api/v1/accounts/{account_id}/labels` — 列出标签
|
||
- `GET /api/v1/accounts/{account_id}/labels/{id}` — 获取标签
|
||
- `POST /api/v1/accounts/{account_id}/labels` — 创建标签
|
||
- `PUT /api/v1/accounts/{account_id}/labels/{id}` — 更新标签
|
||
- `DELETE /api/v1/accounts/{account_id}/labels/{id}` — 删除标签
|
||
- **涉及的数据模型**：
|
||
- **Label**（`labels` 表）核心字段：
|
||
- `id, title, color(default "#1f93ff"), description, show_on_sidebar, account_id`
|
||
- 索引：`title + account_id` UNIQUE
|
||
- **涉及的校验**：
|
||
- title：presence, format（UNICODE_CHARACTER_NUMBER_HYPHEN_UNDERSCORE），uniqueness（scope: account_id）
|
||
- `before_validation` → title 自动 downcase
|
||
- **涉及的业务逻辑**：
|
||
- `acts_as_taggable_on :labels`（通过 Labelable concern）
|
||
- `Labelable` concern 方法：
|
||
- `update_labels(labels)` — 设置标签列表（覆盖）
|
||
- `add_labels(new_labels)` — 添加标签（追加）
|
||
- `after_update_commit :update_associated_models` — 标题变更时触发 `Labels::UpdateJob`，异步更新所有使用旧标签名的 taggings
|
||
- 删除标签时触发 `Labels::RemoveAssociationsJob`，清理所有 taggings
|
||
- `default_scope { order(:title) }` — 默认按标题排序
|
||
|
||
### 联系人标签操作
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/{contact_id}/labels` — 设置/更新联系人标签
|
||
- `GET /api/v1/accounts/{account_id}/contacts/{contact_id}/labels` — 获取联系人标签列表
|
||
- 请求参数：`{ labels: ["vip", "enterprise"] }`
|
||
- 使用 LabelConcern：`model.update_labels(permitted_params[:labels])`
|
||
|
||
### 联系人批量标签操作
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/bulk_actions` — 批量操作（type=Contact）
|
||
- 请求参数：`{ type: "Contact", ids: [...], labels: { add: ["vip"] } }`
|
||
- **Contacts::BulkAssignLabelsService**：批量给多个联系人添加标签
|
||
|
||
---
|
||
|
||
## 9. Company（企业版）
|
||
|
||
### 公司 CRUD
|
||
- **功能描述**：公司（Company）是企业版功能，代表联系人所属的企业组织。联系人通过 email 域名自动关联到公司，也可手动关联。Company 拥有自己的 custom_attributes、avatar、description 等。
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/companies` — 公司列表（分页 25 条/页）
|
||
- `GET /api/v1/accounts/{account_id}/companies/search?q=xxx` — 搜索公司（name/domain）
|
||
- `GET /api/v1/accounts/{account_id}/companies/{id}` — 获取公司详情
|
||
- `POST /api/v1/accounts/{account_id}/companies` — 创建公司
|
||
- `PUT /api/v1/accounts/{account_id}/companies/{id}` — 更新公司
|
||
- `DELETE /api/v1/accounts/{account_id}/companies/{id}` — 删除公司（仅管理员）
|
||
- `POST /api/v1/accounts/{account_id}/companies/{id}/destroy_custom_attributes` — 删除自定义属性
|
||
- `DELETE /api/v1/accounts/{account_id}/companies/{id}/avatar` — 删除公司头像
|
||
- 需 `ensure_companies_enabled!` → feature flag `companies` 必须启用
|
||
- **涉及的数据模型**：
|
||
- **Company**（`companies` 表）核心字段：
|
||
- `id, name(not null, length limit), domain(unique scope: account_id, 格式校验), description(text, length limit), additional_attributes(jsonb), custom_attributes(jsonb), contacts_count, last_activity_at, account_id`
|
||
- 索引：`account_id + domain` UNIQUE WHERE domain IS NOT NULL
|
||
- **涉及的业务逻辑**：
|
||
- **Company** include Avatarable → 支持 avatar + Gravatar
|
||
- `before_validation :prepare_jsonb_attributes` — 清理 jsonb
|
||
- `after_create_commit :fetch_favicon` — domain 存在时异步拉取 favicon
|
||
- `has_many :contacts, dependent: :nullify` — 删除公司时联系人 company_id 设为 NULL
|
||
- scope：`ordered_by_name`, `search_by_name_or_domain`
|
||
|
||
### 公司-联系人关联
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/companies/{company_id}/contacts` — 公司下的联系人列表
|
||
- `GET /api/v1/accounts/{account_id}/companies/{company_id}/contacts/search?q=xxx` — 在公司下搜索联系人
|
||
- `POST /api/v1/accounts/{account_id}/companies/{company_id}/contacts` — 将联系人关联到公司
|
||
- `DELETE /api/v1/accounts/{account_id}/companies/{company_id}/contacts/{contact_id}` — 从公司中移除联系人
|
||
- **自动关联逻辑**：
|
||
- **Enterprise::Concerns::Contact**：
|
||
- `after_commit :associate_company_from_email, on: [:create, :update], if: :should_associate_company?`
|
||
- 条件：`email.present? && company_id.nil? && saved_change_to_email? && saved_change_to_email.first.nil?`
|
||
- **Contacts::CompanyAssociationService**：
|
||
- 检查邮箱是否为商业邮箱（`Companies::BusinessEmailDetectorService`）
|
||
- 提取域名 → `find_or_create_by!(account, domain)` 创建或查找公司
|
||
- 公司名称从 `additional_attributes.company_name` 或域名推导
|
||
- 关联后更新 `contact.company_id` + `Company.contacts_count`（counter_cache）
|
||
- `after_update_commit :record_company_activity` — 联系人活跃时更新公司 `last_activity_at`
|
||
|
||
---
|
||
|
||
## 10. 批量操作
|
||
|
||
### 批量删除联系人
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/bulk_actions` — `{ type: "Contact", action_name: "delete", ids: [...] }`
|
||
- 权限检查：删除操作需 ContactPolicy `destroy?`（仅管理员）
|
||
- **涉及的业务逻辑**：
|
||
- **Contacts::BulkActionService** → 调度到 `Contacts::BulkActionJob`
|
||
- `delete_requested?` → `Contacts::BulkDeleteService` → `find_each(&:destroy!)`
|
||
- **涉及的数据模型**：无独立模型
|
||
|
||
---
|
||
|
||
## 11. 导入/导出
|
||
|
||
### CSV 导入
|
||
- **功能描述**：支持通过 CSV 文件批量导入联系人。仅管理员可操作。
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/import` — 导入 CSV
|
||
- 如企业版未启用联系人导入功能，返回错误
|
||
|
||
### CSV 导出
|
||
- **功能描述**：支持将联系人导出为 CSV 文件，异步执行完成后通过邮件发送给管理员。
|
||
- **涉及的API端点**：
|
||
- `POST /api/v1/accounts/{account_id}/contacts/export` — 导出
|
||
- **涉及的业务逻辑**：
|
||
- **Account::ContactsExportJob**：
|
||
- 异步生成 CSV，支持自定义列名
|
||
- Labels 列特殊处理（preload + join taggings）
|
||
- 生成后通过 `AdministratorNotifications::MailService` 发送邮件通知
|
||
|
||
---
|
||
|
||
## 12. 联系人对话查看
|
||
|
||
### 获取联系人的对话
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{account_id}/contacts/{contact_id}/conversations` — 获取联系人的所有对话
|
||
|
||
### 获取联系人的附件
|
||
- **涉及的API端点**：
|
||
- `GET /api/v1/accounts/{contact_id}/accounts/{account_id}/contacts/{contact_id}/attachments` — 获取联系人相关附件
|
||
|
||
---
|
||
|
||
## 13. 关系图谱总结
|
||
|
||
```
|
||
Account
|
||
├── Contact (belongs_to, N:1)
|
||
│ ├── ContactInbox (has_many, N:N through contact_inboxes)
|
||
│ │ ├── Inbox (belongs_to)
|
||
│ │ ├── Conversation (has_many)
|
||
│ │ └── Pubsubable (pubsub_token)
|
||
│ ├── Conversation (has_many)
|
||
│ ├── Message (has_many, as: sender)
|
||
│ ├── Note (has_many)
|
||
│ ├── CsatSurveyResponse (has_many)
|
||
│ ├── Labels (acts_as_taggable_on :labels)
|
||
│ ├── Avatar (has_one_attached)
|
||
│ ├── Company (belongs_to, 企业版, counter_cache)
|
||
│ ├── custom_attributes (jsonb)
|
||
│ └── additional_attributes (jsonb)
|
||
├── Company (企业版, has_many contacts)
|
||
├── CustomAttributeDefinition (has_many)
|
||
├── CustomFilter (has_many)
|
||
└── Label (has_many)
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 跨模块依赖
|
||
|
||
| 依赖模块 | 依赖内容 |
|
||
|----------|---------|
|
||
| M1 账户与用户 | Contact/Company/Label/CustomAttributeDefinition 均属于 Account；ContactPolicy/CustomAttributeDefinitionPolicy 依赖 AccountUser 角色 |
|
||
| M2 收件箱与渠道 | ContactInbox 连接 Contact ↔ Inbox；ContactInboxBuilder 根据渠道类型生成 source_id；ContactableInboxesService 查询可用渠道 |
|
||
| M3 对话与消息 | Contact has_many Conversations；Contact 是 Message 的 polymorphic sender；合并时迁移 Conversation 和 Message |
|
||
| M5 团队与分配 | Contact 不直接关联 Team（通过 Conversation 间接关联） |
|
||
| M7 通知与事件 | CONTACT_MERGED 事件经 Dispatcher dispatch；contact.create/update/destroy 事件推送 ActionCable |
|
||
|
||
---
|
||
|
||
## 15. GoChat 实现建议
|
||
|
||
### P0（核心必备）
|
||
1. **Contact CRUD**：联系人创建/读取/更新/删除，含 email/phone/name/identifier 基本字段 + additional_attributes/custom_attributes jsonb
|
||
2. **ContactInbox**：联系人-收件箱关联，含 source_id，创建时按渠道类型智能生成
|
||
3. **Contact 搜索**：ILIKE 模糊搜索（name/email/phone/identifier）
|
||
4. **Contact 状态类型**：visitor/lead/customer 三级进阶，自动升级逻辑
|
||
5. **Note CRUD**：联系人笔记，含 content + user_id + timestamps
|
||
|
||
### P1（重要增强）
|
||
6. **Label 系统**：账户级标签 CRUD + 联系人/对话标签关联（可使用简化版 taggable）
|
||
7. **Contact 合并**：base + mergee 合并操作，迁移所有关联数据
|
||
8. **Contact 筛选**：多条件组合筛选（标准属性 + 自定义属性）
|
||
9. **CustomAttributeDefinition**：自定义属性定义 CRUD（contact/conversation/company 三类）
|
||
10. **CustomFilter**：用户级筛选条件保存和复用
|
||
11. **批量操作**：批量删除 + 批量标签赋值
|
||
12. **ContactableInboxes**：查询联系人可用的收件箱列表
|
||
|
||
### P2（企业版扩展）
|
||
13. **Company**：公司 CRUD + 自动关联（email 域名检测）
|
||
14. **Company-Contact**：公司下的联系人管理 + 移除关联
|
||
15. **Stale Cleanup**：定期清理无对话/无标识的 ContactInbox 和 Contact
|
||
16. **Contact 导入/导出**：CSV 批量导入 + 异步导出邮件通知
|
||
17. **regex_pattern/regex_cue**：自定义属性正则校验 |