# CLAUDE.md - AR SDK 项目指引

## 项目概述

tencentcloud-webar SDK，提供实时美颜、虚拟背景、3D 头像等 AR 能力。
- 语言：TypeScript
- 平台：H5 (Web) + 微信小程序
- 构建：Webpack 5
- 测试：Jest

## Bugfix 自动修复流程

当用户说 **"处理 BUG-XXX"** 时，按以下流程执行：

### 触发条件

用户输入包含以下关键词之一：
- "处理 BUG-XXX"
- "修复 BUG-XXX"
- "分析 BUG-XXX"

### 标准处理步骤

#### Step 0: 信息完整性检查（前置门禁）
在开始分析之前，必须先检查以下必要信息是否齐全：
1. **问题描述**：`report.yml` 中的 `title` + `description` 是否清晰描述了问题现象
2. **日志文件**：`logs/` 目录下是否存在 `.ndjson` 日志文件
3. **聊天截图**（可选）：检查 `chat/` 目录下是否有客户沟通截图，如果有则读取参考

如果缺少 1 或 2，**停止处理**，向用户说明缺少什么，要求补充后再继续。

#### Step 1: 读取 & 解析
1. 读取 `bugfix/BUG-XXX/report.yml` 解析 Bug 信息
2. 读取 `bugfix/BUG-XXX/logs/` 下所有 `.ndjson` 日志文件
3. 如果存在 `bugfix/BUG-XXX/chat/` 目录，读取其中的截图辅助理解问题背景
4. 将 report.yml 中 `status` 更新为 `analyzing`

#### Step 2: 问题定位
1. 解析 `.ndjson` 日志：按 `@timestamp` 排序还原时间线，通过 `msg` 字段定位模块
2. 解析 `ext1` 字段（二次 JSON.parse）获取事件详情和参数
3. 结合 `customer_code` 和日志时间线分析调用链路与异常点
4. 在 `src/` 中定位对应源码（注意区分 h5/wx 平台）
5. 确定根因和影响范围
6. 输出分析到 `bugfix/BUG-XXX/fix/analysis.md`，格式：
   ```markdown
   # 问题分析：BUG-XXX
   ## 根因
   ...
   ## 影响范围
   ...
   ## 修复思路
   ...
   ```

#### Step 3: 代码修复
1. 修改 `src/` 中的相关源码
2. 输出变更记录到 `bugfix/BUG-XXX/fix/changes.md`，格式：
   ```markdown
   # 代码变更：BUG-XXX
   ## 修改文件
   - `src/h5/xxx.ts` (行 XX-XX): 修改描述
   ## 修改原因
   ...
   ## 兼容性说明
   ...
   ```

#### Step 4: 创建验证 Demo
1. 生成 `bugfix/BUG-XXX/fix/demo.html`（单文件，可直接浏览器打开）
2. **Demo 必须完全复刻客户的真实使用方式**，包含完整的鉴权、摄像头获取、SDK 初始化流程
3. Demo 规范：
   - SDK 引用：使用 `../webar-sdk.umd.{hash}.js` 相对路径引用 UMD 产物
   - 鉴权信息：使用测试账号（见下方）
   - 必须包含 vconsole 方便调试：`https://unpkg.com/vconsole@latest/dist/vconsole.min.js`
   - 必须包含 sha256：`https://webar-static.tencent-cloud.com/docs/examples/js-sha256/0.9.0/sha256.min.js`
   - 完整复刻客户调用流程（getUserMedia → new ArSdk → initCore → getOutput → 触发问题场景）
   - 提供操作按钮让测试人员可以手动触发问题场景和验证修复

4. **构建 UMD 产物并更新 Demo**（每次创建/更新 demo 后必须执行）：
   ```bash
   # 在 ar/ar-sdk 目录下执行
   npm run build-umd:dev
   # 将产物复制到 bugfix 目录
   cp build-umd/webar-sdk.umd.*.js bugfix/BUG-XXX/fix/
   # 更新 demo.html 中的 script src 为最新产物文件名
   ```

5. 测试账号信息：
   ```javascript
   const APPID = "1309122168";
   const LICENSE_KEY = "f827c19302d1009216d759feee2dafad";
   const token = "1054493363136cf02c1ad7c54e3a9c76";
   const getSignature = function () {
       const timestamp = Math.round(new Date().getTime() / 1000);
       const signature = sha256(timestamp + token + APPID + timestamp).toUpperCase();
       return { signature, timestamp };
   };
   ```

6. Demo 模板结构：
   ```html
   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>BUG-XXX 验证 - [问题简述]</title>
       <meta name="description" content="[问题详细描述和验证目标]">
   </head>
   <body>
       <video id="source" playsinline autoplay style="position:fixed;top:0;left:0;z-index:9;width:200px;"></video>
       <video id="output" playsinline autoplay style="width:auto;"></video>
       <div id="controls">
           <!-- 操作按钮：复现问题 + 验证修复 -->
       </div>
       <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"></script>
       <script src="./webar-sdk.umd.{hash}.js"></script>
       <script src="https://webar-static.tencent-cloud.com/docs/examples/js-sha256/0.9.0/sha256.min.js"></script>
       <script src="https://unpkg.com/vconsole@latest/dist/vconsole.min.js"></script>
       <script>
           var vConsole = new window.VConsole();
           // === 鉴权配置 ===
           // === SDK 初始化（复刻客户用法）===
           // === 复现问题的操作逻辑 ===
           // === 验证修复的操作逻辑 ===
       </script>
   </body>
   </html>
   ```

#### Step 5: 更新状态
1. 将 `report.yml` 中 `status` 更新为 `fixed`
2. 向用户输出修复总结：包含根因、修复方案、验证方式

### 约束

- **必须创建 demo 验证**，不能只改代码不验证
- **修复不能引入破坏性变更**，需考虑向后兼容
- 如果无法确定根因，在 analysis.md 中标明存疑点并询问用户
- 如果判断不是 Bug（用法错误等），将 status 设为 `wontfix` 并说明原因

### 日志格式

日志为 `.ndjson` 文件（Newline Delimited JSON），从内部日志系统直接下载，每行一条记录：
```json
{"@timestamp":"2026-05-16 09:34:18.127","msg":"ArSdk","ext1":"[\"事件名\",参数...]","ext3":"2.0.3-9"}
```

字段说明：
- `@timestamp` - 精确到毫秒的时间戳
- `msg` - SDK 内部模块名（ArSdk / worker-core / Auth / gpu-model / AROptionsManager / common-utils）
- `ext1` - 日志详情，是 JSON 序列化后的字符串，需要 `JSON.parse(ext1)` 二次解析
  - 解析后为数组：第一个元素是事件标识，后续元素是参数/状态
- `ext3` - SDK 版本号

分析策略：
1. 按 `@timestamp` 排序，还原完整事件时间线
2. 通过 `msg` 过滤关注的模块
3. 在时间线中寻找异常断点（如正常流程中断、状态不一致）
4. 结合 report.yml 中描述的时间点重点分析对应日志段

### Bug 报告结构

```
bugfix/BUG-XXX/
├── report.yml          # Bug 描述（YAML）
├── logs/
│   └── xxxxxx.ndjson   # 从日志系统下载的原始日志
├── chat/               # （可选）客户沟通截图
│   └── *.png/jpg       # 聊天记录截图，辅助理解问题背景
└── fix/                # Claude 生成
    ├── analysis.md     # 问题分析
    ├── changes.md      # 变更记录
    └── demo.html       # 验证 Demo
```
