gochat/docs/requirements/M07-reporting-and-csat.md

M7 报告与CSAT — Chatwoot 功能梳理文档

基于 Chatwoot 源码深度阅读 + CodeGraph 上下文梳理
生成日期：2026-05-22
参照仓库：chatwoot-reference
模块覆盖：CSAT Survey · Campaign · Reporting Event + Rollup · Dashboard Stats · Inbox CSAT模板 · Report Metrics

---

1. CSAT Survey（客户满意度调查）

CSAT 调查发送

• 功能描述：当会话被标记为已解决时，系统自动向客户发送满意度调查（CSAT Survey）。支持网站Widget内嵌消息、WhatsApp/Twilio模板消息三种投递通道，同时支持基于标签的 Survey Rules 精准定向。
• 用户操作流程：
  1. 客服解决会话 → 系统监听 conversation_status_changed 事件
  2. CsatSurveyListener 触发 CsatSurveyService
  3. 服务判断 inbox 是否开启 CSAT、是否已发过 CSAT、是否符合 Survey Rules
  4. WhatsApp 通道：使用 WhatsApp CSAT 模板投递；Twilio 通道：使用 Twilio CSAT 模板投递；Website 通道：在消息窗口内创建 input_csat 类型消息
  5. 客户看到评分界面（1-5分 + 文本反馈框）
• 涉及的API端点：
  • GET /public/api/v1/csat_survey/:id — 客户端获取 CSAT 调查页面（通过 conversation UUID）
  • PUT /public/api/v1/csat_survey/:id — 客户提交/更新 CSAT 评分与反馈（14天内可修改）
  • GET /api/v1/accounts/:account_id/csat_survey_responses — 列表查询（支持分页、排序、日期/agent/inbox/team 过滤）
  • GET /api/v1/accounts/:account_id/csat_survey_responses/metrics — 统计汇总（总评分数、各评分等级分布、发送总数）
  • GET /api/v1/accounts/:account_id/csat_survey_responses/download — CSV 导出下载
• 涉及的数据模型+关键字段：
  • CsatSurveyResponse（csat_survey_responses 表）：
    • rating (integer, 1-5) — 评分等级
    • feedback_message (text) — 文本反馈
    • csat_review_notes (text) — 内部审阅备注
    • message_id (bigint, UNIQUE) — 关联消息（一条消息唯一对应一条 CSAT 响应）
    • account_id, conversation_id, contact_id, assigned_agent_id — 多维度关联
    • review_notes_updated_by_id, review_notes_updated_at — 审阅追踪
• 涉及的业务逻辑：
  • CsatSurveyListener（app/listeners/csat_survey_listener.rb）：监听会话状态变化，触发 CSAT 发送；监听消息更新，构建 CSAT 响应
  • CsatSurveyService（app/services/csat_survey_service.rb）：发送前多重校验（conversation_allows_csat? / csat_enabled? / csat_already_sent? / csat_allowed_by_survey_rules?）；根据通道类型选择发送方式
  • CsatSurveys::ResponseBuilder（app/builders/csat_surveys/response_builder.rb）：解析消息 submitted_values 中的 rating 和 feedback，创建/更新 CsatSurveyResponse 记录
  • MessageTemplates::Template::CsatSurvey（app/services/message_templates/template/csat_survey.rb）：创建 content_type: input_csat 的消息，支持自定义消息内容和 display_type（emoji / 文本）
• 涉及的自动化/规则/事件：
  • 会话状态变更 → CsatSurveyListener.conversation_status_changed → 自动发送
  • CSAT 消息提交 → CsatSurveyListener.message_updated → 自动构建 Response
  • Survey Rules：基于会话标签的定向规则（contains / does_not_contain 操作符），配置在 inbox csat_config 中
  • 14天锁定：CSAT 提交后14天内可更新，超期锁定（Public::CsatSurveyController.check_csat_locked）
• Chatwoot原实现代码路径：
  • app/models/csat_survey_response.rb
  • app/listeners/csat_survey_listener.rb
  • app/services/csat_survey_service.rb
  • app/services/message_templates/template/csat_survey.rb
  • app/builders/csat_surveys/response_builder.rb
  • app/controllers/public/api/v1/csat_survey_controller.rb
  • app/controllers/api/v1/accounts/csat_survey_responses_controller.rb
