# M11: 企业版功能（Enterprise Features）

## 模块概述

本模块覆盖 Chatwoot 企业版专属功能，包括：SLA 策略与应用（SlaPolicy + AppliedSla + SlaEvent）、审计日志（AuditLog）、自定义角色权限系统（CustomRole）、组织/公司管理（Company）、坐席容量策略（AgentCapacityPolicy + InboxCapacityLimit）、语音通话（Call + Voice 系列 Service）、SAML SSO 单点登录（AccountSamlSettings）、SidekiqCron 定时任务调度。这些功能在社区版基础上增强了合规、安全、权限精细化、组织管理和语音通信能力。

---

### 功能1：SLA 策略管理（SlaPolicy CRUD + 应用到对话）

- **功能描述**：账户级 SLA（Service Level Agreement）策略管理。管理员可创建 SLA 策略，设定首响时间（FRT）、下次响应时间（NRT）、解决时间（RT）阈值，并将策略绑定到对话。系统通过定时 Job 定期评估 SLA 是否达标/违规，并自动生成 SlaEvent 通知。
- **用户操作流程（UI交互步骤）**：
  1. 进入 Settings → SLA 页面
  2. 点击"Add SLA Policy"，填写名称、描述
  3. 设定三个时间阈值：first_response_time_threshold（首响）、next_response_time_threshold（下次响应）、resolution_time_threshold（解决），单位为秒
  4. 可勾选"only_during_business_hours"，仅在工作时间内计算 SLA
  5. 保存后，可在 Inbox 设置中将 SLA 策略绑定到收件箱，新进入的对话自动应用该 SLA
  6. 对话列表中可查看 SLA 状态标识（active/hit/missed/active_with_misses）
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/sla_policies` — 获取 SLA 策略列表
  - `POST /api/v1/accounts/{account_id}/sla_policies` — 创建 SLA 策略
    - 请求：`{ sla_policy: { name: "Standard SLA", description: "...", first_response_time_threshold: 300, next_response_time_threshold: 600, resolution_time_threshold: 86400, only_during_business_hours: false } }`
    - 响应：策略对象 `{ id, name, description, first_response_time_threshold, next_response_time_threshold, resolution_time_threshold, only_during_business_hours, account_id }`
  - `GET /api/v1/accounts/{account_id}/sla_policies/{id}` — 获取单个 SLA 策略
  - `PUT /api/v1/accounts/{account_id}/sla_policies/{id}` — 更新 SLA 策略
  - `DELETE /api/v1/accounts/{account_id}/sla_policies/{id}` — 删除 SLA 策略（异步通过 DeleteObjectJob）
- **涉及的数据模型 + 关键字段**：
  - `SlaPolicy`（表 `sla_policies`）：
    - `id` (bigint, PK)
    - `name` (string, not null) — 策略名称
    - `description` (string) — 策略描述
    - `first_response_time_threshold` (float) — 首响时间阈值（秒）
    - `next_response_time_threshold` (float) — 下次响应时间阈值（秒）
    - `resolution_time_threshold` (float) — 解决时间阈值（秒）
    - `only_during_business_hours` (boolean, default false) — 仅在工作时间计算
    - `account_id` (bigint, not null, FK)
  - `AppliedSla`（表 `applied_slas`）：
    - `id` (bigint, PK)
    - `sla_status` (integer, enum) — active(0)/hit(1)/missed(2)/active_with_misses(3)
    - `account_id` (bigint, not null, FK)
    - `sla_policy_id` (bigint, not null, FK)
    - `conversation_id` (bigint, not null, FK)
    - 唯一索引：`(account_id, sla_policy_id, conversation_id)`
  - `SlaEvent`（表 `sla_events`）：
    - `id` (bigint, PK)
    - `event_type` (integer, enum) — frt(0)/nrt(1)/rt(2)
    - `meta` (jsonb) — 事件元数据
    - `account_id`, `applied_sla_id`, `conversation_id`, `inbox_id`, `sla_policy_id` (bigint, FK)
  - 关联：`SlaPolicy has_many :conversations, :applied_slas`；`AppliedSla has_many :sla_events`；`AppliedSla belongs_to :sla_policy, :conversation, :account`
- **涉及的业务逻辑（service层）**：
  - **Sla::EvaluateAppliedSlaService** — 核心 SLA 评估逻辑：
    - 依次检查 FRT/NRT/RT 三个阈值
    - 首响检查：`conversation.created_at + sla_policy.first_response_time_threshold`，对比首条回复时间
    - 下次响应检查：等待客户回复后，对比等待时间 + 阈值
    - 解决时间检查：对话创建时间 + 阈值
    - 达标时调用 `handle_hit_sla`，违规时调用 `handle_missed_sla` 生成 SlaEvent
  - **Sla::TriggerSlasForAccountsJob** → **Sla::ProcessAccountAppliedSlasJob** → **Sla::ProcessAppliedSlaJob** — 定时评估链路，遍历所有 active/active_with_misses 状态的 AppliedSla
  - **rake sla:apply_to_conversations** — 批量给已有对话应用 SLA 策略的迁移任务
- **涉及的自动化/规则/事件**：
  - 对话创建时，如 Inbox 绑定了 SLA 策略，自动创建 AppliedSla（conversation callback）
  - SlaEvent 创建后自动发送通知（`after_create_commit :create_notifications`）
  - 对话 resolve 后，EvaluateAppliedSlaService 判断 SLA 是否最终达标
- **涉及的权限/Policy**：
  - `SlaPolicyPolicy`：index/show → administrator || agent；create/update/destroy → administrator
- **GoChat 实现要点**：
  - SLA 三种阈值（FRT/NRT/RT）是核心概念，需要完整建模
  - 定时评估 Job 需要设计好调度频率（Chatwoot 每5分钟通过 TriggerScheduledItemsJob 触发）
  - `only_during_business_hours` 需要结合 M3 的 BusinessHours 计算
  - AppliedSla 状态机：active → active_with_misses → hit/missed

---

### 功能2：审计日志（AuditLog）

- **功能描述**：企业版审计日志，基于 `audited` gem 记录账户内关键资源的变更操作（创建/更新/删除），包括变更内容、操作人、IP 地址等。管理员可在审计日志页面按时间倒序查看所有变更记录，用于合规审计和安全追溯。
- **用户操作流程（UI交互步骤）**：
  1. 账户需启用 `audit_logs` feature flag
  2. 进入账户设置 → Audit Logs 页面
  3. 可按时间倒序浏览所有变更记录（每页15条）
  4. 每条记录显示：操作类型（action）、被审计对象（auditable_type + auditable_id）、变更内容（audited_changes）、操作人（username/email）、IP（remote_address）、时间戳
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/audit_logs` — 获取审计日志（分页）
    - 请求参数：`page`（页码）
    - 响应：审计记录列表，含 `action, auditable_type, auditable_id, audited_changes, username, remote_address, request_uuid, created_at, associated_type, associated_id`
