公开 API 客户端可观测性

客户端要能解释“请求发生了什么”，但不应通过记录完整请求/响应来实现。本文给出公开客户端可用的最小事件、追踪、指标和排障报告设计。

事件模型

每个请求事件可包含：

{
  "time": "<RFC3339_TIME>",
  "action": "read_playlog",
  "status": 200,
  "success": true,
  "duration_ms": 123,
  "retry_count": 0,
  "account_alias": "account-a"
}

account_alias 必须是本地生成的脱敏别名。不要用 Token、完整用户名、机台标识或请求体生成别名。

请求分类

把动作分类成用户可理解的公开操作：

• 会话验证；
• 读取主页/统计；
• 读取列表；
• 读取文件；
• 保存配置；
• 上传；
• 删除；
• 恢复；
• 内容互动；
• 机台统计读取。

不要把未公开路径、内部函数名或源码中的隐藏规则名写入事件名称。

必要指标

延迟

记录请求总耗时和可选的解析耗时。文件下载还可以记录大小，但不记录文件内容。延迟高时先看网络、服务状态和文件大小，不要自动并发增加请求。

错误率

按传输失败、HTTP 失败、业务失败和解析失败分别统计。一个 HTTP 200 + success:false 不应计作成功。

重试

记录重试次数和最终结果。写入、删除、上传、恢复和机台动作默认不自动重放；读请求的重试次数应有上限。

空数据

空数组是业务结果，不应与网络错误混在一起。统计空结果时附带页面、账号范围和查询窗口，不要记录个人数据。

Token 生命周期事件

可以记录：

• Token 验证成功/失败；
• 过期时间是否存在；
• 退出发生；
• 轮询停止。

不要记录 Token 原文、前缀、长度与其它标识的组合，也不要把 Token 放在错误追踪的 URL 中。

脱敏管道

日志发送前执行统一过滤：

1. 移除 Token、密码、访问码、二维码；
2. 移除请求体中的凭据字段；
3. 移除 URL 查询参数；
4. 遮盖 IP、完整机台编号和本地路径；
5. 禁止上传图片、备份和记录原文；
6. 对 msg 限长和转义；
7. 使用随机追踪 ID。

过滤器必须在开发环境和生产环境都启用。测试中故意放入占位凭据，断言输出不包含原文。

追踪 ID

客户端可以为一组用户操作生成随机追踪 ID，例如一次“下载备份并验证”的流程。追踪 ID 不能由 Token、账号名、二维码或时间拼接生成。

在反馈中提供追踪 ID、时间和动作分类即可，管理员再按授权渠道查找内部日志。

轮询可观测性

自动刷新记录：

• 开始时间；
• 周期；
• 最近一次成功；
• 最近一次失败；
• 当前账号别名；
• 停止原因（离开页面、Token 失效、用户关闭）。

离开页面后要停止轮询。不可见标签页可以降低频率，但不能无限后台请求。

写入确认事件

写入操作至少记录以下阶段：

opened → validated → submitted → response_received
→ reread_started → reread_result → finished

超时流程使用 response_unknown，不要直接写成 failed 或 success。状态未知时下一步是回读，不是自动重试。

文件事件

文件读取记录：

• 文件类别（图片/备份/快照/其它）；
• 服务返回的脱敏名称；
• HTTP 状态；
• Content-Type 类别；
• 大小；
• 耗时；
• 预览/下载结果。

不要记录文件路径、内容哈希与完整账号标识的组合，避免可反推个人。

用户反馈摘要

自动生成的反馈摘要应是：

页面：<页面>
动作：<公开动作>
时间：<含时区>
结果：<空/业务失败/网络失败/超时>
状态：<HTTP/业务状态>
重试：<次数>
账号：<脱敏别名>

用户可以在提交前编辑摘要。任何自动附加完整请求体的功能都应关闭。

可观测性自测

• [ ] 成功、业务失败、HTTP 失败和解析失败可区分；
• [ ] 空数组不计为网络错误；
• [ ] 写入超时显示未知状态并触发回读；
• [ ] Token 原文不会出现在控制台；
• [ ] URL 查询参数已过滤；
• [ ] 图片/备份/记录不会自动上传；
• [ ] 离开页面后轮询停止；
• [ ] 日志事件不包含隐藏端点或内部名称；
• [ ] 追踪 ID 不含敏感信息。