• 版本标注：v1（CSAT 基础）+ Enterprise（CSAT Response update 端点）

---

2. Campaign（营销活动/主动推送）

Campaign CRUD + 触发

• 功能描述：Campaign 是面向 Inbox 中联系人进行主动消息推送的功能。支持两种类型：ongoing（持续性，当新对话进入时自动触发）和 one_off（一次性，向指定 audience 批量发送）。仅支持 Website、Twilio SMS、SMS、WhatsApp Inbox。
• 用户操作流程：
  1. 用户在 Inbox 设置中创建 Campaign（选择类型、填写标题/消息/触发规则/受众）
  2. ongoing 类型：当新对话匹配 trigger_rules 时，自动发送 Campaign 消息
  3. one_off 类型：设置 scheduled_at，系统通过 Campaigns::TriggerOneoffCampaignJob 定时触发
  4. 触发时根据 Inbox 类型调用对应 Service（Twilio SMS / SMS / WhatsApp）
• 涉及的API端点：
  • POST /api/v1/accounts/:account_id/campaigns — 创建
  • GET /api/v1/accounts/:account_id/campaigns — 列表
  • GET /api/v1/accounts/:account_id/campaigns/:id — 详情
  • PUT /api/v1/accounts/:account_id/campaigns/:id — 更新
  • DELETE /api/v1/accounts/:account_id/campaigns/:id — 删除
  • GET /api/v1/widget/campaigns — Widget端获取进行中的 Campaign
• 涉及的数据模型+关键字段：
  • Campaign（campaigns 表）：
    • campaign_type (enum: ongoing=0, one_off=1) — 活动类型
    • campaign_status (enum: active=0, completed=1) — 活动状态
    • title (string, required) — 活动标题
    • message (text, required) — 活动消息内容
    • enabled (boolean, default true) — 是否启用
    • trigger_only_during_business_hours (boolean) — 是否仅在营业时间触发
    • trigger_rules (jsonb) — 触发规则（ongoing 类型使用）
    • audience (jsonb) — 受众筛选条件（one_off 类型使用）
    • template_params (jsonb) — 模板参数（WhatsApp Campaign）
    • scheduled_at (datetime) — 定时发送时间（one_off 类型）
    • inbox_id (bigint, required) — 关联 Inbox
    • sender_id (integer) — 发送者 ID
    • display_id (integer) — 展示 ID（自增）
• 涉及的业务逻辑：
  • Campaign.trigger!：one_off 活动触发执行，根据 inbox.inbox_type 选择对应 Service
  • Twilio::OneoffSmsCampaignService / Sms::OneoffSmsCampaignService / Whatsapp::OneoffCampaignService：各通道的具体发送实现
  • Liquid::CampaignTemplateService：支持 Liquid 模板语法（{{contact.name}} 等）的消息变量替换
  • 创建前校验：validate_campaign_inbox（仅支持 Website/Twilio SMS/SMS/WhatsApp）、sender_must_belong_to_account、inbox_must_belong_to_account
  • 已完成的活动不可更新（prevent_completed_campaign_from_update）
• 涉及的自动化/规则/事件：
  • Campaigns::TriggerOneoffCampaignJob：one_off 活动定时触发（scheduled_at 时间到达后执行）
  • ongoing 活动：在会话创建时由前端 / Conversation 创建流程中判断 trigger_rules 匹配并发送
  • 活动完成后状态自动标记为 completed
• Chatwoot原实现代码路径：
  • app/models/campaign.rb
  • app/controllers/api/v1/accounts/campaigns_controller.rb
  • app/controllers/api/v1/widget/campaigns_controller.rb
  • app/jobs/campaigns/trigger_oneoff_campaign_job.rb
  • app/services/twilio/oneoff_sms_campaign_service.rb
  • app/services/sms/oneoff_sms_campaign_service.rb
  • app/services/whatsapp/oneoff_campaign_service.rb
  • app/services/liquid/campaign_template_service.rb
• 版本标注：v1 基础；WhatsApp Campaign 需要 feature flag whatsapp_campaign

---

