试点运行周报开发说明

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

1. 建设目标与边界

试点运行周报用于落实外部验收清单中的周度复盘要求，把平台内有权威数据来源的内容审核、记忆确认、隐私请求、固件分布和设备配置差异汇总为一份可下载、可审计的脱敏JSON。周报按指定IANA时区、从周一零时开始计算七个自然日，避免服务器时区、UTC日期或夏令时导致跨周错位。

当前平台没有投诉/客服工单权威表，因此周报固定返回external_evidence=[{"code":"complaints","status":"REQUIRED",...}]，要求归档人员附客服或CRM脱敏证据。系统不把联调问题、告警或隐私请求推断成用户投诉，也不提供虚假的“投诉为0”结论。

2. 功能设计

2.1 周期与完整性

请求必须填写候选版本和sha256:不可变构建摘要；week_start必须是指定时区内的周一且不能晚于当前日期。窗口采用[week_start, week_start+7个日历日)，可能因夏令时为167、168或169小时。window_start/window_end以UTC返回，is_complete=false表示当前自然周尚未结束，只能作为周中快照；完整周结束后重新生成并归档正式周报。候选身份随响应和审计冻结，证据包强制与同包技术验收快照及7份日报一致。

2.2 内容审核指标

指标	权威来源	口径
周内生成故事	`story_draft.created_at`	所选周创建的候选故事数
审核触达故事	`audit_event`	周内发生修订、确认或拒绝成功动作的去重故事数
人工修订故事	`story.revise`、`sharing.story.edit`	周内至少一次用户修订的去重故事数
人工修订率	上述两项	人工修订故事/审核触达故事，四舍五入到基点
故事确认/拒绝	`story.confirm`、`story.reject`	周内成功终态动作数
故事确认率	确认与拒绝动作	确认/（确认+拒绝），四舍五入到基点
正式记忆首版/修订	`memory_version`	`version_no=1`为首版，后续版本为修订，按`confirmed_at`入周
当前索引积压	`memory_index_entry`	生成时刻当前有效记忆的`PENDING/FAILED`索引数

两个比例均包含*_rate_available。分母为0时available=false且数值保持0，页面显示“—”，避免把“没有审核样本”误读为0%修订或0%确认。

2.3 隐私、固件与配置指标

隐私请求按周内创建时间返回固定四类请求和五类状态数组；即使某项为0也保留。current_open/current_partial_failed是生成时刻所有未完成请求的积压，不限于所选周。

固件分布只统计当前已绑定且状态为registered的设备，按设备型号和device_twin.firmware_version汇总，尚未上报的设备归入UNREPORTED。输出只有分组数量，不包含设备编号、序列摘要、家庭或长者信息。

配置差异使用同一可用设备集合：reported_revision=desired_revision为一致；已上报但不同为差异；没有设备孪生或从未上报为未上报。三项之和必须等于eligible_devices。同时返回当前活动和暂停的运行配置投放数量，但不返回配置正文或密钥引用。

2.4 权限、脱敏与幂等

输出策略为ops-pilot-weekly-minimal-v1，不包含故事/记忆正文、字幕、录音、主体资料、设备编号、供应商任务、配置正文、投诉内容、隐私请求原因或审计原因。接口要求真实OIDC、客户组织选择、ops_operator/ops_admin角色、幂等键和最长255字符的归档原因。

首次成功返回201；24小时内以相同幂等键和请求体重试返回200、Idempotency-Replayed: true及同一周报编号和生成时间。服务端不持久化周报正文，只保存幂等响应和最小审计；响应带Cache-Control: no-store。

3. 接口设计

3.1 请求

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

{
  "candidate_version": "0.55.0-rc.1",
  "build_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "week_start": "2026-08-24",
  "timezone": "Asia/Shanghai",
  "reason": "归档试点周度复盘并补充外部投诉证据"
}

请求头	必填	说明
`Authorization`	是	OIDC Bearer令牌
`X-Tenant-Id`	是	操作人有权访问的客户组织公开编号
`Idempotency-Key`	是	生成动作的重试边界
`X-Request-Id`	否	调用链关联编号

响应包含客户组织、候选身份、周界、完整性、内容审核、隐私、固件、配置、外部证据缺口和免责声明。比例采用0—10000基点整数，前端除以100显示百分比。参数错误返回400，权限或租户关系错误返回403，幂等正文冲突返回409。

4. 业务流程设计

sequenceDiagram
    participant O as 试点运营人员
    participant UI as 联调诊断页面
    participant API as 周报聚合接口
    participant DB as PostgreSQL
    participant E as 客服或CRM证据库
    O->>UI: 选择周一、时区并填写原因
    UI->>API: OIDC + 租户 + 幂等键 + 周报请求
    API->>DB: 校验角色和客户组织
    API->>DB: 聚合审核、记忆、隐私、固件和配置
    API->>DB: 写最小审计和幂等响应
    API-->>UI: 周报JSON + 投诉证据REQUIRED
    UI-->>O: 展示摘要并下载文件
    O->>E: 取得同周期脱敏投诉证据
    O->>O: 两份证据共同归档并召开周度复盘

复盘时先确认is_complete=true，再处理隐私部分失败、记忆索引失败、未上报固件和配置差异。内容比例必须结合样本数阅读，不能只看百分比。投诉证据未附加时周度证据包不完整；周报接口不会因为其他技术指标正常而把该缺口改为完成。

5. 数据库设计

本功能不新增迁移和周报表，复用以下数据：

表	用途
`audit_event`	故事修订、分享修订、确认和拒绝的不可变成功事件
`story_draft`	周内生成故事数量
`curated_memory`、`memory_version`、`memory_index_entry`	正式记忆版本确认与当前索引状态
`privacy_request`	周内类型/状态分布和当前未完成积压
`device_binding`、`device`、`device_twin`	当前可用设备、固件分布和期望/上报配置修订
`runtime_config_rollout`	当前活动/暂停配置投放数量
`idempotency_record`、`audit_event`	下载重放与生成动作审计

各指标使用单条聚合查询保证自身内部口径一致；全部读取、审计和幂等响应在一个数据库事务中提交。审计动作是ops.diagnostics.pilot_weekly_snapshot.export，只记录周起始日、时区、UTC窗口、完整性和脱敏策略。

6. 精简验证

go test ./internal/diagnostics ./internal/httpapi
npm --prefix web run build
powershell -ExecutionPolicy Bypass -File .\scripts\smoke-pilot-weekly-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

定向测试验证跨夏令时的七个日历日、非周一和未来周拒绝、基点舍入；真实OIDC烟测验证固定隐私分布、配置与固件设备数守恒、比例可用性、投诉证据缺口、敏感字段排除、幂等重放和烟测清理；浏览器烟测验证周报下载和缺口提示。全仓回归、容量、安全、恢复、真实设备和供应商验证仍在固定发布候选上集中执行。

7.6 KiB Raw Permalink Blame History