> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue 概览与详情

> 掌握 Flashduty RUM 的异常追踪功能，快速发现并解决网站问题。

错误上报后可在异常追踪模块查看 Issue。在 Flashduty RUM 中，一个 Issue 是由一组相似错误组成的，这些错误通常与同一个 bug 相关。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/7eaffcd3d631d03ffb553f8956ff94ac.png" alt="Issue 列表" />
</Frame>

<Info>
  详细的聚合规则请参阅 [异常聚合](./error-aggregation)。
</Info>

## Issue 信息概览

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/5fb33aa6b0283515ca9f2427ae4aff27.png" alt="Issue 信息概览" />
</Frame>

Issue 浏览器中列出的每个条目包含以下信息：

| 信息项         | 描述            |
| ----------- | ------------- |
| 错误类型和错误消息   | Issue 的核心标识信息 |
| 错误发生的文件路径   | 定位错误来源        |
| 服务名称        | 关联的服务         |
| 错误原因        | 系统推断的可能根因     |
| 问题是否有复现     | 标识已解决问题是否再次出现 |
| 首次和最后出现时间   | Issue 生命周期信息  |
| 发生次数图表      | 随时间变化的趋势      |
| 所选时间段内的发生次数 | 统计数据          |

## Issue 状态

Issue 有 4 种状态，流转方式如下：

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/d81cfab46793c24b044c8d87ef30402b.png" alt="Issue 状态流转" />
</Frame>

| 状态      | 说明          |
| ------- | ----------- |
| **待处理** | 新发现的问题，需要关注 |
| **处理中** | 已确认并正在修复的问题 |
| **已解决** | 问题已修复       |
| **已忽略** | 无需处理的问题     |

<Tip>
  问题复现相关流转逻辑请参阅 [Issue 状态](./issue-status)。
</Tip>

## 筛选与排序

<Tabs>
  <Tab title="时间范围">
    浏览器右上角显示时间轴，允许您显示在选定时间段内发生错误的 Issue。您可以：

    * 从下拉菜单中选择预设范围
    * 直接修改时间
    * 输入自然语言进行筛选
  </Tab>

  <Tab title="排序方式">
    | 排序选项  | 说明                  |
    | ----- | ------------------- |
    | 更新时间  | 根据问题更新时间排序（默认）      |
    | 创建时间  | 根据首次发现时间排序          |
    | 发生次数  | 根据所选时间范围内错误的总发生次数排序 |
    | 影响会话数 | 根据受影响的 RUM 会话数量排序   |
  </Tab>

  <Tab title="筛选器">
    Flashduty RUM 自动为您的 Issue 建立预定义的属性索引，并创建对应的筛选器。

    <Frame>
      <img src="https://docs-cdn.flashcat.cloud/imges/png/718ff0527731fd89465a3a7e0fb7c7ea.png" alt="筛选器" />
    </Frame>

    支持的属性包括：

    | 属性      | 描述                                 |
    | ------- | ---------------------------------- |
    | 错误原因    | 错误发生时可能的根因类型                       |
    | 环境      | Issue 上报时的 env 字段                  |
    | 服务      | Issue 上报时的 service 字段              |
    | 错误类型    | 上报的 error 事件中的 error.type 字段       |
    | 错误信息    | error 事件中的 error.message 字段，支持模糊匹配 |
    | IssueID | Issue 聚合时的 ID，多个 ID 之间可用逗号分割       |
    | 问题复现    | 已解决的问题如果再次发生，则 Issue 会被标记为复现       |
    | 指纹      | Issue 聚合时的指纹信息，多个指纹之间可用逗号分割        |
  </Tab>
</Tabs>

## 错误原因分类

Flashcat 在每次创建 Issue 时会为其添加错误发生可能产生的错误原因分类，帮助提升故障定位的效率。

| 错误原因     | 说明                        |
| -------- | ------------------------- |
| 代码错误     | 由代码缺陷导致的错误                |
| 非法对象访问   | 代码访问了 null 或 undefined 对象 |
| 无效参数     | 使用无效参数调用函数                |
| 网络错误     | 服务器响应时间过长或网络速度慢           |
| API 请求失败 | API 端点返回了错误状态码            |
| 未知错误     | 无法定位该错误类型                 |

