Collector API

HealthGuard Collector 提供 REST API 供 SDK 上报事件和 Dashboard 查询数据。

Base URL: http://your-collector-host:3100

POST /api/events/batch

事件批量上报接口。SDK 调用此接口上报采集到的事件。

Request

{
  "appKey": "web_abc123",
  "events": [
    {
      "eventId": "evt_xxx",
      "appKey": "web_abc123",
      "platform": "web",
      "type": "error",
      "timestamp": 1716192000000,
      "sessionId": "session_xxx",
      "anonymousId": "anon_xxx",
      "sdkVersion": "0.1.0",
      "errorType": "js",
      "message": "Cannot read property 'foo' of undefined",
      "stack": "...",
      "fingerprint": "js:abc123",
      "breadcrumbs": []
    }
  ]
}

Response

{
  "accepted": 1
}

字段说明

字段	类型	必填	说明
appKey	string	是	应用唯一标识
events	array	是	事件数组，最少 1 条，最多 50 条

POST /api/auth/register

用户注册。

Request

{
  "email": "user@example.com",
  "password": "your-password"
}

Response

{
  "token": "session_xxx",
  "user": {
    "id": "user_xxx",
    "email": "user@example.com",
    "createdAt": 1716192000000
  }
}

POST /api/auth/login

用户登录。

Request

同 /api/auth/register。

Response

同 /api/auth/register。

GET /api/auth/me

获取当前登录用户信息。

Headers

Authorization: Bearer <token>

GET /api/apps

获取当前用户的应用列表。

Headers

Authorization: Bearer <token>

POST /api/apps

创建新应用。

Headers

Authorization: Bearer <token>

Request

{
  "name": "My Web App",
  "type": "web"
}

GET /api/overview

获取数据概览。

Query Parameters

参数	类型	必填	说明
appKey	string	否	按应用筛选

Response

{
  "totals": {
    "events": 128,
    "errors": 12,
    "failedRequests": 3,
    "affectedUsers": 8,
    "issues": 5
  }
}

GET /api/issues

获取 Issue 列表。

Query Parameters

参数	类型	必填	说明
appKey	string	否	按应用筛选

GET /api/issues/:id

获取 Issue 详情。

Response

{
  "issue": {
    "id": "web_abc123:js:def456",
    "appKey": "web_abc123",
    "fingerprint": "js:def456",
    "message": "Cannot read property 'foo' of undefined",
    "errorType": "js",
    "eventCount": 15,
    "firstSeenAt": 1716100000000,
    "lastSeenAt": 1716192000000
  },
  "events": [...]
}

PATCH /api/apps/:appKey

修改项目显示名称，需携带项目所有者的 Authorization: Bearer <SESSION_TOKEN>。

{ "name": "示例司机端" }

仅接受 name 字段，去除首尾空白后为 1–100 字符。成功返回 { "app": { ... } }，包含 id、name、appKey、type 和 createdAt。未登录返回 401；非法字段或名称返回 400 INVALID_APP_NAME；项目不存在或不属于当前用户返回 404 APP_NOT_FOUND。

仅更新名称，不改变 appKey、历史数据或通知规则。无需数据库迁移和 SDK 更新；旧版 Collector 需要升级后才能使用。

PATCH /api/issues/:id/archive

需要项目所有者的 Bearer 会话。可对未验证问题归档，不会执行代码修复。

{ "note": "Server-side fix completed" }

请求体和 note 均可省略；备注去除首尾空白后最多 4000 字，未知字段、非法类型或超长备注返回 400，未登录返回 401，不存在或非所有者返回 404。返回 { issue }，其 archiveRecord 为 { note, archivedAt }。时间为毫秒。重复请求不覆盖已保存的归档记录。新增事件继续计数，保持手动归档。

PATCH /api/issues/:id/reopen

仅项目所有者可调用。恢复到当前问题列表，保留上次归档备注；不会修改业务代码。PostgreSQL 在 Collector 启动时自动增加 issues.archive_record JSONB，不删除历史修复元数据。需先升级 Collector 再升级 Dashboard。

兼容保留的修复、验证及 PR 写接口也会校验项目所有权，避免通过旧接口绕过归档权限。

事件接收与通知时间字段

Issue 详情中的每条事件新增可空 receivedAt（Unix 毫秒），由 Collector 在接收批次时设置，客户端提交的同名字段被忽略。timestamp 仍是客户端上报的发生时间；相同 Event ID 重传保留首次接收时间和计数。旧记录返回 null，不从 created_at、事件或邮件时间推算；排序与时间筛选继续沿用原有发生时间语义。

通知历史增加 eventTimestamp、receivedAt、sendingStartedAt 与 sentAt，createdAt 仍表示邮件任务生成时间。sendingStartedAt 表示开始处理发信任务，sentAt 仅在 SMTP 成功接受后返回，失败/取消/投递未知为 null；均不证明进入收件箱。历史未保存的字段可能缺失或为 null，测试邮件没有事件时间。数据库只新增可空 events.received_at 列，回退保留该列。

设备字段与所有者查询（未发布）

Flutter 0.3.0 事件包含独立的 deviceId（hgd1_ + 64 位十六进制 SHA-256）、deviceIdStatus、deviceIdSource、deviceIdScope 和不可用时的 deviceIdReason；设备型号/系统在 deviceInfo.model/system，本次 App/SDK 版本在 release/sdkVersion。获取失败省略 deviceId，不伪造值；旧事件缺失字段继续接收并保持未知。Collector 校验格式及状态/来源/作用域一致性，JSONB 保存原字段，不回填历史 ID，仅新增项目/时间索引。

项目所有者 Bearer 会话可调用：

• GET /api/devices?appKey=<KEY>&kind=stable&search=HG-...&limit=50&offset=0
• GET /api/devices/events?appKey=<KEY>&key=<URL_ENCODED_FULL_GROUP_KEY>&limit=50&offset=0

可选 platform、start、end 毫秒范围；类别为 stable/installation/unknown，分页每页 1–100。列表返回 devices/total/totals，totals 分别为 stableDevices/installations/unidentifiedEvents；单设备历史返回 events/total。分类总量覆盖平台/时间范围，列表 total 额外应用类别/搜索。历史必须使用返回的完整分组 key，不用短码；401 为未认证，404 为项目不存在或不属于当前用户。只统计保留的异常数据，不代表永久物理设备清单。