# 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**：自定义属性正则校验