- **涉及的数据模型 + 关键字段**：
  - `Enterprise::AuditLog`（继承 `Audited::Audit`，表 `audits`）：
    - `id` (bigint, PK)
    - `action` (string) — 操作类型：create/update/destroy
    - `auditable_type` (string) — 被审计对象类型（Account/Inbox/User/AccountUser 等）
    - `auditable_id` (bigint) — 被审计对象 ID
    - `audited_changes` (jsonb) — 变更内容
    - `associated_type` (string) — 关联对象类型（通常是 Account）
    - `associated_id` (bigint) — 关联对象 ID
    - `user_id` (bigint) — 操作人 ID
    - `username` (string) — 操作人邮箱（自动填充）
    - `remote_address` (string) — IP 地址
    - `request_uuid` (string) — 请求唯一标识
    - `version` (integer) — 版本号
    - `comment` (string)
    - `user_type` (string)
    - `created_at` (datetime)
  - `Enterprise::AuditLog` 在 `after_save` 时自动补充 `associated_type/associated_id/username`
- **涉及的业务逻辑（service层）**：
  - 通过 `audited` gem 的 `audited` 声明自动记录变更，无需独立 service
  - 各模型通过 concern 声明审计范围：
    - `Enterprise::Audit::Account` — `audited except: :updated_at, on: [:update]`
    - `Enterprise::Audit::Inbox` — `audited associated_with: :account, on: [:create, :update]`
    - `Enterprise::Audit::AccountUser` — `audited only: [:availability, :role, :account_id, :inviter_id, :user_id], on: [:create, :update], associated_with: :account`
    - `Enterprise::Audit::User` — `audited only: [:availability, :display_name, :email, :name]`（手动记录登录/登出）
    - `Enterprise::Audit::Conversation` — `audited only: [], on: [:destroy]`（仅记录删除）
    - 其他：AutomationRule, Webhook, Macro, AgentBot, Team, TeamMember, InboxMember 等均有审计 concern
  - 全局配置：`config/initializers/audited.rb` → `config.audit_class = 'Enterprise::AuditLog'`
- **涉及的自动化/规则/事件**：
  - 模型变更时自动写入 `audits` 表（audited gem callback）
  - `Enterprise::AuditLog.after_save :log_additional_information` — 自动补充关联信息和操作人邮箱
- **涉及的权限/Policy**：
  - `Api::V1::Accounts::AuditLogsController` — 仅 administrator 可访问（`before_action :check_admin_authorization?`）
  - 需要账户启用 `audit_logs` feature flag