<Tip>
  当鼠标在错误原因分类上 hover 时，系统会结合 AI 能力进一步给出推断的根因和修复建议。
</Tip>

### 分类原理

系统采用两层分析机制对错误进行分类：

**第一层：模式匹配**

系统首先通过规则引擎按优先级依次检查错误类型和错误消息，首个匹配的规则决定分类结果：

| 检查顺序 | 匹配条件                                                               | 分类结果     |
| ---- | ------------------------------------------------------------------ | -------- |
| 1    | 错误消息包含 "Unexpected token ... is not valid JSON"                    | 无效参数     |
| 2    | 关联资源的 HTTP 状态码为 4xx 或 5xx                                          | API 请求失败 |
| 3    | 错误类型包含 "Network" 或 "AbortError"                                    | 网络错误     |
| 4    | 错误类型包含 "Syntax"、"Reference"、"Range"、"URI" 或 "Eval"                 | 代码错误     |
| 5    | 错误类型为 TypeError 且消息匹配空值访问模式（如 "Cannot read property of undefined"） | 非法对象访问   |
| 6    | 错误消息匹配无效参数模式（如 "invalid argument"、"unexpected token"）              | 无效参数     |
| 7    | 错误消息包含 "API ERROR:" 或许可证相关错误                                       | API 请求失败 |
| 8    | 错误消息包含网络连接相关关键词（如 "timeout"、"connection"、"dns"）                    | 网络错误     |
| 9    | 以上均未匹配                                                             | 未知错误     |

**第二层：AI 推断**

当模式匹配结果为「未知错误」时，系统会调用 AI 模型进行深度分析。AI 模型会结合以下信息进行判断：

* **错误消息**：错误的描述文本
* **堆栈信息**：完整的调用堆栈
* **平台类型**：浏览器/JavaScript、Android/Kotlin/Java、iOS/Swift/Objective-C、Flutter/Dart、React Native、Unity/C# 等

AI 会输出错误分类和简要的原因解释（不超过 100 字）。推断结果在 Issue 卡片上以 hover 提示的形式展示，帮助您快速理解错误的根因。

## 问题复现

问题复现（Regression）指的是之前修复的 bug 再次出现。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/489e8b51c598fc2ef0a248508dd546d6.png" alt="问题复现" />
</Frame>

<Warning>
  如果一个错误被标记为已解决，但在后续（version 不同）又产生了相同的错误，则该 Issue 的状态会从结束态重新打开，并标记为「问题复现」。
</Warning>

## Issue 详情

Issue 列表支持两种查看模式：侧栏模式和全屏模式。默认以侧栏方式打开详情面板，您也可以点击展开按钮切换到全屏模式，获得更宽敞的查看空间和更完整的数据展示。

点击任何 Issue 可以打开详情面板，查看更多信息。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/964b9102aca07b4e68b569acf1d99891.png" alt="Issue 详情" />
</Frame>