3. Reporting Event + Rollup（报告事件与数据聚合）

Reporting Event 采集

• 功能描述：ReportingEvent 是 Chatwoot 报告系统的原始数据层，通过事件监听器在关键业务节点自动采集指标事件。涵盖首次响应时间、回复时间、会话解决时间、Bot 解决/移交等核心指标。每条事件包含时间值、营业时间值、多维度关联（account/inbox/user/conversation）。
• 用户操作流程：
  1. 客服首次回复 → ReportingEventListener.first_reply_created → 写入 first_response 事件
  2. 客服后续回复 → reply_time_created → 写入 reply_time 事件
  3. 会话被解决 → conversation_resolved → 写入 conversation_resolved + resolution_time 事件
  4. Bot 解决 → conversation_bot_resolved → 写入 Bot 解决事件
  5. Bot 移交人类 → conversation_bot_handoff → 写入 Bot 移交事件
  6. 每条事件写入后 → ReportingEvents::RollupService 异步聚合到 Rollup 表
• 涉及的API端点：
  • GET /api/v1/accounts/:account_id/conversations/:id/reporting_events — 会话级事件列表（Enterprise）
  • GET /api/v1/accounts/:account_id/reporting_events — 账户级事件列表（Enterprise）
• 涉及的数据模型+关键字段：
  • ReportingEvent（reporting_events 表）：
    • name (string, required) — 事件名（first_response / reply_time / conversation_resolved / conversation_bot_resolved / conversation_bot_handoff / conversation_opened）
    • value (float, required) — 时间值（秒）
    • value_in_business_hours (float) — 营业时间内的时间值
    • event_start_time / event_end_time (datetime) — 事件起止时间
    • account_id, inbox_id, user_id, conversation_id — 多维度关联
  • ReportingEventsRollup（reporting_events_rollups 表）：
    • metric (enum: resolutions_count / first_response / resolution_time / reply_time / bot_resolutions_count / bot_handoffs_count) — 指标名
    • dimension_type (enum: account / agent / inbox / team) — 维度类型
    • dimension_id (bigint) — 维度值
    • date (date) — 聚合日期
    • count (bigint) — 事件计数
    • sum_value (float) — 时间值总和
    • sum_value_business_hours (float) — 营业时间值总和
• 涉及的业务逻辑：
  • ReportingEventListener（app/listeners/reporting_event_listener.rb）：监听6种事件，计算时间差并写入 ReportingEvent
    • first_reply_created：计算首次响应时间 = message.created_at - last_non_human_activity
    • conversation_resolved：计算解决时间 = event_end_time - conversation.created_at
    • reply_time_created：计算回复时间差
    • conversation_bot_resolved / conversation_bot_handoff：Bot 相关指标
  • ReportingEventHelper.last_non_human_activity：计算首次响应基线时间，优先取 bot_handoff / conversation_opened 事件时间，回退到 bot_resolved 或 conversation.created_at
  • ReportingEventHelper.business_hours：利用 working_hours gem 计算 inbox 营业时间内的有效时长
  • ReportingEvents::RollupService：每条 ReportingEvent 写入后触发，按 account/agent/inbox 三维度聚合到 Rollup 表（upsert + count/sum 累加）
  • ReportingEvents::EventMetricRegistry：定义事件 → Rollup 指标的映射关系
  • ReportingEvents::BackfillService：历史数据回填，批量聚合指定日期范围内的原始事件
• 涉及的自动化/规则/事件：
  • 事件写入 → safe_rollup(reporting_event) 自动触发 Rollup 聚合
  • Rollup 仅在账户设置了 reporting_timezone 时启用（软开关）
  • Rollup 读取路径通过 feature flag reporting_events_rollup 控制
  • 首次响应时间基线考虑 Bot 移交 / 重开等场景（last_non_human_activity）
• Chatwoot原实现代码路径：
  • app/models/reporting_event.rb
  • app/models/reporting_events_rollup.rb
  • app/listeners/reporting_event_listener.rb
  • app/helpers/reporting_event_helper.rb
  • app/services/reporting_events/rollup_service.rb
  • app/services/reporting_events/event_metric_registry.rb
  • app/services/reporting_events/metric_registry.rb
  • app/services/reporting_events/backfill_service.rb
  • db/migrate/20260211145813_create_reporting_events_rollup.rb