- **GoChat 实现要点**：
  - 审计日志需基于变更追踪机制（类似 audited gem），在核心模型上声明审计字段
  - 需记录操作人、IP、变更内容、时间戳
  - 分页查询接口，按时间倒序排列
  - associated_type/associated_id 用于按账户维度聚合审计记录
  - feature flag 控制审计功能的启用

---

### 功能3：自定义角色权限系统（CustomRole）

- **功能描述**：企业版自定义角色系统，允许管理员在账户级创建自定义角色，定义细粒度权限列表，并将角色分配给 AccountUser。自定义角色扩展了默认的三级角色体系（administrator/agent/supervisor），使权限控制更灵活。
- **用户操作流程（UI交互步骤）**：
  1. 进入 Settings → Custom Roles 页面
  2. 点击"Add Role"，填写角色名称、描述
  3. 从权限列表勾选所需权限
  4. 创建后可在 Agent Management 中将此角色分配给坐席
  5. 坐席权限将基于其 CustomRole 的 permissions 列表生效
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/custom_roles` — 获取自定义角色列表
  - `POST /api/v1/accounts/{account_id}/custom_roles` — 创建自定义角色
    - 请求：`{ custom_role: { name: "Sales Agent", description: "...", permissions: ["conversation_manage", "contact_manage"] } }`
    - 响应：角色对象 `{ id, name, description, permissions, account_id }`
  - `GET /api/v1/accounts/{account_id}/custom_roles/{id}` — 获取单个角色
  - `PUT /api/v1/accounts/{account_id}/custom_roles/{id}` — 更新角色
  - `DELETE /api/v1/accounts/{account_id}/custom_roles/{id}` — 删除角色
- **涉及的数据模型 + 关键字段**：
  - `CustomRole`（表 `custom_roles`）：
    - `id` (bigint, PK)
    - `name` (string) — 角色名称
    - `description` (string) — 角色描述
    - `permissions` (text array, default []) — 权限列表
    - `account_id` (bigint, not null, FK)
  - 可用权限列表（`PERMISSIONS` 常量）：
    - `conversation_manage` — 管理所有对话
    - `conversation_unassigned_manage` — 管理未分配对话并可认领
    - `conversation_participating_manage` — 管理自己参与的对话
    - `contact_manage` — 管理联系人
    - `report_manage` — 管理报表
    - `knowledge_base_manage` — 管理知识库
  - 关联：`CustomRole has_many :account_users, dependent: :nullify`
  - `Enterprise::AccountUser` 扩展：`permissions` 方法返回 `custom_role.permissions + ['custom_role']`（当有自定义角色时），否则返回默认角色权限
- **涉及的业务逻辑（service层）**：
  - 无独立 service，CRUD 在 controller 完成
  - 权限合并逻辑在 `Enterprise::AccountUser#permissions` 中
  - 删除 CustomRole 时，关联的 AccountUser 的 custom_role_id 设为 NULL（nullify），回归默认角色权限
- **涉及的自动化/规则/事件**：
  - AccountUser 权限检查时，如存在 custom_role 则优先使用其 permissions 列表
  - CustomRole 删除后，AccountUser 自动回退到默认角色
- **涉及的权限/Policy**：
  - `CustomRolePolicy`：所有操作（index/show/create/update/destroy）仅 administrator 可执行
- **GoChat 实现要点**：
  - 权限列表需设计为可扩展的枚举/常量体系
  - AccountUser 需支持 custom_role_id 外键
  - 权限合并逻辑：CustomRole.permissions + 默认角色权限
  - 删除角色时注意 nullify 而非 restrict_with_error
  - 当前6项权限可能需要扩展（如 automation_manage、inbox_manage 等）

---

### 功能4：组织/公司管理（Company）

