Merge pull request #54 from xmindlab-heicode/docs/telemetry-prod-enablement-checklist

docs(telemetry): production enablement checklist 定稿 (#44)

docs/README.md

@@ -12,6 +12,7 @@
 | [`integration/heicode-desktop-client-api.md`](./integration/heicode-desktop-client-api.md) | 桌面客户端对接 HM（模板 Agent 模型），已生产验证 |
 | [`integration/heicode-am-contract.md`](./integration/heicode-am-contract.md) | HM ↔ AM（agent_management）接口契约 |
 | [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md) | **蜂群（Swarm）现状裁定与后续跟踪入口**：HM 当前不实现 swarm runtime，旧 sub/蜂群文档作废后的上下文迁移映射与归属（AM/Swarm 侧） |
+| [`integration/telemetry-production-enablement-checklist.md`](./integration/telemetry-production-enablement-checklist.md) | **客户端错误遥测生产开启前置 Checklist（#44 定稿）**：代码侧控制核验、生产配置、隐私/法务签字硬前置、上线/回滚验证；开启 `HEICODE_TELEMETRY_ENABLED` 前必过 |
 | [`deployment/azure-production-deploy-guardrails.md`](./deployment/azure-production-deploy-guardrails.md) | Azure VM / PostgreSQL / Redis / Agent / NewAPI 生产部署前的安全守卫、环境变量注入和验证计划 |
 
 旧 Agent API 草案、旧 sub / 蜂群任务编排、旧里程碑、旧架构说明和旧上手材料不再作为实施依据（相关文档已删除）。**蜂群相关文档的作废/迁移映射与「HM 不实现 swarm runtime、新能力归 AM/Swarm 侧跟踪」的结论见 [`integration/heicode-swarm-deferred.md`](./integration/heicode-swarm-deferred.md)（删除≠丢上下文，迁移到此追踪入口）。** 当前实施模型以 `heicode.md`、`plan.md` 与 `integration/heicode-hm-template-agent-model.md` 为准；生产部署操作以安全守卫文档约束，且不得覆盖产品/架构主线。

docs/integration/telemetry-production-enablement-checklist.md

@@ -0,0 +1,53 @@
+# 客户端错误遥测 — 生产开启前置 Checklist（定稿）
+
+> 工单：#44（拆分自 #32 EPIC）· 状态：**工程项已就绪;开启前置 = 隐私披露文档已发布 + 评审通过**
+> 适用：把 `HEICODE_TELEMETRY_ENABLED` 从默认 `false` 翻到 `true` 之前的强制检查清单。
+
+## 0. 一句话
+
+遥测**默认关闭**(摄入端点回 410 kill switch)。在本清单**全部勾选**前,生产 **不得** 开启;尤其是 §3 的隐私披露是硬前置——工程已把代码侧防线做齐,但「设备 ID 可关联账号」属隐私敏感,必须先在隐私文档如实披露并发布。
+
+## 1. 代码侧控制（已实现，可现场核验）
+
+| 控制 | 实现 | 核验方式 |
+|---|---|---|
+| 默认关闭 + kill switch | `HEICODE_TELEMETRY_ENABLED` 默认 `false`,关时摄入端点返回 **410** | `GET /api/heicode/config` → `telemetry.enabled=false`;`POST /api/heicode/telemetry/events` → 410 |
+| 不计费、不进 consume log | 独立 `telemetry_events` 表,摄入不写消费日志/不动 quota | 代码 `controller/heicode_telemetry.go`;开启后抽查无 consume log |
+| 仅设备配对可上送 | 需 V2 设备签名 + `X-Heicode-Device-Id`;会话-only 拒绝(403) | 无设备头请求 → 403 |
+| 批量/尺寸限制 | 顶层数组 1–20 条、≤256KB | 超限 → 413 |
+| context 字段白名单（#42） | 仅 `route/retryable/phase/exit_code/duration_ms/attempt`,其余键丢弃 | `TestFilterTelemetryContext_Whitelist` |
+| 单字段尺寸上限 | `stack_top`/`context` 脱敏后截断 8KiB | `TestCapTelemetryField` |
+| 服务端二次脱敏 | `stack_top`/`context` 剥离 sk-/Bearer/URL token/JSON 密钥字段 | `TestTelemetryToModel_RedactsSecrets` |
+| 数据保留期（#43） | `HEICODE_TELEMETRY_RETENTION_DAYS`(默认 30)+ master-only 每日清理 | `GET /api/heicode/config` → `retention_days`;`TestDeleteTelemetryEventsBefore` |
+
+**禁止采集(白名单已强制)**:prompt、代码正文、token、邮箱、完整文件路径、用户名路径、IP 原文等可识别信息——非白名单 `context` 键一律丢弃 + 服务端脱敏兜底。
+
+## 2. 生产配置确认（开启时设置 + 复核）
+
+- [ ] `HEICODE_TELEMETRY_ENABLED=true`（仅在 §3 全部完成后）
+- [ ] `HEICODE_TELEMETRY_RETENTION_DAYS` 已确认(建议 ≤90;默认 30)
+- [ ] `HEICODE_TELEMETRY_RETENTION_INTERVAL_HOURS` 已确认(默认 24)
+- [ ] 仅 master 节点跑清理任务(`IsMasterNode`,已在 `main.go` 内置)
+- [ ] `GET /api/heicode/config` 返回的 `telemetry` 块与上述配置一致
+
+## 3. 隐私披露前置（硬性，开启的真正闸门）
+
+> 这一节是**文档 + 评审**条件,不是代码项;由对应文档 PR 经评审通过即满足。
+
+- [ ] **heicodeDocs 隐私文档如实披露**「客户端错误遥测;**设备 ID 可关联账号、非匿名**;采集范围(崩溃类别/错误码哈希/脱敏调用栈/运行环境);保留期;不采集 prompt/代码/token/邮箱/完整路径/IP 原文」(跟踪：#34，草案已在 #34 给出)
+- [ ] 该隐私披露 PR **已评审通过并合并**(在 #44 / #34 留 PR 链接为开启决定留痕)
+- [ ] 隐私文档**已发布上线**(用户可见),且与实际采集行为一致(`法律声明.md`「隐私披露必须与真实采集行为一致」)
+
+## 4. 上线 / 回滚验证（开启当次执行）
+
+- [ ] 开启前:`POST /api/heicode/telemetry/events` 返回 **410**(确认 kill switch 基线)
+- [ ] 开启后:客户端真实上送一批 → `200 {accepted:n}`,落 `telemetry_events` 表
+- [ ] 抽查入库行:`stack_top`/`context` 已脱敏;`context` 仅白名单键;无 prompt/邮箱/路径/IP
+- [ ] 确认**无** consume log / quota 变化(遥测不计费)
+- [ ] **回滚演练**:把 `HEICODE_TELEMETRY_ENABLED` 改回 `false` → 端点回 410、客户端停送(kill switch 可用)
+- [ ] 保留期清理任务在日志中可见(`secret/telemetry retention task started`)
+
+## 5. 结论门
+
+**只有 §1 已核验 + §2 已确认 + §3 隐私披露已发布 + §4 验证通过,才允许在生产保持 `HEICODE_TELEMETRY_ENABLED=true`。**
+任一项不满足 → 维持默认关闭(410)。本清单作为 #44 的「checklist 定稿」交付;§3 的隐私披露文档(#34)是开启的前置条件。