• 版本标注：v1 ReportingEvent 基础；Rollup 为后续增强（2026年新增 Rollup 表 + 聚合机制）

---

4. Dashboard Stats（仪表盘实时统计）

Live Reports（实时会话指标）

• 功能描述：LiveReports 提供会话维度的实时统计，包括打开数、未关注数、未分配数、等待数。支持按 team_id / assignee_id 分组聚合，用于仪表盘实时展示。
• 用户操作流程：
  1. 用户打开仪表盘首页 → 前端请求 live report API
  2. 系统查询当前账户的会话实时状态
  3. 返回 open/unattended/unassigned/pending 计数
  4. 如请求 grouped 接口 → 按 team 或 agent 分组返回各组计数
• 涉及的API端点：
  • GET /api/v2/accounts/:account_id/live_reports/conversation_metrics — 全局实时指标（需 report:view 权限）
  • GET /api/v2/accounts/:account_id/live_reports/grouped_conversation_metrics?group_by=team_id/assignee_id — 分组实时指标
  • 参数：team_id, inbox_id, user_ids[] — 过滤条件
• 涉及的数据模型+关键字段：
  • 基于 Conversation 模型的 scope 查询：
    • open — 状态为 open 的会话
    • unattended — open + 无人工回复的会话
    • unassigned — open + 无 assignee 的会话
    • pending — 状态为 pending 的会话
• 涉及的业务逻辑：
  • LiveReportsController 直接用 Conversation scope 做 count/group 查询
  • 分组模式：group(@group_scope).count 按 team_id 或 assignee_id 分组统计
  • 权限控制：authorize :report, :view?
• 涉及的自动化/规则/事件：无（纯查询接口）
• Chatwoot原实现代码路径：
  • app/controllers/api/v2/accounts/live_reports_controller.rb
• 版本标注：v2

Dashboard Apps（自定义仪表盘应用）

• 功能描述：DashboardApp 是嵌入在 Chatwoot 主仪表盘中的自定义 iframe 应用模块。用户可配置标题和内容（URL + type=frame），将外部报表/工具嵌入到客服工作界面。
• 用户操作流程：
  1. 管理员在设置中创建 Dashboard App（配置标题和 iframe URL）
  2. 前端在仪表盘侧边栏或主区域渲染 iframe
  3. 外部应用通过 iframe 嵌入展示
• 涉及的API端点：
  • POST /api/v1/accounts/:account_id/dashboard_apps — 创建
  • GET /api/v1/accounts/:account_id/dashboard_apps — 列表
  • GET /api/v1/accounts/:account_id/dashboard_apps/:id — 详情
  • PUT /api/v1/accounts/:account_id/dashboard_apps/:id — 更新
  • DELETE /api/v1/accounts/:account_id/dashboard_apps/:id — 删除
• 涉及的数据模型+关键字段：
  • DashboardApp（dashboard_apps 表）：
    • title (string, required) — 应用标题
    • content (jsonb, required) — 内容配置，结构为 [ { url: "https://...", type: "frame" } ]
    • account_id, user_id — 关联
• 涉及的业务逻辑：
  • JSON Schema 校验 content 格式（必须为 array，每项必须有 url 和 type=frame，url 必须为 http/https）
  • 空内容自动置为 []
• 涉及的自动化/规则/事件：无
• Chatwoot原实现代码路径：
  • app/models/dashboard_app.rb
  • app/controllers/api/v1/accounts/dashboard_apps_controller.rb
• 版本标注：v1

---

5. Inbox CSAT 模板（WhatsApp/Twilio CSAT 模板管理）

CSAT 模板创建与管理

• 功能描述：针对 WhatsApp 和 Twilio WhatsApp 通道，CSAT 调查需要通过官方模板（Template）发送。此功能提供 CSAT 模板的状态查询、创建、效用分析（Captain AI 评分）三部分能力。模板创建后自动更新 Inbox 的 csat_config 配置。
• 用户操作流程：
  1. 管理员进入 Inbox 设置 → CSAT 模板管理
  2. 查看当前模板状态（是否已创建、是否已审批通过）
  3. 创建新模板（填写消息文本、按钮文本、语言）→ 系统调用 WhatsApp/Twilio API 创建
  4. 可选使用 AI 分析功能（analyze）对模板文本质量进行评分
  5. 模板审批通过后，CsatSurveyService 在 WhatsApp 通道优先使用模板发送