- **功能描述**：企业版组织管理功能，允许账户创建"公司"（Company）实体，将联系人按组织分组。每个公司有名称、域名、描述、自定义属性，支持头像和 favicon 自动获取。联系人可归属于公司，系统可根据联系人邮箱域名自动关联公司。
- **用户操作流程（UI交互步骤）**：
  1. 进入 Contacts → Companies 页面（需启用 `companies` feature flag）
  2. 点击"Add Company"，填写名称、域名、描述
  3. 可上传公司头像
  4. 如填入域名，系统自动获取 favicon
  5. 创建后可将联系人手动归属到该公司
  6. 系统也可根据联系人邮箱自动关联（业务邮箱检测 → 域名匹配 → 自动建公司）
  7. 在公司详情页可查看关联联系人列表、活动时间线
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/companies` — 获取公司列表（分页25条/页，支持排序/过滤）
  - `GET /api/v1/accounts/{account_id}/companies/search?q=xxx` — 搜索公司（按名称/域名）
  - `POST /api/v1/accounts/{account_id}/companies` — 创建公司
    - 请求：`{ company: { name: "Acme Corp", domain: "acme.com", description: "...", additional_attributes: {}, custom_attributes: {} } }`
    - 响应：公司对象 `{ id, name, domain, description, contacts_count, last_activity_at, additional_attributes, custom_attributes, account_id }`
  - `GET /api/v1/accounts/{account_id}/companies/{id}` — 获取单个公司
  - `PUT /api/v1/accounts/{account_id}/companies/{id}` — 更新公司（custom_attributes 为 merge 逻辑）
  - `DELETE /api/v1/accounts/{account_id}/companies/{id}` — 删除公司（仅 administrator）
  - `DELETE /api/v1/accounts/{account_id}/companies/{id}/destroy_custom_attributes` — 删除指定自定义属性
  - `POST /api/v1/accounts/{account_id}/companies/{id}/avatar` — 上传/更新头像
- **涉及的数据模型 + 关键字段**：
  - `Company`（表 `companies`）：
    - `id` (bigint, PK)
    - `name` (string, not null, 最大255字符) — 公司名称
    - `domain` (string, 可选, 同账户下唯一) — 公司域名
    - `description` (text, 最大限制) — 公司描述
    - `contacts_count` (integer) — 关联联系人数（counter cache）
    - `last_activity_at` (datetime) — 最后活动时间
    - `additional_attributes` (jsonb) — 附加属性
    - `custom_attributes` (jsonb) — 自定义属性（merge 语义）
    - `account_id` (bigint, not null, FK)
    - 唯一索引：`(account_id, domain) WHERE domain IS NOT NULL`
  - 关联：`Company has_many :contacts, dependent: :nullify`；`Company include Avatarable`
- **涉及的业务逻辑（service层）**：
  - **Companies::BusinessEmailDetectorService** — 检测邮箱是否为业务邮箱（排除 disposable/free provider），用于自动关联判断
  - **Companies::ContactMembershipService** — 公司-联系人关联管理：
    - `assign(contact:)` — 将联系人归属公司，更新 company.last_activity_at
    - `remove(contact:)` — 移除联系人归属
  - **Contacts::CompanyAssociationService** — 自动根据邮箱域名关联公司：
    - 检测是否为业务邮箱 → 提取域名 → find_or_create_by(domain) → 自动归属
  - Company model：
    - `after_create_commit :fetch_favicon` — 域名存在时异步获取 favicon
    - `record_activity_at!(timestamp)` — 滚动更新 last_activity_at（5分钟间隔去重）
    - `search_by_name_or_domain(query)` — 名称/域名搜索 scope
- **涉及的自动化/规则/事件**：
  - 创建公司时如有域名，自动获取 favicon
  - 联系人创建/更新时，如邮箱为业务邮箱，自动关联对应公司
  - last_activity_at 滚动更新（ACTIVITY_ROLLUP_INTERVAL = 5分钟）
- **涉及的权限/Policy**：
  - `CompanyPolicy`：index/search/show/create/update → 所有账户用户；destroy → 仅 administrator
- **GoChat 实现要点**：
  - Company 是联系人分组维度，需与 Contact 模型建立 belongs_to 关系
  - custom_attributes 需支持 merge 语义（更新时合并而非替换）
  - domain 唯一约束（同账户下）需注意 NULL domain 不参与唯一检查
  - 自动关联逻辑：邮箱域名 → 业务邮箱检测 → find_or_create Company → assign Contact
  - contacts_count counter cache 需维护
  - 需启用 `companies` feature flag

---

### 功能5：坐席容量策略（AgentCapacityPolicy + InboxCapacityLimit）

- **功能描述**：企业版坐席容量策略，用于限制每个坐席在特定收件箱中的最大同时处理对话数。管理员创建容量策略，设定排除规则（如超过N小时的老对话不计入容量、特定标签对话不计入），并为策略关联收件箱及各自的对话上限。
- **用户操作流程（UI交互步骤）**：
  1. 进入 Settings → Agent Capacity Policies 页面
  2. 点击"Add Policy"，填写策略名称、描述
  3. 设定排除规则：exclude_older_than_hours（超时老对话排除）、excluded_labels（特定标签对话排除）
  4. 为策略关联收件箱，并设定每个收件箱的 conversation_limit（对话上限）
  5. 将策略分配给坐席（AccountUser.agent_capacity_policy_id）
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/agent_capacity_policies` — 获取容量策略列表
  - `POST /api/v1/accounts/{account_id}/agent_capacity_policies` — 创建容量策略
    - 请求：`{ agent_capacity_policy: { name: "Standard Capacity", description: "...", exclusion_rules: { exclude_older_than_hours: 24, excluded_labels: ["spam"] } } }`
    - 响应：策略对象 `{ id, name, description, exclusion_rules, account_id }`
  - `GET /api/v1/accounts/{account_id}/agent_capacity_policies/{id}` — 获取单个策略
  - `PUT /api/v1/accounts/{account_id}/agent_capacity_policies/{id}` — 更新策略
  - `DELETE /api/v1/accounts/{account_id}/agent_capacity_policies/{id}` — 删除策略
