# 试点运行周报开发说明

> 对应接口契约：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`

```json
{
  "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. 业务流程设计

```mermaid
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. 精简验证

```powershell
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烟测验证固定隐私分布、配置与固件设备数守恒、比例可用性、投诉证据缺口、敏感字段排除、幂等重放和烟测清理；浏览器烟测验证周报下载和缺口提示。全仓回归、容量、安全、恢复、真实设备和供应商验证仍在固定发布候选上集中执行。