# Bugfix 工作流程说明

## 概述

本目录用于结构化管理客户反馈的 SDK 使用异常。每个 Bug 对应一个独立目录，包含报告、日志和修复验证。

## 目录结构

```
bugfix/
├── _template.yml         # Bug 报告模板
├── _log_format.md        # 日志格式说明
├── WORKFLOW.md           # 本文件
├── BUG-000/              # 示例 Bug
├── BUG-001/              # 实际 Bug
│   ├── report.yml        # Bug 描述（必须）
│   ├── logs/             # 从日志系统下载的 .ndjson 文件
│   │   └── xxxxxx.ndjson
│   ├── chat/             # （可选）客户沟通截图
│   │   └── *.png/jpg
│   └── fix/              # 修复产出（Claude 自动生成）
│       ├── analysis.md   # 问题分析报告
│       ├── changes.md    # 代码变更说明
│       └── demo.html     # 验证 Demo
```

## 提交 Bug 流程

1. **创建目录**：复制 `BUG-000` 目录，重命名为下一个编号（如 `BUG-001`）
2. **填写报告**：编辑 `report.yml`，按模板填写各字段
3. **放入日志**：从日志系统下载 `.ndjson` 文件，直接放入 `logs/` 目录（保持原始文件名即可）
4. **放入截图**（可选）：如果有客户聊天记录截图，放入 `chat/` 目录，Claude 会读取截图辅助理解问题
5. **触发修复**：告诉 Claude "处理 BUG-XXX"

## report.yml 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| id | 是 | Bug 编号，如 BUG-001 |
| title | 是 | 一句话描述 |
| status | 是 | pending/analyzing/fixed/verified/wontfix |
| priority | 是 | low/medium/high/critical |
| environment | 是 | SDK 版本、平台、浏览器等 |
| description | 是 | 详细问题描述 |
| customer_code | 是 | 客户的关键调用代码 |
| actual | 是 | 实际的错误行为/信息 |
| logs | 是 | 日志文件路径 |
| steps_to_reproduce | 推荐 | 复现步骤 |
| expected | 推荐 | 期望行为 |
| notes | 选填 | 你的初步判断 |

## 日志格式（.ndjson）

日志文件从内部日志系统直接下载，格式为 **Newline Delimited JSON**（每行一条记录），无需额外加工。

每条记录字段：
```json
{
  "@timestamp": "2026-05-16 09:34:18.127",   // 时间戳（精确到毫秒）
  "msg": "ArSdk",                             // SDK 内部模块名
  "ext1": "[\"事件名\",参数1,参数2]",           // 日志详情（JSON 字符串，需二次 parse）
  "ext3": "2.0.3-9"                           // SDK 版本号
}
```

常见 `msg` 模块值：
- `ArSdk` - SDK 主流程
- `worker-core` - Worker 渲染核心
- `Auth` - 鉴权
- `gpu-model` - GPU 检测
- `AROptionsManager` - 配置管理
- `common-utils` - 工具函数

分析要点：
1. 按 `@timestamp` 排序还原事件时间线
2. 通过 `msg` 过滤特定模块日志
3. `ext1` 解析后第一个元素为事件标识，后续为参数/状态

详见 `_log_format.md`。

## Claude 自动修复流程

当你说 **"处理 BUG-XXX"** 时，Claude 会自动执行：

1. **读取分析** - 解析 report.yml + 日志文件
2. **定位问题** - 根据堆栈在 src/ 中定位源码，分析根因
3. **修复代码** - 修改 src/ 中的相关文件
4. **创建 Demo** - 生成可独立运行的 demo.html 验证修复效果
5. **更新状态** - 将 status 标记为 fixed

## 状态流转

```
pending → analyzing → fixed → verified
                  ↘ wontfix
```

- `pending`: 新提交，待处理
- `analyzing`: Claude 正在分析中
- `fixed`: 已修复，待人工验证
- `verified`: 人工验证通过
- `wontfix`: 非 Bug 或不修复