- **涉及的数据模型 + 关键字段**：
  - `AgentCapacityPolicy`（表 `agent_capacity_policies`）：
    - `id` (bigint, PK)
    - `name` (string, 最大255字符, not null) — 策略名称
    - `description` (text) — 策略描述
    - `exclusion_rules` (jsonb, not null) — 排除规则：
      - `exclude_older_than_hours` — 超过N小时的活跃对话不计入容量
      - `excluded_labels` — 带特定标签的对话不计入容量
    - `account_id` (bigint, not null, FK)
  - `InboxCapacityLimit`（表 `inbox_capacity_limits`）：
    - `id` (bigint, PK)
    - `agent_capacity_policy_id` (bigint, not null, FK)
    - `inbox_id` (bigint, not null, FK)
    - `conversation_limit` (integer, not null, ≥ 0) — 该收件箱的对话上限
    - 唯一索引：`(agent_capacity_policy_id, inbox_id)`
  - 关联：
    - `AgentCapacityPolicy has_many :inbox_capacity_limits, :inboxes (through), :account_users (dependent: :nullify)`
    - `AccountUser` 增加 `agent_capacity_policy_id` 外键
- **涉及的业务逻辑（service层）**：
  - 无独立 service，CRUD 在 controller 完成
  - 容量计算逻辑（在自动分配系统中使用）：
    - 遍历坐席的所有 inbox_capacity_limits
    - 计算每个收件箱的活跃对话数（排除规则过滤）
    - 判断是否达到上限
- **涉及的自动化/规则/事件**：
  - 删除策略时，关联的 AccountUser 的 agent_capacity_policy_id 被设为 NULL
  - 容量策略在自动分配时作为坐席可分配判断依据
- **涉及的权限/Policy**：
  - `AgentCapacityPolicyPolicy`：所有操作仅 administrator 可执行
- **GoChat 实现要点**：
  - exclusion_rules 作为 jsonb 存储，灵活支持扩展
  - InboxCapacityLimit 是策略和收件箱的中间表，需唯一约束
  - 容量计算需排除规则过滤（超时对话 + 标签排除）
  - 与自动分配系统（M5）深度集成
  - AccountUser 需增加 agent_capacity_policy_id 字段

---

### 功能6：语音通话（Call + Voice Services）

- **功能描述**：企业版语音通话功能，支持通过 Twilio 和 WhatsApp 两种通话提供商进行语音通话。支持呼入/呼出通话，基于 Twilio Conference 实现坐席接听/拒接/挂断，通话状态实时更新，支持录音和转录。呼出通话在对话中创建 voice_call 类型消息气泡。
- **用户操作流程（UI交互步骤）**：
  1. 呼出通话：在联系人详情页点击"Call"，选择语音收件箱 → 系统发起 Twilio/WhatsApp 通话
  2. 呼入通话：客户拨打 Twilio 号码 → 系统创建 Call + 对话 → 坐席看到 ringing 状态
  3. 坐席接听：点击接听按钮 → 通话状态变为 in_progress → 坐席被自动分配到对话
  4. 通话结束：任一方挂断 → 状态变为 completed/no_answer/failed → 记录时长
  5. 录音/转录：通话完成后可查看录音和转录文本
- **涉及的API端点 + 请求/响应格式**：
  - `POST /api/v1/accounts/{account_id}/contacts/{contact_id}/calls` — 发起呼出通话
    - 请求：`{ inbox_id: 1, conversation_id: 42 }`（可选关联现有对话）
    - 响应：`{ conversation_id, inbox_id, call_sid, conference_sid }`
  - `POST /api/v1/accounts/{account_id}/whatsapp_calls/initiate` — WhatsApp 呼出
  - `GET /api/v1/accounts/{account_id}/whatsapp_calls/{id}` — 获取通话详情
  - `POST /api/v1/accounts/{account_id}/whatsapp_calls/{id}/accept` — 接听
  - `POST /api/v1/accounts/{account_id}/whatsapp_calls/{id}/reject` — 拒接
  - `POST /api/v1/accounts/{account_id}/whatsapp_calls/{id}/terminate` — 挂断
  - `POST /api/v1/accounts/{account_id}/whatsapp_calls/{id}/upload_recording` — 上传录音
  - Twilio Webhook 端点：
    - `POST /twilio/voice/{phone}/status` — 通话状态回调
    - `POST /twilio/voice/{phone}/call_twiml` — TwiML 响应
    - `POST /twilio/voice/{phone}/conference_status` — 会议状态回调
    - `POST /twilio/voice/{phone}/recording_status` — 录音状态回调
