# 重建触发与错误码约定

本文档定义仓库对外提供的统一重建入口，供 AstrBot、cron 或手工执行复用。

## 统一入口

```bash
npm run rebuild
```

该命令会顺序执行：

1. `npm run content:sync`
2. `npm run build`

当前还不包含部署步骤；后续如接入部署，可继续扩展到同一入口里。

## 适合 AstrBot 的调用方式

AstrBot 只需要做三件事：

1. 定时触发 `npm run rebuild`
2. 读取进程退出码
3. 从输出中提取 `REBUILD_RESULT ...` 这一行，作为结构化结果

推荐通知内容：

- 成功：开始时间、结束时间、总耗时
- 失败：失败阶段、错误码、错误符号、最后几行日志

## 结构化输出

命令结束前会输出一行 JSON：

```text
REBUILD_RESULT {"ok":true,"stage":"build","code":0,"symbol":"SUCCESS",...}
```

字段说明：

- `ok`: 是否成功
- `stage`: 失败或结束所在阶段，当前可能为 `sync` / `build` / `bootstrap`
- `code`: 退出码
- `symbol`: 退出码对应的文本符号
- `startedAt`: 整体开始时间
- `finishedAt`: 整体结束时间
- `durationMs`: 整体耗时
- `failedStepDurationMs`: 当前失败步骤耗时；成功时为最后一步耗时
- `logTail`: 最后若干行日志，便于 AstrBot 通知时直接带上排障信息

## 错误码

### 成功

| Code | Symbol | 含义 |
|------|--------|------|
| 0 | `SUCCESS` | 全部成功 |

### 同步阶段

| Code | Symbol | 含义 |
|------|--------|------|
| 10 | `SYNC_FAILED` | 通用同步失败 |
| 11 | `GITEA_SYNC_FAILED` | Gitea 同步失败 |
| 12 | `SEAFILE_SYNC_FAILED` | Seafile 同步失败 |
| 13 | `SCHEMA_VALIDATION_FAILED` | JSON/Schema 校验失败 |

### 构建阶段

| Code | Symbol | 含义 |
|------|--------|------|
| 20 | `BUILD_FAILED` | Astro 构建失败 |

### 部署阶段（预留）

| Code | Symbol | 含义 |
|------|--------|------|
| 30 | `DEPLOY_FAILED` | 静态产物部署失败 |

### 运行阶段

| Code | Symbol | 含义 |
|------|--------|------|
| 40 | `CONFIG_INVALID` | 运行环境缺少必要命令或配置异常 |
| 50 | `UNKNOWN_ERROR` | 未归类异常 |

## 手动补跑

本地或服务器上都可以直接执行：

```bash
npm run rebuild
```

如果只是想单独排查同步阶段，也可以先运行：

```bash
npm run content:sync
```

## 建议的 AstrBot 判定逻辑

- 退出码 `0`：发送成功通知
- 非 `0`：发送失败告警
- 优先展示：
  - `symbol`
  - `stage`
  - `code`
  - `logTail`