用户反馈（Feedback）

用户反馈把”用户在 App 里遇到问题想说话”这件事收进 Argus：端上 SDK 提供一行代码弹出的反馈表单 （或纯 API 提交），自动附带会话 / 设备 / 最近日志等上下文；反馈到达 Console 后可升格为工单 （Ticket），走”分流 → 定优先级 → 回复用户 → 解决 / 归档”的完整流转。

核心概念

反馈事件 vs 工单

• 反馈事件：端上提交的原始内容（正文 + 可选联系方式 + 附件 + 自动上下文），经 POST /v1/events（统一 EventBatch）落 ClickHouse，在 Console 反馈列表中可见、可搜索。
• 工单（Ticket）：运营在 Console 对某条反馈事件点”建工单”后生成的可流转对象（PostgreSQL）， 承载状态、优先级、负责人与回复时间线。一条反馈事件至多对应一个工单。

工单状态机

new（新建）→ triaged（已分流）→ responded（已回复）→ resolved（已解决）→ archived（已归档）

• 允许跳级前进（如 new → resolved）。
• resolved / archived 可重开回 triaged / responded。
• 禁止倒退回 new；archived 为终态（仅可重开）。
• 非法流转被服务端拒绝，返回 409 + 原因——Console 的状态下拉只会列出合法的下一步。

优先级

urgent（紧急）/ high（高）/ normal（普通）/ low（低），运营在工单详情里随时调整。

富媒体附件

• 单条反馈最多 9 个附件。
• 图片 ≤ 10MB（png / jpeg / gif / webp），视频 ≤ 50MB（mp4 / webm / quicktime）； 服务端按真实内容嗅探类型，SVG 等可执行内容一律拒绝。
• 上传链路：SDK 先逐个上传附件（任一失败整体中止，不留半截反馈）→ 提交反馈事件 → 回填关联。附件由后台过期清理，被清理后 Console 显示”附件已过期”占位。

接入

平台矩阵

SDK 提交时会自动附加上下文（session / 设备信息 / 最近日志摘要）到事件 attributes， 便于在 Console 排查时还原现场。

最小接入片段

// 方式一：内置最小反馈表单（正文 + 可选联系方式 + 选择图片/视频附件）
const close = Argus.openFeedback(); // 返回手动关闭表单的函数
 
// 方式二：自己做 UI，直接 API 提交
await Argus.submitFeedback("结算页点了没反应", {
  contact: "user@example.com",           // 可选，便于回访
  attributes: { screen: "checkout" },    // 可选，业务补充属性
  // attachments: [...]                  // 可选，截图 / 录屏附件
});

// 方式一：弹出内置反馈表单（主线程调用）
Argus.openFeedback()
 
// 方式二：API 提交（async throws，失败由调用方决定如何提示）
try await Argus.submitFeedback("结算页点了没反应",
                               contact: "user@example.com",
                               attributes: ["screen": "checkout"])

// 方式一：弹出内置反馈表单（须传 Activity，Application context 无法弹窗）
Argus.openFeedback(activity)
 
// 宿主 Activity 的 onActivityResult 里转发文件选择结果（选择图片/视频附件需要）
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (Argus.handleFeedbackActivityResult(requestCode, resultCode, data)) return
    super.onActivityResult(requestCode, resultCode, data)
}
 
// 方式二：API 提交（后台执行，best-effort，失败记日志不抛）
Argus.submitFeedback("结算页点了没反应", contact = "user@example.com")

Console 使用

进入 Console 左侧导航 Feedback 页（先在左上角选择项目）：

1. 反馈列表（左侧）：展示反馈事件的时间、正文、用户、平台，以及关联工单的状态 / 优先级徽章； 支持按正文搜索、按工单状态过滤（新建 / 已分流 / 已回复 / 已解决 / 已归档）。
2. 建工单：尚未建单的反馈行有”建工单”按钮，一键以反馈正文为摘要创建工单并打开详情。
3. 工单详情（右侧）：
   • 摘要、提交用户、联系方式、平台 / 版本、关联事件 ID；
   • 附件区：图片缩略图（点击放大）、视频内嵌播放、已被清理的附件显示”附件已过期”占位；
   • 状态流转：下拉只显示当前状态的合法下一步（非法流转服务端 409 拦截）；
   • 优先级 / 负责人：随时调整；
   • 回复：查看回复时间线、发送新回复。发送回复后，new / triaged 状态的工单会自动推进到 responded（“回复即已回复”）。

SDK API 速查

Web 的 opts（FeedbackOptions）字段：contact?、attributes?、userId?、sessionId?、 anonymousId?、attachments?。

MCP 工具

接入 Argus MCP Server 后，AI 可直接检索与总结反馈 （源码：feedback_search.ts）：

典型提问：“最近用户都在抱怨什么？帮我按主题归纳”、“把 user-123 的历史反馈都列出来”。

配额与计费

• 反馈事件与回复计入项目事件量，富媒体附件字节计入存储量（具体系数以计费页为准）。
• 详见 套餐、配额与计费。

FAQ

用户能在 App 里看到我的回复吗？ 暂时不能。当前回复留存在 Console 工单时间线中，用户侧”我的反馈”列表 / 应用内收件箱为规划中能力。 需要触达用户请使用其填写的联系方式。

为什么改工单状态报 409？ 状态机拒绝了非法流转（例如从 responded 退回 new）。参照上文状态机图；Console 的下拉框只给 合法选项，直接调 API 时同样受服务端校验约束。

附件上传有什么限制？ 每条反馈最多 9 个附件；图片单个 ≤ 10MB、视频单个 ≤ 50MB；类型以服务端内容嗅探为准 （png / jpeg / gif / webp / mp4 / webm / quicktime）。任一附件上传失败时整条反馈中止提交， 不会出现”文字到了、附件丢了”的半截反馈。

Flutter / React Native 怎么收反馈？ 这两端的反馈 API 尚未提供（规划中）。短期可自行实现表单 UI 后由后端转发，或引导用户走其他渠道； 请关注 SDK 版本更新。

工单详情里的附件显示”附件已过期”？ 附件有保留期，由后台清理任务定期删除过期对象；指针仍在事件上所以渲染为占位。属正常行为， 不影响其余附件与工单内容。