790 lines
43 KiB
Markdown
790 lines
43 KiB
Markdown
# M1 账户与用户管理 — Chatwoot 功能梳理文档
|
||
|
||
> 基于 Chatwoot 源码深度阅读 + CodeGraph 上下文梳理
|
||
> 生成日期：2026-05-22
|
||
> 参照仓库：chatwoot-reference
|
||
|
||
---
|
||
|
||
## 1. 账户 CRUD + 设置 + 品牌
|
||
|
||
### 账户创建（注册时自动建账）
|
||
- 功能描述：用户注册时同步创建其第一个 Account，Account 与 User 通过 AccountUser 关联。AccountBuilder 事务性地创建 Account + User + AccountUser（角色默认 administrator）。
|
||
- 用户操作流程：
|
||
1. 用户在注册页面填写账户名、用户名、邮箱、密码
|
||
2. 系统验证邮箱有效性（ disposable / blocked domain 检测）
|
||
3. 如通过 CAPTCHA 校验，事务性地创建 Account 和 User
|
||
4. 发送确认邮件；API-only 模式下直接返回 auth token
|
||
5. 已登录用户点击"添加账户"可创建新账户，自动成为该账户 administrator
|
||
- 涉及的API端点：
|
||
- `POST /api/v1/accounts` — 创建账户（无需认证）
|
||
- 请求参数：`{ account_name, user_full_name, email, password, locale }`
|
||
- 响应（已认证/API-only）：`{ data: { id, email, ... }, meta: { access_token, ... } }`
|
||
- 响应（未确认注册）：`{ email: "user@example.com" }`
|
||
- 涉及的数据模型：
|
||
- **Account**（`accounts` 表）：`id, name, domain, locale, status, feature_flags, settings, custom_attributes, limits, support_email, auto_resolve_duration, internal_attributes`
|
||
- `status` enum：active(0), suspended(1)
|
||
- `settings` jsonb：包含 auto_resolve_after, auto_resolve_message, auto_resolve_ignore_waiting, audio_transcriptions 等大量配置项（参见 AccountSettingsSchema）
|
||
- `feature_flags` bigint：位运算存储（FlagShihTzu）
|
||
- 涉及的业务逻辑：
|
||
- **AccountBuilder**（`app/builders/account_builder.rb`）：事务性创建 Account → User → AccountUser
|
||
- **Account::SignUpEmailValidationService**：邮箱验证（valid_email2 + blocked domain）
|
||
- **Account::BrandingEnrichmentJob**：注册后异步从邮箱域名拉取品牌信息（logo/favicon）
|
||
- 涉及的自动化/规则/事件：
|
||
- `before_create :enable_default_features` — 根据 InstallationConfig 启用默认 feature flags
|
||
- `after_create_commit :notify_creation` — ActionCable 通知
|
||
- `Account::BrandingEnrichmentJob.perform_later` — 品牌信息异步填充
|
||
- `AccountSettingsSchema` — JSON Schema 校验 settings 字段合法性
|
||
- CAPTCHA 验证（`validate_captcha` before_action）
|
||
- 邮件域名黑名单（`SignUpEmailValidationService.blocked_domains`）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/v1/accounts_controller.rb`
|
||
- `app/builders/account_builder.rb`
|
||
- `app/services/account/sign_up_email_validation_service.rb`
|
||
- `app/jobs/account/branding_enrichment_job.rb`
|
||
- `app/models/account.rb`
|
||
- `app/models/concerns/account_settings_schema.rb`
|
||
- `app/models/concerns/featurable.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 账户查看（Show）
|
||
- 功能描述：返回当前账户详情，包含 feature flags、settings、limits、品牌信息等。
|
||
- 用户操作流程：用户切换到某账户后，前端自动请求账户数据以渲染侧边栏和设置页。
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/accounts/:id`
|
||
- 响应：`{ id, name, domain, locale, features, settings, limits, ... }`
|
||
- 涉及的数据模型：Account 全字段 + `latest_chatwoot_version`（Redis::Alfred）
|
||
- 涉及的业务逻辑：`AccountsController#show` — 查 Redis 获取最新 Chatwoot 版本号用于版本提示
|
||
- 涉及的自动化/规则/事件：Pundit 授权（AccountPolicy#show? → administrator || agent）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/v1/accounts_controller.rb`
|
||
- `app/policies/account_policy.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 账户更新（Update）
|
||
- 功能描述：管理员更新账户名称、域名、语言、支持邮箱、settings（自动解决配置等）、custom_attributes。
|
||
- 用户操作流程：
|
||
1. 管理员进入 Settings → Account Settings
|
||
2. 编辑账户名称/域名/locale/support_email
|
||
3. 编辑 auto_resolve_after、auto_resolve_message 等会话自动解决配置
|
||
4. 保存
|
||
- 涉及的API端点：
|
||
- `PUT /api/v1/accounts/:id`
|
||
- 请求参数：`{ name, locale, domain, support_email, settings: { auto_resolve_after, ... }, custom_attributes: { ... } }`
|
||
- 涉及的数据模型：Account 的 `name, locale, domain, support_email, settings, custom_attributes`
|
||
- 涉及的业务逻辑：
|
||
- 合并 `custom_attributes` 和 `settings`（merge! 策略，非覆盖）
|
||
- JSON Schema 校验 settings（`AccountSettingsSchema`）
|
||
- onboarding_step 步进逻辑：account_details → invite_team
|
||
- 涉及的自动化/规则/事件：Pundit（AccountPolicy#update? → 仅 administrator）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/v1/accounts_controller.rb`
|
||
- `app/models/concerns/account_settings_schema.rb`
|
||
- `app/policies/account_policy.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 账户激活时间更新（Update Active At）
|
||
- 功能描述：用户切换账户时更新 AccountUser 的 `active_at`，用于前端判断当前活跃账户。
|
||
- 涉及的API端点：`POST /api/v1/accounts/:id/update_active_at`
|
||
- 涉及的数据模型：AccountUser `active_at`
|
||
- 涉及的业务逻辑：直接更新 `active_at = Time.now.utc`
|
||
- Chatwoot原实现关键代码文件路径：`app/controllers/api/v1/accounts_controller.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 账户缓存键（Cache Keys）
|
||
- 功能描述：前端轮询获取账户级别缓存键，用于判断数据是否需要刷新。
|
||
- 涉及的API端点：`GET /api/v1/accounts/:id/cache_keys`
|
||
- 涉及的业务逻辑：`CacheKeysHelper#cache_keys_for_account` 生成多维缓存键
|
||
- Chatwoot原实现关键代码文件路径：`app/controllers/api/v1/accounts_controller.rb`, `app/helpers/cache_keys_helper.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
---
|
||
|
||
## 2. 用户注册 / 登录 / OAuth
|
||
|
||
### 用户注册（邮箱+密码）
|
||
- 功能描述：通过 AccountBuilder 创建账户时同步注册用户；独立注册仅通过账户创建入口。Devise Confirmable 模块要求邮箱确认后才能登录。
|
||
- 用户操作流程：
|
||
1. 填写邮箱、密码、全名
|
||
2. 系统调用 AccountBuilder → User.create! + Account.create! + AccountUser.create!
|
||
3. 发送确认邮件
|
||
4. 用户点击邮件链接确认邮箱
|
||
5. 确认后可正常登录
|
||
- 涉及的API端点：
|
||
- `POST /api/v1/accounts`（注册入口与账户创建合一）
|
||
- `GET /auth/confirmation?confirmation_token=xxx`（Devise 确认回调）
|
||
- `POST /api/v1/resend_confirmation`（重发确认邮件）
|
||
- 涉及的数据模型：
|
||
- **User**（`users` 表）：`id, name, email, display_name, encrypted_password, provider, uid, confirmation_token, confirmed_at, confirmation_sent_at, unconfirmed_email, reset_password_token, reset_password_sent_at, sign_in_count, current_sign_in_at, current_sign_in_ip, last_sign_in_at, last_sign_in_ip, availability, message_signature, custom_attributes, ui_settings, pubsub_token, tokens, type`
|
||
- Devise 模块：`:database_authenticatable, :registerable, :recoverable, :rememberable, :trackable, :validatable, :confirmable, :password_has_required_content`
|
||
- 涉及的业务逻辑：
|
||
- **Account::SignUpEmailValidationService**：邮箱有效性 + disposable + blocked domain
|
||
- **AccountBuilder**：事务创建 User → Account → AccountUser
|
||
- Devise Confirmable：确认邮件 → token 校验 → 设置 confirmed_at
|
||
- 涉及的自动化/规则/事件：
|
||
- 邮箱确认后才能登录（`DeviseOverrides::SessionsController` 检查 confirmed?）
|
||
- 密码必须包含数字+字母+特殊字符（`:password_has_required_content`）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/builders/account_builder.rb`
|
||
- `app/services/account/sign_up_email_validation_service.rb`
|
||
- `app/controllers/devise_overrides/confirmations_controller.rb`
|
||
- `app/controllers/auth/resend_confirmations_controller.rb`
|
||
- `app/models/user.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 用户登录（邮箱+密码 + MFA + SSO）
|
||
- 功能描述：支持邮箱密码登录、MFA 二次验证、SSO 一次性令牌登录。基于 DeviseTokenAuth 实现 JWT 式 token 认证（多 token 机制，支持并发多设备）。
|
||
- 用户操作流程：
|
||
1. 用户输入邮箱 + 密码 → `POST /auth/sign_in`
|
||
2. 若启用 MFA，返回 `mfa_required` 错误，前端引导用户输入 OTP/backup code
|
||
3. 用户输入 `mfa_token` → 再次 `POST /auth/sign_in` 完成 MFA 校验
|
||
4. 若使用 SSO 登录（`sso_auth_token`），直接通过令牌认证
|
||
5. 成功后返回 auth headers（`access-token, client, uid, expiry`）
|
||
- 涉及的API端点：
|
||
- `POST /auth/sign_in` — 登录
|
||
- 请求：`{ email, password }` 或 `{ email, password, mfa_token }` 或 `{ email, sso_auth_token }`
|
||
- 响应成功：auth headers + 用户 JSON
|
||
- 响应 MFA：`{ errors: ["mfa_required"], mfa_required: true }`
|
||
- 响应未确认：`{ errors: ["user_not_confirmed"] }`
|
||
- 涉及的数据模型：User `email, encrypted_password, otp_required_for_login, otp_secret, confirmed_at, provider`
|
||
- 涉及的业务逻辑：
|
||
- **DeviseOverrides::SessionsController**：
|
||
- `find_user_for_authentication`：邮箱 + 密码校验
|
||
- `handle_mfa_verification`：Mfa::AuthenticationService 校验 OTP 或 backup code
|
||
- `handle_mfa_required`：返回 MFA 提示
|
||
- `handle_sso_authentication`：SsoAuthenticatable#valid_sso_auth_token?
|
||
- `process_sso_auth_token`：SSO token 前置处理
|
||
- **Mfa::AuthenticationService**：OTP / backup code 校验
|
||
- **SsoAuthenticatable**：Redis 管理临时 SSO token（5 分钟有效期）
|
||
- 涉及的自动化/规则/事件：
|
||
- MFA 启用的用户必须经过二次验证
|
||
- SSO auth token 5 分钟过期（Redis::Alfred setex）
|
||
- DeviseTokenAuth 多 token 机制：每次登录生成新 token 对（access-token + client）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/devise_overrides/sessions_controller.rb`
|
||
- `app/models/concerns/sso_authenticatable.rb`
|
||
- `app/services/mfa/management_service.rb`
|
||
- `app/services/mfa/authentication_service.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### 用户密码重置
|
||
- 功能描述：通过邮箱发送重置密码链接，用户点击链接后设置新密码。
|
||
- 用户操作流程：
|
||
1. 用户在登录页点击"忘记密码"
|
||
2. 输入邮箱 → `POST /auth/password` → 发送重置邮件
|
||
3. 用户点击邮件中的链接
|
||
4. 输入新密码 + 确认密码 → `PUT /auth/password` → 返回 auth headers
|
||
- 涉及的API端点：
|
||
- `POST /auth/password` — 请求重置邮件
|
||
- `PUT /auth/password` — 执行重置（`{ reset_password_token, password, password_confirmation }`)
|
||
- 涉及的数据模型：User `reset_password_token, reset_password_sent_at, encrypted_password`
|
||
- 涉及的业务逻辑：**DeviseOverrides::PasswordsController** — 标准 Devise 流程 + 返回 auth headers
|
||
- Chatwoot原实现关键代码文件路径：`app/controllers/devise_overrides/passwords_controller.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
### OAuth 登录（Google OAuth2 / SAML）
|
||
- 功能描述：支持 Google OAuth2 和 SAML 作为外部认证提供者。OAuth 回调后查找或创建用户，生成 SSO auth token 重定向到前端登录页完成认证。
|
||
- 用户操作流程：
|
||
1. 用户点击"Google 登录"按钮
|
||
2. 重定向到 Google OAuth 授权页
|
||
3. 授权后回调到 `/auth/google_oauth2/callback`
|
||
4. 系统查找/创建用户，生成 SSO auth token
|
||
5. 重定向到前端 `/app/login?email=xxx&sso_auth_token=xxx`
|
||
6. 前端用 SSO auth token 调用 `POST /auth/sign_in` 完成认证
|
||
- 涉及的API端点：
|
||
- `GET /auth/google_oauth2` — 发起 OAuth
|
||
- `GET /auth/google_oauth2/callback` — OAuth 回调
|
||
- `POST /auth/saml_login` — SAML 登录入口（企业版）
|
||
- 涉及的数据模型：User `provider, uid`（OAuth 用户 provider='google_oauth2', uid=Google sub）
|
||
- 涉及的业务逻辑：
|
||
- **DeviseOverrides::OmniauthCallbacksController**：
|
||
- `sign_in_user`：找到用户 → 生成 SSO auth token → 重定向到登录页
|
||
- `sign_up_user`：创建新用户 → 设置随机密码 → 重定向到登录页
|
||
- `sign_in_user_on_mobile`：移动端 deeplink 方式
|
||
- **SsoAuthenticatable**：`generate_sso_auth_token`（Redis 5分钟有效期）
|
||
- 涉及的自动化/规则/事件：
|
||
- OAuth 新用户自动确认邮箱（`skip_confirmation!`）
|
||
- OAuth 新用户设置随机密码
|
||
- 移动端通过 deeplink 跳转
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/devise_overrides/omniauth_callbacks_controller.rb`
|
||
- `app/models/concerns/sso_authenticatable.rb`
|
||
- `enterprise/app/controllers/api/v1/auth_controller.rb`
|
||
- 版本标注：**社区版**（Google OAuth2）/ **企业版**（SAML）
|
||
|
||
### Token 验证
|
||
- 功能描述：验证当前 access-token 是否有效，用于前端刷新时校验 session。
|
||
- 涉及的API端点：`GET /auth/validate_token`
|
||
- 涉及的业务逻辑：**DeviseOverrides::TokenValidationsController** — DeviseTokenAuth 标准 + 自定义渲染
|
||
- Chatwoot原实现关键代码文件路径：`app/controllers/devise_overrides/token_validations_controller.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
---
|
||
|
||
## 3. AccountUser 多账户角色
|
||
|
||
### AccountUser 关联管理
|
||
- 功能描述：一个 User 可属于多个 Account（通过 AccountUser 中间表），每个 AccountUser 独立设定 role（administrator/agent）、availability、auto_offline、custom_role_id、agent_capacity_policy_id。
|
||
- 用户操作流程：
|
||
1. 管理员在 Settings → Agents 列表中邀请/删除/编辑成员
|
||
2. 用户切换账户时前端调用 `update_active_at` 更新活跃账户
|
||
3. 用户可在 Profile 中设置各账户的 availability 和 auto_offline
|
||
- 涉及的API端点：
|
||
- `POST /api/v1/accounts/:account_id/agents` — 邀请成员
|
||
- `PUT /api/v1/accounts/:account_id/agents/:id` — 更新成员角色/availability
|
||
- `DELETE /api/v1/accounts/:account_id/agents/:id` — 删除成员
|
||
- `POST /api/v1/accounts/:account_id/agents/bulk_create` — 批量邀请
|
||
- `GET /api/v1/accounts/:account_id/agents` — 列出成员
|
||
- `POST /api/v1/profile/availability` — 更新当前用户在某账户的 availability
|
||
- `POST /api/v1/profile/auto_offline` — 更新 auto_offline
|
||
- `PUT /api/v1/profile/set_active_account` — 切换活跃账户
|
||
- 涉及的数据模型：
|
||
- **AccountUser**（`account_users` 表）：`id, account_id, user_id, role, availability, auto_offline, active_at, inviter_id, custom_role_id, agent_capacity_policy_id`
|
||
- `role` enum：agent(0), administrator(1)
|
||
- `availability` enum：online(0), offline(1), busy(2)
|
||
- 索引：`uniq_user_id_per_account_id`（account_id + user_id 联合唯一）
|
||
- 涉及的业务逻辑：
|
||
- **AgentBuilder**（`app/builders/agent_builder.rb`）：查找或创建 User → 创建 AccountUser → 发送邀请邮件
|
||
- **AccountsController#update_active_at**：更新 active_at
|
||
- **ProfilesController#availability / #auto_offline / #set_active_account**：各账户独立设置
|
||
- 删除 Agent 时：`AccountUser.destroy!` → 如果用户无其他账户则删除 User 记录
|
||
- 涉及的自动化/规则/事件：
|
||
- `after_create_commit :notify_creation, :create_notification_setting` — 创建 AccountUser 时自动创建通知设置
|
||
- `after_destroy :notify_deletion, :remove_user_from_account` — 删除时清理
|
||
- `after_save :update_presence_in_redis` — availability 变更时更新 Redis 在线状态
|
||
- **AvailabilityStatusable**：用户 availability_status 综合判断（DB availability + Redis online presence + auto_offline）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/models/account_user.rb`
|
||
- `app/controllers/api/v1/accounts/agents_controller.rb`
|
||
- `app/builders/agent_builder.rb`
|
||
- `app/controllers/api/v1/profiles_controller.rb`
|
||
- `app/models/concerns/availability_statusable.rb`
|
||
- `app/policies/user_policy.rb`
|
||
- 版本标注：**社区版**（role=agent/administrator）/ **企业版**（custom_role_id, agent_capacity_policy_id）
|
||
|
||
---
|
||
|
||
## 4. Profile 管理
|
||
|
||
### Profile 查看 / 更新
|
||
- 功能描述：用户查看和更新自己的个人信息，包括姓名、邮箱、显示名、消息签名、头像、UI 设置等。
|
||
- 用户操作流程：
|
||
1. 用户点击侧边栏头像 → 进入 Profile 页
|
||
2. 编辑 name / display_name / email / message_signature / custom_attributes
|
||
3. 更换头像（上传/删除）
|
||
4. 修改密码（需输入当前密码验证）
|
||
5. 重置 access token（用于 API 访问）
|
||
6. 重发邮箱确认
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/profile` — 查看
|
||
- `PUT /api/v1/profile` — 更新（含密码修改需 current_password）
|
||
- `DELETE /api/v1/profile/avatar` — 删除头像
|
||
- `POST /api/v1/profile/resend_confirmation` — 重发确认邮件
|
||
- `POST /api/v1/profile/reset_access_token` — 重置 access token
|
||
- `POST /api/v1/profile/availability` — 更新某账户 availability
|
||
- `POST /api/v1/profile/auto_offline` — 更新某账户 auto_offline
|
||
- `PUT /api/v1/profile/set_active_account` — 设置活跃账户
|
||
- 涉及的数据模型：User `name, display_name, email, message_signature, ui_settings, custom_attributes, avatar(ActiveStorage)`
|
||
- 涉及的业务逻辑：
|
||
- **ProfilesController**：
|
||
- `update`：密码修改需验证 current_password；其他字段直接 assign_attributes + merge custom_attributes
|
||
- `avatar`：删除 ActiveStorage attachment
|
||
- `reset_access_token`：`user.access_token.regenerate_token`
|
||
- 邮箱变更触发 Devise Confirmable reconfirmation 流程
|
||
- 涉及的自动化/规则/事件：
|
||
- 邮箱变更需重新确认（unconfirmed_email 机制）
|
||
- 密码修改必须验证当前密码
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/v1/profiles_controller.rb`
|
||
- `app/views/api/v1/profiles/show.json.jbuilder`
|
||
- 版本标注：**社区版**
|
||
|
||
### MFA（多因子认证）管理
|
||
- 功能描述：用户启用/禁用/验证 TOTP 二步认证，支持 OTP code 和 backup code。
|
||
- 用户操作流程：
|
||
1. 用户在 Profile → Security 页点击"启用 MFA"
|
||
2. 系统生成 otp_secret → 返回 provisioning URI（QR 码）
|
||
3. 用户用 Authenticator App 扫码绑定
|
||
4. 输入 OTP code 验证 → `POST /api/v1/profile/mfa/verify`
|
||
5. 验证成功后启用 MFA，返回 10 个 backup codes
|
||
6. 可随时重新生成 backup codes 或禁用 MFA（需验证 OTP）
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/profile/mfa` — 查看 MFA 状态
|
||
- `POST /api/v1/profile/mfa` — 启用（生成 otp_secret）
|
||
- `POST /api/v1/profile/mfa/verify` — 验证并激活
|
||
- `POST /api/v1/profile/mfa/backup_codes` — 重新生成 backup codes
|
||
- `DELETE /api/v1/profile/mfa` — 禁用 MFA
|
||
- 涉及的数据模型：User `otp_secret(encrypted), otp_required_for_login, otp_backup_codes(encrypted)`
|
||
- 涉及的业务逻辑：
|
||
- **Mfa::ManagementService**：enable/disable/verify/generate_backup_codes
|
||
- **Mfa::AuthenticationService**：authenticate（OTP 或 backup code）
|
||
- backup code 消耗机制：验证后标记为 'XXXXXXXX'（不可重用）
|
||
- OTP secret 和 backup codes 使用 ActiveRecord encryption
|
||
- 涉及的自动化/规则/事件：
|
||
- 全局 MFA 开关：`Chatwoot.mfa_enabled?`（环境变量控制）
|
||
- 禁用 MFA 需验证当前 OTP/backup code
|
||
- backup code 常量时间比较（防 timing attack）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/v1/profile/mfa_controller.rb`
|
||
- `app/services/mfa/management_service.rb`
|
||
- `app/services/mfa/authentication_service.rb`
|
||
- `app/services/mfa/token_service.rb`
|
||
- 版本标注：**社区版**
|
||
|
||
---
|
||
|
||
## 5. JWT 认证 + Devise
|
||
|
||
### DeviseTokenAuth 认证机制
|
||
- 功能描述：Chatwoot 使用 DeviseTokenAuth 实现 token-based 认证，而非传统 JWT。每次登录生成一对 token（`access-token` + `client`），通过 HTTP headers 传递。支持多设备并发登录（每个 client 一个 token）。
|
||
- 用户操作流程：
|
||
1. 登录成功后响应 headers 包含 `access-token, client, uid, expiry, token-type`
|
||
2. 前端存储 headers，后续请求携带这些 headers
|
||
3. Token 验证：`GET /auth/validate_token`
|
||
4. Token 过期后自动刷新（DeviseTokenAuth 内置机制）
|
||
- 涉及的API端点：
|
||
- `POST /auth/sign_in` — 登录
|
||
- `DELETE /auth/sign_out` — 登出
|
||
- `GET /auth/validate_token` — 验证 token
|
||
- Auth headers：`access-token, client, uid, expiry, token-type`
|
||
- 涉及的数据模型：User `tokens`（json 列，存储多 client token 信息）
|
||
- 涉及的业务逻辑：
|
||
- DeviseTokenAuth 管理多 client token 存储/验证/过期
|
||
- `Api::BaseController#authenticate_user!` → DeviseTokenAuth `set_user_by_token`
|
||
- `Api::BaseController#set_current_user` → 设置 `Current.user`
|
||
- `Api::BaseController#set_current_account` → 根据 `account_id` 参数设置 `Current.account` + `Current.account_user`
|
||
- 涉及的自动化/规则/事件：
|
||
- Token 过期时间 configurable（默认 2 周）
|
||
- 每次请求可更新 token（change_headers_on_each_request）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/controllers/api/base_controller.rb`
|
||
- `app/controllers/devise_overrides/sessions_controller.rb`
|
||
- `app/controllers/devise_overrides/token_validations_controller.rb`
|
||
- `config/routes.rb`（mount_devise_token_auth_for 'User', at: 'auth'）
|
||
- `app/models/user.rb`（DeviseTokenAuth::Concerns::User）
|
||
- 版本标注：**社区版**
|
||
|
||
---
|
||
|
||
## 6. RBAC 权限 + CustomRole（企业版）
|
||
|
||
### 内置角色 RBAC
|
||
- 功能描述：AccountUser 内置两种角色：administrator(1) 和 agent(0)。各 Policy 类基于 `@account_user.role` 做授权判断。administrator 有全部权限，agent 权限受限。
|
||
- 用户操作流程：管理员在邀请成员时选择角色（administrator / agent / custom_role）。
|
||
- 涉及的API端点：
|
||
- `POST /api/v1/accounts/:account_id/agents`（role 参数）
|
||
- `PUT /api/v1/accounts/:account_id/agents/:id`（可更改 role）
|
||
- 涉及的数据模型：AccountUser `role` enum（agent:0, administrator:1）
|
||
- 涉及的业务逻辑：
|
||
- **ApplicationPolicy**：所有 Policy 的基类，接收 `user_context[:account_user]` 进行角色判断
|
||
- **AccountPolicy**：show/limits → agent+administrator；update/toggle_deletion/subscription → 仅 administrator
|
||
- **UserPolicy**：create/update/destroy/bulk_create → 仅 administrator
|
||
- **AgentPolicy**：通过 Pundit + AccountPolicy 授权
|
||
- 涉及的自动化/规则/事件：Pundit 中间件在每次 controller action 前调用 `authorize` 方法
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/policies/application_policy.rb`
|
||
- `app/policies/account_policy.rb`
|
||
- `app/policies/user_policy.rb`
|
||
- `app/controllers/api/base_controller.rb`（`check_authorization` before_action）
|
||
- 版本标注：**社区版**
|
||
|
||
### CustomRole 自定义角色（企业版）
|
||
- 功能描述：企业版允许管理员创建自定义角色（CustomRole），定义细粒度权限（conversation_manage, contact_manage 等），并将 CustomRole 关联到 AccountUser，替代内置 agent 角色提供更精细的权限控制。
|
||
- 用户操作流程：
|
||
1. 管理员进入 Settings → Custom Roles
|
||
2. 创建自定义角色：填写名称、描述、勾选权限列表
|
||
3. 在邀请/编辑 Agent 时选择自定义角色
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/accounts/:account_id/custom_roles` — 列出
|
||
- `POST /api/v1/accounts/:account_id/custom_roles` — 创建
|
||
- `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` — 删除
|
||
- 请求：`{ name, description, permissions: ["conversation_manage", "contact_manage", ...] }`
|
||
- 涉及的数据模型：
|
||
- **CustomRole**（`custom_roles` 表）：`id, name, description, permissions(array), account_id`
|
||
- 可用权限列表（PERMISSIONS 常量）：
|
||
- `conversation_manage` — 管理所有会话
|
||
- `conversation_unassigned_manage` — 管理未分配会话并自分配
|
||
- `conversation_participating_manage` — 管理参与的会话
|
||
- `contact_manage` — 管理联系人
|
||
- `report_manage` — 管理报告
|
||
- `knowledge_base_manage` — 管理知识库
|
||
- AccountUser `custom_role_id`（FK → custom_roles）
|
||
- 涉及的业务逻辑：
|
||
- **CustomRolesController**：CRUD，依赖 EnterpriseAccountsController（企业版校验）
|
||
- 删除 CustomRole 时 `account_users.custom_role_id` 被 nullify
|
||
- 涉及的自动化/规则/事件：
|
||
- Feature flag `custom_roles` 必须启用
|
||
- CustomRolePolicy 全部操作仅 administrator
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `enterprise/app/models/custom_role.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/custom_roles_controller.rb`
|
||
- `enterprise/app/policies/custom_role_policy.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/enterprise_accounts_controller.rb`
|
||
- 版本标注：**企业版**
|
||
|
||
---
|
||
|
||
## 7. SAML SSO 设置（企业版）
|
||
|
||
### SAML SSO 配置
|
||
- 功能描述：管理员为账户配置 SAML IdP 参数（SSO URL、证书、Entity ID），配置后账户内用户的 `provider` 字段自动更新为 'saml'，强制通过 SAML 认证登录。
|
||
- 用户操作流程：
|
||
1. 管理员进入 Settings → SAML SSO
|
||
2. 填写 IdP SSO URL、X.509 Certificate、IdP Entity ID、SP Entity ID
|
||
3. 可选配置 role_mappings（SAML 属性 → Chatwoot 角色映射）
|
||
4. 保存后，账户用户 provider 字段批量更新为 'saml'
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/accounts/:account_id/saml_settings` — 查看
|
||
- `POST /api/v1/accounts/:account_id/saml_settings` — 创建
|
||
- `PUT /api/v1/accounts/:account_id/saml_settings` — 更新
|
||
- `DELETE /api/v1/accounts/:account_id/saml_settings` — 删除
|
||
- `POST /api/v1/auth/saml_login` — 发起 SAML 登录
|
||
- 请求：`{ sso_url, certificate, idp_entity_id, sp_entity_id, role_mappings: {} }`
|
||
- 涉及的数据模型：
|
||
- **AccountSamlSettings**（`account_saml_settings` 表）：`id, account_id, sso_url, certificate, idp_entity_id, sp_entity_id, role_mappings(json)`
|
||
- Account `saml_settings`（has_one 关联）
|
||
- User `provider`（更新为 'saml'）
|
||
- 涉及的业务逻辑：
|
||
- **SamlSettingsController**：CRUD + SAML feature flag 校验 + SSO 全局开关校验
|
||
- **AccountSamlSettings**：
|
||
- `after_create_commit :update_account_users_provider` — 批量将账户用户 provider 改为 'saml'
|
||
- `after_destroy_commit :reset_account_users_provider` — 批量恢复 provider 为 'email'
|
||
- 证书 X.509 校验（`certificate_must_be_valid_x509`）
|
||
- SP Entity ID 自动生成（`set_sp_entity_id`）
|
||
- `certificate_fingerprint`：计算证书指纹
|
||
- **Saml::UpdateAccountUsersProviderJob**：批量更新 provider，1000条/批
|
||
- **Api::V1::AuthController#saml_login**：根据邮箱查找 SAML 启用的账户，重定向到 `/auth/saml?account_id=xxx`
|
||
- 涉及的自动化/规则/事件：
|
||
- Feature flag `saml` 必须启用
|
||
- 全局配置 `ENABLE_SAML_SSO_LOGIN` 必须为 true
|
||
- SAML 设置创建/删除触发批量 provider 更新 Job
|
||
- SAML 回调 → OmniauthCallbacksController → sign_in_user（生成 SSO auth token）
|
||
- role_mappings 可将 SAML 属性映射到 Chatwoot 角色
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `enterprise/app/models/account_saml_settings.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/saml_settings_controller.rb`
|
||
- `enterprise/app/controllers/api/v1/auth_controller.rb`
|
||
- `enterprise/app/jobs/saml/update_account_users_provider_job.rb`
|
||
- `enterprise/app/policies/account_saml_settings_policy.rb`
|
||
- `app/controllers/devise_overrides/omniauth_callbacks_controller.rb`
|
||
- 版本标注：**企业版**
|
||
|
||
---
|
||
|
||
## 8. Company 组织管理（企业版）
|
||
|
||
### Company CRUD + 品牌
|
||
- 功能描述：企业版提供 Company 模型，用于组织/公司级别管理联系人归属。Company 可设置名称、域名、描述、自定义属性，支持自动从域名拉取 favicon 作为 logo。
|
||
- 用户操作流程：
|
||
1. 管理员/用户进入 Contacts → Companies 页面
|
||
2. 创建公司：填写名称、域名（可选）、描述
|
||
3. 编辑/删除公司
|
||
4. 将联系人关联到公司
|
||
5. 搜索公司（按名称或域名）
|
||
- 涉及的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` — 创建
|
||
- `GET /api/v1/accounts/:account_id/companies/:id` — 查看
|
||
- `PUT /api/v1/accounts/:account_id/companies/:id` — 更新
|
||
- `DELETE /api/v1/accounts/:account_id/companies/:id` — 删除（仅 administrator）
|
||
- `DELETE /api/v1/accounts/:account_id/companies/:id/destroy_custom_attributes` — 删除自定义属性
|
||
- 涉及的数据模型：
|
||
- **Company**（`companies` 表）：`id, account_id, name, domain, description, additional_attributes(jsonb), custom_attributes(jsonb), contacts_count, last_activity_at`
|
||
- 索引：`(account_id, domain) UNIQUE WHERE domain IS NOT NULL`
|
||
- 关联：`contacts`（has_many, dependent: nullify）
|
||
- `Avatarable` — 支持 ActiveStorage avatar + 从域名 favicon 自动拉取
|
||
- 涉及的业务逻辑：
|
||
- **CompaniesController**：CRUD + 搜索 + 分页 + 排序（Sift gem: name/domain/created_at/last_activity_at/contacts_count）
|
||
- `after_create_commit :fetch_favicon` — 从域名自动拉取 favicon 作为 logo
|
||
- `record_activity_at!` — 5分钟 rollup 间隔内不重复更新 last_activity_at
|
||
- 品名长度限制（COMPANY_NAME_LENGTH_LIMIT）
|
||
- 品域名格式校验 + 账户内唯一
|
||
- 涉及的自动化/规则/事件：
|
||
- Feature flag `companies` 必须启用
|
||
- CompanyPolicy：所有用户可 index/show/create/update/search；仅 administrator 可 destroy
|
||
- favicon 自动拉取（Avatar::AvatarFromFaviconJob）
|
||
- last_activity_at 活动汇总（ACTIVITY_ROLLUP_INTERVAL = 5分钟）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `enterprise/app/models/company.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/companies_controller.rb`
|
||
- `enterprise/app/policies/company_policy.rb`
|
||
- 版本标注：**企业版**
|
||
|
||
---
|
||
|
||
## 9. AgentCapacityPolicy 容量策略（企业版）
|
||
|
||
### 容量策略 CRUD
|
||
- 功能描述：企业版支持定义 Agent 容量策略（AgentCapacityPolicy），限制每个 Agent 在指定 Inbox 中同时处理的会话数量上限。一个策略可关联多个 Inbox 的容量上限（InboxCapacityLimit），并可分配给多个 AccountUser。
|
||
- 用户操作流程：
|
||
1. 管理员进入 Settings → Agent Capacity Policies
|
||
2. 创建策略：填写名称、描述、排除规则（exclusion_rules）
|
||
3. 为策略添加 Inbox 容量限制：选择 Inbox + 设置 conversation_limit
|
||
4. 将策略分配给特定 Agent
|
||
5. 编辑/删除策略
|
||
- 涉及的API端点：
|
||
- `GET /api/v1/accounts/:account_id/agent_capacity_policies` — 列出
|
||
- `POST /api/v1/accounts/:account_id/agent_capacity_policies` — 创建
|
||
- `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` — 删除
|
||
- 子资源：
|
||
- `GET /api/v1/accounts/:account_id/agent_capacity_policies/:policy_id/users` — 查看分配的 Agent
|
||
- `POST /api/v1/accounts/:account_id/agent_capacity_policies/:policy_id/users` — 分配 Agent
|
||
- `DELETE /api/v1/accounts/:account_id/agent_capacity_policies/:policy_id/users/:id` — 取消分配
|
||
- `POST /api/v1/accounts/:account_id/agent_capacity_policies/:policy_id/inbox_limits` — 创建 Inbox 容量限制
|
||
- `PUT .../inbox_limits/:id` — 更新容量限制值
|
||
- `DELETE .../inbox_limits/:id` — 删除容量限制
|
||
- 涉及的数据模型：
|
||
- **AgentCapacityPolicy**（`agent_capacity_policies` 表）：`id, account_id, name, description, exclusion_rules(jsonb)`
|
||
- `exclusion_rules`：`{ exclude_older_than_hours: int, excluded_labels: [string] }`
|
||
- 含排除逻辑：超过指定小时数的会话不计入容量；带特定标签的会话不计入容量
|
||
- **InboxCapacityLimit**（`inbox_capacity_limits` 表）：`id, agent_capacity_policy_id, inbox_id, conversation_limit`
|
||
- 索引：`(agent_capacity_policy_id, inbox_id) UNIQUE`
|
||
- `conversation_limit` 必须 >= 0
|
||
- **AccountUser** `agent_capacity_policy_id`（FK → agent_capacity_policies）
|
||
- 涉及的业务逻辑：
|
||
- **AgentCapacityPoliciesController**：CRUD + 企业版校验
|
||
- **AgentCapacityPolicies::UsersController**：分配/取消 Agent → 更新 AccountUser.agent_capacity_policy_id
|
||
- **AgentCapacityPolicies::InboxLimitsController**：管理各 Inbox 的 conversation_limit
|
||
- 涉及的自动化/规则/事件：
|
||
- 仅 administrator 可操作（AgentCapacityPolicyPolicy 全操作限 administrator）
|
||
- 一个 Inbox 在同一策略下只能有一个容量限制（唯一索引）
|
||
- AccountUser 删除时 `agent_capacity_policy_id` 被 nullify
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `enterprise/app/models/agent_capacity_policy.rb`
|
||
- `enterprise/app/models/inbox_capacity_limit.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/agent_capacity_policies_controller.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/agent_capacity_policies/users_controller.rb`
|
||
- `enterprise/app/controllers/api/v1/accounts/agent_capacity_policies/inbox_limits_controller.rb`
|
||
- `enterprise/app/policies/agent_capacity_policy_policy.rb`
|
||
- `db/migrate/20250806140004_add_agent_capacity_policy_to_account_users.rb`
|
||
- 版本标注：**企业版**
|
||
|
||
---
|
||
|
||
## 10. FeatureFlags 功能开关
|
||
|
||
### FeatureFlags 管理
|
||
- 功能描述：Account 级别功能开关，通过 FlagShihTzu 位运算存储在 `feature_flags` bigint 列中。支持按 Account 启用/禁用特定功能，前端根据 feature flags 动态显示/隐藏功能入口。
|
||
- 用户操作流程：
|
||
1. 管理员进入 Settings → Account Features
|
||
2. 切换功能开关（enable/disable）
|
||
3. 前端实时响应功能可见性变化
|
||
- 涉及的API端点：
|
||
- 通过 Account show/update 间接管理（settings 返回 enabled_features / disabled_features）
|
||
- Super Admin 可通过 InstallationConfig 设置 `ACCOUNT_LEVEL_FEATURE_DEFAULTS`
|
||
- 涉及的数据模型：
|
||
- **Account** `feature_flags`（bigint，位运算存储）
|
||
- **Featurable** concern：`enable_features! / disable_features! / feature_enabled? / all_features / enabled_features / disabled_features`
|
||
- **config/features.yml**：定义所有功能开关列表（名称 + 显示名 + 默认启用 + premium 标记）
|
||
- 涉及的业务逻辑：
|
||
- **Featurable**（`app/models/concerns/featurable.rb`）：
|
||
- `enable_default_features`：创建 Account 时根据 InstallationConfig 设置默认值
|
||
- `feature_enabled?(name)` → 位运算检查
|
||
- 功能列表（config/features.yml 关键项）：
|
||
| Feature | Display Name | Default | Premium |
|
||
|---|---|---|---|
|
||
| inbound_emails | Inbound Emails | true | - |
|
||
| channel_email | Email Channel | true | - |
|
||
| channel_facebook | Facebook Channel | true | - |
|
||
| help_center | Help Center | true | - |
|
||
| agent_bots | Agent Bots | true | - |
|
||
| macros | Macros | true | - |
|
||
| agent_management | Agent Management | true | - |
|
||
| team_management | Team Management | true | - |
|
||
| inbox_management | Inbox Management | true | - |
|
||
| labels | Labels | true | - |
|
||
| custom_attributes | Custom Attributes | true | - |
|
||
| automations | Automations | true | - |
|
||
| campaigns | Campaigns | true | - |
|
||
| reports | Reports | true | - |
|
||
| crm | CRM | true | - |
|
||
| auto_resolve_conversations | Auto Resolve | true | - |
|
||
| disable_branding | Disable Branding | false | ✅ premium |
|
||
| custom_roles | Custom Roles | false | ✅ premium |
|
||
| sla | SLA | false | ✅ premium |
|
||
| audit_logs | Audit Logs | false | ✅ premium |
|
||
| saml | SAML | false | ✅ premium |
|
||
| companies | Companies | false | ✅ premium |
|
||
| channel_voice | Voice Channel | false | ✅ premium |
|
||
| advanced_search | Advanced Search | false | ✅ premium |
|
||
- 涉及的自动化/规则/事件：
|
||
- `before_create :enable_default_features` — Account 创建时设置默认 features
|
||
- premium 功能需要企业版许可证
|
||
- feature flag 变更触发缓存清除（`after_update_commit :clear_unread_conversation_counts_cache` 等条件回调）
|
||
- Chatwoot原实现关键代码文件路径：
|
||
- `app/models/concerns/featurable.rb`
|
||
- `config/features.yml`
|
||
- `app/models/account.rb`
|
||
- 版本标注：**社区版**（基础功能）/ **企业版**（premium 功能需许可证）
|
||
|
||
---
|
||
|
||
## 附录：关键数据模型汇总
|
||
|
||
### accounts 表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | integer PK | 主键 |
|
||
| name | string NOT NULL | 账户名称 |
|
||
| domain | string(100) | 入站邮件域名 |
|
||
| locale | integer default(en) | 账户语言 |
|
||
| status | integer default(active) | active(0)/suspended(1) |
|
||
| feature_flags | bigint default(0) | 位运算功能开关 |
|
||
| settings | jsonb | 账户设置（自动解决、Captain等） |
|
||
| custom_attributes | jsonb | 自定义属性（含 onboarding_step） |
|
||
| limits | jsonb | 使用限制 |
|
||
| support_email | string(100) | 支持邮箱 |
|
||
| auto_resolve_duration | integer | 自动解决时长 |
|
||
| internal_attributes | jsonb | 内部属性 |
|
||
|
||
### users 表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | integer PK | 主键 |
|
||
| name | string NOT NULL | 用户名 |
|
||
| email | string | 邮箱（唯一） |
|
||
| display_name | string | 显示名 |
|
||
| encrypted_password | string NOT NULL | 加密密码 |
|
||
| provider | string default(email) | 认证提供者(email/google_oauth2/saml) |
|
||
| uid | string NOT NULL | 提供者内ID |
|
||
| confirmation_token | string | 确认令牌 |
|
||
| confirmed_at | datetime | 确认时间 |
|
||
| otp_secret | string(encrypted) | MFA TOTP secret |
|
||
| otp_required_for_login | boolean default(false) | MFA 启用标志 |
|
||
| otp_backup_codes | text(encrypted) | MFA 备用码 |
|
||
| availability | integer default(online) | online(0)/offline(1)/busy(2) |
|
||
| message_signature | text | 消息签名 |
|
||
| custom_attributes | jsonb | 自定义属性 |
|
||
| ui_settings | jsonb | UI偏好设置 |
|
||
| pubsub_token | string | ActionCable token |
|
||
| tokens | json | DeviseTokenAuth 多 token 存储 |
|
||
| type | string | 用户类型（SuperAdmin等STI） |
|
||
|
||
### account_users 表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| account_id | bigint FK | 所属账户 |
|
||
| user_id | bigint FK | 所属用户 |
|
||
| role | integer default(agent) | agent(0)/administrator(1) |
|
||
| availability | integer default(online) | online(0)/offline(1)/busy(2) |
|
||
| auto_offline | boolean default(true) | 自动离线 |
|
||
| active_at | datetime | 活跃时间 |
|
||
| inviter_id | bigint FK | 邀请人 |
|
||
| custom_role_id | bigint FK | 自定义角色(企业版) |
|
||
| agent_capacity_policy_id | bigint FK | 容量策略(企业版) |
|
||
|
||
### custom_roles 表（企业版）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| account_id | bigint FK NOT NULL | 所属账户 |
|
||
| name | string | 角色名称 |
|
||
| description | string | 角色描述 |
|
||
| permissions | text array | 权限列表 |
|
||
|
||
### account_saml_settings 表（企业版）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| account_id | bigint FK NOT NULL | 所属账户 |
|
||
| sso_url | string | IdP SSO URL |
|
||
| certificate | text | X.509 Certificate |
|
||
| idp_entity_id | string | IdP Entity ID |
|
||
| sp_entity_id | string | SP Entity ID |
|
||
| role_mappings | json | SAML→角色映射 |
|
||
|
||
### companies 表（企业版）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| account_id | bigint FK NOT NULL | 所属账户 |
|
||
| name | string NOT NULL | 公司名称 |
|
||
| domain | string | 公司域名（账户内唯一） |
|
||
| description | text | 描述 |
|
||
| additional_attributes | jsonb | 额外属性 |
|
||
| custom_attributes | jsonb | 自定义属性 |
|
||
| contacts_count | integer | 联系人数 |
|
||
| last_activity_at | datetime | 最后活动时间 |
|
||
|
||
### agent_capacity_policies 表（企业版）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| account_id | bigint FK NOT NULL | 所属账户 |
|
||
| name | string(255) NOT NULL | 策略名称 |
|
||
| description | text | 策略描述 |
|
||
| exclusion_rules | jsonb NOT NULL | 排除规则 |
|
||
|
||
### inbox_capacity_limits 表（企业版）
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | bigint PK | 主键 |
|
||
| agent_capacity_policy_id | bigint FK NOT NULL | 所属策略 |
|
||
| inbox_id | bigint FK NOT NULL | 所属 Inbox |
|
||
| conversation_limit | integer NOT NULL | 会话容量上限 |
|
||
|
||
---
|
||
|
||
## 附录：路由汇总
|
||
|
||
```
|
||
# 认证路由
|
||
POST /auth/sign_in # 登录
|
||
DELETE /auth/sign_out # 登出
|
||
GET /auth/validate_token # Token 验证
|
||
POST /auth/password # 密码重置请求
|
||
PUT /auth/password # 密码重置执行
|
||
GET /auth/confirmation # 邮箱确认
|
||
POST /api/v1/resend_confirmation # 重发确认
|
||
GET /auth/google_oauth2 # Google OAuth 发起
|
||
GET /auth/google_oauth2/callback # Google OAuth 回调
|
||
POST /api/v1/auth/saml_login # SAML 登录(企业版)
|
||
GET /auth/saml # SAML IdP 重定向
|
||
|
||
# 账户路由
|
||
POST /api/v1/accounts # 创建账户
|
||
GET /api/v1/accounts/:id # 查看
|
||
PUT /api/v1/accounts/:id # 更新
|
||
POST /api/v1/accounts/:id/update_active_at # 更新活跃时间
|
||
GET /api/v1/accounts/:id/cache_keys # 缓存键
|
||
|
||
# 成员管理
|
||
GET /api/v1/accounts/:id/agents # 成员列表
|
||
POST /api/v1/accounts/:id/agents # 邀请成员
|
||
PUT /api/v1/accounts/:id/agents/:id # 更新成员
|
||
DELETE /api/v1/accounts/:id/agents/:id # 删除成员
|
||
POST /api/v1/accounts/:id/agents/bulk_create # 批量邀请
|
||
GET /api/v1/accounts/:id/assignable_agents # 可分配成员
|
||
|
||
# Profile
|
||
GET /api/v1/profile # 查看
|
||
PUT /api/v1/profile # 更新
|
||
DELETE /api/v1/profile/avatar # 删除头像
|
||
POST /api/v1/profile/availability # 更新可用状态
|
||
POST /api/v1/profile/auto_offline # 更新自动离线
|
||
PUT /api/v1/profile/set_active_account # 切换活跃账户
|
||
POST /api/v1/profile/resend_confirmation # 重发确认
|
||
POST /api/v1/profile/reset_access_token # 重置 token
|
||
|
||
# MFA
|
||
GET /api/v1/profile/mfa # MFA 状态
|
||
POST /api/v1/profile/mfa # 启用
|
||
POST /api/v1/profile/mfa/verify # 验证激活
|
||
POST /api/v1/profile/mfa/backup_codes # 备用码
|
||
DELETE /api/v1/profile/mfa # 禁用
|
||
|
||
# 企业版路由
|
||
GET/POST/PUT/DELETE /api/v1/accounts/:id/saml_settings
|
||
GET/POST/PUT/DELETE /api/v1/accounts/:id/custom_roles
|
||
GET/POST/PUT/DELETE /api/v1/accounts/:id/agent_capacity_policies
|
||
GET/POST/DELETE /api/v1/accounts/:id/agent_capacity_policies/:policy_id/users
|
||
POST/PUT/DELETE /api/v1/accounts/:id/agent_capacity_policies/:policy_id/inbox_limits
|
||
GET/POST/PUT/DELETE /api/v1/accounts/:id/companies
|
||
GET /api/v1/accounts/:id/companies/search
|
||
``` |