• 涉及的API端点：
  • GET /api/v1/accounts/:account_id/inboxes/:inbox_id/csat_template — 查看模板状态
  • POST /api/v1/accounts/:account_id/inboxes/:inbox_id/csat_template — 创建模板
  • POST /api/v1/accounts/:account_id/inboxes/:inbox_id/csat_template/analyze — AI 分析模板效用（需 Captain feature flag）
• 涉及的数据模型+关键字段：
  • Inbox 的 csat_config (jsonb)：
    • csat_survey_enabled (boolean) — 是否开启 CSAT
    • message (string) — 自定义 CSAT 消息文本
    • display_type (string) — 评分展示类型（emoji / text）
    • survey_rules — 标签定向规则
    • template — WhatsApp/Twilio 模板配置（template name、language、status 等）
• 涉及的业务逻辑：
  • CsatTemplateManagementService：
    • template_status：根据 Inbox 类型调用 WhatsApp/Twilio API 查询模板审批状态
    • create_template：验证参数 → 删除旧模板 → 调用对应 Provider API 创建 → 更新 csat_config
  • Whatsapp::CsatTemplateService / Twilio::CsatTemplateService：封装 WhatsApp Business API 和 Twilio API 的模板 CRUD
  • CsatTemplateUtilityAnalysisService：调用 Captain AI 分析模板文本质量（按钮文字、语言适配性）
  • CsatTemplateNameService：生成标准化的 CSAT 模板命名
  • CsatTemplateUtilityRubric：定义 CSAT 模板质量评分标准
• 涉及的自动化/规则/事件：
  • 模板创建 → 自动更新 Inbox csat_config 的 template 字段
  • 模板审批状态变更 → 前端重新查询状态
  • CsatSurveyService 发送时检查 template_available_and_approved?，优先使用模板
• Chatwoot原实现代码路径：
  • app/controllers/api/v1/accounts/inbox_csat_templates_controller.rb
  • app/services/csat_template_management_service.rb
  • app/services/csat_template_utility_analysis_service.rb
  • app/services/csat_template_utility_rubric.rb
  • app/services/csat_template_name_service.rb
  • app/services/whatsapp/csat_template_service.rb
  • app/services/twilio/csat_template_service.rb
  • app/services/twilio/csat_template_api_client.rb
• 版本标注：v1；AI analyze 需要 Captain feature flag

---

6. Report Metrics（报告指标与数据查询体系）

指标注册体系

• 功能描述：Chatwoot 报告系统采用双层指标注册机制。ReportingEvents::EventMetricRegistry 定义写入侧（原始事件 → Rollup 指标的映射），Reports::ReportMetricRegistry 定义读取侧（API 请求指标名 → 查询策略的映射）。两者保持指标名对齐，确保写入和读取路径一致。
• 核心指标清单：
  • conversations_count — 会话数（count）
  • incoming_messages_count — 收到消息数（count）
  • outgoing_messages_count — 发出消息数（count）
  • avg_first_response_time — 平均首次响应时间（average, raw_event: first_response, rollup: first_response）
  • avg_resolution_time — 平均解决时间（average, raw_event: conversation_resolved, rollup: resolution_time）
  • avg_reply_time — 平均回复时间（average, raw_event: reply_time, rollup: reply_time）
  • resolved_conversations_count — 已解决会话数（count, raw_event: conversation_resolved）
  • bot_resolutions_count — Bot 解决数（count）
  • bot_handoffs_count — Bot 移交数（count）

时序报告（Timeseries Report）

