update-server/Docs/崩溃报告接口联调说明.md

# SimCAE 崩溃报告接口联调说明

本文说明崩溃报告后端接口怎么测试，以及 curl 示例里的 `dev-token` 应该替换成什么。

## 一、先搞清楚三个 Token

curl 示例里的：

```text
Authorization: Bearer dev-token
```

这里的 `dev-token` 只是占位符，不是固定值。实际要按接口用途替换成服务端 `.env` / `.env.docker.example` 里的 token。

| 使用场景 | 请求头里填什么 | 服务端配置字段 |
| --- | --- | --- |
| 客户端上传崩溃报告 | `Authorization: Bearer <CRASH_REPORT_TOKEN>` | `CRASH_REPORT_TOKEN` |
| 上传符号包 | `Authorization: Bearer <CRASH_SYMBOL_TOKEN>` | `CRASH_SYMBOL_TOKEN` |
| 查询/下载崩溃报告原始文件 | `Authorization: Bearer <CRASH_ADMIN_TOKEN>` | `CRASH_ADMIN_TOKEN` |
| `CRASH_ADMIN_TOKEN` 为空时查询/下载 | `Authorization: Bearer <ADMIN_TOKEN>` | `ADMIN_TOKEN` |

当前默认配置通常是：

```env
CRASH_REPORT_TOKEN=SimCAECrashReportToken2026
CRASH_SYMBOL_TOKEN=SimCAESymbolToken2026
CRASH_ADMIN_TOKEN=
ADMIN_TOKEN=SimCAEAdminToken2026
```

所以，如果使用默认配置：

- 上传崩溃报告用 `SimCAECrashReportToken2026`。
- 上传符号包用 `SimCAESymbolToken2026`。
- 查询/下载崩溃报告时，因为 `CRASH_ADMIN_TOKEN` 为空，所以用 `SimCAEAdminToken2026`。

管理后台“客户端配置生成”区域下方也会显示“崩溃报告接口联调信息”。这部分只给管理员或测试人员查看，不会复制进客户端 `app_config.json`，也不要手动放进客户端配置文件。

其中会以类似 `.env` 的形式把 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN`、`CRASH_ADMIN_TOKEN`、`ADMIN_TOKEN` 单独列出来，并在每个字段前加中文说明。`CRASH_ADMIN_TOKEN` 如果为空，查询和下载崩溃报告时就使用 `ADMIN_TOKEN`。

## 二、接口地址

假设服务端地址是：

```text
http://192.168.1.158:8000
```

下面示例里用变量表示：

```bash
SERVER=http://192.168.1.158:8000
REPORT_TOKEN=SimCAECrashReportToken2026
SYMBOL_TOKEN=SimCAESymbolToken2026
ADMIN_TOKEN=SimCAEAdminToken2026
```

如果部署了 HTTPS 或域名，把 `SERVER` 改成实际地址即可。

## 三、健康检查

健康检查不需要 token：

```bash
curl "$SERVER/api/v1/health"
```

正常返回类似：

```json
{
  "status": "ok",
  "service": "simcae-crash-server",
  "version": "1.0.0",
  "timeUtc": "2026-07-14T00:00:00Z"
}
```

## 四、准备测试文件

创建一个假的 minidump 文件：

```bash
printf "dummy minidump for api test\n" > crash.dmp
```

附件是可选的。需要测试附件时可以准备一个 zip：

```bash
mkdir -p attachments
printf "extra log\n" > attachments/runtime.log
zip -r attachments.zip attachments
```

如果服务器上没有 `zip`，可以先不传 `attachments` 字段。

## 五、准备 metadata.json

`clientReportId` 必须是 UUID，并且请求头 `Idempotency-Key` 必须和它完全一致。

最小可用示例：

```json
{
  "schemaVersion": 1,
  "clientReportId": "8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1",
  "crashTimeUtc": "2026-07-14T08:30:00Z",
  "product": "SIMCAE",
  "appVersion": "0.10.3",
  "gitCommit": "unknown",
  "buildType": "Release",
  "channel": "stable",
  "platform": {
    "os": "Windows",
    "arch": "x64"
  },
  "crash": {
    "exceptionCode": "0xC0000005",
    "threadId": 1
  },
  "userConsent": {
    "uploadAllowed": true
  },
  "files": []
}
```

保存成 `metadata.json`。

说明：

- `product` 必须是 `SIMCAE`。
- `schemaVersion` 必须是数字 `1`。
- `files` 必须是数组，可以先填空数组。
- 如果 `files` 里声明了 `minidump` 的 `sha256`，服务端会校验它必须和实际上传的 `crash.dmp` 一致。

## 六、上传崩溃报告

不带附件的最小上传：

```bash
curl -X POST "$SERVER/api/v1/crash-reports" \
  -H "Authorization: Bearer $REPORT_TOKEN" \
  -H "Idempotency-Key: 8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1" \
  -H "X-SimCAE-Client: SIMCAE" \
  -H "X-SimCAE-Version: 0.10.3" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "minidump=@crash.dmp;type=application/octet-stream"