<AccordionGroup>
  <Accordion title="基础信息">
    面板上部显示 Issue 的基础信息，如状态、错误原因等。您还可了解 Issue 的生命周期：首次和最后出现日期、持续时间，以及时间内的错误发生次数（按照一定时间粒度聚合）。
  </Accordion>

  <Accordion title="标签分布">
    在标签分布区块可按照各种维度查看该 Issue 下不同标签所占比重，从而快速判断问题影响范围，辅助定位根因。

    目前支持 `view_name`、`browser_name`、`version`、`env` 等标签。
  </Accordion>

  <Accordion title="错误样例">
    默认展示当前 Issue 发生期间最近一次上报的错误信息作为错误样例，您也可通过导航条进行切换。
  </Accordion>

  <Accordion title="错误堆栈（Web）">
    查看 Web 端错误的上下文信息和堆栈信息。如果上传过 SourceMap，您可以看到映射还原后的原始源码位置和代码片段。

    <Frame>
      <img src="https://docs-cdn.flashcat.cloud/imges/png/551f3fdc7eef25ac2888f71db87b9f69.png" alt="错误堆栈" />
    </Frame>

    在「应用管理」-「源码管理」可查看已上传的源码信息，详见 [源码映射](./source-mapping)。
  </Accordion>

  <Accordion title="错误堆栈（Native — Android/iOS）">
    Native 平台（Android/iOS）的错误堆栈展示针对移动端特点进行了专门设计，提供以下能力：

    **Pretty / Raw 模式切换**

    * **Pretty 模式**：结构化展示堆栈信息，自动区分应用帧（app frames）和第三方帧（third-party frames），第三方帧默认折叠，突出显示您自己的代码
    * **Raw 模式**：展示原始堆栈文本，方便复制和在外部工具中分析

    **符号化状态**

    如果已上传对应版本的符号文件（Android mapping 或 iOS dSYM），堆栈中的混淆地址会被自动还原为可读的函数名、文件名和行号。未符号化时，系统会提示您上传符号文件，并提供直达「源码管理」和上传工具的链接。

    **线程堆栈（Threads）**

    Native 崩溃通常涉及多个线程。线程面板展示崩溃时所有线程的堆栈信息，支持：

    * 查看线程总数和当前展示的线程数
    * 展开/折叠所有线程
    * 每个线程内独立区分应用帧和第三方帧，第三方帧可按需展开查看
    * 崩溃线程的堆栈会被优先展示

    **Binary Images（iOS）**

    对于 iOS 崩溃，还可以查看崩溃时加载的 Binary Images（二进制镜像）列表，包含镜像名称、地址范围和 UUID 等信息，用于辅助离线符号化分析。

    详细的符号文件上传流程请参阅 [源码映射](./source-mapping)。
  </Accordion>

  <Accordion title="会话时间线">
    查看当前错误示例所属的 Session 事件总数，以及该异常发生前后用户的资源访问情况和操作情况。

    <Note>
      当前最多展示包含当前 Error 事件在内的 20 条上下文信息，后续您可在 Session 查看器模块查看更多日志信息。
    </Note>

    <Tip>
      如果该会话已采集了回放数据，您可以直接点击「查看回放」按钮跳转到会话重放页面，从用户视角重现错误发生时的完整操作路径。
    </Tip>
  </Accordion>

  <Accordion title="属性">
    异常事件在上报时会携带一系列属性，您可在属性区块查看当前的 Session、视图、用户等各类信息，方便排查问题。
  </Accordion>
</AccordionGroup>

## 异常告警

在问题发生时立即发现它，让您有机会在问题变得严重之前主动识别和修复它。

<Frame>
  <img src="https://docs-cdn.flashcat.cloud/imges/png/eebe04d7a964b0dfaafd87daa9b6a345.png" alt="异常告警配置" />
</Frame>

<Steps>
  <Step title="进入应用管理">
    选中应用卡片后进行编辑
  </Step>

  <Step title="开启告警">
    打开「告警」开关
  </Step>

  <Step title="选择协作空间">
    选择通知的协作空间
  </Step>
</Steps>

<Info>
  具体告警配置说明请参阅 [Issue 告警](./issue-alerts)。
</Info>

## 最佳实践

<CardGroup cols={2}>
  <Card title="配置源码映射" icon="code">
    便于在生产环境定位问题
  </Card>

  <Card title="添加用户信息" icon="user">
    配置用户相关信息，提供更好的错误上下文
  </Card>

  <Card title="设置告警策略" icon="bell">
    为错误配置合理的协作空间和分派策略
  </Card>

  <Card title="定期错误分析" icon="chart-line">
    定期检查错误报告，发现潜在问题
  </Card>

  <Card title="团队协作" icon="users">
    利用团队所有权功能确保问题能够快速分配给相关团队
  </Card>

  <Card title="监控回归" icon="rotate">
    密切关注已解决问题的潜在回归
  </Card>
</CardGroup>

## 下一步

<CardGroup cols={3}>
  <Card title="源码映射" icon="code" href="./source-mapping">
    配置源码映射
  </Card>

  <Card title="异常聚合" icon="layer-group" href="./error-aggregation">
    了解聚合机制
  </Card>

  <Card title="Issue 状态" icon="circle-check" href="./issue-status">
    管理 Issue 状态
  </Card>
</CardGroup>