• 功能描述：时序报告按时间维度（day/week/month/year/hour）聚合指标数据，支持按 account/inbox/agent/label/team 维度过滤，返回 { value, timestamp, count } 结构的时序数据。数据源自动选择 RawDataSource（原始事件查询）或 RollupDataSource（聚合表查询，预留）。
• 用户操作流程：
  1. 前端请求指定 metric + type + id + 时间范围的报告 API
  2. ReportBuilder 根据 metric 从 ReportMetricRegistry 获取查询策略
  3. DataSource.for() 创建数据源实例（当前默认 RawDataSource）
  4. 执行 timeseries 或 aggregate 查询 → 返回时间序列数据
• 涉及的API端点：
  • GET /api/v2/accounts/:account_id/reports?metric=avg_first_response_time&type=account&id=1&since=...&until=... — 时序数据
  • GET /api/v2/accounts/:account_id/reports/summary — 全局汇总
  • GET /api/v2/accounts/:account_id/reports/bot_summary — Bot 汇总
• 涉及的数据模型+关键字段：
  • 基于 ReportingEvent + ReportingEventsRollup 的查询
  • DataSource 参数：account, metric, dimension_type, dimension_id, scope, range, group_by, timezone_offset, business_hours
• 涉及的业务逻辑：
  • V2::Reports::Conversations::ReportBuilder → V2::Reports::Timeseries::ReportBuilder → Reports::DataSource.for() → Reports::RawDataSource
  • RawDataSource.timeseries：average 指标 → group_by_period + average + count；count 指标 → group_by_period + count
  • RawDataSource.summary：按 dimension_type 分组查询各指标（conversations_count / resolved_count / avg_resolution_time / avg_first_response_time / avg_reply_time）
  • 支持 business_hours 参数：当 use_business_hours? 为 true 时查询 value_in_business_hours 字段
• 涉及的自动化/规则/事件：
  • Rollup 读取路径预留：DataSource.for() 中注释 # TODO: Route to Reports::RollupDataSource when rollup reads are implemented
• Chatwoot原实现代码路径：
  • app/services/reports/report_metric_registry.rb
  • app/services/reports/data_source.rb
  • app/services/reports/raw_data_source.rb
  • app/builders/v2/reports/conversations/report_builder.rb
  • app/builders/v2/reports/conversations/base_report_builder.rb
  • app/builders/v2/reports/timeseries/report_builder.rb
  • app/builders/v2/reports/timeseries/base_timeseries_builder.rb
  • app/controllers/api/v2/accounts/reports_controller.rb
• 版本标注：v2；Rollup 读取路径待实现

Summary Reports（分组汇总报告）

• 功能描述：Summary Reports 按不同维度（Agent / Team / Inbox / Label / Channel）提供分组汇总数据，每组返回 conversations_count、resolved_conversations_count、avg_resolution_time、avg_first_response_time、avg_reply_time 五项指标。支持 business_hours 和日期范围过滤。Channel Summary 有额外日期范围长度限制（≤31天）。
• 用户操作流程：
  1. 前端选择维度（Agent/Team/Inbox/Label/Channel）+ 日期范围 + 是否仅营业时间
  2. 后端调用对应 SummaryBuilder → DataSource.summary → 聚合查询
  3. Builder 将结果按维度分组整理返回
• 涉及的API端点：
  • GET /api/v2/accounts/:account_id/summary_reports/agent?since=...&until=...&business_hours=true
  • GET /api/v2/accounts/:account_id/summary_reports/team
  • GET /api/v2/accounts/:account_id/summary_reports/inbox
  • GET /api/v2/accounts/:account_id/summary_reports/label
  • GET /api/v2/accounts/:account_id/summary_reports/channel（≤31天限制）
• 涉及的数据模型+关键字段：
  • 通过 Reports::DataSource.summary 查询 ReportingEvent / ReportingEventsRollup
  • SummaryBuilder 的 group_by_key：Agent → user_id，Team → conversations.team_id，Inbox → inbox_id
• 涉及的业务逻辑：
  • V2::Reports::AgentSummaryBuilder：按 user_id 分组，遍历 account_users 构建每个 Agent 的指标字典
  • V2::Reports::TeamSummaryBuilder / InboxSummaryBuilder / LabelSummaryBuilder / ChannelSummaryBuilder：类似模式
  • V2::Reports::BaseSummaryBuilder：统一 load_data → prepare_report 流程，data_source 使用 summary_dimension_type 映射
  • Channel Summary 特殊：日期范围 ≤31天校验