- **涉及的数据模型 + 关键字段**：
  - `Call`（表 `calls`）：
    - `id` (bigint, PK)
    - `direction` (integer, enum) — incoming(0)/outgoing(1)
    - `status` (string, default "ringing") — ringing/in_progress/completed/no_answer/failed
    - `provider` (integer, enum) — twilio(0)/whatsapp(1)
    - `duration_seconds` (integer) — 通话时长（秒）
    - `end_reason` (string) — 结束原因
    - `started_at` (datetime) — 开始时间
    - `transcript` (text) — 转录文本
    - `meta` (jsonb) — conference_sid, twilio_conference_sid, recording_sid, parent_call_sid, initiated_at, ended_at
    - `provider_call_id` (string, not null) — 提供商侧通话 ID（唯一约束）
    - `accepted_by_agent_id` (bigint) — 接听坐席 ID
    - `account_id`, `contact_id`, `conversation_id`, `inbox_id`, `message_id` (bigint, FK)
    - `recording` (ActiveStorage attachment) — 录音文件
    - TERMINAL_STATUSES = completed/no_answer/failed
  - 关联：`Call belongs_to :account, :inbox, :conversation, :contact, :message (optional), :accepted_by_agent (User, optional)`
- **涉及的业务逻辑（service层）**：
  - **Voice::OutboundCallBuilder** — 呼出通话构建：
    - 事务性创建 ContactInbox → Conversation → Call → Message(voice_call)
    - 通过 `inbox.channel.initiate_call` 发起 Twilio 通话
  - **Voice::InboundCallBuilder** — 呼入通话构建：
    - 查找或创建 ContactInbox → Contact → Conversation → Call → Message
    - 支持并发防重复（RecordNotUnique 处理）
  - **Voice::StatusUpdateService** — 通话状态更新：
    - Twilio 状态映射：queued/initiated/ringing → ringing; in-progress/answered → in_progress; completed → completed; busy/no-answer → no_answer; failed/canceled → failed
  - **Voice::CallStatus::Manager** — 通话状态机管理：
    - 处理状态更新，记录 started_at/duration_seconds
    - 通话结束时更新 meta、时长
    - 触发 message.touch 使前端实时更新
  - **Voice::Conference::Manager** — 会议事件处理：
    - conference-start → ringing; participant-join → in_progress + 自动分配坐席; participant-leave → 处理离开; conference-end → finalize
    - 坐席接听时自动 claim_for_user + auto_assign_conversation
  - **Voice::Provider::Twilio::ConferenceService** — Twilio 会议管理：
    - ensure_conference_sid, mark_agent_joined, end_conference
    - claim_call + assign_conversation（首次接听获胜）
  - **Voice::Provider::Twilio::TokenService** — 生成 Twilio Access Token（JWT）+ Voice Grant
  - **Voice::CallMessageBuilder** — 创建/更新 voice_call 类型消息：
    - content_type: 'voice_call', 包含 call_id/call_sid/call_source/call_direction/status
  - **Voice::RecordingStatusService** — 处理 Twilio 录音回调，异步附件化录音文件
  - **Whatsapp::CallService** — WhatsApp 通话操作（accept/reject/terminate）
  - **Whatsapp::IncomingCallService** — WhatsApp 呼入处理
  - **Whatsapp::CallPermissionReplyService** — WhatsApp 通话权限回复
- **涉及的自动化/规则/事件**：
  - 通话创建时自动在对话中插入 voice_call 消息气泡
  - 坐席接听时自动 claim_call + auto_assign（如对话无现有 assignee）
  - 通话结束时更新 duration_seconds、transcript
  - 录音状态回调异步处理附件
  - Twilio Conference 事件实时驱动状态更新
- **涉及的权限/Policy**：
  - 呼出通话：需 authorize contact (:show) + inbox (:show)，且 inbox 需启用 voice
  - WhatsApp 通话：需确保 calling_enabled + SDP offer + contact phone
- **GoChat 实现要点**：
  - 通话模型需支持多 provider（Twilio/WhatsApp）和方向（呼入/呼出）
  - 状态机：ringing → in_progress → completed/no_answer/failed
  - Conference 模式：坐席和客户通过会议桥连接
  - 录音附件化处理需异步
  - 通话消息（voice_call content_type）与对话系统集成
  - Twilio Access Token 生成（JWT + VoiceGrant）
  - 需 feature flag 控制 voice 通话功能启用

---

### 功能7：SAML SSO 单点登录（AccountSamlSettings）

