试点运行日报开发说明

对应接口契约：OpenAPI 0.55.0
适用阶段：阶段8内部试用、家庭试点和灰度观察
适用角色：ops_operator、ops_admin

1. 建设目标

试点运行日报把每日必须归档的设备在线、通话状态、供应商失败、媒体上传积压、告警和费用六类信息聚合为一份脱敏JSON，解决运营人员分别查询多个工作台后手工拼表、时间边界不一致和证据无法复核的问题。日报由运营诊断页面即时生成并下载，服务端只保存幂等记录和最小审计，不建立日报正文历史表。

日报是运行复盘证据，不是发布门禁或业务验收结论。它混合两种明确区分的口径：所选自然日内的活动统计，以及生成时刻的在线、积压和未关闭状态。真实听感、供应商账单、用户反馈、隐私授权和发布批准仍由对应外部证据承担。

2. 功能设计

2.1 输入与时间边界

操作人填写候选版本、sha256:不可变构建摘要、业务日期、IANA时区和归档原因。候选身份随日报进入响应、幂等摘要和审计，后续PILOT证据包强制与技术验收快照一致。服务端使用时区数据库把local_date转换为[window_start, window_end)半开区间，再统一以UTC查询。自然日通过日历日期递增计算，因此夏令时切换日可以是23小时或25小时，不强行按24小时截断。候选标识不合法、未来日期、未知时区、空原因和超过255字符的原因均拒绝。

2.2 指标口径

领域	自然日活动统计	生成时刻状态
设备	当前可用设备中，最新孪生上报落在自然日内的设备数	当前仍绑定的总数、可用/隔离/吊销、可用设备在线/离线数
通话	自然日内创建的通话总数及8个权威状态分布	不单列当前历史通话，避免与当日创建口径混淆
供应商	自然日内失败通知数、首次进入`FAILED`的关联通话数	最新探针状态、连续失败、待处理/失败通知积压
上传	当日创建、完成，以及当日最后更新且当前失败的上传批次	未结束批次、待处理分段、已拒绝分段
告警	当日首次发现和当日解决数量	全部未关闭、HIGH未关闭、CRITICAL未关闭
费用	按用量事件发生时间汇总费用行和微单位成本	不提供跨币种总计，不做未经批准的汇率换算

通话状态数组固定按PREPARING、ROOM_ISSUED、STARTING_AGENT、ACTIVE、STOPPING、COMPLETED、FAILED、EXPIRED返回，即使某状态为0也保留，从而让下载文件可直接纵向比较。供应商和币种数组按稳定字典序输出；无记录时返回[]而不是null。

2.3 脱敏与权限

输出策略固定为ops-pilot-daily-minimal-v1。日报不返回长者或家庭资料、字幕、录音、故事、记忆、设备密钥、短期凭证、供应商任务编号、告警标题/摘要、Webhook地址或原始错误。角色校验和所有查询均带客户组织边界；ops_viewer和ops_approver不能生成日报。

首次请求返回HTTP 201，相同操作人、租户、路径、幂等键和相同请求体在24小时内重放时返回HTTP 200及Idempotency-Replayed: true，且编号和生成时间保持不变。相同幂等键配不同请求体返回冲突。响应带Cache-Control: no-store。

3. 接口设计

3.1 请求

POST /api/v1/ops/diagnostics/pilot-daily-snapshots

请求头	必填	说明
`Authorization`	是	真实OIDC Bearer令牌
`X-Tenant-Id`	是	当前运营账号有权访问的客户组织公开编号
`Idempotency-Key`	是	本次日报生成的唯一重试标识
`X-Request-Id`	否	调用链关联编号；未提供时由公共HTTP层生成

请求体示例：

{
  "candidate_version": "0.55.0-rc.1",
  "build_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "local_date": "2026-08-25",
  "timezone": "Asia/Shanghai",
  "reason": "归档试点运行日报并复核当日异常与当前积压"
}

3.2 响应

响应data包含日报编号、生成时间、客户组织、候选版本、构建摘要、业务日期、时区、UTC窗口、脱敏策略、六类指标和固定免责声明。费用使用cost_micros整数保存和传输，前端仅在展示时除以1,000,000，避免浮点数参与权威汇总。

主要错误：参数或时区非法返回400，运营权限或客户组织关系不成立返回403，幂等键正文冲突或请求执行中返回409。错误响应不泄露另一客户组织是否存在相同数据。

4. 业务流程设计

sequenceDiagram
    participant O as 试点运营人员
    participant UI as 联调诊断页面
    participant API as 日报聚合接口
    participant DB as PostgreSQL
    O->>UI: 选择日期、时区并填写归档原因
    UI->>API: OIDC + 租户 + 幂等键 + 请求体
    API->>DB: 校验运营角色和客户组织关系
    API->>DB: 锁定或校验幂等请求
    API->>DB: 同一事务读取六类权威统计
    API->>DB: 写最小审计和幂等响应
    API-->>UI: 201日报或200同一结果重放
    UI-->>O: 展示摘要并下载JSON
    O->>O: 归档、复核异常、关联个案和周报

运营人员每日在约定时区日界后生成前一日或当日日报，首先核对高严重度告警和供应商/上传积压，再核对失败通话与设备离线情况，最后把费用按币种与供应商账单或成本工作台交叉确认。发现异常时转入告警工作台、精确诊断或联调问题清单；日报本身不执行修复动作，也不自动关闭告警。

5. 数据库设计

本功能不新增迁移和日报表，复用权威数据：

表	日报用途
`device_binding`、`device`	当前绑定边界和设备注册状态
`device_twin`、`device_presence_state`	最新上报时间和当前在线状态
`conversation`、`conversation_state_history`	当日创建通话分布和失败状态发生时间
`rtc_task`、`provider_event`、`provider_dependency_state`	供应商归属、失败通知、当前依赖状态和通知积压
`upload_batch`、`media_segment`	上传批次活动和当前分段积压
`alert_incident`	当日发现/解决和当前未关闭告警
`conversation_usage_event`、`conversation_cost_line`	按发生时间和币种汇总费用微单位
`idempotency_record`	24小时内请求重放和正文冲突保护
`audit_event`	操作人、原因、日期、时区、窗口和脱敏策略

所有聚合在同一个数据库事务中完成，每一类指标由单条聚合查询保持内部口径一致；审计和幂等响应与统计结果一起提交。审计动作是ops.diagnostics.pilot_daily_snapshot.export，资源类型为pilot_daily_snapshot；审计不复制日报正文或费用明细。

6. 可用性验证与运行方式

本功能采用精简验证：时间边界单元测试覆盖夏令时23小时自然日以及非法时区/未来日期；Go诊断和HTTP包定向测试验证编译与公共错误映射；真实纵向烟测使用本地OIDC、PostgreSQL和运行API核对首次创建、统计守恒、敏感字段排除、幂等重放和非法时区；浏览器烟测确认页面可见、JSON可下载解析且无横向溢出。

powershell -ExecutionPolicy Bypass -File .\scripts\smoke-pilot-daily-snapshot.ps1
$env:PLAYWRIGHT_REQUIRE_FROM='C:\Users\19926\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules'
node .\scripts\visual-diagnostics-ui.cjs
.\scripts\check-functional.ps1

烟测结束会删除对应审计和幂等记录；日报正文从未在服务端持久化。发布候选仍按阶段8清单执行真实设备、供应商、家庭试点、容量、安全、恢复和人工审批，不以本地日报烟测替代外部验收。

7.8 KiB Raw Permalink Blame History