• 涉及的自动化/规则/事件：无（纯查询）
• Chatwoot原实现代码路径：
  • app/controllers/api/v2/accounts/summary_reports_controller.rb
  • app/builders/v2/reports/base_summary_builder.rb
  • app/builders/v2/reports/agent_summary_builder.rb
  • app/builders/v2/reports/team_summary_builder.rb
  • app/builders/v2/reports/inbox_summary_builder.rb
  • app/builders/v2/reports/label_summary_builder.rb
  • app/builders/v2/reports/channel_summary_builder.rb
• 版本标注：v2

CSV 导出报告

• 功能描述：Reports Controller 的 agents/inboxes/labels/teams/conversations_summary/conversation_traffic 端点同时支持 JSON 和 CSV 导出。前端请求时根据响应格式选择渲染方式。
• 涉及的API端点：
  • GET /api/v2/accounts/:account_id/reports/agents — Agent 报告（JSON/CSV）
  • GET /api/v2/accounts/:account_id/reports/inboxes — Inbox 报告（JSON/CSV）
  • GET /api/v2/accounts/:account_id/reports/labels — Label 报告
  • GET /api/v2/accounts/:account_id/reports/teams — Team 报告
  • GET /api/v2/accounts/:account_id/reports/conversations_summary — 会话汇总
  • GET /api/v2/accounts/:account_id/reports/conversation_traffic — 会话流量热力图
  • GET /api/v2/accounts/:account_id/reports/bot_metrics — Bot 指标
  • GET /api/v2/accounts/:account_id/reports/first_response_time_distribution — 首次响应时间分布
• 涉及的业务逻辑：
  • ReportsHelper（app/helpers/api/v2/accounts/reports_helper.rb）：调用各 SummaryBuilder 构建 JSON 数据，再转换为 CSV 格式
  • HeatmapHelper：会话流量热力图数据，按小时 × 日期矩阵组织
  • generate_csv 方法：根据格式参数渲染 CSV template 或 JSON
• Chatwoot原实现代码路径：
  • app/helpers/api/v2/accounts/reports_helper.rb
  • app/helpers/api/v2/accounts/heatmap_helper.rb
  • app/controllers/api/v2/accounts/reports_controller.rb
  • app/views/api/v2/accounts/reports/ — CSV 模板
• 版本标注：v2

---

附录：模块间依赖关系

功能	依赖
CSAT Survey	Inbox.csat_config, Conversation.resolved, Message.input_csat, WhatsApp/Twilio Template
Campaign	Inbox.inbox_type, Liquid Template, Contact/Audience
Reporting Event	Conversation lifecycle events, Inbox.working_hours, User assignments
Reporting Rollup	Reporting Event (写入触发), Account.reporting_timezone
Live Reports	Conversation.open/unattended/unassigned/pending scopes
Dashboard Apps	Account, User
Inbox CSAT Template	Inbox.channel (WhatsApp/Twilio), csat_config, Captain AI
Report Metrics	ReportingEvent + Rollup (数据源), ReportMetricRegistry (查询策略)
Summary Reports	DataSource.summary, Conversation group scopes
CSAT Survey → Reporting	CSAT 评分数据未直接写入 ReportingEvent（独立查询体系）

---

附录：核心数据表一览

表名	主要字段	索引特点
csat_survey_responses	rating(1-5), feedback_message, message_id(UNIQUE), assigned_agent_id, contact_id	message_id 唯一索引，多维度关联索引
campaigns	campaign_type(ongoing/one_off), campaign_status(active/completed), trigger_rules(jsonb), audience(jsonb), scheduled_at	campaign_type/status/scheduled_at 索引
reporting_events	name, value, value_in_business_hours, account_id, inbox_id, user_id, conversation_id, event_start/end_time	(account_id,name,created_at) 复合索引，response_distribution 复合索引
reporting_events_rollups	metric, dimension_type, dimension_id, date, count, sum_value, sum_value_business_hours	(account_id,date,dimension_type,dimension_id,metric) UNIQUE，timeseries/summary 索引
dashboard_apps	title, content(jsonb: [{url,type:"frame"}]), account_id, user_id	account_id, user_id 索引