- **功能描述**：企业版 SAML 2.0 单点登录，允许账户配置 SAML IdP 参数，用户通过企业身份提供商（如 Okta、Azure AD）登录 Chatwoot。支持角色映射（SAML 属性 → Chatwoot 角色），创建/更新 SAML 配置后自动将账户用户 provider 转为 saml。
- **用户操作流程（UI交互步骤）**：
  1. 管理员进入 Settings → SAML SSO 页面（需启用 `saml` feature flag + 全局 ENABLE_SAML_SSO_LOGIN）
  2. 填写 IdP 参数：SSO URL、Certificate（X509）、IdP Entity ID
  3. SP Entity ID 自动生成（基于 FRONTEND_URL + account_id）
  4. 可配置 role_mappings（SAML 属性 → Chatwoot 角色）
  5. 保存后，账户的登录页面出现 SAML 登录按钮
  6. 用户点击 SAML 登录 → 重定向到 IdP → 认证成功后回调 Chatwoot
  7. SamlUserBuilder 查找或创建用户，关联到账户
- **涉及的API端点 + 请求/响应格式**：
  - `GET /api/v1/accounts/{account_id}/saml_settings` — 获取 SAML 配置
  - `POST /api/v1/accounts/{account_id}/saml_settings` — 创建 SAML 配置
    - 请求：`{ saml_settings: { sso_url: "https://idp.example.com/saml/sso", certificate: "X509 cert string", idp_entity_id: "idp_entity", role_mappings: { "admin" => "administrator" } } }`
    - 响应：SAML 配置对象
  - `PUT /api/v1/accounts/{account_id}/saml_settings` — 更新配置
  - `DELETE /api/v1/accounts/{account_id}/saml_settings` — 删除配置（重置用户 provider 为 email）
- **涉及的数据模型 + 关键字段**：
  - `AccountSamlSettings`（表 `account_saml_settings`）：
    - `id` (bigint, PK)
    - `sso_url` (string, not null) — IdP SSO URL
    - `certificate` (text, not null) — X509 证书（需验证有效性）
    - `idp_entity_id` (string, not null) — IdP Entity ID
    - `sp_entity_id` (string) — SP Entity ID（自动生成）
    - `role_mappings` (json) — SAML 角色映射配置
    - `account_id` (bigint, not null, FK, 唯一)
  - 关联：`AccountSamlSettings belongs_to :account`；Account `has_one :saml_settings`
- **涉及的业务逻辑（service层）**：
  - **SamlUserBuilder** — SAML 认证后用户构建：
    - 查找已有用户（by email）→ 如用户属于账户则直接登录
    - 不属于账户则抛出 AuthenticationFailed
    - 新用户创建时设置 provider: 'saml', uid, 自动确认邮箱
    - 角色映射：根据 SAML 属性 + role_mappings 配置分配 AccountUser 角色
  - **Enterprise::DeviseOverrides::OmniauthCallbacksController** — SAML 认证回调处理：
    - `redirect_callbacks` → SAML provider 时走 `omniauth_success`
    - `handle_saml_auth` → 检查 SAML 是否启用 → SamlUserBuilder → 登录/错误处理
    - 支持 mobile 和 web 两种 RelayState 处理
  - AccountSamlSettings：
    - `certificate_must_be_valid_x509` — 验证证书格式
    - `certificate_fingerprint` — 计算证书指纹
    - `set_sp_entity_id` — 自动生成 SP Entity ID（FRONTEND_URL/saml/sp/{account_id}）
    - `after_create_commit :update_account_users_provider` — 创建后将用户 provider 转为 saml
    - `after_destroy_commit :reset_account_users_provider` — 删除后重置为 email
- **涉及的自动化/规则/事件**：
  - SAML 配置创建后，账户用户 provider 自动转为 'saml'
  - SAML 配置删除后，用户 provider 重置为 'email'
  - SP Entity ID 自动生成
  - 证书有效性验证
- **涉及的权限/Policy**：
  - `AccountSamlSettingsPolicy`：所有操作仅 administrator 可执行
  - 需启用 `saml` feature flag + 全局 ENABLE_SAML_SSO_LOGIN
- **GoChat 实现要点**：
  - 需集成 SAML 2.0 协议（可参考 ruby-saml 或类似库）
  - X509 证书验证和指纹计算
  - SP Entity ID 自动生成逻辑
  - 用户查找/创建/角色映射需事务性处理
  - Omniauth 回调流程适配
  - 账户级 SAML 配置（每个账户独立 IdP）
  - role_mappings 灵活映射 SAML 属性到 Chatwoot 角色

---

### 功能8：SidekiqCron 定时任务调度

- **功能描述**：Chatwoot 使用 sidekiq-cron gem 管理 Sidekiq 定时任务。通过 `config/schedule.yml` 定义任务计划，在服务启动时自动加载并持久化到 Redis。定时任务涵盖系统巡检、SLA 评估触发、IMAP 邮件收取、数据清理、报表生成等。
- **用户操作流程（UI交互步骤）**：
  - 此功能为后台运维功能，无用户 UI 交互
  - 管理员可在 Sidekiq Web UI（/sidekiq/cron）查看和管理定时任务
- **涉及的数据模型 + 关键字段**：
  - 无独立数据模型，任务定义存储在 `config/schedule.yml` 和 Redis 中