```

带附件上传：

```bash
curl -X POST "$SERVER/api/v1/crash-reports" \
  -H "Authorization: Bearer $REPORT_TOKEN" \
  -H "Idempotency-Key: 8f6c5ed9-9a2b-4ef1-89a2-8843f2f7d9d1" \
  -H "X-SimCAE-Client: SIMCAE" \
  -H "X-SimCAE-Version: 0.10.3" \
  -F "metadata=@metadata.json;type=application/json" \
  -F "minidump=@crash.dmp;type=application/octet-stream" \
  -F "attachments=@attachments.zip;type=application/zip"
```

正常首次上传返回 HTTP 201，类似：

```json
{
  "reportId": "srv_xxxxxxxxxxxxxxxxxxxxxxxx",
  "duplicate": false,
  "status": "stored",
  "acceptedAtUtc": "2026-07-14T08:31:00Z"
}
```

如果用同一个 `clientReportId` 和相同内容重复上传，会返回 HTTP 200，并且：

```json
{
  "duplicate": true
}
```

如果同一个 `clientReportId` 但内容变了，会返回 HTTP 409，表示幂等冲突。

## 七、查询崩溃报告详情

把上传返回的 `reportId` 填到下面命令里：

```bash
REPORT_ID=srv_xxxxxxxxxxxxxxxxxxxxxxxx

curl "$SERVER/api/v1/crash-reports/$REPORT_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

注意：

- 这里用的是管理查询 token。
- 如果 `.env` 里配置了 `CRASH_ADMIN_TOKEN`，就用 `CRASH_ADMIN_TOKEN`。
- 如果 `CRASH_ADMIN_TOKEN` 为空，就用 `ADMIN_TOKEN`。

## 八、下载崩溃报告文件

可下载文件名：

```text
metadata.json
crash.dmp
attachments.zip
server.json
```

下载 minidump：

```bash
curl "$SERVER/api/v1/crash-reports/$REPORT_ID/files/crash.dmp" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o crash_downloaded.dmp
```

下载 metadata：

```bash
curl "$SERVER/api/v1/crash-reports/$REPORT_ID/files/metadata.json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o metadata_downloaded.json
```

管理后台也可以查看崩溃报告列表和下载文件。

## 九、上传符号包

符号包接口用于上传某个版本/构建对应的 symbols.zip。

准备 `symbols_metadata.json`：

```json
{
  "schemaVersion": 1,
  "product": "SIMCAE",
  "appVersion": "0.10.3",
  "gitCommit": "unknown",
  "buildType": "Release",
  "platform": "windows-x64",
  "toolchain": "msvc2019",
  "createdAtUtc": "2026-07-14T08:00:00Z",
  "files": []
}
```

准备测试符号包：

```bash
mkdir -p symbols
printf "dummy symbols\n" > symbols/readme.txt
zip -r symbols.zip symbols
```

上传：

```bash
curl -X POST "$SERVER/api/v1/symbols" \
  -H "Authorization: Bearer $SYMBOL_TOKEN" \
  -F "metadata=@symbols_metadata.json;type=application/json" \
  -F "symbols=@symbols.zip;type=application/zip"
```

正常返回类似：

```json
{
  "symbolUploadId": "sym_xxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "stored",
  "duplicate": false,
  "acceptedAtUtc": "2026-07-14T08:35:00Z"
}
```

## 十、常见错误

1. HTTP 401 `missing bearer token`
   没有传 `Authorization: Bearer ...`，或者格式写错。

2. HTTP 401 `invalid bearer token`
   token 值不对。检查 `.env` 里的 `CRASH_REPORT_TOKEN`、`CRASH_SYMBOL_TOKEN`、`CRASH_ADMIN_TOKEN`、`ADMIN_TOKEN`。

3. HTTP 403 `token is not allowed to access this endpoint`
   token 是对的，但用错接口了。例如拿 `CRASH_REPORT_TOKEN` 去查询/下载报告。

4. HTTP 400 `Idempotency-Key must equal metadata.clientReportId`
   请求头 `Idempotency-Key` 必须等于 metadata 里的 `clientReportId`。

5. HTTP 400 `metadata.product must be SIMCAE`
   metadata 里的 `product` 必须填 `SIMCAE`。

6. HTTP 400 `file_hash_mismatch`
   metadata.files 里声明的 SHA-256 和实际上传文件不一致。联调初期可以先把 `files` 填成空数组。

7. HTTP 413 `payload_too_large`
   文件超过 `.env` 里的大小限制，例如 `CRASH_MINIDUMP_MAX_MB`、`CRASH_ATTACHMENTS_MAX_MB`、`CRASH_REQUEST_MAX_MB`。

8. HTTP 409 `idempotency_conflict`
   同一个 `clientReportId` 已经上传过，但这次内容不一样。换一个新的 UUID 再试。