hyb-oa/.trellis/tasks/08-23-wecom-public-health-alert-diagnostics-and-debounce/implement.md

企微公网健康告警防抖与诊断增强实施计划

Preconditions

• 用户审核并明确批准本规划后，才运行 task.py start。
• Phase 2 开始前加载 trellis-before-dev，读取 operations 相关 spec、当前任务三份规划材料及引用的运维事实源。
• 本任务采用 Codex inline 实施，不整理或依赖 implement.jsonl / check.jsonl。
• 保持现有报销任务未提交改动不动，不纳入本任务 diff、校验或提交。

Ordered Implementation Checklist

1. 探测分类
   • 在 scripts/check-public-app-health.py 按具体异常优先级拆分 DNS 与 TCP 类别。
   • 保持 TLS、超时、HTTP、响应过大和响应合同分类稳定，日志只打印 token。
2. 状态 schema 与纯状态转换
   • 引入显式新版探测状态、严格校验、有界计数和旧 schema 保守迁移。
   • 将“样本 + 当前时间 → 新状态 + 可选通知候选”提取为纯逻辑。
   • 实现 2 次失败、2 次成功、60 分钟同类复发提醒、抖动期静默计数和连续健康 30 分钟静默退出。
3. 专用消息文案与兼容
   • 为应用健康普通告警、恢复和抖动事件增加明确的“OA 公网健康”标题。
   • 扩展 helper 白名单及发送判断，但保持备份、dead-man 和其他既有状态文案/去重行为不变。
4. 合同测试
   • 扩充 scripts/qa/run-app-health-monitor-contract.sh：分别模拟 DNS、TCP、TLS、超时、HTTP、格式、过大响应。
   • 使用纯状态转换或合成时间覆盖全部正常、恢复确认、同类抖动、不同类别复发、30/60 分钟边界和旧状态迁移。
   • 断言消息数量、顺序、专用标题、静默退出及敏感内容禁入。
   • 回归损坏状态 fail-closed、文件权限、固定路径、默认 disabled 和 5 分钟 timer。
5. 共享合同与事实源
   • 运行自动备份合同，证明共用 helper 无回归。
   • 仅在形成稳定可复用规则时，更新既有 .trellis/spec/hyb-oa/ 或 docs/试运行与自动化验证手册.md；不新建无必要文档。
6. 本地质量门禁
   • 逐项运行下列验证，限定敏感扫描和 diff 审核在本任务相关文件。
   • 对权限/状态机变更完成主会话只读复核；inline 模式不派发 implement/check 子代理。
7. 提交与交付
   • 只暂存当前 Trellis task 和本任务实现/测试/必要事实源文件。
   • 使用中文 commit message，并引用 wecom-public-health-alert-diagnostics-and-debounce。
   • 本地完成后仅报告“本地验证通过”；未获 ARM 部署与公网检查批准前，不告知用户可在企业微信测试。

Validation Commands

python3 -m py_compile scripts/check-public-app-health.py scripts/send-wecom-group-alert.py
bash scripts/qa/run-app-health-monitor-contract.sh
bash scripts/qa/run-automatic-backup-contract.sh
bash -n deploy/trialrun/install-offhost-app-health-monitor.sh
node scripts/qa/check-process-contract.mjs --baseline --json
node scripts/qa/audit-docs.mjs --check-registry
node scripts/qa/check-trellis-governance.mjs
python3 ./.trellis/scripts/task.py validate 08-23-wecom-public-health-alert-diagnostics-and-debounce
git diff --check

敏感扫描采用稳定关键词和本任务文件清单，不打印潜在 Secret 值或原始 payload。

Risky Files and Rollback Points

• scripts/check-public-app-health.py：状态迁移和通知时机会改变；每一步先以合同测试锁定消息数量，再进入下一步。
• scripts/send-wecom-group-alert.py：被备份/dead-man 共用；任何改动必须先通过应用健康合同，再通过完整自动备份合同。
• deploy/trialrun/install-offhost-app-health-monitor.sh：若无需新增生产参数则尽量不改；如需改动，必须保持默认 disabled 和固定安全目标。
• 状态 schema：必须支持有效旧状态保守迁移；回滚前先停 timer，并只对已解析的精确状态文件执行保留/移出操作。

External Approval Gates

以下动作均不属于本地实施批准，执行前必须分别再次获得明确授权：

1. ARM 文件、systemd 或生产配置写入；
2. 启用/重启公网健康 timer；
3. 向真实企业微信群发送测试或生产消息；
4. 修改 DNS、resolver 或任何网络策略；
5. 写入真实业务数据或执行恢复操作。