- **核心定时任务列表**：
  - `trigger_scheduled_items_job` — */5 * * * *（每5分钟）— 触发 SLA 评估等调度任务
  - `trigger_hourly_scheduled_items_job` — 0 * * * *（每小时）— 低频定时任务触发
  - `trigger_imap_email_inboxes_job` — */1 * * * *（每分钟）— IMAP 邮件收取
  - `internal_check_new_versions_job` — 0 0 * * *（每日 00:00 UTC）— 版本检查 + 日级调度
  - `remove_stale_contact_inboxes_job` — 30 22 * * *（每日 22:30 UTC）— 清理过期 ContactInbox
  - `remove_stale_redis_keys_job` — 30 22 * * *（每日 22:30 UTC）— 清理过期 Redis Key
  - SLA 相关：通过 `TriggerScheduledItemsJob` → `Sla::TriggerSlasForAccountsJob` 链路触发
- **涉及的业务逻辑**：
  - `config/initializers/sidekiq.rb` — Sidekiq 服务启动时：
    - 加载 `config/schedule.yml`
    - `Sidekiq::Cron::Job.load_from_hash!` — upsert 任务并清理已删除条目
    - 显式清理 legacy 动态任务（如 bulk_auto_assignment_job）
  - `TriggerScheduledItemsJob` — 核心调度入口，每5分钟执行，触发 SLA 评估等子任务
  - `Internal::TriggerDailyScheduledItemsJob` — 日级调度
  - `Internal::TriggerHourlyScheduledItemsJob` — 小时级调度
- **涉及的自动化/规则/事件**：
  - 服务启动时自动加载 schedule.yml 到 Redis
  - 部署时自动清理已删除的 schedule 条目
  - 任务执行日志（Sidekiq logger）
- **GoChat 实现要点**：
  - 如使用 Go 实现，需设计定时任务调度框架（可参考 cron 表达式 + 分布式锁）
  - SLA 评估链路：定时触发 → 遍历账户 → 遍历 AppliedSla → EvaluateAppliedSlaService
  - 任务需要幂等性（防止重复执行）
  - 需考虑分布式环境下的任务竞争（Redis 锁 / DB 锁）
  - 任务配置建议外部化（YAML / DB 配置），支持动态调整
  - 清理类任务（stale data）需在低峰时段执行

---

## 模块间依赖关系

| 依赖模块 | 依赖说明 |
|---------|---------|
| M1-Account | SLA/CustomRole/Company/AgentCapacityPolicy/SAML 均属于 Account 级别；AuditLog 的 associated 关联 Account |
| M3-Conversation | SLA AppliedSla/SlaEvent 关联 Conversation；Call 关联 Conversation |
| M4-Contact | Company 关联 Contact（belongs_to）；Call 关联 Contact；CompanyAssociationService 自动关联 |
| M5-Team/Assignment | AgentCapacityPolicy 与自动分配系统集成；Call 接听时 auto_assign_conversation |
| M2-Inbox | SlaPolicy 绑定到 Inbox；InboxCapacityLimit 关联 Inbox；Call 关联 Inbox；Voice 需 Inbox 启用 voice |
| M6-Automation | Audit 审计 AutomationRule 变更 |
| M8-Notification | SlaEvent 创建后发送通知 |
| BusinessHours | SLA only_during_business_hours 依赖工作时间计算 |

---

## Feature Flags 依赖

| Feature Flag | 所属功能 | 说明 |
|-------------|---------|-----|
| `audit_logs` | AuditLog | 控制审计日志功能启用 |
| `companies` | Company | 控制组织管理功能启用 |
| `saml` | SAML SSO | 控制 SAML 单点登录启用 |
| `voice`（隐含） | Call/Voice | 控制语音通话功能启用 |
| `sla`（隐含） | SLA | 控制 SLA 功能启用 |

---

## 企业版功能全景总结

Chatwoot 企业版功能通过 Feature Flags 逐项控制启用，每个功能模块独立可配。核心设计模式：

1. **Concern 扩展**：Enterprise::Concerns::Account 通过 `included` 块注入 `has_many :sla_policies, :custom_roles, :agent_capacity_policies, :companies, :calls, has_one :saml_settings` 等关联
2. **Policy 红线**：所有企业版功能的写操作（create/update/destroy）均需 administrator 权限
3. **审计追踪**：Enterprise::AuditLog 继承 Audited::Audit，全局配置审计类，核心模型通过 concern 声明审计范围
4. **Feature Flag 门控**：每个企业版功能都有对应的 feature flag，controller 层 before_action 检查
5. **定时调度**：SLA 评估等周期性任务通过 SidekiqCron + TriggerScheduledItemsJob 链路触发
6. **异步处理**：SLA 评估、录音附件、favicon 获取等均通过 Sidekiq Job 异步执行