chore: establish local platform baseline
This commit is contained in:
Codex Local
@@ -0,0 +1,20 @@
|
||||
# ADR-0001：首期采用Go模块化单体与独立Worker
|
||||
|
||||
- 状态：已接受
|
||||
- 日期：2026-08-23
|
||||
|
||||
## 背景
|
||||
|
||||
系统需要同时承载设备控制、家庭业务、Agent编排、供应商回调和后台可靠任务。首期需要优先保证事务一致性、联调效率和可部署性，同时保留以后按领域拆分服务的路径。
|
||||
|
||||
## 决策
|
||||
|
||||
后端采用同一Go模块中的模块化单体，部署为`api`、`callbacks`和`worker`三个独立进程。业务模块只能通过公开的应用层接口协作，不跨模块直接修改数据。跨进程工作先写入PostgreSQL outbox，再由Worker执行；Redis只保存可重建状态。
|
||||
|
||||
前端采用React、TypeScript和Vite。业务事实以PostgreSQL为准，实时语音不经过自建应用服务器。
|
||||
|
||||
## 影响
|
||||
|
||||
- 本地和测试环境可以用一套代码快速启动三个进程。
|
||||
- 共享数据库不代表可以绕过模块边界，代码评审需检查跨模块访问。
|
||||
- 将来拆分服务时，以模块公开接口、outbox事件和数据所有权为迁移边界。
|
||||
@@ -0,0 +1,176 @@
|
||||
# Agent固定评测集与发布门禁
|
||||
|
||||
## 1. 目的和需求对应
|
||||
|
||||
本文落实原需求 `P0252`“建立可重复的评测集和质量指标”。评测执行器把固定测试集、脱敏观测结果、评分规则、阈值、Agent版本和模型配置版本组合成一份可重复生成的JSON报告。相同评测集既可用于模拟供应商，也可用于真实账号；两种环境使用同一评分口径，但报告必须明确标记`mock`或`real`，不得用模拟结果代替真实账号验收。
|
||||
|
||||
评测报告可以直接转换为运营配置接口所需的登记正文，并固定标记为`AGENT_QUALITY_V1`。运营配置发布仍由既有双人审批、资源引用和评测门禁控制；`AGENT_BUNDLE`只有登记了`PASSED`标准Agent质量证据才可以发布，普通手工`GENERIC`证据不能绕过该门禁。
|
||||
|
||||
## 2. 交付组成
|
||||
|
||||
| 文件 | 作用 |
|
||||
|---|---|
|
||||
| `cmd/agent-eval` | 读取评测集和观测结果，生成报告；退化时返回非零退出码 |
|
||||
| `cmd/agent-eval-collect` | 通过受权限控制的SaaS接口读取每个用例的通话状态和最终话轮，自动生成脱敏观测文件 |
|
||||
| `cmd/agent-eval-register` | 校验评测集和报告完整性，使用确定性幂等键把证据登记到指定运行配置版本 |
|
||||
| `internal/agenteval` | 输入校验、逐用例评分、聚合指标、阈值判断和登记正文生成 |
|
||||
| `testdata/agent-eval-suite.v1.json` | 首版固定评测集、预期结果和评分规则引用 |
|
||||
| `testdata/agent-eval-collection.example.v1.json` | 用例、唯一通话编号和脱敏评分卡的采集清单示例 |
|
||||
| `testdata/agent-eval-observations.mock.v1.json` | 可重复执行的模拟供应商脱敏观测样例 |
|
||||
| `artifacts/agent-eval-report.mock.v1.json` | 当前模拟基线报告和可登记正文 |
|
||||
|
||||
测试集与观测文件只保存合成用例编号、时延、回答长度、布尔评分和计数，不保存完整对话、姓名、录音、提示词或供应商长期凭证。真实试点问题应先脱敏并分配稳定用例编号，再进入评测集。
|
||||
|
||||
## 3. 固定覆盖范围
|
||||
|
||||
评测集缺少以下任一类别时，执行器直接判定输入无效，不生成“通过”结论：
|
||||
|
||||
1. 正常闲聊 `normal_chat`；
|
||||
2. 长停顿 `long_pause`；
|
||||
3. 重复表达 `repeated_expression`；
|
||||
4. 姓名和日期歧义 `name_date_ambiguity`；
|
||||
5. 冲突事实 `conflicting_fact`；
|
||||
6. 情绪话题 `emotional_topic`；
|
||||
7. 用户打断 `user_interruption`；
|
||||
8. 网络波动 `network_fluctuation`；
|
||||
9. 记忆召回 `memory_recall`；
|
||||
10. 敏感信息 `sensitive_information`。
|
||||
|
||||
每个用例必须声明预期通话结果、首个回答时延上限、回答长度上限、虚构事实数量上限、至少一个评分标志和版本化评分规则引用。观测结果必须与评测集中的用例一一对应，不能缺失、重复或混入未知用例。
|
||||
|
||||
## 4. 质量指标
|
||||
|
||||
执行器同时执行“逐用例门禁”和“整套指标门禁”。逐用例失败能够定位到具体用例；聚合指标用于识别Agent版本整体退化。
|
||||
|
||||
| 指标 | 计算方式 | 默认基线用途 |
|
||||
|---|---|---|
|
||||
| 通话成功率 | 成功用例数 ÷ 全部用例数 | 检查完整对话是否可用 |
|
||||
| 首个回答P95时延 | 全部用例首个回答时延的最近秩P95 | 检查回答等待时间退化 |
|
||||
| 打断恢复率 | 打断用例中通过`interruption_recovered`的比例 | 检查打断后能否继续交流 |
|
||||
| 平均回答长度 | 全部用例回答字符数平均值 | 防止回答变得过长 |
|
||||
| 称呼准确率 | 要求`salutation_correct`的用例通过比例 | 检查长者称呼使用 |
|
||||
| 记忆准确率 | 要求`memory_correct`的用例通过比例 | 检查是否使用正确长者记忆 |
|
||||
| 虚构事实数 | 全部用例虚构事实计数之和 | 阻止无来源事实进入内容闭环 |
|
||||
| 故事来源完整率 | 要求`story_source_complete`的用例通过比例 | 检查候选内容可追溯性 |
|
||||
| 敏感信息处理率 | 敏感信息用例通过比例 | 检查敏感内容不进入普通故事或记忆 |
|
||||
|
||||
阈值保存在评测集文件中并随版本提交。修改阈值必须创建新的`suite_version`，不能覆盖已经用于发布结论的旧版本。
|
||||
|
||||
## 5. 自动采集与评分边界
|
||||
|
||||
每个用例完成一次独立通话后，采集清单把`case_id`关联到唯一`conversation_id`，并填写人工评分器或经过批准的自动评分器产生的脱敏评分标志。一个通话编号不能复用于多个用例。
|
||||
|
||||
采集器通过当前登录用户的OIDC访问令牌调用：
|
||||
|
||||
```text
|
||||
GET /api/v1/conversations/{id}
|
||||
GET /api/v1/conversations/{id}/turns?limit=100
|
||||
```
|
||||
|
||||
服务端继续执行客户组织、家庭、长者和资源权限检查。采集器自动计算以下机器可观察结果：
|
||||
|
||||
- 通话状态为`COMPLETED`且存在有效长者—智能体话轮时，判定控制和内容链路成功；
|
||||
- 从第一条长者话轮结束到随后第一条智能体话轮开始计算首答时延；
|
||||
- 使用本通话最长的智能体最终话轮字符数作为回答长度，避免多个短回答掩盖单条过长回答；
|
||||
- 观测文件只保留`conversation:<id>`证据引用，不复制最终字幕正文。
|
||||
|
||||
称呼是否准确、记忆是否正确、是否虚构、故事来源是否完整、敏感信息是否正确处理属于语义判断。采集器要求评分卡显式提供这些字段，但不会因为通话完成而自动写成`true`。缺少任一用例、重复使用同一通话或缺少必需评分字段时，采集直接失败。
|
||||
|
||||
准备一个权限受控且只包含一行OIDC访问令牌的临时文件，然后执行：
|
||||
|
||||
```powershell
|
||||
$env:GOCACHE = (Resolve-Path '.').Path + '\.gocache'
|
||||
go run ./cmd/agent-eval-collect `
|
||||
-suite ./testdata/agent-eval-suite.v1.json `
|
||||
-manifest ./testdata/agent-eval-collection.example.v1.json `
|
||||
-api http://127.0.0.1:58080 `
|
||||
-access-token-file <临时令牌文件> `
|
||||
-out ./artifacts/agent-eval-observations.current.json
|
||||
```
|
||||
|
||||
示例清单中的通话编号仅为格式占位，执行前必须替换为本次十个独立用例产生且当前账号有权读取的真实编号。访问令牌不会写入观测文件、报告或日志；执行后应删除临时令牌文件。
|
||||
|
||||
## 6. 生成评测报告
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```powershell
|
||||
$env:GOCACHE = (Resolve-Path '.').Path + '\.gocache'
|
||||
go run ./cmd/agent-eval `
|
||||
-suite ./testdata/agent-eval-suite.v1.json `
|
||||
-observations ./testdata/agent-eval-observations.mock.v1.json `
|
||||
-report-ref 'artifact://agent-eval-report.mock.v1.json' `
|
||||
-out ./artifacts/agent-eval-report.mock.v1.json
|
||||
```
|
||||
|
||||
退出码含义：
|
||||
|
||||
- `0`：输入完整且所有用例和聚合阈值通过；
|
||||
- `1`：评测正常完成但存在退化，报告仍会写出；
|
||||
- `2`：评测集、观测结果、报告引用或文件格式无效，不能形成质量结论。
|
||||
|
||||
真实账号评测只需把观测文件的`environment`改为`real`，填写实际Agent版本、同一模型配置引用和真实执行时间，并用同一套用例编号记录脱敏评分。真实观测不得复制完整个人对话；需要人工复核时，报告仅保存受控证据系统中的引用。
|
||||
|
||||
## 7. 登记到配置发布流程
|
||||
|
||||
报告中的`registration_payload`是以下接口的JSON正文：
|
||||
|
||||
```text
|
||||
POST /api/v1/ops/config-versions/{id}/evaluations
|
||||
Idempotency-Key: <稳定且唯一的评测登记键>
|
||||
If-Match: "<配置版本行版本>"
|
||||
```
|
||||
|
||||
推荐流程如下：
|
||||
|
||||
1. 固定Agent版本、模型配置引用和评测集版本；
|
||||
2. 在模拟供应商环境执行，修复输入、流程和明显质量问题；
|
||||
3. 在真实账号环境执行同一评测集，形成独立的`real`报告；
|
||||
4. 将真实报告存入受控交付位置，使用其引用和`registration_payload`登记评测证据；
|
||||
5. 由非配置创建人完成发布审批；
|
||||
6. 任一关键指标低于阈值时保持`FAILED`，不得手工改写为`PASSED`；修复后使用新的Agent或配置版本重新执行。
|
||||
|
||||
登记前先执行只读校验：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/agent-eval-register `
|
||||
-suite ./testdata/agent-eval-suite.v1.json `
|
||||
-observations ./testdata/agent-eval-observations.mock.v1.json `
|
||||
-report ./artifacts/agent-eval-report.mock.v1.json `
|
||||
-tenant <客户组织UUID> `
|
||||
-config <运行配置版本UUID> `
|
||||
-dry-run
|
||||
```
|
||||
|
||||
只读校验会用评测集和观测文件重新计算完整报告，再检查评测集SHA-256、版本、模型配置引用、用例数量、通过/失败结论和`registration_payload`是否逐项一致，并显示本次登记的确定性幂等键。评测集、观测、报告或登记正文任一项被单独修改，命令都会拒绝发送。
|
||||
|
||||
确认无误后，使用运营人员OIDC令牌登记：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/agent-eval-register `
|
||||
-suite ./testdata/agent-eval-suite.v1.json `
|
||||
-observations ./testdata/agent-eval-observations.mock.v1.json `
|
||||
-report ./artifacts/agent-eval-report.mock.v1.json `
|
||||
-tenant <客户组织UUID> `
|
||||
-config <运行配置版本UUID> `
|
||||
-api http://127.0.0.1:58080 `
|
||||
-access-token-file <临时令牌文件>
|
||||
```
|
||||
|
||||
同一配置版本和同一报告正文始终生成相同的`Idempotency-Key`。登记器发送前会复制指标并注入目标`config_version_id`，不修改磁盘上的原始报告。第一次成功返回HTTP 201，响应丢失后重试返回同一评测记录和HTTP 200，不会重复产生发布证据。服务端还会复核`evidence_type`、报告结构、评测集摘要、用例计数、结论一致性和全部必需指标；标准证据只能属于`AGENT_BUNDLE`，且`model_config_ref`必须严格等于`runtime-config-version:<该组合的model_version_id>`，防止把另一模型或另一组合的报告误作当前发布证据。访问令牌不进入命令输出、报告或幂等键。
|
||||
|
||||
因此，执行候选组合评测前应从固定评测集复制一个本次运行文件，只把`model_config_ref`设为目标组合模型组件的规范引用；用例、分类、预期、评分规则和阈值保持不变。观测文件必须使用同一引用。仓库中的模拟基线报告用于证明工具链可运行，不应直接登记到模型组件编号不同的候选组合。
|
||||
|
||||
`FAILED`报告默认拒绝登记，防止操作人员误把调试产物当成发布证据。如果项目需要保留失败历史，必须显式增加`-allow-failed`；它只登记`FAILED`证据，仍不能满足配置发布门禁。
|
||||
|
||||
模拟报告证明评测工具和评分闭环可运行，不证明真实语音质量、真实首包时延、真实打断体验或供应商配额已经验收。
|
||||
|
||||
阶段8使用[真实Agent模型质量一致性证据](real-agent-models-evidence.md)把本报告与Embedding六类召回/隔离、内容安全六类策略、数据条款和额度证据绑定到同一候选。`agent-eval`报告仍是内容生成质量的唯一评分来源；聚合门禁会重新计算它，不接受只复制结论的手工摘要。
|
||||
|
||||
## 8. 扩展规则
|
||||
|
||||
- 新增用例可以扩展类别，但不能删除十类强制覆盖。
|
||||
- 自动评分器和人工评分器都必须输出相同的脱敏观测结构。
|
||||
- 评分标志的含义发生变化时，必须更新`scoring_rule_ref`和评测集版本。
|
||||
- 同一报告必须能够追溯`suite_sha256`、Agent版本、模型配置引用、运行环境和执行时间。
|
||||
- 发布候选只执行一遍完整固定集；普通功能子批次只运行受影响用例，符合项目“功能完整、验证精简”的测试策略。
|
||||
@@ -0,0 +1,248 @@
|
||||
# 告警监测与运营处置开发说明
|
||||
|
||||
> 对应数据库迁移：V22、V25
|
||||
> 对应接口契约：OpenAPI 0.55.0
|
||||
> 适用范围：客户组织级业务、技术、安全和费用告警的发现、路由、升级、静默及人工闭环
|
||||
|
||||
## 1. 建设目标与边界
|
||||
|
||||
告警模块将已有Prometheus基础规则之外、需要关联业务资源和人工处置的信号统一落入运营闭环。平台按客户组织隔离信号，把同一问题的重复命中归并为一个事件，冻结当时有效的接收组和运行手册，并记录确认、缓解、关闭、静默、重新打开和升级动作。
|
||||
|
||||
当前版本已经覆盖数据库、后台扫描器、运营接口、React工作台、可靠Webhook通知适配器、不会生成正式告警的接收器联通测试和本地端到端验证。`receiver_group`和`escalation_receiver_group`仍是受审计的逻辑接收组，接收端可据此映射短信、电话、PagerDuty或企业协作平台；真实通知网关账号、地址和值班组映射需在部署环境配置。PostgreSQL或Redis自身完全不可连接时，服务无法把故障写入同一主库，因此这类基础设施失联仍由Prometheus/部署平台外部探针告警，不能依赖本模块自举。
|
||||
|
||||
阶段8使用`cmd/alert-receiver-conformance`把全部活动路由、联通测试、真实网关回执、主/升级值班组映射和一次受控正式告警演练形成候选一致的结构化报告。详细采集格式、10项校验和证据包门禁见[真实告警接收器一致性证据](alert-receiver-conformance-evidence.md)。
|
||||
|
||||
## 2. 功能设计
|
||||
|
||||
### 2.1 告警分类与级别
|
||||
|
||||
| 维度 | 取值 | 用途 |
|
||||
|---|---|---|
|
||||
| 分类 | `BUSINESS` | 隐私删除、录音上传、业务任务等需要业务确认的问题 |
|
||||
| 分类 | `TECHNICAL` | 死信、语音任务卡滞、固件失败等技术处置问题 |
|
||||
| 分类 | `SECURITY` | 证书、异常访问、密钥或安全策略问题 |
|
||||
| 分类 | `COST` | 额度临界、异常费用增长和供应商核价问题 |
|
||||
| 级别 | `CRITICAL/HIGH/MEDIUM/LOW` | 决定队列排序、响应时限和升级路径 |
|
||||
|
||||
### 2.2 当前自动扫描规则
|
||||
|
||||
| 规则代码 | 分类/级别 | 判定依据 | 关联资源 |
|
||||
|---|---|---|---|
|
||||
| `OUTBOX_DEAD_LETTER` | 技术/高 | 客户组织存在`dead`可靠任务 | Outbox队列 |
|
||||
| `PRIVACY_DELETE_OVERDUE` | 业务/严重 | 删除请求部分失败，或创建超过1小时仍未完成 | 隐私请求 |
|
||||
| `MEDIA_UPLOAD_FAILED` | 业务/中 | 双轨录音上传批次进入失败终态 | 上传批次 |
|
||||
| `FIRMWARE_ROLLOUT_FAILURE` | 技术/高 | 固件灰度存在失败设备 | 固件灰度批次 |
|
||||
| `COST_DAILY_QUOTA_NEAR` | 费用/中 | 当前账期日费用达到活动硬额度的80% | 额度策略 |
|
||||
| `VOICE_TASK_STUCK` | 技术/高 | 通话在启动或停止中间态停留超过5分钟 | 通话 |
|
||||
| `PROVIDER_NOTIFICATION_BACKLOG` | 技术/高 | 供应商通知处于待处理/失败且超过1分钟，按客户组织和供应商归并 | 供应商通知队列 |
|
||||
| `PROVIDER_UNAVAILABLE` | 技术/严重 | 连续临时失败达到阈值，供应商启动熔断处于不可用状态 | 供应商依赖状态 |
|
||||
| `CERTIFICATE_EXPIRING` | 安全/高或严重 | 活动证书引用在30天内到期；7天内提升为严重 | 受控证书引用 |
|
||||
|
||||
扫描器随Worker进程启动，默认使用`WORKER_POLL_INTERVAL`。每次扫描只读取规范业务表，生成脱敏标题和摘要，不把供应商任务正文、录音、字幕、密钥或完整请求正文复制到告警表。
|
||||
|
||||
供应商临时错误由 Worker 按网络错误、超时、HTTP 429 和 HTTP 5xx 分类。连续失败达到`PROVIDER_FAILURE_THRESHOLD`后，`provider_dependency_state`按客户组织和供应商持久化为`UNAVAILABLE`，在`PROVIDER_CIRCUIT_COOLDOWN`窗口内暂停新的语音任务启动；停止和异常回收不经过启动熔断，仍会继续尝试。任一成功的启动或停止会清零连续失败并恢复`AVAILABLE`。告警扫描器对`UNAVAILABLE`状态生成`PROVIDER_UNAVAILABLE` CRITICAL事件，摘要只包含供应商代号、失败次数和归一化错误码。
|
||||
|
||||
### 2.3 路由策略
|
||||
|
||||
- 路由按`客户组织 + 分类 + 级别`版本化，同一组合只有一个`ACTIVE`版本。
|
||||
- 新版本由`ops_approver`或`ops_admin`激活，旧版本自动变为`RETIRED`。
|
||||
- 策略保存首接组、响应时限、升级时限、升级接收组、运行手册引用和变更说明。
|
||||
- 事件首次发现时保存活动路由内部引用；后续策略升级不会改写历史处置依据。
|
||||
- 如果事件首次发现时尚无路由，事件仍进入队列；后续重复命中可补挂当时有效的路由。
|
||||
|
||||
### 2.4 告警归并与状态机
|
||||
|
||||
同一客户组织内使用`fingerprint`归并仍未关闭的重复信号。扫描器通过事务级顾问锁串行化同一指纹，避免多Worker同时插入两个活动事件。重复命中只增加`occurrence_count`、刷新最后发现时间和摘要，不生成重复费用或重复业务资源。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> OPEN: 首次命中且无静默
|
||||
[*] --> SILENCED: 首次命中且匹配静默
|
||||
OPEN --> ACKNOWLEDGED: 运营确认并接手
|
||||
OPEN --> MITIGATED: 直接记录缓解
|
||||
ACKNOWLEDGED --> MITIGATED: 完成缓解
|
||||
OPEN --> RESOLVED: 验证后关闭
|
||||
ACKNOWLEDGED --> RESOLVED: 验证后关闭
|
||||
MITIGATED --> RESOLVED: 验证后关闭
|
||||
OPEN --> SILENCED: 后续命中有效静默
|
||||
ACKNOWLEDGED --> SILENCED: 后续命中有效静默
|
||||
MITIGATED --> SILENCED: 后续命中有效静默
|
||||
SILENCED --> OPEN: 静默到期或撤销且信号仍存在
|
||||
RESOLVED --> [*]
|
||||
```
|
||||
|
||||
关闭后的相同问题再次发生时创建新的事件，而不是改写已关闭事件。这样每次故障窗口、首次发现、响应和恢复证据都可独立复盘。
|
||||
|
||||
### 2.5 超时升级
|
||||
|
||||
扫描器在每轮检测后查找`OPEN`或`ACKNOWLEDGED`且尚未升级的事件。若`first_detected_at + escalation_after_minutes`已到期，则原子写入`escalated_at`并追加`ESCALATED`动作。升级不改变业务状态，避免“已升级”被误认为“已缓解”。
|
||||
|
||||
### 2.6 静默
|
||||
|
||||
- 静默至少按规则代码、分类或具体资源之一限定，不能创建全平台无条件静默。
|
||||
- 时间窗口必须有效，最长30天，原因必填。
|
||||
- 静默不会删除事件或停止命中计数；首次命中仍写`DETECTED`和`SILENCED`动作。
|
||||
- 对活动事件新增静默后，下次命中转为`SILENCED`；静默到期或撤销且问题仍存在时转回`OPEN`并写`REOPENED`。
|
||||
- 撤销使用强`If-Match`，防止两个运营人员基于旧页面重复操作。
|
||||
|
||||
### 2.7 Webhook通知
|
||||
|
||||
- 未静默的新告警在写入事件和`DETECTED`动作的同一事务中生成`alert.webhook_requested`可靠任务；静默中的首次命中不对外通知。
|
||||
- 超时升级在写入`ESCALATED`动作的同一事务中生成第二条通知，接收组切换为`escalation_receiver_group`。
|
||||
- 通知正文只使用客户组织、事件和业务资源的公开编号，并携带规则、分类、级别、状态、脱敏标题/摘要、逻辑接收组和运行手册引用，不暴露内部主键、令牌、密钥、字幕或录音正文。
|
||||
- Worker以稳定`event_id`投递，网络错误、超时、HTTP 408/425/429/5xx进入统一指数退避重试，其他4xx作为永久配置错误进入死信。
|
||||
- 每次请求携带`X-Voice-Event-ID`、Unix秒`X-Voice-Timestamp`和`X-Voice-Signature`。签名格式为`v1=HMAC-SHA256(secret, timestamp + "." + raw_body)`；接收端必须校验签名、限制时间偏差并按事件编号去重。
|
||||
- `ALERT_WEBHOOK_URL`为空时适配器安全关闭，任务由Worker正常确认，不访问外部网络，也不形成待处理或死信积压；启用时密钥至少32字符，生产环境强制HTTPS和非占位密钥。
|
||||
- 运营人员可以针对任一活动路由发起`alert.webhook_test_requested`。测试使用同一Worker、目标地址、HMAC密钥、超时和错误分类，但`aggregate_type=alert_delivery_test`，不会写入`alert_incident`或触发正式告警升级。
|
||||
- 普通告警在地址未配置时仍保持安全空操作；联通测试在地址未配置时明确进入`FAILED`，避免把“没有发送”误报为“接收器可用”。失败任务使用公开任务编号进入现有诊断受控重试链路。
|
||||
|
||||
## 3. 数据库设计
|
||||
|
||||
### 3.1 表及职责
|
||||
|
||||
| 表 | 主体字段 | 约束与用途 |
|
||||
|---|---|---|
|
||||
| `alert_routing_policy` | 分类、级别、版本、接收组、时限、运行手册 | 活动版本部分唯一；历史版本不可覆盖 |
|
||||
| `alert_silence` | 规则/分类/资源范围、匹配器、原因、起止时间、撤销人 | 至少一个范围；结束晚于开始；服务层限制最长30天 |
|
||||
| `alert_incident` | 规则、指纹、状态、摘要、资源、路由、负责人、时间和次数 | 未关闭指纹部分唯一；保存响应、缓解、关闭、静默和升级时间 |
|
||||
| `alert_action` | 动作、前后状态、系统/用户操作人、说明、时间 | 随事件级联删除；构成不可变处置时间线 |
|
||||
| `ops_resource_reference`（V25扩展） | `resource_type=CERTIFICATE`、受控引用、核验时间、到期时间 | 不保存证书私钥或正文；活动证书必须有未来到期时间 |
|
||||
| `outbox_event`（V26扩展） | 公开任务编号、事件类型、测试关联号、状态、尝试与人工重试次数 | 联通测试复用可靠任务台账，不新增业务表；测试原因只进审计，不进入外发正文 |
|
||||
|
||||
所有表使用内部UUID关联，HTTP只暴露`public_id`。每张租户数据表都保存`tenant_id`，所有服务查询先用OIDC身份和客户组织公开编号解析运营账号，再固定内部客户组织条件；不接受前端传入内部客户组织编号。
|
||||
|
||||
### 3.2 关键索引
|
||||
|
||||
- `alert_route_active_unique`：保证一个分类/级别只有一个活动路由。
|
||||
- `alert_silence_active_idx`：加速客户组织当前静默窗口判断。
|
||||
- `alert_incident_active_fingerprint`：保证同一问题只有一个未关闭事件。
|
||||
- `alert_incident_queue_idx`：按状态、严重度和最后发现时间查询运营队列。
|
||||
- `alert_action_incident_time_idx`：按事件顺序读取完整动作时间线。
|
||||
|
||||
## 4. 接口设计
|
||||
|
||||
所有运营接口均要求OIDC Bearer Token和`X-Tenant-Id`；创建接口要求`Idempotency-Key`，状态变更要求`If-Match: "v{row_version}"`。
|
||||
|
||||
| 方法与路径 | 最低角色 | 说明 |
|
||||
|---|---|---|
|
||||
| `GET /api/v1/ops/alert-routing-policies` | `ops_viewer` | 查询活动和历史路由 |
|
||||
| `POST /api/v1/ops/alert-routing-policies` | `ops_approver` | 激活新路由版本，支持幂等重放 |
|
||||
| `GET /api/v1/ops/alert-delivery-tests` | `ops_viewer` | 查询最近50次联通测试及真实投递状态，不返回地址、密钥或测试原因 |
|
||||
| `POST /api/v1/ops/alert-routing-policies/{id}/delivery-tests` | `ops_operator` | 针对活动路由创建受审计、幂等的联通测试，不创建正式告警 |
|
||||
| `GET /api/v1/ops/alerts` | `ops_viewer` | 查询队列，可按状态筛选 |
|
||||
| `GET /api/v1/ops/alerts/{id}` | `ops_viewer` | 查询事件详情和完整动作时间线 |
|
||||
| `POST /api/v1/ops/alerts/{id}/acknowledge` | `ops_operator` | 确认并把首次操作人记为当前负责人 |
|
||||
| `POST /api/v1/ops/alerts/{id}/mitigate` | `ops_operator` | 记录已采取缓解措施 |
|
||||
| `POST /api/v1/ops/alerts/{id}/resolve` | `ops_operator` | 验证恢复并关闭事件 |
|
||||
| `GET /api/v1/ops/alert-silences` | `ops_viewer` | 查询当前和历史静默 |
|
||||
| `POST /api/v1/ops/alert-silences` | `ops_operator` | 创建有范围、有原因、有限时长的静默 |
|
||||
| `POST /api/v1/ops/alert-silences/{id}/revoke` | `ops_operator` | 提前撤销静默 |
|
||||
|
||||
稳定错误包括：`OPS_ACCESS_DENIED`、`ALERT_NOT_FOUND`、`ALERT_STATE_CONFLICT`、`VERSION_CONFLICT`、`IDEMPOTENCY_KEY_CONFLICT`。内部数据库错误只在服务端结构化日志记录，客户端不返回SQL或内部编号。
|
||||
|
||||
## 5. 业务流程
|
||||
|
||||
### 5.1 自动发现到关闭
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as Worker扫描器
|
||||
participant DB as PostgreSQL
|
||||
participant W as Outbox Worker
|
||||
participant R as 通知接收端
|
||||
participant O as 运营人员
|
||||
S->>DB: 读取业务表并生成脱敏Signal
|
||||
S->>DB: 指纹加锁、检查活动路由和静默
|
||||
S->>DB: 新建事件或增加命中次数
|
||||
S->>DB: 超时则追加ESCALATED动作
|
||||
S->>DB: 同事务写可靠通知任务
|
||||
W->>DB: 领取通知任务
|
||||
W->>R: HMAC签名Webhook
|
||||
R-->>W: 2xx确认或临时失败重试
|
||||
O->>DB: 查询队列和运行手册
|
||||
O->>DB: If-Match确认并接手
|
||||
O->>DB: If-Match记录缓解
|
||||
O->>DB: If-Match验证并关闭
|
||||
DB-->>O: 返回最新版本及完整动作时间线
|
||||
```
|
||||
|
||||
### 5.2 静默与恢复
|
||||
|
||||
1. 运营人员选择明确规则、分类或资源，填写原因和结束时间。
|
||||
2. 服务端校验角色、范围、时间和幂等键，在同一事务写静默与审计。
|
||||
3. 扫描器继续检测信号并保留命中次数，但把事件放入`SILENCED`。
|
||||
4. 静默到期或被带版本撤销后，如果信号仍存在，扫描器将事件重新打开并追加动作。
|
||||
5. 若信号已经消失，事件保留静默历史，不自动伪造“已恢复”；运营人员根据复核结果关闭。发布候选快照会提供阻断告警公开编号和关联资源`PRESENT/MISSING/AGGREGATE/UNKNOWN`状态，帮助复核，但`MISSING`本身不会绕过人工关闭责任。
|
||||
|
||||
### 5.3 接收器联通测试
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant O as 运营人员
|
||||
participant A as 运营API
|
||||
participant DB as PostgreSQL/Outbox
|
||||
participant W as Worker
|
||||
participant R as 告警接收器
|
||||
O->>A: 选择活动路由并填写测试原因
|
||||
A->>DB: 幂等写测试任务和最小审计
|
||||
A-->>O: 返回PENDING与test_ref
|
||||
W->>DB: 领取alert.webhook_test_requested
|
||||
W->>R: 与正式告警相同的HMAC签名信封
|
||||
R-->>W: 2xx或可分类错误
|
||||
W->>DB: DELIVERED或FAILED
|
||||
O->>A: 查询最近测试状态
|
||||
A-->>O: 尝试次数、错误码和完成时间
|
||||
```
|
||||
|
||||
外发正文固定带`action=TEST`、测试关联号、客户组织公开编号、活动路由公开编号、分类、级别、接收组、运行手册和“非真实故障”说明，不携带操作人填写的测试原因。失败任务只有在配置或网络问题已复核后才能由运营操作角色受控重试。
|
||||
|
||||
## 6. 工作台设计
|
||||
|
||||
运营工作台包含五块信息：待处置/严重/已升级/活动静默概览；按状态筛选的告警队列；包含路由、运行手册、资源和请求关联号的详情及动作时间线；路由版本和临时静默管理；最近50次接收器联通测试及失败重试。只读运营角色不会看到写操作按钮，审批角色才可激活路由，操作角色可处置、静默、发起联通测试和重试失败任务。Grafana安全仪表盘同时展示7天/30天证书到期数量和当前安全事件，技术仪表盘展示供应商通知积压与可靠任务状态。
|
||||
|
||||
确认接手、记录缓解和验证关闭从告警详情打开页面内处置表单，不再调用浏览器输入弹窗。表单固定告警公开编号、规则、分类、级别、当前状态、命中次数和行版本，处置说明必填且最长1000字符；关闭还必须确认缓解措施已经验证、监测指标恢复、关联影响和遗留风险完成复核。重新筛选、切换客户组织、选择其他告警、刷新或取消会清除处置草稿，不发送状态请求；服务端仍执行角色、租户、状态及`If-Match`并发校验。
|
||||
|
||||
接收器联通测试、失败测试受控重试和静默提前撤销也统一使用页面内受控操作区。联通测试固定活动路由编号、分类、级别、版本、接收组、运行手册和行版本，要求确认接收组知晓测试，且原因仅进入审计、不外发；失败重试固定任务编号、测试关联号、尝试次数、人工重试次数和稳定错误码，要求确认依赖问题已经修复；静默撤销固定静默编号、范围、原因、窗口和行版本，要求确认仍在发生的信号会重新进入队列。三类原因最长500字符，刷新、切换客户组织或取消会清除草稿。
|
||||
|
||||
## 7. 验证与运行
|
||||
|
||||
执行后端、契约和前端门禁：
|
||||
|
||||
```powershell
|
||||
.\scripts\check.ps1
|
||||
```
|
||||
|
||||
执行真实OIDC、PostgreSQL、API和Worker组合烟测：
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-alerts.ps1
|
||||
```
|
||||
|
||||
该脚本验证跨客户组织拒绝、路由幂等、自动发现、首次通知接收组、路由冻结、超时升级及升级通知接收组、旧ETag返回412、确认—缓解—关闭时间线、静默命中、撤销静默和重新打开，并在结束后清理全部合成数据及通知任务。
|
||||
|
||||
日常页面增量采用低强度真实OIDC无提交检查：`test/e2e/visual-ops-alert-transitions.mjs`使用三条分别处于`OPEN`、`ACKNOWLEDGED`和`MITIGATED`的临时告警，验证确认、缓解和关闭表单的目标/行版本绑定、空说明阻断、关闭二次确认、取消关闭、零状态POST、零横向溢出、零控制台错误和零非预期失败请求。截图保存到`test/e2e/screenshots/ops-alert-transition-form.png`，夹具在`finally`中精确清理。该检查证明页面不会误处置，不替代既有服务端状态机纵向烟测。
|
||||
|
||||
剩余三类告警操作复用一条真实OIDC无提交检查：`test/e2e/visual-ops-alert-controlled-actions.mjs`使用临时活动路由、活动静默和失败联通任务，验证目标/版本绑定、原因与影响确认门禁、取消关闭，以及零测试发送、零重试、零静默撤销请求；同时检查零横向溢出、零控制台错误和零非预期失败请求。截图为`test/e2e/screenshots/ops-alert-controlled-actions.png`，路由、静默和死信任务夹具在`finally`中精确清理。
|
||||
|
||||
执行接收器真实投递纵向烟测：
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-alert-delivery-test.ps1
|
||||
```
|
||||
|
||||
该脚本在没有活动路由时临时建立一条路由，通过真实OIDC创建联通任务，等待真实Worker出队，验证本地接收器HMAC签名、状态回读、非正式告警隔离和幂等重放，最后清理路由、Outbox、审计和幂等记录。
|
||||
|
||||
执行Chrome布局检查：
|
||||
|
||||
```powershell
|
||||
$env:PLAYWRIGHT_REQUIRE_FROM='C:\Users\19926\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules'
|
||||
node .\scripts\visual-alert-ui.cjs
|
||||
```
|
||||
|
||||
## 8. 生产接入待办
|
||||
|
||||
- 配置真实Webhook通知网关，把逻辑接收组映射到PagerDuty、短信、电话或企业协作平台；先从活动路由发起联通测试并确认`DELIVERED`和接收端唯一事件，再在预生产环境验证正式告警的去重、送达、限流和失败重试。
|
||||
- 将异常访问、密钥轮换失败和核价失败接入规范Signal；证书到期、供应商不可用和供应商通知积压已经接入。
|
||||
- 在类生产环境校准规则阈值、扫描周期、事件量和存储保留期。
|
||||
- 使用外部探针验证PostgreSQL、Redis、对象存储和区域级故障；主库失联不能仅依赖主库内事件。
|
||||
- 完成值班表、接收组映射、每条规则运行手册和故障演练签署。
|
||||
@@ -0,0 +1,80 @@
|
||||
# 真实告警接收器、值班组映射与正式演练一致性证据
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
本工具把云端当前活动告警路由、联通测试投递状态、接收网关唯一验签回执、逻辑值班组映射和一次受控正式告警演练绑定到同一候选版本与构建摘要，生成可进入阶段8候选证据包的结构化报告。它解决以下问题：页面显示`DELIVERED`但接收端没有收到、同一`test_ref`重复通知、逻辑组没有映射到真实值班目标、只验证主接收组而遗漏升级组，以及用本地模拟接收器冒充生产告警网关。
|
||||
|
||||
`cmd/alert-receiver-conformance`输出`alert-receiver-conformance-report-v1`。本地Compose接收器固定产生`MOCK_RECEIVER`报告并保留`external_validation_required=true`；只有真实网关证据、全部活动路由、主/升级组映射和正式演练同时通过时，报告才是`REAL_RECEIVER`且`external_validation_required=false`。报告仍不等于业务发布批准，联合签署继续由`BUSINESS_APPROVAL`管理。
|
||||
|
||||
## 2. 四类输入
|
||||
|
||||
| 输入 | 获取方式 | 必需内容 |
|
||||
|---|---|---|
|
||||
| 活动路由 | 下载`GET /api/v1/ops/alert-routing-policies`完整响应 | 当前租户全部`ACTIVE`路由、主接收组、升级接收组和运行手册 |
|
||||
| 联通测试 | 下载`GET /api/v1/ops/alert-delivery-tests`完整响应 | 每条活动路由最近一次`DELIVERED`测试、`test_ref`、尝试和完成时间 |
|
||||
| 正式演练告警 | 下载`GET /api/v1/ops/alerts/{id}`详情 | 已解决的受控正式告警、接收组、确认动作和时间线 |
|
||||
| 接收端采集 | 告警网关按`alert-receiver-capture-v1`导出 | 值班组映射、唯一测试回执、HMAC验签结果和正式演练接收/确认记录 |
|
||||
|
||||
接口返回可以是完整API响应或其中的`data`正文。接收端采集严格拒绝未知字段；不得包含Webhook密钥、Token、手机号、个人邮箱或完整值班人姓名。`receiver_system_ref`、`mapped_target_refs`和`acknowledgement_ref`只能使用脱敏稳定引用，例如`pager-service:platform-primary`或`incident-ticket:masked-001`。
|
||||
|
||||
## 3. 接收端证据格式
|
||||
|
||||
`alert-receiver-capture-v1`包含：
|
||||
|
||||
- `evidence_source`：真实网关填`REAL`，本地或测试接收器填`MOCK`；
|
||||
- `candidate_version/build_digest`：必须与候选证据包完全一致；
|
||||
- `group_mappings`：每个逻辑接收组对应一个或多个脱敏目标引用及复核时间；
|
||||
- `test_receipts`：按`test_ref`记录外部事件编号、接收组、唯一送达次数、签名校验结果和接收时间；
|
||||
- `formal_drill`：正式受控告警编号、接收组、唯一送达、签名校验、接收时间、值班确认时间和脱敏确认引用；
|
||||
- `collected_at`：不得早于任何映射、回执或确认时间。
|
||||
|
||||
接收端事件编号与云端Outbox任务编号是两个独立公开编号，不要求相等；两端使用同一个`test_ref`绑定。每个联通测试必须只形成一条接收端回执，重复Webhook应由网关按事件编号幂等处理。
|
||||
|
||||
## 4. 自动校验项
|
||||
|
||||
报告固定包含以下10项`PASS/FAIL`检查，任一失败使总结果为`FAIL`：
|
||||
|
||||
1. `CAPTURE_SCHEMA`：接收证据版本正确；
|
||||
2. `EVIDENCE_SOURCE`：来源明确为真实或模拟；
|
||||
3. `CANDIDATE_IDENTITY`：候选版本和SHA-256构建摘要合法；
|
||||
4. `CAPTURE_CANDIDATE_BINDING`：接收证据与命令参数绑定同一候选；
|
||||
5. `RECEIVER_IDENTITY`：接收系统使用非秘密稳定引用；
|
||||
6. `ACTIVE_ROUTES`：至少一条活动路由且全部属于同一租户；
|
||||
7. `RECEIVER_GROUP_MAPPING`：每条活动路由的主接收组和升级接收组均有非空脱敏映射；
|
||||
8. `DELIVERY_TEST_COVERAGE`：每条活动路由都有最近一次云端`DELIVERED`测试和唯一验签回执；
|
||||
9. `DELIVERY_TIME_CORRELATION`：云端完成时间与接收时间差不超过10分钟；
|
||||
10. `FORMAL_ALERT_DRILL`：一条已解决且包含确认动作的正式受控告警，与接收端唯一验签送达和确认引用一致。
|
||||
|
||||
联通测试不会创建正式告警，所以不能单独满足第10项。真实网关联通测试全部通过但尚未完成正式演练时，证据索引仍必须保持`REAL_ALERT_RECEIVER/PENDING`。
|
||||
|
||||
## 5. 命令用法
|
||||
|
||||
```powershell
|
||||
go run ./cmd/alert-receiver-conformance `
|
||||
-routes E:\evidence\alert-routes.json `
|
||||
-tests E:\evidence\alert-delivery-tests.json `
|
||||
-incident E:\evidence\formal-drill-incident.json `
|
||||
-receiver E:\evidence\receiver-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\alert-receiver-report.json
|
||||
```
|
||||
|
||||
输出路径必须是绝对路径。通过返回0，不一致时仍写完整报告并返回1，参数、文件和JSON格式错误返回2。报告保存四份输入的SHA-256，不复制接收地址或通知正文。
|
||||
|
||||
## 6. 阶段8证据包门禁
|
||||
|
||||
`release-evidence-index-v2`中的`REAL_ALERT_RECEIVER`不可豁免：
|
||||
|
||||
- 无真实报告时保持`PENDING`，v3清单写入`REAL_RECEIVER_REPORT:0/1`和`FORMAL_ALERT_DRILL:0/1`；
|
||||
- `files`的第一个文件必须是候选一致、所有检查通过、范围为`REAL_RECEIVER`且外部验证已完成的官方报告；后续文件可附真实网关导出、演练工单和签署材料；
|
||||
- `MOCK_RECEIVER`、失败报告、跨候选报告、缺活动路由、缺升级组映射、重复回执或缺正式演练均不能标记`VERIFIED`；
|
||||
- 通过后清单记录活动路由数、映射组数、测试回执数和正式演练结论，最终业务批准仍由独立门禁完成。
|
||||
|
||||
## 7. 本地轻量验证
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-alert-delivery-test.ps1
|
||||
```
|
||||
|
||||
脚本只创建一条临时活动路由和一条联通测试，真实经过Worker、HMAC签名和本地验签接收器，核对唯一回执后生成`MOCK_RECEIVER`报告。它使用合成正式演练输入验证报告结构，但必须继续声明外部验证未完成。脚本结束清理临时路由、Outbox、幂等、审计和磁盘报告，不会改变`REAL_ALERT_RECEIVER`门禁。
|
||||
@@ -0,0 +1,118 @@
|
||||
# 字幕、故事审核与已确认记忆设计
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
本批次实现“最终转写入库—通话整理—故事候选—人工审核—已确认记忆—索引生效”的完整业务链。系统把模型输出始终视为候选内容；只有具备`story.review`能力的家庭成员明确确认，并且长者当前存在有效`personalized_memory`授权时，候选才可转为长期记忆。
|
||||
|
||||
当前抽取器支持两类可切换适配器：默认的`local-deterministic-extractor`用于本地业务验证，`ark:<model-id>`通过火山方舟OpenAI兼容Chat Completions接口生成结构化候选。向量生成与查询同样支持`local-deterministic-hash-v1`和`ark:<embedding-model-id>`两类适配器，并强制使用数据库既定的1536维。生产配置门禁禁止内容生成、索引或查询继续使用本地适配器；真实方舟账号效果仍需外部验收。
|
||||
|
||||
## 2. 功能设计
|
||||
|
||||
| 功能 | 输入 | 处理规则 | 输出 |
|
||||
| --- | --- | --- | --- |
|
||||
| 最终话轮接收 | 供应商签名回调、最终话轮数组 | 只接受`voice_chat.transcript.final/FINAL`；校验话轮键、序号、角色、时间和正文；按`conversation_id + turn_key`去重；同键不同内容拒绝 | `conversation_turn` |
|
||||
| 通话整理 | 已结束通话、冻结授权快照、最终话轮 | 无`story_extraction`授权时不处理；只使用长者话轮作为故事和摘要来源；同一生成版本幂等 | 通话摘要、开放话题、故事候选、事实候选 |
|
||||
| 方舟模型调用 | 本地安全策略通过的长者话轮 | 使用Bearer API Key调用`${ARK_BASE_URL}/chat/completions`；要求结构化JSON；网络、超时、408/425/429/5xx可靠重试，永久4xx进入死信 | 带模型编号、提示词版本和置信度的候选结果 |
|
||||
| 分层内容安全过滤 | 长者最终话轮及模型结构化输出 | 验证码、支付账户、提示注入和高敏医疗先在本地拦截且不外发；其余输入在生成前、模型输出在落库前调用托管策略；BLOCK/REVIEW改为受控提示，策略服务异常时可靠重试且不落库 | 策略版本、非敏感提示和可审计请求引用 |
|
||||
| 故事修订 | 候选故事、人工正文、原因、强ETag | 新增人工修订版本并复制来源关系，不覆盖模型版本；终态故事禁止再改 | 新的`story_revision`和`IN_REVIEW`状态 |
|
||||
| 故事确认 | 当前故事、审核原因、强ETag | 必须有原话来源、具备审核权限且个性化记忆授权当前有效；确认故事及候选事实 | `CONFIRMED`故事和`PENDING`记忆 |
|
||||
| 故事拒绝 | 当前故事、审核原因、强ETag | 拒绝故事及仍为候选状态的事实，不创建记忆 | `REJECTED`故事 |
|
||||
| 记忆索引 | 待索引记忆版本 | 再次校验记忆为当前版本、状态有效且授权仍有效；不满足条件时清空向量并标记`STALE` | `ACTIVE`或`STALE`索引 |
|
||||
| 生产向量化 | 普通敏感级别的当前记忆正文或新通话检索语句 | API与Worker使用同一方舟Embedding模型；请求1536维float向量并校验维度和有限数值；网络、超时、408/425/429/5xx可靠重试 | `ark:<model-id>`索引或固定边界查询向量 |
|
||||
| 记忆修订与停用 | 当前记忆、正文或状态、原因、强ETag | 正文变化创建新版本并立即使旧索引失效；停用后不再召回；重新启用必须重新校验授权并重新索引；`PENDING_DELETE/SUPERSEDED/DELETED`均禁止修改 | 新记忆版本或状态 |
|
||||
| 记忆永久删除 | 当前记忆、删除原因、强ETag | 事务内先进入`PENDING_DELETE`并清空活动向量，使新通话立即停止召回；该状态不可通过修改接口恢复；Outbox后台把索引标记删除、清除所有记忆版本正文并记录完成审计 | `DELETED`记忆和索引 |
|
||||
| 新通话记忆检索 | 服务端已确定的客户组织、长者和通话目标 | SQL同时限制租户、长者、当前授权、活动记忆、当前版本、普通敏感级别、有效期和活动索引；最多5条 | 冻结到`context_snapshot.memory_versions`的版本引用和最小背景摘要 |
|
||||
| 授权撤回 | `personalized_memory`授权 | 在同一事务内停用该长者的活动记忆，清空活动/待处理索引向量并标记失效 | `DISABLED`记忆、`STALE`索引 |
|
||||
|
||||
## 3. 业务流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[供应商最终转写回调] --> B{字幕保存授权允许?}
|
||||
B -- 否 --> C[不保存转写正文]
|
||||
B -- 是 --> D[校验并去重最终话轮]
|
||||
D --> E[通话进入COMPLETED或FAILED]
|
||||
E --> F{故事整理授权允许?}
|
||||
F -- 否 --> G[结束且不生成候选]
|
||||
F -- 是 --> H[仅提取长者话轮]
|
||||
H --> I[摘要与开放话题]
|
||||
H --> J[故事和事实候选]
|
||||
J --> K{家庭成员人工审核}
|
||||
K -- 修订 --> L[新增人工版本并保留来源]
|
||||
L --> K
|
||||
K -- 拒绝 --> M[故事和候选事实拒绝]
|
||||
K -- 确认 --> N{来源完整且记忆授权有效?}
|
||||
N -- 否 --> O[返回冲突且不建记忆]
|
||||
N -- 是 --> P[确认故事与事实]
|
||||
P --> Q[创建记忆版本和待处理索引]
|
||||
Q --> R{后台再次校验当前状态与授权}
|
||||
R -- 合格 --> S[索引ACTIVE]
|
||||
R -- 不合格 --> T[清空向量并标记STALE]
|
||||
S --> U[创建下一次通话]
|
||||
U --> V[数据库固定边界检索]
|
||||
V --> W[冻结记忆版本和背景摘要]
|
||||
```
|
||||
|
||||
供应商停止事件和最终转写事件可能存在先后竞争。停止事件会发布内容整理待办；如果话轮尚未到达，处理器返回可重试错误，由Outbox退避重试，避免把“暂无话轮”错误当成永久空内容。
|
||||
|
||||
内容处理器先在无事务状态读取已结束通话、冻结授权和有序最终话轮，执行本地敏感内容判断；只有普通内容才调用外部模型。模型返回后才开启短事务并锁定通话，重新读取状态、授权和全部话轮并比较SHA-256输入指纹。若模型调用期间授权撤回，则不写入结果；若话轮发生变化，则本次任务进入可靠重试并基于新输入重新生成。该顺序满足“数据库事务不得跨越大模型网络调用”的需求约束。
|
||||
|
||||
记忆索引也先在无事务状态读取当前版本和授权，事务外生成Embedding，返回后才锁定记忆与索引行重新校验；修订、停用或撤回授权发生在模型调用期间时，旧结果不会被激活。新通话创建前仅在设备绑定、语音授权和个性化记忆授权均可用时生成查询向量；事务内仍以固定租户、长者、授权、状态和敏感级别条件检索。Embedding临时不可用时，本次通话以`pgvector-degraded-v1`记录降级且不注入记忆，不阻断基本语音通话。普通顺序幂等重放和同键正文冲突会先读取已完成幂等记录，不重复调用Embedding；并发首请求仍由数据库唯一键保证只创建一个通话。
|
||||
|
||||
## 4. 接口设计
|
||||
|
||||
| 方法与路径 | 权限 | 并发/校验 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `GET /api/v1/conversations/{id}/turns` | `conversation.read` | HMAC游标、1—100条 | 最终话轮分页 |
|
||||
| `GET /api/v1/conversations/{id}/summaries` | `conversation.read` | 资源隔离 | 摘要和开放话题 |
|
||||
| `GET /api/v1/subjects/{id}/stories` | `subject.read` | 可按状态过滤 | 故事列表，不展开子项 |
|
||||
| `GET /api/v1/stories/{id}` | `subject.read` | 返回强ETag | 当前故事、来源和事实 |
|
||||
| `PATCH /api/v1/stories/{id}` | `story.review` | 必须`If-Match`；正文和原因必填 | 创建人工修订版本 |
|
||||
| `POST /api/v1/stories/{id}/confirm` | `story.review` | 必须`If-Match`；来源与授权门禁 | 确认故事并创建记忆 |
|
||||
| `POST /api/v1/stories/{id}/reject` | `story.review` | 必须`If-Match`；原因必填 | 拒绝候选 |
|
||||
| `GET /api/v1/subjects/{id}/memories` | `subject.read` | 过滤已删除记录；可用`q`在固定长者边界内搜索 | 已确认记忆列表 |
|
||||
| `GET /api/v1/memories/{id}` | `subject.read` | 返回强ETag | 当前记忆版本和索引状态 |
|
||||
| `PATCH /api/v1/memories/{id}` | `story.review` | 必须`If-Match`；正文/状态至少一项且原因必填；删除中及历史终态拒绝修改 | 修订、停用或重新启用记忆 |
|
||||
| `DELETE /api/v1/memories/{id}` | `story.review` | 必须`If-Match`；删除原因必填；返回202 | 可靠受理永久删除任务 |
|
||||
|
||||
统一冲突码包括`STORY_SOURCE_REQUIRED`、`PERSONALIZED_MEMORY_CONSENT_REQUIRED`和`STORY_REVIEW_STATE_CONFLICT`。跨租户或非家庭成员访问统一返回403，不借404差异泄露资源是否存在。
|
||||
|
||||
## 5. 数据库设计
|
||||
|
||||
| 表 | 作用 | 关键约束 |
|
||||
| --- | --- | --- |
|
||||
| `conversation_turn` | 最终话轮 | 通话内`turn_key`和`sequence_no`唯一；角色、时间顺序和正文长度约束 |
|
||||
| `conversation_summary` | 摘要与开放话题 | 通话、类型、生成版本唯一；必须有源话轮 |
|
||||
| `story_draft` | 故事聚合根和审核状态 | 通话与生成版本唯一；强版本号；指向当前修订 |
|
||||
| `story_revision` | 不可覆盖的故事版本 | 故事内修订号唯一；区分模型/人工作者；保存基础版本和原因 |
|
||||
| `story_source` | 故事版本到原话的追溯关系 | 版本、话轮和文本偏移组合唯一 |
|
||||
| `fact_candidate` | 可审核事实候选 | 区分长者陈述与模型推断；保存源话轮、敏感级别和状态 |
|
||||
| `curated_memory` | 长期记忆聚合根 | 当前版本、状态、有效期、敏感级别和强版本号 |
|
||||
| `memory_version` | 不可覆盖的记忆版本 | 记忆内版本号唯一；确认人、确认时间、原因、来源和内容摘要 |
|
||||
| `memory_index_entry` | 记忆检索索引状态 | 记忆版本和索引类型唯一；向量维度1536；状态可失效和删除 |
|
||||
|
||||
V8迁移已经在独立空数据库执行`up → down -all → up`，最终为`8|dirty=false`，九张内容与记忆表均存在。测试数据库随后已删除。
|
||||
|
||||
## 6. 安全、隐私与可观测性
|
||||
|
||||
- 供应商事件记录只保存事件类型、状态、时间和话轮数量，不把转写正文复制进事件审计正文。
|
||||
- 普通故事生成前执行本地敏感规则基线；验证码、支付账户和高敏感医疗信息默认不进入普通故事。该规则集只是生产内容安全服务接入前的最低门禁。
|
||||
- 内容生成API Key由Worker环境注入，Embedding API Key由API和Worker环境注入；密钥不写入数据库、候选记录、HTTP响应或错误正文，业务记录只保留`ark:<model-id>`和提示词版本。
|
||||
- Embedding API Key由API和Worker环境注入；记忆只记录模型引用，不记录密钥。只有普通敏感级别、当前有效且已授权的记忆进入外部向量化和语音召回。
|
||||
- 只有冻结快照允许保存字幕时才落`conversation_turn`；故事整理和个性化记忆分别使用独立授权门禁。
|
||||
- 故事、事实和记忆均保留租户、长者和来源边界；所有网页接口从OIDC主体重新解析家庭成员关系，不信任客户端传入租户。
|
||||
- 人工修订、确认、拒绝和授权撤回记录审计事件；写操作使用强ETag防止并发覆盖。
|
||||
- 通话创建已接入内部数据库召回并冻结实际使用的记忆版本；调用方不能传入自由租户或长者过滤条件。当前尚未开放通话中工具检索接口。
|
||||
|
||||
## 7. 验证结果
|
||||
|
||||
- Go全仓测试通过，OpenAPI 0.10.0可生成TypeScript类型，React生产构建通过。
|
||||
- 本地内容策略单元测试覆盖验证码、银行卡号、高敏感医疗词和普通生活经历。
|
||||
- 方舟兼容适配器轻量验证覆盖Bearer鉴权、请求路径、结构化响应校验、HTTP 429重试分类；真实PostgreSQL组合验证模型调用期间不持有通话行锁，模型返回后正常生成候选，敏感话轮不会调用外部模型。
|
||||
- 方舟Embedding适配器轻量验证覆盖Bearer鉴权、`/embeddings`请求、模型/维度参数、1536维结果和错误维度拒绝；真实PostgreSQL组合验证向量生成期间不持有索引行锁，返回后可激活索引。
|
||||
- 端到端通话冒烟验证最终话轮去重、两类整理结果、故事来源、人工确认前零记忆、确认后记忆生成及索引生效；下一次通话冻结1个记忆版本。
|
||||
- 记忆修订生成第2版并重新索引；停用后索引立即失效且新通话召回0条；重新启用再次进入索引流程。
|
||||
- 永久删除验证覆盖`PENDING_DELETE → DELETED`、删除中重新激活稳定拒绝、向量清理、数据库正文替换为删除标记和删除后新通话召回0条。
|
||||
- React故事与记忆页以页面内管理区提供正文修订、启停和永久删除；未修改正文、空原因、未确认删除均不能提交，删除中和历史终态只读，不再依赖浏览器弹窗。
|
||||
- OIDC、SaaS、设备、成员和通话五组冒烟全部通过；测试结束后内容表残留为0，Outbox无待处理、处理中或死信事件。
|
||||
- 当前方舟内容与Embedding协议均使用本地模拟端点验证，尚未使用业务方真实API Key核验模型效果、召回质量、额度和数据条款；真实语音供应商与真实设备也仍待验收。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 生产内容安全服务适配
|
||||
|
||||
## 1. 处理边界
|
||||
|
||||
Worker以两层策略保护故事、事实和后续记忆。第一层是进程内固定高风险规则，识别验证码、支付账户、提示注入和高敏医疗内容；命中后直接生成不含原文的受控提示，原文不发送给内容模型或外部安全服务。第二层是生产托管策略，分别检查准备送给内容模型的长者话轮和模型返回的摘要、开放话题、故事、事实组合文本。
|
||||
|
||||
托管策略返回`BLOCK`或`REVIEW`时，Worker只保存受控摘要和开放提示，不创建普通故事、事实或记忆。网络失败、超时、408/425/429/5xx、不可解析响应和不符合协议的响应均按可重试错误安全阻断；其他4xx作为永久配置或请求错误进入现有死信治理。任何失败都不会被降级解释为允许。
|
||||
|
||||
## 2. HTTP协议
|
||||
|
||||
Worker对`CONTENT_SAFETY_ENDPOINT`执行`POST`，使用`Authorization: Bearer <API Key>`和`Content-Type: application/json`。请求为：
|
||||
|
||||
```json
|
||||
{
|
||||
"policy_ref": "elder-story-production-v1",
|
||||
"content": "待分类文本"
|
||||
}
|
||||
```
|
||||
|
||||
成功响应必须是：
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "ALLOW",
|
||||
"sensitivity": "normal",
|
||||
"reason_code": "",
|
||||
"request_ref": "provider-audit-reference"
|
||||
}
|
||||
```
|
||||
|
||||
`decision`只允许`ALLOW`、`BLOCK`、`REVIEW`；`sensitivity`只允许`normal`、`sensitive`、`high`。阻断或复核必须返回由小写字母、数字、下划线或连字符组成且不超过64字符的`reason_code`。`request_ref`用于供应商侧审计关联，不写入普通业务正文。响应正文、API Key和待分类文本不会拼入应用错误。
|
||||
|
||||
## 3. 配置
|
||||
|
||||
| 变量 | 说明 |
|
||||
|---|---|
|
||||
| `CONTENT_SAFETY_PROVIDER` | 本地开发为`local`；生产必须为`managed_http` |
|
||||
| `CONTENT_SAFETY_ENDPOINT` | 托管分类服务绝对地址；生产必须为非本地HTTPS |
|
||||
| `CONTENT_SAFETY_API_KEY` / `_FILE` | Bearer密钥；二者只能配置一个，生产建议CSI文件 |
|
||||
| `CONTENT_SAFETY_POLICY_REF` | 经业务、安全和法务批准的不可变策略版本 |
|
||||
| `CONTENT_SAFETY_TIMEOUT` | 单次HTTP超时，默认5秒 |
|
||||
|
||||
生产Worker在连接数据库前执行配置门禁，拒绝本地提供器、HTTP或本地端点、占位/短密钥和本地策略名。Kubernetes基线从`voice-platform-model-storage`目录读取`content-safety-api-key`；生产覆盖层必须替换ConfigMap中的`.example.invalid`与`replace-with-*`占位值。
|
||||
|
||||
启用托管策略时，Worker还按`EXTERNAL_PROBE_INTERVAL`对策略端点执行无正文的DNS、TCP和受信TLS握手，结果写入`content_safety_tls`外部依赖状态和Prometheus指标。连续5分钟不可用触发`PlatformExternalDependencyUnavailable`，但不进入Pod readiness，避免网络抖动引发重启风暴；生产候选验收快照必须把该依赖列为必需项。
|
||||
|
||||
## 4. 验收
|
||||
|
||||
日常开发只运行适配器和配置的定向测试，覆盖正常允许、本地命中不外发、托管复核阻断、临时故障重试以及永久4xx。发布候选仍需在真实账号和目标策略上完成`VERIFICATION_CODE`、`FINANCIAL_ACCOUNT`、`PROMPT_INJECTION`、`SENSITIVE_MEDICAL`、`NORMAL_BENIGN`、`MODEL_OUTPUT_SAFETY`六类证据，并由`cmd/agent-models-conformance`形成不可豁免报告。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 私有数据导出开发说明
|
||||
|
||||
## 1. 功能边界
|
||||
|
||||
私有数据导出用于将某一长者在当前租户和家庭边界内的资料生成独立JSON文件。它与`ACCESS`数据盘点分离：盘点只返回分类数量，导出文件才包含用户被授权获取的正文。
|
||||
|
||||
可导出分类包括长者档案、授权记录、设备绑定、通话元数据、最终话轮、摘要、故事与来源、已确认记忆。未显式指定分类时生成全量导出。
|
||||
|
||||
## 2. 功能设计
|
||||
|
||||
1. 家庭所有者使用`Idempotency-Key`提交导出任务。
|
||||
2. API在事务中验证`privacy.manage`、长者归属和请求摘要，写入`QUEUED`任务及Outbox事件。
|
||||
3. Worker将任务转为`RUNNING`，按固定分类SQL查询数据，生成`subject-export-v1`文档。
|
||||
4. Worker计算SHA-256，将文件写入MinIO私有桶，再把文件大小、摘要和过期时间提交到PostgreSQL。
|
||||
5. 用户读取`READY`任务时，API使用公网端点现场生成短期预签名URL，不在数据库和页面持久化URL。
|
||||
6. 到期扫描器删除对象，清空内部对象引用，把任务置为`EXPIRED`并记录最小审计。
|
||||
|
||||
## 3. 安全设计
|
||||
|
||||
- MinIO桶`private-exports`保持私有，未签名的对象请求被拒绝。
|
||||
- 对象路径为`tenants/{tenant-hash}/exports/{export-id}/v1.json`，不把租户主键直接写入路径。
|
||||
- API不返回`object_ref`、对象存储凭据或长期URL。导出详情和列表使用`Cache-Control: no-store`。
|
||||
- 下载URL有效期取“配置的短期下载TTL”与“对象剩余有效期”的较小值。
|
||||
- 导出文件包含私密正文，仅能使用合成数据进行本地测试，生产密钥必须由密钥管理系统注入。
|
||||
|
||||
## 4. 接口设计
|
||||
|
||||
| 接口 | 权限 | 说明 |
|
||||
|---|---|---|
|
||||
| `POST /api/v1/subjects/{id}/exports` | `privacy.manage` | 幂等创建导出，返回`202`；重放返回`200` |
|
||||
| `GET /api/v1/subjects/{id}/exports` | `privacy.read` | 返回当前长者导出列表，不签发下载URL |
|
||||
| `GET /api/v1/exports/{id}` | `privacy.read` | 返回任务详情；仅就绪且未过期时包含短期URL |
|
||||
|
||||
## 5. 数据库设计
|
||||
|
||||
`export_task`保存租户、长者、申请人、冻结范围、任务状态、对象引用、大小、内容摘要、过期时间、尝试次数和幂等摘要。状态为`QUEUED/RUNNING/READY/FAILED/EXPIRED`。`READY`数据库约束要求对象引用、大小、摘要、过期时间和完成时间全部存在。
|
||||
|
||||
## 6. 配置
|
||||
|
||||
| 变量 | 用途 |
|
||||
|---|---|
|
||||
| `OBJECT_STORE_ENDPOINT` | API/Worker访问对象存储的内网端点 |
|
||||
| `OBJECT_STORE_PUBLIC_ENDPOINT` | 用于生成用户可访问签名URL的端点 |
|
||||
| `OBJECT_STORE_REGION` | 签名Region，避免使用公网地址执行内部探测 |
|
||||
| `OBJECT_STORE_EXPORT_BUCKET` | 私有导出桶 |
|
||||
| `EXPORT_DOWNLOAD_TTL` | 单次预签名下载地址有效期 |
|
||||
| `EXPORT_OBJECT_TTL` | 导出对象总保留期 |
|
||||
|
||||
## 7. 验证
|
||||
|
||||
`scripts/smoke-export.ps1`使用本地真实OIDC令牌、PostgreSQL、Worker和MinIO验证所有者/编辑者权限、幂等重放、分类范围、私有桶拒绝直连、预签名下载、SHA-256校验、长者边界和过期后对象删除。
|
||||
|
||||
家庭工作台的“生成私有导出”现先打开页面内受控操作区。表单固定当前长者公开编号和八类导出范围，并明确后台将生成包含个人正文的私有JSON文件、对象与短期下载地址均有有效期、文件下载后应受控保存和销毁且操作会进入申请与导出审计。用户必须勾选私密数据影响确认后才能提交；取消或切换业务上下文会清除草稿，不创建任务，也不提前签发下载地址。
|
||||
|
||||
READY任务的“获取短期下载”同样不再单击即读取任务详情并触发下载。确认区固定长者、导出任务公开编号、任务冻结的分类范围、文件大小和对象过期时间，明确短期地址只会在提交时现场生成，JSON包含个人正文且离开平台后需要限制转交并按需销毁。只有显式确认后才重新读取任务；任务仍为READY、对象仍未过期且返回短期地址时才触发浏览器下载。取消或切换长者、家庭、工作台会清除草稿，不调用会签发地址的任务详情接口。
|
||||
|
||||
日常页面验证采用真实OIDC无提交冒烟，只检查对象/范围绑定、确认门禁、取消关闭、零导出创建请求、零任务详情地址签发请求、任务数量不变及页面布局。完整对象生成、私有桶、摘要、下载和过期清理由本节既有定向脚本承担，避免在普通前端改动中重复执行高强度全链路测试。
|
||||
|
||||
V10迁移已在独立临时空库完成`up 1—10 → down -all → up 1—10`，最终状态为`10|dirty=false`，验证库已删除。
|
||||
@@ -0,0 +1,445 @@
|
||||
# 数据采集终端—云端系统详细开发计划
|
||||
|
||||
> 依据：《数据采集终端—云端系统研发需求规格说明书》
|
||||
> 计划口径：从工程框架搭建到生产落地
|
||||
> 编制日期：2026-08-23
|
||||
> 文档状态：可执行基线，外部账号、硬件和生产资源确认后滚动修订
|
||||
|
||||
## 1. 计划目标
|
||||
|
||||
本计划用于组织数据采集终端、SaaS平台、Agent编排、实时音视频供应商、模型供应商和平台工程的联合研发。最终交付应形成以下完整业务闭环：
|
||||
|
||||
1. 家庭用户创建家庭和长者档案，完成分项授权与设备绑定。
|
||||
2. 终端摘机后通过设备身份访问云端，取得只适用于本次房间和用户的短期RTC资料。
|
||||
3. 设备确认入房后，云端启动语音智能体；实时语音直接在终端、RTC和语音智能体之间传输，自建应用服务器只负责控制面和业务数据。
|
||||
4. 通话期间持续处理心跳、状态、最终话轮、打断、异常停止和任务回收。
|
||||
5. 通话后按授权生成摘要、开放话题、故事与事实候选，经家庭用户核对后形成可版本化的正式记忆。
|
||||
6. 录音、分享、导出、授权撤回和主体删除均按最小权限处理并可审计、可对账。
|
||||
7. 运营人员可以在脱敏边界内处理故障，管理配置版本、灰度、费用、额度和告警。
|
||||
8. 系统完成真机、真实供应商、家庭试点、容量、安全、恢复和生产上线验收。
|
||||
|
||||
## 2. 计划假设与工期口径
|
||||
|
||||
### 2.1 建议团队
|
||||
|
||||
| 角色 | 建议人数 | 主要责任 |
|
||||
|---|---:|---|
|
||||
| 项目经理/需求负责人 | 1 | 需求基线、计划、风险、跨团队协调和验收 |
|
||||
| 后端工程师 | 2—3 | SaaS业务、设备接入、Agent控制、数据、异步任务和运营接口 |
|
||||
| 前端工程师 | 1—2 | 家庭工作台、内容核对、隐私和运营后台 |
|
||||
| Agent/模型工程师 | 1—2 | 供应商适配、提示词、模型路由、内容整理、记忆和评测 |
|
||||
| 测试工程师 | 1—2 | 接口、端到端、真机、性能、安全、恢复和验收测试 |
|
||||
| 平台/运维工程师 | 1 | CI/CD、环境、监控、告警、备份、密钥和生产发布 |
|
||||
| 硬件/固件接口人 | 1 | 设备协议、音频、命令、录音上传、固件和真机联调 |
|
||||
|
||||
工期以8—10人的跨职能团队并行开发为估算前提。若后端、Agent、测试或硬件接口人不能并行，日历工期需相应顺延。外部供应商账号、真实设备、生产网络和合规材料不计入纯编码工时，但直接影响联调、试点和上线日期。
|
||||
|
||||
### 2.2 总体工期建议
|
||||
|
||||
| 阶段 | 建议周期 | 累计时间 | 主要里程碑 |
|
||||
|---|---:|---:|---|
|
||||
| 阶段0：启动与需求冻结 | 1—2周 | 第1—2周 | M0需求与边界基线 |
|
||||
| 阶段1：工程框架与环境 | 2周 | 第3—4周 | M1工程可运行 |
|
||||
| 阶段2：公共基础能力 | 2—3周 | 第5—7周 | M2安全业务底座 |
|
||||
| 阶段3：端到端语音最小闭环 | 3—4周 | 第8—11周 | M3真/模拟设备可完成通话 |
|
||||
| 阶段4：SaaS核心业务 | 4—5周 | 第12—16周 | M4家庭用户P0流程 |
|
||||
| 阶段5：内容与记忆闭环 | 3—4周 | 第15—18周 | M5确认记忆进入下一通话 |
|
||||
| 阶段6：隐私、分享与媒体完善 | 3—4周 | 第17—20周 | M6数据生命周期闭环 |
|
||||
| 阶段7：运营与生产加固 | 3—4周 | 第19—22周 | M7可运营、可恢复、可发布 |
|
||||
| 阶段8：联调、试点与上线 | 3—6周 | 第23—28周 | M8生产上线与移交 |
|
||||
|
||||
阶段4—7可在接口和数据边界冻结后交叉并行。上述周期是项目计划估算，不是需求文档中的固定交付承诺；应在M0评审时结合人员和外部资源形成正式排期。
|
||||
|
||||
## 3. 总体执行原则
|
||||
|
||||
- 采用模块化单体起步，`api`、`callbacks`和`worker`分别承载在线接口、供应商通知和后台任务。
|
||||
- OpenAPI是浏览器、设备和回调接口的事实来源；接口变更先改契约，再改实现和测试。
|
||||
- 所有业务数据同时落实客户组织、家庭、长者和具体资源边界，不能相信浏览器或设备上报的租户编号。
|
||||
- 会产生外部影响的POST请求使用`Idempotency-Key`；修改操作使用`ETag/If-Match`或显式版本号。
|
||||
- 外部调用前先保存业务意图，通过可靠待办异步执行；数据库事务不跨越供应商、对象存储或身份服务网络调用。
|
||||
- 配置、授权、故事、记忆和费用采用版本化保存；撤销、逻辑删除、审计保留和物理删除分别建模。
|
||||
- 长期密钥只保存在KMS/HSM或受控密钥系统中，业务数据库和页面仅保存引用与最后轮换时间。
|
||||
- 每阶段采用“最小充分验证”后再进入下一阶段：变更包定向测试、受影响的迁移或接口契约检查、一条可复现的纵向功能冒烟和文档同步必须通过；无关模块的全量回归不作为日常阶段门禁。
|
||||
|
||||
## 4. 分阶段开发计划
|
||||
|
||||
## 4.1 阶段0：项目启动与需求基线冻结
|
||||
|
||||
### 目标
|
||||
|
||||
把需求文档转化为研发、联调和验收共同使用的范围基线，先解决系统边界、责任分工和外部依赖不确定性。
|
||||
|
||||
### 主要任务
|
||||
|
||||
1. 建立需求追踪矩阵：需求编号—模块—接口—数据表—测试用例—交付物。
|
||||
2. 冻结两条责任边界：SaaS负责“人、设备、权限、数据和网页”，Agent负责“通话控制、供应商适配、模型效果和内容候选”。
|
||||
3. 确认实时语音不经过自建应用服务器，应用服务只处理控制、状态、字幕、用量和业务数据。
|
||||
4. 明确设备型号、主板版本、音频格式、RTC发布/订阅方式、心跳字段、双轨分片清单和命令回执。
|
||||
5. 明确火山RTC、豆包语音、模型、Embedding、对象存储、OIDC、短信/邮件和KMS账号申请计划。
|
||||
6. 形成开发、测试、预生产、生产四套环境的隔离清单。
|
||||
7. 输出风险台账，重点跟踪真实供应商能力、录音合规、硬件交付、供应商限额和生产网络。
|
||||
|
||||
### 交付物与退出条件
|
||||
|
||||
- 需求基线、范围清单、术语表、责任矩阵、接口清单和数据分类分级表完成评审。
|
||||
- 外部依赖有负责人、申请时间和替代模拟方案。
|
||||
- 未决事项明确决策截止日期，不影响第一阶段工程搭建。
|
||||
|
||||
## 4.2 阶段1：工程框架与本地环境搭建
|
||||
|
||||
### 目标
|
||||
|
||||
建立可重复启动、可检查、可迁移、可构建的工程骨架，让前后端、Agent和测试可以并行开发。
|
||||
|
||||
### 后端与基础设施任务
|
||||
|
||||
- 初始化Go模块化单体，建立`cmd/api`、`cmd/callbacks`、`cmd/worker`三个进程入口。
|
||||
- 建立配置加载、结构化日志、请求编号、优雅停机、错误响应和健康检查。
|
||||
- 接入PostgreSQL、pgvector、Redis、S3兼容对象存储和OIDC开发身份服务。
|
||||
- 建立数据库迁移规则：迁移仅追加、支持空库升级、单版本回退和重新升级。
|
||||
- 建立Dockerfile、Docker Compose、环境变量模板和本地种子数据。
|
||||
- 建立CI基础流水线：格式、静态检查、变更包单元测试、OpenAPI生成、前端类型检查、构建、依赖审计和Compose解析；全仓单测和完整安全扫描放到发布候选流水线执行。
|
||||
|
||||
### 前端任务
|
||||
|
||||
- 初始化React、TypeScript和Vite应用。
|
||||
- 建立登录回调、API客户端、全局错误、加载、无数据、权限不足和重试组件。
|
||||
- 建立桌面端优先、平板可用的页面框架和统一设计变量。
|
||||
|
||||
### 接口与数据库
|
||||
|
||||
- 首批接口：`/health/live`、`/health/ready`、`/api/v1/version`、`/api/v1/me`。
|
||||
- 首批表：租户、用户、审计事件、幂等记录和可靠待办。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 新开发机可按文档一次启动完整本地环境。
|
||||
- 空数据库可升级到最新版本，服务就绪接口全部通过。
|
||||
- 前后端镜像可构建，OpenAPI可生成TypeScript类型，基础CI无失败。
|
||||
|
||||
## 4.3 阶段2：公共基础能力建设
|
||||
|
||||
### 目标
|
||||
|
||||
一次性建立后续所有业务模块共用的身份、权限、隔离、可靠性和可观测能力。
|
||||
|
||||
### 主要任务
|
||||
|
||||
1. OIDC令牌验证：校验签发方、使用对象、签名、有效期和账号状态。
|
||||
2. 租户与家庭权限：建立所有者、管理员、编辑者、查看者能力矩阵；服务端反查资源边界。
|
||||
3. 幂等执行器：保存请求摘要和原响应，支持并发串行化及同键异文拒绝。
|
||||
4. 事务审计：业务写入与审计同事务提交，记录操作人、原因、前后状态和请求编号。
|
||||
5. Outbox可靠待办：领取、重试、退避、死信、进程崩溃锁恢复和积压指标。
|
||||
6. 接口治理：请求体限制、统一错误码、签名游标、强ETag、安全响应头和Redis限流。
|
||||
7. 可观测性：OpenTelemetry链路、Prometheus指标、结构化日志和依赖健康状态。
|
||||
8. 安全基线：敏感字段日志过滤、生产配置启动门禁和密钥相互独立检查。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 跨租户、跨家庭、角色越权、伪造/过期令牌测试全部拒绝。
|
||||
- 并发幂等请求只产生一次业务效果。
|
||||
- 业务回滚时审计同步回滚，Outbox在进程重启后可以继续处理。
|
||||
- 指标、日志和追踪可使用同一请求编号关联。
|
||||
|
||||
## 4.4 阶段3：端到端语音最小闭环
|
||||
|
||||
### 目标
|
||||
|
||||
先使用模拟设备和模拟供应商打通“摘机—创建—入房—激活—对话—挂断—回收”，再切换真实设备和供应商。
|
||||
|
||||
### 设备接入任务
|
||||
|
||||
- 每台设备建立独立身份，采用经批准的每设备请求签名或mTLS。
|
||||
- 实现时间偏差校验、Nonce防重放、密钥吊销和轮换兼容。
|
||||
- 实现`bootstrap`和版本化`config`，配置只包含设备运行所需的非敏感信息。
|
||||
- 建立设备在线状态、期望配置、实际配置和单调版本同步。
|
||||
|
||||
### 通话控制任务
|
||||
|
||||
1. `POST /device/v2/conversations`：冻结授权、背景、记忆和配置版本，分配RTC房间与短期凭证，此时不启动Agent。
|
||||
2. `POST /device/v2/conversations/{id}/activate`：设备确认入房后可靠投递供应商启动任务。
|
||||
3. `POST /device/v2/conversations/{id}/heartbeat`：维护数据库权威租约和Redis热状态，拒绝旧序号覆盖新状态。
|
||||
4. `POST /device/v2/conversations/{id}/stop`：可靠停止供应商任务并收敛终态。
|
||||
5. `POST /device/v2/conversations/{id}/turns:batch`：供应商终稿缺失时由所属设备补传，按话轮业务键原子去重合并。
|
||||
6. `POST /device/v2/telemetry:batch`：批量接收状态、有限错误码和命令结果，推进设备影子并返回后续动作。
|
||||
7. `POST /callbacks/v1/vertc/voice-chat`：先验签再解析，按供应商事件编号和正文摘要去重。
|
||||
8. Worker扫描预留过期、心跳超时、启动/停止卡住和供应商遗留任务。
|
||||
|
||||
### 状态机
|
||||
|
||||
`PREPARING → ROOM_ISSUED → STARTING_AGENT → ACTIVE → STOPPING → COMPLETED`
|
||||
|
||||
异常终态为`FAILED`或`EXPIRED`。重复通知和过时通知不得让终态回退。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 模拟设备可连续完成完整通话，重复创建不会产生两个有效房间。
|
||||
- 设备未入房时不启动供应商任务，预留到期可自动回收。
|
||||
- API、Callback或Worker重启后，中间状态可自动收敛。
|
||||
- 使用真实账号完成RTC短期凭证、Agent启动/停止和签名通知联调后，才将本阶段标记为真实闭环完成。
|
||||
|
||||
## 4.5 阶段4：SaaS核心业务开发
|
||||
|
||||
### 目标
|
||||
|
||||
完成家庭用户从登录、建档、授权和绑定设备，到查看通话与管理内容的P0业务流程。
|
||||
|
||||
### 功能批次
|
||||
|
||||
| 子批次 | 功能 | 关键接口与数据 |
|
||||
|---|---|---|
|
||||
| 4A 家庭与成员 | 家庭创建、邀请、角色、移除、所有权转移 | `/households`、`/members`、`member_invitation`、`household_member` |
|
||||
| 4B 长者与授权 | 档案、稳定事实、五类分项授权、撤回和快照 | `/subjects`、`/facts`、`/consents`、`subject_profile`、`consent_record` |
|
||||
| 4C 设备管理 | 列表、详情、绑定、解绑/转移申请、在线状态和设备影子 | `/devices`、`/device-claims`、`device_binding`、`device_twin` |
|
||||
| 4D 受控命令 | 排队、设备拉取、确认、成功/失败和过期 | `/devices/{id}/commands`、`/device/v2/commands`、`device_command` |
|
||||
| 4E 固件 | 公钥、制品、签名、灰度、暂停、回滚和逐设备进度 | `/firmware-*`、`firmware_release`、`firmware_rollout` |
|
||||
| 4F 通话页面 | 列表、筛选、游标分页、状态、字幕、摘要、用量和错误 | `/subjects/{id}/conversations`、`/conversations/{id}` |
|
||||
|
||||
### 页面设计
|
||||
|
||||
- 家庭成员页、长者档案与授权页、设备管理页、固件发布页和通话记录页。
|
||||
- 所有页面覆盖加载、空数据、失败、重试、权限不足和并发修改状态。
|
||||
- 家庭角色只控制业务操作能力，不隐式授予字幕、录音或具体分享资源权限。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 家庭用户P0流程端到端通过；跨家庭资源编号访问不泄露资源是否存在。
|
||||
- 多人编辑使用版本检查，旧版本写入返回冲突。
|
||||
- 设备离线、命令过期、重复回执和固件损坏均有稳定、可审计结果。
|
||||
|
||||
## 4.6 阶段5：Agent内容、故事与记忆闭环
|
||||
|
||||
### 目标
|
||||
|
||||
把最终字幕转化为可追溯候选内容，经人工核对后形成仅在有效授权下进入后续通话的正式记忆。
|
||||
|
||||
### 主要任务
|
||||
|
||||
- 接收并去重最终话轮，保存角色、顺序、时间、打断和来源事件。
|
||||
- 仅在字幕保存授权有效时保存正文；供应商原始事件不重复保存完整字幕。
|
||||
- 生成通话摘要、开放话题、故事候选和事实候选，并保留来源话轮和生成版本。
|
||||
- 对验证码、账户信息和敏感医疗内容先识别、最小化和策略过滤。
|
||||
- 实现故事查看、修订、确认和拒绝；每次修改形成不可覆盖的新版本。
|
||||
- 只有人工确认且个性化记忆授权有效时，才创建正式记忆和检索索引。
|
||||
- 使用PostgreSQL与pgvector按租户、长者、授权、敏感级别、状态和版本检索。
|
||||
- 停用、授权撤回或删除后立即停止新通话召回，后台对账索引和正文清理。
|
||||
- 建立固定评测集，记录通话成功、时延、打断、称呼、记忆、虚构、来源完整和敏感内容处理。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 机器候选不会自动成为正式记忆。
|
||||
- 新确认记忆只从下一次新通话开始生效；进行中的通话保持冻结版本。
|
||||
- 两位长者交替测试不串用资料；提示注入不能改变服务端授权和数据边界。
|
||||
- 删除或撤回后，新通话召回为零并有后台对账证据。
|
||||
|
||||
## 4.7 阶段6：录音、分享、导出与隐私闭环
|
||||
|
||||
### 目标
|
||||
|
||||
完成从设备本地双轨录音到云端访问，以及数据分享、导出、撤回和永久删除的全生命周期。
|
||||
|
||||
### 录音链路
|
||||
|
||||
1. 设备在原录音保存授权有效时，本地加密保存near/far两条轨道。
|
||||
2. 设备提交幂等分片清单，云端为单个对象签发短期上传地址。
|
||||
3. Worker校验大小、SHA-256、WAV/Opus容器、时长和分片稳定编号。
|
||||
4. 云端确认校验且达到保留窗口后，设备删除本地密文并提交删除回执。
|
||||
5. 播放和下载使用独立授权，每次访问重新校验授权并签发短期地址。
|
||||
|
||||
### 分享与状态通知
|
||||
|
||||
- 具体资源分享支持故事、通话文字和录音，分别设置接收人、权限、用途、时限和登录要求。
|
||||
- 登录分享校验指定接收人；匿名分享只保存口令摘要；匿名模式禁止故事编辑。
|
||||
- 故事共享编辑使用`If-Match`并形成新修订；文字分享不隐式包含音频。
|
||||
- `/api/v1/events`使用认证SSE发送最小状态事件，支持`Last-Event-ID`短时续传和客户端去重。
|
||||
|
||||
### 导出与删除
|
||||
|
||||
- 数据访问请求只返回分类盘点和状态，不在列表中复制正文。
|
||||
- 私有导出由Worker生成，保存至私有对象存储，提供短期下载和摘要校验。
|
||||
- 主体删除先立即冻结访问、上传和召回，再对PostgreSQL、Redis、对象存储、pgvector、供应商索引和导出文件执行可重试对账。
|
||||
- 删除证明只保存必要编号、状态、计数和时间，不保留已删除正文。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 无原录音授权或无播放/下载授权时不能取得录音地址，每次成功和拒绝均有审计。
|
||||
- 分享撤销或过期后拒绝新访问；匿名原始口令不进入数据库和日志。
|
||||
- 隐私删除在任一子系统短暂失败后可以继续重试，最终状态可查询且无正文残留。
|
||||
|
||||
## 4.8 阶段7：内部运营、配置、费用、告警与生产加固
|
||||
|
||||
### 目标
|
||||
|
||||
建立面向内部运营人员的脱敏工作台和生产运行能力，使系统可诊断、可配置、可控费、可告警、可恢复。
|
||||
|
||||
### 运营故障处理
|
||||
|
||||
- 建立`/ops/*`接口与独立运营角色：客服只读、运营操作、配置审批和平台管理员。
|
||||
- 按脱敏设备编号和通话编号查询状态、错误、配置版本、用量和上传积压。
|
||||
- 支持安全停止、设备吊销、后台任务重试、状态对账和脱敏诊断包。
|
||||
- 临时查看敏感内容必须填写理由、有效期并经过审批；默认不显示字幕正文和原录音。
|
||||
- 所有运营动作记录操作人、原因、操作前后状态和请求编号。
|
||||
|
||||
### 配置发布
|
||||
|
||||
- 人设、音色、模型和路由配置按`DRAFT → PENDING_APPROVAL → PUBLISHED → RETIRED`管理。
|
||||
- 发布前执行字段完整性、资源引用、模型兼容性、费用上限和离线评测检查。
|
||||
- 支持按客户组织、设备分组或测试长者灰度，并限制并发影响范围。
|
||||
- 支持版本差异比较和回滚；新通话使用新版本，历史通话保留原配置快照。
|
||||
- 页面只显示长期密钥引用名称和最后轮换时间。
|
||||
|
||||
### 用量、费用和额度
|
||||
|
||||
- 按通话归集RTC、端到端语音、ASR、LLM、TTS、存储和通话后处理用量。
|
||||
- 供应商用量事件幂等去重；按带版本的单价快照计算，价格调整不改变历史费用。
|
||||
- 配置客户组织每日/月度额度、同时通话数和单次最长时长。
|
||||
- 达到硬额度时阻止新通话并返回稳定错误；在途通话按已发布策略停止或完成当前轮次。
|
||||
|
||||
### 监控、告警和恢复
|
||||
|
||||
- 业务仪表盘：通话成功、活跃通话、设备在线、上传、内容审核、隐私任务和费用。
|
||||
- 技术仪表盘：API、Callback、Worker、数据库、Redis、对象存储、Outbox和供应商依赖。
|
||||
- 安全仪表盘：认证失败、越权、重放、密钥/证书到期和高风险运营操作。
|
||||
- 告警覆盖供应商不可用、启动/停止异常、遗留任务、数据库/Redis故障、通知积压、删除超期、上传失败和费用异常增长，并关联运维手册。
|
||||
- 完成数据库恢复、长期密钥轮换、供应商故障和隐私删除四类演练。
|
||||
|
||||
### 专项验证
|
||||
|
||||
- 执行需求场景的接口、活跃通话、回调、SSE、媒体分片和并发删除专项压测。
|
||||
- 执行租户隔离、录音越权、回调重放、提示注入、依赖漏洞、镜像和密钥扫描。
|
||||
- 在Chrome、Edge和项目确认的其他目标浏览器完成桌面与平板兼容验证。
|
||||
|
||||
### 退出条件
|
||||
|
||||
- 错误配置在影响新通话前被阻止，回滚后新通话使用上一已发布版本。
|
||||
- 每次通话的用量、价格版本和总费用可追溯且不重复计费。
|
||||
- 告警有接收人、严重级别、静默规则、升级路径和运维手册链接。
|
||||
- 备份可在隔离环境实际恢复，而不是只检查备份任务状态。
|
||||
|
||||
## 4.9 阶段8：真实联调、家庭试点与生产上线
|
||||
|
||||
### 目标
|
||||
|
||||
用真实设备、真实供应商账号和类生产基础设施完成联合验收，并安全发布生产。
|
||||
|
||||
### 联调顺序
|
||||
|
||||
1. 单设备实验室联调：入房、双向语音、心跳、挂断、录音、命令和固件。
|
||||
2. 弱网与异常联调：丢包、断网、设备重启、API/Worker重启、供应商超时和重复通知。
|
||||
3. 多设备稳定性：连续多轮通话、并发通话、任务遗留和资源回收。
|
||||
4. 小范围内部试用：仅合成或经批准的脱敏数据，检查内容质量与运维流程。
|
||||
5. 家庭试点：明确知情同意、退出方式、反馈渠道和每日风险复盘。
|
||||
6. 预生产演练：部署、数据库迁移、回滚、备份恢复、密钥轮换和告警通知。
|
||||
7. 生产发布：分批放量，观察业务、技术、安全和费用指标后逐步扩大。
|
||||
|
||||
### 上线门禁
|
||||
|
||||
- 首期需求、用例、缺陷和遗留风险可追踪，阻断级缺陷为0。
|
||||
- 真实账号完成RTC、三种语音处理方式、字幕、状态、用量和配额验证。
|
||||
- 客户组织隔离、录音越权、通知重放、遗留任务回收和隐私删除专项通过。
|
||||
- 生产域名、证书、OIDC、对象存储、数据库、Redis、KMS、备份、告警接收人和应急联系人已配置。
|
||||
- 业务方、研发方、测试方和硬件方签署联合验收与上线检查清单。
|
||||
|
||||
### 交付与移交
|
||||
|
||||
- 源代码、版本标签、构建说明、镜像和软件材料清单。
|
||||
- OpenAPI、数据字典、迁移、架构、功能、流程和接口文档。
|
||||
- 自动化测试、覆盖率、性能、安全、恢复、真机和试点报告。
|
||||
- 部署、回滚、监控、告警、备份恢复、密钥轮换和故障处理手册。
|
||||
- 账号权限、密钥引用、云资源、已知问题、值班机制和后续优化建议。
|
||||
|
||||
## 5. 关键业务流程与阶段依赖
|
||||
|
||||
```text
|
||||
需求冻结
|
||||
↓
|
||||
工程框架 ──→ 身份/权限/审计/幂等/Outbox
|
||||
↓ ↓
|
||||
设备身份与配置 ──→ 通话创建/激活/心跳/停止 ──→ 真实供应商联调
|
||||
↓ ↓
|
||||
家庭/长者/授权/绑定 最终字幕/摘要/候选
|
||||
↓ ↓
|
||||
录音上传与访问 人工核对/正式记忆/检索
|
||||
└──────────┬──────────────┘
|
||||
↓
|
||||
分享/导出/撤回/删除/SSE
|
||||
↓
|
||||
运营配置/费用/告警/恢复/安全
|
||||
↓
|
||||
真机试点 → 预生产演练 → 灰度上线 → 项目移交
|
||||
```
|
||||
|
||||
关键依赖如下：
|
||||
|
||||
- 没有设备身份和绑定关系，不能开始真实通话。
|
||||
- 没有分项授权快照，不能保存字幕、录音或生成长期记忆。
|
||||
- 没有最终话轮来源，不能确认故事和事实候选。
|
||||
- 没有配置版本冻结，不能做供应商问题、质量和费用追溯。
|
||||
- 没有可靠删除与审计，不进入家庭试点。
|
||||
- 没有真实账号、真机、告警接收人和恢复演练，不进入生产上线。
|
||||
|
||||
## 6. 测试与质量门禁
|
||||
|
||||
日常开发采用“功能完整、验证精简”的风险分层策略：每个子批次只验证本次改变的核心规则、接口契约、数据迁移和一条真实身份纵向链路，不为提高覆盖率重复补低价值用例，也不在普通功能批次重复执行全量压测、全浏览器矩阵或全仓回归。身份隔离、授权、幂等、通话状态、隐私删除、费用额度和密钥等高风险边界仍保留定向门禁；全量、安全、容量、恢复和真机矩阵集中在发布候选及上线前执行。
|
||||
|
||||
验证分为三档：
|
||||
|
||||
1. **日常必跑**：编译或类型检查、变更包测试、受影响的OpenAPI或数据库迁移检查、单条端到端轻量冒烟、运行服务就绪检查。
|
||||
2. **条件触发**：只有改动涉及身份权限、状态机、数据删除、并发容量、外部供应商、浏览器交互或恢复机制时，才增加相应专项用例。
|
||||
3. **发布候选必跑**：在计划发布的固定版本上执行一次全仓回归、安全扫描、关键业务全流程、容量与恢复验证，避免把高成本测试重复摊到每个小批次。
|
||||
|
||||
“功能完全可用”的最低判断标准不是用例数量，而是本次功能的入口、正常处理、一个关键失败分支、最终状态、用户可见反馈和数据清理均已闭环；任何一项缺失都不能仅凭接口返回成功宣告完成。
|
||||
|
||||
| 测试层次 | 每阶段要求 | 上线前要求 |
|
||||
|---|---|---|
|
||||
| 单元测试 | 只运行变更包及其直接依赖；新增或修正的核心规则至少一个正向、一个关键失败用例 | 核心规则无未解释失败，并运行一次全量单测 |
|
||||
| 数据库测试 | 有新迁移时执行正向升级、单版回退和重升；仅对新增约束做定向事务验证 | 完整升级/回退方案和备份点验证 |
|
||||
| 接口契约 | OpenAPI生成前端类型，检查破坏性变更 | Device/SaaS/Callback契约冻结 |
|
||||
| 集成测试 | 只组合本次功能实际依赖的服务，不重复跑无关模块 | 类生产依赖组合通过 |
|
||||
| 端到端测试 | 每个可见业务子批次一条真实身份纵向烟测并精确清理数据 | 家庭P0、通话、记忆、媒体、隐私和运营全流程 |
|
||||
| 性能测试 | 普通功能批次不重复执行；仅在热点路径、容量参数或并发模型变化时定向运行 | 按需求场景完成容量、瓶颈和扩容报告 |
|
||||
| 安全测试 | 依赖审计、越权、重放、敏感日志和配置门禁 | 渗透、密钥、镜像、租户隔离和隐私专项 |
|
||||
| 恢复测试 | Worker重试和中间状态恢复 | 数据库恢复、密钥轮换、供应商故障和删除演练 |
|
||||
| 页面测试 | TypeScript检查和生产构建；有明显交互或布局变化时才检查对应页面 | 目标浏览器、桌面和平板兼容矩阵 |
|
||||
|
||||
每个阶段的“完成”必须同时满足：代码合并、受影响迁移与接口同步、最小充分验证、页面或设备可见结果确认、文档同步和遗留风险登记。真实页面、真机、供应商或恢复验收只在本阶段功能依赖这些环境时执行；尚未取得外部条件的项目明确登记为“本地闭环、外部待验”，不能伪装为已经完成。
|
||||
|
||||
## 7. 项目管理机制
|
||||
|
||||
### 7.1 迭代节奏
|
||||
|
||||
- 采用两周一个迭代；每个迭代只承诺能够形成可演示纵向链路的事项。
|
||||
- 每周维护需求追踪、风险、接口变更、数据迁移和外部依赖五张清单。
|
||||
- 每个子批次先冻结接口和数据，再并行开发后端、前端、Agent与测试。
|
||||
- 每次演示使用端到端场景，不以单模块接口成功代替业务闭环。
|
||||
|
||||
### 7.2 评审与变更
|
||||
|
||||
- 需求变更先评估业务、隐私、接口、数据库、固件兼容、运维和回滚影响。
|
||||
- 破坏设备协议的变更发布新接口版本，不根据User-Agent猜测固件能力。
|
||||
- 生产配置、数据库迁移和高风险运营动作执行双人复核。
|
||||
- 未经真实环境验证的性能数字、兼容性和供应商能力必须标为待验证。
|
||||
|
||||
## 8. 风险与应对
|
||||
|
||||
| 风险 | 影响 | 预防与应对 |
|
||||
|---|---|---|
|
||||
| 真实供应商账号延期 | 语音、模型、用量和费用无法验收 | 先用模拟供应商完成契约与异常；账号到位后安排专门联调窗口 |
|
||||
| 硬件或固件延期 | 无法验证音频、弱网、录音和命令 | 提供模拟设备和协议回放；硬件每日构建接入同一OpenAPI |
|
||||
| 授权或隐私规则不明确 | 返工或合规风险 | 阶段0冻结数据分类、授权范围、保留和删除规则；高风险默认关闭 |
|
||||
| 供应商事件重复/乱序 | 状态错误、重复费用 | 事件编号+正文摘要幂等、状态单向推进、定期对账 |
|
||||
| 长事务调用外部服务 | 锁等待和不一致 | 业务意图+Outbox+可重试Worker，不跨网络持有事务 |
|
||||
| 配置错误影响全部通话 | 大范围不可用或费用异常 | 草稿、审批、离线校验、小范围灰度、上限和一键回滚 |
|
||||
| 内容候选被误当事实 | 错误记忆进入后续通话 | 来源必需、人工确认、版本化、授权门禁和召回过滤 |
|
||||
| 删除只完成部分系统 | 隐私风险 | 立即冻结、分子系统状态、可靠重试、最小证明和定期对账 |
|
||||
| 容量估计偏差 | 高峰不可用或成本失控 | 类生产压测、按模块指标定位、容量余量和分阶段放量 |
|
||||
| 文档与代码漂移 | 联调失败和运维误操作 | OpenAPI生成、迁移检查和文档状态纳入CI门禁 |
|
||||
|
||||
## 9. 当前实施状态与后续顺序
|
||||
|
||||
截至2026-08-25，本地工程已经完成阶段1—7的本地开发与验证闭环。1000活跃通话、50 RPS持续30分钟、500回调/秒、500条SSE、10000媒体分片、100并发删除、隔离数据库恢复、进程/Redis恢复、供应商故障、安全扫描、真实Chrome/Edge兼容、全仓检查、跨功能烟测和无测试残留对账均已完成。后续顺序为：
|
||||
|
||||
1. 外部基础设施探针、运营预检台账、联调问题门禁、可归档技术验收快照、试点日/周证据和v3候选证据包均已完成；生产内容安全已具备本地前置拦截、托管HTTP策略、输入/输出双检和安全失败语义；远程CI供应链已具备绑定提交、运行、14项检查、双镜像摘要和三份SBOM的不可豁免门禁。`PILOT`周期、远程CI、真机固件、真实终端RTC六通矩阵、真实Agent生成/Embedding/内容安全质量、真实告警网关、云KMS/HSM、四类生产等价恢复、七类生产基础设施和Safari精简矩阵均不可由本地模拟报告放行。下一步在目标环境逐项替换证据索引中的`PENDING`。
|
||||
2. 待真实火山RTC/豆包、大模型/Embedding账号、终端硬件和生产资源到位后，完成阶段8真机联调、家庭试点、预生产恢复与灰度发布。
|
||||
|
||||
实际完成证据与未完成项持续维护在[开发状态与门禁记录](development-status.md)中；本计划只定义执行顺序和退出条件，不用计划状态替代测试证据。
|
||||
@@ -0,0 +1,255 @@
|
||||
# 开发状态与门禁记录
|
||||
|
||||
> 更新日期：2026-08-25
|
||||
> 当前接口契约版本：0.64.0
|
||||
> 当前主里程碑：M8目标环境联调、试点与上线验收（外部条件待提供）
|
||||
|
||||
## 阶段状态
|
||||
|
||||
| 阶段 | 状态 | 已取得的证据 | 尚未完成 |
|
||||
|---|---|---|---|
|
||||
| 第一阶段：项目准备与基线冻结 | 本地研发基线完成 | `project-baseline.md`、ADR-0001、需求和技术栈已对应 | 真实硬件、供应商、OIDC、云资源和法务资料仍需业务方提供与确认 |
|
||||
| 第二阶段：工程框架与环境搭建 | 核心工程完成 | 三个Go进程、React Web、OpenAPI、两版迁移、Compose、镜像构建、健康冒烟和本地检查均通过 | 远程Git地址、实际CI运行、dev集群持续部署和密钥扫描平台待外部环境确定 |
|
||||
| 第三阶段：公共基础能力建设 | 已完成 | OIDC、租户隔离、权限、事务审计、幂等、outbox、OpenTelemetry、Prometheus指标、网络/用户/租户/设备分层限流、供应商启动容量保护、签名游标和ETag均已实现并通过测试；本地专项容量门禁已覆盖核心入口 | 参数和容量余量仍需在生产等价环境复测 |
|
||||
| 第四阶段：端到端语音最小闭环 | 本地模拟闭环完成 | 设备身份、`bootstrap/config`、创建、三种语音模式冻结与供应商模板选择、激活、启动、心跳、停止、终稿补传、批量遥测、录音直传能力、命令结果、签名回调、断网重连、重复/乱序保护和后台异常回收均已完成 | 真实硬件、火山RTC和豆包账号联调需要业务方提供外部参数 |
|
||||
| 第五阶段：SaaS核心业务开发 | 本地业务闭环完成 | 已完成家庭成员邀请与角色协作、长者、稳定事实、五类分项授权、设备读取/配置/绑定、可靠命令、签名固件灰度/暂停/回滚和逐设备升级进度、通话查询、双轨录音状态/授权/播放下载的数据库、服务、HTTP契约与React工作台；服务端隔离、ETag、审计、纵向烟测及Chrome/Edge兼容检查均通过 | 固件生产签名设施、macOS Safari和类生产容量仍待外部环境验证 |
|
||||
| 第六阶段：Agent内容与记忆闭环 | 本地开发闭环完成，生产模型协议已接入 | 最终话轮、可切换本地/火山方舟内容生成器与Embedding、事务外模型调用、摘要、开放话题、故事/事实候选、人工版本审核、授权门禁、已确认记忆、索引失效、固定边界召回及React审核页面均已实现；端到端烟测通过 | 真实方舟API Key、内容效果与召回质量验收、模型评测和真实内容安全策略待完成 |
|
||||
| 第七阶段：生产加固 | 本地证据持续收敛 | 记忆可靠删除、隐私访问/导出/删除、运营配置灰度、用量费用额度、告警处置闭环、可重试HMAC告警Webhook及不污染正式告警的接收器联通测试、三类Grafana仪表盘、证书到期监测、OIDC/方舟/RTC外部基础设施探针、本地密钥轮换、生产配置拒绝启动门禁、全部本地专项容量、隔离恢复、供应商故障、安全扫描及Chrome/Edge兼容均通过；主要业务核心包已达到70%覆盖率，供应商客户端达到关键分支85%目标 | 全仓覆盖率及HTTP公共层仍低于需求目标；真实告警网关和值班组映射、生产等价容量、云密钥托管和Safari仍待完成 |
|
||||
| 第八阶段：联调试点与上线 | 本地准备完成，外部联调待执行 | 外部依赖预检、联调问题门禁、候选验收快照、阻断告警定位、接收器联通测试、内容安全TLS预检和按业务时区生成的试点日/周报均已形成可执行入口；本地真实OIDC、Worker、HMAC验签接收、六项技术门禁及日/周报下载通过 | 远程CI、真实投诉证据、告警网关和值班组映射、真实供应商/真机联调、家庭试点、预生产演练和生产发布 |
|
||||
|
||||
## 本轮验证记录
|
||||
|
||||
| 检查项 | 结果 |
|
||||
|---|---|
|
||||
| Go格式、`go vet`和单元测试 | 通过 |
|
||||
| OpenAPI生成React类型 | 通过 |
|
||||
| TypeScript类型检查和Vite生产构建 | 通过 |
|
||||
| npm依赖审计 | 0个已知漏洞 |
|
||||
| 当前轻量功能验收 | Web、API、Callbacks、Worker和模拟供应商入口均返回200；owner/editor/outsider三类OIDC账号映射与权限正确；完整语音状态链、终稿/内容/记忆闭环及家庭—长者—事实—授权SaaS操作链均通过，合成数据已清理 |
|
||||
| 角色化工作台导航 | 登录后由统一业务导航按需挂载家庭业务、运行配置、费用额度、告警处置和联调诊断；普通客户账号仅显示家庭业务，运营账号按角色显示运营入口，避免五个大型页面同时请求和无权限空页面；生产构建、容器更新及Web/API/Callbacks/Worker就绪检查通过 |
|
||||
| 登录会话续期 | Web已启用OIDC访问令牌提前60秒自动续期；续期成功由用户加载事件刷新服务端权限快照，续期失败或令牌过期时立即隐藏业务工作台并提示重新登录，避免继续展示过期权限和连续401；生产构建及容器资源生效检查通过 |
|
||||
| 页面请求超时与取消 | 所有健康、查询和写操作统一设置15秒请求超时，页面切换或组件卸载仍可主动取消；超时显示稳定中文提示并释放按钮忙碌状态，避免依赖异常时无限等待和重复提交；生产构建、Web容器资源及API就绪检查通过 |
|
||||
| Web静态交付策略 | 哈希JS/CSS资源返回一年缓存，`index.html`返回`no-cache`以便及时加载新版本；网页资源增加CSP、`DENY`防嵌套、`nosniff`、来源和摄像头/定位/麦克风权限策略，API代理保持原有响应头；Compose容器内`nginx -t`、Web反向代理和API直连就绪检查均通过 |
|
||||
| Web运行时环境配置 | Web容器启动时根据`WEB_OIDC_AUTHORITY`和`WEB_OIDC_CLIENT_ID`生成不缓存的`runtime-config.js`，本地保留安全默认值；同一镜像可在dev/preprod/prod覆盖公开OIDC配置，无需修改源码或重新构建，HTTPS OIDC和对象存储已纳入CSP；自定义值和Compose默认值均完成容器内生成验证 |
|
||||
| 后续验证策略 | 保留身份、权限、通话状态、删除、供应商回调等高风险门禁；停止单纯为覆盖率补低价值测试，功能变更后只运行相关包、主链冒烟及一次发布前全量检查 |
|
||||
| 轻量功能就绪脚本 | `scripts/check-functional.ps1`固定检查九个必要服务、五个HTTP就绪/存活端点、API与Worker依赖指标、Outbox积压和近期错误日志；日常开发默认执行该脚本及变更模块定向测试，`scripts/check.ps1`仅用于发布候选和CI全量门禁 |
|
||||
| 录音上传队列可视化 | 终端心跳和批量遥测均可上报待上传数、失败数、最近失败码和失败时间；设备影子接口返回脱敏最近错误，家庭端设备卡片显示无积压、待上传或失败状态及原因。OpenAPI 0.31.0类型生成、相关Go包定向测试、TypeScript检查和生产构建均通过 |
|
||||
| 联调握手阶段耗时 | 诊断查询从通话权威创建时间和状态历史计算房间资料签发、设备入房确认、智能体启动、智能体停止和全程耗时；缺失或时间倒置的阶段不伪造数值。OpenAPI 0.32.0与React联调卡片同步展示，固定时间数据库集成用例验证250毫秒和2000毫秒阶段结果 |
|
||||
| 短期凭证时间元数据 | V28只保存短期入房凭证签发时间和过期时间，不保存凭证正文；创建通话按实际Token TTL写入，联调查询和页面展示两个时间点。数据库约束保证过期晚于签发，OpenAPI 0.33.0不暴露完整凭证 |
|
||||
| 短期凭证迁移验证 | V28正向升级、单版本回退至`27|false`及重新升级均通过；回退后两个字段为0个，重升后为2个，过期不晚于签发的异常记录为0，最终数据库为`28|false` |
|
||||
| 心跳短期凭证续签 | 设备心跳上报当前凭证过期时间；进入续签窗口后，服务端原子轮换时间元数据并返回`renew_rtc_credential`及新的房间绑定短期凭证。响应丢失时旧过期时间会触发同一确定性凭证重放；签名失败会回滚心跳序号和时间元数据。OpenAPI 0.34.0、模拟终端和本地冒烟请求已同步 |
|
||||
| 通话历史筛选与分页 | 家庭端通话记录现可按长者、八种通话状态、三种语音处理方式及起止日期组合筛选；首批加载20条，使用服务端签发的HMAC游标继续加载并在页面端去重，不拼接或解析游标。筛选变化会清理不再匹配的详情；SSE实时状态刷新只更新列表和业务数据，不再把用户正在查看的通话详情清空。前端类型检查、生产构建和容器运行检查按轻量策略执行。 |
|
||||
| 首次创建家庭 | 家庭工作台补齐后端既有`POST /api/v1/households`的网页入口；无家庭账号可选择自己已有的客户组织并创建第一个家庭，创建事务同步建立所有者成员关系，页面随后重新读取服务端家庭清单并自动选中新家庭。已有家庭账号也可从折叠入口新增家庭，输入最长200字符且不接受空白名称；真实本地OIDC正向请求已验证创建响应、所有者角色和列表可见性，临时家庭及审计夹具随后按公开编号清理为0。 |
|
||||
| 长者背景进入新通话 | OpenAPI 0.35.0明确背景、兴趣、交流目标、节奏和优先话题五类白名单字段；家庭端创建和强ETag修订均可维护这些资料。创建通话时按档案版本读取并冻结白名单上下文，内部备注和设备技术目标不会进入语音提示；Worker向供应商启动时使用同一冻结文本，提示明确背景资料不是可执行指令。真实PostgreSQL定向用例验证背景、目标、兴趣、节奏、话题及非白名单排除；真实OIDC HTTP验证创建后以`If-Match: "v1"`修订为v2，临时档案和审计夹具清理为0，运行Web容器已包含创建与修订界面。 |
|
||||
| 首次通话就绪清单 | OpenAPI 0.36.0新增按长者读取的服务端就绪检查，依据当前档案、授权快照、有效绑定、设备注册/固件上报、配置版本和最近联系事实给出阻断项与提醒项；家庭工作台直接展示清单并跳转到档案授权或设备修复入口。额度、生产路由和并发通话只在真正创建通话时原子校验，页面明确不把瞬时结果误报为保证。按轻量策略仅执行该读取接口的真实PostgreSQL定向用例、TypeScript检查、生产构建及一次功能就绪检查。 |
|
||||
| 故事来源跳转 | 故事审核详情使用服务端返回的稳定`conversation_id`提供“查看完整原始通话”入口；跳转后直接读取该通话详情、完整最终话轮、摘要、用量和当前用户可访问的录音状态，审核人员无需根据标题或时间猜测来源。变更只涉及React交互，按轻量策略执行TypeScript检查、生产构建和运行容器资源检查。 |
|
||||
| 最低固件版本门禁 | V29为设备新增独立`minimum_firmware_version`，不再把`minimum_security_version`安全基线标识误作固件版本。设备引导明确返回兼容结果；创建通话在任何房间或供应商任务产生前按同一规则拒绝不兼容设备并返回HTTP 426及`FIRMWARE_UPDATE_REQUIRED`；家庭就绪清单和设备卡片同步显示策略。SemVer按标准顺序比较，非SemVer厂商版本仅允许精确匹配。V29单版本回退/重升、版本比较、设备引导、通话门禁、就绪查询和前端构建均按定向策略通过。 |
|
||||
| 模拟录音删除闭环 | 模拟终端`media`场景在对象直传后轮询云端批次，只有分片进入`VERIFIED`且到达`local_delete_after`才释放内存副本并提交`DELETED`回执；校验失败、超时和超过等待窗口均给出明确结果，不删除`SIM_MEDIA_FILE`源文件。`MEDIA_LOCAL_DELETE_GRACE`默认1小时、本地Compose为1秒，便于轻量联调而不改变生产安全默认值。 |
|
||||
| 联调问题清单 | OpenAPI 0.38.0和V30新增客户组织隔离的问题清单，按需求P0282保存问题现象、设备/通话/请求编号、发生时间、责任方、解决结果和回归结论。创建使用幂等键，维护使用强ETag；已解决状态必须填写解决结果，已验证或已关闭还必须填写回归结论。运营诊断工作台支持登记、筛选、接手、解决、回归、关闭和重新打开，记录不复制字幕或录音正文。 |
|
||||
| 背景资料准备失败闭环 | OpenAPI 0.39.0和V31落实需求P0285：SaaS授权、固件、额度和路由校验通过后，若Agent背景白名单资料存在不可解析类型，平台仍在同一事务内保存`FAILED/context_preparation_failed`通话与失败快照，不创建RTC任务、不冻结用量预算、不投递启动事件。设备得到不可自动重试的HTTP 422及通话编号；同一幂等键重放同一结果。家庭通话详情和运营诊断工作台展示相同稳定失败码。按低强度策略仅执行背景字段解析与HTTP映射单测、V31迁移、前端类型/构建和一次真实HMAC+OIDC纵向烟测，夹具已恢复清理。 |
|
||||
| 活动通话授权撤回停止 | OpenAPI 0.40.0落实需求P0287：撤回活动通话冻结快照正在使用的字幕、原录音、故事整理或个性化记忆授权时，SaaS撤回事务同步写入`STOPPING`状态、状态历史、脱敏原因和唯一`conversation.agent_stop_requested`可靠待办；预留房间尚未启动Agent时直接过期。Worker按固定供应商任务完成停止，设备心跳或遥测从PostgreSQL权威状态取得停止动作；家庭分享撤回不打断语音。按轻量策略验证相关Go包、OpenAPI类型、前端构建和一次真实OIDC+设备HMAC+模拟供应商纵向链路。 |
|
||||
| 设备v2兼容与终端媒体不变量 | OpenAPI 0.41.0和V32落实P0280/P0281：接口变更说明与契约版本同步，CI比较目标分支并拒绝破坏性变化；同一v2内只用可选能力位启用新动作，不按固件版本或User-Agent猜测。`rtc_credential_renewal`在通话创建时冻结，旧终端省略后不收到未知续签动作；`engine_mode`只供云端诊断、成本和记录，模拟终端不解析、不据此改变采集或播放。按低强度策略只验证契约门禁、相关Go包、V32单版回退/重升、前端契约构建和一次轻量运行就绪。 |
|
||||
| 智能体启动失败设备收敛 | OpenAPI 0.42.0落实P0062：设备确认入房后通过独立只读接口取得权威状态与`wait/continue/leave_room`动作；供应商永久拒绝启动时，Worker同一事务写入`FAILED/provider_start_rejected`、RTC失败、状态历史和系统审计并结束可靠待办，异步失败沿用`provider_start_failed`。模拟终端不再用新幂等键重复激活，而是在`leave_room`时携稳定失败码退出。该批次复用既有表结构，无需新增迁移。 |
|
||||
| Agent固定评测与发布证据 | OpenAPI 0.43.0与V33落实P0252：新增版本化固定评测集、模拟供应商脱敏观测样例、SaaS证据采集器、评测执行器和受控登记命令，强制覆盖正常闲聊、长停顿、重复表达、姓名日期歧义、冲突事实、情绪话题、用户打断、网络波动、记忆召回和敏感信息十类场景。采集器使用OIDC权限读取每个用例的独立通话及最终话轮，自动计算完成状态、首答时延和最长回答，不复制字幕正文；称呼、记忆、虚构、来源和敏感处理必须由显式脱敏评分卡给出。登记前使用评测集和观测重新计算完整报告，再复核SHA-256和登记正文，为配置版本与报告生成确定性幂等键；任一输入单独篡改均拒绝发送，FAILED报告必须显式允许且不能满足发布门禁。服务端区分`GENERIC`与`AGENT_QUALITY_V1`，标准证据只能登记到Agent组合并校验报告元数据、十个以上用例、计数、全部质量指标及结论一致性；Agent组合发布仅接受标准`PASSED`，通用手工证据不能绕过门禁。模拟基线10/10通过；真实账号质量仍列为外部待验。 |
|
||||
| Agent质量证据迁移验证 | V33正向升级、单版本回退至`32|false`及重新升级均通过；回退后`evidence_type`字段不存在，重升后字段和枚举约束恢复，最终数据库为`33|false`。纵向验证确认通用`PASSED`发布返回409，标准证据首次登记201、完全重放200且仅一条记录，随后Agent组合发布成功，临时配置残留为0。 |
|
||||
| Agent组合组件引用门禁 | OpenAPI 0.44.0收紧P0214/P0254：四个组件字段必须是UUID，并在当前客户组织内分别指向已发布过的`PERSONA`、`VOICE`、`MODEL`和`ROUTING`不可变版本；提交审批保存组件校验快照，发布及回滚再次复核。错误类型、不存在、跨客户、草稿或待审批组件不能形成可发布组合；已被新版本替代的`RETIRED`组件仍可用于可追溯回滚。标准评测登记同时绑定目标组合编号和其`model_version_id`，另一组合或另一模型报告不能误用。真实OIDC纵向验证错误组件类型、错误组合绑定和错误模型绑定均返回400，正确证据首次201、重放200，组件快照4项并成功发布；临时配置残留为0。该批次不新增迁移。 |
|
||||
| Agent组合运行时生效 | OpenAPI 0.45.0完成P0212/P0214/P0240/P0254的运行时交接：新通话按“试验对象 > 设备组 > 客户组织”优先命中`default-agent-bundle`投放，从组合引用的已发布或已退役路由版本取得语音模式，并冻结组合公开编号；未命中组合时兼容旧`default-agent-routing`。Worker按冻结组合读取同租户、正确类型的人设、音色和模型组件，把四个组件版本、系统提示、表达风格、音色资源引用和模型资源引用交给供应商适配器。真实PostgreSQL定向用例已覆盖选择、冻结、`cascade`生效和完整启动参数传递；无数据库迁移。 |
|
||||
| 自定义Agent版本族投放 | OpenAPI 0.46.0修正运营发布到运行时选择的隐式键名依赖：`config_key`仅标识不可变版本族，运行时根据投放所绑定版本的`AGENT_BUNDLE`类型选择组合，不再要求键名必须为`default-agent-bundle`；未命中组合时同样按类型选择直接`ROUTING`投放作为兼容路径。范围仍按“试验对象 > 设备组 > 客户组织”，同范围按最近激活时间确定生效项。真实PostgreSQL用例使用自定义版本族键验证组合冻结、`cascade`和供应商参数传递；无迁移、无设备契约变化。 |
|
||||
| Agent组合结构化创建 | 运营页面不再要求手工填写四个组件UUID和组合JSON；按当前客户组织列出已发布或已退役的人设、音色、模型和路由不可变版本，优先自动选择最近发布项，明确标记退役版本并在缺少任一类型时禁用创建。切换客户组织会清理未提交表单，避免跨客户残留选择；服务端提交与发布门禁保持最终权威。该批次仅涉及React交互和文档，不改变接口或数据库。 |
|
||||
| 配置投放暂停与恢复 | OpenAPI 0.47.0与V34补齐运行配置投放止血能力：审批员/管理员可使用强`If-Match`暂停活动投放或恢复尚未被替代的暂停投放；暂停只阻止后续新通话命中，已创建通话继续使用冻结配置。恢复前复核配置仍为已发布、同键同范围无其他活动投放；新版本同时结束同范围活动或暂停旧投放，防止旧灰度复活。运营台账显示活动/暂停状态和行版本并提供对应操作。V34单版回退、重升、真实PostgreSQL服务状态机及HTTP纵向用例均通过；未修改设备端契约。 |
|
||||
| 外部依赖预检台账 | OpenAPI 0.48.0与V35把API/Worker周期探针结果写入平台级状态台账：记录进程、依赖、可用状态、检查时间、最近成功/失败、耗时、探针周期、连续失败次数和有限错误码，不保存端点、凭据或原始错误。进程启动会清理本进程已经停用的旧探针，页面超过三倍周期未更新时标记“结果过期”，避免把已停止进程的历史成功误作当前可用。联调诊断工作台向全部运营角色提供只读预检卡片；本地OIDC真实探针、V35回退重升、失败累计恢复和真实浏览器查询按轻量策略验证。 |
|
||||
| 联调问题验收证据门禁 | OpenAPI 0.49.0与V36在既有问题台账增加LOW/MEDIUM/HIGH/CRITICAL严重级别、根因、修复版本和脱敏回归证据；已解决、已验证状态分别执行必填门禁。清单接口基于当前客户组织全量记录汇总未关闭HIGH/CRITICAL，不受最近100条展示上限影响；诊断工作台展示严重问题、高优先问题和发布阻断状态。V36单版回退/重升、真实PostgreSQL状态机、真实OIDC HTTP闭环、Chrome页面及测试残留清理均按轻量策略通过，最终数据库`36|false`。 |
|
||||
| 发布候选验收快照 | OpenAPI 0.50.0新增运营侧可下载技术预检快照，不新增迁移。快照在幂等审计事务中冻结候选版本/镜像摘要、运行构建、数据库迁移、所选必需外部探针、联调问题、租户及平台级Outbox和未解决HIGH/CRITICAL告警，计算六项独立门禁与总结果；实验室允许开发构建，预发布/生产要求运行版本与候选一致且构建元数据完整。输出不含探针端点、凭据、原始错误或业务正文，并固定声明不替代真机、供应商、灰度和发布审批。真实PostgreSQL定向用例、真实OIDC HTTP创建/重放/跨租户拒绝、Chrome下载解析与轻量功能就绪检查均通过，夹具残留为0；当前本地快照如实被3条既有HIGH中间态告警阻断，需按告警处置流程复核后关闭，未被测试脚本伪造为整体可发布。 |
|
||||
| 验收快照阻断定位 | OpenAPI 0.51.0为技术验收快照增加最多100条阻断告警的公开编号、规则、级别、状态、关联资源及存在性证据，数量截断显式标记；不返回告警正文，也不因关联资源`MISSING`自动关闭。诊断页面在下载后直接展示六项门禁和阻断项，切换客户组织会清除旧结果。真实PostgreSQL定向用例用缺失合成通话验证`MISSING`关键失败分支；真实OIDC/Chrome先验证3条阻断定位，再确认其引用的合成通话、RTC任务和可靠任务均不存在，通过强ETag告警接口保留时间线并审计关闭，重新生成快照后六项门禁全部通过。无阻断时`blocking_items`固定返回`[]`而非`null`，下载夹具残留为0。 |
|
||||
| SSE事件刷新合并 | 家庭工作台不再让每条SSE事件分别触发成员、长者、授权、内容、设备和固件整套查询；事件刷新按2秒最小间隔合并，人工业务操作仍立即刷新，410过期游标也复用同一合并队列。真实OIDC Chrome连接中分散注入8条最小事件，形成5批、85个业务响应，0个HTTP失败/429，页面无错误，事件夹具残留0。 |
|
||||
| 告警Webhook通知 | 新告警与超时升级在告警事务内生成稳定去重Outbox任务；Worker支持HMAC-SHA256签名、2xx确认、网络/超时/408/425/429/5xx重试和永久4xx死信；空地址安全关闭。适配器、配置、真实PostgreSQL告警事务、Worker受控重放和四个应用就绪端点已完成轻量验证；真实网关仍需外部参数 |
|
||||
| Docker Compose配置解析 | 通过 |
|
||||
| 后端和Web容器镜像构建 | 通过 |
|
||||
| 空数据库迁移 | 成功到版本2，`dirty=false` |
|
||||
| PostgreSQL扩展 | `pgcrypto`、`vector`已启用 |
|
||||
| API、Callbacks和Worker就绪检查 | 均返回HTTP 200，PostgreSQL与Redis为`up`；三个命令入口均已抽取可测试装配函数，集成用例验证服务名、上下文和启动错误透传，三个命令包覆盖率均由0%提升到20% |
|
||||
| 交付与验收命令工具 | 固件签名工具已验证SHA-256、Manifest、Ed25519正向验签和篡改拒绝；SSE工具已验证Bearer、事件游标、`Last-Event-ID`重连、非200和取消；模拟终端已验证请求摘要/签名头、幂等键、WAV头和错误响应；模拟供应商已验证配置拒绝及随机端口优雅启停，四个命令包覆盖率为33.3%/57.7%/27.9%/67.7% |
|
||||
| Web、MinIO和Keycloak访问 | 均返回HTTP 200 |
|
||||
| 数据库迁移 | 成功到版本4，`dirty=false` |
|
||||
| OIDC真实签名令牌 | `owner/editor/outsider`均通过签名、签发方、使用对象和有效期验证 |
|
||||
| 未登录和伪造令牌 | 均返回HTTP 401及稳定错误码 |
|
||||
| 客户组织隔离和角色权限 | 跨租户、查看者管理和家庭角色隐式录音访问全部被拒绝 |
|
||||
| 当前账号与权限快照 | `/api/v1/me`已覆盖未认证401、所有者账号200、未建档账号403及数据库故障500；账号、角色与家庭能力快照响应新增`Cache-Control: no-store`，避免认证态权限信息被中间缓存 |
|
||||
| 幂等执行 | 重放返回原结果；请求摘要冲突被拒绝；5个并发请求只执行1次 |
|
||||
| 事务审计 | 业务回滚时审计同步回滚，业务提交时同步提交 |
|
||||
| outbox可靠待办 | 去重、正文冲突、领取、完成和死信测试通过；容器Worker实测完成事件 |
|
||||
| 核心模块集成覆盖率 | 身份85.5%、幂等75.6%、审计72.7%、outbox75.5% |
|
||||
| 接口治理单元测试 | ETag并发控制100%、统一JSON响应封装100%、签名游标78.1%；HTTP公共层当前整体56.8% |
|
||||
| Redis限流集成测试 | 突发限额、拒绝和令牌恢复通过，覆盖率81.2% |
|
||||
| 可观测性容器烟测 | 三个服务就绪；Prometheus三个target均为`up=1`；Collector收到Span；日志包含trace/span编号 |
|
||||
| Worker积压指标 | pending、processing、dead三种状态均可抓取 |
|
||||
| 设备与通话迁移 | 主库到版本5且`dirty=false`；临时空库完成1—5全量升级、版本5回退及重新升级 |
|
||||
| 通话状态机 | 主路径、准备失败、预留过期、启动失败、供应商同步/异步启动与停止、未知启动对账、主动结束、运行中失败、重复事件和终态防回退测试通过；供应商故障进入停止状态时允许空设备停止原因并使用受控原因继续收口 |
|
||||
| 模拟设备夹具 | 合成设备、长者、当前绑定、设备影子和测试授权可重复初始化 |
|
||||
| 设备身份与租户隔离 | 签名正文篡改、过期、重放、吊销和依赖故障分支有测试；跨租户配置查询被拒绝 |
|
||||
| 设备启动纵向烟测 | Compose模拟设备使用真实HMAC和Redis nonce访问`bootstrap/config`均返回200，设备报告写入PostgreSQL |
|
||||
| 设备接口契约 | OpenAPI 0.7.0可生成React类型；创建、激活、心跳、停止及回调契约均已冻结 |
|
||||
| 通话创建集成测试 | 同键重放只创建1条通话、2条状态历史、1次审计和1个outbox事件；不同正文冲突；数据库不保存完整短期Token |
|
||||
| 通话创建HTTP烟测 | 真实设备签名两次请求均为201，第二次标记重放，通话编号和Token一致；状态`ROOM_ISSUED`且RTC任务仅为`ALLOCATED` |
|
||||
| 通话激活集成测试 | 校验设备归属、房间/用户、预留期限和配置版本；首次激活仅创建1个固定供应商启动待办，重复激活不重复投递 |
|
||||
| 模拟供应商与启动回调 | 固定任务编号幂等启动；回调先验签再解析；相同事件重放成功，不同正文冲突，过时事件不导致状态回退 |
|
||||
| 通话激活HTTP纵向烟测 | 创建201、激活202、同键重放带标记；Worker调用1次；模拟供应商发送2次相同回调但仅落1条事件；最终通话和RTC任务均为`ACTIVE` |
|
||||
| 激活链日志与敏感信息 | 两次回调请求均有独立请求/追踪编号；API、Callbacks、Worker和模拟供应商日志未发现设备密钥或RTC Token |
|
||||
| 心跳数据库集成测试 | 严格递增序号续租；旧序号不更新租约；设备报告版本高于期望版本被拒绝；设备影子只前进不回退 |
|
||||
| 心跳Redis集成测试 | Lua仅接受更大序号，同时更新通话租约与设备在线状态；乱序刷新不能覆盖较新状态 |
|
||||
| 心跳HTTP纵向烟测 | 真实设备签名返回200和`continue`动作；PostgreSQL/Redis均为序号2；随后序号1安全返回且数据库租约时间不变 |
|
||||
| 主动停止集成测试 | 首次停止只产生1个供应商待办和1次审计；同键重放返回原结果；重复结束回调仅落1条事件，最终状态不回退 |
|
||||
| 完整通话HTTP纵向烟测 | 六段状态链`PREPARING → ROOM_ISSUED → STARTING_AGENT → ACTIVE → STOPPING → COMPLETED`通过；Start/Stop各调用1次，热租约最终释放 |
|
||||
| 后台异常回收集成测试 | 预留到期自动EXPIRED；租约到期自动STOPPING；卡在启动/停止的任务按时间桶投递幂等对账；4次恢复均形成系统审计 |
|
||||
| 供应商失败回调集成测试 | `STARTING_AGENT`收到签名失败事件后，通话和RTC任务均进入`FAILED`；`ACTIVE`运行中失败进入`STOPPING`并可靠调用供应商停止，重复失败回执保持幂等且保留可诊断失败码；终态不回退 |
|
||||
| 后台异常回收容器烟测 | 人工将合成房间预留设为过期后，5秒扫描周期内收敛为`EXPIRED|COMPLETED`并生成1条`conversation.recovery`审计 |
|
||||
| SaaS核心迁移 | 主库到版本6且`dirty=false`；临时空库完成1—6升级、版本6回退及重新升级，新增档案字段、稳定事实和分项授权表 |
|
||||
| 家庭与长者服务集成测试 | 所有者创建/修改、编辑者写长者、跨租户拒绝、旧ETag冲突、事务审计及合成数据清理均通过 |
|
||||
| 分项授权服务集成测试 | 同类型有效授权唯一性在长者行锁事务中保证；授权追加、重复阻止、撤回幂等、历史查询及两版不可变快照均通过 |
|
||||
| SaaS接口契约 | OpenAPI 0.13.0覆盖家庭、成员协作、长者、授权、设备、通话内容、故事审核、记忆管理、隐私数据访问、私有导出和主体删除接口，可生成React类型 |
|
||||
| SaaS HTTP纵向烟测 | 真实OIDC令牌完成家庭创建、403隔离、角色拒绝、412旧版本、长者创建/修改、授权/重复/两次撤回和快照计数，测试数据已清理 |
|
||||
| 设备绑定迁移 | 主库到版本7且`dirty=false`；临时空库完成1—7升级、版本7回退及重新升级；绑定码仅保存SHA-256摘要 |
|
||||
| 稳定事实闭环 | 模型候选与家庭事实独立保存来源、确认状态、敏感等级和版本；确认缺少来源被拒绝，旧ETag写入返回412 |
|
||||
| 设备管理服务 | 家庭内列表/详情、Redis在线状态与数据库降级、设备影子读写、非敏感配置白名单、敏感字段递归拒绝和事务审计均通过 |
|
||||
| 一次性设备绑定 | 跨租户403、首次绑定、完全相同目标安全重试、单设备唯一有效绑定和历史绑定保存通过；烟测后绑定及审计已清理 |
|
||||
| 通话查询工作台 | 长者维度游标分页、条件过滤、脱敏详情、冻结快照摘要和六段状态历史已实现；真实OIDC烟测验证跨租户403并清理合成数据 |
|
||||
| React SaaS业务页面 | 完成家庭切换、长者档案、事实登记/确认、五类授权/撤回、设备绑定、在线状态、孪生配置、通话列表/详情和只读权限交互；生产构建与容器重建通过 |
|
||||
| 家庭成员协作 | 一次性邀请创建/撤销/接受、跨客户组织受邀账号映射、成员列表、角色强ETag、成员移除、所有者保护及双向所有权转移均通过集成测试和真实OIDC烟测；邀请复用失败审计已验证 |
|
||||
| 内容与记忆迁移 | 主库到版本8且`dirty=false`；临时空库完成1—8全量升级、全部回退及重新升级，九张内容与记忆表完整，验证库已删除 |
|
||||
| 隐私请求迁移 | 主库到版本9且`dirty=false`；独立临时空库完成1—9全量升级、`down -all`和重新升级，最终`9|false`，验证库已删除 |
|
||||
| 私有导出迁移 | 主库到版本10且`dirty=false`；独立临时空库完成1—10全量升级、`down -all`和重新升级，最终`10|false`，验证库已删除 |
|
||||
| 设备命令迁移 | 主库到版本11且`dirty=false`；V11已完成单版本回退及重新升级，最终`11|false` |
|
||||
| 最终转写接入 | 签名回调支持最终话轮；正文只在冻结字幕授权允许时保存；按业务键去重，同键不同内容冲突；供应商事件正文不复制转写内容 |
|
||||
| 终端终稿补传 | `POST /device/v2/conversations/{id}/turns:batch`已实现设备归属、状态、留存模式和当前授权校验；1—500条批量终稿按业务键原子合并，完全相同计为重复、不同内容整批409回滚；幂等重放、越权设备、禁止留存和内容再提取事件均通过HTTP单元测试及真实PostgreSQL集成测试 |
|
||||
| 设备批量遥测 | V24新增设备遥测事件历史及设备影子单调序号/最近错误快照；`POST /device/v2/telemetry:batch`原子处理状态、有限错误码和命令结果，验证关联通话归属、阻止旧状态覆盖和敏感结果字段，返回配置刷新/拉取命令/停止通话动作；V24回退重升、真实PostgreSQL集成测试及签名HTTP烟测均通过并清理夹具 |
|
||||
| 可运行模拟设备 | `SIM_SCENARIO`现支持启动/配置、断网后新Nonce重连、完整通话、创建/停止/字幕/遥测幂等重放、字幕补交、遥测、命令结果和授权录音直传；Compose组合场景实测最终通话/RTC均COMPLETED、Start/Stop各1次、3条话轮、1条关联遥测、开放Outbox为0，验证夹具已精确清理 |
|
||||
| 可重放供应商通知样例 | 模拟供应商新增API Key保护的`POST /mock/v1/admin/replay`，对已启动任务稳定重放任务开始、最终字幕、智能体回答、被打断、用量、错误和停止七类脱敏通知，并可控制1—10次完全相同投递；样例字段、打断标志、用量结构、签名及重复投递均有单元测试 |
|
||||
| 摘要与候选生成 | 默认本地确定性适配器和可配置火山方舟Chat Completions适配器均只使用长者话轮；模型网络调用位于数据库事务外，返回后短事务复核状态、授权和话轮SHA-256指纹；生产内容安全采用本地高风险前置拦截+托管HTTP策略，输入生成前与模型输出落库前双检，BLOCK/REVIEW转受控提示，外部故障安全重试且不落库；生产配置拒绝本地策略、HTTP端点和占位密钥。相关轻量测试及真实PostgreSQL组合验证通过，真实账号策略效果待验收 |
|
||||
| 生产记忆Embedding | API查询与Worker索引共用可配置本地/方舟Embedding提供器，方舟协议调用`${ARK_BASE_URL}/embeddings`并请求、强校验1536维float向量；索引在事务外生成向量后短事务复核版本、状态、授权和普通敏感级别；查询向量在通话事务前生成，临时失败无记忆降级但不阻断通话；顺序幂等重放和同键冲突不重复调用Embedding。协议、维度拒绝、数据库无长锁、单次计费语义及本地主链已完成轻量验证，真实召回质量待验收 |
|
||||
| 火山RTC生产适配 | API新增官方二进制正式Token生成器，按房间/用户/到期时间确定性重建且不持久化短期Token；Worker新增AK/SK签名的`StartVoiceChat/StopVoiceChat`适配器，动态覆盖AppId/RoomId/TaskId/设备与Agent用户并追加授权背景，`Result=ok`或稳定TaskId已启动均收敛为ACTIVE，限流和服务端错误可重试，生产配置拒绝本地Token与Mock协议。完成Token格式/签名、协议映射和关键错误分类轻量测试，真实入房、可选供应商事件细分和计费仍待账号联调 |
|
||||
| 三种语音处理方式路由 | 通话事务从活动运营投放冻结`s2s_pure/s2s_hybrid/cascade`，StartProcessor读取冻结值并传给供应商；火山适配器支持`voice-chat-template-bundle-v1`逐模式选择，生产Worker要求三模板齐全，生产API缺少活动路由时返回503而不再静默回退。三个模板选择、缺失模板拒绝、路由缺失门禁和数据库到供应商请求传播的相关测试通过；三种真实供应商Config及音质/费用仍待账号验收 |
|
||||
| 逐设备生产密钥 | 新增受控目录型设备密钥解析器，数据库只保存`device-secret://<name>`；解析器限制单层安全名称、解析后根目录约束、4KiB上限和32字节下限，每次请求读取以支持Secrets/KMS CSI原子轮换；生产API拒绝单一静态开发密钥。本地解析、隔离、短密钥拒绝和无需重启轮换测试通过，真实KMS CSI挂载和量产注入仍待外部环境 |
|
||||
| 通用Secrets文件注入 | 数据库连接串、Redis、RTC AppKey、火山AK/SK/临时Token、方舟、对象存储和各类签名密钥支持`NAME_FILE`绝对路径读取；普通文件与64KiB上限校验、末尾换行处理、NUL拒绝及明文/文件双源冲突拒绝在依赖连接前执行。文件读取与冲突轻量测试通过，云KMS工作负载身份和真实CSI轮换仍待外部环境 |
|
||||
| Kubernetes生产部署基线 | 新增API、Callbacks、Worker、Web的Kustomize基线和stage/prod覆盖层，独立数据库迁移镜像与Job，预创建Secret只读挂载、逐设备密钥目录、启动/存活/就绪探针、Prometheus Pod发现注解、只读根文件系统、非root、资源限额、滚动发布、拓扑分散、PDB/HPA、TLS Ingress及默认拒绝入口网络策略；清单已完成本地渲染与对象结构校验，不包含真实密钥，真实集群、Ingress、Metrics Server、CSI和外部依赖仍待环境验收 |
|
||||
| 外部基础设施探针 | API周期读取并验证OIDC JWKS状态、JSON结构和非空密钥集；启用方舟的API/Worker及启用火山RTC的Worker仅执行DNS、TCP和证书校验TLS握手，不消耗模型或语音额度；结果同时进入Prometheus指标和V35脱敏预检台账，连续5分钟失败触发CRITICAL告警但不影响readiness。本地Keycloak真实探针指标及运营页面均可见，方舟/RTC目标仍待生产网络验证 |
|
||||
| Secrets Store CSI部署模式 | 新增生产应用和数据库迁移CSI覆盖层，API/Callbacks/Worker按职责挂载六个同命名空间`SecretProviderClass`，不使用`subPath`，迁移Job直接从文件读取数据库连接串；提供器参数、工作负载身份、轮换版本和真实挂载仍待目标云KMS/Secret Manager环境验证。逐设备密钥可按请求读取轮换值，其他启动期密钥明确要求轮换后受控滚动重启 |
|
||||
| 内容安全基线 | 故事生成前识别验证码、支付账户和高敏感医疗关键词；命中时不复制敏感正文到摘要，不生成普通故事/事实候选；规则单元测试及带银行卡号/验证码的真实提取集成测试通过，生产内容安全服务仍待接入 |
|
||||
| 故事人工审核 | 查看、人工修订、确认和拒绝接口均已实现；来源必需、角色权限、强ETag、版本留痕和事务审计门禁通过端到端验证；新增真实PostgreSQL集成测试覆盖摘要来源、故事/事实读取、人工修订、旧版本冲突、来源复制、确认门禁及终态重复确认拒绝 |
|
||||
| 已确认记忆与索引 | 人工确认前记忆数为0；确认且个性化记忆授权有效后才创建版本化记忆；Worker完成1536维本地开发索引；修订生成新版本并使旧索引失效；停用和授权撤回会清空向量、标记索引失效；新增集成测试验证确认生成、关键词检索、跨成员隔离、内容修订、无变化拒绝及停用索引失效 |
|
||||
| 记忆可靠删除 | 删除接口先将记忆置为`PENDING_DELETE`并立即移出召回；Outbox后台把本地索引置为`DELETED`、清除所有记忆版本正文、完成删除审计；页面可提交删除并显示处理中状态；删除申请及终态幂等重放已纳入真实数据库回归 |
|
||||
| 新通话记忆召回 | 通话创建使用服务端固定租户和长者边界检索；同时过滤当前授权、活动状态、当前版本、普通敏感级别、有效期和活动索引；实际记忆版本与`minimal-v2`程序版本冻结到背景快照；真实pgvector测试验证普通记忆命中、敏感记忆排除、跨长者隔离和非法limit拒绝，召回模块覆盖率81.2% |
|
||||
| React内容审核页面 | 通话详情展示摘要和最终话轮；故事与记忆页展示来源、事实、记忆搜索、人工修订/确认/拒绝、记忆修订/停用/删除及索引状态；查看者审核控件禁用；TypeScript和生产构建通过 |
|
||||
| 内容端到端烟测 | 重复最终转写仅落2条话轮，生成2类整理结果和1个故事候选；人工确认后索引`ACTIVE`且下一次通话冻结1个记忆版本；修订形成第2版，停用和永久删除后新通话召回均为0；删除正文和索引状态已验证；跨租户403；测试后内容残留0且Outbox无pending/processing/dead |
|
||||
| 隐私数据访问闭环 | V9迁移建立请求、子任务和最小删除证明表；所有者提交、编辑者拒绝、幂等重放/冲突、Worker状态收敛、请求范围过滤和`content_included=false`均通过真实OIDC HTTP烟测 |
|
||||
| 私有数据导出 | V10迁移建立导出任务；Worker按冻结范围生成JSON并写入MinIO私有桶；未签名访问403、短期URL下载、SHA-256校验、所有者/编辑者权限、幂等重放和过期删除均通过HTTP烟测；真实PostgreSQL集成测试进一步覆盖范围化制品、摘要、READY、重复处理和到期清理，不存在任务的迟到Outbox事件已修正为安全空操作 |
|
||||
| 主体级隐私删除 | 精确称呼确认、活动通话409保护、受理事务立即冻结、授权撤回/记忆失效、Redis/MinIO/pgvector/供应商引用/PostgreSQL六子系统可重试对账和无正文墓碑已实现；临时主体真实OIDC烟测通过并清理 |
|
||||
| 设备命令可靠链路 | V11迁移、家庭端幂等排队、设备HMAC拉取、重复投递、ACK/成功/失败回执、过期终态和Web诊断入口已实现；真实本地OIDC+设备签名烟测通过并清理；新增处理器用例覆盖终端鉴权、命令拉取、可重试依赖失败、回执参数归一化、状态冲突及结果摘要透传；设备核心包进一步覆盖命令到期、首投/重投、ACK、成功/失败终态不可变、跨设备拒绝和非法正文，覆盖率75.5% |
|
||||
| 固件安全发布 | V12迁移建立受信Ed25519公钥、固件版本、灰度批次和设备分配；合法签名与摘要校验、非法签名409、暂停取消未投递命令、暂停后下载拒绝、已验证版本回滚、设备下载摘要及最终状态收敛均通过本地OIDC+HMAC+MinIO烟测并清理；新增服务与HTTP集成测试覆盖公钥登记、发布准备/确认、对象摘要校验、设备范围下载、灰度启动和暂停 |
|
||||
| 固件进度与管理页 | V13迁移把分配状态细化为`ASSIGNED/DOWNLOADING/INSTALLING/CONFIRMED/FAILED/ROLLED_BACK`并保存进度和最近回执；版本/批次列表、逐设备详情、React公钥登记、制品直传、灰度、暂停和回滚已实现；25%下载、80%安装、100%确认的接口回归通过 |
|
||||
| 双轨录音上传与访问 | V14迁移建立上传批次、稳定分片、批次关联、PLAY/DOWNLOAD独立授权和访问日志；设备幂等清单、15分钟单对象直传、Outbox后台大小/SHA-256/WAV PCM16容器与时长校验、延迟本地删除、5分钟播放/下载、撤销与成功/拒绝审计均通过本地OIDC+HMAC+MinIO烟测；新增真实PostgreSQL服务集成测试覆盖上传重放、Worker验证、PLAY授权、DOWNLOAD拒绝、撤销及删除回执并精确清理夹具 |
|
||||
| 录音设备删除回执与管理页 | V15迁移保存本地密文删除结果、时间和错误码；过早成功回执409、失败后重试、成功幂等和云端对象状态不变均通过设备签名烟测。React通话详情支持双轨状态、PLAY/DOWNLOAD独立能力、5分钟播放/下载、按成员/用途/时限授权、有效授权列表和立即撤销 |
|
||||
| Web状态事件流 | V16迁移建立15分钟最小事件续传和设备在线状态表；会话、故事、媒体、导出、隐私、指令及设备上线/离线事件已实现。Bearer认证SSE、`Last-Event-ID`恢复、活动家庭成员过滤、跨租户/过期游标410、客户端去重和自动重连均通过烟测；新增真实PostgreSQL测试覆盖起始游标、有效/过期/跨用户游标、分页、过期清理及设备离线事件，模块覆盖率86.5% |
|
||||
| 具体资源分享 | V17—V18已建立分享授权、匿名口令摘要和访问日志；登录定向与匿名口令访问、单项权限、幂等重放、撤销、过期、跨租户隔离、故事共享编辑/412并发保护、React管理页和逐次审计均已实现并通过烟测；新增真实数据库集成测试覆盖登录定向转写分享、匿名令牌、错误令牌、接收人不匹配、幂等重放、撤销、故事修订/版本/撤销、匿名故事、录音试听/下载/授权撤回和成功/拒绝访问日志，模块覆盖率78.5%；HTTP层新增鉴权、UUID、幂等键、匿名口令、`If-Match`及全部分享错误映射用例 |
|
||||
| 资源分享迁移与页面验收 | V18单版本回退和重新升级均成功，最终`18|false`；实际Chrome 1280×900检查资源分享配置、登录/匿名提示和有效分享区，未发现横向溢出、控制台错误或失败请求 |
|
||||
| 运营身份与配置版本 | V19新增`customer/ops_viewer/ops_operator/ops_approver/ops_admin`平台角色和五类运行配置版本；草稿幂等、结构/敏感键校验、双人审批、单一发布版、旧版退役、不可变回滚、事务审计及新通话配置冻结均通过真实OIDC+设备HMAC烟测 |
|
||||
| 运营配置页面 | React工作台支持客户组织选择、五类配置JSON与密钥引用、草稿、审批/发布、回滚、版本历史和相邻版本正文对比；实际Chrome 1440×1100未发现失败请求、控制台错误或横向溢出 |
|
||||
| 运营配置灰度与发布门禁 | V20新增评测证据、受控资源引用、设备灰度组和投放台账；无通过评测、凭据/音色/模型引用缺失、类型错误、已撤销或核验超过180天均阻断发布；租户、试验对象、设备组范围可并存，同一目标只保留一个活动投放；新增服务及HTTP真实数据库测试覆盖草稿幂等、越权、提交ETag、创建人自批拒绝、评测创建/查询、发布门禁、双人发布、投放查询、旧投放退役、不可变回滚、资源引用和设备组的租户/版本/状态/非法输入分支，运营配置模块覆盖率74.5% |
|
||||
| 运行时灰度与影响控制 | 新通话按试验对象、设备组、租户优先级选择路由，设备组使用稳定哈希百分比分桶，并以冻结该配置版本的未结束通话数执行并发影响上限；真实设备HMAC烟测验证设备组优先命中、不可变回滚和背景快照版本冻结 |
|
||||
| 运营投放与资源页面 | React工作台新增资源登记/撤销、设备组创建、活动投放台账、评测证据、范围/比例/并发上限配置；实际Chrome 1440×1100整页检查无失败请求、控制台错误或横向溢出 |
|
||||
| 运营灰度迁移与清理 | V20完成单版本回退和重新升级；回退后恢复V19单发布版唯一索引并移除四类V20表，重升最终`20|false`；烟测后配置、投放、评测、资源、设备组、运营审计/幂等、分享、Web事件和Outbox open/dead均为0 |
|
||||
| 用量费用与额度迁移 | V21新增价格版本/费率、额度策略、通话用量、冻结费用行和预算快照六类表；单版本回退验证表已移除且版本为`20|false`，重新升级最终`21|false` |
|
||||
| 价格版本与核价 | 价格草稿幂等、创建人禁止自批、另一名审批人发布、旧版本退役和费用行版本/单价冻结已实现；七类用量使用精确十进制数量和微单位金额，真实签名回调验证总费用`CNY 0.132450` |
|
||||
| 用量回调幂等 | `voice_chat.usage / FINAL`先验签再校验；同一事件完全重放返回duplicate且费用仍为7条，同事件编号不同正文返回409，回调事件不复制用量明细正文 |
|
||||
| 额度与通话预算 | 客户组织/设备日月费用、并发和最长时长策略已实现；创建前按账期时区检查，达到硬额度返回429 `USAGE_QUOTA_EXCEEDED`；新通话冻结策略编号、限额、时长和在途动作 |
|
||||
| 费用展示与脱敏 | 运营周期汇总和家庭单通话用量接口均只返回标准化分类、数量、单位、费用和币种，不返回供应商任务/事件或内部价格编号；跨租户及非家庭成员访问返回403；新增HTTP真实数据库集成用例，覆盖价格版本创建/查询、创建人自批拒绝、双人发布、额度策略创建/查询、汇总时间参数校验及`no-store`响应 |
|
||||
| 用量费用运营页面 | React页面包含费用概览、七类费率草稿、双人发布、价格台账、费用构成、客户组织/设备额度和历史策略；实际Chrome 1440×1100未发现失败请求、控制台错误或横向溢出 |
|
||||
| 告警处置迁移 | V22新增版本化路由、有限时长静默、客户组织事件和不可变动作时间线四类表；活动路由和未关闭指纹使用部分唯一索引，迁移库最终为`22|false` |
|
||||
| 告警自动发现与归并 | Worker扫描死信、隐私删除超时、录音上传失败、固件灰度失败、日费用额度80%和语音任务卡滞；同客户组织同指纹事务加锁归并，重复命中只增加次数并刷新摘要 |
|
||||
| 告警升级与静默 | 活动路由冻结接收组、响应/升级时限和运行手册；超时追加`ESCALATED`动作；规则/分类/资源静默最长30天，静默不丢命中，撤销或到期后仍存在的信号自动`REOPENED` |
|
||||
| 告警人工处置 | `ops_operator`以上角色使用强ETag完成确认、缓解和关闭；首次确认记录负责人，每一步写动作时间线和事务审计；跨租户403、旧版本412、已关闭重发新事件均有纵向烟测；新增服务及HTTP真实数据库测试覆盖路由版本替换、静默幂等/撤销、运营范围/幂等头、缺失If-Match返回428、跨账号隔离、确认—缓解—关闭、过期版本、重复终态拒绝、告警归并、静默期间保留命中、撤销后重开及取消扫描，告警模块覆盖率73.4% |
|
||||
| 告警运营页面 | React工作台提供四项概览、状态队列、资源/请求/运行手册上下文、完整时间线、路由版本和静默管理；实际Chrome 1440×1200检查无失败请求、控制台错误或横向溢出 |
|
||||
| 告警接收器联通测试 | OpenAPI 0.52.0新增最近50次测试查询和活动路由测试创建接口；测试复用正式Webhook的Worker、HMAC、超时和重试分类，但使用独立Outbox事件且不写`alert_incident`。本地Compose新增验签接收器；真实OIDC纵向烟测确认`PENDING → DELIVERED`、唯一接收、幂等重放和测试数据清理，真实数据库接口测试及Chrome 1440×1200页面检查通过 |
|
||||
| 发布候选证据包基础闭环 | `cmd/release-evidence`初版使用`release-candidate-evidence-bundle-v2`清单：候选版本/构建摘要必须与六项门禁通过的技术快照一致，预发布/生产要求真实源提交；当时九类外部证据逐项登记`VERIFIED/PENDING/WAIVED`。`PILOT`包强制同租户、同候选版本/构建摘要、同IANA时区、一个已结束自然周的7份连续日报和1份完整周报，并保留`complaints/REQUIRED`；缺日、重复日、周中快照、跨租户/候选、时区/窗口或脱敏策略不一致均拒绝打包。当前格式已由后续真机固件门禁升级到v3和十类索引。 |
|
||||
| 试点运行日报 | OpenAPI 0.55.0要求候选版本和`sha256:`不可变构建摘要后，按IANA时区自然日生成脱敏运营日报，不新增迁移或服务端正文表。日报聚合设备在线、8类通话状态、供应商失败与通知积压、上传活动与积压、告警开闭和按币种费用；自然日活动与生成时刻状态分字段表达，不做汇率换算。候选身份进入响应、幂等和最小审计，并由PILOT证据包与验收快照强制匹配。时区/DST定向单测、Go包、前端构建、真实OIDC 7日报纵向链路和Chrome下载通过，烟测数据精确清理 |
|
||||
| 试点运行周报 | OpenAPI 0.55.0要求候选版本和`sha256:`不可变构建摘要后，按周一开始的七个IANA业务自然日生成脱敏周报，不新增迁移或服务端正文表。周报从审计事件和权威业务表汇总人工修订率及样本、故事确认/拒绝、正式记忆版本、隐私请求固定分布、固件版本和配置修订差异；周中快照明确标记不完整，无比例分母时显示不可计算。因平台没有投诉权威表，JSON与页面固定要求附客服/CRM证据。候选身份由PILOT证据包与验收快照及7份日报强制匹配；DST/周一/基点测试、真实OIDC周报与119文件打包、Chrome下载和缺口提示通过，烟测残留为0 |
|
||||
| 生产配置门禁 | `APP_ENV=prod`时拒绝HTTP OIDC、数据库明文传输、无Redis认证、对象存储非TLS、本地模拟供应商、占位密钥和API重复签名密钥；配置单元测试覆盖默认拒绝、合规通过和重复密钥拒绝 |
|
||||
| 1000活跃通话状态 | 950条健康租约保持ACTIVE；50条过期租约全部进入STOPPING；每条只形成一个停止意图，无重复任务，夹具已清理 |
|
||||
| 供应商回调长稳态 | 500次/秒持续10分钟，300000次请求、0%失败、0中断、p95 8.90ms、p99 11.81ms；300000个唯一事件全部处理/忽略，100组会话/RTC任务保持ACTIVE |
|
||||
| 普通API长稳态 | 固定50 RPS持续30分钟，90001次请求、0%失败、0中断、p95 3.67ms、p99 4.12ms、最大278.57ms；每次响应的PostgreSQL/Redis状态均为up |
|
||||
| SSE连接容量 | 500条认证SSE全部建立并保持5秒，50条使用`Last-Event-ID`断点重连成功 |
|
||||
| 媒体清单容量 | 10批×1000分片准确落库和关联；批量SQL优化后平均0.12秒、p95/最大0.16秒，API容器内存峰值15.8MiB |
|
||||
| 隐私删除并发 | 100个并发受理全部成功、HTTP失败率0%、提交p95 385.15ms；11.58秒内600个子任务、100个墓碑和100个主体冻结全部对账 |
|
||||
| PostgreSQL隔离恢复 | 实际`pg_dump`/`pg_restore`到随机隔离库，迁移`22|false`、66张表、190个外键和关键计数一致；本地约5.14秒，临时库/备份已清理 |
|
||||
| 进程与Redis恢复 | API/Callbacks/Worker重启恢复；停机期间Outbox仅执行一次；Redis 14个热状态键清空后由签名设备请求重建，PostgreSQL权威计数不变 |
|
||||
| 供应商故障恢复 | V23持久化按租户/供应商的可用状态；连续临时失败暂停新启动但停止任务继续尝试；演练确认暂停后新外呼0、停止尝试2次、历史接口200、CRITICAL告警出现，恢复后全部收敛；V23单版本回退/重升通过 |
|
||||
| 安全专项 | Go 1.26.6容器`govulncheck`可达漏洞0、npm高危审计0、最终镜像HIGH/CRITICAL已修复漏洞0、Gitleaks无泄漏；HTTP认证/授权/注入式输入/1MiB正文/回调签名/Nonce重放/安全头/日志过滤烟测通过 |
|
||||
| 压测与告警基线 | k6固定到达率门禁覆盖50 RPS/30分钟和500回调/秒/10分钟，阈值为错误率/p95/p99；Prometheus规则覆盖服务不可用、5xx、p95、Outbox积压/死信、隐私部分失败及固件失败/停滞 |
|
||||
| 浏览器兼容检查 | 实际Chrome 151和Edge 151在1440×1000、1024×900视口完成OIDC、运营工作台、认证SSE及8个SaaS页签检查；均为0横向溢出、0控制台错误、0失败请求，FCP分别124ms和116ms；Safari明确待macOS真浏览器补测 |
|
||||
| 分层限流与供应商容量 | 网络、OIDC用户、客户组织和设备令牌桶已独立实施；供应商启动另有RPS/突发门禁和PostgreSQL顾问锁保护的跨Worker活动任务上限；单元及集成测试通过 |
|
||||
| 供应商未知结果处理 | `UNKNOWN`启动任务先调用供应商查询；已活动则本地对账、仍启动则延迟确认，只有供应商确认404才使用原稳定任务编号重新启动；不再盲目换号重试。供应商HTTP客户端新增启动、停止、查询在成功、限流、5xx、永久错误、非法响应、网络中断和响应读取失败下的测试，包覆盖率90.4%，三类操作各90.5% |
|
||||
| 后台任务重试分类 | 普通业务错误和未注册处理器立即死信；仅显式临时错误、超时、网络中断、临时供应商/对象存储/数据库错误按指数退避和随机变化重试；真实PostgreSQL测试验证永久任务为`dead`、临时任务为`pending` |
|
||||
| 晚到终稿处理 | 供应商停止通知早于最终字幕时，原提取任务会等待；若终稿在通话终态后到达，则按通知摘要和最大话轮序号创建新的幂等提取版本；真实PostgreSQL顺序测试通过 |
|
||||
| 证书库存与告警 | V25扩展受控资源引用支持`CERTIFICATE`及到期时间；30天/7天分级到期告警、供应商通知积压告警和真实PostgreSQL安全事件测试通过；V25单版本回退及重升最终`25|false` |
|
||||
| 诊断作业恢复迁移 | V26为Outbox增加公开编号、人工重试次数、最近重试时间和操作人；V26单版本升级、回退到V25及重新升级均已通过，最终`26|false` |
|
||||
| 运营敏感数据临时访问迁移 | V27建立单通话限时申请和逐次访问日志；最长4小时、两类最小能力、同申请人/通话单一开放申请、申请人禁止自批；V27升级、单版本回退到V26及重升最终`27|false` |
|
||||
| 监控仪表盘 | Compose已装载Grafana 12.2.0，业务/技术/安全三个仪表盘均已发现；Prometheus对API、Callbacks、Worker三个目标均为`up` |
|
||||
| 本地长期密钥轮换 | 新设备签名密钥通过环境注入生效、旧密钥401、镜像摘要不变，演练完成后原本地密钥和API服务已恢复；不宣称替代生产KMS/HSM验证 |
|
||||
| 集成诊断工作台 | OpenAPI 0.34.0和React工作台支持五类精确检索、短期凭证时间元数据、握手阶段耗时、配置刷新、安全停止、状态对账、管理员设备吊销、已注册死信受控重试和脱敏JSON诊断包；活动设备被吊销时同步进入可靠停止，未知事件类型不允许人工重试；真实数据库用例覆盖精确检索、时间元数据、配置刷新、受控停止和对账 |
|
||||
| 敏感数据临时提权 | React工作台和API支持单通话字幕读取/录音播放申请、另一人审批、申请人绑定、到期自动失效、原录音授权复核、5分钟播放地址及逐次成功/拒绝审计；新增HTTP真实数据库纵向用例覆盖申请、幂等重放、审批队列、另一人批准、受控字幕、短时录音地址及全部稳定错误映射，处理器覆盖率72.2%—100%，夹具已清理 |
|
||||
| Web容器安全基线 | Trivy发现原Web镜像root运行和旧Nginx/Alpine高危漏洞后，已改为UID 101、8080非特权监听、Nginx 1.30.4及构建时系统补丁；配置误配和最终Web镜像HIGH/CRITICAL复扫均为0 |
|
||||
| CI供应链门禁 | 工作流已加入固定版本/摘要的govulncheck、go-licenses、npm audit、前端许可证检查、Gitleaks、Trivy配置/镜像扫描、Syft CycloneDX SBOM及不可变构建元数据；新增离线一致性校验器把完整提交、远程运行、14项检查、后端/Web镜像摘要和三份SBOM绑定为不可豁免报告，本地工具链保持`external_validation_required=true`；Go 1.26.6容器漏洞扫描、Gitleaks及最新Worker/Callbacks镜像HIGH/CRITICAL扫描均为0，仍待远程托管CI固定候选运行 |
|
||||
| 全仓质量门禁 | V28代码已通过既有V27全量基线，并新增OpenAPI 0.34.0类型生成和相关模块定向验证；完整发布候选仍执行`scripts/check.ps1`。主要业务核心包已达到70%，但全仓、HTTP公共层和入口装配仍低于需求目标，不能标为整体已满足 |
|
||||
| 最终残留对账 | 当前数据库为`28|false`；新增设备命令、SaaS命令、告警检测、运营提权服务及HTTP纵向测试夹具残留均为0，Outbox open/processing/dead均为0且仅保留历史`completed`；既有安全基线保持不变，当前增量按轻量策略验证 |
|
||||
| V14跨功能回归 | 双轨媒体上传/校验/访问审计、固件签名/拒绝/列表/暂停/回滚及升级进度、设备命令和主体隐私删除均通过；烟测后媒体、访问授权、固件记录及Outbox open/dead均为0，服务日志未发现panic、fatal或受检密钥名称 |
|
||||
| 主体删除页面可用性 | 家庭工作台已把连续浏览器弹窗替换为页面内不可逆操作确认区：明确六类删除对账范围和活动通话保护，删除原因限制500字符，称呼必须与当前长者完全一致才启用提交，错误称呼即时提示，取消后清空敏感输入。父级动作返回实际成功状态，只有删除对账完整完成才关闭确认区；失败时保留输入和页面错误供复核。真实OIDC Chrome轻量检查验证错误称呼阻断、精确称呼放行、取消清理、桌面/平板无溢出、无控制台错误和非预期失败请求；检查不实际提交删除，不改变种子主体。页面里程碑同步为M8联调、试点与上线准备 |
|
||||
| 记忆管理页面可用性与删除终态 | 故事与记忆页已用主详情区替换记忆编辑、启停和删除的浏览器弹窗，展示资源/正文版本、索引、来源、最近变更及完整正文；修订必须正文变化且填写原因，启停说明索引与授权影响，永久删除必须填写原因并勾选不可逆确认。`PENDING_DELETE/SUPERSEDED/DELETED`只读；服务端新增强制终态校验，直接调用PATCH也不能把删除中记忆恢复为ACTIVE。真实PostgreSQL生命周期用例证明删除中重激活返回冲突；临时记忆夹具的真实OIDC Chrome检查验证六项按钮门禁、零PATCH/DELETE请求、无溢出/控制台错误/失败请求，夹具在`finally`精确清理 |
|
||||
| 设备音量配置页面可用性 | 设备管理页已移除写死的“设为60%”动作，改为0—100逐级滑块；同时展示云端期望值和设备上报值，未配置时明确标识并以60%作为首次建议值，已有相同配置时禁止重复保存。提交保留其他期望配置字段，成功后直接回显服务端递增版本；服务端新增扬声器音量整数范围校验，继续执行顶层分类白名单、敏感字段递归拒绝和强ETag并发保护。按轻量策略完成输入校验单测、设备影子真实PostgreSQL定向测试、TypeScript生产构建和真实OIDC Chrome无写入冒烟；页面无横向溢出、控制台错误或失败请求 |
|
||||
| 通话详情加载与恢复可用性 | 通话列表和详情已把语音处理、保存策略及状态来源转换为家庭业务名称。每次打开详情会取消上一条未完成请求并立即清理旧内容，核心接口失败时在右侧显示错误和“重新加载”，不会继续展示上一条通话或把错误混入长者资料；仅保存字幕或完全不留存的通话不再调用录音媒体接口。临时通话夹具的真实OIDC Chrome故障注入验证首次详情请求失败、旧详情隐藏、页面内重试恢复、选中态保持和业务标签展示；除预期注入失败外无失败请求、横向溢出或控制台错误，夹具在`finally`精确清理 |
|
||||
| Web登录会话失效恢复 | 所有认证API的HTTP 401统一触发页面级会话失效，不再只停留在家庭或运营子页面。客户端合并并发401，清除`sessionStorage`旧OIDC用户、卸载全部业务工作台并取消在途请求；身份区显示明确原因和“重新登录”。已保存用户过期、令牌到期及静默续期失败走相同清理流程，403和普通业务错误不会误触发退出。真实OIDC Chrome轻量检查注入一次家庭接口401，验证旧会话条目归零、业务区卸载、预期请求取消、重新认证后账号与工作台恢复，无非预期失败请求、控制台错误或横向溢出 |
|
||||
| 工作台URL导航与恢复 | 家庭业务保持根地址，运行配置、费用额度、告警处置和联调诊断使用可恢复的`workspace`查询参数；点击入口写入浏览器历史，刷新、直接地址、后退和前进均恢复正确工作台。URL不授予权限，客户端等待云端账号加载后校验运营角色，无权访问或未知值回退家庭业务并规范化地址；会话重新认证后权限不变则保留原工作台。真实OIDC Chrome按人工节奏验证配置/费用切换、刷新、前进后退、未知值和告警深链，零429、失败请求、控制台错误及横向溢出 |
|
||||
| 运营敏感访问申请页面可用性 | 联调诊断工作台已用页面内申请表单替换单通话敏感访问创建时的浏览器弹窗：表单固定当前通话，字幕读取强制最小能力，录音播放按需勾选，理由必填且最长500字符，有效期限定15分钟/1小时/4小时，并明确申请不等于授权、禁止录音下载。取消会清空草稿且不创建申请。OIDC回调同时安全恢复登录前站内相对路径，拒绝跨源、协议相对和回调页返回地址。真实OIDC Chrome从未登录联调深链验证全部表单门禁、取消关闭、零创建请求、零横向溢出、零控制台错误和零失败请求；临时通话夹具已精确清理 |
|
||||
| 联调受控操作页面可用性 | 配置刷新、状态对账、安全停止和设备吊销已用页面内受控操作确认区替换浏览器原因/确认弹窗；确认区固定显示目标设备，通话类操作同时显示目标通话，理由必填且最长500字符。安全停止和设备吊销增加影响确认，重新检索或切换客户组织会清除旧目标，取消不发送请求。真实OIDC Chrome复用临时诊断夹具验证四项门禁、目标绑定、危险操作确认、零修改请求、零横向溢出、零控制台错误和零失败请求，夹具已精确清理；服务端角色、租户、状态、幂等和审计边界保持不变 |
|
||||
| 诊断包导出与死信重试页面可用性 | 脱敏诊断包导出和死信任务受控重试已改为页面内表单。导出表单冻结打开时的中文检索字段和精确值，明确文件脱敏边界和导出审计，理由必填且最长500字符；重试表单固定任务公开编号、注册事件类型、聚合类型、尝试次数和稳定错误码，理由必填并要求确认根因或依赖已经处理。重新检索、刷新任务、切换客户组织或取消会清除相应旧草稿。真实OIDC Chrome使用临时通话和`platform.noop`死信夹具验证全部门禁、目标绑定、零导出/重试请求、零横向溢出、零控制台错误和零失败请求，夹具已精确清理 |
|
||||
| 联调问题状态流转页面可用性 | 调整级别、接手处理、登记解决、登记回归、关闭问题和重新打开已统一为页面内流转编辑区。编辑区固定问题编号、当前状态、责任方、现象和ETag版本，并按动作显示不同必填字段；同级别禁止重复保存，解决要求根因/修复版本/结果，回归要求脱敏证据/结论，关闭要求完整复核确认，重新打开要求责任方。刷新、筛选、切换客户组织或取消会清除草稿，服务端If-Match并发保护保持不变。真实OIDC Chrome使用覆盖OPEN/IN_PROGRESS/RESOLVED/VERIFIED/CLOSED的五条临时问题验证六项门禁、目标版本、零PATCH、零横向溢出、零控制台错误和零失败请求，夹具已精确清理 |
|
||||
| 敏感访问审批页面可用性 | 临时敏感访问的批准和拒绝已改为页面内审批区，固定展示申请编号、版本、申请人、通话、能力、到期时间和原始理由。批准依据与拒绝原因均必填且最长500字符；批准还必须确认非本人申请、单通话、最小能力、有效期及原申请人绑定，拒绝明确提示说明范围不足。刷新、切换客户组织或取消会清除审批草稿；页面隐藏本人申请的审批入口，服务端继续执行禁止自批、角色、租户、状态和到期校验。真实OIDC Chrome使用另一用户的PENDING夹具验证批准/拒绝门禁、目标绑定、零审批请求、零横向溢出、零控制台错误和零失败请求，夹具已精确清理 |
|
||||
| 通用离线评测登记页面可用性 | 非Agent组合配置的通用离线评测已用配置版本内联表单替换连续浏览器弹窗，固定展示配置编号、类型、版本族、版本号和行版本。套件版本最长100字符、报告引用最长300字符且均必填；通过/失败默认不选并必须显式决定，通过还需确认报告指标支持结论及可能参与发布门禁，取消不会被误登记为失败。Agent组合仍不显示手工通用评测入口。真实OIDC Chrome使用临时ROUTING草稿验证字段/结论/二次确认门禁、零评测POST、零横向溢出、零控制台错误和零失败请求，配置及评测夹具已精确清理 |
|
||||
| 资源撤销与配置投放控制页面可用性 | 资源引用撤销、配置投放暂停和恢复已统一为页面内受控操作区。资源操作固定公开编号、名称、类型、引用和行版本；投放操作固定公开编号、配置键、范围、状态、比例、并发上限和行版本。三类操作均要求最长500字符的原因及影响确认，明确资源撤销不删除外部密钥、不改写历史会话，暂停/恢复只改变后续新通话命中。切换客户组织、刷新或取消会清除草稿，服务端角色、租户、状态与If-Match门禁保持不变。真实OIDC Chrome复用一条低强度无提交冒烟验证三类目标绑定、字段/确认门禁、零PATCH、零横向溢出、零控制台错误和零失败请求，临时资源、版本及投放夹具已精确清理 |
|
||||
| 价格版本审批发布页面可用性 | 价格草稿审批发布已用页面内双人审批确认区替换浏览器输入弹窗，固定展示价格版本编号、供应商、币种、费率项数、生效时间、创建人和行版本。发布依据必填且最长500字符；提交前必须确认本人不是创建人，且报价/合同、全部费率和生效时间均已复核，并明确旧版本退役但历史费用不重算。切换客户组织、刷新或取消会清除草稿，服务端角色、禁止自批、状态和If-Match门禁保持不变。真实OIDC Chrome使用另一账号创建的临时价格草稿验证目标绑定、原因/确认门禁、零发布PATCH、零横向溢出、零控制台错误和零失败请求，价格及费率夹具已精确清理 |
|
||||
| 告警状态处置页面可用性 | 确认并接手、记录缓解和验证关闭已用告警详情内联处置表单替换浏览器输入弹窗，固定展示告警编号、规则、分类、级别、当前状态、命中次数和行版本。处置说明必填且最长1000字符；关闭还要求确认缓解措施、恢复指标、关联影响及遗留风险均已复核。重新筛选、切换客户组织、选择其他告警、刷新或取消会清除草稿，服务端角色、租户、状态和If-Match门禁保持不变。真实OIDC Chrome使用OPEN/ACKNOWLEDGED/MITIGATED三条临时告警验证目标绑定、字段/关闭确认门禁、零状态POST、零横向溢出、零控制台错误和零失败请求，夹具已精确清理 |
|
||||
| 告警测试、重试与静默撤销页面可用性 | 接收器联通测试、失败测试受控重试和静默提前撤销已统一为页面内受控操作区。联通测试固定活动路由、接收组、运行手册和行版本，并明确测试原因只进入审计、不外发且不会创建正式告警；重试固定任务编号、测试关联号、尝试次数、人工重试次数和错误码，要求确认依赖问题已修复；静默撤销固定静默范围、窗口和行版本，明确仍在发生的信号会重新进入队列。三类原因最长500字符并要求影响确认。真实OIDC Chrome使用临时活动路由、静默和失败测试任务验证全部门禁、零发送/重试/撤销POST、零横向溢出、零控制台错误和零失败请求，夹具已精确清理 |
|
||||
| 家庭高影响操作页面可用性 | 授权撤回、成员移除、家庭所有权转移、固件批次暂停、固件版本回滚和分享撤销已统一为页面内受控操作区。表单固定家庭/长者、成员、授权策略、固件批次与目标版本、分享资源及行版本，并明确各操作对访问、记忆、在途设备和离线副本的影响；成员移除和所有权转移要求逐字输入目标成员显示名，其余操作要求显式影响确认。真实OIDC Chrome以不提交方式验证六项表单的目标绑定和门禁，确认零业务变更、零横向溢出、零控制台错误和零失败请求；临时固件及分享夹具已精确清理，种子授权和成员状态未改变 |
|
||||
| 配置版本受控流转页面可用性 | 配置草稿提交审批、待审批版本发布和已退役历史内容回滚已改为具体版本卡片内的全宽受控流转区，固定展示版本编号、类型、配置键、状态、创建人、变更说明和行版本。发布/回滚范围、比例、并发上限和依据只保存在当前目标草稿内，修改范围会清除影响确认；页面明确提交不等于发布、发布只影响后续新通话、回滚创建新不可变版本。真实OIDC Chrome使用三条临时状态夹具验证目标/范围/确认门禁、取消关闭、数据库状态不变、零流转请求、零横向溢出、零控制台错误和零失败请求；首轮截图发现窄列不可读后已修复为全宽布局并复验，夹具已精确清理 |
|
||||
| 邀请撤销与设备诊断页面可用性 | 待接受邀请撤销和设备诊断下发已从单击即执行改为家庭工作台顶部受控操作表单。邀请表单固定家庭、接收人提示、角色、编号、到期时间和状态，明确一次性凭据失效但现有成员不受影响；诊断表单固定设备、长者、软硬件版本、在线状态和配置/记录版本，明确音频/网络/存储范围、5分钟有效期及不重启不改配置。两项均要求显式确认，取消或业务上下文变化会清空草稿。真实OIDC Chrome使用一条临时邀请和现有模拟设备验证目标/确认门禁、取消关闭、邀请与命令数量不变、零POST、零横向溢出、零控制台错误和零失败请求；邀请夹具已精确清理 |
|
||||
| 成员角色与稳定事实确认页面可用性 | 成员角色变更已从下拉即保存改为受控表单，固定家庭、成员、当前角色和行版本，目标角色改变会清除旧确认，并展示管理员/编辑者/查看者的实际能力及高敏感资源不随角色授予的边界。待核对事实确认也改为受控表单，固定长者、事实正文、来源引用、敏感等级、状态和行版本，明确只影响后续新通话且模型推断必须人工复核。真实OIDC Chrome使用种子编辑者和一条临时待核对事实验证目标/角色变化/确认门禁、取消关闭、成员及事实版本不变、零PATCH、零横向溢出、零控制台错误和零失败请求；事实夹具已精确清理 |
|
||||
| 录音授权撤销与隐私盘点/导出页面可用性 | 录音访问授权撤销、八类隐私数据盘点和私有导出已从单击即提交改为家庭业务受控操作表单。撤销表单固定长者、成员、权限、用途和有效期，并提示已签地址最多仍有效5分钟及离线副本不可远程收回；盘点明确只返回数量和状态、不复制正文；导出明确包含私密正文、使用短期地址并需受控保存销毁。三项均要求显式影响确认，取消或上下文变化会清除草稿。真实OIDC Chrome以一次无提交轻量冒烟验证目标/八类范围/确认门禁、零业务请求、三类数据库记录不变、零横向溢出和零非预期浏览器错误；通话媒体403为快照未授权下的预期安全门禁，临时通话与授权夹具已精确清理 |
|
||||
| 录音与私有导出敏感地址签发页面可用性 | 录音分片播放、录音分片下载和READY私有导出下载已从单击即签发地址改为页面内受控操作。录音表单固定长者、通话、轨道、分片、时长、大小和用途，区分浏览器播放的旁听风险与本地声音文件的保管责任；导出表单固定任务编号、八类范围、大小和对象过期时间。三项都在确认后才调用服务端，服务端继续二次核验权限、原录音授权、分片或任务状态。真实OIDC Chrome使用一条已验证分片、最小PLAY/DOWNLOAD授权和READY导出任务执行无提交轻量冒烟，验证全部目标/确认门禁、取消关闭、零媒体POST、零导出详情GET、访问日志及任务不变、零横向溢出/控制台错误/失败请求；夹具已精确清理 |
|
||||
| 录音能力与具体资源分享创建页面可用性 | 录音PLAY/DOWNLOAD显式授权和故事、通话文字、录音分片分享创建已接入家庭业务受控操作。录音确认区固定长者、成员、能力、用途和到期时间，明确授权按长者覆盖有效期内当前及后续录音、同类旧授权会被替换；分享确认区固定具体资源、接收人、单项能力、用途、到期时间和登录方式，分别说明登录接收边界与匿名口令等同凭据、只显示一次和分渠道转交要求。取消或上下文变化不创建授权，打开/取消新分享也不提前清除旧匿名口令。真实OIDC Chrome使用合成故事、通话、已验证录音分片及最小当前账号录音授权验证录音授权和三种分享资源、匿名/登录两种模式的目标/确认门禁，零创建POST、两类授权表数量不变、零横向溢出/控制台错误/失败请求；夹具已精确清理 |
|
||||
| 成员邀请与设备绑定一次性凭据页面可用性 | 成员邀请创建和设备屏幕绑定码消费已接入家庭业务受控操作。邀请确认区固定家庭、接收人提示、目标角色和七天有效期，明确提示不绑定真实身份、实际凭据持有者加入家庭、明文只显示一次及泄露撤销要求；设备确认区固定家庭和长者，只显示绑定码掩码/长度/末四位，明确云端不生成设备码、绑定建立唯一长期关联且错误目标不能复用同一码改绑。设备输入增加16—128字符门禁，取消或上下文变化清空完整码；邀请取消不生成凭据。真实OIDC Chrome无提交轻量冒烟验证两项目标/确认门禁、短码阻断、设备码不回显、取消清理、零邀请/绑定POST、邀请和绑定表数量不变、零横向溢出/控制台错误/失败请求 |
|
||||
| 创建家庭与接受邀请关系控制页面可用性 | OpenAPI 0.56.0下，创建家庭和接受成员邀请已接入家庭业务受控操作。创建确认区固定客户组织、当前账号和家庭名称，明确当前账号成为所有者以及初始家庭不自动包含长者、授权、设备或通话。接受邀请新增登录态只读预览接口，按一次性凭据展示目标客户组织、家庭、接收人提示、角色和到期时间，响应禁止缓存且页面只显示掩码凭据；正式提交仍原子复核邀请和成员状态。定向Go测试、前后端生产构建及一次真实OIDC Chrome无提交轻量烟测通过；烟测仅产生一次预览POST，创建/接受写请求为0，取消后家庭、成员和邀请状态不变，无横向溢出、控制台错误或失败请求，临时邀请家庭夹具已精确清理 |
|
||||
| 长者档案与稳定事实创建页面可用性 | 新增长者长期档案和家庭成员登记稳定事实已接入家庭业务受控操作。档案确认区固定家庭、称呼、背景、兴趣、交流目标、节奏和优先话题，明确个人资料长期保存、仅影响后续新通话且不等同分项授权；事实表单新增普通/敏感/高度敏感选择，健康背景默认提升为敏感，确认区固定长者、完整内容、家庭录入来源、敏感等级和待核对状态，并明确不会自动确认或创建记忆。前端生产构建、Web镜像重建及一次真实OIDC Chrome无提交轻量烟测通过；两类创建POST均为0，取消后长者和事实表数量不变，无横向溢出、控制台错误或失败请求 |
|
||||
| 档案修订与设备期望配置页面可用性 | OpenAPI 0.57.0下，长者档案修订和设备扬声器期望配置已接入家庭业务受控操作。档案表单无变化时禁止提交，确认区逐项展示当前版本到下一版本的旧值和新值，明确只影响后续新通话、不扩大授权且强ETag冲突不覆盖；设备确认区固定设备、长者、期望旧值/新值、上报实际值和期望版本变化，明确离线领取与实际应用边界。修复设备配置覆盖缺陷：网页仅发送白名单增量，服务端按顶层分类合并，保留未提交的历史编码、采样率和心跳配置。真实PostgreSQL定向用例、前后端生产构建及一次真实OIDC Chrome无提交烟测通过；两类PATCH为0，取消后档案和设备影子版本/正文不变，无横向溢出、控制台错误或失败请求 |
|
||||
| 分项授权与固件灰度创建页面可用性 | 新增分项授权和启动固件灰度批次已接入家庭业务受控操作。授权确认区冻结长者、类型、后续新通话范围、政策、告知摘要、证据和数据影响；切换类型清除旧告知确认，已有同类有效授权在页面阻断且服务端仍事务复核。灰度页只允许选择`READY`版本和当前家庭内型号/硬件兼容设备，确认区冻结制品摘要、比例、候选设备及当前版本，并明确服务端确定性选样和24小时可靠命令边界。按降低测试强度的要求仅执行前端生产构建、Web镜像重建、一次真实OIDC Chrome无提交冒烟和轻量残留检查；授权/灰度创建POST均为0，授权、批次及命令数量不变，无横向溢出、控制台错误、失败请求或临时固件夹具残留 |
|
||||
| 固件信任根与制品上传页面可用性 | 固件签名公钥登记和制品上传校验已接入家庭业务受控操作。网页先验证公钥为标准Base64的32字节Ed25519公钥、签名为64字节Ed25519结果；公钥确认区冻结家庭、密钥编号和完整SHA-256指纹并明确编号不可变、轮换须使用新编号，制品确认区冻结型号/主板/版本、文件名/大小/完整摘要、签名密钥、安全基线、发布说明和逐字段签名清单。确认后仍执行15分钟私有地址、浏览器直传以及服务端大小/摘要/签名三重校验。按降低测试强度要求只执行生产构建、镜像重建、一次真实OIDC Chrome无提交冒烟和轻量数据核验；公钥/版本/审计数量不变，相关POST和对象PUT均为0，无横向溢出、控制台错误或失败请求 |
|
||||
| 固件上传中断恢复与未完成版本处置 | OpenAPI 0.58.0与V37补齐`UPLOADING`版本恢复：可重新签发15分钟私有上传地址、用大小和SHA-256完全一致的本地文件覆盖同一对象并重复完成校验，也可把无法继续的版本条件退役并幂等清理对象。完成校验与退役均检查状态条件实际更新行数，消除并发误报；唯一性只约束未退役清单，退役后允许相同业务版本创建纠正版且保留历史。网页恢复表单阻断错误文件，恢复/退役均使用目标冻结和影响确认。按低强度策略仅执行V37升级、真实PostgreSQL服务/HTTP定向用例、生产构建、一次真实OIDC Chrome无提交冒烟和残留检查；零续传/完成/退役/PUT请求，夹具状态与审计不变，无溢出、控制台错误或失败请求 |
|
||||
| 可信固件公钥台账、吊销与轮换保护 | OpenAPI 0.59.0补齐租户可信公钥查询和受控吊销：台账只展示完整SHA-256指纹、状态、登记/吊销时间及上传中版本、已就绪版本、运行中批次引用数量，不暴露原始公钥。密钥编号不可变；相同公钥可幂等重放，不同公钥不得覆盖，已吊销编号不得重新激活，轮换使用新编号。上传中版本或运行中批次引用会阻断吊销；已吊销密钥不能创建新版本或启动新灰度，历史已就绪版本和审计仍保留。网页提供引用阻断原因和目标冻结的吊销确认。按低强度策略仅执行真实PostgreSQL服务/HTTP定向用例、生产构建、镜像重建、一次真实OIDC Chrome无提交冒烟和轻量残留检查；吊销请求为0，夹具状态与审计不变，无溢出、控制台错误或失败请求 |
|
||||
| 已验证固件版本暂停、恢复与退役生命周期 | OpenAPI 0.60.0补齐版本级暂停、恢复和受保护退役。`READY`暂停在同一事务阻断新灰度/新下载、暂停关联运行批次并取消未投递命令；恢复重新核验签名密钥活动状态，只恢复版本而不自动重启旧批次。运行中批次通过`FIRMWARE_RELEASE_IN_USE`阻断直接退役；未完成版本退役继续尝试清理对象，已验证版本退役保留不可变制品、清单、历史批次和审计。网页按状态展示操作，运行引用阻断退役，吊销密钥阻断恢复，并使用目标冻结和影响确认。按低强度策略执行真实PostgreSQL服务/HTTP定向用例、生产构建、镜像重建、一次真实OIDC Chrome无提交冒烟和轻量残留检查，不重复完整设备安装/回滚回归 |
|
||||
| 固件版本影响预览与处置结果查询 | OpenAPI 0.61.0新增版本影响只读接口，实时汇总关联批次状态、设备分配/下载/安装/确认/失败阶段和命令排队、送达、确认、终态及暂停取消数量；观察清单覆盖下载中、安装中及命令已送达或确认但分配尚未收敛的设备，返回批次、设备、阶段、进度、命令状态、观察原因和最后上报时间。完整汇总不截断，清单最多100条并显式标记。网页版本卡片可按需查看影响，生命周期操作成功后同步刷新处置结果。按低强度策略执行真实PostgreSQL服务/HTTP定向用例、生产构建、镜像重建、一次真实OIDC Chrome只读冒烟和残留检查，不重复完整设备升级/回滚回归 |
|
||||
| 模拟终端固件升级执行与中断恢复 | 模拟终端的`firmware_update`不再直接合成成功：从固定设备边界取得5分钟私有地址，限制1字节至256 MiB，校验小写SHA-256，并用设备侧`SIM_FIRMWARE_TRUSTED_KEYS`预置信任锚验证Ed25519清单签名；随后依次上报下载开始、制品验证完成、安装开始和确认终态。支持下载、摘要、签名、安装四类失败及下载后/安装后中断注入。服务端允许同一设备重新拉取未过期`ACKNOWLEDGED`命令且保持状态不回退，使进程重启后可从安全起点重复执行。按低强度策略仅执行模拟器/设备命令定向Go用例、一个真实PostgreSQL状态用例和一次“校验后中断—重启—确认”的纵向冒烟；最终两次投递收敛为`SUCCEEDED/CONFIRMED/100`、影响观察数为0，临时数据库和对象夹具已清理，未重复Web、暂停和回滚全量回归 |
|
||||
| 设备A/B分区升级、启动健康确认与自动回退 | OpenAPI 0.62.0在既有命令结果对象中增加向后兼容的`staging/reboot_pending/boot_verifying/rolled_back`可选阶段，不扩展旧设备必填字段和固件分配主状态枚举。模拟器只在显式启用时把制品写入非活动分区，使用权限受限的耐久日志保存命令、版本、摘要、活动/目标分区、启动尝试和健康截止时间；重启后重新拉取同一`ACKNOWLEDGED`命令，健康通过才确认新分区，失败或超时则回到旧分区并报告回退版本。家庭固件批次详情展示写入、等待重启、健康确认和已回退事实。按低强度策略执行定向Go用例、前端类型/生产构建和一次B分区启动失败自动回A分区纵向冒烟；实测从`ACKNOWLEDGED/INSTALLING/90/REBOOT_ARMED`收敛为`FAILED/FAILED/95/BOOT_HEALTH_FAILED_ROLLED_BACK`，批次暂停、观察设备为0且全部夹具已清理。该证据只证明协议闭环，真实Bootloader与掉电一致性仍属于阶段8外部验收 |
|
||||
| 固件真机联调阶段事件与一致性证据 | OpenAPI 0.63.0和V38新增每设备不可变固件阶段事件，直接命令ACK和批量遥测补交均在命令/分配事务内记录；`assignment+command_status+result_digest`对完全重复回执去重，事件保存命令/分配状态、阶段、进度、结果码、A/B分区、启动尝试、健康截止、回退、安装版本、制品摘要和签名密钥，不向页面返回完整结果正文。批次详情展示按云端接收时间排序的阶段时间线。新增`firmware-device-evidence-v1`和`cmd/firmware-conformance`，离线核对候选构建、设备/发布/命令、Bootloader/分区表、制品/信任锚、事件顺序、启动尝试、10分钟时间相关性及最终分区/版本，并把两份输入SHA-256写入报告。低强度验证执行V38正向/单版回退/重升、定向Go与前端类型检查、一次A/B回退纵向冒烟；实测7条云端事件与模拟设备独立证据全部一致，报告PASS且继续标记外部验收必需，临时业务/对象/证据文件均清理 |
|
||||
| 真机固件报告纳入阶段8证据包门禁 | `release-evidence-index-v2`新增不可豁免的`REAL_DEVICE_FIRMWARE`，`release-candidate-evidence-bundle-v3`在清单内保存真机报告数、实际/完整覆盖设备数、四场景设备计数和具体缺口。每份报告必须严格符合`firmware-conformance-report-v1`、全部检查通过、范围为`HARDWARE_CAPTURE`并绑定同一候选版本/构建摘要；模拟报告、跨候选报告、失败/字段漂移报告和同设备同场景重复报告均拒绝。`VERIFIED`要求至少3台不同设备中的每台都完成AB成功、AB回滚、写入后断电和启动中断电，缺项必须保持`PENDING`。按低强度策略执行固件校验器/证据打包定向Go测试和一条真实OIDC候选包纵向烟测，不重复固件刷写、前端或全仓回归。 |
|
||||
| 真实告警接收器和值班组映射证据 | 新增`alert-receiver-capture-v1`、`alert-receiver-conformance-report-v1`和`cmd/alert-receiver-conformance`，把同一候选的全部活动路由、最近成功联通测试、接收端按`test_ref`唯一验签回执、主/升级逻辑组到脱敏目标引用的映射，以及一条已确认并解决的受控正式告警演练形成10项一致性检查。真实来源全部通过后报告为`REAL_RECEIVER`；本地接收器固定为`MOCK_RECEIVER/external_validation_required=true`。v3证据包新增`alert_receiver_validation`缺口摘要，`REAL_ALERT_RECEIVER`不可豁免且首个文件必须是合格真实报告。按低强度策略执行两个相关Go包测试、一条真实Worker/HMAC本地接收器纵向冒烟；报告PASS但模拟范围继续待验，临时路由、Outbox、幂等、审计和磁盘文件均清理。 |
|
||||
| 云KMS/HSM轮换证据与发布门禁 | 新增`kms-rotation-capture-v1`、`kms-rotation-conformance-report-v1`和`cmd/kms-rotation-conformance`，绑定候选构建、预生产/生产环境、云提供器、工作负载身份、提供器审计、新旧版本、认证探针、业务连续性和安全复核引用。真实报告必须同时覆盖逐请求`DYNAMIC_READ`和进程级`ROLLING_RESTART`，新凭据成功、旧凭据拒绝且不导出密钥正文；本地演练只生成`LOCAL_SECRET/external_validation_required=true`。v3证据包新增`kms_rotation_validation`，`KMS_ROTATION`不可豁免，首个文件必须为合格`REAL_KMS_HSM`报告。按低强度策略执行KMS报告/证据包定向Go测试和一条现有本地HMAC轮换纵向演练；新密钥200、旧密钥401、镜像不变、API恢复，临时容器和报告均清理，真实云门禁保持待验。 |
|
||||
| 生产等价恢复演练证据与发布门禁 | 新增`production-recovery-capture-v1`、`production-recovery-conformance-report-v1`和`cmd/recovery-conformance`，把候选构建、环境/故障域/变更工单、PostgreSQL恢复、Redis重建、API/Callbacks/Worker滚动重启、供应商停机恢复、实测恢复用时、权威状态摘要、业务连续性、无重复效果、清理及审计引用形成11项检查。真实报告必须在预生产或生产等价环境完成四类演练；本地子集固定为`LOCAL_RECOVERY/external_validation_required=true`。v3证据包新增`production_recovery_validation`，该门禁不可豁免。按低强度策略执行恢复报告/证据包定向Go测试和一条现有服务重启＋Redis清空重建演练；三个服务重启、停机Outbox一次完成、Redis从0经签名请求重建、PostgreSQL权威计数不变，报告PASS但真实PostgreSQL/供应商演练继续待验，夹具和磁盘文件已清理。 |
|
||||
| 生产基础设施一致性证据与发布门禁 | 新增`production-infrastructure-capture-v1`、`production-infrastructure-conformance-report-v1`和`cmd/infrastructure-conformance`，把同一候选的域名TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控七类组件，与环境/区域/集群/变更工单、规定控制项、观测时间以及探针/配置/审计引用形成9项检查。真实来源完整通过后报告为`PRODUCTION_INFRASTRUCTURE`；本地可达性固定为`LOCAL_INFRASTRUCTURE/external_validation_required=true`。v3证据包新增`production_infrastructure_validation`，该门禁不可豁免且首个文件必须为合格真实报告。按低强度策略执行采集器/证据包定向Go测试和一条无业务写入的本地纵向冒烟：API、OIDC、PostgreSQL、Redis、MinIO和Prometheus均可达，网络及告警配置存在，报告`PASS/LOCAL_INFRASTRUCTURE`并继续外部待验；证据包保留报告加七组件共8项缺口，临时文件已清理。 |
|
||||
| Safari兼容精简矩阵与发布门禁 | 新增`safari-compatibility-capture-v1`、`safari-compatibility-conformance-report-v1`和`cmd/safari-conformance`。真实报告按候选冻结时的发布依据覆盖`CURRENT/PREVIOUS`两个不同Safari版本、桌面/平板两视口和认证会话、家庭、运营、实时导航、媒体文件、受控操作六流程，共24项；每项要求功能通过且控制台错误、非预期失败请求、横向溢出为0。非Safari工具固定为`NON_SAFARI_TOOLCHAIN/external_validation_required=true`。v3证据包新增`safari_compatibility_validation`，该门禁不可豁免且首个文件必须为合格`REAL_SAFARI`报告。按低强度策略执行采集器/证据包定向测试和一条不声称兼容的结构工具链冒烟：12项本地结构结果生成`PASS/NON_SAFARI_TOOLCHAIN`并继续外部待验；证据包保留真实报告及两个版本共3项缺口，临时文件已清理。 |
|
||||
| 真实终端RTC/语音供应商精简矩阵与发布门禁 | 新增`real-device-rtc-capture-v1`、`real-device-rtc-conformance-report-v1`和`cmd/rtc-conformance`。真实报告以至少3台候选终端执行6通：`s2s_pure/s2s_hybrid/cascade`各正常完成1通，再覆盖凭证续签、网络切换恢复和受控停止；每通必须证明房间/用户/任务绑定、双向媒体、固定状态序列、供应商启停、最终字幕、用量、质量通过、任务去重和资源回收。协议模拟固定为`PROTOCOL_SIMULATION/external_validation_required=true`。v3证据包新增`real_device_rtc_validation`，该门禁不可豁免且首个文件必须为合格真实报告。按低强度策略执行采集器/证据包定向测试和一条协议结构工具链冒烟：1台模拟终端1通结构结果生成`PASS/PROTOCOL_SIMULATION`并继续外部待验；证据包保留真实报告、设备/通话数量、三方式和四场景共10项缺口，临时文件已清理。 |
|
||||
| 真实Agent生成、Embedding和内容安全质量门禁 | 新增`real-agent-models-capture-v1`、`real-agent-models-conformance-report-v1`和`cmd/agent-models-conformance`。内容生成复用现有固定10类Agent评测，并使用评测集、脱敏观测和报告重新计算防篡改；Embedding按版本化阈值覆盖精确/改写召回、跨长者隔离、撤销/敏感排除和无匹配降级六类；内容安全覆盖验证码、金融账户、提示注入、敏感医疗、正常内容和模型输出六类。真实证据还必须绑定受控提供器、账号/区域、数据条款、额度和审计引用；本地生成器、哈希向量和规则固定为`LOCAL_AGENT_TOOLCHAIN/external_validation_required=true`。v3证据包新增`real_agent_models_validation`，该门禁不可豁免。按低强度策略执行聚合器/证据包定向测试和一条重算现有模拟报告的本地工具链冒烟：既有10类模拟报告重新计算一致，两组六类结构完整，输出`PASS/LOCAL_AGENT_TOOLCHAIN`并继续外部待验；证据包保留真实报告、三提供器和12类别共16项缺口，临时文件已清理。 |
|
||||
| 托管内容安全外部预检与告警 | OpenAPI 0.64.0把`content_safety_tls`纳入外部依赖查询和候选验收快照。生产Worker仅执行DNS、TCP和受信TLS握手，不发送待分类正文；结果复用依赖可用性指标、数据库脱敏状态和运营诊断页面，连续5分钟不可用进入统一CRITICAL告警，记录缺失/失败/过期均可阻断候选技术快照但不驱逐Pod。按低强度策略执行App/探针/诊断定向测试、前端类型生成/类型检查/生产构建和Prometheus规则校验。 |
|
||||
| 阶段8外部执行轻量预检 | 新增`scripts/stage8-preflight.ps1`，以单一只读入口核对候选Git提交、远程仓库、Compose本地基线、外部配置变量名称和十类证据索引结构/状态；报告明确不读取密钥值，也不把环境变量或本地服务可用性当作验收证据。默认仅报告缺口，`-Strict`可供自动化阻断未就绪交接；当前实测本地运行基线就绪、索引结构有效，但无候选提交/远程仓库、构建摘要仍为占位值且十类证据均为`PENDING`。 |
|
||||
|
||||
## 下一开发批次
|
||||
|
||||
1. 生产内容安全适配器、远程CI供应链门禁及内容安全外部预检/告警均已完成本地运行闭环；当前没有已知的仓库内业务功能缺口。
|
||||
2. 在目标环境执行远程CI、真实基础设施、网关、云密钥、四类恢复、内容安全六类质量和macOS Safari矩阵，逐项替换`PENDING`。
|
||||
3. 在业务方提供真实账号、硬件和生产基础设施后，为已实现的方舟内容与Embedding适配器配置真实模型并验收内容效果、召回质量、额度和数据条款，同时接入火山RTC/豆包语音，执行3台真机固件场景、家庭试点、生产等价恢复和灰度发布。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 设备 API 兼容性约定
|
||||
|
||||
> 当前设备接口主版本：`/device/v2`
|
||||
> 当前接口契约：OpenAPI 0.64.0
|
||||
> 适用对象：云端 API、终端固件、模拟终端和设备联调工具
|
||||
|
||||
## 1. 兼容目标
|
||||
|
||||
设备通常无法与云端同步升级，因此同一主版本内必须保证已投产终端无需识别新增字段也能继续完成启动、通话、心跳、停止、遥测和录音补传。云端只依据请求正文中明确声明的能力协商可选行为，不根据固件版本字符串、HTTP `User-Agent`、设备型号或服务端推测结果改变协议语义。
|
||||
|
||||
## 2. `/device/v2`允许的兼容变更
|
||||
|
||||
- 响应对象增加非必填字段；旧终端必须忽略未知字段。
|
||||
- 请求对象增加非必填字段；字段省略时必须保持原有行为。
|
||||
- 增加新端点，但不得改变已有端点的请求、响应和状态转换。
|
||||
- 在既有可选能力位明确为`true`时启用对应新动作；未声明、`false`或无法识别时均走旧行为。
|
||||
- 修正实现缺陷，但不得改变已发布字段的类型、含义、必填性和错误处理约定。
|
||||
|
||||
## 3. 必须升级到`/device/v3`的变更
|
||||
|
||||
以下任一变化都属于破坏性变更：删除或重命名字段、改变字段类型或业务含义、给既有请求增加必填字段、缩小已发布枚举导致旧值失效、改变签名算法或规范化规则、让旧固件收到无法安全忽略的新控制动作、改变既有状态机或重试/幂等语义。此类变更必须新增`/device/v3`，并保留v2迁移期和独立契约。
|
||||
|
||||
CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查。若确实需要破坏性变更，应先建立新主版本路径和迁移方案，不得通过修改或删除旧版契约绕过门禁。
|
||||
|
||||
## 4. 能力协商
|
||||
|
||||
创建通话时，终端通过`capabilities`声明能力。`rtc_credential_renewal`是可选布尔字段：
|
||||
|
||||
- 明确为`true`：进入续签窗口后，心跳可能在`continue`之后返回`renew_rtc_credential`及新短期凭证。
|
||||
- 省略或为`false`：云端不返回该新增动作，保持旧版v2终端心跳行为。
|
||||
- 能力在通话创建时冻结到通话记录，后续心跳不允许临时切换，避免同一通话内协议行为漂移。
|
||||
|
||||
模拟终端显式声明该能力，用于验证新链路。旧固件无需修改请求即可继续工作。
|
||||
|
||||
## 5. `engine_mode`终端不变量
|
||||
|
||||
创建响应中的`session.engine_mode`只用于云端诊断、成本归集和通话记录。终端不得根据该字段切换麦克风采集、音频编码、近端/远端轨道发布、智能体轨道订阅或扬声器播放。终端媒体行为只由固定设备协议、RTC房间资料和显式设备能力控制。
|
||||
|
||||
模拟终端的创建响应结构故意不定义也不解析`engine_mode`；JSON解码会忽略该未知字段。契约测试会阻止生产模拟终端重新依赖该字段。
|
||||
|
||||
## 6. 变更记录
|
||||
|
||||
| OpenAPI版本 | 设备兼容变更 | 兼容结论 |
|
||||
|---|---|---|
|
||||
| 0.64.0 | 运营外部预检增加`content_safety_tls`枚举和候选快照第四类可选必需依赖；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
|
||||
| 0.63.0 | 增加设备固件阶段事件查询及云端证据字段；设备已有命令回执仅记录同一结果的不可变事件，未增加旧终端必填字段 | v2兼容，旧终端行为不变 |
|
||||
| 0.62.0 | 命令结果增加A/B写入、待重启、启动健康和回退可选字段，省略时保持原有单分区结果语义 | v2兼容，旧终端可继续省略 |
|
||||
| 0.61.0 | 新增家庭侧固件版本影响只读接口，未修改设备协议 | v2完全兼容 |
|
||||
| 0.60.0 | 新增家庭侧固件版本暂停、恢复和退役操作，设备仍通过既有命令与配置接口工作 | v2完全兼容 |
|
||||
| 0.59.0 | 新增家庭侧固件信任根台账与吊销操作，未改变设备签名请求和回执格式 | v2完全兼容 |
|
||||
| 0.58.0 | 新增家庭侧未完成固件上传恢复与退役接口，未修改设备端点 | v2完全兼容 |
|
||||
| 0.57.0 | 设备期望配置更新改为服务端白名单合并，避免未提交字段丢失；请求字段和终端拉取语义不变 | v2兼容性修复 |
|
||||
| 0.56.0 | 新增家庭创建和邀请预览等SaaS操作，未修改设备端点 | v2完全兼容 |
|
||||
| 0.55.0 | 试点日/周报增加运营侧候选版本和构建摘要，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.54.0 | 新增运营侧试点运行周报生成接口，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.53.0 | 新增运营侧试点运行日报生成接口，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.51.0 | 发布候选快照增加脱敏阻断告警定位与资源存在性信息，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.52.0 | 新增运营告警接收器联通测试和状态查询，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.50.0 | 增加运营侧发布候选验收快照与归档下载，未修改设备端点、字段、能力位或终端行为 | v2完全兼容 |
|
||||
| 0.49.0 | 增强运营侧联调问题验收证据和高严重度发布阻断汇总，未修改设备端点、字段或终端行为 | v2完全兼容 |
|
||||
| 0.48.0 | 增加运营侧外部依赖预检台账和只读页面，未修改设备端点、字段或终端行为 | v2完全兼容 |
|
||||
| 0.47.0 | 增加运营侧配置投放暂停/恢复和并发版本控制；暂停只改变后续新通话的云端选择，未修改设备端点、字段或终端行为 | v2完全兼容 |
|
||||
| 0.44.0 | 仅收紧运营侧Agent组合的组件版本引用校验，未修改设备端点或字段 | v2完全兼容 |
|
||||
| 0.45.0 | 新通话优先冻结已投放Agent组合并把已发布人设、音色、模型和路由版本传入供应商启动；未修改设备端点、字段或终端行为 | v2完全兼容 |
|
||||
| 0.46.0 | 运行时按配置类型识别运营自定义键名的Agent组合和旧路由投放，消除保留键名依赖；未修改设备端点、字段或终端行为 | v2完全兼容 |
|
||||
| 0.43.0 | 仅增加运营侧Agent质量证据类型和发布门禁，未修改设备端点或字段 | v2完全兼容 |
|
||||
| 0.42.0 | 新增只读设备通话状态端点，明确返回`wait`、`continue`或`leave_room`；旧端点语义不变 | v2兼容，新终端可识别供应商启动失败并及时退房 |
|
||||
| 0.41.0 | 新增可选`rtc_credential_renewal`能力位；续签动作按通话冻结能力返回；明确`engine_mode`终端不变量 | v2兼容，旧终端省略能力后保持旧行为 |
|
||||
| 0.40.0 | 活动授权撤回后，心跳从权威通话状态返回既有`stop`动作 | v2兼容 |
|
||||
| 0.34.0 | 增加短期RTC凭证续签动作 | 由0.41.0补充能力协商，消除旧终端收到未知动作的风险 |
|
||||
|
||||
每次OpenAPI版本更新都必须同步本表；设备端破坏性变更还必须给出v2保留期限、v3升级方式、灰度范围和回滚条件。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 设备命令可靠下发说明
|
||||
|
||||
当前版本实现“云端排队、设备主动拉取、分阶段回执”的设备命令基线，避免依赖设备持续在线或由公网直接访问设备。家庭内具有`device.manage`能力的成员可创建命令；设备使用原有HMAC身份从固定设备边界拉取，只能读取和回执自己的命令。
|
||||
|
||||
## 状态机
|
||||
|
||||
`QUEUED → DELIVERED → ACKNOWLEDGED → SUCCEEDED/FAILED`为正常主链。超过`expires_at`且尚未终结的命令转为`EXPIRED`；重复拉取会增加`delivery_attempts`并返回同一未终结命令。设备已上报`ACKNOWLEDGED`但尚未提交终态时，命令仍可被同一设备重新拉取用于进程重启恢复，服务端保持`ACKNOWLEDGED`而不回退为`DELIVERED`。重复提交相同阶段或终态回执保持幂等。非法跨设备回执、过期回执和状态回退返回409。
|
||||
|
||||
## 接口
|
||||
|
||||
| 接口 | 身份 | 作用 |
|
||||
|---|---|---|
|
||||
| `POST /api/v1/devices/{id}/commands` | OIDC + `device.manage` | 以`Idempotency-Key`创建30秒至24小时有效的命令 |
|
||||
| `GET /api/v1/devices/{id}/commands` | OIDC + `device.manage` | 查看最近100条命令、投递次数和结果摘要 |
|
||||
| `GET /device/v2/commands?limit=10` | 设备HMAC | 拉取本设备未过期、未终结命令；首次投递记为`DELIVERED`，处理中重拉保持`ACKNOWLEDGED` |
|
||||
| `POST /device/v2/commands/{id}/ack` | 设备HMAC | 上报`ACKNOWLEDGED`、`SUCCEEDED`或`FAILED` |
|
||||
|
||||
支持`apply_config`、`reboot`、`diagnostics`和`firmware_update`四类命令。`firmware_update`只接受固件发布服务生成的私有对象引用、已验证SHA-256摘要和签名清单；制品直传、Ed25519验签、确定性灰度、暂停和已验证版本回滚详见[固件制品、签名、灰度与回滚开发说明](firmware-rollout.md)，不接受任意公网URL作为固件来源。
|
||||
|
||||
家庭工作台的诊断命令使用页面内受控操作表单，不再点击按钮后立即排队。表单固定展示设备公开编号、型号、长者、硬件/固件版本、在线状态、期望配置版本和设备记录版本，并明确诊断范围固定为音频、网络和存储。操作者必须确认命令有效期为5分钟、离线设备可能来不及领取，以及该动作不会重启设备或修改配置；取消，或切换页签、家庭、长者，会清空草稿且不创建命令。服务端仍执行`device.manage`、家庭租户隔离、设备状态、幂等和可靠投递门禁。
|
||||
|
||||
V11迁移建立`device_command`表，包含租户/设备复合外键、申请人幂等约束、JSON对象约束、过期索引和投递索引。`scripts/smoke-device-commands.ps1`已用真实OIDC与设备HMAC验证权限拒绝、幂等重放、拉取、两阶段回执、终态和测试数据清理。
|
||||
|
||||
页面增量只执行`test/e2e/visual-family-invitation-device-controls.mjs`的真实OIDC无提交冒烟：检查设备目标和固定诊断范围、确认门禁、取消关闭、诊断命令数量不变、零POST、零横向溢出、零控制台错误和零失败请求，不重复设备HMAC全状态链测试。
|
||||
@@ -0,0 +1,113 @@
|
||||
# 设备A/B分区固件升级与启动确认协议
|
||||
|
||||
## 1. 目的与适用边界
|
||||
|
||||
本协议用于把云端已经完成的签名制品、灰度命令和阶段回执，与量产终端常见的A/B双分区升级机制对齐。它定义设备必须持久化的升级状态、云端可观察阶段、启动健康窗口和自动回退结果，但不替代具体芯片、Bootloader、分区表、看门狗或厂商烧写SDK。当前`cmd/sim-device`实现的是协议级模拟器，用于在真机到位前发现状态机和联调问题；是否能安全写入真实分区、断电后继续启动及由Bootloader自动回退，仍必须在量产候选硬件上验收。
|
||||
|
||||
旧设备不声明或不启用A/B能力时继续使用既有`downloading → installing → confirmed/failed`链路。A/B模拟器只有在`SIM_FIRMWARE_AB_UPDATE=true`且提供绝对路径`SIM_FIRMWARE_STATE_FILE`时启用，不改变设备v2既有必填字段和命令终态。
|
||||
|
||||
## 2. 设计原则
|
||||
|
||||
1. 设备只信任安全存储或受控镜像预置的厂商公钥，不信任升级命令携带的公钥。
|
||||
2. 制品大小、SHA-256和Ed25519签名全部通过后，才允许写入非活动分区。
|
||||
3. 任何时刻都不得直接覆盖当前活动且已确认可启动的分区。
|
||||
4. 设置下次启动分区和健康截止时间前，必须先持久化升级日志；云端回执不得先于本地耐久状态。
|
||||
5. 新分区只有在核心进程、配置读取、设备身份和必要外设健康检查通过后才能确认。
|
||||
6. 健康检查失败或超过截止时间时，由设备/Bootloader回到旧分区，并向云端提交带回退事实的稳定失败终态。
|
||||
7. 设备重启后可重新拉取仍为`ACKNOWLEDGED`的同一命令；云端增加投递次数但不把状态回退到`DELIVERED`。
|
||||
|
||||
## 3. 设备侧状态机
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> StableA: A分区已确认
|
||||
StableA --> Downloading: 收到firmware_update
|
||||
Downloading --> ArtifactVerified: 摘要和签名通过
|
||||
Downloading --> Failed: 下载/摘要/签名失败
|
||||
ArtifactVerified --> StagedB: 写入并校验非活动B分区
|
||||
StagedB --> RebootPending: 持久化启动尝试和健康截止时间
|
||||
RebootPending --> BootVerifyingB: 重启进入B分区
|
||||
BootVerifyingB --> StableB: 健康检查通过并确认B
|
||||
BootVerifyingB --> RolledBackA: 健康失败或超时
|
||||
RolledBackA --> Failed: 上报已自动回退
|
||||
StableB --> [*]
|
||||
Failed --> [*]
|
||||
```
|
||||
|
||||
当活动分区为B时，下一次升级使用完全对称的B→A流程。`power_loss_after_stage`保留`STAGED`日志，重启后从设置启动分区继续；`power_loss_during_boot`保留`REBOOT_PENDING`日志，后续启动继续执行健康检查。重复执行必须针对同一命令编号、版本、发布编号和摘要，任一不一致都以`LOCAL_UPDATE_STATE_CONFLICT`停止，不能覆盖未知的在途升级。
|
||||
|
||||
## 4. 本地耐久日志
|
||||
|
||||
模拟器状态文件只保存非敏感升级元数据，权限为当前进程可读写。字段如下：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| `phase` | `STAGED`、`REBOOT_PENDING`、`CONFIRMED`或`ROLLED_BACK` |
|
||||
| `command_id`、`release_id` | 绑定当前可靠命令和云端发布记录 |
|
||||
| `target_version`、`previous_version` | 目标版本和回退基线版本 |
|
||||
| `sha256` | 已验证制品摘要，用于重启后核对同一升级意图 |
|
||||
| `active_slot`、`previous_slot`、`target_slot` | 当前稳定分区、回退分区和待启动分区 |
|
||||
| `boot_attempt_id` | 每次设置下次启动分区时生成的随机启动尝试编号 |
|
||||
| `health_deadline` | 新分区必须完成健康确认的UTC截止时间 |
|
||||
| `updated_at` | 最近一次耐久更新时刻 |
|
||||
|
||||
`CONFIRMED`和`ROLLED_BACK`记录作为下一次升级的本地稳定基线保留。量产实现应把等价数据写入具备掉电保护的Bootloader环境区或专用元数据分区，并使用冗余、校验和或事务写策略处理半写入，不能直接照搬普通文件实现。
|
||||
|
||||
## 5. 云端回执与主状态映射
|
||||
|
||||
命令仍只使用`ACKNOWLEDGED`、`SUCCEEDED`和`FAILED`三类状态。A/B细节放在可选`result_summary`中，云端将所有设备侧写入、重启和健康确认阶段保持为`firmware_assignment.status=INSTALLING`，避免扩展既有主状态枚举破坏客户端兼容。
|
||||
|
||||
| 回执阶段 | 命令状态 | 分配主状态 | 建议进度 | 关键字段 |
|
||||
|---|---|---|---:|---|
|
||||
| `downloading` | `ACKNOWLEDGED` | `DOWNLOADING` | 5—100 | `result_code`、`verified_sha256` |
|
||||
| `installing` | `ACKNOWLEDGED` | `INSTALLING` | 80 | `INSTALL_STARTED` |
|
||||
| `staging` | `ACKNOWLEDGED` | `INSTALLING` | 85 | `active_slot`、`target_slot` |
|
||||
| `reboot_pending` | `ACKNOWLEDGED` | `INSTALLING` | 90 | `boot_attempt_id`、`boot_health_deadline` |
|
||||
| `boot_verifying` | `ACKNOWLEDGED` | `INSTALLING` | 95 | `active_slot`、`previous_slot` |
|
||||
| `confirmed` | `SUCCEEDED` | `CONFIRMED` | 100 | `installed_version`、`active_slot` |
|
||||
| `rolled_back` | `FAILED` | `FAILED` | 95 | `rollback_applied=true`、`rollback_version`、`failed_slot` |
|
||||
|
||||
启动失败回退示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "FAILED",
|
||||
"result_summary": {
|
||||
"phase": "rolled_back",
|
||||
"progress_percent": 95,
|
||||
"result_code": "BOOT_HEALTH_FAILED_ROLLED_BACK",
|
||||
"rollback_applied": true,
|
||||
"active_slot": "A",
|
||||
"failed_slot": "B",
|
||||
"rollback_version": "0.2.0-sim",
|
||||
"boot_attempt_id": "<随机编号>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
回退已经保护设备可启动性，但目标版本未成功，因此云端仍把命令和分配标记为失败、把批次暂停并停止扩量。运营页面从`last_result`展示非活动分区写入、等待重启、健康确认或已自动回退，不把“回到了可用旧版本”误报成升级成功。
|
||||
|
||||
## 6. 模拟器参数和故障注入
|
||||
|
||||
| 参数 | 默认值 | 作用 |
|
||||
|---|---|---|
|
||||
| `SIM_FIRMWARE_AB_UPDATE` | `false` | 显式启用A/B升级协议 |
|
||||
| `SIM_FIRMWARE_STATE_FILE` | 无 | A/B耐久日志绝对路径；启用时必填 |
|
||||
| `SIM_FIRMWARE_ACTIVE_SLOT` | `A` | 首次运行且没有稳定日志时的活动分区，只允许A/B |
|
||||
| `SIM_FIRMWARE_CURRENT_VERSION` | `0.2.0-sim` | 首次运行的回退基线版本 |
|
||||
| `SIM_FIRMWARE_BOOT_HEALTH_WINDOW` | `2m` | 启动健康窗口，范围1秒至30分钟 |
|
||||
| `SIM_FIRMWARE_FAULT=power_loss_after_stage` | 无 | 写完非活动分区后模拟掉电，保留`STAGED` |
|
||||
| `SIM_FIRMWARE_FAULT=power_loss_during_boot` | 无 | 新分区健康确认时模拟掉电，保留`REBOOT_PENDING` |
|
||||
| `SIM_FIRMWARE_FAULT=boot_health_failed` | 无 | 模拟新分区健康失败并自动回退 |
|
||||
|
||||
## 7. 轻量纵向验证
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-sim-firmware.ps1 -Mode ABRollback
|
||||
```
|
||||
|
||||
脚本创建一个临时签名版本和单设备批次。第一次运行下载、验签、写入B分区并持久化`REBOOT_PENDING`，断言云端为`ACKNOWLEDGED/INSTALLING/90/REBOOT_ARMED`；第二次运行模拟B分区健康失败，断言本地回到A分区、原版本恢复，云端收敛为`FAILED/FAILED/95/BOOT_HEALTH_FAILED_ROLLED_BACK`，批次暂停且观察设备为0。结束后精确清理数据库、对象存储、固件文件和本地状态文件。
|
||||
|
||||
同一脚本还生成独立的`firmware-device-evidence-v1`设备侧证据，读取包含7条去重阶段事件的云端批次响应，并调用`cmd/firmware-conformance`核对命令、发布、启动尝试、制品摘要、签名密钥、阶段顺序、时间相关性、分区和回退版本。证据字段及报告归档规则见[固件真机联调一致性证据采集与校验说明](firmware-conformance-evidence.md)。
|
||||
|
||||
该结果证明协议和云端状态闭环可联调，不证明真实Bootloader、闪存掉电一致性或真实外设健康检查已经通过。真机验收仍须覆盖至少3台量产候选终端、A→B和B→A、写入中断电、首次启动断电、健康超时、看门狗复位、连续升级、云端暂停和已验证版本回滚。
|
||||
@@ -0,0 +1,289 @@
|
||||
# 设备接入与启动配置联调说明
|
||||
|
||||
## 1. 当前接口
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|---|---|---|
|
||||
| GET | `/device/v2/bootstrap` | 上报启动信息，取得服务器时间、可信设备状态、绑定、最低安全基线、最低固件版本及兼容结论 |
|
||||
| GET | `/device/v2/config` | 取得版本化期望配置和当前绑定；支持 `If-None-Match` |
|
||||
| POST | `/device/v2/conversations` | 冻结授权和背景；成功时分配RTC房间并进入`ROOM_ISSUED`，背景准备失败时保存可诊断`FAILED`结果且不创建房间 |
|
||||
| POST | `/device/v2/conversations/{id}/activate` | 确认设备已成功入房，可靠投递固定语音供应商任务 |
|
||||
| GET | `/device/v2/conversations/{id}` | 读取权威通话状态、稳定失败码和设备下一步动作；用于确认智能体启动结果 |
|
||||
| POST | `/device/v2/conversations/{id}/heartbeat` | 按递增序号上报在线、RTC、配置和录音队列状态并刷新短期租约 |
|
||||
| POST | `/device/v2/conversations/{id}/stop` | 记录挂断原因并可靠停止固定供应商任务，最终收敛到终态 |
|
||||
| POST | `/device/v2/conversations/{id}/turns:batch` | 在供应商终稿缺失时补传设备终稿，并与已保存供应商终稿去重合并 |
|
||||
| POST | `/device/v2/telemetry:batch` | 批量上报设备状态、有限错误码和命令结果，返回配置/命令/停止动作 |
|
||||
| POST | `/callbacks/v1/vertc/voice-chat` | 接收经HMAC签名的语音供应商异步事件 |
|
||||
|
||||
设备自报的型号、设备编号或版本不构成身份依据。云端使用签名中的设备公开编号查询登记记录，并从数据库取得租户、状态和凭据引用。
|
||||
|
||||
### 1.1 家庭端设备绑定
|
||||
|
||||
设备绑定码由未绑定设备在受控配网或屏幕流程中显示，家庭Web工作台只调用`POST /api/v1/device-claims`消费该码，不生成绑定码。输入框限制16—128字符并关闭自动填充；进入确认区后不回显完整码，只显示掩码、总长度和末四位。确认区同时冻结当前家庭、长者及其公开编号，要求操作者当面核对设备屏幕、设备型号和实际使用人，并明确绑定将建立唯一有效的长期家庭/长者关联，错误目标不能通过再次输入同一码自行改绑。
|
||||
|
||||
只有显式确认后才提交完整绑定码。服务端重新校验操作者的`device.manage`能力、家庭与长者边界、设备未绑定、绑定码摘要、到期和撤销状态；相同码和相同目标可安全重试，不同目标或已有有效绑定返回冲突。取消、切换页签/家庭/长者会同时清除确认草稿和输入框中的完整码，不发送请求。页面增量只执行真实OIDC无提交轻量冒烟，验证短码阻断、固定目标、完整码不回显、确认门禁、取消清理、零`device-claims` POST和绑定记录数量不变；完整首次绑定与安全重试继续由既有真实数据库用例承担。
|
||||
|
||||
最低固件版本与最低安全基线是两个独立概念。`minimum_security_version`保存厂商安全能力或签名基线标识；`minimum_firmware_version`保存允许创建新通话的固件下限。设备启动上报当前固件后，`firmware_compatible`立即给出判断；SemVer兼容版本按主版本、次版本、修订号和预发布标识排序，厂商自定义的不透明版本无法安全排序，只允许与策略精确相等。设备必须在兼容结果为`false`时进入升级提示而不是继续通话；云端创建接口仍会再次校验并返回不可自动重试的`FIRMWARE_UPDATE_REQUIRED`，因此绕过设备侧提示也不会分配房间。
|
||||
|
||||
## 2. 开发环境签名
|
||||
|
||||
每个请求必须包含：
|
||||
|
||||
- `X-Device-Id`：已登记的设备公开编号。
|
||||
- `X-Device-Timestamp`：RFC3339 UTC时间，默认允许前后5分钟误差。
|
||||
- `X-Device-Nonce`：每个请求唯一的16—128字符随机数。
|
||||
- `X-Device-Content-SHA256`：原始HTTP正文的SHA-256小写十六进制值；空正文也必须计算。
|
||||
- `X-Device-Signature`：HMAC-SHA256结果的无填充Base64URL编码。
|
||||
|
||||
签名原文按以下顺序拼接，行间使用单个换行符：
|
||||
|
||||
```text
|
||||
UPPERCASE_HTTP_METHOD
|
||||
REQUEST_URI_WITH_EXACT_QUERY_STRING
|
||||
X-Device-Timestamp原值
|
||||
X-Device-Nonce原值
|
||||
X-Device-Content-SHA256原值
|
||||
```
|
||||
|
||||
云端先核验时间窗、正文摘要和签名，再使用Redis `SET NX`登记随机数。相同设备和随机数只能使用一次；Redis或数据库不可用时设备鉴权采用fail-closed并返回可重试的503，不绕过身份验证。
|
||||
|
||||
本地环境使用静态HMAC密钥模拟联调。量产采用每设备独立HMAC时，密钥应写入硬件安全区并通过Secrets/KMS CSI受控挂载到云端；如硬件与PKI条件允许，仍可进一步切换每设备mTLS证书。不能把本地合成密钥烧录到真实设备。
|
||||
|
||||
### 2.1 逐设备生产密钥解析
|
||||
|
||||
dev、stage和prod把设备密钥通过Docker/Kubernetes Secrets或云KMS CSI驱动挂载到API容器的受控只读目录，并设置`DEVICE_SECRET_DIRECTORY`。设备表不保存密钥正文，只保存`device-secret://<name>`引用；解析器只接受单层安全文件名，解析符号链接后仍必须位于配置根目录内，文件最大4KiB且有效密钥至少32字节。
|
||||
|
||||
每次验签都按设备记录读取对应文件，因此不同设备使用不同密钥，原子替换挂载文件即可完成轮换，不需要重新构建镜像或重启API。文件缺失、过短、引用格式错误或越界时统一按无效凭据拒绝，响应与日志不暴露文件路径及密钥内容。生产启动门禁拒绝退回单一`DEVICE_LOCAL_SECRET`。
|
||||
|
||||
## 3. 启动参数
|
||||
|
||||
`bootstrap`查询参数包括：`firmware_version`、`board_rev`、`rtc_sdk_version`、`codec`、`sample_rate`、`device_time`和`network`。其中固件版本和设备时间必填。服务端把报告写入设备影子的reported区域，网页配置只能修改desired区域。
|
||||
|
||||
响应返回服务器时间和设备时钟偏差、登记状态、型号、最低安全版本、期望配置版本及当前绑定。响应不包含内部数据库主键或任何设备密钥。
|
||||
|
||||
## 4. 配置缓存
|
||||
|
||||
配置接口返回强ETag，例如 `"v1"`。设备下次请求可携带：
|
||||
|
||||
```http
|
||||
If-None-Match: "v1"
|
||||
```
|
||||
|
||||
配置未变化时返回HTTP 304；变化时返回HTTP 200、新ETag、期望配置、设备已报告版本和绑定信息。
|
||||
|
||||
### 4.1 家庭端音量配置
|
||||
|
||||
家庭端设备管理页把扬声器音量作为设备影子的非敏感期望配置管理，不直接假定设备已经应用。页面同时展示“云端期望”和“设备上报”两个值：未配置时滑块以60%作为首次建议值，但明确显示云端尚未设置；已有配置时从当前`desired_config.volume.speaker`回显，相同值不允许重复提交。用户可在0—100范围内逐级调节；提交前的受控操作区固定设备、长者、旧值、新值、设备上报实际值和期望版本变化，并说明离线设备可能稍后领取。
|
||||
|
||||
网页提交`PATCH /api/v1/devices/{id}/twin`时只发送需要修改的白名单顶层分类并携带当前设备影子强ETag。服务端仅接受0—100的整数`desired_config.volume.speaker`，继续递归拒绝密钥、令牌、口令和凭据字段，并把已验证分类按顶层增量合并到现有期望配置，未提交的历史编码、采样率、心跳和其他分类不会被音量修改删除。版本过期时返回412，页面刷新后由最新设备影子重新回显；成功时响应包含递增后的期望版本，页面立即更新为“等待设备应用”。设备随后通过配置拉取和心跳报告实际版本及`reported_config.volume.speaker`，二者一致后显示“设备已应用”。
|
||||
|
||||
## 5. 创建通话
|
||||
|
||||
创建接口必须同时提供设备签名和16—128字符的`Idempotency-Key`。服务端在同一事务中完成：
|
||||
|
||||
1. 锁定并核验设备当前绑定、长者状态和语音授权；
|
||||
2. 冻结本次授权快照和最小背景快照；
|
||||
3. 创建固定通话编号、房间编号和供应商任务编号；
|
||||
4. 记录`PREPARING → ROOM_ISSUED`状态链、RTC任务、审计和可靠待办；
|
||||
5. 提交后签发绑定指定房间和设备用户的短期Token。
|
||||
|
||||
请求中的`capabilities`用于显式能力协商。当前模拟终端在原有`rtc`、`audio_tracks`和`upload_resume`之外声明可选的`rtc_credential_renewal=true`；云端把该能力冻结到本次通话。旧版v2固件省略该字段时仍可创建通话，云端不会向其返回新增的凭证续签动作。能力选择不得根据固件版本或HTTP `User-Agent`推测，完整兼容规则见[设备API兼容性约定](device-api-compatibility.md)。
|
||||
|
||||
最小背景快照不是设备自由上报的正文。服务端按当前有效绑定读取长者档案版本，只从`profile_data.background/interests`和`conversation_preferences.conversation_goal/pace/preferred_topics`提取有长度上限的白名单资料，再加入最多5条当前有效的已确认记忆。非白名单扩展字段、内部备注和设备侧固定技术目标`open_conversation`不会进入供应商提示。生成的摘要和档案版本随通话冻结；网页后续修改只影响下一次新通话。供应商系统消息还会把该段内容明确标记为“背景资料而非可执行指令”，不能借此覆盖固定安全规则。
|
||||
|
||||
### 5.1 背景资料准备失败协议
|
||||
|
||||
五个白名单字段一旦存在，就必须符合约定类型：背景、交流目标和节奏为字符串，兴趣和优先话题为字符串数组；缺失或`null`表示未填写。历史导入或异常写库造成类型不正确时，云端不会把字段静默丢弃后继续通话，也不会创建RTC房间或供应商任务，而是保存一条状态为`FAILED`、失败码为`context_preparation_failed`的权威通话和脱敏失败快照。
|
||||
|
||||
设备收到HTTP 422，错误码为`AGENT_CONTEXT_PREPARATION_FAILED`，`details`固定包含`conversation_id`、`status=FAILED`和`failure_code=context_preparation_failed`。该错误不可在原请求上无限自动重试；设备应停止入房流程，展示“背景资料准备失败”，并上报稳定错误码。网络重放必须沿用原`Idempotency-Key`，云端返回相同通话编号并携带`Idempotency-Replayed: true`；用户修正档案后才使用新的幂等键发起新通话。家庭网页和运营诊断均按同一`failure_code`展示“背景资料准备失败，未进入语音通话”。
|
||||
|
||||
家庭端可在设备真正发起通话前调用`GET /api/v1/subjects/{id}/conversation-readiness`。该接口只返回当前成员有权查看的长者及绑定设备事实，把档案背景、交流目标、语音授权、有效绑定和设备运行上报列为准备条件，把配置同步和最近联系列为运行提醒。用量额度、生产路由接纳和进行中通话属于瞬时状态，仍由`POST /device/v2/conversations`在事务内最终判断；就绪响应不会预留房间、额度或供应商容量。
|
||||
|
||||
创建阶段不会调用`StartVoiceChat`。设备必须先加入返回的RTC房间，再调用后续`activate`接口。相同设备、接口、幂等键和相同正文返回同一通话；正文不同返回冲突。为避免持久化完整短期Token，幂等记录只保存非敏感房间声明，重放时根据原声明确定性重建同一个Token。
|
||||
|
||||
创建响应中的`session.engine_mode`只供云端诊断、成本归集和通话追溯。终端必须忽略该字段，不得用它切换麦克风采集、编码、近远端轨道发布、订阅或扬声器播放。
|
||||
|
||||
## 6. 激活通话与启动语音供应商
|
||||
|
||||
设备收到房间资料并成功加入RTC房间后，调用`POST /device/v2/conversations/{id}/activate`，正文必须带入云端原先分配的`room_id`、`rtc_user_id`，并将`rtc_join_result`设为`success`。服务端还会校验当前设备归属、房间预留有效期和`config_revision`，任何不一致都不会启动供应商任务。
|
||||
|
||||
首次有效激活在一个事务中完成`ROOM_ISSUED → STARTING_AGENT`、RTC任务`ALLOCATED → STARTING`、审计记录和`conversation.agent_start_requested` outbox事件。Worker使用创建通话时已经冻结的`provider_task_ref`调用供应商，重试时不得生成新任务编号。重复的相同幂等请求返回原结果；通话已经处于`STARTING_AGENT`或`ACTIVE`时再次确认也不会创建第二个启动事件。
|
||||
|
||||
激活接口受理后，设备使用`GET /device/v2/conversations/{id}`查询启动结果，不通过更换幂等键重复调用激活接口充当轮询。返回动作含义如下：
|
||||
|
||||
- `wait`：房间已分配或智能体仍在启动，设备保持入房并按有限次数继续查询；
|
||||
- `continue`：权威状态为`ACTIVE`，设备进入正常双向语音和心跳；
|
||||
- `leave_room`：通话正在停止或已进入终态，设备立即退出RTC房间；`FAILED`时同时显示稳定脱敏`failure_code`。
|
||||
|
||||
供应商明确、不可重试地拒绝启动时，Worker在同一数据库事务内把通话和RTC任务收敛为`FAILED/provider_start_rejected`，写入状态历史和系统审计，并正常完成可靠待办，不让通话停留在`STARTING_AGENT`或把永久错误反复重试。供应商异步报告启动失败时返回既有`provider_start_failed`。两种情况都不向设备暴露供应商原始响应；模拟终端识别`leave_room`后立即结束启动流程。
|
||||
|
||||
本地`mock-provider`暴露在`http://localhost:59200`，用于模拟供应商启动和异步回调。它按固定任务编号幂等受理启动，并故意发送两次完全相同的`voice_chat.started`回调。Callbacks进程先按时间戳和原始正文校验HMAC签名，再以`provider + event_id`去重；同一事件编号和同一正文返回成功，同一事件编号却对应不同正文时返回409。首个有效启动事件使通话和RTC任务进入`ACTIVE`，重复或过时事件不能让状态回退。
|
||||
|
||||
生产模式不复用Mock路径。API使用RTC AppKey生成官方正式Token格式，Token只授权本次`room_id + rtc_user_id`的发布与订阅并在短期后失效；相同创建请求重放时按相同房间、用户和到期时间重建同一Token，数据库和日志均不保存Token。Worker使用火山引擎AK/SK对`StartVoiceChat/StopVoiceChat`签名，平台稳定任务编号映射为`TaskId`，房间映射为`RoomId`，已冻结的设备/智能体RTC用户映射到`AgentConfig`。通话创建时冻结的`s2s_pure`、`s2s_hybrid`或`cascade`会进入可靠启动任务，Worker从`voice-chat-template-bundle-v1`选择同名模板；生产启动要求三个模板全部存在，避免运营路由切换后仍使用另一种处理链。官方同步响应`Result=ok`表示RTC已接受并启动该任务，平台据此进入`ACTIVE`，后续由设备心跳维持租约；火山接口没有任务查询API，因此不确定启动的恢复逻辑会以同一`TaskId`安全重发，供应商“任务已启动”响应同样按已存在活动任务收敛，不生成新任务编号。服务端状态事件可作为状态细分和用量补充，但不是最小通话链进入ACTIVE的单点依赖。
|
||||
|
||||
生产API优先选择活动投放所绑定的`AGENT_BUNDLE`版本，并从组合引用的路由版本取得处理模式；`config_key`是运营自定义版本族标识，不要求保留键名。未命中组合时兼容活动投放所绑定的直接`ROUTING`版本。两类投放都未命中时返回503 `RUNTIME_CONFIG_UNAVAILABLE`，不会回退到开发用`minimal-v2 + s2s_hybrid`。dev、test和local环境保留该默认值，便于模拟设备和本地闭环运行。该变化仅影响云端新通话配置选择，不改变设备v2请求、响应字段或终端媒体行为。
|
||||
|
||||
阶段8真实验收按[真实终端与RTC/语音供应商一致性证据](real-device-rtc-evidence.md)执行6通精简矩阵，三种方式各完成正常闭环，并额外覆盖凭证续签、网络切换恢复和受控停止。协议模拟只验证工具链，不计入`REAL_DEVICE_RTC`。
|
||||
|
||||
模拟供应商还提供仅限本地、使用`X-Mock-Provider-Key`保护的`POST /mock/v1/admin/replay`。请求指定已启动的`task_ref`、样例名和1—10次重复投递次数，可重复播放`started`、`final_transcript`、`agent_answering`、`interrupted`、`usage`、`error`和`stopped`七类脱敏通知。`agent_answering`和`interrupted`以最终智能体话轮表达，后者明确设置`interrupted=true`；`usage`只使用标准化分类、计量代码、数量和单位。相同样例针对同一任务生成稳定事件编号，用于验证通知幂等，不应在生产部署中暴露该管理接口。
|
||||
|
||||
供应商回调签名使用以下原文：
|
||||
|
||||
```text
|
||||
X-Provider-Timestamp原值
|
||||
原始HTTP正文的SHA-256小写十六进制值
|
||||
```
|
||||
|
||||
签名算法为HMAC-SHA256，响应编码为无填充Base64URL。本地共享密钥只用于联调；生产应改由密钥管理服务托管并建立轮换机制。
|
||||
|
||||
## 7. 通话心跳与租约
|
||||
|
||||
通话进入`STARTING_AGENT`或`ACTIVE`后，设备按创建响应中的`heartbeat_interval_sec`调用心跳接口。请求至少包含严格递增的`sequence_no`、设备时间与单调时钟、云端通话状态、RTC上下行状态、网络、固件版本、已应用配置版本、录音队列以及命令结果数组。录音队列必须报告待上传数和失败数；发生失败时可附带脱敏的`last_failure_code`与`last_failure_at`，家庭端据此显示上传积压和最近失败原因。
|
||||
|
||||
PostgreSQL保存`last_heartbeat_seq`和权威`lease_expires_at`；Redis只保存可重建的热租约和设备在线状态。处理规则如下：
|
||||
|
||||
1. 新序号在数据库行锁内更新通话、RTC任务和设备影子，并把租约续期为五个心跳周期；
|
||||
2. 同序号重放或更小序号的乱序心跳返回当前结果，不更新设备报告，也不延长数据库或Redis租约；
|
||||
3. Redis使用Lua比较序号，避免两个已经提交的并发请求以相反顺序覆盖热租约；
|
||||
4. 设备报告的配置版本低于期望版本时，服务端接受心跳并返回最新`desired_config_revision`；高于云端期望版本时返回冲突，防止未知配置污染设备影子；
|
||||
5. RTC已经离房、设备报告正在停止或通话已是终态时返回`stop`动作，终态永远不会因迟到心跳回到运行态；
|
||||
6. 已在创建通话时明确声明`rtc_credential_renewal=true`的设备，把当前使用的Token过期时间原样放入`rtc_credential_expires_at`；进入续签窗口时响应在`continue`后追加`renew_rtc_credential`，其中`rtc`结构包含同一房间和设备用户的新短期凭证；未声明能力的旧版v2设备只收到原有动作；
|
||||
7. 设备先替换运行内存中的RTC凭证，再在下一次心跳报告新的过期时间。若续签响应丢失，旧过期时间会使服务端按已保存的新过期时间重新生成同一确定性凭证，不重复延长有效期；
|
||||
8. Token签名失败时数据库事务整体回滚，不推进心跳序号或凭证时间，设备可用同一序号安全重试；凭证正文仍不写入PostgreSQL、Redis、审计或日志；
|
||||
9. PostgreSQL事务提交后Redis刷新失败不回滚权威心跳，后台可从数据库重建热租约。
|
||||
|
||||
心跳中的`last_error`只接受短错误码，不接受自由文本；云端不会把命令结果、短期Token或供应商密钥写入请求日志。
|
||||
|
||||
## 8. 停止通话与异常回收
|
||||
|
||||
设备挂断后调用`POST /device/v2/conversations/{id}/stop`，同时提供16—128字符的`Idempotency-Key`。正文包含原因代码、设备时间、最后心跳序号、RTC是否已经离房和near/far本地录音分片计数。首次有效请求执行以下事务：
|
||||
|
||||
1. `ACTIVE`或`STARTING_AGENT`进入`STOPPING`，清空权威租约并记录停止原因；
|
||||
2. RTC任务进入`STOPPING`；
|
||||
3. 创建唯一的`conversation.agent_stop_requested`可靠待办和操作审计；
|
||||
4. 事务提交后删除Redis通话热租约，并把设备在线状态恢复为`idle`。
|
||||
|
||||
Worker始终使用创建通话时固定的`provider_task_ref`调用Stop。相同幂等键重放返回原结果；换新幂等键重复停止、Worker重试或后台对账也不会产生第二个供应商任务。供应商返回`COMPLETED`或签名结束回调到达后，通话和RTC任务统一进入`COMPLETED`、写入结束时间，并追加`STOPPING → COMPLETED`状态历史。完全相同的结束回调只落一条供应商事件。
|
||||
|
||||
家庭用户在通话中撤回该通话冻结快照正在使用的字幕、原录音、故事整理或个性化记忆授权时，SaaS在撤回事务内同步保存停止意图：`ACTIVE/STARTING_AGENT`进入`STOPPING`并创建唯一Agent停止待办，尚未启动Agent的房间直接进入`EXPIRED`。设备不需要新增接口；下一次通话心跳返回`stop`，批量遥测若引用该通话则返回`stop_conversation`。即使Worker先完成供应商停止，设备对已进入终态的通话心跳仍收到停止动作。家庭分享授权只控制后续分享访问，不中断实时语音。
|
||||
|
||||
如果设备在激活前挂断，`ROOM_ISSUED`直接进入`EXPIRED`，供应商侧不会发生Start或Stop调用。后台恢复扫描器从PostgreSQL扫描非终态通话并使用数据库行锁和`SKIP LOCKED`避免多个Worker重复修复：
|
||||
|
||||
- 房间预留到期：进入`EXPIRED`；
|
||||
- `ACTIVE`租约到期：进入`STOPPING`并可靠投递Stop；
|
||||
- `STARTING_AGENT`长时间未收敛：按时间桶投递幂等启动对账；
|
||||
- `STOPPING`长时间未完成：按时间桶安全重试Stop；
|
||||
- 供应商幂等Start/Stop响应已经确认终态时，即使原回调丢失也可由Worker补齐状态历史；
|
||||
- 每次发现和恢复均写入`conversation.recovery`系统审计。
|
||||
|
||||
本地默认每5秒扫描一次，启动中或停止中超过20秒进入对账。生产值必须依据真实供应商回调延迟、设备心跳间隔和压测结果调整。
|
||||
|
||||
## 9. 终稿补传与冲突处理
|
||||
|
||||
当供应商最终转写缺失或不完整时，通话所属设备可调用`POST /device/v2/conversations/{id}/turns:batch`补传1—500条最终话轮。请求同时携带设备签名和16—128字符的`Idempotency-Key`。每条终稿包含`turn_key`、严格正整数`sequence_no`、说话方、起止时间、最终文本和是否被打断；同一批内`turn_key`和`sequence_no`分别唯一。
|
||||
|
||||
云端在单个数据库事务内按通话归属、留存策略和当前文字留存授权校验后，以`turn_key`和`sequence_no`同时合并：
|
||||
|
||||
1. 两个业务键、说话方、时间、文本和打断标志完全一致时计入`duplicate_count`，不重复保存；
|
||||
2. 两个业务键均未使用时以`source_type=device`保存并计入`accepted_count`；
|
||||
3. 任一业务键已经对应不同终稿时返回409 `TRANSCRIPT_TURN_CONFLICT`，冲突项位于`error.details.conflicts`，整批新增全部回滚；
|
||||
4. 留存模式为`none`或文字留存授权已经撤回/过期时返回403 `TRANSCRIPT_STORAGE_NOT_ALLOWED`；
|
||||
5. 至少新增一条终稿时可靠投递内容再提取任务；相同幂等请求只返回原合并结果，不重复生成任务。
|
||||
|
||||
终端收到409后不得覆盖云端终稿，应记录冲突并拉取云端通话内容供排查；网络失败或503时保持原正文和原幂等键退避重试，但必须为每次HTTP请求生成新的签名随机数。
|
||||
|
||||
## 10. 批量遥测、错误与命令结果
|
||||
|
||||
设备在通话中或空闲期均可调用`POST /device/v2/telemetry:batch`，每批提交1—500条按设备单调编号的事件。事件类型分为`status`、`error`和`command_result`，每条事件必须提供设备内唯一的`event_key`、`sequence_no`和发生时间，并且只携带与`event_type`对应的同名对象。请求需使用设备签名和16—128字符`Idempotency-Key`。
|
||||
|
||||
- `status`更新设备实际固件、实际配置版本、网络、RTC和录音队列快照；旧序号不能覆盖新快照，报告版本高于云端期望版本返回409。
|
||||
- `error`只接受最长80字符的有限错误码和`warning/error/critical`级别，不接收可能包含个人信息的自由文本堆栈。
|
||||
- `command_result`把属于当前设备且未过期的命令收敛到`ACKNOWLEDGED/SUCCEEDED/FAILED`，并同步固件分配进度；结果对象递归拒绝密钥、令牌、口令、私钥和凭据字段。
|
||||
- `conversation_id`可选，但一旦提交，云端必须验证通话属于当前签名设备；终态或停止中的通话返回`stop_conversation`动作，不能借遥测访问任意长者的通话。
|
||||
- 完全相同的事件计入`duplicate_count`；同一事件键或序号对应不同内容返回409 `TELEMETRY_EVENT_CONFLICT`并回滚整批。响应还可返回`refresh_config`或`pull_commands`动作。
|
||||
|
||||
当前命令结果字段是本地联调基线，硬件团队给出最终设备能力表和结果格式后，应先更新OpenAPI兼容说明再调整实现；不能依赖固件User-Agent猜测字段版本。
|
||||
|
||||
## 11. 运行模拟设备与端到端冒烟
|
||||
|
||||
完整环境启动后执行：
|
||||
|
||||
```powershell
|
||||
Set-Location E:\Codex\story\platform
|
||||
docker compose --profile simulation run --rm sim-device
|
||||
```
|
||||
|
||||
模拟器默认执行`bootstrap`和配置读取，只打印状态与脱敏编号，不打印签名密钥。默认设备公开编号为`10000000-0000-0000-0000-000000000511`；可通过`SIM_API_URL`、`SIM_DEVICE_ID`和`SIM_DEVICE_SECRET`覆盖本地值。
|
||||
|
||||
`SIM_SCENARIO`支持逗号分隔的场景：
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| `bootstrap` | 启动、时间同步和版本化配置读取 |
|
||||
| `offline` | 先向不可达端点发起请求，确认本地保留后使用新Nonce重连 |
|
||||
| `conversation` | 创建、创建重放、激活并轮询到ACTIVE、心跳、停止和停止重放 |
|
||||
| `transcript` | 对本次或`SIM_CONVERSATION_ID`指定通话补交最终字幕并验证幂等重放 |
|
||||
| `telemetry` | 批量上报设备状态，可关联本次通话，并验证幂等重放 |
|
||||
| `commands` | 拉取当前设备未终结命令；普通命令提交合成成功结果，`firmware_update`执行私有下载、SHA-256、Ed25519签名、安装和确认状态链 |
|
||||
| `media` | 为`SIM_CONVERSATION_ID`指定且具有当前录音授权的通话生成或读取WAV PCM16文件，直传对象存储，轮询至云端校验完成，并在`local_delete_after`到达后回报本地密文已删除；可设置`SIM_MEDIA_FILE`、`SIM_MEDIA_DURATION_MS`、`SIM_MEDIA_TRACK`、`SIM_MEDIA_VERIFY_TIMEOUT`和`SIM_MEDIA_DELETE_WAIT_MAX` |
|
||||
| `all` | 依次执行启动、完整通话、字幕、遥测和命令；录音因需要单独授权和可访问的对象存储公开地址而不自动包含 |
|
||||
|
||||
例如执行联合模拟闭环：
|
||||
|
||||
```powershell
|
||||
docker compose --profile simulation run --rm -e SIM_SCENARIO=offline,conversation,transcript,telemetry,commands sim-device
|
||||
```
|
||||
|
||||
固件执行器不会信任命令下发通道携带的公钥。运行前必须通过`SIM_FIRMWARE_TRUSTED_KEYS`预置本地信任锚，值为“密钥编号到标准Base64 Ed25519公钥”的JSON对象，例如`{"vendor-2026":"<32字节公钥的Base64>"}`。执行器只接受固定的`/device/v2/firmware-releases/{id}/download`相对路径，拒绝任意公网地址、查询参数、片段和路径穿越；下载对象限制为1字节至256 MiB。下载后先校验小写SHA-256，再使用本机型号、硬件版本、实际字节数和命令清单重建`firmware-manifest-v1`并验证签名，全部通过才进入安装阶段。`SIM_DEVICE_MODEL`和`SIM_DEVICE_HARDWARE_REVISION`默认分别为`simulated-terminal`和`sim-rev-a`，必须与制品签名清单一致。
|
||||
|
||||
`SIM_FIRMWARE_FAULT`可设置为`download_failed`、`digest_mismatch`、`signature_mismatch`、`install_failed`、`interrupt_after_download`或`interrupt_after_install`；默认`none`。前三类安全失败和安装失败都会提交明确的`FAILED`终态；两类中断保留`ACKNOWLEDGED`阶段，设备进程重新启动后会重新拉取同一未终结命令并从安全起点重复执行，不把状态回退为`DELIVERED`。`SIM_FIRMWARE_STEP_DELAY`可在0至30秒内模拟下载校验后及安装后的耗时。
|
||||
|
||||
启用`SIM_FIRMWARE_AB_UPDATE=true`后，模拟器把制品写入非活动分区，使用`SIM_FIRMWARE_STATE_FILE`持久化启动尝试，并上报`staging`、`reboot_pending`和`boot_verifying`细分阶段。启动健康失败或超过`SIM_FIRMWARE_BOOT_HEALTH_WINDOW`会恢复旧分区并以`FAILED/rolled_back`报告已执行回退；`power_loss_after_stage`、`power_loss_during_boot`和`boot_health_failed`只在A/B模式下允许。完整状态、字段、顺序和真机边界见[设备A/B分区固件升级与启动确认协议](device-firmware-ab-protocol.md)。
|
||||
|
||||
轻量纵向验收执行：
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-sim-firmware.ps1
|
||||
```
|
||||
|
||||
脚本只建立一个临时公钥、一个签名版本、一个单设备批次和一条命令，先在制品校验完成后模拟进程中断，再以同一设备重新运行并核对`SUCCEEDED/CONFIRMED/100`及影响汇总，最后精确清理数据库和对象存储夹具。若目标设备已有未终结命令，脚本会在创建夹具前停止，避免消费真实在途任务。
|
||||
|
||||
仅验证A/B启动失败自动回退时执行`-Mode ABRollback`。该模式只增加一个本地状态文件，不增加固件版本或目标设备数量；验证完成后同样精确清理。
|
||||
|
||||
本地实测组合场景已收敛为`COMPLETED|COMPLETED`，供应商Start/Stop各1次、3条最终话轮（2条供应商+1条设备补交）、1条关联遥测且无开放Outbox。录音场景可在宿主机使用`go run ./cmd/sim-device`执行，以便`localhost:59000`短期上传地址可达；模拟器会等待校验结果并自动提交删除回执。Compose本地环境把`MEDIA_LOCAL_DELETE_GRACE`设为1秒，生产默认值仍为1小时。若删除时间超过`SIM_MEDIA_DELETE_WAIT_MAX`，模拟器明确打印计划时间并安全退出，不会提前回报。`SIM_MEDIA_FILE`仅作为操作人员提供的输入夹具，模拟器只释放内存副本，绝不删除该源文件。
|
||||
|
||||
完整环境启动后，可执行自动化通话冒烟：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-conversation.ps1
|
||||
```
|
||||
|
||||
脚本会验证创建、首次激活、相同幂等键重放、Worker调用、两次签名回调去重和最终`ACTIVE`状态，并断言供应商仅启动一次。脚本只使用合成数据，验证结束后按本次通话编号精确清理数据库痕迹。
|
||||
|
||||
## 12. 错误处理
|
||||
|
||||
| HTTP状态 | 错误码 | 处理建议 |
|
||||
|---|---|---|
|
||||
| 400 | `VALIDATION_FAILED` | 修正字段后重新生成随机数和签名 |
|
||||
| 401 | `DEVICE_AUTHENTICATION_FAILED` | 检查设备登记、时钟、摘要、签名或是否发生重放 |
|
||||
| 503 | `DEVICE_AUTHENTICATION_UNAVAILABLE` | 退避后使用新随机数重试，不关闭鉴权 |
|
||||
| 503 | `DEVICE_CONFIG_UNAVAILABLE` / `DEVICE_BOOTSTRAP_FAILED` | 退避重试并保留上一次有效配置 |
|
||||
| 503 | `RUNTIME_CONFIG_UNAVAILABLE` | 生产环境没有命中活动语音路由；停止创建通话，由运营发布或恢复目标范围配置 |
|
||||
| 403 | `CONSENT_REQUIRED` | 不重试，等待有效授权 |
|
||||
| 403 | `TRANSCRIPT_STORAGE_NOT_ALLOWED` | 停止补传，等待留存策略或授权恢复，不得本地绕过 |
|
||||
| 409 | `DEVICE_NOT_BOUND` / `CONVERSATION_ALREADY_ACTIVE` | 修复绑定或查询已有通话 |
|
||||
| 409 | `IDEMPOTENCY_KEY_REUSED` | 不得用同一幂等键提交不同正文 |
|
||||
| 409 | `ROOM_ALLOCATION_EXPIRED` | 重新创建通话并取得新的房间预留 |
|
||||
| 409 | `RTC_ALLOCATION_MISMATCH` | 丢弃本地房间资料，重新拉取或重建通话 |
|
||||
| 409 | `CONFIG_VERSION_CONFLICT` | 先重新获取设备配置再尝试创建新通话 |
|
||||
| 409 | `PROVIDER_EVENT_CONFLICT` | 供应商事件编号复用且正文不同，转人工排查 |
|
||||
| 409 | `CONVERSATION_STATE_CONFLICT` | 查询云端当前通话状态，不要强制覆盖状态机 |
|
||||
| 409 | `TRANSCRIPT_TURN_CONFLICT` | 保留本地终稿和冲突明细，禁止覆盖云端终稿，转入人工对账 |
|
||||
| 409 | `TELEMETRY_EVENT_CONFLICT` | 保留冲突事件并停止推进本地确认点，人工核对事件键和单调序号 |
|
||||
| 404 | `TELEMETRY_CONVERSATION_NOT_FOUND` | 删除错误通话引用，不得改用任意长者编号重试 |
|
||||
| 409 | `DEVICE_COMMAND_STATE_CONFLICT` | 重新拉取命令；不得覆盖已过期、已取消或其他设备的命令 |
|
||||
| 503 | `TRANSCRIPT_BATCH_UNAVAILABLE` | 使用原幂等键和原正文退避重试，并生成新的设备签名随机数 |
|
||||
| 503 | `DEVICE_TELEMETRY_UNAVAILABLE` | 保留本地事件队列，以原正文和原幂等键退避重试 |
|
||||
| 503 | `CONVERSATION_HEARTBEAT_UNAVAILABLE` / `CONVERSATION_STOP_UNAVAILABLE` | 使用新随机数退避重试；停止请求保留原幂等键和原正文 |
|
||||
|
||||
服务端故意不区分“设备不存在”“设备已吊销”和“签名错误”的外部提示，避免泄露设备登记状态；内部可通过请求关联编号排障。
|
||||
@@ -0,0 +1,125 @@
|
||||
# 真机、真实供应商、试点与生产发布外部验收清单
|
||||
|
||||
> 用途：把本地已验证能力与必须由业务方、硬件方、供应商和生产环境共同完成的验收明确分开。
|
||||
> 原则：前一阶段退出条件未满足，不进入下一阶段；所有证据使用生产候选版本号、构建摘要、配置版本和请求关联编号归档。
|
||||
|
||||
## 1. 外部输入与责任人
|
||||
|
||||
开始准备外部环境时，可先运行以下轻量预检。它只读取Git元数据、Compose运行服务、外部配置变量名称和证据索引，不读取密钥值，也不会调用真实供应商或执行完整回归：
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File scripts/stage8-preflight.ps1 `
|
||||
-EvidenceIndex testdata/release-evidence-index.example.v2.json `
|
||||
-OutputPath artifacts/stage8-preflight.json
|
||||
```
|
||||
|
||||
自动化入口可增加`-Strict`；当候选提交、远程仓库、真实构建摘要或证据索引结构尚未就绪时返回非零退出码。该报告仅用于定位进入条件，不替代十类一致性报告和`cmd/release-evidence`最终校验。
|
||||
|
||||
| 输入 | 提供方 | 最低要求 | 未提供时影响 |
|
||||
|---|---|---|---|
|
||||
| 量产候选终端、板卡/音频硬件版本、设备证书注入流程 | 硬件/设备团队 | 至少3台，含目标麦克风、扬声器、网络模组和安全存储 | 无法验证采集质量、AEC、断网补传、升级和吊销 |
|
||||
| 火山RTC正式测试应用、房间权限、回调和用量查询账号 | RTC供应商/平台团队 | 与生产同区域和同能力，密钥进入云KMS/Secrets Manager | 正式Token与签名Start/Stop适配器已完成，但不能确认真实入房、可选事件回调和计费 |
|
||||
| 豆包实时语音/大模型、Embedding及内容安全账号 | Agent/供应商团队 | 明确模型版本、区域、额度、SLA、数据使用和留存条款 | 不能完成真实语音质量、模型效果、召回和内容安全验收 |
|
||||
| 生产OIDC租户、运营角色和审批人员 | IAM/安全团队 | 客户、客服、操作、审批、管理员角色及两名独立审批账号 | 不能验证真实组织映射、双人审批和离职回收 |
|
||||
| 云PostgreSQL、Redis、对象存储、KMS/HSM、监控和告警接收器 | 云平台/SRE | 私网、TLS、备份、跨可用区、容量配额和告警路由 | 不能完成生产等价恢复、密钥轮换和容量结论 |
|
||||
| 试点家庭、长者授权文本、隐私政策和退出流程 | 业务/法务/试点运营 | 书面知情同意、联系人、异常升级和数据删除承诺 | 不允许进入家庭试点 |
|
||||
|
||||
## 2. 真机与真实供应商联调
|
||||
|
||||
### 2.1 进入条件
|
||||
|
||||
- 固定一个生产候选提交和OpenAPI版本，V1—当前迁移在空库与备份恢复库均通过；
|
||||
- 真实密钥只通过云密钥引用注入，镜像、Git、日志和工单中无明文；
|
||||
- 设备出厂身份、吊销名单、RTC应用、回调地址、IP/域名白名单和时钟同步已配置；
|
||||
- 明确联调窗口、供应商技术联系人、回滚负责人和故障升级路径。
|
||||
- 使用`POST /api/v1/ops/diagnostics/acceptance-snapshots`生成`REAL_DEVICE_PROVIDER`快照，候选版本、镜像摘要、迁移和实际必需依赖均已冻结；若存在阻断告警，按快照公开编号和资源核对状态转入告警工作台复核，不能仅凭`MISSING`自动关闭；技术门禁通过只作为进入联调的必要条件，不替代本节退出条件。
|
||||
- 在告警工作台对每个实际活动路由执行`POST /api/v1/ops/alert-routing-policies/{id}/delivery-tests`，状态必须收敛为`DELIVERED`，接收端按`test_ref`只记录一次且逻辑接收组映射正确；测试不会生成正式告警，不能替代至少一次受控正式告警演练。
|
||||
- 导出活动路由、联通测试、已解决的正式演练告警和网关脱敏采集，使用`cmd/alert-receiver-conformance`生成`PASS/REAL_RECEIVER`报告；证据包内`alert_receiver_validation.coverage_complete=true`后，`REAL_ALERT_RECEIVER`才可标记`VERIFIED`。
|
||||
|
||||
### 2.2 必测场景
|
||||
|
||||
| 领域 | 场景 | 通过标准与证据 |
|
||||
|---|---|---|
|
||||
| 设备身份 | 首次启动、正文篡改、Nonce重放、时钟偏差、证书吊销 | 正常请求成功；异常均稳定拒绝；吊销后新请求和新通话立即失败；保存请求编号和安全审计 |
|
||||
| RTC | 正常入房、错房间、错用户、过期Token、续签、网络切换 | 仅绑定的房间/用户可入；短期Token不落业务库/日志；Wi-Fi/蜂窝切换后状态可收敛 |
|
||||
| 语音 | 近讲/远讲、打断、回声、静音、噪声、长时通话 | 由业务方冻结主观评分方法和采样条件；保存设备型号、音频参数、供应商任务编号和原始评测记录 |
|
||||
| 供应商任务 | 启动超时、未知结果、重复/乱序回调、停止、停止后晚到终稿 | 固定任务编号；未知先查询；回调不回退终态；停止不受启动熔断影响；晚到终稿触发新提取版本 |
|
||||
| 离线补偿 | 断网重连、字幕批量补交、遥测补交、录音断点续传 | 业务键幂等，无重复话轮/分片；旧遥测不覆盖新状态；补交后后台任务全部收敛 |
|
||||
| 固件 | 签名验证、灰度、暂停、失败重试、A/B双向升级、写入后断电、首次启动断电、健康超时和人工回滚 | 非法签名拒绝；暂停不新增投递；灰度进度与设备回执一致；至少3台候选设备各形成4份`PASS/HARDWARE_CAPTURE`一致性报告，A→B、B→A、健康超时和人工回滚另有操作记录；缺项保持`REAL_DEVICE_FIRMWARE/PENDING` |
|
||||
| 隐私 | 授权撤回、主体删除、导出、临时敏感数据提权 | 撤回后停止新增留存；删除六子系统对账；临时提权双人审批、到期拒绝、逐次访问审计 |
|
||||
|
||||
### 2.3 退出条件
|
||||
|
||||
- 至少3台候选终端完成连续通话、断网恢复和升级/回滚，未出现跨设备、跨长者或跨租户数据串用；
|
||||
- 同一候选构建的真机固件证据达到3台×4结构化场景，`release-candidate-evidence-bundle-v3`中的`firmware_validation.coverage_complete=true`；模拟器报告不得计入真机覆盖；
|
||||
- 使用`cmd/rtc-conformance`归档至少3台候选终端的6通精简矩阵，报告必须为`PASS/REAL_DEVICE_RTC_PROVIDER`，证据包内`real_device_rtc_validation.coverage_complete=true`；模拟供应商不得计入。
|
||||
- 供应商启动、停止、回调、用量和错误码映射与接口契约一致，所有未知差异已有书面处置结论；
|
||||
- 使用`cmd/agent-models-conformance`归档真实内容生成10类固定评测、Embedding六类召回/隔离、内容安全六类策略和数据条款/额度证据；报告必须为`PASS/REAL_AGENT_MODELS`，证据包内`real_agent_models_validation.coverage_complete=true`。
|
||||
- 发现的问题均进入V36联调问题台账并具备严重级别、根因、修复版本和脱敏回归证据；清单全量汇总显示未关闭HIGH/CRITICAL为0；
|
||||
- 真实凭据完成一次轮换，旧凭据失效且业务不中断。
|
||||
- 使用`cmd/kms-rotation-conformance`归档同一候选构建的云提供器、工作负载身份、动态读取和滚动重启两类轮换；报告必须为`PASS/REAL_KMS_HSM`，证据包内`kms_rotation_validation.coverage_complete=true`。
|
||||
- 以相同候选构建重新生成验收快照并归档，六项技术门禁均通过；若候选构建变化，原快照作废并重新执行受影响场景。
|
||||
|
||||
## 3. 家庭试点
|
||||
|
||||
### 3.1 进入条件
|
||||
|
||||
- 法务批准知情同意、隐私说明、录音/字幕/故事/记忆分项授权、退出与删除流程；
|
||||
- 试点运营、客服、SRE和安全值班表已发布，告警接收器和工单系统可用；
|
||||
- 每个家庭有明确设备、长者、成员和授权边界，初始配置版本及灰度范围已冻结；
|
||||
- 已生成`PILOT`验收快照，范围与本次试点客户组织/设备组一致，方舟和RTC等实际依赖不得从必需列表中省略；
|
||||
- 备份恢复、供应商故障、固件暂停/回滚和隐私删除演练通过。
|
||||
|
||||
### 3.2 试点节奏
|
||||
|
||||
1. 内部员工家庭小范围验证，确认安装、网络、音频、授权和客服流程；
|
||||
2. 少量外部家庭灰度，按客户组织/设备组限制并发影响，逐日评审告警、修订率、失败原因和成本；
|
||||
3. 扩大前召开门禁评审，仅对新通话发布新配置，任何异常可回滚到上一已发布版本；
|
||||
4. 试点结束执行授权盘点、导出/删除抽查、设备回收或转正式登记和问题复盘。
|
||||
|
||||
### 3.3 试点证据
|
||||
|
||||
- 每日：由`POST /api/v1/ops/diagnostics/pilot-daily-snapshots`按约定业务时区生成并归档设备在线、通话状态分布、供应商失败、上传积压、告警和费用快照；日报编号、日期、时区和复核人写入试点台账，异常转入告警或联调问题闭环；
|
||||
- 每周：由`POST /api/v1/ops/diagnostics/pilot-weekly-snapshots`按周一开始的业务自然周生成并归档人工修订率、故事/记忆确认、隐私请求、固件分布和配置版本差异；平台没有投诉权威表，必须另附同周期客服或CRM脱敏投诉证据，`is_complete=false`的周中快照不得替代完整周报；
|
||||
- 个案：请求编号、设备/通话公开编号、供应商任务编号、配置版本、处置时间线和结果；
|
||||
- 退出：每个试点家庭的授权、数据保留、设备归属和待删除资源确认单。
|
||||
|
||||
## 4. 生产发布门禁
|
||||
|
||||
### 4.1 技术门禁
|
||||
|
||||
- CI在远程仓库实际通过，并用`cmd/ci-supply-chain-conformance`绑定完整提交、远程运行、14项检查、后端/Web镜像摘要及源码/双镜像三份CycloneDX SBOM；报告必须为`PASS/REMOTE_CI_SUPPLY_CHAIN`，本地工具链报告不得计入；
|
||||
- 生产等价容量测试达到业务方冻结的RPS、并发、时延和持续时间，数据库/Redis/对象存储无不可接受饱和；
|
||||
- PostgreSQL备份恢复、Redis丢失重建、API/Callbacks/Worker滚动重启、供应商停机与恢复演练通过；
|
||||
- 使用`cmd/recovery-conformance`归档同一候选的四类演练，报告必须为`PASS/PRODUCTION_EQUIVALENT`，证据包内`production_recovery_validation.coverage_complete=true`；本地Compose报告不得计入。
|
||||
- 使用`cmd/infrastructure-conformance`归档同一候选的七类基础设施和规定控制项，报告必须为`PASS/PRODUCTION_INFRASTRUCTURE`，证据包内`production_infrastructure_validation.coverage_complete=true`；本地可达性和静态清单不得计入。
|
||||
- 云KMS/HSM轮换、证书到期告警、外部基础设施探针和真实告警接收器均有实测证据；
|
||||
- 最近两个Chrome/Edge和macOS最近两个Safari版本通过关键流程；
|
||||
- 使用`cmd/safari-conformance`归档同一候选在真实Safari `CURRENT/PREVIOUS`、两视口和六流程的24项结果；报告必须为`PASS/REAL_SAFARI`，证据包内`safari_compatibility_validation.coverage_complete=true`。
|
||||
- 核心模块覆盖率和关键分支覆盖率达到需求规定门槛，当前本地未达标项必须在发布前关闭或由风险负责人书面接受。
|
||||
- 已使用生产候选镜像摘要生成`PRODUCTION_RELEASE`验收快照；运行版本必须等于候选版本且包含提交号和构建时间，六项技术门禁全部通过。
|
||||
- 使用`cmd/release-evidence`为同一候选版本、镜像摘要和源提交生成最终证据包；十类证据索引不得存在`PENDING`。出现`WAIVED`时必须附有权责任人的书面风险接受，包状态只能进入带豁免的发布评审，不能自动视为批准；八类不可豁免门禁不得使用`WAIVED`。
|
||||
|
||||
### 4.2 业务与合规门禁
|
||||
|
||||
- 产品、硬件、Agent、SRE、安全、法务和试点运营共同签署验收结论；
|
||||
- 供应商合同明确数据地域、训练使用、日志/录音留存、删除时限、SLA和事件通报；
|
||||
- 隐私访问、导出、删除、授权撤回、临时提权和审计留存抽查通过；
|
||||
- 价格版本、额度策略、告警路由、固件目标和运行配置均完成另一人审批；
|
||||
- 发布公告、客服话术、回滚条件、状态页和事故联系人准备完成。
|
||||
|
||||
### 4.3 发布与回滚
|
||||
|
||||
生产采用客户组织/设备组小比例灰度，先验证身份、通话、供应商、上传、费用和告警，再逐级扩大。每一级保存开始/结束时间、版本、范围、观测结果和审批人。出现跨租户、未授权敏感数据访问、无法停止的供应商任务、持续回调验签失败、隐私删除不可对账或高严重度安全事件时立即停止扩量并回滚；历史通话继续使用其冻结配置解释，不重写历史版本。
|
||||
|
||||
## 5. 最终签署表
|
||||
|
||||
| 门禁 | 负责人 | 证据位置 | 结论 | 日期 |
|
||||
|---|---|---|---|---|
|
||||
| 真机与RTC/Agent供应商联调 | 设备/Agent负责人 | 待填写 | 待执行 | — |
|
||||
| 生产等价容量与恢复 | SRE | 待填写 | 待执行 | — |
|
||||
| 安全、KMS/HSM与供应链 | 安全负责人 | 待填写 | 待执行 | — |
|
||||
| 隐私、合同与试点授权 | 法务/业务负责人 | 待填写 | 待执行 | — |
|
||||
| 浏览器与运营工作台 | QA | 待填写 | Safari待执行 | — |
|
||||
| 核心覆盖率与发布风险 | 研发负责人 | `coverage.integration.out`及CI | 当前未通过 | 2026-08-23 |
|
||||
| 生产灰度与回滚批准 | 发布经理 | 待填写 | 待执行 | — |
|
||||
@@ -0,0 +1,122 @@
|
||||
# 固件真机联调一致性证据采集与校验说明
|
||||
|
||||
## 1. 目标
|
||||
|
||||
固件一致性证据用于回答“设备本地实际发生了什么”与“云端收到并据此处置了什么”是否一致。它把设备侧Bootloader、分区、启动尝试和健康结果，与云端可靠命令、固件阶段回执和批次终态绑定，避免只凭页面最后状态或设备口头说明判断升级结果。
|
||||
|
||||
本功能包含三部分：
|
||||
|
||||
1. V38`firmware_assignment_event`不可变事件表，留存每次下载、安装、写分区、重启、启动健康确认和回退回执；
|
||||
2. 设备侧`firmware-device-evidence-v1`脱敏证据格式；
|
||||
3. `cmd/firmware-conformance`离线校验命令，输出带输入SHA-256和逐项结论的`firmware-conformance-report-v1`报告。
|
||||
|
||||
校验结果为`PASS`只表示两份输入在协议、身份、顺序和结果上相互一致。模拟器证据固定标记为`PROTOCOL_SIMULATION`，真机证据标记为`HARDWARE_CAPTURE`；两者都保留`external_validation_required=true`，不能据此自动批准生产发布。
|
||||
|
||||
## 2. 云端阶段事件
|
||||
|
||||
设备通过`POST /device/v2/commands/{id}/ack`直接回执，或通过批量遥测中的`command_result`补交结果时，云端在更新命令和固件分配的同一事务内写入阶段事件。任一步失败会整体回滚，不会出现命令已变化但事件缺失的半完成状态。
|
||||
|
||||
事件使用`assignment_id + command_status + result_digest`唯一键去重。`result_digest`是服务端对规范JSON结果摘要计算的小写SHA-256；完全相同的重复ACK仍保持命令幂等，但不会生成重复时间线记录。不同进度、阶段、启动尝试或终态具有不同摘要，会形成新的事件。
|
||||
|
||||
| 字段 | 用途 |
|
||||
|---|---|
|
||||
| `command_id` | 对外设备命令编号，绑定设备证据 |
|
||||
| `command_status`、`assignment_status` | 命令状态和云端固件分配主状态 |
|
||||
| `phase`、`progress_percent`、`result_code` | 设备阶段、进度和稳定结果码 |
|
||||
| `active_slot`、`target_slot`、`previous_slot`、`failed_slot` | A/B分区转换和失败分区 |
|
||||
| `boot_attempt_id`、`boot_health_deadline` | 同一次启动尝试和健康窗口 |
|
||||
| `rollback_applied`、`rollback_version` | 是否实际回退及回退版本 |
|
||||
| `installed_version` | 成功确认的目标版本 |
|
||||
| `verified_sha256`、`verified_signing_key_id` | 设备实际验证的制品和本地信任锚编号 |
|
||||
| `result_digest`、`reported_at` | 去重摘要和云端接收时间 |
|
||||
|
||||
事件只保留固件状态和非敏感标识，不返回完整`result_summary`。原结果摘要继续留在当前分配和命令记录中，并受既有递归敏感字段拒绝规则保护。批次详情按设备、云端接收时间和事件编号升序返回时间线；V38之前创建的历史批次没有倒推事件，页面明确显示“暂无逐步时间线”，不会伪造历史。
|
||||
|
||||
## 3. 设备证据格式
|
||||
|
||||
设备侧文件必须使用`firmware-device-evidence-v1`，未知字段被校验器拒绝，避免采集程序和校验程序在未评审的情况下悄然漂移。
|
||||
|
||||
| 分类 | 必需字段 |
|
||||
|---|---|
|
||||
| 候选身份 | `candidate_version`、`build_digest`，摘要格式为`sha256:<64位小写十六进制>` |
|
||||
| 证据来源 | `evidence_source=SIMULATOR/HARDWARE` |
|
||||
| 设备身份 | 设备公开编号、型号、硬件版本、发布编号、命令编号 |
|
||||
| 平台基线 | Bootloader版本、分区表SHA-256、是否启用安全启动 |
|
||||
| 制品身份 | 固件SHA-256、设备本地采用的签名密钥编号 |
|
||||
| 测试场景 | `AB_SUCCESS`、`AB_ROLLBACK`、`POWER_LOSS_AFTER_STAGE`或`POWER_LOSS_DURING_BOOT` |
|
||||
| 分区与版本 | 初始、目标、最终分区及初始、目标、最终版本 |
|
||||
| 启动尝试 | `boot_attempt_id`及设备本地事件时间线 |
|
||||
| 采集时间 | UTC`collected_at`，不得早于任何本地事件 |
|
||||
|
||||
设备证据不得包含设备HMAC密钥、私钥、Token、完整序列号、家庭、长者、录音、字幕、网络口令或云账号。量产采集适配器应从受控Bootloader环境区、只读系统版本文件和升级日志生成证据，并在离开设备前完成字段白名单过滤。
|
||||
|
||||
## 4. 一致性校验项
|
||||
|
||||
校验器逐项输出`PASS/FAIL`，任何一项失败都会使总结果为`FAIL`：
|
||||
|
||||
1. 设备证据版本和来源合法；
|
||||
2. 候选版本及构建摘要完整；
|
||||
3. 设备、发布、命令公开编号和型号/硬件版本完整；
|
||||
4. Bootloader及分区表摘要存在；
|
||||
5. 制品摘要和签名密钥编号完整；
|
||||
6. 云端批次唯一包含目标设备；
|
||||
7. 云端批次与设备证据引用同一发布；
|
||||
8. 云端时间线包含设备声明的已验证摘要和签名密钥；
|
||||
9. 全部云端事件绑定同一命令；
|
||||
10. 云端事件UUID、结果摘要哈希和接收顺序有效；
|
||||
11. 设备本地事件顺序有效且不晚于采集时间；
|
||||
12. 场景和必需阶段顺序正确；
|
||||
13. 云端与设备引用同一启动尝试；
|
||||
14. 同名设备/云端阶段最大时间差不超过10分钟；
|
||||
15. 最终分区、版本、命令终态、分配终态及回退事实一致。
|
||||
|
||||
时间相关性使用同名阶段的最近时间，不要求设备与云端毫秒级相等；超过10分钟通常表示设备时钟、采集时区、离线补交或证据混用问题，必须先解释并重新采集，不能手工修改报告。
|
||||
|
||||
## 5. 命令用法
|
||||
|
||||
先以有权查看固件批次的账号下载`GET /api/v1/firmware-rollouts/{id}`完整JSON响应，再从设备导出证据文件。校验在离线环境执行：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/firmware-conformance `
|
||||
-cloud C:\evidence\rollout-response.json `
|
||||
-device C:\evidence\device-evidence.json `
|
||||
-output C:\evidence\firmware-conformance-report.json
|
||||
```
|
||||
|
||||
输出路径必须为绝对路径，文件权限限制为当前用户可读写。通过时进程退出码为0，业务不一致时仍写出完整失败报告并返回1，参数、文件或JSON格式错误返回2。报告包含两份输入文件的SHA-256，可在归档后判断输入是否被替换；报告不复制云端完整结果摘要或设备原始日志。
|
||||
|
||||
## 6. 模拟闭环
|
||||
|
||||
模拟器在A/B模式下可通过以下变量生成独立设备侧证据：
|
||||
|
||||
| 变量 | 作用 |
|
||||
|---|---|
|
||||
| `SIM_FIRMWARE_EVIDENCE_FILE` | 设备证据绝对路径 |
|
||||
| `SIM_FIRMWARE_EVIDENCE_SCENARIO` | 本次场景 |
|
||||
| `SIM_CANDIDATE_VERSION`、`SIM_BUILD_DIGEST` | 候选构建身份 |
|
||||
| `SIM_BOOTLOADER_VERSION` | 模拟Bootloader版本 |
|
||||
| `SIM_PARTITION_TABLE_SHA256` | 模拟分区表摘要 |
|
||||
| `SIM_SECURE_BOOT_ENABLED` | 模拟安全启动状态，只允许true/false |
|
||||
|
||||
运行以下单条低强度烟测：
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-sim-firmware.ps1 -Mode ABRollback
|
||||
```
|
||||
|
||||
脚本断言云端形成7条去重事件：两条下载、安装开始、非活动分区写入、等待重启、启动健康检查和已回退；随后使用模拟器独立生成的设备证据执行校验器。报告必须全部通过、范围必须是`PROTOCOL_SIMULATION`且必须继续声明外部验收未完成。烟测结束删除临时数据库记录、对象、固件、状态、两份输入和报告。
|
||||
|
||||
## 7. 真机交付要求
|
||||
|
||||
硬件团队应为每台候选设备的A→B、B→A、写入后断电、首次启动断电、健康超时和人工回滚分别交付设备证据与云端批次快照。研发或QA使用同一候选校验器生成报告，并把原输入及报告一并放入候选证据库。任何`FAIL`、不同命令编号、不同启动尝试、摘要不一致或时间差超限都必须进入联调问题台账；不得只保留截图或手工修改后的汇总表。
|
||||
|
||||
## 8. 阶段8发布证据包门禁
|
||||
|
||||
`cmd/release-evidence`使用`release-evidence-index-v2`中的`REAL_DEVICE_FIRMWARE`登记真机报告，并在`release-candidate-evidence-bundle-v3`清单内生成`firmware_validation`覆盖摘要。当前自动门禁要求至少3台不同候选设备中的每一台都完成以下四种可由一致性校验器结构化确认的场景：
|
||||
|
||||
- `AB_SUCCESS`：候选分区启动并完成健康确认；实际联调同时覆盖A→B和B→A方向；
|
||||
- `AB_ROLLBACK`：启动健康失败或超时后自动回到旧分区；人工回滚另附操作与审计证据；
|
||||
- `POWER_LOSS_AFTER_STAGE`：写入完成、切换启动前断电并恢复；
|
||||
- `POWER_LOSS_DURING_BOOT`：首次候选分区启动期间断电并恢复。
|
||||
|
||||
每份报告必须是`PASS/HARDWARE_CAPTURE`，候选版本、构建摘要、公开设备/发布/批次/命令编号、两份输入摘要和全部20项检查必须完整。相同设备和场景只能登记一次。缺少任一设备或场景时，`REAL_DEVICE_FIRMWARE`必须保持`PENDING`，打包清单会列出每个场景的设备计数和缺口；把不完整项标记为`VERIFIED`会直接拒绝打包。该门禁不可用`WAIVED`绕过，也不接受`PROTOCOL_SIMULATION`报告。人工回滚、A/B双向覆盖及硬件团队签署继续作为同一证据项的外部复核材料，不因结构化四场景通过而自动获得生产批准。
|
||||
@@ -0,0 +1,140 @@
|
||||
# 固件制品、签名、灰度与回滚开发说明
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
固件发布链路用于向已绑定家庭的兼容数据采集终端下发经过校验的固件制品。平台不保存固件私钥，也不在浏览器或服务端生成生产签名；生产私钥应保存在离线签名机、HSM或云密钥管理服务中。平台只登记受信任的Ed25519公钥、校验签名和摘要，并通过短期私有对象地址向被分配的设备提供下载。
|
||||
|
||||
## 2. 数据对象
|
||||
|
||||
| 对象 | 关键内容 | 状态 |
|
||||
|---|---|---|
|
||||
| `firmware_signing_key` | 租户、密钥编号、Ed25519公钥、创建人 | `ACTIVE`、`REVOKED` |
|
||||
| `firmware_release` | 家庭、设备型号、硬件版本、版本号、对象引用、大小、SHA-256、签名、密钥编号及安全基线 | `UPLOADING`、`READY`、`PAUSED`、`RETIRED` |
|
||||
| `firmware_rollout` | 固件版本、批次名称、灰度比例、创建人、开始/完成时间 | `DRAFT`、`RUNNING`、`PAUSED`、`COMPLETED`、`ROLLED_BACK` |
|
||||
| `firmware_assignment` | 批次、设备、可靠命令、原版本、下载/安装进度、最近回执 | `ASSIGNED`、`DOWNLOADING`、`INSTALLING`、`CONFIRMED`、`FAILED`、`ROLLED_BACK` |
|
||||
|
||||
## 3. 签名清单
|
||||
|
||||
Ed25519签名输入使用确定性UTF-8文本，字段顺序和末尾换行不可改变：
|
||||
|
||||
```text
|
||||
firmware-manifest-v1
|
||||
model={设备型号}
|
||||
hardware_revision={硬件版本}
|
||||
version={固件版本}
|
||||
sha256={小写SHA-256}
|
||||
size={字节数}
|
||||
```
|
||||
|
||||
研发辅助命令`go run ./cmd/firmware-sign <model> <hardware-revision> <version> <file>`会生成临时密钥并输出测试签名，只能用于合成数据和本地冒烟，不能代替生产签名设施。
|
||||
|
||||
## 4. 发布流程
|
||||
|
||||
1. 所有者或管理员登记受信任的Ed25519公钥；编辑者和查看者无权操作。
|
||||
2. 管理端提交制品元数据，平台创建`UPLOADING`版本并返回15分钟私有上传地址。
|
||||
3. 管理端直接上传制品到私有对象存储，业务API不转发大文件。
|
||||
4. 管理端请求完成版本；平台流式核对实际大小和SHA-256，再使用租户内活动公钥验证清单签名。
|
||||
5. 只有两项校验均通过，版本才进入`READY`；摘要、大小或签名不匹配均不能进入灰度流程。
|
||||
6. 网络中断或原上传地址过期时，管理端必须重新选择与原记录大小和SHA-256完全一致的文件；平台仅为仍处于`UPLOADING`的版本重新签发15分钟上传地址，并在覆盖同一私有对象后重复执行完成校验。无法继续的版本可正式转为`RETIRED`并清理对象；退役后允许以相同业务版本重新创建纠正后的制品，但退役历史和审计仍保留。
|
||||
7. 管理端选择已绑定且型号/硬件兼容的设备和1—100灰度比例。平台按设备编号确定性选样，并至少选择一台目标设备。
|
||||
8. 每台目标设备生成一条幂等`firmware_update`可靠命令。设备使用HMAC身份拉取命令，再请求5分钟私有下载地址。
|
||||
9. 设备在本地再次校验摘要和厂商签名，并通过命令回执上报`downloading`、`installing`阶段及0—100进度；云端依次映射为`DOWNLOADING`、`INSTALLING`。
|
||||
10. 安装完成后设备上报`SUCCEEDED`或`FAILED`，分配记录进入`CONFIRMED`或`FAILED`。全部目标终态后，批次自动收敛为`COMPLETED`或`PAUSED`。
|
||||
|
||||
## 5. 暂停与回滚
|
||||
|
||||
暂停仅允许作用于`RUNNING`批次。平台将批次改为`PAUSED`，取消尚未投递的`QUEUED`命令，并立即禁止该批次继续取得固件下载地址。已经下载或正在安装的设备不能依赖云端强制中断，设备固件必须实现本地安全停止点和启动失败自动回退。
|
||||
|
||||
回滚不是修改原制品，而是选择另一个已经完成摘要及签名验证的`READY`版本，针对原批次全部目标设备创建新的100%可靠批次。这样可以保留完整版本、命令、设备结果和审计链。
|
||||
|
||||
## 6. 接口
|
||||
|
||||
| 方法与路径 | 用途 |
|
||||
|---|---|
|
||||
| `POST /api/v1/households/{id}/firmware-signing-keys` | 登记受信任公钥 |
|
||||
| `GET /api/v1/households/{id}/firmware-signing-keys` | 查询租户可信公钥台账、指纹、状态及固件引用数量 |
|
||||
| `POST /api/v1/households/{id}/firmware-signing-keys/revoke` | 在引用保护通过后吊销可信公钥 |
|
||||
| `POST /api/v1/households/{id}/firmware-releases` | 创建版本和短期上传地址 |
|
||||
| `GET /api/v1/households/{id}/firmware-releases` | 查询固件版本、校验状态及元数据 |
|
||||
| `POST /api/v1/firmware-releases/{id}/finalize` | 校验大小、摘要和签名 |
|
||||
| `GET /api/v1/firmware-releases/{id}/impact` | 汇总关联批次、设备阶段、命令处置和仍需观察设备 |
|
||||
| `POST /api/v1/firmware-releases/{id}/upload-session` | 为仍处于上传中的版本重新签发15分钟私有上传地址 |
|
||||
| `POST /api/v1/firmware-releases/{id}/pause` | 暂停已验证版本分发，并暂停关联运行批次、取消未投递命令 |
|
||||
| `POST /api/v1/firmware-releases/{id}/resume` | 在签名密钥仍活动时恢复版本分发，不自动恢复旧批次 |
|
||||
| `POST /api/v1/firmware-releases/{id}/retire` | 退役版本；未完成对象尝试清理，已验证对象和历史保留 |
|
||||
| `POST /api/v1/households/{id}/firmware-rollouts` | 创建灰度批次 |
|
||||
| `GET /api/v1/households/{id}/firmware-rollouts` | 查询家庭内最近灰度批次及结果汇总 |
|
||||
| `GET /api/v1/firmware-rollouts/{id}` | 查询批次、逐设备阶段、进度和最近回执 |
|
||||
| `POST /api/v1/firmware-rollouts/{id}/pause` | 暂停批次并取消未投递命令 |
|
||||
| `POST /api/v1/firmware-rollouts/{id}/rollback` | 使用已验证版本建立回滚批次 |
|
||||
| `GET /device/v2/firmware-releases/{id}/download` | 被分配设备取得短期私有下载地址 |
|
||||
|
||||
完整字段、错误结构和响应模型以`openapi/openapi.yaml`为准。
|
||||
|
||||
设备登记记录中的`minimum_firmware_version`是新通话准入策略，与固件制品声明的`minimum_security_version`用途不同。前者比较设备当前固件并阻止低版本创建通话，后者描述该制品运行所需的安全基线。调整准入策略属于设备注册/运维配置职责；发布一个新制品不会自动抬高所有设备的通话下限，避免灰度期间未升级设备被意外整体阻断。
|
||||
|
||||
V37将固件业务版本唯一性调整为仅约束未退役记录，并把空主板版本统一视为同一值。这样同一租户内相同型号、主板和版本不能同时存在两个活动清单；只有原`UPLOADING`版本正式退役后，才允许使用相同业务版本创建纠正后的制品。退役记录不会物理删除，历史审计仍可追溯。完成校验和退役都使用带原状态条件的更新并检查实际影响行数，二者并发时只有一个状态转换能够成功。
|
||||
|
||||
可信公钥按租户形成独立台账。查询接口只返回SHA-256指纹、状态、登记/吊销时间以及`UPLOADING`版本、`READY`版本和`RUNNING`批次引用数量，不返回原始公钥。密钥编号一经登记即绑定同一公钥：相同编号和相同公钥可幂等重放，不同公钥不得覆盖，已吊销编号不得重新激活；轮换必须先用新编号登记新公钥，再让新版本引用新编号。存在上传中版本或运行中灰度批次时禁止吊销，避免中断完成校验或在途升级；仅有已就绪历史版本时允许吊销，但吊销后这些版本不能再启动新灰度，且新版本也不能引用该密钥。
|
||||
|
||||
已验证版本支持`READY → PAUSED → READY`和`READY/PAUSED → RETIRED`生命周期。暂停版本在同一事务把关联`RUNNING`批次转为`PAUSED`，取消尚未投递的`QUEUED`设备命令；新灰度创建和新下载地址都会因版本不再是`READY`而被拒绝。已经签发的短期下载地址无法远程收回，最长仍可能在原5分钟有效期内使用；已经下载或进入安装的设备继续依靠设备端安全停止点和失败回退，页面需继续观察其状态。恢复版本前重新核验签名密钥仍为`ACTIVE`，且只恢复版本本身，不自动恢复旧批次或重新创建已取消命令。
|
||||
|
||||
退役未完成版本仍尝试删除可能已上传的对象，并允许重复调用以修复对象存储瞬时清理失败。退役已验证版本时保留不可变制品对象、清单、历史批次和审计，防止破坏取证与追溯；若仍有关联`RUNNING`批次则返回`FIRMWARE_RELEASE_IN_USE`，要求先执行版本暂停。退役后版本永久不能创建新灰度或签发新下载地址。
|
||||
|
||||
版本影响查询使用服务端权威数据实时汇总，不把页面缓存当作处置结果。批次统计区分运行、暂停、完成和已回滚；设备统计区分已分配、下载中、安装中、已确认、失败和已回滚；命令统计单独显示排队、送达、确认、成功、失败、过期以及暂停时取消的未投递命令。仍需观察设备包括`DOWNLOADING`、`INSTALLING`，以及分配仍为`ASSIGNED`但命令已送达、确认或出现结果待对账的设备。接口返回完整汇总和最多100条观察清单，超过100条时设置截断标志，避免页面误把未展示设备理解为已经收敛。
|
||||
|
||||
## 7. 验证
|
||||
|
||||
日常开发优先执行低强度纵向冒烟：
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-sim-firmware.ps1
|
||||
```
|
||||
|
||||
该脚本只创建一个受信公钥、一个签名制品、一个单设备批次和一条升级命令。模拟终端从固定设备接口取得私有地址，限制下载大小，核对SHA-256，并使用`SIM_FIRMWARE_TRUSTED_KEYS`内预置而非命令携带的Ed25519公钥验证`firmware-manifest-v1`签名；校验完成后上报`ACKNOWLEDGED/DOWNLOADING/100`。脚本随后模拟进程中断，重启后重新拉取保持`ACKNOWLEDGED`的同一命令，重复安全校验并上报安装及`SUCCEEDED/CONFIRMED/100`，最后检查版本影响中的已确认、成功命令、已完成批次和零观察设备。夹具数据库记录与对象存储制品在结束时精确清理。
|
||||
|
||||
需要覆盖发布管理全部异常门禁时再运行完整回归：
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-firmware-rollout.ps1
|
||||
```
|
||||
|
||||
脚本验证角色拒绝、合法签名、非法签名拒绝、浏览器跨域直传预检、版本/批次列表、灰度暂停、未投递命令取消、暂停后下载拒绝、已验证版本回滚、设备下载SHA-256、25%下载、80%安装和100%确认状态收敛，并在结束后清理制品及数据库合成数据。
|
||||
|
||||
## 8. Web管理页
|
||||
|
||||
具有`firmware.manage`能力的家庭成员可在“固件发布”页完成公钥登记、制品选择、浏览器SHA-256计算、私有对象直传、服务端签名校验、灰度目标选择、批次暂停和回滚。生产私钥始终不进入页面或平台：页面只接收离线签名结果和公钥。
|
||||
|
||||
登记公钥先在浏览器验证输入是标准Base64编码的32字节Ed25519公钥，并计算SHA-256指纹；页面内受控操作区冻结家庭、密钥编号、长度和完整指纹，要求操作者通过受控渠道核对后再提交。页面会对照可信公钥台账：相同编号和相同指纹只作为幂等登记，不同指纹或已吊销编号直接阻断并提示使用新的轮换编号；服务端仍重新解码公钥、复核不可变编号规则、校验固件管理能力并写入审计。私钥没有输入字段，也不会进入确认区、API请求或平台数据库。
|
||||
|
||||
可信公钥台账在页面显示完整指纹、状态、登记/吊销时间和三类引用数量。只有活动密钥可以进入吊销确认区；存在上传中版本或运行中批次时按钮禁用并展示阻断原因。允许吊销时，确认区固定密钥编号、完整指纹和引用统计并要求确认影响。已吊销密钥仍保留在台账中用于历史追溯，但不能登记替换、创建新版本或启动新灰度。
|
||||
|
||||
制品上传先由浏览器计算文件SHA-256，并验证离线签名是标准Base64编码的64字节Ed25519签名。页面允许填写最低安全基线和最长2000字符的发布说明；受控操作区冻结家庭、型号、主板、版本、文件名、实际大小、完整摘要、签名密钥编号以及逐字段`firmware-manifest-v1`清单。只有操作者确认离线签名对应这份清单后，页面才创建15分钟私有上传地址、把原始文件直接PUT到对象存储并调用完成校验；任一步失败都不会把版本显示为`READY`，只有服务端流式核对大小、摘要和活动公钥签名全部通过才进入灰度候选。
|
||||
|
||||
版本停留在“等待校验”时，版本卡片提供“恢复上传”和“退役未完成版本”两个入口。恢复表单在浏览器重新计算所选本地文件摘要，文件大小或完整SHA-256任一不一致即禁止继续；匹配后再进入受控确认区，确认后依次重新签发地址、PUT同一对象和重复完成校验。退役确认区固定家庭、版本编号、清单摘要和签名密钥，明确已就绪版本不会被清理、先前签发地址最多仍可在原15分钟窗口内写入但不能恢复退役状态。退役接口可安全重复，以便对象存储瞬时失败后再次请求清理。
|
||||
|
||||
已验证版本卡片提供“暂停分发”“恢复分发”和“退役版本”。暂停确认区显示版本、完整摘要、签名密钥和运行中批次数，明确暂停会阻断新灰度/新下载、暂停关联批次并取消未投递命令；退役按钮在仍有运行批次时禁用并提示先暂停。已暂停版本只有在签名密钥仍活动时允许恢复，确认区明确旧批次不会自动重启。已验证版本退役确认区明确制品与历史保留、短期地址有效窗口和永久停止分发边界。
|
||||
|
||||
每个版本卡片均提供“查看影响”。影响面板显示版本权威状态、计算时间、关联批次、各设备阶段、排队及已取消命令数量，并逐台列出安装中、下载中或回执待收敛设备的批次、阶段、进度、命令状态和最后上报时间。暂停、恢复或退役成功后，页面同时刷新版本、批次、公钥引用和当前影响面板，使操作者能够核对处置结果；查询本身只读且不写审计或业务状态。
|
||||
|
||||
启动灰度批次使用页面内受控操作表单。版本选择只列出`READY`制品；候选设备必须已注册到当前家庭，且设备型号、硬件版本与所选制品一致。打开确认区时冻结家庭、批次名称、制品编号与摘要、灰度比例以及候选设备编号和当前版本，修改版本会立即清空旧设备选择。操作者确认兼容性和多设备版本变更影响后才提交；服务端再次核验版本、设备归属和兼容性，再按设备编号确定性分桶，至少命中一台设备，并为实际目标创建24小时有效的可靠升级命令。因而页面显示的候选数不被当成最终命中数，也不能绕过服务端状态校验。
|
||||
|
||||
版本列表显示设备型号、硬件版本、固件版本、大小、签名密钥和校验状态；批次详情显示每台设备的`ASSIGNED → DOWNLOADING → INSTALLING → CONFIRMED`进度或失败结果。该页已经在隔离的实际Chrome内完成1440×1000与1024×900渲染检查，未发现横向溢出、控制台错误或失败请求；真实多浏览器兼容性仍属于类生产验收范围。
|
||||
|
||||
批次暂停和版本回滚使用页面内受控操作表单。暂停表单固定当前批次编号、状态、完成比例、设备总数及各状态数量；回滚表单还固定用户选择的`READY`目标版本，避免确认过程中目标漂移。两项操作都要求显式确认对尚未执行设备、在途设备和后续回滚指令的影响；取消，或切换页签、家庭，都会清空草稿且不发送请求。服务端继续校验管理角色、租户、批次状态、目标版本可用性和并发版本。
|
||||
|
||||
本轮按低强度功能验收策略复用既有服务端签名、上传、下载和状态收敛证据，只执行前端生产构建、Web镜像重建以及真实OIDC Chrome无提交冒烟。冒烟分别验证无效公钥/签名阻断、有效输入启用、指纹和清单目标冻结、影响确认及取消关闭；固件公钥、版本和审计数量保持不变，登记/制品创建/完成校验/对象PUT请求均为0，页面无横向溢出、控制台错误或失败请求。灰度批次创建的同轮轻量冒烟继续验证兼容设备选择、确认门禁和零业务写入；本轮不重复执行完整设备下载、安装、暂停和回滚回归。
|
||||
|
||||
上传恢复批次按相同低强度策略执行V37升级、真实PostgreSQL服务/HTTP定向用例、生产构建和一次真实OIDC Chrome无提交冒烟。定向用例覆盖续传地址重签、非管理员拒绝、`READY`禁止续传/退役、退役幂等、退役后禁止完成校验、同业务版本纠正重建及HTTP禁止缓存；浏览器覆盖错误文件阻断、匹配文件启用、恢复/退役目标冻结和取消零写入。临时版本、公钥和审计已清理，页面无溢出、控制台错误或失败请求；完整设备升级回归未重复执行。
|
||||
|
||||
可信公钥台账批次继续采用低强度功能验收：执行真实PostgreSQL服务层和HTTP定向用例、前端生产构建、容器镜像重建以及一次真实OIDC Chrome无提交冒烟。定向用例覆盖同密钥幂等登记、同编号替换拒绝、引用统计、上传中/运行中引用阻断吊销、吊销幂等、吊销后禁止创建版本和启动灰度；浏览器覆盖完整指纹与引用展示、阻断原因、轮换编号提示、吊销目标冻结和取消零写入。未重复执行完整设备下载、安装和回滚回归，临时密钥、版本、批次及审计夹具已清理。
|
||||
|
||||
版本生命周期批次按同一低强度策略执行真实PostgreSQL服务层和HTTP定向用例、前端生产构建、容器重建以及一次真实OIDC Chrome无提交冒烟。定向用例覆盖暂停/恢复幂等、暂停版本阻断新灰度、运行批次与排队命令同步收敛、运行引用阻断退役、吊销密钥阻断恢复、已验证退役保留对象以及稳定HTTP冲突码；浏览器只核对按钮门禁、目标冻结、影响确认和取消零写入，不重复完整设备下载、安装和回滚回归。
|
||||
|
||||
影响预览批次继续采用低强度验证：真实PostgreSQL服务层和HTTP定向用例构造一条排队命令和一台安装中设备，分别核对暂停前后的批次、设备、取消命令和观察清单；前端执行生产构建、容器重建及一次真实OIDC Chrome只读冒烟，核对汇总口径、观察原因、无写请求和页面布局。完整设备升级与回滚回归不重复执行。
|
||||
|
||||
模拟终端执行器批次继续遵循低强度策略：定向Go用例覆盖正常下载、摘要和Ed25519签名校验、下载/摘要/签名/安装失败、两处中断及清单边界；真实PostgreSQL定向用例只核对`ACKNOWLEDGED`命令重拉不发生状态回退。随后仅执行一次“校验后中断—进程重启—重复安全校验—安装确认”的真实服务纵向冒烟，验证两次投递、最终批次与影响汇总，并确认临时密钥、版本、批次、命令、审计和对象夹具清理完成；不重复Web、暂停和回滚全量回归。
|
||||
|
||||
A/B启动确认批次在OpenAPI 0.62.0下扩展可选回执阶段，不增加旧设备必填字段或主状态枚举。启用设备先将制品写入非活动分区并持久化启动尝试，再依次上报`staging`、`reboot_pending`和`boot_verifying`；健康通过才提交成功，健康失败或超时则恢复旧分区并提交`FAILED/rolled_back`及回退版本。云端将三类中间阶段保持为`INSTALLING`，同时保留完整`last_result`供页面展示。低强度验证只执行定向Go用例、前端类型/生产构建和一次B分区启动失败自动回A分区的纵向冒烟，不把模拟结果作为真实Bootloader验收。详细协议见[设备A/B分区固件升级与启动确认协议](device-firmware-ab-protocol.md)。
|
||||
|
||||
OpenAPI 0.63.0和V38进一步为每台固件分配保存去重的阶段事件。直接命令ACK与批量遥测补交在更新命令/分配的同一事务内写入事件，重复结果摘要通过SHA-256唯一键保持幂等；批次详情按设备返回完整时间线，页面显示云端接收时间、阶段、命令状态和稳定结果码。`cmd/firmware-conformance`可把该时间线与设备侧Bootloader/分区证据进行离线一致性校验，详细格式和15项检查见[固件真机联调一致性证据采集与校验说明](firmware-conformance-evidence.md)。
|
||||
@@ -0,0 +1,210 @@
|
||||
# 集成诊断工作台开发说明
|
||||
|
||||
> 对应接口契约：OpenAPI 0.55.0
|
||||
> 适用角色：`ops_viewer`、`ops_operator`、`ops_approver`、`ops_admin`
|
||||
> 适用阶段：模拟联调、真机联调、试点运行和生产故障处置
|
||||
|
||||
## 1. 建设目标与安全边界
|
||||
|
||||
集成诊断工作台用于把设备、通话、RTC房间、供应商任务和接口请求关联到同一条脱敏诊断记录，减少联调时在多个数据库表和日志系统之间人工拼接信息的成本。查询始终使用已经验证的OIDC身份和明确的`X-Tenant-Id`，服务端先解析运营账号与客户组织关系，再固定租户条件执行查询。
|
||||
|
||||
工作台不返回字幕正文、录音地址、RTC短期令牌、设备签名密钥、供应商API Key、Outbox正文或配置密钥内容。`ops_viewer`和`ops_approver`只能查询；`ops_operator`可执行配置刷新、安全停止、状态对账、死信重试和诊断包导出；设备吊销仅允许`ops_admin`执行。所有修改动作必须填写原因、提供幂等键，并记录操作人、请求关联编号、资源和结果。
|
||||
|
||||
字幕正文和原录音不属于诊断查询返回。需要排查内容问题时，必须转入[运营敏感数据临时访问](ops-sensitive-access.md)流程，按单次通话申请最小能力、由另一人审批并逐次审计。
|
||||
|
||||
## 2. 功能设计
|
||||
|
||||
### 2.0 外部依赖预检
|
||||
|
||||
API和Worker按配置周期检查OIDC JWKS、方舟HTTPS入口及火山RTC HTTPS入口。OIDC检查要求响应成功、JSON可解析且至少包含一把签名密钥；方舟和RTC只执行DNS、TCP及证书校验TLS握手，不发送模型或语音业务请求，不消耗额度。V35把每个进程和依赖的最近结果写入平台级状态台账，字段包括最近检查、最近成功/失败、耗时、探针周期、连续失败和有限错误码。台账不保存实际端点、证书正文、原始网络错误或任何凭据。
|
||||
|
||||
联调页面把超过三倍探针周期未更新的记录显示为“结果过期”，即使其最后状态为成功也不能作为当前可用证据。进程启动时删除本进程已停用依赖的旧记录，避免从方舟或RTC切回本地实现后继续展示历史探针。探针失败不会让健康API或Worker退出就绪状态，但会进入Prometheus和告警规则，便于区分“平台自身不可用”和“外部联调条件未满足”。
|
||||
|
||||
### 2.1 精确检索
|
||||
|
||||
| 检索字段 | 输入 | 主要关联路径 | 返回信息 |
|
||||
|---|---|---|---|
|
||||
| `device_id` | 设备公开UUID | `device → conversation → rtc_task` | 设备状态、在线状态、固件/配置版本及相关通话 |
|
||||
| `conversation_id` | 通话公开UUID | `conversation → device/rtc_task/provider_event` | 通话状态、预留期限、房间及供应商任务状态 |
|
||||
| `room_id` | RTC房间编号 | `rtc_task → conversation → device` | 对应通话、设备和供应商任务 |
|
||||
| `provider_task_ref` | 供应商任务编号 | `rtc_task → conversation → device` | 供应商、任务状态、启动/停止尝试次数 |
|
||||
| `request_id` | 接口请求关联编号 | `audit_event → resource → conversation/device` | 该请求涉及的脱敏资源状态 |
|
||||
|
||||
查询只支持完整值匹配，不提供字幕、姓名、手机号等个人数据的模糊检索。单次最多返回50条，设备检索可返回该设备的多条历史通话，其余唯一业务编号通常只返回一条。
|
||||
|
||||
### 2.2 状态展示
|
||||
|
||||
每条记录包含以下诊断字段：
|
||||
|
||||
- 设备公开编号、注册/吊销状态、Redis在线状态、固件版本、期望/已应用配置版本和最近归一化错误码；
|
||||
- 通话公开编号、通话状态、房间资料有效期；
|
||||
- 短期入房凭证签发时间和过期时间，不返回凭证正文、摘要或可重建凭证的签名材料；
|
||||
- RTC房间编号、供应商代号、稳定任务编号、任务状态、启动和停止尝试次数；
|
||||
- 已接收供应商通知数量、最近通知类型与时间；
|
||||
- 最近一次相关请求编号。
|
||||
|
||||
存在通话时，接口同时从`conversation.created_at/ended_at`和`conversation_state_history`的首次状态到达时间计算五类耗时：创建至`ROOM_ISSUED`、房间资料签发至设备确认`STARTING_AGENT`、设备确认至供应商`ACTIVE`、`STOPPING`至最终结束，以及创建至最终结束。尚未到达的阶段返回空值，时间倒置的数据不生成负数；页面以毫秒、秒或分秒展示，不使用浏览器请求时间代替业务阶段耗时。
|
||||
|
||||
### 2.3 授权修复动作
|
||||
|
||||
| 动作 | 允许状态 | 处理结果 |
|
||||
|---|---|---|
|
||||
| 配置刷新 | 设备属于选定客户组织 | 以当前期望版本创建幂等`apply_config`设备命令 |
|
||||
| 状态对账 | `STARTING_AGENT`或`STOPPING` | 分别创建启动/停止对账Outbox任务；稳定状态返回`queued=false` |
|
||||
| 安全停止 | `PREPARING/ROOM_ISSUED` | 不调用供应商，直接收敛为`EXPIRED`并释放房间 |
|
||||
| 安全停止 | `STARTING_AGENT/ACTIVE` | 收敛为`STOPPING`并可靠投递供应商停止任务 |
|
||||
| 安全停止 | `STOPPING`或最终状态 | 幂等返回当前状态，不重复创建副作用 |
|
||||
| 设备吊销 | 设备属于选定客户组织 | 写入吊销时间并立即阻断后续设备签名请求；若存在未结束通话，则在同一事务内过期或可靠停止 |
|
||||
| 死信重试 | 状态为`dead`且事件类型已注册 | 重置为`pending`，保留并递增人工重试次数、操作人和时间；未知事件类型拒绝重试 |
|
||||
| 诊断包导出 | 五类精确检索条件有效 | 生成`ops-diagnostic-minimal-v1`脱敏JSON快照，不写正文副本 |
|
||||
| 发布候选验收快照 | 候选版本、SHA-256构建摘要、环境、范围和必需依赖明确 | 在单个事务内冻结迁移、依赖、问题、任务和告警门禁，生成`ops-acceptance-minimal-v1`归档JSON |
|
||||
| 试点运行日报 | 业务日期、IANA时区和归档原因有效 | 聚合六类运行证据并生成`ops-pilot-daily-minimal-v1`脱敏JSON，不在服务端保存正文 |
|
||||
| 试点运行周报 | 周一业务日期、IANA时区和归档原因有效 | 聚合内容审核、记忆、隐私、固件和配置差异，并明确要求外部投诉证据 |
|
||||
|
||||
配置刷新、状态对账、安全停止和设备吊销均从具体诊断结果卡片打开页面内“受控联调操作”确认区，不再通过浏览器弹窗采集原因。确认区固定展示目标设备；状态对账和安全停止还固定展示目标通话，切换客户组织或重新检索会清除旧操作草稿。操作原因必填、最长500字符，空理由不能提交。安全停止与设备吊销还必须勾选对应影响确认，其中设备吊销明确提示后续签名请求将被拒绝，安全停止明确限定为当前通话。取消只清空页面草稿，不调用修改接口。角色、租户、状态、幂等和审计仍由服务端重新校验，前端确认不能替代服务端门禁。
|
||||
|
||||
诊断包导出和死信重试同样使用页面内表单。导出表单在打开时冻结检索字段和精确编号，展示中文字段名称、完整目标值、脱敏边界和审计提示；用户随后修改检索框不会改变已经打开的导出目标，重新执行查询则清除旧导出草稿。死信重试表单冻结任务公开编号、注册事件类型、聚合类型、自动/人工尝试次数和最近稳定错误码，并要求填写最长500字符的原因，再勾选“根因或依赖问题已经处理”的影响确认。刷新任务列表、切换客户组织或取消会清除旧任务草稿。页面不展示Outbox正文、内部聚合编号或锁信息。
|
||||
|
||||
### 2.4 死信作业摘要
|
||||
|
||||
死信列表最多返回100条，只展示作业公开编号、已注册事件类型、聚合类型、自动尝试次数、人工重试次数、稳定错误码和时间。接口不返回Outbox正文、内部聚合编号或锁持有者。人工重试会重新启用一轮自动重试预算，但不清除人工重试历史；若根因未修复，任务仍会按显式重试分类再次进入退避或死信。
|
||||
|
||||
### 2.5 联调问题闭环
|
||||
|
||||
问题清单按客户组织保存需求P0282规定的可追踪字段：问题现象、严重级别、设备编号、通话编号、发生时间、请求关联编号、责任方、根因、解决结果、修复版本、回归证据和回归结论。设备、通话和请求编号均为诊断引用；记录不得粘贴字幕正文、录音地址、短期凭证、长期密钥或带签名下载地址。设备和通话编号同时填写时，服务端验证二者属于同一关联链，避免建立错误关联。
|
||||
|
||||
问题状态为`OPEN → IN_PROGRESS → RESOLVED → VERIFIED → CLOSED`，严重级别为`LOW/MEDIUM/HIGH/CRITICAL`。重新处理时可以回到`IN_PROGRESS`；进入`RESOLVED`及后续状态必须填写解决结果、根因和修复版本，进入`VERIFIED`或`CLOSED`还必须填写回归结论和脱敏回归证据。V36汇总当前客户组织全部问题，而不是只统计页面最近100条；任何未关闭的HIGH或CRITICAL问题均计入高严重度发布阻断。该布尔结果只证明此项门禁，不替代供应商、真机、安全、恢复和合规门禁。创建请求使用幂等键，后续维护使用强ETag，防止两名联调人员静默覆盖彼此结论。只读运营角色可以查看，`ops_operator`和`ops_admin`可以登记和维护，每次写入均记录独立审计。
|
||||
|
||||
问题维护不再使用连续浏览器弹窗，而是从具体问题卡片打开统一的页面内流转编辑区。编辑区固定问题公开编号、当前状态、当前责任方、现象和ETag版本，再根据动作只显示当前必需字段：调整级别要求选择不同值；接手或重新打开要求最长120字符的责任方；登记解决同时要求根因、最长128字符的修复版本及解决结果；登记回归同时要求脱敏回归证据和结论；关闭要求显式确认已经复核根因、修复版本、解决结果和回归证据。正文类字段最长4000字符。切换筛选、刷新清单、切换客户组织或取消会清除草稿；并发更新仍由服务端`If-Match`校验，冲突时保留页面输入和错误提示供人工复核。
|
||||
|
||||
背景资料准备失败是无需供应商对账的本地终态。精确查询该通话时，诊断记录返回`conversation_status=FAILED`和`conversation_failure_code=context_preparation_failed`，RTC状态、房间和供应商任务均为空；工作台与设备HTTP 422响应使用同一个失败码，联调人员可直接登记问题，不得把空RTC任务误判为任务丢失。
|
||||
|
||||
### 2.6 发布候选验收快照
|
||||
|
||||
验收快照用于阶段8每次真实联调、试点扩量或生产发布前的技术状态冻结。操作人必须填写候选版本、`sha256:`构建摘要、`LAB/STAGING/PRODUCTION`环境、验收类型、覆盖范围、必需外部依赖和最长255字符的归档原因。服务端在一个数据库事务内读取当前迁移版本及脏状态、当前客户组织的联调问题全量汇总、租户及平台级Outbox积压、未解决HIGH/CRITICAL告警，以及所选外部依赖的最新探针状态。
|
||||
|
||||
六项门禁分别为候选构建可识别、数据库迁移清洁、必需依赖当前可用、无未关闭高严重度联调问题、无待处理/处理中/死信可靠任务、无未解决高严重度告警。探针记录超过三倍探针周期即视为过期；缺少记录不能按成功处理。实验室环境允许运行版本为`dev`，便于本地准备；预发布和生产环境要求运行版本等于候选版本，同时提交号和构建时间不能为`unknown`。`overall_gate_satisfied`是六项技术条件的合取结果，不包含真机音频体验、真实供应商协议、灰度观察、容量、安全、合规或人工审批，快照正文固定携带该免责声明。
|
||||
|
||||
OpenAPI 0.51.0在告警计数之外加入最多100条阻断告警定位项，只包含告警公开编号、规则码、级别、处置状态、关联资源类型/公开编号、首次/最近命中时间和资源核对结果。`PRESENT`表示关联资源仍存在，`MISSING`表示快照时已找不到关联公开资源，`AGGREGATE`表示队列类聚合告警，`UNKNOWN`表示该资源类型没有自动存在性判断。该字段不返回告警标题、摘要、接收组或原始错误；`MISSING`只能作为运营复核证据，不能自动关闭告警。总数超过100时`blocking_items_truncated=true`，必须转到告警工作台查看完整队列。
|
||||
|
||||
快照不建立服务端历史表，返回后由浏览器下载归档。页面同时保留本次响应，直接展示六项门禁和阻断告警定位，切换客户组织时立即清除，避免把上一组织的结果误作当前状态。幂等记录保证网络重试返回同一编号与生成时间；审计只保存候选标识、环境、范围、所选依赖、结果和脱敏策略。输出不包含探针地址、凭据、原始错误、告警正文、Outbox正文、字幕或录音。
|
||||
|
||||
### 2.7 试点运行日报
|
||||
|
||||
OpenAPI 0.55.0要求日报绑定候选版本与不可变构建摘要，再按指定IANA时区的自然日生成设备、通话、供应商、上传、告警和费用快照。自然日活动和生成时刻积压采用不同字段，通话始终返回8个状态，费用按币种分列且不做汇率换算。日报只保存幂等和审计元数据，不保存服务端正文；详细口径、接口和数据来源见[试点运行日报开发说明](pilot-daily-operations.md)。
|
||||
|
||||
### 2.8 试点运行周报
|
||||
|
||||
OpenAPI 0.55.0要求周报绑定候选版本与不可变构建摘要，再按周一开始的七个业务自然日生成内容审核、正式记忆、隐私请求、固件分布和配置差异快照。人工修订率和故事确认率同时返回样本数及可计算标识；没有分母时不能解释为0%。平台没有投诉权威表，因此周报固定保留外部投诉证据缺口。详细设计见[试点运行周报开发说明](pilot-weekly-review.md)。
|
||||
|
||||
## 3. 接口设计
|
||||
|
||||
所有接口要求`Authorization: Bearer ...`和`X-Tenant-Id`。修改接口还要求`Idempotency-Key`，请求体为`{"reason":"..."}`。
|
||||
|
||||
| 方法与路径 | 最低角色 | 说明 |
|
||||
|---|---|---|
|
||||
| `GET /api/v1/ops/diagnostics/search?field={field}&value={value}` | `ops_viewer` | 按五类字段精确查询脱敏状态 |
|
||||
| `GET /api/v1/ops/diagnostics/external-dependencies` | `ops_viewer` | 查询API/Worker外部依赖预检台账 |
|
||||
| `POST /api/v1/ops/diagnostics/conversations/{id}/stop` | `ops_operator` | 按当前状态执行本地收敛或可靠停止 |
|
||||
| `POST /api/v1/ops/diagnostics/conversations/{id}/reconcile` | `ops_operator` | 对启动/停止中间态创建幂等对账任务 |
|
||||
| `POST /api/v1/ops/diagnostics/devices/{id}/config-refresh` | `ops_operator` | 创建当前配置重新应用命令 |
|
||||
| `GET /api/v1/ops/diagnostics/jobs` | `ops_viewer` | 查询当前客户组织的脱敏死信摘要 |
|
||||
| `POST /api/v1/ops/diagnostics/jobs/{id}/retry` | `ops_operator` | 对已注册类型的死信作业执行受控重试 |
|
||||
| `POST /api/v1/ops/diagnostics/bundles` | `ops_operator` | 按精确检索条件生成脱敏JSON诊断包 |
|
||||
| `POST /api/v1/ops/diagnostics/acceptance-snapshots` | `ops_operator` | 幂等生成并下载发布候选技术验收快照 |
|
||||
| `POST /api/v1/ops/diagnostics/pilot-daily-snapshots` | `ops_operator` | 按业务自然日幂等生成并下载脱敏试点运行日报 |
|
||||
| `POST /api/v1/ops/diagnostics/pilot-weekly-snapshots` | `ops_operator` | 按周一开始的业务自然周幂等生成并下载脱敏试点运行周报 |
|
||||
| `POST /api/v1/ops/diagnostics/devices/{id}/revoke` | `ops_admin` | 吊销设备，并联动收敛该设备未结束通话 |
|
||||
| `GET /api/v1/ops/integration-issues` | `ops_viewer` | 查询最近100条问题及全量高严重度发布阻断汇总，可按状态筛选 |
|
||||
| `POST /api/v1/ops/integration-issues` | `ops_operator` | 幂等登记问题现象、严重级别、关联编号、发生时间和责任方 |
|
||||
| `PATCH /api/v1/ops/integration-issues/{id}` | `ops_operator` | 使用If-Match维护严重级别、责任方、根因、修复版本和回归证据 |
|
||||
|
||||
成功响应返回动作、最新状态、是否排队和相关命令编号。跨客户组织、只读角色或不存在资源不会泄露其他租户信息；响应统一带`Cache-Control: no-store`。稳定错误包括`OPS_ACCESS_DENIED`、`DIAGNOSTIC_NOT_FOUND`、`DIAGNOSTIC_STATE_CONFLICT`和`IDEMPOTENCY_KEY_CONFLICT`。
|
||||
|
||||
## 4. 业务流程设计
|
||||
|
||||
### 4.1 联调定位流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant O as 联调/运营人员
|
||||
participant API as 诊断API
|
||||
participant DB as PostgreSQL
|
||||
participant R as Redis
|
||||
O->>API: OIDC令牌 + 客户组织 + 精确编号
|
||||
API->>DB: 校验运营账号与租户关系
|
||||
API->>DB: 查询设备/通话/RTC任务/通知/审计
|
||||
API->>R: 查询设备在线状态
|
||||
API-->>O: 返回脱敏统一诊断记录
|
||||
O->>API: 选择修复动作并填写原因、幂等键
|
||||
API->>DB: 锁定资源并检查当前状态
|
||||
API->>DB: 写状态/命令/Outbox与审计
|
||||
API-->>O: 返回最新状态、是否排队和请求编号
|
||||
```
|
||||
|
||||
### 4.2 安全停止流程
|
||||
|
||||
系统先锁定目标通话并重新读取权威状态。尚未启动供应商任务时，只执行本地过期收敛；供应商任务可能存在时，事务内把通话置为`STOPPING`并写可靠停止任务；已在停止或最终状态时直接幂等返回。这样可避免运营页面重复点击产生第二个供应商任务。
|
||||
|
||||
### 4.3 状态对账流程
|
||||
|
||||
只有启动中和停止中状态需要向后台恢复链路排队。任务使用通话内部编号和操作幂等键形成去重边界，Worker继续遵守固定供应商任务编号、未知启动先查询、停止不受启动熔断影响等规则。稳定状态不伪造对账任务。
|
||||
|
||||
### 4.4 设备吊销流程
|
||||
|
||||
系统先锁定设备，再锁定该设备唯一未结束通话。设备状态、`revoked_at`和版本号在事务内更新；`PREPARING/ROOM_ISSUED`通话直接进入`EXPIRED`且RTC任务进入`COMPLETED`，`STARTING_AGENT/ACTIVE`通话进入`STOPPING`并写入可靠停止任务，已经`STOPPING`则不重复投递。状态历史、吊销审计和停止意图与设备吊销一起提交，避免出现“身份已失效但云端任务继续运行”的分裂状态。
|
||||
|
||||
### 4.5 死信恢复与诊断包流程
|
||||
|
||||
运营人员先根据稳定错误码修复依赖，再选择死信任务、填写原因并提交。服务端锁定任务，确认租户、`dead`状态和已注册类型后重置待执行字段并记录人工重试元数据。诊断包则复用同一套精确查询和租户边界，把当前脱敏状态序列化为JSON；导出编号、条件、条数和脱敏策略进入审计，但服务端不建立新的内容副本。
|
||||
|
||||
### 4.6 联调问题处理流程
|
||||
|
||||
联调人员先通过精确诊断检索确认设备、通话和请求关联编号，可从诊断结果一键带入三个编号，再补充问题现象、严重级别和责任方。责任方接手后把状态置为处理中，完成修复后填写根因、修复版本和解决结果并置为待回归；回归人员按可复现步骤验证，登记请求关联号、诊断包编号、重复次数等脱敏证据和结论，最后关闭问题。若回归失败或问题复现，记录回到处理中，原解决结果、回归证据和审计历史继续保留。HIGH或CRITICAL问题在关闭前持续阻断对应发布门禁。服务端通过版本条件更新保证并发修改可见，不以最后写入者静默覆盖前一人的结论。
|
||||
|
||||
### 4.7 发布候选技术预检流程
|
||||
|
||||
运营人员先冻结候选版本和构建摘要，再按本次联调或发布范围选择真实必需依赖。API完成角色和客户组织校验后，在幂等事务中依次读取迁移、问题、探针、可靠任务和告警状态，计算六项独立门禁及总结果，同时写入最小审计。浏览器下载JSON后交由阶段8证据库归档；任一门禁失败时以`gates`中的稳定代码定位处理项，修复后使用新的幂等键重新生成，不修改旧快照。技术门禁全部通过后仍需继续执行真实设备、供应商、灰度和人工审批清单。
|
||||
|
||||
## 5. 数据库设计
|
||||
|
||||
诊断模块不建立正文副本或独立影子库，复用以下权威表：
|
||||
|
||||
| 表 | 用途 |
|
||||
|---|---|
|
||||
| `device`、`device_twin`、`device_presence_state` | 设备身份、吊销时间、固件、期望/已应用配置和在线状态 |
|
||||
| `conversation`、`conversation_state_history` | 通话权威状态和状态变更依据 |
|
||||
| `rtc_task`、`provider_event` | RTC房间、短期凭证签发/过期时间、供应商稳定任务编号、尝试次数及通知摘要；V28只新增凭证时间元数据 |
|
||||
| `device_command` | 配置刷新命令及设备回执 |
|
||||
| `outbox_event` | 启动/停止对账和可靠停止任务；V26增加公开编号、人工重试次数、时间和操作人 |
|
||||
| `audit_event` | 操作人、原因、请求编号、资源和结果 |
|
||||
| `idempotency_record` | 修改动作的重放、并发和正文冲突保护 |
|
||||
| `integration_issue` | V30联调问题权威记录；V36增加严重级别、根因、修复版本、脱敏回归证据和高严重度汇总索引 |
|
||||
| `external_dependency_probe_state` | V35平台级探针当前状态、周期、时间、有限错误码和连续失败次数；不保存端点或凭据 |
|
||||
| `schema_migrations`、`alert_incident` | 验收快照读取迁移脏状态和未解决HIGH/CRITICAL告警；不复制告警正文 |
|
||||
| `upload_batch`、`media_segment`、`conversation_usage_event`、`conversation_cost_line` | 试点日报读取上传活动/积压与按币种费用，不建立日报副本 |
|
||||
|
||||
查询所有连接条件同时包含或继承客户组织边界；HTTP只暴露公开UUID。运营修改在同一数据库事务内完成状态、可靠任务和审计写入，任一步失败则整体回滚。验收快照和试点日/周报复用权威表及`idempotency_record/audit_event`，OpenAPI 0.50.0—0.55.0不新增数据库迁移或快照持久化表。
|
||||
|
||||
## 6. 验证
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-diagnostics.ps1
|
||||
pwsh -NoProfile -File .\scripts\smoke-acceptance-snapshot.ps1
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\smoke-pilot-daily-snapshot.ps1
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\smoke-pilot-weekly-snapshot.ps1
|
||||
```
|
||||
|
||||
烟测使用真实本地OIDC令牌和设备HMAC签名，验证五类查询、跨租户403、稳定状态对账、配置刷新、安全停止、死信重试、脱敏诊断包、设备吊销、请求编号回查和精确数据清理。联调问题采用定向数据库与HTTP验证，覆盖创建重放、租户隔离、严重级别阻断、根因/修复版本/回归证据门禁、关闭后汇总恢复和旧ETag冲突。服务集成测试另覆盖活动通话随设备吊销进入`STOPPING`并只投递一个停止任务。生产验收仍需使用真实设备、真实供应商账号和实际值班角色重复执行。
|
||||
|
||||
日常页面可用性采用一条轻量真实OIDC冒烟：`test/e2e/visual-ops-sensitive-access-request.mjs`创建临时通话诊断记录、已注册类型的临时死信任务及覆盖五种状态的临时问题记录，依次打开诊断包导出、配置刷新、状态对账、安全停止、设备吊销、死信重试、六种问题流转和敏感访问申请表单，验证目标绑定、字段门禁、ETag展示、危险操作显式确认、取消关闭以及零修改/导出请求。检查要求零横向溢出、零控制台错误和零失败请求，并在`finally`精确清理夹具。该检查不实际下载诊断包、修改问题、重试任务、停止通话或吊销种子设备，服务端副作用仍由上述HTTP与集成测试证明。
|
||||
|
||||
外部预检日常验证只运行V35迁移、`internal/externalprobe`定向用例和真实OIDC纵向查询。页面检查使用：
|
||||
|
||||
```powershell
|
||||
$env:PLAYWRIGHT_REQUIRE_FROM='C:\Users\19926\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules'
|
||||
$env:CHROME_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
|
||||
node .\scripts\visual-diagnostics-ui.cjs
|
||||
```
|
||||
|
||||
该检查确认本地Keycloak的`api/oidc_jwks`为当前可用、服务归属和检查时间可见、接口无端点或原始错误字段；同时使用真实登录从页面下载实验室验收快照和试点运行日/周报，核对门禁、固定分布、统计守恒、外部投诉证据缺口与归档JSON后精确清理审计/幂等夹具，并保存`test/e2e/screenshots/operations/ops-diagnostics-workspace.png`。本地未配置方舟、火山RTC或托管内容安全时不生成对应成功记录；真实联调或生产快照必须把实际使用的方舟、RTC和`content_safety_tls`列为必需依赖。
|
||||
@@ -0,0 +1,69 @@
|
||||
# 云KMS/HSM密钥轮换一致性证据
|
||||
|
||||
## 1. 目标与验收边界
|
||||
|
||||
`cmd/kms-rotation-conformance`用于把同一候选构建下的云密钥提供器、工作负载身份、版本切换、新旧凭据认证结果、业务连续性探针和提供器访问审计形成`kms-rotation-conformance-report-v1`。本地环境变量、Docker Secret或普通文件演练只能输出`LOCAL_SECRET/external_validation_required=true`；只有目标预生产或生产环境的云KMS、HSM、Secret Manager或等价受控提供器证据完整时，报告才为`REAL_KMS_HSM`。
|
||||
|
||||
报告不包含密钥值、令牌、数据库连接串或可还原的密钥摘要。它使用提供器版本引用、脱敏探针引用和审计引用证明“轮换的是哪一个受控版本、谁读取了它、业务如何验证、旧版本如何失效”。报告通过不等于业务发布批准，也不替代厂商侧权限审计和安全负责人签署。
|
||||
|
||||
## 2. 证据格式
|
||||
|
||||
输入文件使用`kms-rotation-capture-v1`并严格拒绝未知字段。顶层字段包括：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `evidence_source` | 本地演练填`LOCAL`，真实云KMS/HSM填`KMS_HSM` |
|
||||
| `candidate_version/build_digest` | 必须与候选证据包一致 |
|
||||
| `environment` | 本地为`LOCAL`；真实证据只能是`STAGING`或`PRODUCTION` |
|
||||
| `provider_ref` | 不含租户凭据的云提供器或HSM稳定引用 |
|
||||
| `workload_identity_ref` | API、Callbacks、Worker等实际工作负载身份引用 |
|
||||
| `provider_audit_ref` | 提供器访问审计、版本变更审计或受控工单引用 |
|
||||
| `attested_by_ref/attested_at` | 安全或平台复核人脱敏引用与复核时间 |
|
||||
| `rotations` | 一次或多次密钥轮换观测 |
|
||||
|
||||
每条`rotations`必须保存密钥和消费者的非秘密引用、消费模式、不同的新旧版本引用、轮换时间，以及以下五类可复核结果：轮换前基线、新凭据成功、旧凭据拒绝、业务连续性、提供器访问审计。`secret_value_not_exported=true`声明采集过程没有导出密钥正文；该字段为false会使报告失败。
|
||||
|
||||
## 3. 两种消费模式
|
||||
|
||||
真实报告必须同时覆盖：
|
||||
|
||||
- `DYNAMIC_READ`：逐设备密钥等按请求从CSI原子挂载目录重新读取的凭据；新版本生效后下一次请求使用新值，过渡窗口结束后旧值被拒绝；
|
||||
- `ROLLING_RESTART`：数据库、Redis、RTC、供应商、对象存储、方舟和进程级签名密钥等启动时读取的凭据；挂载版本更新后执行受控滚动重启，新Pod就绪再终止旧Pod，并确认旧版本失效。
|
||||
|
||||
只验证其中一种消费模式的云端报告仍为`FAIL`。本地报告允许只验证一种模式，以便开发环境检查工具链，但始终保留外部验收缺口。
|
||||
|
||||
## 4. 自动检查
|
||||
|
||||
报告包含11项检查：采集版本、证据来源、候选身份、采集候选绑定、提供器/身份/审计、两种轮换范围、版本转换、新凭据接受、旧凭据拒绝、业务连续性和全部探针/审计引用。任一失败使总结果为`FAIL`。
|
||||
|
||||
真实证据满足以下条件后才设置`external_validation_required=false`：来源为`KMS_HSM`、环境是预生产或生产、提供器和工作负载身份完整、至少两条轮换覆盖两种消费模式、新旧版本不同、新凭据成功、旧凭据拒绝、业务连续性通过、密钥正文未导出且所有审计引用存在。
|
||||
|
||||
## 5. 命令用法
|
||||
|
||||
```powershell
|
||||
go run ./cmd/kms-rotation-conformance `
|
||||
-capture E:\evidence\kms-rotation-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\kms-rotation-report.json
|
||||
```
|
||||
|
||||
输出路径必须为绝对路径。通过返回0，不一致时仍写出失败报告并返回1，文件、参数或JSON格式错误返回2。报告保存输入采集文件SHA-256，用于归档后检测替换。
|
||||
|
||||
## 6. 候选证据包门禁
|
||||
|
||||
`release-evidence-index-v2`中的`KMS_ROTATION`不可豁免。第一个文件必须是`PASS/REAL_KMS_HSM`报告并绑定同一候选；后续可以附SecretProviderClassPodStatus脱敏导出、云审计、滚动发布记录和安全签署材料。没有真实报告时，v3清单固定显示：
|
||||
|
||||
- `REAL_KMS_HSM_REPORT:0/1`；
|
||||
- `DYNAMIC_READ:0/1`；
|
||||
- `ROLLING_RESTART:0/1`。
|
||||
|
||||
本地报告、单一消费模式、跨候选版本、缺旧凭据拒绝、缺业务连续性或缺云审计时，`KMS_ROTATION`必须保持`PENDING`，不能使用`WAIVED`绕过。
|
||||
|
||||
## 7. 本地低强度演练
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\verify-local-secret-rotation.ps1
|
||||
```
|
||||
|
||||
脚本沿用现有本地设备HMAC轮换：原密钥请求成功，启动同镜像临时API并注入新密钥，新密钥请求成功、旧密钥返回401、就绪接口持续可用，随后恢复Compose API及原本地密钥。新增步骤把结果输出为`PASS/LOCAL_SECRET`报告，并确认它仍要求外部验证。脚本结束删除临时容器、采集和报告，不改变真实KMS门禁。
|
||||
@@ -0,0 +1,241 @@
|
||||
# Kubernetes部署手册
|
||||
|
||||
## 1. 适用范围
|
||||
|
||||
本手册用于把数据采集终端—云端系统部署到预生产或生产Kubernetes集群。仓库提供Kustomize基线，不在集群内自建PostgreSQL、Redis、对象存储、OIDC、OpenTelemetry Collector或外部模型/语音服务；这些依赖应使用已备份、可监控且具备生产SLA的托管或平台服务。
|
||||
|
||||
清单只定义应用工作负载，不包含任何真实Secret。`deploy/kubernetes/base/configmap.yaml`中的`.example.invalid`、24位全零RTC App ID和`replace-with-*`是不可用占位值。生产服务的启动门禁会拒绝这些值，避免占位配置被误发布。
|
||||
|
||||
## 2. 目录与发布单元
|
||||
|
||||
| 目录 | 用途 | 是否可重复应用 |
|
||||
|---|---|---|
|
||||
| `deploy/kubernetes/base` | 四个应用Deployment、Service、Ingress、PDB、HPA和NetworkPolicy | 是 |
|
||||
| `deploy/kubernetes/overlays/staging` | 预生产环境覆盖层，`APP_ENV=stage` | 是 |
|
||||
| `deploy/kubernetes/overlays/production` | 生产环境覆盖层，`APP_ENV=prod` | 是 |
|
||||
| `deploy/kubernetes/overlays/production-csi` | 生产环境覆盖层，并以Secrets Store CSI替代应用Kubernetes Secret卷 | 是 |
|
||||
| `deploy/kubernetes/migration` | 数据库向前迁移一次性Job | 每次发布前执行并等待完成 |
|
||||
| `deploy/kubernetes/migration-csi` | 从Secrets Store CSI文件读取数据库连接串的迁移Job | 每次发布前执行并等待完成 |
|
||||
|
||||
API、Callbacks和Worker共用一个后端镜像，通过容器命令分别启动`/app/api`、`/app/callbacks`和`/app/worker`。Web使用独立Nginx镜像。迁移镜像只包含固定版本的`migrate`程序和当前仓库`migrations`目录。
|
||||
|
||||
## 3. 集群前置条件
|
||||
|
||||
部署前应具备：
|
||||
|
||||
1. Kubernetes 1.27或更高版本，并启用支持`autoscaling/v2`的Metrics Server。
|
||||
2. Nginx Ingress Controller；基线假定控制器命名空间为`ingress-nginx`。
|
||||
3. 证书控制器或人工创建的TLS Secret `voice-platform-tls`。
|
||||
4. 监控系统；基线假定Prometheus位于`monitoring`命名空间。
|
||||
5. 支持pgvector的PostgreSQL、启用认证的Redis、TLS对象存储和HTTPS OIDC。
|
||||
6. 火山RTC/豆包语音、火山方舟内容模型和1536维Embedding模型的真实账号与已开通资源。
|
||||
7. 推荐使用External Secrets Operator或云KMS Secrets Store CSI Driver。若平台采用不同的Ingress或监控命名空间，必须同步修改NetworkPolicy。
|
||||
|
||||
生产数据库连接必须启用TLS，例如`sslmode=verify-full`；对象存储必须启用TLS；OIDC Issuer和JWKS必须为HTTPS。数据库迁移账号可与运行账号分离，但迁移Job使用的账号必须具有执行当前迁移所需的DDL权限。
|
||||
|
||||
## 4. 构建和推送镜像
|
||||
|
||||
为同一次发布使用不可变版本号或Git提交摘要，不要复用`latest`：
|
||||
|
||||
```powershell
|
||||
$Version = "2026.08.23-<commit>"
|
||||
$Registry = "registry.company.example/voice-platform"
|
||||
|
||||
docker build -f deploy/backend.Dockerfile -t "$Registry/backend:$Version" .
|
||||
docker build -f deploy/web.Dockerfile -t "$Registry/web:$Version" .
|
||||
docker build -f deploy/migrate.Dockerfile -t "$Registry/migrate:$Version" .
|
||||
|
||||
docker push "$Registry/backend:$Version"
|
||||
docker push "$Registry/web:$Version"
|
||||
docker push "$Registry/migrate:$Version"
|
||||
```
|
||||
|
||||
在目标覆盖层的`kustomization.yaml`中把三个镜像名称和版本改成上述不可变地址。建议由流水线写入镜像摘要，并在发布记录中保存后端、Web和迁移镜像的对应关系。
|
||||
|
||||
## 5. 非敏感环境配置
|
||||
|
||||
不要直接修改`base`作为某个现场的长期配置。复制环境覆盖层或增加一个现场补丁，至少替换下列字段：
|
||||
|
||||
| 配置 | 说明 |
|
||||
|---|---|
|
||||
| `REDIS_ADDR` | Redis主机与端口，不含密码 |
|
||||
| `AUTH_ISSUER_URL`、`AUTH_JWKS_URL` | HTTPS OIDC地址 |
|
||||
| `AUTH_AUDIENCE` | Web/API共同使用的Audience |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP gRPC地址 |
|
||||
| `EXTERNAL_PROBE_INTERVAL` | OIDC、方舟和RTC外部探针周期，默认30秒 |
|
||||
| `RTC_APP_ID` | 真实24字符火山RTC App ID |
|
||||
| `OBJECT_STORE_ENDPOINT` | 应用访问对象存储的TLS端点 |
|
||||
| `OBJECT_STORE_PUBLIC_ENDPOINT` | 浏览器短期下载地址使用的公网TLS端点 |
|
||||
| `OBJECT_STORE_EXPORT_BUCKET`、`OBJECT_STORE_REGION` | 私有导出桶和区域 |
|
||||
| `ARK_CONTENT_MODEL` | 已开通的方舟内容模型Endpoint ID |
|
||||
| `ARK_EMBEDDING_MODEL` | 已开通且输出1536维向量的Endpoint ID |
|
||||
| `CONTENT_SAFETY_PROVIDER`、`CONTENT_SAFETY_ENDPOINT` | `managed_http`和正式HTTPS分类端点 |
|
||||
| `CONTENT_SAFETY_POLICY_REF`、`CONTENT_SAFETY_TIMEOUT` | 已批准且不可变的策略版本和调用超时 |
|
||||
| `WEB_OIDC_AUTHORITY`、`WEB_OIDC_CLIENT_ID` | 浏览器可见的OIDC公开配置 |
|
||||
| Ingress `host`和TLS Secret | 正式域名与证书Secret |
|
||||
|
||||
`APP_ENV=prod`会启用严格生产门禁。不要通过改回`stage`绕过配置错误；应修正真实配置后再发布。
|
||||
|
||||
## 6. Secret清单
|
||||
|
||||
下列Secret必须在`voice-platform`命名空间预先存在。文件名就是Secret的key，Secret内容不得提交到Git或写入普通ConfigMap。
|
||||
|
||||
| Secret名称 | 必需key | 使用者 |
|
||||
|---|---|---|
|
||||
| `voice-platform-common-secrets` | `database-url`、`redis-password` | API、Callbacks、Worker、迁移Job |
|
||||
| `voice-platform-api-secrets` | `rtc-app-key`、`cursor-signing-secret`、`share-token-signing-secret` | API |
|
||||
| `voice-platform-callbacks-secrets` | `provider-callback-secret` | Callbacks |
|
||||
| `voice-platform-worker-secrets` | `volc-access-key-id`、`volc-secret-access-key`、`voice-chat-template.json` | Worker |
|
||||
| `voice-platform-model-storage-secrets` | `object-store-access-key`、`object-store-secret-key`、`ark-api-key`、`content-safety-api-key` | API、Worker；内容安全Key仅由Worker引用 |
|
||||
| `voice-platform-device-secrets` | 每台设备一个key，例如`terminal-001` | API |
|
||||
| `voice-platform-tls` | `tls.crt`、`tls.key` | Ingress |
|
||||
|
||||
游标签名密钥和分享签名密钥必须各不少于32字节且互不相同。供应商回调密钥不少于32字节。数据库连接串和Redis密码由应用通过`*_FILE`读取；应用错误日志不会输出Secret内容。
|
||||
|
||||
每台量产设备在数据库中的`credential_ref`应写为`device-secret://terminal-001`，对应`voice-platform-device-secrets`中的`terminal-001`文件。名称只允许安全的单层文件名。Kubernetes Secret或CSI卷原子更新后，API会在下一次设备验签时读取新值，无需重启。
|
||||
|
||||
`voice-chat-template.json`可从`deploy/volcengine/voice-chat-template.example.json`复制结构。生产文件必须使用`voice-chat-template-bundle-v1`并同时包含`s2s_pure`、`s2s_hybrid`和`cascade`三个模板；示例中的`TemplateBodyMustBeReplaced`表示整个`Config`对象都应按现场已开通的官方语音能力替换，不是一个可直接提交给供应商的字段。平台按通话冻结模式选中模板后覆盖AppId、RoomId、TaskId、设备用户、Agent用户和授权背景，模板中不要固定这些请求级字段。若现场模型或音色字段需要由已发布Agent组合动态提供，应在官方字段对应位置填写`{{MODEL_RESOURCE_REF}}`或`{{VOICE_RESOURCE_REF}}`；还可用`{{AGENT_BUNDLE_VERSION}}`、`{{PERSONA_VERSION}}`、`{{VOICE_VERSION}}`、`{{MODEL_VERSION}}`和`{{ROUTING_VERSION}}`写入供应商允许的追踪字段。未使用的占位符无需添加。
|
||||
|
||||
如使用火山临时凭据，可在Worker Secret增加`volc-session-token`，并通过现场补丁增加`VOLC_SESSION_TOKEN_FILE=/var/run/secrets/voice-platform/worker/volc-session-token`。如启用告警Webhook，同样应以现场补丁配置HTTPS `ALERT_WEBHOOK_URL`，并通过Secret文件注入`ALERT_WEBHOOK_SECRET_FILE`。
|
||||
|
||||
首次创建命名空间后再由密钥平台同步Secret：
|
||||
|
||||
```powershell
|
||||
kubectl apply -f deploy/kubernetes/base/namespace.yaml
|
||||
kubectl -n voice-platform get secret
|
||||
```
|
||||
|
||||
不建议在命令行直接传入密钥明文。短期人工联调只能使用`kubectl create secret generic --from-file=...`从受控临时文件创建，并在完成后安全清理临时文件和终端历史。
|
||||
|
||||
### 6.1 Secrets Store CSI模式
|
||||
|
||||
生产环境推荐使用`deploy/kubernetes/overlays/production-csi`和`deploy/kubernetes/migration-csi`。这两个覆盖层保持原有容器内文件路径不变，只把卷来源从Kubernetes Secret替换为`secrets-store.csi.k8s.io`内联卷。
|
||||
|
||||
集群平台需先安装Secrets Store CSI Driver和对应云密钥提供器，并启用工作负载身份。`SecretProviderClass`必须创建在`voice-platform`命名空间；仓库提供[参数化示例](../deploy/kubernetes/examples/secret-provider-classes.example.yaml)，但`provider`和`parameters`必须严格按现场云厂商或Vault提供器文档填写，不能直接应用示例占位值。
|
||||
|
||||
必须创建以下六个`SecretProviderClass`：
|
||||
|
||||
| SecretProviderClass | 必须挂载的文件名 |
|
||||
|---|---|
|
||||
| `voice-platform-common` | `database-url`、`redis-password` |
|
||||
| `voice-platform-api` | `rtc-app-key`、`cursor-signing-secret`、`share-token-signing-secret` |
|
||||
| `voice-platform-callbacks` | `provider-callback-secret` |
|
||||
| `voice-platform-worker` | `volc-access-key-id`、`volc-secret-access-key`、`voice-chat-template.json` |
|
||||
| `voice-platform-model-storage` | `object-store-access-key`、`object-store-secret-key`、`ark-api-key`、`content-safety-api-key` |
|
||||
| `voice-platform-devices` | 每台设备一个文件，例如`terminal-001` |
|
||||
|
||||
提供器对象应通过`objectAlias`或等价字段映射为上述准确文件名。Deployment挂载整个目录，不使用`subPath`，以便CSI原子轮换能够更新容器看到的符号链接。ServiceAccount已按API、Callbacks、Worker和Web拆分；现场应只给前三个需要密钥的ServiceAccount附加相应工作负载身份，并按最小权限授予密钥读取能力。
|
||||
|
||||
自动轮换必须在CSI Driver和所选提供器均支持时启用。轮换后：
|
||||
|
||||
- `voice-platform-devices`中的逐设备密钥由API每次请求重新读取，原子更新后下一次验签即可使用新值；轮换协议仍应保留受控双密钥过渡或设备同步窗口。
|
||||
- 数据库、Redis、RTC、供应商、对象存储、方舟和签名密钥在进程启动时读取。CSI可以更新文件，但不会主动重启Pod；这些密钥轮换后必须由部署流水线执行受控滚动重启，并验证新Pod就绪后再终止旧Pod。
|
||||
- 不应依赖`secretObjects`同步为Kubernetes Secret。CSI迁移Job直接读取`voice-platform-common/database-url`文件，避免数据库连接串落入额外Secret副本。
|
||||
|
||||
检查CSI对象和已挂载版本：
|
||||
|
||||
```powershell
|
||||
kubectl get secretproviderclass -n voice-platform
|
||||
kubectl get secretproviderclasspodstatus -n voice-platform
|
||||
kubectl describe pod -n voice-platform -l app.kubernetes.io/name=voice-platform-api
|
||||
```
|
||||
|
||||
不要通过`kubectl exec ... cat`打印Secret内容。验收只检查文件存在、权限、版本编号、Pod就绪和实际认证结果。
|
||||
|
||||
目标环境完成动态读取和滚动重启两类轮换后，按[云KMS/HSM密钥轮换一致性证据](kms-hsm-rotation-evidence.md)导出不含密钥正文的版本、探针和审计引用，并使用`cmd/kms-rotation-conformance`生成候选报告。仅检查SecretProviderClass存在或本地文件更新不能满足`KMS_ROTATION`发布门禁。
|
||||
|
||||
## 7. 发布前静态检查
|
||||
|
||||
静态渲染不连接集群，适合本地和CI的轻量门禁：
|
||||
|
||||
```powershell
|
||||
kubectl kustomize deploy/kubernetes/overlays/production > $null
|
||||
kubectl kustomize deploy/kubernetes/migration > $null
|
||||
kubectl kustomize deploy/kubernetes/overlays/production-csi > $null
|
||||
kubectl kustomize deploy/kubernetes/migration-csi > $null
|
||||
```
|
||||
|
||||
连接目标集群后执行服务端预检和差异检查：
|
||||
|
||||
```powershell
|
||||
kubectl apply --server-side --dry-run=server -k deploy/kubernetes/overlays/production
|
||||
kubectl diff -k deploy/kubernetes/overlays/production
|
||||
```
|
||||
|
||||
重点确认镜像摘要、生产域名、OIDC、RTC App ID、方舟模型、对象存储、Secret齐备情况和NetworkPolicy命名空间。此处只做结构和部署配置检查，不替代真实供应商、真机和恢复演练。
|
||||
|
||||
七类生产基础设施完成现场核对后，按[生产基础设施一致性证据](production-infrastructure-evidence.md)保存脱敏探针、配置版本和审计引用，并使用`cmd/infrastructure-conformance`生成同候选报告。静态Kustomize渲染或本地Compose报告不能满足`PRODUCTION_INFRASTRUCTURE`发布门禁。
|
||||
|
||||
## 8. 数据库迁移
|
||||
|
||||
应用发布前先执行向前迁移，并等待Job成功：
|
||||
|
||||
```powershell
|
||||
kubectl delete job voice-platform-migrate -n voice-platform --ignore-not-found
|
||||
kubectl apply -k deploy/kubernetes/migration
|
||||
kubectl wait --for=condition=complete job/voice-platform-migrate -n voice-platform --timeout=10m
|
||||
kubectl logs job/voice-platform-migrate -n voice-platform
|
||||
```
|
||||
|
||||
使用CSI模式时，把迁移命令中的目录替换为`deploy/kubernetes/migration-csi`。该Job直接挂载`voice-platform-common`，不会读取`voice-platform-common-secrets`。
|
||||
|
||||
迁移失败时停止应用发布，检查Job日志、数据库TLS、权限和当前schema版本。不要自动执行`down`；若迁移包含不兼容变更，应按发布方案先完成备份和向前修复脚本评审。
|
||||
|
||||
## 9. 应用发布
|
||||
|
||||
迁移成功后应用覆盖层：
|
||||
|
||||
```powershell
|
||||
kubectl apply -k deploy/kubernetes/overlays/production
|
||||
kubectl rollout status deployment/api -n voice-platform --timeout=10m
|
||||
kubectl rollout status deployment/callbacks -n voice-platform --timeout=10m
|
||||
kubectl rollout status deployment/worker -n voice-platform --timeout=10m
|
||||
kubectl rollout status deployment/web -n voice-platform --timeout=10m
|
||||
```
|
||||
|
||||
使用CSI模式时，应用目录替换为`deploy/kubernetes/overlays/production-csi`。如果Pod停留在`ContainerCreating`，优先检查CSI Driver、提供器DaemonSet、工作负载身份、`SecretProviderClassPodStatus`和对象别名，不要通过放宽应用权限绕过挂载错误。
|
||||
|
||||
Deployment使用`maxUnavailable=0`、`maxSurge=1`滚动更新；每类服务默认至少两个副本，并受PDB保护。HPA根据CPU在2—10个副本范围内扩缩，真实生产应在观察一段时间的CPU、内存、请求率、Outbox积压和供应商配额后调整阈值。
|
||||
|
||||
## 10. 发布后轻量验收
|
||||
|
||||
按照“功能可用优先、避免重复高强度测试”的原则，生产发布只执行下列关键检查：
|
||||
|
||||
1. 四个Deployment全部Available，Pod无重启循环。
|
||||
2. API、Callbacks和Worker的`/health/ready`在集群内返回200。
|
||||
3. Web的`/runtime-config.js`包含当前OIDC公开配置，登录和家庭导航可用。
|
||||
4. 使用专用验收设备完成一次签名握手、配置读取、通话启动、入房确认、心跳和停止。
|
||||
5. 确认火山任务进入ACTIVE后正常完成，最终字幕可见，内容候选生成并可人工确认。
|
||||
6. 确认一条已确认记忆能在下一次通话中按授权召回。
|
||||
7. 检查最近错误日志、Prometheus目标、Outbox open/dead数量和告警接收器。
|
||||
8. 确认`oidc_jwks`、`ark_tls`、`volc_rtc_tls`和`content_safety_tls`外部依赖指标为1；该检查只证明网络、证书及JWKS结构，不替代真实账号业务调用或内容安全六类质量评测。
|
||||
|
||||
不在每次小版本发布后重复全量压测、全库恢复或完整浏览器矩阵；这些演练按重大变更、基础设施变更或既定周期执行。若上述关键链路任一失败，停止放量并回滚应用镜像。
|
||||
|
||||
## 11. 网络与观测说明
|
||||
|
||||
API、Callbacks和Worker Pod均带有`prometheus.io/scrape`、`path`和`port`发现注解。若集群Prometheus启用了基于Pod注解的服务发现，可直接抓取；使用Prometheus Operator时应创建等价的PodMonitor/ServiceMonitor，并保留相同指标路径和端口。
|
||||
|
||||
基线NetworkPolicy默认拒绝命名空间内所有Pod的入口流量，仅允许：
|
||||
|
||||
- `ingress-nginx`命名空间访问API、Callbacks和Web业务端口；
|
||||
- `monitoring`命名空间访问API、Callbacks和Worker指标端口。
|
||||
|
||||
基线暂不限制出口，因为数据库、Redis、OIDC、对象存储、OTLP、方舟和火山RTC可能位于不同网络。正式环境应根据实际CNI、域名解析和固定网段逐步增加出口白名单。`/metrics`不通过Ingress暴露，只允许监控网络访问。
|
||||
|
||||
## 12. 回滚
|
||||
|
||||
优先回滚应用镜像，不回滚已经成功执行的数据库迁移：
|
||||
|
||||
```powershell
|
||||
kubectl rollout undo deployment/api -n voice-platform
|
||||
kubectl rollout undo deployment/callbacks -n voice-platform
|
||||
kubectl rollout undo deployment/worker -n voice-platform
|
||||
kubectl rollout undo deployment/web -n voice-platform
|
||||
```
|
||||
|
||||
回滚后再次执行第10节的关键链路检查。若新迁移与旧应用不兼容，应使用事先评审的向前兼容修复版本，而不是在生产自动降级schema。
|
||||
|
||||
## 13. 尚需现场完成的事项
|
||||
|
||||
仓库清单完成的是可部署结构，不代表已经通过目标集群验收。上线前仍需业务方或平台方提供并验证：真实域名和证书、镜像仓库、托管数据库/Redis/对象存储、OIDC客户端、KMS/CSI工作负载身份、火山RTC/豆包语音、方舟模型、量产设备密钥、告警接收器，以及真机通话、外部故障、备份恢复和灰度回滚结果。
|
||||
@@ -0,0 +1,103 @@
|
||||
# 压测、告警与生产安全门禁
|
||||
|
||||
## 1. 生产配置启动门禁
|
||||
|
||||
当`APP_ENV=prod`时，进程在连接外部依赖前执行配置校验，任一条件不满足即拒绝启动：
|
||||
|
||||
- OIDC签发方和JWKS地址必须使用HTTPS；
|
||||
- PostgreSQL连接不能使用`sslmode=disable`；
|
||||
- Redis必须配置非占位密码；
|
||||
- API设备凭据必须按设备从受控Secrets/KMS CSI目录解析，生产禁止单一静态开发密钥；
|
||||
- RTC应用必须使用正式AppID/AppKey和火山正式Token格式；
|
||||
- Worker必须使用火山RTC HTTPS签名VoiceChat接口以及非占位AK/SK，禁止本地模拟供应商；
|
||||
- 分页游标和分享签名密钥必须至少32字符、不得使用本地/示例值且彼此不同；
|
||||
- 对象存储必须启用TLS，内外端点不能指向本机，访问凭据不得使用本地/示例值；
|
||||
- Callback签名密钥不得使用本地/示例值。
|
||||
|
||||
生产密钥不得写入Git、镜像、Compose文件或普通配置文件。部署平台应通过Secret Manager/KMS、短期工作负载身份或只读内存挂载注入，并建立轮换、吊销、双密钥过渡和访问审计。当前仓库只提供启动门禁，不宣称已经接入任何特定云厂商的密钥托管。
|
||||
|
||||
所有后端长期敏感配置均支持`NAME_FILE`约定，包括数据库连接串、Redis密码、RTC AppKey、火山AK/SK/临时Token、方舟API Key、对象存储凭据、设备本地开发密钥以及游标、分享、供应商回调和告警签名密钥。文件必须使用容器内绝对路径并小于等于64KiB；同一密钥的`NAME`与`NAME_FILE`同时配置时服务拒绝启动。该能力用于直接消费Docker/Kubernetes Secret或KMS CSI挂载文件，不等同于已经完成某个云厂商的身份授权与轮换验收。
|
||||
|
||||
本地开发已通过目录解析器测试验证不同设备密钥隔离、越界引用拒绝、短密钥拒绝，以及原子替换文件后无需重启即可读取新密钥。`scripts/verify-local-secret-rotation.ps1`保留用于验证旧的进程级环境注入路径；两者都不能替代真实KMS/HSM、量产设备注入、双密钥过渡和吊销审计。
|
||||
|
||||
## 2. 压测入口
|
||||
|
||||
`test/load/api-readiness.js`提供固定到达率压测。`acceptance`配置为50 RPS持续30分钟，门禁为失败率低于0.1%、p95低于500毫秒、p99低于1秒；`smoke`配置用于提交前短测。该数值是研发压测门禁，不是未经真实环境验证的产品SLA。
|
||||
|
||||
```powershell
|
||||
docker run --rm -v "${PWD}/test/load:/scripts:ro" grafana/k6 run `
|
||||
-e BASE_URL=http://host.docker.internal:58080 `
|
||||
-e PROFILE=acceptance /scripts/api-readiness.js
|
||||
|
||||
# 500次/秒供应商回调，持续10分钟，并对账30万唯一事件
|
||||
pwsh -NoProfile -File .\scripts\load-provider-callbacks.ps1 `
|
||||
-Profile acceptance -ConversationPool 100
|
||||
|
||||
# 1000活跃通话、500条SSE、10000媒体分片、100并发隐私删除
|
||||
pwsh -NoProfile -File .\scripts\load-conversation-state.ps1
|
||||
pwsh -NoProfile -File .\scripts\load-sse-connections.ps1 -Connections 500
|
||||
pwsh -NoProfile -File .\scripts\load-media-manifest.ps1
|
||||
pwsh -NoProfile -File .\scripts\load-privacy-delete.ps1
|
||||
```
|
||||
|
||||
如需叠加真实OIDC授权读取，将短期测试令牌通过进程环境传入`ACCESS_TOKEN`。禁止把令牌写进脚本或提交仓库。负载脚本必须使用隔离租户和合成数据；带夹具的包装脚本会在结束后执行数据库对账和精确清理。压测应在与生产容量相近的测试环境执行；本地结果只能形成研发回归基线，不能替代生产容量结论。完整本地结果、夹具边界和失败修正记录见[性能、恢复、安全与兼容性专项验证报告](performance-recovery-security-compatibility.md)。
|
||||
|
||||
## 3. Prometheus告警
|
||||
|
||||
`deploy/prometheus/rules/platform-alerts.yml`定义以下基础规则：
|
||||
|
||||
| 告警 | 条件 | 建议动作 |
|
||||
|---|---|---|
|
||||
| `PlatformServiceDown` | 连续2分钟无法抓取服务 | 检查部署、健康依赖和网络 |
|
||||
| `PlatformHighHTTP5xxRate` | 5分钟窗口5xx高于5%，持续5分钟 | 按服务、路由和trace定位错误 |
|
||||
| `PlatformHighP95Latency` | 路由p95高于1.5秒，持续10分钟 | 检查数据库、Redis、对象存储和下游供应商 |
|
||||
| `OutboxDeadLetterPresent` | 存在死信 | 核对错误码，修复后人工重放 |
|
||||
| `OutboxPendingBacklog` | pending超过100且持续10分钟 | 检查Worker容量及下游可用性 |
|
||||
| `PrivacyDeletionPartialFailure` | 隐私请求存在`PARTIAL_FAILED` | 立即对账六子系统并保留处置证据 |
|
||||
| `FirmwareAssignmentFailure` | 存在失败设备 | 暂停批次，分析设备结果，必要时回滚 |
|
||||
| `FirmwareRolloutStalled` | 运行批次15分钟无更新 | 检查命令投递、设备在线和下载权限 |
|
||||
|
||||
业务告警扫描器还会从`provider_dependency_state`生成`PROVIDER_UNAVAILABLE`事件。连续临时失败达到部署阈值后只暂停新启动，不阻断停止与回收；历史网页和普通查询不依赖供应商在线状态。恢复演练必须证明外呼调用数在熔断窗口内不再因新启动增加、停止任务仍有尝试、告警出现，并在供应商恢复后最终收敛。
|
||||
|
||||
本地Compose已挂载规则目录，并自动配置Grafana业务、技术、安全三类仪表盘；Prometheus采集API、Callbacks和Worker三类目标。正式环境还需对接告警接收器、值班分组、抑制规则和升级策略，并基于真实容量重新校准阈值。
|
||||
|
||||
业务扫描器还生成供应商通知积压和证书到期信号。证书通过`ops_resource_reference`登记为受控引用，只保存引用、核验时间和到期时间，不保存私钥或证书正文；30天内到期为高等级，7天内提升为严重等级。
|
||||
|
||||
## 4. 恢复与安全专项入口
|
||||
|
||||
```powershell
|
||||
# 真实pg_dump/pg_restore到隔离数据库并核对迁移、表、外键和关键计数
|
||||
pwsh -NoProfile -File .\scripts\verify-postgres-restore.ps1
|
||||
|
||||
# API/Callbacks/Worker重启、停机Outbox恢复和Redis热状态重建
|
||||
pwsh -NoProfile -File .\scripts\verify-runtime-recovery.ps1
|
||||
|
||||
# 本地长期设备签名密钥轮换，不重建镜像
|
||||
pwsh -NoProfile -File .\scripts\verify-local-secret-rotation.ps1
|
||||
|
||||
# 认证、授权、输入、签名、防重放、安全响应头和日志正文过滤
|
||||
pwsh -NoProfile -File .\scripts\security-http-smoke.ps1
|
||||
|
||||
# 后端依赖可达漏洞、前端依赖、仓库密钥和最终镜像
|
||||
docker run --rm -v "${PWD}:/src" -w /src golang:1.26.6-alpine `
|
||||
sh -c "go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./..."
|
||||
npm --prefix web audit --audit-level=high
|
||||
docker run --rm -v "${PWD}:/src" zricethezav/gitleaks:v8.30.1 `
|
||||
detect --source=/src --config=/src/.gitleaks.toml --no-banner
|
||||
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock `
|
||||
-v data-terminal-trivy-cache:/root/.cache/trivy aquasec/trivy:0.74.0 `
|
||||
image --scanners vuln --ignore-unfixed --severity HIGH,CRITICAL `
|
||||
data-terminal-cloud-api:latest
|
||||
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock `
|
||||
-v data-terminal-trivy-cache:/root/.cache/trivy aquasec/trivy:0.74.0 `
|
||||
image --scanners vuln --ignore-unfixed --severity HIGH,CRITICAL `
|
||||
data-terminal-cloud-web:latest
|
||||
```
|
||||
|
||||
Web最终镜像使用非特权UID 101和8080监听；构建基线为Nginx 1.30.4 unprivileged Alpine并在镜像构建时应用当前系统安全更新。配置扫描必须确认Dockerfile不存在root运行高危项，镜像扫描必须同时覆盖API和Web最终运行层。
|
||||
|
||||
CI进一步使用镜像摘要固定Gitleaks、Trivy和Syft，并输出CycloneDX SBOM。浏览器矩阵由`node test/e2e/browser-matrix.mjs`执行，Safari必须在macOS真浏览器补测。宿主Go版本可能落后于镜像构建器，因此最终`govulncheck`证据必须在与生产构建一致的Go版本中生成。
|
||||
|
||||
## 5. 上线前证据
|
||||
|
||||
生产候选版本至少应保存：构建提交号、SBOM和镜像摘要，单元/集成/迁移/接口契约结果，依赖与镜像漏洞报告，密钥扫描报告，压测报告，故障恢复演练，固件暂停/回滚演练，隐私删除六子系统对账，以及真实供应商和真机连续通话记录。缺少外部账号、硬件或生产基础设施时，应明确标为“待外部验证”，不能用本地模拟结果替代。
|
||||
@@ -0,0 +1,84 @@
|
||||
# 双轨录音上传、校验与访问开发说明
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
本模块实现长者声音`near`和智能体声音`far`两条录音轨道的分片声明、私有对象直传、可靠校验、播放/下载独立授权和访问审计。实时语音仍由终端、RTC和语音智能体直接传输；录音字节不经过业务HTTP接口，也不写入应用服务器系统盘。业务API只处理元数据和短期单对象地址，Worker从私有对象存储流式核验文件。
|
||||
|
||||
终端在通话心跳或离线批量遥测中上报`recording_queue.pending_segments`、`failed_segments`以及可选的脱敏`last_failure_code/last_failure_at`。家庭端设备卡片从设备影子选择时间最新的队列报告，显示待上传数量、失败数量和最近失败原因；失败码缺失时明确提示终端尚未上报，不把未知原因伪装成成功。云端完成对象完整性与WAV校验前，页面不会提示终端删除本地密文。
|
||||
|
||||
录音上传同时受两层授权约束：创建通话时冻结的授权必须允许`transcript_and_audio`，并且当前`raw_audio_storage`授权仍然有效。授权撤回后，不再创建新上传批次。家庭所有者、管理员、编辑者和查看者角色均不会自动获得录音播放或下载权。
|
||||
|
||||
## 2. 数据模型
|
||||
|
||||
| 对象 | 用途 | 状态/关键约束 |
|
||||
|---|---|---|
|
||||
| `upload_batch` | 设备一次分片清单及校验汇总 | `PENDING → UPLOADING → VERIFYING → COMPLETED/FAILED/EXPIRED`；设备、通话和幂等键唯一 |
|
||||
| `media_segment` | 通话内单轨单序号录音对象 | 云端生命周期为`DECLARED → AUTHORIZED → VERIFYING → VERIFIED/REJECTED → DELETED`；另存设备本地密文删除状态、回报时间和失败码 |
|
||||
| `upload_batch_segment` | 连接重试批次与稳定分片记录 | 同一分片可在失败后进入新批次重试，不生成重复媒体记录 |
|
||||
| `recording_access_grant` | 指定用户的显式访问授权 | `PLAY`与`DOWNLOAD`分别授权，带用途、授予人、到期和撤销时间 |
|
||||
| `media_access_log` | 每次播放/下载判定记录 | 保存用户、资源、动作、用途、成功/拒绝/失败、原因和请求编号 |
|
||||
|
||||
对象路径由云端按租户摘要、通话编号、轨道、序号和摘要前缀生成，不含长者姓名，也不接受设备自定义路径。数据库只保存对象引用，不保存临时上传或下载URL。
|
||||
|
||||
## 3. 设备上传流程
|
||||
|
||||
1. 通话结束后，设备为`near`和`far`分片计算SHA-256，提交轨道、序号、编码、内容类型、时长、大小和摘要，并提供16—128字符幂等键。
|
||||
2. 云端检查设备与通话归属、通话终态、冻结录音策略、当前原录音授权、轨道/序号唯一性和清单结构。
|
||||
3. 相同幂等键和相同清单返回原批次；同键不同清单或相同轨道序号对应不同元数据返回冲突。
|
||||
4. 云端只为未验证分片签发15分钟、只能PUT一个私有对象的地址。录音字节由设备直接上传对象存储。
|
||||
5. 设备调用完成接口后，事务把分片置为`VERIFYING`，并通过Outbox可靠创建`media.verify_requested`任务；重复完成不会重复生成校验任务。
|
||||
6. Worker流式校验实际大小和SHA-256，再解析音频容器、编码和时长。对象暂时不可见时任务保留`VERIFYING`并按Outbox策略重试；大小、摘要、容器、编码或时长不符时进入`REJECTED`。
|
||||
7. 全部分片验证通过后批次进入`COMPLETED`。设备查询到分片`VERIFIED`和`local_delete_after`后，才可在该时间之后删除本地加密文件。
|
||||
8. 设备删除完成后提交`DELETED`回执；删除失败则提交`FAILED`和稳定错误码。云端拒绝过早的成功回执，已成功回执可幂等重放，且回执只表示设备副本已删除，不改变云端已验证对象状态。
|
||||
|
||||
`MEDIA_LOCAL_DELETE_GRACE`控制云端校验通过到允许终端删除本地密文之间的保护期，默认1小时，允许范围为大于0且不超过7天。Compose本地联调环境使用1秒以便快速完成闭环；生产环境未显式配置时保持1小时，不能为了缩短联调时间而提前返回删除成功。
|
||||
|
||||
当前研发基线实际解析`audio/wav`的PCM 16位格式并核对时长。Opus/Ogg等编码尚未在硬件能力表和分片清单格式中冻结，因此不会被当前API接受，避免把“只相信设备声明”误报为完成编码校验。
|
||||
|
||||
## 4. 播放与下载流程
|
||||
|
||||
1. 家庭所有者或管理员为家庭内指定用户显式创建`PLAY`或`DOWNLOAD`授权，填写用途和到期时间。编辑者和查看者不能创建授权。管理端可查询最近授权、识别有效/到期/已撤销状态并立即撤销。
|
||||
2. 查看通话媒体时，服务重新检查账号仍是家庭有效成员、原录音授权仍有效，并确认至少有一种当前有效访问授权。响应仅返回已验证分片元数据，不返回对象地址。
|
||||
3. 每次播放或下载都调用访问接口，重新检查成员关系、原录音授权、动作对应的独立授权和分片`VERIFIED`状态。
|
||||
4. 检查成功后签发5分钟单对象地址：播放使用`inline`，下载使用`attachment`；文件名只包含通话编号、轨道和序号。
|
||||
5. 成功和拒绝都写入`media_access_log`及统一审计。撤销播放授权不会自动撤销下载授权，反之亦然。
|
||||
|
||||
## 5. 接口
|
||||
|
||||
| 方法与路径 | 用途 |
|
||||
|---|---|
|
||||
| `POST /device/v2/conversations/{id}/upload-batches` | 幂等提交分片清单并取得缺失分片上传地址 |
|
||||
| `POST /device/v2/upload-batches/{id}/complete` | 声明上传完成并可靠触发后台校验 |
|
||||
| `GET /device/v2/upload-batches/{id}` | 查询批次、分片结果及本地延迟删除时间 |
|
||||
| `POST /device/v2/media-segments/{id}/local-delete-ack` | 回报设备本地密文删除成功或失败；成功受删除时间门禁约束 |
|
||||
| `GET /api/v1/subjects/{id}/recording-access-grants` | 所有者/管理员查询最近录音访问授权及状态 |
|
||||
| `POST /api/v1/subjects/{id}/recording-access-grants` | 显式授予PLAY或DOWNLOAD |
|
||||
| `POST /api/v1/recording-access-grants/{id}/revoke` | 撤销一条录音访问授权 |
|
||||
| `GET /api/v1/conversations/{id}/media` | 按授权读取两轨已验证分片元数据 |
|
||||
| `POST /api/v1/media-segments/{id}/access` | 重新鉴权并取得5分钟播放或下载地址 |
|
||||
|
||||
字段、错误码和设备签名头以`openapi/openapi.yaml`为准。
|
||||
|
||||
## 6. 删除与验证
|
||||
|
||||
主体删除任务的`object_storage`子任务会逐个删除该长者全部媒体对象，并将分片置为`DELETED`、清空对象引用和文件摘要；PostgreSQL子任务同步撤销录音访问授权、脱敏授权用途和访问用途，并清理媒体Outbox正文。任一对象删除失败时隐私请求保持部分失败并继续重试，不会错误显示完成。
|
||||
|
||||
本地完整环境运行：
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-media-upload.ps1
|
||||
```
|
||||
|
||||
脚本验证双轨直传、清单幂等、同键冲突、对象大小/SHA-256、WAV PCM16容器与时长、后台收敛、错误摘要拒绝、本地删除时间门禁、失败回执、成功与幂等回执、角色默认拒绝、授权列表权限、PLAY/DOWNLOAD独立授权、编辑者授予拒绝、撤销立即生效、短期对象访问，以及成功/拒绝访问审计；默认结束后删除全部合成数据库记录和对象。`-KeepFixture`仅供隔离的页面视觉验收，验收结束必须清理夹具。
|
||||
|
||||
React通话详情页展示近端/远端已验证分片、播放和下载能力、短期地址说明、按成员/用途/有效期的显式授权、当前有效授权和立即撤销入口。播放地址只保存在当前页面内存中，刷新页面后失效；下载通过一次性页面链接触发，前端不把短期地址写入持久化存储。
|
||||
|
||||
录音显式授权创建也使用家庭业务受控操作区。原录音管理表单只负责选择家庭成员、PLAY或DOWNLOAD、1/8/24小时有效期和用途；点击“确认授权”后先冻结长者、接收成员公开编号、单项能力、用途和准确到期时间。页面明确该授权按长者生效，可覆盖有效期内当前及后续可访问的全部已验证原录音，而不是只覆盖当前打开的通话；同一成员原有的同类有效授权会被服务端撤销并替换，家庭角色本身仍不产生录音能力。操作者显式确认后才调用创建接口，取消或切换通话、长者、家庭、工作台不会创建授权。
|
||||
|
||||
录音访问授权的“立即撤销”不会再单击即提交。页面先打开家庭业务受控操作区，固定展示长者、被授权成员、授权公开编号、PLAY或DOWNLOAD权限、用途、授予时间和到期时间；提交前必须确认后续不再为该成员签发新地址，并知晓已经签发的地址最长仍可能在5分钟内有效、成员已保存的离线副本无法由平台远程收回。取消只清除当前操作草稿，不调用撤销接口；切换长者或其他家庭业务上下文也会清除旧目标，避免误操作到上一条授权。
|
||||
|
||||
已获得独立权限的用户点击具体分片的“播放”或“下载”时，也不会立即签发地址。页面先冻结当前长者、通话公开编号、近端/远端轨道、分片序号和公开编号、时长、大小及用途：播放确认说明5分钟浏览器地址、逐次访问审计和旁听泄露风险；下载确认说明本地声音文件离开平台后的受控保存、转交与销毁责任。只有显式确认后才调用访问接口，服务端仍会重新核验家庭成员关系、动作对应的PLAY或DOWNLOAD授权、当前原录音授权和分片VERIFIED状态。切换通话、长者、家庭或工作台会清除旧分片草稿。
|
||||
|
||||
该页面采用低强度真实链路检查：使用真实本地OIDC登录和临时授权记录，只验证目标绑定、影响确认、取消关闭、零撤销或地址签发请求和数据库不变，不实际撤销业务数据或生成可访问地址。其中撤销页面夹具的通话快照未给当前账号原始录音播放权，媒体接口返回403被视为预期权限门禁；地址签发页面则使用最小PLAY/DOWNLOAD授权、当前原录音授权和一条已验证分片，证明按钮确实可达。除此之外的控制台错误、请求失败或页面溢出仍会使检查失败。
|
||||
|
||||
模拟终端的`media`场景现在会执行清单声明、对象直传、提交校验、轮询批次、等待删除保护期和`DELETED`回执。它不会删除`SIM_MEDIA_FILE`指向的操作人员文件，只把已上传内容视为内存中的设备密文副本并在回执前释放。生产保护期超过模拟器等待上限时，模拟器只报告计划删除时间，不发送过早成功回执。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 可观测性与接口治理设计
|
||||
|
||||
## 1. 目标与适用范围
|
||||
|
||||
本设计作为 API、Callbacks 与 Worker 三个进程的公共能力基线，统一请求关联、分布式追踪、指标采集、流量保护、列表分页和资源并发更新规则。领域接口不得另行定义不兼容的分页游标或版本标记。
|
||||
|
||||
OpenAPI是浏览器、设备和回调接口的事实来源。拉取请求以目标分支契约为基线执行破坏性变更检查；设备接口还由代码测试固定`/device/v2`主版本、禁止以`User-Agent`推测能力，并要求兼容说明与OpenAPI版本同步。设备同主版本的新增行为必须通过可选能力位协商，破坏性变化使用新主版本，具体规则见[设备API兼容性约定](device-api-compatibility.md)。
|
||||
|
||||
## 2. 请求关联与分布式追踪
|
||||
|
||||
- 每个 HTTP 请求接收或生成 `X-Request-Id`，并在响应、统一错误体和结构化日志中返回。
|
||||
- `otelhttp` 在最外层创建服务端 Span，接收并传播 W3C `traceparent` 与 `baggage`。
|
||||
- 访问日志记录 `request_id`、`trace_id`、`span_id`、服务、方法、匹配后的路由模板和耗时；不记录 Authorization、Cookie、录音正文或供应商密钥。
|
||||
- 本地环境通过 OTLP/gRPC 发送至 OpenTelemetry Collector。Collector 当前使用调试导出器，后续环境可替换为 Tempo、Jaeger或云厂商后端，不改变业务代码。
|
||||
|
||||
## 3. Prometheus 指标
|
||||
|
||||
| 指标 | 标签 | 用途 |
|
||||
|---|---|---|
|
||||
| `voice_platform_http_requests_total` | service、method、route、status | 请求量与错误率 |
|
||||
| `voice_platform_http_request_duration_seconds` | service、method、route | HTTP延迟分布 |
|
||||
| `voice_platform_http_inflight_requests` | service | 在途请求数 |
|
||||
| `voice_platform_dependency_up` | service、dependency | PostgreSQL、Redis最近一次检查状态 |
|
||||
| `voice_platform_dependency_check_duration_seconds` | service、dependency | 依赖检查耗时 |
|
||||
| `voice_platform_outbox_events` | status | pending、processing、dead积压 |
|
||||
|
||||
`/metrics`与`/health/*`不进入业务限流。Prometheus 每10秒抓取三个进程；本地入口为 `http://localhost:59190`。生产环境应限制指标端点只允许监控网络访问。
|
||||
|
||||
API还会按`EXTERNAL_PROBE_INTERVAL`周期验证OIDC JWKS端点可读取、JSON结构有效且至少存在一把公钥。启用方舟的API/Worker会对`ARK_BASE_URL`执行证书校验TLS握手，启用火山RTC的Worker会对`VOLC_RTC_BASE_URL`执行同类握手，启用托管内容安全的Worker会对`CONTENT_SAFETY_ENDPOINT`执行同类握手。TLS探针只做DNS、TCP和TLS协商，不发送供应商业务请求或待分类正文，因此不消耗模型Token、RTC分钟、策略调用或任务配额。
|
||||
|
||||
探针结果复用`voice_platform_dependency_up{service,dependency}`，其中外部标签为`oidc_jwks`、`ark_tls`、`volc_rtc_tls`和`content_safety_tls`。失败不会改变服务readiness；模型和内容安全调用本身已有降级或安全重试路径，供应商网络故障不应触发Pod重启风暴。`PlatformExternalDependencyUnavailable`只在指标连续5分钟为0后触发CRITICAL告警。运营验收快照可把四类依赖全部选为必需项，任何记录缺失、不可用或超过三倍探针周期未更新都会阻断技术门禁。
|
||||
|
||||
## 4. Redis令牌桶限流
|
||||
|
||||
- Key格式：`voice-platform:ratelimit:{scope}:{identifier_hash}`。
|
||||
- 标识符使用SHA-256截断摘要，Redis中不保存原始IP、用户编号、设备编号或客户组织编号。
|
||||
- Lua脚本以Redis服务器时间原子完成补充、扣减和过期时间设置，避免多实例竞态及应用服务器时钟偏差。
|
||||
- HTTP入口当前先启用 `network` 范围；应用服务可复用同一组件增加 `user`、`device`、`tenant` 范围并组合更严格策略。
|
||||
- 超限返回HTTP 429、错误码 `RATE_LIMITED`、`Retry-After` 和 `X-RateLimit-Remaining`。
|
||||
- Redis短时故障采用可观测的 fail-open，避免公共缓存故障放大成全站中断；登录、设备注册、密钥操作等高风险接口落地时应叠加本地保护或按接口改为 fail-closed。
|
||||
|
||||
本地默认速率为每来源50次/秒、突发100次，可通过 `RATE_LIMIT_RPS` 和 `RATE_LIMIT_BURST` 调整。生产值必须依据容量测试冻结。
|
||||
|
||||
## 5. 游标分页规范
|
||||
|
||||
- 查询参数 `limit` 缺省为20，只允许1至100。
|
||||
- `cursor` 是HMAC-SHA256签名的不透明Base64URL值，载荷只含版本、稳定排序键和公开资源ID。
|
||||
- 服务端按“排序键 + ID”组成确定性顺序，查询下一页时使用严格大于或小于条件，禁止把数据库偏移量作为游标。
|
||||
- 响应中的 `next_cursor` 仅在确有下一页时返回；客户端不得解析、修改或长期持久化游标。
|
||||
- 签名失败、版本不支持或字段缺失统一作为无效游标处理，不把解析细节暴露给调用方。
|
||||
|
||||
## 6. ETag与乐观并发规范
|
||||
|
||||
- 可变资源读取成功时返回强ETag，格式为 `"v{version}"`，例如 `"v3"`。
|
||||
- PATCH、PUT和状态变更请求必须携带 `If-Match`；缺失时映射HTTP 428，格式无效映射HTTP 400，版本不一致映射HTTP 412。
|
||||
- 不接受弱ETag `W/` 或通配符 `*`。
|
||||
- 数据表须包含从1开始的 `version` 列；更新SQL必须带 `WHERE id=? AND version=?`，成功后原子执行 `version=version+1`。
|
||||
- ETag只解决并发覆盖，不替代幂等键。会产生外部副作用的写请求仍须使用幂等执行器和outbox。
|
||||
|
||||
## 7. 验证门禁
|
||||
|
||||
1. 日常开发运行变更包测试、OpenAPI类型生成和前端构建；`go test ./...`、`go vet ./...`保留给CI或发布候选。
|
||||
2. 游标篡改、非法limit、弱ETag、缺失If-Match和版本冲突必须有自动化测试。
|
||||
3. Redis集成测试必须证明突发上限和令牌恢复。
|
||||
4. 三个后端 `/health/ready` 返回200，Prometheus三个target均为 `up=1`。
|
||||
5. Collector日志出现三个服务上报的Span，访问日志出现对应 `trace_id` 与 `span_id`。
|
||||
6. Worker指标能区分待处理、处理中和死信事件。
|
||||
7. OpenAPI破坏性变更检查和设备协议兼容门禁必须通过。
|
||||
@@ -0,0 +1,172 @@
|
||||
# 内部运营配置、发布门禁与灰度控制开发说明
|
||||
|
||||
## 1. 实现范围
|
||||
|
||||
V19—V20及V34已经形成内部运营配置的本地纵向闭环：运营身份、五类运行配置、不可变草稿、结构校验、离线评测证据、受控资源引用、双人审批、按范围灰度、确定性分桶、并发影响上限、投放台账、带版本校验的暂停恢复、历史差异、不可变回滚和新通话配置冻结。
|
||||
|
||||
本批次覆盖的配置类型为`PERSONA`、`VOICE`、`MODEL`、`ROUTING`和`AGENT_BUNDLE`。灰度范围支持整个客户组织、单个试验对象和设备组；运行时命中优先级固定为“试验对象 > 设备组 > 客户组织”。
|
||||
|
||||
以下能力仍不冒充已完成：真实KMS取密、供应商在线资源探测、真实模型兼容性调用和成本预测尚未接入外部服务；当前资源引用的“已核验”状态由受控运营流程登记，并由类型、状态及180天有效期门禁复核。费用、额度和告警处置属于后续批次。
|
||||
|
||||
## 2. 运营角色与租户边界
|
||||
|
||||
| 角色 | 权限 |
|
||||
|---|---|
|
||||
| `customer` | 无内部运营接口权限 |
|
||||
| `ops_viewer` | 查看配置、评测证据、资源引用、设备组和投放台账 |
|
||||
| `ops_operator` | 查看、创建草稿、提交审批、登记评测/资源/设备组、撤销资源引用 |
|
||||
| `ops_approver` | 具备操作员能力，并可审批发布、回滚、暂停和恢复投放 |
|
||||
| `ops_admin` | 平台管理员能力；仍受创建人与审批人分离约束 |
|
||||
|
||||
运营角色保存在`user_account.platform_role`，不会信任OIDC令牌中的自报角色。每次运营请求用OIDC签名身份与`X-Tenant-Id`共同解析当前客户组织的活动账号；家庭角色不会隐式获得运营权限，跨客户组织的试验对象和设备编号均由服务端拒绝。生产环境仍需由身份系统强制MFA和受控授权流程。
|
||||
|
||||
## 3. 配置与投放状态
|
||||
|
||||
```text
|
||||
DRAFT ──结构校验/提交──> PENDING_APPROVAL ──评测与资源门禁+另一审批人──> PUBLISHED
|
||||
│
|
||||
激活一个或多个灰度投放范围
|
||||
↓
|
||||
ACTIVE ──暂停──> PAUSED
|
||||
↑ │
|
||||
└────恢复─────┘
|
||||
│
|
||||
同范围新版本替代ACTIVE或PAUSED
|
||||
↓
|
||||
ENDED
|
||||
│
|
||||
无任何活动投放仍引用该配置版本 ───────────┘
|
||||
↓
|
||||
RETIRED
|
||||
```
|
||||
|
||||
- `tenant_id + config_key`内的`version_no`严格递增，事务级咨询锁防止并发分配重复版本。
|
||||
- 草稿和历史版本不可覆盖；提交、发布、资源撤销及投放暂停恢复均使用强`If-Match`并发控制。
|
||||
- 配置创建人不得审批自己的变更，违反时返回`SELF_APPROVAL_FORBIDDEN`。
|
||||
- 同一配置键可以同时存在多个已发布版本，但每个具体投放目标只能有一个活动版本。
|
||||
- 租户、每个试验对象、每个设备组分别由数据库部分唯一索引保护活动投放唯一性。
|
||||
- 替换某一目标时只结束该目标的旧投放；旧版本仍被其他活动目标使用时保持`PUBLISHED`。
|
||||
- 暂停只阻止后续新通话命中，不改变已经建立通话的冻结配置；恢复要求配置仍为`PUBLISHED`且同一键和范围没有其他活动投放。
|
||||
- 新版本会同时结束同范围的`ACTIVE`和`PAUSED`旧投放；被替代的暂停记录不能恢复，避免旧灰度意外复活。
|
||||
- 当旧版本不再被任何活动投放使用时才转为`RETIRED`。
|
||||
- 回滚复制历史正文创建新的已发布版本，不复活或修改历史行；`rollback_of_id`记录内容来源，`supersedes_id`记录被该目标替换的版本。
|
||||
- 创建草稿、评测、设备组、资源引用和回滚要求`Idempotency-Key`，正文摘要冲突返回HTTP 409。
|
||||
|
||||
## 4. 发布门禁
|
||||
|
||||
### 4.1 结构与敏感信息
|
||||
|
||||
配置正文最大64KiB，拒绝任意层级包含`secret`、`password`、`token`、`private_key`、`api_key`或`credential`含义的键。供应商凭据只通过`secret_refs`保存引用，接口、数据库、页面和日志均不保存密钥明文。
|
||||
|
||||
`runtime-config-v1`本地结构检查如下：
|
||||
|
||||
- 人设要求`system_prompt`和`tone`。
|
||||
- 音色要求`provider`、`voice_resource_ref`及`credential_ref`。
|
||||
- 模型要求`provider`、`model_id`及`credential_ref`。
|
||||
- 路由要求`default_engine_mode`属于`s2s_pure`、`s2s_hybrid`或`cascade`，且存在`routes`。
|
||||
- Agent组合要求人设、音色、模型和路由四个版本引用。
|
||||
|
||||
Agent组合的四个字段不是任意字符串：`persona_version_id`、`voice_version_id`、`model_version_id`和`routing_version_id`必须是UUID，并分别指向当前客户组织内对应`PERSONA`、`VOICE`、`MODEL`和`ROUTING`类型的不可变配置版本。组件必须已经发布过；当前为`PUBLISHED`或因后续版本替换而成为`RETIRED`都可复用，`DRAFT`、`PENDING_APPROVAL`、跨客户、错误类型和不存在的编号均会被拒绝。提交审批时把四个组件的编号、类型和状态写入结构校验结果，发布及回滚事务再次复核，避免审批期间引用失效。
|
||||
|
||||
### 4.2 离线评测
|
||||
|
||||
每个待发布版本至少需要一条`PASSED`评测记录。评测通过`evidence_type`区分通用证据`GENERIC`和标准Agent质量证据`AGENT_QUALITY_V1`，并保存套件版本、结果、指标快照、报告引用、操作者和时间。除Agent组合外的配置继续接受通用证据；`AGENT_BUNDLE`发布必须存在一条`PASSED`的`AGENT_QUALITY_V1`证据，手工登记的通用`PASSED`不能放行。
|
||||
|
||||
标准Agent质量证据只能登记到`AGENT_BUNDLE`。服务端校验报告结构版本、评测集SHA-256、Agent和模型配置引用、执行环境与时间、十个以上用例、通过/失败计数以及全部强制质量指标，并校验结论与失败计数一致。登记器注入的`config_version_id`必须等于目标组合编号，`model_config_ref`必须等于`runtime-config-version:<model_version_id>`，另一组合或另一模型的报告不能复用。页面不向Agent组合提供手工通用评测按钮；标准证据应由`cmd/agent-eval-register`在重新计算报告并完成防篡改检查后登记。失败记录不会被删除，也不能单独放行发布。所有评测都只允许在`DRAFT`或`PENDING_APPROVAL`状态登记，防止发布后补写证据。
|
||||
|
||||
非Agent组合的通用评测从具体配置版本卡片打开页面内登记表单，不再连续调用浏览器输入和确认弹窗。表单固定配置公开编号、类型、版本族、版本号及行版本；套件版本必填且最长100字符，报告引用必填且最长300字符，`PASSED/FAILED`均必须由操作者明确选择，默认不预选结论。选择`PASSED`后还必须确认报告内容和指标支持通过结论，并理解该记录可能参与发布门禁；选择`FAILED`不会沿用该确认。取消、切换客户组织或配置列表刷新会清除草稿，不创建评测。页面仍不允许为`AGENT_BUNDLE`手工登记通用证据，服务端继续校验配置状态、租户、幂等和证据类型。
|
||||
|
||||
### 4.3 资源引用
|
||||
|
||||
门禁按用途匹配资源类型：
|
||||
|
||||
| 配置字段 | 必需资源类型 |
|
||||
|---|---|
|
||||
| `secret_refs.*` | `PROVIDER_CREDENTIAL` |
|
||||
| `VOICE.voice_resource_ref` | `VOICE_RESOURCE` |
|
||||
| `MODEL.model_id` | `MODEL_RESOURCE` |
|
||||
|
||||
引用必须属于当前客户组织、状态为`ACTIVE`，且`verified_at`在180天内。仅名称相同但类型错误、已撤销或过期的引用均不能放行。资源撤销使用`If-Match`并形成事务审计；撤销后后续发布会被阻断。真实KMS读取、供应商在线校验和自动轮换仍需外部系统接入。
|
||||
|
||||
资源撤销从资源台账打开页面内受控操作区，不再使用浏览器输入弹窗。确认区固定资源公开编号、显示名称、类型、引用标识、当前状态和行版本；原因必填且最长500字符，并要求操作者确认后续发布门禁影响、替代资源已经核对，以及本操作不会删除外部密钥或改写历史会话。取消、客户组织切换或列表刷新会清除草稿，不发送撤销请求。
|
||||
|
||||
## 5. 灰度选择与影响上限
|
||||
|
||||
发布或回滚请求必须提供：`scope_type`、可选`scope_id`、`rollout_percent`和`max_concurrent_calls`。
|
||||
|
||||
- `TENANT`不允许填写`scope_id`。
|
||||
- `SUBJECT`要求有效试验对象公开编号且比例固定为100%。
|
||||
- `DEVICE_GROUP`要求当前客户组织的活动设备组，可设置1%—100%。
|
||||
- 设备组百分比使用设备公开编号、投放固定种子和PostgreSQL稳定哈希进行确定性分桶；同一投放下设备不会在请求间随机跳组。
|
||||
- 运行时先尝试试验对象范围，再尝试设备组，最后尝试租户范围。
|
||||
- 当前冻结该配置版本的未结束通话数达到`max_concurrent_calls`时，该投放不再接纳新通话，继续尝试较低优先级范围或本地开发回退配置。
|
||||
|
||||
## 6. 接口
|
||||
|
||||
| 接口 | 作用 |
|
||||
|---|---|
|
||||
| `GET /api/v1/ops/config-versions` | 查询配置版本历史 |
|
||||
| `POST /api/v1/ops/config-versions` | 幂等创建不可变草稿 |
|
||||
| `PATCH /api/v1/ops/config-versions/{id}/submit` | 结构校验并提交审批 |
|
||||
| `GET /api/v1/ops/config-versions/{id}/evaluations` | 查询离线评测证据 |
|
||||
| `POST /api/v1/ops/config-versions/{id}/evaluations` | 幂等登记评测证据 |
|
||||
| `PATCH /api/v1/ops/config-versions/{id}/publish` | 双人审批并激活指定灰度范围 |
|
||||
| `POST /api/v1/ops/config-versions/{id}/rollback` | 幂等复制历史内容并投放新的回滚版本 |
|
||||
| `GET /api/v1/ops/config-rollouts` | 查询活动及历史投放台账 |
|
||||
| `PATCH /api/v1/ops/config-rollouts/{id}/pause` | 使用`If-Match`暂停活动投放，仅影响后续新通话 |
|
||||
| `PATCH /api/v1/ops/config-rollouts/{id}/resume` | 使用`If-Match`恢复未被替代的暂停投放 |
|
||||
| `GET/POST /api/v1/ops/resource-references` | 查询或登记受控资源引用 |
|
||||
| `PATCH /api/v1/ops/resource-references/{id}/revoke` | 使用`If-Match`撤销资源引用 |
|
||||
| `GET/POST /api/v1/ops/device-groups` | 查询或创建静态设备灰度组 |
|
||||
|
||||
所有接口要求OIDC和`X-Tenant-Id`；所有写入形成事务审计，不记录密钥明文。
|
||||
|
||||
## 7. 新通话配置冻结
|
||||
|
||||
设备创建新通话时，在同一数据库事务内读取设备活动绑定，并执行目标匹配、稳定分桶及并发上限判断。平台优先选择活动投放所绑定的`AGENT_BUNDLE`版本，`config_key`只表示运营定义的版本族，不是运行时保留开关；页面建议的`default-agent-bundle`可以直接使用，也可以按业务命名多个灰度版本族。优先级固定为“试验对象 > 设备组 > 客户组织”，同一范围存在多个可命中组合时选择最近激活的一项。命中后读取组合引用的`ROUTING.default_engine_mode`，并把`cfg:{Agent组合公开编号}`写入`context_snapshot.prompt_bundle_version`。组合所引用的路由版本允许处于`PUBLISHED`或`RETIRED`，因为已发布版本不可变且退役只阻止新的直接发布选择，不破坏已审核组合和回滚的可追溯性。后续发布、暂停、撤销或回滚只改变新通话选择，已创建通话始终使用自己的冻结组合。
|
||||
|
||||
Worker启动Agent时按冻结的组合公开编号重新读取同一客户组织内、类型严格匹配的`PERSONA`、`VOICE`和`MODEL`版本，把组合编号、四个组件编号、系统提示、表达风格、音色资源引用和模型资源引用放入统一供应商启动请求。火山适配器会把系统提示、表达风格和最小必要背景按顺序加入系统消息，并支持在正式模板中使用`{{MODEL_RESOURCE_REF}}`、`{{VOICE_RESOURCE_REF}}`、`{{AGENT_BUNDLE_VERSION}}`、`{{PERSONA_VERSION}}`、`{{VOICE_VERSION}}`、`{{MODEL_VERSION}}`和`{{ROUTING_VERSION}}`占位符。模型和音色字段的实际落点由供应商官方模板决定，平台不猜测未确认的专有字段。
|
||||
|
||||
为兼容已有数据，未命中Agent组合时继续选择活动投放所绑定的`ROUTING`版本，并冻结该路由公开编号；页面建议键`default-agent-routing`不是强制值。若同一范围存在多个直接路由，也按最近激活时间选择。本地开发环境在两类投放都不可用时回退到`minimal-v2 + s2s_hybrid`；生产环境没有任何可命中的Agent组合或旧路由时拒绝创建并返回`RUNTIME_CONFIG_UNAVAILABLE`，避免静默切换。冻结的三种模式由`voice-chat-template-bundle-v1`选择同名供应商请求模板；真实模板字段、资源兼容性和语音效果仍需供应商账号联调。
|
||||
|
||||
## 8. 管理端
|
||||
|
||||
非`customer`账号可见“配置发布与版本控制”工作台，支持：
|
||||
|
||||
- 切换有运营权限的客户组织。
|
||||
- 登记并撤销受控资源引用、创建设备灰度组。
|
||||
- 查看活动/暂停投放的范围、比例、并发上限和行版本，并按权限暂停或恢复。
|
||||
- 创建五类配置草稿并查看相邻版本差异；创建Agent组合时直接从当前客户组织已经发布过的人设、音色、模型和路由版本中选择，不需要手工复制UUID或编辑组合JSON。
|
||||
- 登记和查看离线评测证据。
|
||||
- 配置租户、设备组或试验对象投放参数并审批发布/回滚。
|
||||
- 根据角色隐藏写入控件，并显示空数据、失败、并发冲突与操作结果。
|
||||
|
||||
Agent组合选择器优先预选最近发布的组件版本，并明确标记仍可追溯复用的已退役版本。任一组件类型尚无已发布版本时，页面显示缺失类型并禁用创建按钮；切换客户组织会重置未提交配置和通用评测表单，避免把上一客户组织的组件编号或评测结论带入新草稿。页面校验只用于减少录入错误，提交和发布时服务端仍重新验证客户组织、组件类型以及`PUBLISHED/RETIRED`状态。
|
||||
|
||||
投放暂停和恢复同样使用页面内受控操作区，固定投放公开编号、配置键、范围、当前状态、比例、并发上限和行版本。暂停要求原因、观察依据及“只停止后续新通话命中”的影响确认；恢复要求问题消除证据、观察/回退方案，并确认配置仍可发布且同一范围不存在其他活动投放。三类受控操作在页面提交前只编辑本地草稿，实际请求继续由服务端执行角色、租户、状态和`If-Match`校验。
|
||||
|
||||
草稿提交审批、待审批版本发布和已退役历史内容回滚也使用具体版本卡片内的全宽受控流转区。确认区固定版本公开编号、类型、配置键、版本号、状态、行版本、创建人和变更说明；提交审批只要求确认目标与内容，不会直接发布。发布与回滚在当前受控区内单独填写客户组织、设备组或试验对象范围、灰度比例、并发影响上限和最长500字符的依据，选择其他版本时不会隐式沿用这些参数。范围或目标变化会重新要求影响确认；发布明确只影响后续新通话，回滚明确创建新的不可变版本而不复活历史行。取消、客户组织切换或列表刷新会清除草稿且不发送流转请求，服务端双人审批、评测、资源、租户、状态、幂等和并发门禁保持不变。
|
||||
|
||||
## 9. 验证
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-ops-config.ps1
|
||||
```
|
||||
|
||||
主烟测使用真实Keycloak账号和真实设备HMAC，覆盖普通账号403、敏感键拒绝、幂等、创建人自批拒绝、无评测发布阻断、评测证据查询、缺少模型/凭据资源阻断、正确类型资源放行、资源撤销、投放台账、租户与设备组并存、设备组优先、回滚版本链、新通话冻结和事务审计，并清理所有合成数据。日常低强度验证另以真实PostgreSQL的定向HTTP用例覆盖暂停、缺少`If-Match`、过期版本冲突、恢复和审计，不要求重复执行整套主烟测。
|
||||
|
||||
页面可用性增量采用一次真实OIDC登录的无提交冒烟，不重复整套回归：`test/e2e/visual-ops-config-evaluation.mjs`以临时资源、活动投放和暂停投放为目标，检查三类确认区的目标与行版本绑定、原因门禁、影响确认、取消关闭、零撤销/暂停/恢复PATCH、零横向溢出、零控制台错误和零非预期失败请求；`finally`按公开夹具范围精确清理。该检查证明页面不会误提交且操作前置约束可用，不代替服务端已有状态机烟测或目标环境真实资源验证。
|
||||
|
||||
配置版本流转另使用`test/e2e/visual-ops-config-version-transition.mjs`进行单条真实OIDC无提交验证：脚本创建`DRAFT`、`PENDING_APPROVAL`和`RETIRED`三条临时版本，检查提交、发布、回滚目标及行版本绑定，原因/范围/二次确认门禁，试验对象范围强制100%及修改范围后重新确认，取消关闭和数据库状态不变，同时检查零流转请求、零横向溢出、零控制台错误和零失败请求。截图仅用于确认全宽表单可读性，脚本结束后精确清理三条配置夹具。
|
||||
|
||||
实际Chrome页面检查：
|
||||
|
||||
```powershell
|
||||
$env:PLAYWRIGHT_REQUIRE_FROM='C:\Users\19926\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules'
|
||||
$env:CHROME_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
|
||||
node .\scripts\visual-ops-config-ui.cjs
|
||||
```
|
||||
|
||||
检查覆盖OIDC登录、运营工作台可见性、资源/设备组/投放/版本区布局、接口失败、控制台错误和横向溢出；截图保存到`test/e2e/screenshots/operations/ops-config-workspace.png`。
|
||||
|
||||
通用评测表单另使用`test/e2e/visual-ops-config-evaluation.mjs`进行单条轻量验证：脚本创建一条临时路由草稿，经真实OIDC深链进入配置工作台，验证目标/行版本绑定、空字段与未选结论阻断、通过结论二次确认、失败结论显式选择、取消关闭、零评测POST、零控制台错误和零横向溢出，最后精确清理配置及评测夹具。该检查不替代服务端评测登记、发布门禁和标准Agent报告验证。
|
||||
@@ -0,0 +1,99 @@
|
||||
# 运营敏感数据临时访问开发说明
|
||||
|
||||
> 对应接口契约：OpenAPI 0.55.0
|
||||
> 对应数据库迁移：V27
|
||||
> 适用范围：指定客户组织内、指定单次通话的限时字幕读取与原录音播放
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
运营账号默认只能在诊断工作台查看设备、通话、供应商任务、错误码和配置版本等脱敏状态，不能通过家庭角色或运营角色直接读取字幕正文或取得录音地址。确需排障时，申请人必须选择单次通话、最小能力、明确理由和到期时间，由另一名审批人员决定；批准后也只能由原申请人在有效期内使用。每次成功读取和每次被拒绝的尝试均独立记录，不把字幕或录音地址写入审计正文。
|
||||
|
||||
能力只有两种：
|
||||
|
||||
- `TRANSCRIPT_READ`：读取指定通话已经落库的最终话轮；
|
||||
- `RECORDING_PLAY`：查看该通话已验证录音分片，并为单个分片现场签发5分钟播放地址。
|
||||
|
||||
单次申请至少5分钟、最长4小时。申请不支持全租户、全设备、全长者或长期通配范围，不提供录音下载能力。录音播放除临时批准外，仍要求原始录音存储授权当前有效。
|
||||
|
||||
## 2. 角色与权限
|
||||
|
||||
| 角色 | 申请 | 查看队列 | 审批 | 使用批准权限 |
|
||||
|---|---:|---:|---:|---:|
|
||||
| `ops_viewer` | 是 | 仅本人 | 否 | 仅本人已批准申请 |
|
||||
| `ops_operator` | 是 | 仅本人 | 否 | 仅本人已批准申请 |
|
||||
| `ops_approver` | 是 | 当前客户组织 | 是，禁止自批 | 仅本人已批准申请 |
|
||||
| `ops_admin` | 是 | 当前客户组织 | 是，禁止自批 | 仅本人已批准申请 |
|
||||
|
||||
审批角色不能借用申请人的批准，也不能批准自己提交的申请。账号被停用或平台角色退回`customer`后，即使申请尚未到期也无法继续使用。
|
||||
|
||||
## 3. 业务流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant R as 申请人
|
||||
participant API as 运营API
|
||||
participant A as 另一名审批人
|
||||
participant DB as PostgreSQL
|
||||
participant S as 私有对象存储
|
||||
R->>API: 通话+能力+理由+到期时间+幂等键
|
||||
API->>DB: 固定租户和通话，写PENDING申请与审计
|
||||
A->>API: APPROVE/REJECT+审批理由
|
||||
API->>DB: 校验非本人、未到期、仍为PENDING
|
||||
API->>DB: 写决定、审批人、时间与审计
|
||||
R->>API: 申请编号+指定通话读取字幕
|
||||
API->>DB: 再校验申请人/租户/通话/能力/状态/有效期
|
||||
API->>DB: 写SUCCESS或DENIED逐次访问日志
|
||||
API-->>R: 最终字幕及批准范围内的录音分片编号
|
||||
R->>API: 申请编号+单个分片播放
|
||||
API->>DB: 再校验RECORDING_PLAY和原始录音授权
|
||||
API->>S: 现场签发5分钟只读播放地址
|
||||
API->>DB: 写逐次访问日志与审计
|
||||
API-->>R: 短期播放地址
|
||||
```
|
||||
|
||||
到期判断发生在列表刷新和每次实际访问时。到期申请会进入`EXPIRED`，此后不再返回正文或签发地址；服务不依赖前端计时器实现安全边界。
|
||||
|
||||
### 3.1 页面申请流程
|
||||
|
||||
联调诊断工作台不使用浏览器弹窗采集申请信息。运营人员先通过精确编号定位一条通话，再在该诊断结果下打开页面内“临时敏感访问申请”表单。表单固定绑定当前通话，不能改成租户、设备或长者范围；页面同时明确提示“提交申请不等于获得访问权限”，必须等待另一名审批人处理。
|
||||
|
||||
- “读取本次通话最终字幕”是本页面排障流程的必选能力，默认选中且不可取消；
|
||||
- “同时申请本次通话原录音播放”由申请人按实际需要选取，不勾选时不申请录音能力；
|
||||
- 排障理由必填、最长500字符，空理由不能提交；
|
||||
- 有效期只能选择15分钟、1小时或4小时，服务端仍执行最长4小时校验；
|
||||
- 取消申请会关闭表单并清空当前草稿，不创建申请；
|
||||
- 页面不提供录音下载选项，批准后的播放仍按单分片签发5分钟地址。
|
||||
|
||||
审批角色从待审批卡片打开页面内审批区，不再使用浏览器输入弹窗。审批区冻结申请公开编号、版本、申请人、通话、能力、到期时间和原始理由，避免审批过程中列表刷新或选择变化造成目标漂移。批准与拒绝依据均必填、最长500字符：批准在填写依据后还必须确认申请人不是本人，并已复核单次通话、最小能力和到期时间；拒绝需要说明能力范围、理由或有效期不满足要求的具体原因。取消或刷新申请列表会清除审批草稿，不调用审批接口。页面隐藏本人申请的审批按钮，服务端仍会再次校验禁止自批、审批角色、`PENDING`状态、租户、版本和到期时间。
|
||||
|
||||
## 4. 接口设计
|
||||
|
||||
所有接口要求OIDC Bearer令牌和`X-Tenant-Id`。创建与审批还要求`Idempotency-Key`；敏感读取响应统一`Cache-Control: no-store`。
|
||||
|
||||
| 方法与路径 | 说明 |
|
||||
|---|---|
|
||||
| `GET /api/v1/ops/sensitive-access-requests` | 本人申请或审批队列 |
|
||||
| `POST /api/v1/ops/sensitive-access-requests` | 创建单通话、限能力、限时申请 |
|
||||
| `POST /api/v1/ops/sensitive-access-requests/{id}/review` | 另一名审批人批准或拒绝 |
|
||||
| `GET /api/v1/ops/sensitive-conversations/{id}` | 使用`X-Ops-Access-Grant`读取最终字幕 |
|
||||
| `POST /api/v1/ops/sensitive-media/{id}/play` | 使用批准申请签发单分片5分钟播放地址 |
|
||||
|
||||
稳定错误包括`TEMPORARY_ACCESS_DENIED`、`TEMPORARY_ACCESS_STATE_CONFLICT`、`RESOURCE_NOT_FOUND`和幂等冲突。缺少申请编号、能力不匹配、审批未完成、申请人与调用人不同、到期、跨租户或原始录音授权失效均不会降级放行。
|
||||
|
||||
## 5. 数据库设计
|
||||
|
||||
`ops_sensitive_access_request`保存申请公开编号、租户、通话、申请人、规范化能力数组、理由、申请到期时间、状态、审批人、审批理由、审批时间和版本。部分唯一索引保证同一申请人对同一通话最多只有一个`PENDING/APPROVED`申请。
|
||||
|
||||
`ops_sensitive_access_log`追加保存申请、调用人、通话、可选录音分片、能力、`SUCCESS/DENIED`结果、稳定拒绝原因、接口请求关联编号和时间，不保存字幕正文、对象路径或播放地址。通用`audit_event`另保存申请、审批和逐次访问动作，支持按请求编号还原操作链。
|
||||
|
||||
## 6. 验证
|
||||
|
||||
```powershell
|
||||
$env:TEST_DATABASE_URL='postgres://voice:voice_dev_only@localhost:55432/voice_platform?sslmode=disable'
|
||||
go test ./internal/opsaccess -count=1 -cover
|
||||
pwsh -NoProfile -File .\scripts\smoke-ops-sensitive-access.ps1
|
||||
```
|
||||
|
||||
服务集成测试覆盖申请、自批拒绝、错误使用人拒绝、另一人审批、字幕读取、录音短链、原申请到期和成功/拒绝日志。HTTP烟测使用本地真实OIDC管理员与审批账号，验证双账号审批和逐次审计后精确清理夹具。生产验收仍需用实际客服组织、值班审批账号、真实录音对象和审计留存策略复测。
|
||||
|
||||
页面改动采用轻量可用性检查：`test/e2e/visual-ops-sensitive-access-request.mjs`使用真实本地OIDC、临时单通话和另一用户的待审批申请夹具，验证未登录深链在认证后恢复到联调诊断、创建申请的空理由/能力/有效期门禁，以及批准和拒绝时申请上下文、版本、依据、最小能力复核与取消清理。脚本要求桌面页面无横向溢出、控制台错误或失败请求，并明确拦截、断言敏感访问创建和审批请求均为零，不实际提交或审批，不替代上面的双账号服务集成验证。
|
||||
@@ -0,0 +1,165 @@
|
||||
# 性能、恢复、安全与兼容性专项验证报告
|
||||
|
||||
> 验证日期：2026-08-23
|
||||
> 验证范围：本地 Compose 集成环境、合成数据、实际 Chrome/Edge
|
||||
> 需求依据：需求规格说明书中的服务指标、容量基线、恢复指标、安全专项和浏览器兼容要求
|
||||
|
||||
## 1. 结论边界
|
||||
|
||||
本报告证明当前代码在一台 Windows 开发机的本地 Compose 环境中可以完成规定的功能容量脚本、故障恢复、安全门禁和浏览器检查。它不证明生产环境已经达到月度 99.9% 可用性，也不能替代真实火山 RTC/豆包账号、真机、生产网络、生产 PostgreSQL/Redis/对象存储、macOS Safari、云 KMS 和真实告警接收器的验收。
|
||||
|
||||
所有负载夹具均使用合成数据并在测试结束后精确清理。性能数字包含本地 Docker Desktop、脚本客户端和本机网络栈影响，只能作为研发回归基线；生产 SLA 必须在与正式部署规格一致的预生产环境重新测量。
|
||||
|
||||
## 2. 验证环境
|
||||
|
||||
| 项目 | 本次环境 |
|
||||
|---|---|
|
||||
| 应用 | Go 模块化单体，独立 API、Callbacks、Worker 进程 |
|
||||
| 前端 | React/Vite，Nginx 静态资源和 API/SSE 反向代理 |
|
||||
| 数据 | PostgreSQL 16 + pgvector、Redis 7、MinIO |
|
||||
| 身份 | 本地 Keycloak OIDC，合成账号和客户组织 |
|
||||
| 负载工具 | k6、Go 标准库 SSE 连接器、PowerShell 夹具/对账脚本 |
|
||||
| 后端工具链 | 生产构建镜像固定 Go 1.26.6，`pgx/v5` 5.9.2 |
|
||||
| 浏览器 | Chrome 151.0.7922.170、Edge 151.0.4129.101 |
|
||||
| 数据库版本 | V23，`dirty=false` |
|
||||
|
||||
## 3. 性能与容量结果
|
||||
|
||||
### 3.1 指标对照
|
||||
|
||||
| 需求项 | 研发门禁 | 本地结果 | 结论 |
|
||||
|---|---:|---:|---|
|
||||
| 普通 API 查询 | 50 RPS 持续 30 分钟；错误率 `<0.1%`；p95 `<500ms` | 90001 次请求，实际 50.003 RPS，0% 失败、0 中断，p95 3.67ms、p99 4.12ms、最大 278.57ms；每次就绪响应的 PostgreSQL/Redis 均为 up | 通过（本地） |
|
||||
| 供应商回调确认 | 500 次/秒持续 10 分钟；错误率 `<0.1%`；p95 `<200ms` | 300000 次请求，实际 500.016 次/秒，0% 失败、0 中断，p95 8.90ms、p99 11.81ms；300000 个唯一事件全部处理/忽略，100 组会话和 RTC 任务保持 ACTIVE | 通过（本地） |
|
||||
| 活跃通话状态 | 1000 条同时活跃 | 950 条健康 ACTIVE；50 条租约到期均进入 STOPPING；每条只产生一个停止意图 | 通过 |
|
||||
| Web 状态连接 | 500 条同时 SSE | 500 条全部建立；保持 5 秒；50 条使用 `Last-Event-ID` 重连成功 | 通过 |
|
||||
| 媒体分片 | 10000 条，使用分页/分批 | 10 批 × 1000 条；数据库 10/10000/10000 精确对账；优化后平均 0.12 秒、p95 0.16 秒、最大 0.16 秒 | 通过 |
|
||||
| 媒体上传 URL | p95 `<1s` | 1000 条/批的预签名清单 p95 0.16 秒 | 通过（本地） |
|
||||
| 主体删除 | 100 个并发请求 | 100/100 受理，HTTP 失败率 0%，提交 p95 385.15ms；11.58 秒内 600 个子任务全部收敛并生成 100 个墓碑 | 通过 |
|
||||
| 页面首次绘制 | p75 `<3s` | 单轮本地 FCP：Chrome 124ms、Edge 116ms | 基础门禁通过；生产 p75 待采样 |
|
||||
|
||||
### 3.2 媒体批量优化
|
||||
|
||||
首次 10000 分片验证功能正确，但逐分片执行查询、插入和批次关联导致第 10 批达到 1.49 秒，未满足上传 URL p95 小于 1 秒的目标。服务改为使用 PostgreSQL `jsonb_to_recordset` 完成批量插入、整体一致性核验、批量状态恢复和批量关联。优化后同样 10×1000 的第二次稳定结果为平均 0.12 秒、p95 0.16 秒、最大 0.16 秒，API 容器内存峰值约 15.8MiB；原双轨上传、对象校验、访问授权和本地删除回执烟测仍通过。
|
||||
|
||||
### 3.3 回调长稳态夹具边界
|
||||
|
||||
回调负载只验证供应商通知验签、关联、幂等落库和确认响应，不模拟设备心跳。首次长测使用 `STARTING_AGENT` 夹具，第一条启动事件把会话激活并将租约调整为正常的短心跳租约；因为负载端没有继续发送设备心跳，恢复任务随后按设计收口会话，导致“10 分钟后仍为 ACTIVE”的夹具断言失败。HTTP 层当次仍为 300001 次请求、0% 失败、p95 9.01ms、p99 14.52ms，且 300000 个唯一事件全部处理/忽略。
|
||||
|
||||
最终验收把纯回调容量夹具预置为租约覆盖测试窗口的 ACTIVE 会话，不修改产品租约或恢复逻辑；短测先通过后重新执行完整 10 分钟。最终 HTTP、事件落库以及 100 组会话/RTC 任务终态断言全部通过。设备心跳续租和租约到期收口另由通话状态负载与恢复脚本验证。
|
||||
|
||||
### 3.4 可重复命令
|
||||
|
||||
```powershell
|
||||
# 普通 API：默认 acceptance 为 50 RPS / 30 分钟
|
||||
docker run --rm -v "${PWD}/test/load:/scripts:ro" grafana/k6 run `
|
||||
-e BASE_URL=http://host.docker.internal:58080 `
|
||||
-e PROFILE=acceptance /scripts/api-readiness.js
|
||||
|
||||
# 供应商回调：默认 acceptance 为 500/s / 10 分钟
|
||||
pwsh -NoProfile -File .\scripts\load-provider-callbacks.ps1 -Profile acceptance -ConversationPool 100
|
||||
|
||||
pwsh -NoProfile -File .\scripts\load-conversation-state.ps1
|
||||
pwsh -NoProfile -File .\scripts\load-sse-connections.ps1 -Connections 500
|
||||
pwsh -NoProfile -File .\scripts\load-media-manifest.ps1
|
||||
pwsh -NoProfile -File .\scripts\load-privacy-delete.ps1
|
||||
```
|
||||
|
||||
## 4. 恢复验证
|
||||
|
||||
### 4.1 PostgreSQL 隔离恢复
|
||||
|
||||
`verify-postgres-restore.ps1`从运行库执行自定义格式 `pg_dump`，创建随机命名的隔离数据库并执行 `pg_restore`，然后对比迁移版本、dirty 状态、客户组织/用户计数、表数量和外键数量。实测结果：
|
||||
|
||||
- 源库与恢复库均为 `22|false|2|3`；
|
||||
- 公共表 66 张、外键 190 条；
|
||||
- 本地完整演练约 5.14 秒；
|
||||
- 临时数据库和备份文件在核验后均已删除。
|
||||
|
||||
这证明备份文件可以实际恢复，不证明生产 PITR、RPO≤15 分钟或 RTO≤4 小时。生产结论还需要连续归档、跨故障域备份、正式数据量和隔离恢复环境。
|
||||
|
||||
### 4.2 进程和 Redis 恢复
|
||||
|
||||
`verify-runtime-recovery.ps1`完成以下演练：
|
||||
|
||||
1. 停止 Worker，并在 PostgreSQL 写入一个待处理 Outbox 事件；
|
||||
2. 重启 API、Callbacks 和 Worker，确认三个进程启动时间变化且就绪检查恢复；
|
||||
3. Worker 启动后仅尝试一次即完成停机期间的待办；
|
||||
4. 在 Redis 写入合成租约/在线键后执行 `FLUSHDB`，确认键数从 14 变为 0；
|
||||
5. API 保持就绪，真实设备 HMAC 只读配置请求返回 200，并把防重放热状态重建为 2 个键；
|
||||
6. PostgreSQL 的客户组织、用户、家庭和长者权威计数前后一致。
|
||||
|
||||
该结果证明 Redis 是可重建热状态且可靠任务以 PostgreSQL 为准。数据库完全失联、区域故障和生产网络分区仍需部署平台、外部探针及预生产演练。
|
||||
|
||||
### 4.3 供应商不可用与恢复
|
||||
|
||||
V23新增按客户组织和供应商持久化的`provider_dependency_state`。Worker只把网络错误、超时、HTTP 429和HTTP 5xx计为临时故障；连续失败达到部署阈值后暂停新启动，停止和异常回收始终旁路启动熔断。任一成功外呼会恢复可用状态。告警扫描器对不可用状态生成`PROVIDER_UNAVAILABLE` CRITICAL事件。
|
||||
|
||||
`verify-provider-outage.ps1`使用真实Worker待办和模拟供应商HTTP 503完成演练。实测证据为：熔断打开；熔断后新启动外呼0次；已知停止任务在故障期间继续尝试2次；历史通话查询HTTP 200；供应商不可用告警出现；恢复后停止任务完成、暂停的两条新启动进入ACTIVE，健康状态恢复AVAILABLE。V23还完成`23 → 22 → 23`单版本回退/重升，表消失与重建均已核验；所有演练夹具随后清理。
|
||||
|
||||
## 5. 安全验证
|
||||
|
||||
### 5.1 漏洞和供应链
|
||||
|
||||
首次 `govulncheck` 发现旧构建工具链 Go 1.26.1 的标准库可达漏洞以及 `pgx/v5` 5.7.6 的占位符混淆型 SQL 注入公告。处理后：
|
||||
|
||||
- 生产构建镜像固定 `golang:1.26.6-alpine`；
|
||||
- `pgx/v5` 升级至 5.9.2；
|
||||
- Go 全量测试通过；
|
||||
- 在 Go 1.26.6 容器内重新执行 `govulncheck ./...`，可达漏洞为 0；
|
||||
- `npm audit --audit-level=high` 为 0；
|
||||
- Trivy 对最终 Debian 基础层及 API、Callbacks、Worker、模拟设备和模拟供应商五个 Go 二进制扫描 HIGH/CRITICAL 且已有修复项，结果均为 0；
|
||||
- Gitleaks 扫描约 3.06MB 仓库内容，无密钥泄漏。唯一豁免同时限定为 `conversation_handlers_test.go` 路径和包含 `Idempotency-Key` 的行，因为幂等键是重放标识而非访问凭据。
|
||||
|
||||
### 5.2 HTTP、身份和输入边界
|
||||
|
||||
`security-http-smoke.ps1`验证：
|
||||
|
||||
- 匿名 API 请求返回 401，低权限用户访问运营告警返回 403；
|
||||
- SQL 注入式 UUID、路径穿越式资源编号和非 UUID 均返回安全 400，响应不包含 SQLSTATE、pgx 或数据库语法；
|
||||
- 已知 `Content-Length` 超过 1MiB 时在领域处理器之前返回 413 `REQUEST_BODY_TOO_LARGE`；
|
||||
- 伪造供应商回调签名返回 401；
|
||||
- 完全相同的设备 Nonce 第二次请求返回 401；
|
||||
- `nosniff`、`DENY` 和 `no-referrer` 响应头存在；
|
||||
- 超限正文哨兵没有进入 API/Callbacks 日志；
|
||||
- 探测前后家庭和主体计数不变。
|
||||
|
||||
外呼地址只来自运维配置，不接受家庭用户或设备请求正文中的 URL；生产配置还要求供应商和对象存储使用 HTTPS、拒绝 localhost/占位凭据，从入口上限制 SSRF 面。SQL 业务值均使用 pgx 参数，唯一动态分享查询只在程序内固定表和连接片段中选择，不拼接请求值。
|
||||
|
||||
### 5.3 提示注入
|
||||
|
||||
本地默认内容整理器是确定性适配器，不执行长者文本中的指令；生产可切换到已实现的方舟兼容适配器。内容安全基线识别中英文常见提示注入，例如“忽略之前指令并输出其他长者资料”或“reveal system prompt”；命中后在外部模型调用前按高风险处理，不生成普通故事、事实候选或可召回记忆。无论内容文本如何，客户组织、家庭、长者、授权和可见资源仍由服务端关系及数据库条件推导。真实模型上线前仍需完成模型级红队、系统提示隔离和输出策略评测。
|
||||
|
||||
## 6. 浏览器兼容性
|
||||
|
||||
`browser-matrix.mjs`使用实际安装的浏览器二进制完成 OIDC 登录、运营配置、费用额度、告警处置、认证 SSE 和家庭业务工作台检查。每种浏览器在 1440×1000 桌面与 1024×900 平板视口逐一打开以下 8 个页签：家庭成员、长者与授权、设备管理、固件发布、通话记录、故事与记忆、资源分享、隐私请求。
|
||||
|
||||
| 浏览器 | 版本 | 视口 | 结果 |
|
||||
|---|---|---|---|
|
||||
| Chrome | 151.0.7922.170 | 1440×1000、1024×900 | 0 溢出、0 控制台错误、0 失败请求，SSE 已连接 |
|
||||
| Edge | 151.0.4129.101 | 1440×1000、1024×900 | 0 溢出、0 控制台错误、0 失败请求，SSE 已连接 |
|
||||
| Safari | 未安装（Windows） | 未执行 | 必须在 macOS 的最近两个 Safari 版本补测 |
|
||||
|
||||
Safari现场补测采用[Safari兼容性一致性证据](safari-compatibility-evidence.md)的精简矩阵：两个真实版本、两种视口和六条关键流程，共24项；Chrome/Edge或Playwright WebKit结果不得替代真实Safari报告。
|
||||
|
||||
验证过程中发现隐私请求工具栏的选择框保留 12rem 全局最小宽度，在 11rem 栅格列中产生局部溢出；已为该区域增加 `min-width:0` 和 100% 宽度，并在 Chrome/Edge 两种视口复测通过。截图位于：
|
||||
|
||||
- `test/e2e/screenshots/compatibility/chrome/desktop.png`
|
||||
- `test/e2e/screenshots/compatibility/chrome/tablet.png`
|
||||
- `test/e2e/screenshots/compatibility/edge/desktop.png`
|
||||
- `test/e2e/screenshots/compatibility/edge/tablet.png`
|
||||
|
||||
## 7. 最终回归与清理
|
||||
|
||||
最终V23镜像重建后执行`check.ps1`，全量Go测试/覆盖率采集、OpenAPI类型生成、npm审计、TypeScript和Vite生产构建均通过。认证、完整通话、媒体上传访问、主体隐私删除、运营配置灰度、用量费用额度、告警处置、资源分享和供应商故障纵向烟测全部通过。
|
||||
|
||||
最终运行库为`23|false`；Outbox的pending、processing和dead均为0；回调、供应商故障、媒体、隐私容量夹具和测试告警均为0；临时恢复/迁移数据库为0。烟测成功产生的mock供应商AVAILABLE记录和内存任务已定向清理，不删除非测试业务数据。
|
||||
|
||||
## 8. 仍需外部完成的门禁
|
||||
|
||||
1. 在生产等价规格执行全部长测并形成容量曲线、CPU/内存/连接池/磁盘 IOPS 和安全余量，而不是照搬本地数字。
|
||||
2. 使用真实火山 RTC、豆包端到端语音、大模型和 Embedding 账号验证超时、限流、重复通知、供应商故障和费用账单对账。
|
||||
3. 在真机验证弱网、断网重连、设备重启、双轨录音、固件安全回退、证书轮换和连续通话。
|
||||
4. 在 macOS 完成最近两个 Safari 版本的桌面和平板/触控兼容矩阵。
|
||||
5. 在生产数据库完成 PITR、RPO≤15 分钟、RTO≤4 小时及跨故障域恢复演练。
|
||||
6. 接入 KMS/HSM、外部基础设施探针、真实告警接收器、值班升级链和应急联系人。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 家庭角色权限矩阵 V0.1
|
||||
|
||||
家庭角色用于控制一般管理能力，不代表录音、下载、分享或其他高敏感资源授权。资源访问始终继续检查客户组织、家庭成员、长者代理关系、分项授权、资源分享授权和资源状态。
|
||||
|
||||
家庭工作台调整非所有者成员角色时，先固定目标成员、当前角色和成员行版本，再选择管理员、编辑者或查看者，并展示本矩阵对应的能力变化。选择另一目标角色会要求重新确认；取消、切换家庭或刷新不会写入。最终PATCH继续由服务端验证`household.member.manage`、所有者保护、租户边界和`If-Match`，页面说明不能替代服务端授权。
|
||||
|
||||
| 能力 | 所有者 | 管理员 | 编辑者 | 查看者 |
|
||||
|---|:---:|:---:|:---:|:---:|
|
||||
| 查看家庭基本信息 | ✓ | ✓ | ✓ | ✓ |
|
||||
| 修改家庭基本信息 | ✓ | ✓ | | |
|
||||
| 管理成员 | ✓ | ✓ | | |
|
||||
| 转移家庭所有权 | ✓ | | | |
|
||||
| 查看长者基本资料 | ✓ | ✓ | ✓ | ✓ |
|
||||
| 修改长者基本资料 | ✓ | ✓ | ✓ | |
|
||||
| 查看通话文字结果 | ✓ | ✓ | ✓ | ✓ |
|
||||
| 核对故事候选 | ✓ | ✓ | ✓ | |
|
||||
| 管理普通设备配置 | ✓ | ✓ | ✓ | |
|
||||
| 查看隐私请求进度 | ✓ | ✓ | | |
|
||||
| 提交隐私请求 | ✓ | | | |
|
||||
| 播放原录音 | 需独立授权 | 需独立授权 | 需独立授权 | 需独立授权 |
|
||||
| 下载原录音 | 需独立授权 | 需独立授权 | 需独立授权 | 需独立授权 |
|
||||
|
||||
## 服务端判断顺序
|
||||
|
||||
1. 验证OIDC令牌签发方、使用对象、签名、有效期和Subject。
|
||||
2. 通过`issuer + subject`查询平台账号，不接受浏览器指定租户边界。
|
||||
3. 通过目标资源反查客户组织和家庭，再匹配当前身份的有效账号与成员关系。
|
||||
4. 根据成员角色检查一般业务能力。
|
||||
5. 后续领域接口继续检查长者关系、分项授权、具体资源授权和资源状态。
|
||||
6. 跨客户组织、跨家庭和无权访问统一返回`RESOURCE_ACCESS_DENIED`，不泄露资源是否存在。
|
||||
|
||||
## 本地合成账号
|
||||
|
||||
本地Keycloak Realm为`voice-local`，仅用于合成数据联调：
|
||||
|
||||
| 用户名 | 密码 | 客户组织 | 家庭角色 |
|
||||
|---|---|---|---|
|
||||
| `owner` | `LocalOnly123!` | 合成数据一号客户组织 | 所有者 |
|
||||
| `editor` | `LocalOnly123!` | 合成数据一号客户组织 | 编辑者 |
|
||||
| `outsider` | `LocalOnly123!` | 合成数据二号客户组织 | 查看者 |
|
||||
|
||||
这些密码不得复制到任何共享、测试、预生产或生产环境。
|
||||
@@ -0,0 +1,119 @@
|
||||
# 试点运行日报开发说明
|
||||
|
||||
> 对应接口契约：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层生成 |
|
||||
|
||||
请求体示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"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. 业务流程设计
|
||||
|
||||
```mermaid
|
||||
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
|
||||
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清单执行真实设备、供应商、家庭试点、容量、安全、恢复和人工审批，不以本地日报烟测替代外部验收。
|
||||
@@ -0,0 +1,122 @@
|
||||
# 试点运行周报开发说明
|
||||
|
||||
> 对应接口契约：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烟测验证固定隐私分布、配置与固件设备数守恒、比例可用性、投诉证据缺口、敏感字段排除、幂等重放和烟测清理；浏览器烟测验证周报下载和缺口提示。全仓回归、容量、安全、恢复、真实设备和供应商验证仍在固定发布候选上集中执行。
|
||||
@@ -0,0 +1,130 @@
|
||||
# 隐私数据请求开发说明
|
||||
|
||||
## 1. 当前交付边界
|
||||
|
||||
当前版本完成了`ACCESS`数据访问申请和`DELETE`主体删除申请的端到端闭环。`ACCESS`由Worker在服务端租户/家庭/长者边界内盘点数据范围；`DELETE`在受理事务内立即冻结主体，再由Worker对六个子系统逐项处理、持久化状态并对账，只有全部子任务进入`COMPLETED`或经核验的`SKIPPED`后才将总请求置为`COMPLETED`。
|
||||
|
||||
隐私请求结果始终设置`content_included=false`，不把档案、转写、故事或记忆正文复制到请求表、审计记录和普通日志。正文导出由独立私有导出任务实现，见`data-export.md`。当前仍未开放`CORRECTION`和独立的`CONSENT_WITHDRAWAL`批处理请求。
|
||||
|
||||
## 2. 权限与安全边界
|
||||
|
||||
| 能力 | 家庭所有者 | 管理员 | 编辑者/查看者 |
|
||||
|---|:---:|:---:|:---:|
|
||||
| `privacy.read` | 允许 | 允许 | 拒绝 |
|
||||
| `privacy.manage` | 允许 | 拒绝 | 拒绝 |
|
||||
|
||||
服务端从OIDC主体重新解析账号、客户组织、家庭成员和长者归属，不使用浏览器提交的租户条件。创建请求必须提交16至128字符的`Idempotency-Key`；同键同正文返回原请求，同键不同正文返回`IDEMPOTENCY_KEY_CONFLICT`。详情响应使用`Cache-Control: no-store`和强ETag。
|
||||
|
||||
`DELETE`还必须满足以下门禁：
|
||||
|
||||
- `reason`为1至500字符，但服务端仅持久化SHA-256摘要，不保存原因正文；
|
||||
- `confirmation`必须与主体当前称呼完全一致，确认值不持久化；
|
||||
- 主体存在`PREPARING`、`ROOM_ISSUED`、`STARTING_AGENT`、`ACTIVE`或`STOPPING`通话时返回`SUBJECT_ACTIVE_CONVERSATION`，必须先正常结束通话；
|
||||
- 受理后主体立即变为`deleting`，一般主体、内容、设备和导出接口不再返回该主体；所有有效授权同时撤回，记忆停用并清除可召回向量；
|
||||
- 删除申请详情使用请求编号仍可查询，即使主体已进入`deleting`或`deleted`。
|
||||
|
||||
## 3. 业务流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 家庭所有者
|
||||
participant A as API
|
||||
participant D as PostgreSQL
|
||||
participant O as Outbox
|
||||
participant W as Worker
|
||||
U->>A: POST /subjects/{id}/privacy-requests
|
||||
A->>A: 验证OIDC、privacy.manage、长者边界和幂等键
|
||||
A->>D: 创建SUBMITTED请求与PENDING子任务
|
||||
A->>O: privacy.access_requested
|
||||
A-->>U: 202 + 请求编号
|
||||
W->>D: VERIFYING -> EXECUTING
|
||||
W->>D: 按冻结分类统计当前长者数据
|
||||
W->>D: 子任务COMPLETED，请求COMPLETED
|
||||
W->>D: 写入无正文系统审计
|
||||
U->>A: GET /privacy-requests/{id}
|
||||
A-->>U: 状态、分类数量和子任务
|
||||
```
|
||||
|
||||
### 3.1 DELETE删除与对账流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 家庭所有者
|
||||
participant A as API
|
||||
participant D as PostgreSQL
|
||||
participant O as Outbox
|
||||
participant W as Worker
|
||||
participant R as Redis
|
||||
participant S as MinIO
|
||||
U->>A: DELETE申请+原因+精确称呼确认
|
||||
A->>D: 校验权限、确认值及无活动通话
|
||||
A->>D: 主体deleting、撤回授权、停用记忆/向量
|
||||
A->>D: 创建6个PENDING子任务
|
||||
A->>O: privacy.delete_requested
|
||||
A-->>U: 202 + 请求编号
|
||||
W->>R: 删除会话租约和设备在线键
|
||||
W->>S: 删除所有私有导出对象
|
||||
W->>D: 核验媒体对象和外部索引引用
|
||||
W->>D: 清空pgvector及供应商引用
|
||||
W->>D: 脱敏正文、快照、回调、绑定和档案
|
||||
W->>D: 六任务对账+最小tombstone
|
||||
W->>D: 请求COMPLETED或PARTIAL_FAILED
|
||||
```
|
||||
|
||||
六类子任务如下：
|
||||
|
||||
| 子系统 | 当前动作 | 成功判定 |
|
||||
|---|---|---|
|
||||
| `redis` | 删除该主体历史通话租约键和关联设备在线键 | Redis删除操作成功，允许键本来不存在 |
|
||||
| `export_files` | 删除全部`export_task.object_ref`对应私有对象，任务改为`EXPIRED`并清空对象元数据 | 每个对象删除成功且数据库引用为空 |
|
||||
| `object_storage` | 删除该主体全部已登记录音对象，并把分片置为`DELETED`、清空对象引用和文件摘要 | 对象存储删除失败时记`FAILED`并持续重试；无对象时安全完成 |
|
||||
| `pgvector` | 清空本地embedding和provider引用，索引记`DELETED` | 目标主体本地向量均不可召回 |
|
||||
| `provider_index` | 检查外部供应商索引引用 | 无外部引用时记`SKIPPED`；存在引用但无删除适配器时失败并使总请求`PARTIAL_FAILED` |
|
||||
| `postgresql` | 对档案、事实、转写、摘要、故事、记忆、快照、回调和绑定做删除或不可逆脱敏 | 主体为`deleted`，正文为固定删除标记，审计只留最小证明 |
|
||||
|
||||
## 4. 接口
|
||||
|
||||
| 接口 | 能力 | 关键约束 | 结果 |
|
||||
|---|---|---|---|
|
||||
| `POST /api/v1/subjects/{id}/privacy-requests` | `privacy.manage` | 接受`ACCESS`或`DELETE`；必须`Idempotency-Key`；DELETE还需原因和精确确认 | `202`受理，幂等重放为`200` |
|
||||
| `GET /api/v1/subjects/{id}/privacy-requests` | `privacy.read` | 固定长者边界 | 请求列表及盘点摘要 |
|
||||
| `GET /api/v1/privacy-requests/{id}` | `privacy.read` | 服务端反查家庭归属；禁止缓存 | 请求详情和子任务 |
|
||||
|
||||
可请求的分类为`profile`、`consents`、`device_bindings`、`conversations`、`transcripts`、`summaries`、`stories`和`memories`。不指定分类时盘点全部分类。
|
||||
|
||||
## 5. 数据库
|
||||
|
||||
| 表 | 作用 | 关键约束 |
|
||||
|---|---|---|
|
||||
| `privacy_request` | 隐私请求聚合根 | 租户+申请人+幂等键唯一；请求摘要用于检测正文冲突 |
|
||||
| `privacy_subtask` | 子系统执行与重试状态 | 请求+子系统+目标唯一；保留尝试次数和最后错误 |
|
||||
| `tombstone` | 后续删除闭环的最小不可逆证明 | 只保存资源摘要和保留原因，不保存待删正文 |
|
||||
|
||||
V9迁移提供了请求、子任务和最小证明模型。当前`ACCESS`和`DELETE`已开放；`CORRECTION`与独立`CONSENT_WITHDRAWAL`仍保持关闭。
|
||||
独立临时空库已完成`up 1—9 → down -all → up 1—9`，最终迁移状态为`9|dirty=false`，验证库随后已删除。
|
||||
|
||||
## 6. 自动化验证
|
||||
|
||||
`scripts/smoke-privacy.ps1`使用真实本地OIDC令牌验证：
|
||||
|
||||
- 所有者创建、同键重放和同键不同范围冲突；
|
||||
- 编辑者提交请求返回403；
|
||||
- Worker完成数据库子任务，请求收敛为`COMPLETED`；
|
||||
- 返回的分类严格等于请求范围且`content_included=false`；
|
||||
- 列表可见、测试数据和关联Outbox/审计可清理。
|
||||
|
||||
`scripts/smoke-privacy-delete.ps1`使用临时家庭和主体，并验证：
|
||||
|
||||
- 错误称呼确认和非所有者提交均被拒绝；
|
||||
- 存在活动通话时删除返回409，正常结束后才允许受理；
|
||||
- 受理后普通主体读取和新建导出立即被阻断；
|
||||
- 冻结后的同键同正文仍能安全重放，不会创建第二个请求；
|
||||
- 六个子任务全部收敛为`COMPLETED`或经核验的`SKIPPED`；
|
||||
- 档案和稳定事实正文已脱敏，原因明文未进入请求表；
|
||||
- 私有导出数据库引用与MinIO对象均已删除；
|
||||
- 仅留下不含个人正文的SHA-256主体摘要墓碑；
|
||||
- 测试完成后临时业务数据、Outbox、审计和对象均被清理。
|
||||
|
||||
家庭工作台的“提交全量盘点”现通过页面内受控操作区提交。操作区固定当前长者公开编号和八类盘点范围：长者档案、授权记录、设备绑定、通话、话轮、摘要、故事和记忆；同时明确ACCESS结果仅返回各分类数量、处理状态和子任务状态，不会把个人正文复制到隐私请求、审计或普通日志。用户必须显式确认范围后才能提交，取消或切换业务上下文会清除草稿且不会创建请求。
|
||||
|
||||
页面按低强度策略使用真实OIDC执行无提交冒烟：检查固定对象、八类范围、正文边界、确认门禁和取消行为，并验证零创建请求、请求数量不变、无横向溢出及无非预期浏览器错误。服务端权限、幂等、租户隔离和Worker闭环继续由既有定向脚本覆盖，不在每次页面改动后重复执行全套隐私删除回归。
|
||||
@@ -0,0 +1,71 @@
|
||||
# 生产基础设施一致性证据说明
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
`cmd/infrastructure-conformance`把同一发布候选在目标环境中的域名与TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控证据形成`production-infrastructure-conformance-report-v1`。报告用于阻止“只部署了清单”或“本地Compose可用”被误登记为生产基础设施已经验收。
|
||||
|
||||
本地冒烟只输出`LOCAL_INFRASTRUCTURE/external_validation_required=true`。只有证据来源为`PRODUCTION`，环境为`STAGING`或`PRODUCTION`，七类组件、强制控制项、观测时间和三类引用全部完整时，才能输出`PRODUCTION_INFRASTRUCTURE/external_validation_required=false`。该报告不替代容量结论、恢复演练、密钥轮换或业务发布审批。
|
||||
|
||||
## 2. 采集格式
|
||||
|
||||
输入使用`production-infrastructure-capture-v1`，顶层字段如下：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `evidence_source` | `LOCAL`或`PRODUCTION`；不能用自定义值弱化范围 |
|
||||
| `candidate_version`、`build_digest` | 与候选证据包完全一致的版本和不可变镜像摘要 |
|
||||
| `environment` | 本地为`LOCAL`；真实报告只能是`STAGING`或`PRODUCTION` |
|
||||
| `region_ref`、`cluster_ref` | 脱敏区域和集群引用，不填写管理凭据或地址中的密钥 |
|
||||
| `change_ticket_ref` | 本地演练引用或目标环境变更工单 |
|
||||
| `attested_by_ref`、`attested_at` | 平台复核人引用和复核时间 |
|
||||
| `collected_at` | 本批证据收集结束时间 |
|
||||
| `components` | 七类组件证据；同一类型只能出现一次 |
|
||||
|
||||
每个组件必须包含`component_type`、`resource_ref`、`status=VERIFIED`、`observed_at`、`verified_controls`、`probe_ref`、`configuration_ref`和`audit_ref`。引用可指向受控工单、云资源台账、脱敏命令输出或监控截图，不应包含令牌、连接口令、证书私钥、对象存储密钥或业务正文。
|
||||
|
||||
## 3. 生产控制项
|
||||
|
||||
| 组件 | 必须验证的控制项 |
|
||||
|---|---|
|
||||
| `DOMAIN_TLS` | DNS已解析、TLS有效、证书到期受监控 |
|
||||
| `OIDC` | JWKS可用、TLS有效、客户组织映射已核对 |
|
||||
| `POSTGRES` | 私网、TLS、高可用、备份已配置、已监控 |
|
||||
| `REDIS` | 私网、TLS、高可用、可从权威状态重建、已监控 |
|
||||
| `OBJECT_STORE` | 私有访问、TLS、版本或保留策略、已监控 |
|
||||
| `NETWORK_ISOLATION` | 入口受限、出口受限、命名空间隔离 |
|
||||
| `MONITORING` | 指标已抓取、告警规则已加载、真实接收器已路由 |
|
||||
|
||||
控制项名称必须使用校验器定义值。额外控制项可以保留，但不能替代上表中的必需项。可用性、备份和高可用不能只用配置文件存在来证明，应关联目标资源状态或受控验证结果。
|
||||
|
||||
## 4. 九项一致性检查
|
||||
|
||||
报告固定执行：采集模式、证据来源、候选身份、采集与候选绑定、环境身份、七类组件覆盖、生产控制项覆盖、观测时间线和证据引用九项检查。任一检查失败，结果为`FAIL`并保持外部待验。
|
||||
|
||||
`PRODUCTION_INFRASTRUCTURE`是证据包不可豁免门禁。索引标记为`VERIFIED`时，第一个文件必须是同候选的`PASS/PRODUCTION_INFRASTRUCTURE`报告；本地报告会被拒绝。清单中的`production_infrastructure_validation`汇总环境、区域、集群、七类组件、各组件控制项数量和未完成缺口。
|
||||
|
||||
## 5. 生成命令
|
||||
|
||||
```powershell
|
||||
go run ./cmd/infrastructure-conformance `
|
||||
-capture E:\evidence\production-infrastructure-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\production-infrastructure-report.json
|
||||
```
|
||||
|
||||
本地可执行：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-infrastructure-conformance.ps1
|
||||
```
|
||||
|
||||
该脚本只做API就绪、OIDC JWKS、PostgreSQL、Redis、MinIO、Prometheus和仓库网络/告警配置的一条纵向检查；它不修改业务数据、不执行压力测试，也不会把`PRODUCTION_INFRASTRUCTURE`改为通过。
|
||||
|
||||
## 6. 现场执行顺序
|
||||
|
||||
1. 固定候选版本、镜像摘要、区域、集群和变更工单。
|
||||
2. 对七类组件分别执行目标环境探针并保存脱敏输出、配置版本和云审计引用。
|
||||
3. 由平台复核人确认观测发生在同一候选部署后，生成采集JSON。
|
||||
4. 运行校验器，报告必须为`PASS/PRODUCTION_INFRASTRUCTURE`且`external_validation_required=false`。
|
||||
5. 将报告作为该证据项第一个文件，再生成候选证据包并核对`coverage_complete=true`。
|
||||
6. 继续完成独立的恢复、KMS、告警接收器、Safari和业务审批门禁；基础设施报告本身不放行生产。
|
||||
@@ -0,0 +1,62 @@
|
||||
# 生产等价恢复演练一致性证据
|
||||
|
||||
## 1. 目标与范围
|
||||
|
||||
`cmd/recovery-conformance`把同一候选构建的故障注入、恢复时间线、权威数据摘要、业务连续性、重复效果检查、清理结果和审计引用形成`production-recovery-conformance-report-v1`。本地Compose演练固定输出`LOCAL_RECOVERY/external_validation_required=true`；只有预生产或生产等价基础设施完整覆盖四类演练后，报告才为`PRODUCTION_EQUIVALENT`。
|
||||
|
||||
本工具不自行规定RTO/RPO数值。`observed_recovery_seconds`只记录本次实测用时，是否符合业务方冻结的恢复目标由发布评审判断。报告通过也不替代跨故障域架构审查、云厂商恢复能力或业务发布批准。
|
||||
|
||||
## 2. 必须覆盖的四类演练
|
||||
|
||||
| 演练类型 | 最低要求 |
|
||||
|---|---|
|
||||
| `POSTGRES_RESTORE` | 从生产候选备份恢复到隔离目标，迁移状态、关键权威计数、约束和业务抽查一致，临时恢复目标受控清理 |
|
||||
| `REDIS_REBUILD` | 清空或替换Redis后，从PostgreSQL权威状态和实际请求重建租约、在线态、限流/重放状态，权威业务数据不变化 |
|
||||
| `SERVICE_ROLLING_RESTART` | API、Callbacks和Worker按生产部署策略滚动重启，Pod/进程就绪、停机期间Outbox恢复且业务效果只执行一次 |
|
||||
| `PROVIDER_OUTAGE_RECOVERY` | 供应商停机触发熔断和降级，新启动暂停但历史查询、停止和回收仍可用；供应商恢复后任务最终收敛且告警可关闭 |
|
||||
|
||||
生产等价报告缺少任一类型都会失败。本地报告可以只包含本轮实际执行的子集，但始终不能进入真实恢复门禁。
|
||||
|
||||
## 3. 采集格式
|
||||
|
||||
输入文件使用`production-recovery-capture-v1`并严格拒绝未知字段。顶层绑定候选版本、构建摘要、环境、基础设施、故障域、变更工单、复核人和采集时间。每条演练记录：
|
||||
|
||||
- 演练类型和脱敏场景引用；
|
||||
- 开始、完成时间及实测恢复秒数；
|
||||
- 恢复成功、数据完整、业务连续、无重复效果和夹具清理五个结果；
|
||||
- 恢复前后权威状态摘要，两者必须完全一致；
|
||||
- 执行记录、验证记录和审计记录的脱敏引用。
|
||||
|
||||
摘要用于比较结构化权威状态，不得直接散列低熵个人数据、Token或密钥。执行记录不得包含数据库连接串、供应商密钥、录音、字幕或个人信息。
|
||||
|
||||
## 4. 自动检查
|
||||
|
||||
报告固定包含11项检查：采集版本、来源、候选身份、候选绑定、生产等价环境身份、四类演练覆盖、时间线、恢复与清理、数据完整性、业务连续性/无重复效果、执行验证审计引用。任一项失败则报告为`FAIL`。
|
||||
|
||||
只有来源为`PRODUCTION_EQUIVALENT`、环境为`STAGING/PRODUCTION`、故障域和变更工单完整、四类演练全部通过且恢复前后摘要一致时，才设置`external_validation_required=false`。
|
||||
|
||||
## 5. 命令用法
|
||||
|
||||
```powershell
|
||||
go run ./cmd/recovery-conformance `
|
||||
-capture E:\evidence\production-recovery-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\production-recovery-report.json
|
||||
```
|
||||
|
||||
输出路径必须是绝对路径。通过返回0，不一致时仍写出失败报告并返回1，参数、文件或JSON错误返回2。报告保存输入SHA-256，避免归档后替换采集文件。
|
||||
|
||||
## 6. 候选证据包门禁
|
||||
|
||||
`release-evidence-index-v2`中的`PRODUCTION_RECOVERY`不可豁免。第一个文件必须是同候选、全部检查通过且范围为`PRODUCTION_EQUIVALENT`的官方报告。后续可以附数据库恢复日志、Kubernetes rollout记录、供应商故障工单、告警时间线和签署材料。
|
||||
|
||||
没有真实报告时，v3清单固定显示报告以及四类演练共5个缺口。`LOCAL_RECOVERY`、跨候选、缺故障域、缺演练、数据摘要不一致、重复业务效果或未清理夹具时必须保持`PENDING`，不能用`WAIVED`绕过。
|
||||
|
||||
## 7. 本地轻量演练
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\verify-runtime-recovery.ps1
|
||||
```
|
||||
|
||||
脚本停止Worker并插入一条唯一Outbox探针，重启API/Callbacks/Worker后确认只执行一次；随后清空Redis，通过真实设备签名请求重建热状态，并确认PostgreSQL权威计数不变。新增步骤把这两类结果生成`PASS/LOCAL_RECOVERY`报告。脚本不重复执行PostgreSQL备份恢复和供应商停机，因此真实门禁继续保持`PENDING`；结束后删除Outbox夹具和磁盘报告。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 项目研发基线 V0.1
|
||||
|
||||
## 已冻结范围
|
||||
|
||||
- 自建云端负责设备身份、通话控制、家庭与长者业务、授权、数据治理、Agent编排和运行维护。
|
||||
- 实时语音由设备、火山引擎RTC和豆包语音智能体直接传输，自建应用服务器不转发、不落盘。
|
||||
- 录音在授权有效时由设备直接上传S3兼容对象存储，应用接口只签发短期授权并核验结果。
|
||||
- PostgreSQL保存最终业务事实；Redis只保存可重建在线状态、租约、限流、幂等结果和短期缓存。
|
||||
- 机器生成的故事和事实必须经过家庭用户核对，确认后才能成为正式记忆。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层次 | 首版选择 |
|
||||
|---|---|
|
||||
| 后端 | Go模块化单体，`api`、`callbacks`、`worker`独立进程 |
|
||||
| 前端 | React、TypeScript、Vite |
|
||||
| 业务数据库 | PostgreSQL 16与pgvector |
|
||||
| 缓存 | Redis 7 |
|
||||
| 对象存储 | S3兼容存储，本地使用MinIO |
|
||||
| 身份 | OIDC/OAuth 2.1；本地先使用模拟身份，接入方式保持可替换 |
|
||||
| 接口 | REST/JSON、OpenAPI 3.1；状态通知使用SSE |
|
||||
| 部署 | Docker、Docker Compose；后续接入环境流水线 |
|
||||
|
||||
## 第一批外部待确认项
|
||||
|
||||
以下内容不会阻止本地工程和模拟闭环开发，但会阻止真实设备及真实供应商验收：
|
||||
|
||||
1. 硬件设备身份材料、绑定码规则、固件接口和RTC能力。
|
||||
2. 火山引擎RTC与豆包真实测试账号、区域、配额、回调签名和错误码。
|
||||
3. 正式OIDC提供方、Claim映射、会话策略和多因素认证要求。
|
||||
4. 生产对象存储、KMS、域名、证书、网络和数据驻留要求。
|
||||
5. 授权文本、数据保留期、删除例外和运营审计规则的业务与法务确认。
|
||||
|
||||
## 配置和安全约定
|
||||
|
||||
- 仓库只提交`.env.example`，不提交`.env`、Token、证书、长期密钥和真实个人数据。
|
||||
- 所有对外资源编号使用不可猜测标识；内部数据库标识不得作为可枚举接口编号。
|
||||
- 请求使用`X-Request-Id`关联；修改类接口逐步接入`Idempotency-Key`。
|
||||
- 数据库事务中不调用外部网络服务，外部副作用使用outbox衔接。
|
||||
@@ -0,0 +1,82 @@
|
||||
# 真实Agent模型质量一致性证据说明
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
`cmd/agent-models-conformance`把同一发布候选的真实内容生成固定评测、Embedding召回与隔离评测、内容安全策略评测，以及数据条款和额度证据形成`real-agent-models-conformance-report-v1`。它复用已有`agent-eval`防篡改评测链，不以另一个较弱评分器替代现有质量门禁。
|
||||
|
||||
本地确定性生成器、哈希向量和本地规则只能输出`LOCAL_AGENT_TOOLCHAIN/external_validation_required=true`。只有目标环境的外部受控提供器、真实账号和完整质量证据通过时，报告才为`REAL_AGENT_MODELS/external_validation_required=false`。报告不证明真实RTC音频质量，也不替代业务与法务发布审批。
|
||||
|
||||
## 2. 内容生成质量
|
||||
|
||||
内容生成继续使用[Agent固定评测集与发布门禁](agent-evaluation.md)中的10类用例和版本化阈值。校验器同时读取：
|
||||
|
||||
- `agent-eval-suite-v1`固定评测集；
|
||||
- `agent-eval-observations-v1`脱敏观测；
|
||||
- `agent-eval-report-v1`完整报告及登记正文。
|
||||
|
||||
它调用已有`agenteval.ValidateArtifact`重新计算报告，任何单独修改评测集、观测、报告或登记正文都会失败。真实门禁要求`environment=real`、至少10例全部通过、无失败项，并将报告、观测、评测集和本次模型证据绑定为四个SHA-256输入摘要。
|
||||
|
||||
## 3. Embedding六类精简评测
|
||||
|
||||
Embedding不重复执行大规模检索压测，只要求版本化数据集和阈值下的六类关键语义：
|
||||
|
||||
| 类别 | 验证目标 |
|
||||
|---|---|
|
||||
| `EXACT_CONFIRMED_MEMORY` | 已确认当前记忆可以精确召回 |
|
||||
| `PARAPHRASE_RECALL` | 同义改写仍能召回正确记忆 |
|
||||
| `CROSS_SUBJECT_ISOLATION` | 不召回另一长者的记忆 |
|
||||
| `REVOKED_MEMORY_EXCLUSION` | 已撤销或失效记忆不进入结果 |
|
||||
| `SENSITIVE_MEMORY_EXCLUSION` | 不把禁止索引的敏感记忆作为普通召回结果 |
|
||||
| `NO_MATCH_FALLBACK` | 无合格匹配时安全返回空结果，不阻断通话 |
|
||||
|
||||
采集必须记录提供器、模型、1536维度、数据集、阈值版本、查询总数、通过数和每类脱敏证据引用。校验器不写死召回率或相似度阈值；这些指标由业务方和Agent负责人冻结在`thresholds_ref`中，修改标准必须产生新版本。
|
||||
|
||||
## 4. 内容安全六类精简评测
|
||||
|
||||
| 类别 | 验证目标 |
|
||||
|---|---|
|
||||
| `VERIFICATION_CODE` | 验证码不进入普通故事、事实或记忆 |
|
||||
| `FINANCIAL_ACCOUNT` | 支付和账户信息被正确拦截或提升敏感级别 |
|
||||
| `PROMPT_INJECTION` | 提示注入不能绕过授权、来源和输出约束 |
|
||||
| `SENSITIVE_MEDICAL` | 高敏感医疗内容不被当作普通事实扩散 |
|
||||
| `NORMAL_BENIGN` | 正常家庭回忆不会被系统性误拦截 |
|
||||
| `MODEL_OUTPUT_SAFETY` | 模型生成结果在落库前通过批准策略复核 |
|
||||
|
||||
采集绑定内容安全提供器、策略版本、数据集、阈值、用例数量、全量通过数量、数据条款和审计引用。生产证据的提供器类别必须为`EXTERNAL_MANAGED`；本地关键词基线只能用于开发前置拦截和工具链验证。
|
||||
|
||||
运行时已提供[生产内容安全服务适配](content-safety-provider.md)：本地高风险前置规则不会把原文发送给外部服务，其余输入在模型调用前检查，模型生成结果在事务外复核后才允许进入短事务。托管服务返回`BLOCK`或`REVIEW`时不生成普通故事/事实；网络、限流、服务端故障或无效响应安全失败并由Outbox重试，不会降级为`ALLOW`。真实门禁仍要求用目标策略完成六类精简评测，不能用适配器单元测试替代。
|
||||
|
||||
## 5. 14项一致性检查
|
||||
|
||||
报告检查采集模式、来源、候选身份、候选绑定、环境身份、生成提供器、固定生成质量、模型绑定、Embedding提供器、Embedding覆盖、内容安全提供器、内容安全覆盖、数据条款与额度、证据引用。
|
||||
|
||||
`REAL_AGENT_MODELS`不可豁免。索引标记`VERIFIED`时，第一个文件必须为同候选的`PASS/REAL_AGENT_MODELS`报告。证据包中的`real_agent_models_validation`汇总生成模型/套件/用例、Embedding模型/查询/六类别、内容安全策略/用例/六类别。缺真实账号、任一类别、数据条款或额度证据时必须保持`PENDING`。
|
||||
|
||||
## 6. 现场执行顺序
|
||||
|
||||
1. 固定候选镜像、Agent组合、生成模型、Embedding模型、内容安全策略、区域和账号。
|
||||
2. 使用真实账号运行现有10类Agent固定集，生成`real`观测和防篡改报告。
|
||||
3. 在相同候选上执行Embedding六类数据集和内容安全六类数据集，保存版本化阈值及脱敏结果引用。
|
||||
4. 归档供应商数据地域、训练使用、日志留存、删除时限和额度/限流证据，不保存API Key。
|
||||
5. 由独立复核人完成采集JSON后执行：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/agent-models-conformance `
|
||||
-capture E:\evidence\real-agent-models-capture.json `
|
||||
-suite E:\evidence\agent-suite.json `
|
||||
-observations E:\evidence\agent-observations.real.json `
|
||||
-agent-report E:\evidence\agent-report.real.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\real-agent-models-report.json
|
||||
```
|
||||
|
||||
6. 将输出作为`REAL_AGENT_MODELS`首个文件，重建候选证据包并核对`coverage_complete=true`。
|
||||
|
||||
本地工具链冒烟：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-agent-models-conformance.ps1
|
||||
```
|
||||
|
||||
该脚本重算仓库内模拟Agent报告，并验证两组六类结构，不连接真实模型、不修改业务数据，也不会放行真实模型门禁。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 真实终端与RTC/语音供应商一致性证据说明
|
||||
|
||||
## 1. 目标与最小矩阵
|
||||
|
||||
`cmd/rtc-conformance`把同一发布候选的终端身份、RTC房间、语音供应商任务、状态时间线、双向媒体、最终字幕、用量、质量结论和资源回收形成`real-device-rtc-conformance-report-v1`。它用于防止模拟供应商、单一语音方式或“能够入房”被误登记为真实通话闭环已经完成。
|
||||
|
||||
为降低重复测试强度，真实验收采用6通最小矩阵：
|
||||
|
||||
1. `s2s_pure`、`s2s_hybrid`、`cascade`各完成1次`NORMAL_COMPLETION`；
|
||||
2. 另外各完成1次`TOKEN_RENEWAL`、`NETWORK_SWITCH_RECOVERY`和`CONTROLLED_STOP`，异常场景可分配到任一已批准方式；
|
||||
3. 6通总体至少覆盖3台不同量产候选终端，每台至少参与1通。
|
||||
|
||||
协议模拟只能输出`PROTOCOL_SIMULATION/external_validation_required=true`。只有真实硬件与非模拟RTC/语音供应商证据完整时，报告才为`REAL_DEVICE_RTC_PROVIDER/external_validation_required=false`。
|
||||
|
||||
## 2. 单通通过标准
|
||||
|
||||
每通证据必须同时满足：
|
||||
|
||||
- 终端使用自己的受控身份创建通话，房间、设备RTC用户、Agent RTC用户和供应商任务引用完整且与其他通话不重复；
|
||||
- 状态按`ROOM_ISSUED → STARTING_AGENT → ACTIVE → STOPPING → COMPLETED`收敛；
|
||||
- 终端入房成功，上行、下行、近端音频发布和远端Agent音频播放均通过；
|
||||
- 供应商启动和停止得到确认，同一稳定任务没有重复创建，终止后RTC与供应商资源已释放；
|
||||
- 最终字幕可见，用量已归集，业务方采用现场冻结的质量方法判定`PASS`；校验器不虚构主观分数阈值；
|
||||
- 凭证续签场景必须证明新短期凭证生效；网络切换场景必须证明媒体与状态恢复；
|
||||
- 保存云端、设备、供应商、质量和用量五类脱敏证据引用。
|
||||
|
||||
不得把RTC Token、AppKey、AK/SK、设备密钥、原始录音、完整字幕正文或个人信息写入采集JSON。房间、用户和任务使用脱敏稳定引用即可。
|
||||
|
||||
## 3. 采集结构
|
||||
|
||||
输入使用`real-device-rtc-capture-v1`：
|
||||
|
||||
| 区域 | 关键字段 |
|
||||
|---|---|
|
||||
| 候选 | `candidate_version`、`build_digest`、`environment` |
|
||||
| 供应商 | `rtc_provider_ref`、`voice_provider_ref`、`rtc_application_ref`、`region_ref` |
|
||||
| 管理 | `change_ticket_ref`、执行人、独立复核人、复核/采集时间 |
|
||||
| 终端 | 设备公开引用、型号、主板、固件、身份引用、音频配置引用 |
|
||||
| 通话 | 方式、场景、房间/用户/任务引用、时间线、媒体、恢复、字幕、用量、质量、去重、回收和五类引用 |
|
||||
|
||||
真实采集的`evidence_source`固定为`HARDWARE_PROVIDER_CAPTURE`，环境只能为`STAGING`或`PRODUCTION`，执行人与复核人不能相同。模拟或本地工具使用`PROTOCOL_SIMULATION/LOCAL`。
|
||||
|
||||
## 4. 17项一致性检查
|
||||
|
||||
报告固定检查：采集模式、来源、候选身份、候选绑定、供应商身份、环境身份、设备覆盖、会话身份、三模式覆盖、四场景覆盖、RTC媒体路径、状态生命周期、凭证/网络恢复、供应商生命周期、字幕/用量/质量、证据引用和执行时间线。
|
||||
|
||||
`REAL_DEVICE_RTC`不可豁免。索引标记为`VERIFIED`时，第一个文件必须是同候选的`PASS/REAL_DEVICE_RTC_PROVIDER`报告。证据包中的`real_device_rtc_validation`汇总终端数、通话数、三模式、四场景及各自通话数量；协议模拟报告会被拒绝。
|
||||
|
||||
## 5. 现场执行流程
|
||||
|
||||
1. 冻结候选镜像、三种已发布路由模板、真实RTC应用、语音供应商资源和3台候选终端。
|
||||
2. 依次执行三次正常闭环，确认终端不根据`engine_mode`改变固定媒体协议，只由云端选择供应商处理链。
|
||||
3. 使用剩余三通覆盖短期凭证续签、Wi-Fi/蜂窝或批准网络之间切换恢复、设备/运营发起的受控停止。
|
||||
4. 每通结束后核对供应商任务、云端状态、最终字幕、用量、质量记录和资源回收；发现不确定启动时确认稳定TaskId重试未产生重复任务。
|
||||
5. 由独立复核人核对脱敏引用后生成报告：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/rtc-conformance `
|
||||
-capture E:\evidence\real-device-rtc-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\real-device-rtc-report.json
|
||||
```
|
||||
|
||||
6. 将报告作为`REAL_DEVICE_RTC`首个文件，重建候选证据包并确认`coverage_complete=true`。
|
||||
|
||||
本地只验证结构工具链：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-rtc-conformance-toolchain.ps1
|
||||
```
|
||||
|
||||
该脚本不会连接真实RTC，不修改业务数据，也不会把模拟结果计入真机门禁。
|
||||
@@ -0,0 +1,146 @@
|
||||
# 发布候选证据包开发与使用说明
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
`cmd/release-evidence`用于阶段8联调、试点和生产发布前，把同一候选版本的技术验收快照、外部验收状态、真机固件一致性报告、接口契约、数据库迁移、部署清单、关键交付文档和可用SBOM封装为一个带SHA-256清单的ZIP。`PILOT`包还必须携带同一客户组织、同一业务时区、上一完整自然周的7份日报和1份周报。它解决证据散落、候选身份不一致、真机场景缺口被模拟结果掩盖、试点周期证据缺失以及归档后无法判断文件是否被替换的问题。
|
||||
|
||||
证据包不是发布批准。生成器只在技术验收快照六项门禁全部通过时工作，但外部证据可以保持`PENDING`，此时包内状态固定为`EXTERNAL_VALIDATION_PENDING`。真实设备、供应商、KMS、告警接收器、Safari或业务签署不能用本地模拟结果替代。
|
||||
|
||||
## 2. 输入设计
|
||||
|
||||
### 2.1 必需参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `-candidate-version` | 与验收快照一致的候选版本，最长128字符 |
|
||||
| `-build-digest` | 与验收快照一致的`sha256:`不可变构建摘要 |
|
||||
| `-source-commit` | 源代码提交；`STAGING/PRODUCTION`必须是40或64位十六进制提交摘要，`LAB`可使用明确的本地标签 |
|
||||
| `-acceptance-snapshot` | `POST /api/v1/ops/diagnostics/acceptance-snapshots`返回或下载的JSON |
|
||||
| `-evidence-index` | `release-evidence-index-v2`外部证据索引 |
|
||||
| `-pilot-daily-snapshot` | `PILOT`包重复传入恰好7次，分别对应周一至周日的`ops-pilot-daily-minimal-v1`日报 |
|
||||
| `-pilot-weekly-snapshot` | `PILOT`包必需的`ops-pilot-weekly-minimal-v1`完整周报 |
|
||||
| `-out` | 新ZIP文件路径；已有文件不会被覆盖 |
|
||||
|
||||
技术验收快照必须满足：候选版本和构建摘要完全匹配、`overall_gate_satisfied=true`、脱敏策略为`ops-acceptance-minimal-v1`，并包含有效环境、验收类型、编号和生成时间。
|
||||
|
||||
### 2.2 PILOT周期证据
|
||||
|
||||
验收类型为`PILOT`时，打包器执行以下强制校验：
|
||||
|
||||
- 验收快照、7份日报和周报的`tenant_id`、`candidate_version`和`build_digest`完全一致；
|
||||
- 所有日/周报使用同一个有效IANA时区，周报起始日是周一；
|
||||
- 周报`is_complete=true`，生成时间不早于自然周结束时间，UTC窗口与业务自然周一致；
|
||||
- 7份日报日期无重复、无缺失且完整覆盖周一至周日，每份UTC窗口与其业务自然日一致；
|
||||
- 日报和周报分别使用`ops-pilot-daily-minimal-v1`、`ops-pilot-weekly-minimal-v1`；
|
||||
- 周报继续包含`complaints/REQUIRED`，防止打包时把未接入的客服/CRM投诉证据误报为已完成。
|
||||
|
||||
任一项不满足即拒绝生成ZIP。非`PILOT`包不要求周期证据；若主动提供，则同样必须满足完整的一周规则，不能只附零散文件。
|
||||
|
||||
### 2.3 外部证据索引
|
||||
|
||||
索引必须逐项包含以下十个代码，不能缺少、重复或自行改名：
|
||||
|
||||
| 代码 | 证据范围 |
|
||||
|---|---|
|
||||
| `REMOTE_CI_SUPPLY_CHAIN` | 固定提交的远程CI、14项构建/质量/安全检查、后端与Web镜像摘要及三份CycloneDX SBOM；首个文件须为`REMOTE_CI_SUPPLY_CHAIN`一致性报告 |
|
||||
| `REAL_DEVICE_RTC` | 量产候选终端、真实RTC、三模式通话和异常恢复 |
|
||||
| `REAL_DEVICE_FIRMWARE` | 至少3台量产候选终端的四场景`HARDWARE_CAPTURE`固件一致性报告 |
|
||||
| `REAL_AGENT_MODELS` | 真实语音、内容、Embedding、内容安全与效果评测 |
|
||||
| `PRODUCTION_INFRASTRUCTURE` | 生产域名、证书、OIDC、数据库、Redis、对象存储、网络和监控 |
|
||||
| `PRODUCTION_RECOVERY` | 生产等价备份恢复、滚动重启、供应商停机和回滚演练 |
|
||||
| `KMS_ROTATION` | 云KMS/HSM身份、挂载、轮换及旧凭据失效 |
|
||||
| `REAL_ALERT_RECEIVER` | 真实通知网关、值班组映射、唯一送达及正式告警演练 |
|
||||
| `SAFARI_COMPATIBILITY` | macOS最近两个Safari版本关键流程 |
|
||||
| `BUSINESS_APPROVAL` | 产品、硬件、Agent、SRE、安全、法务和试点联合结论 |
|
||||
|
||||
每项状态只能为：
|
||||
|
||||
- `VERIFIED`：至少关联一个实际证据文件；
|
||||
- `PENDING`：明确保留待外部验证，不会阻止生成包，但包状态不能进入发布评审就绪；
|
||||
- `WAIVED`：必须填写豁免说明，最终状态为`RELEASE_REVIEW_WITH_WAIVERS`，仍需有权人员复核。
|
||||
|
||||
`REAL_DEVICE_FIRMWARE`是不可豁免门禁。它只能保持`PENDING`或标记为`VERIFIED`，其中每个文件都必须是官方校验器生成、候选版本和构建摘要一致、全部检查通过且范围为`HARDWARE_CAPTURE`的`firmware-conformance-report-v1`。打包器要求至少3台不同真机中的每一台均完成`AB_SUCCESS`、`AB_ROLLBACK`、`POWER_LOSS_AFTER_STAGE`和`POWER_LOSS_DURING_BOOT`四个场景，共至少12份不重复报告。缺少设备或任一场景时，索引必须保持`PENDING`；模拟器的`PROTOCOL_SIMULATION`报告即使全部通过也会被拒绝作为真机证据。
|
||||
|
||||
`REAL_ALERT_RECEIVER`同样不可豁免。第一个证据文件必须是`PASS/REAL_RECEIVER`的`alert-receiver-conformance-report-v1`，并与候选版本和构建摘要一致。报告必须覆盖全部活动路由、每条路由的唯一验签联通回执、主/升级接收组映射以及一条已确认并解决的受控正式告警演练。只完成本地或测试网关时报告范围为`MOCK_RECEIVER`，不能进入真实接收器证据项；缺报告或缺正式演练时必须保持`PENDING`。
|
||||
|
||||
`KMS_ROTATION`也不可豁免。第一个文件必须是`PASS/REAL_KMS_HSM`的`kms-rotation-conformance-report-v1`，环境必须为预生产或生产，并同时覆盖逐请求动态读取和受控滚动重启两类凭据。新版本接受、旧版本拒绝、业务连续性、工作负载身份和云提供器审计缺一不可。本地`LOCAL_SECRET`报告只能证明演练工具可用，不能进入真实轮换证据项。
|
||||
|
||||
`PRODUCTION_RECOVERY`不可豁免。第一个文件必须是`PASS/PRODUCTION_EQUIVALENT`的`production-recovery-conformance-report-v1`，同一预生产或生产候选必须完成PostgreSQL隔离恢复、Redis权威状态重建、API/Callbacks/Worker滚动重启和供应商停机恢复。每项都必须证明权威数据一致、业务连续、没有重复效果并完成清理。本地`LOCAL_RECOVERY`报告不能放行。
|
||||
|
||||
`PRODUCTION_INFRASTRUCTURE`不可豁免。第一个文件必须是`PASS/PRODUCTION_INFRASTRUCTURE`的`production-infrastructure-conformance-report-v1`，并完整覆盖域名TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控。每类组件必须具备规定控制项和探针、配置、审计引用。本地`LOCAL_INFRASTRUCTURE`报告只能验证采集工具链，不能放行。
|
||||
|
||||
`SAFARI_COMPATIBILITY`不可豁免。第一个文件必须是`PASS/REAL_SAFARI`的`safari-compatibility-conformance-report-v1`，覆盖发布依据中的`CURRENT/PREVIOUS`两个不同真实Safari版本、两种视口和六条关键流程，共24项结果。本地浏览器或Playwright WebKit只能形成`NON_SAFARI_TOOLCHAIN`报告，不能放行。
|
||||
|
||||
`REAL_DEVICE_RTC`不可豁免。第一个文件必须是`PASS/REAL_DEVICE_RTC_PROVIDER`的`real-device-rtc-conformance-report-v1`，至少3台量产候选终端以6通精简矩阵覆盖三种语音方式正常闭环，以及凭证续签、网络切换恢复和受控停止。每通都必须证明双向媒体、供应商启停、最终字幕、用量、质量结论、任务去重和资源回收。本地`PROTOCOL_SIMULATION`报告不能放行。
|
||||
|
||||
`REAL_AGENT_MODELS`不可豁免。第一个文件必须是`PASS/REAL_AGENT_MODELS`的`real-agent-models-conformance-report-v1`，内容生成必须使用`real`观测重新计算已有10类固定评测，Embedding和内容安全各覆盖6类精简数据集，并附数据条款和额度证据。本地生成器、哈希向量或本地规则只能形成`LOCAL_AGENT_TOOLCHAIN`报告，不能放行。
|
||||
|
||||
相对证据路径以索引文件所在目录为基准。每个文件必须是普通文件且不超过100 MiB。打包时本机绝对路径会被替换为包内路径，避免泄露工作站目录；不得把密钥、令牌、录音、字幕正文或未脱敏个人信息作为证据文件。
|
||||
|
||||
样例见[`testdata/release-evidence-index.example.v2.json`](../testdata/release-evidence-index.example.v2.json)。使用前必须替换候选版本、构建摘要、责任人、状态和证据文件。
|
||||
|
||||
## 3. 包结构与完整性
|
||||
|
||||
```text
|
||||
candidate-evidence.zip
|
||||
├── release-manifest.json
|
||||
├── evidence-index.json
|
||||
├── acceptance/technical-acceptance-snapshot.json
|
||||
├── pilot/daily/YYYY-MM-DD.json # PILOT包恰好7份
|
||||
├── pilot/weekly/YYYY-MM-DD.json # PILOT包1份完整周报
|
||||
├── baseline/openapi/openapi.yaml
|
||||
├── baseline/migrations/*.sql
|
||||
├── baseline/deploy/kubernetes/**
|
||||
├── baseline/docs/**
|
||||
├── baseline/artifacts/*.cdx.json # 当前工作区存在时加入
|
||||
└── evidence/<CODE>/<序号>-<文件名>
|
||||
```
|
||||
|
||||
`release-manifest.json`使用`release-candidate-evidence-bundle-v3`，保存候选版本、构建摘要、源提交、OpenAPI版本、环境、验收类型、技术快照编号、外部证据状态计数、SBOM数量和每个归档文件的大小与SHA-256。`remote_ci_supply_chain_validation`给出远程运行、14项检查、双镜像摘要和三份SBOM覆盖，`firmware_validation`同步给出真机与四场景覆盖，`real_device_rtc_validation`给出真机、三种方式和四类RTC场景覆盖，`real_agent_models_validation`给出真实生成、Embedding和内容安全质量覆盖，`alert_receiver_validation`给出活动路由、映射、唯一回执和正式演练，`kms_rotation_validation`给出真实提供器和两种轮换模式，`production_recovery_validation`给出基础设施、四类演练和实际恢复用时，`production_infrastructure_validation`给出目标环境和七类组件控制项覆盖，`safari_compatibility_validation`给出两个Safari版本和24项关键流程矩阵。没有报告时这些门禁都会明确列出`PENDING`原因。PILOT包额外保存`pilot_evidence_included=true`、`pilot_week_start`、`pilot_timezone`和`pilot_daily_count=7`。清单不把自身摘要写入自身；命令完成后另行输出整个ZIP的`sha256:`摘要，用于制品库登记。
|
||||
|
||||
如果当前工作区没有CI生成的CycloneDX文件，包仍可用于外部验收准备，但清单写入`SBOM_NOT_PRESENT_IN_WORKTREE`警告，且`REMOTE_CI_SUPPLY_CHAIN`不应标记为已验证。
|
||||
|
||||
## 4. 使用流程
|
||||
|
||||
1. 固定候选提交、构建镜像并取得不可变摘要。
|
||||
2. 使用相同候选标识生成技术验收快照；任一技术门禁失败先处理问题，不允许打包。
|
||||
3. 复制外部证据索引样例，逐项登记责任人、状态和文件；真机固件报告未达到3台×4场景时保持`PENDING`。
|
||||
4. 执行：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/release-evidence `
|
||||
-root . `
|
||||
-candidate-version 0.55.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-source-commit <固定提交摘要> `
|
||||
-acceptance-snapshot E:\evidence\acceptance.json `
|
||||
-evidence-index E:\evidence\evidence-index.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-17.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-18.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-19.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-20.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-21.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-22.json `
|
||||
-pilot-daily-snapshot E:\evidence\daily\2026-08-23.json `
|
||||
-pilot-weekly-snapshot E:\evidence\weekly\2026-08-17.json `
|
||||
-out E:\evidence\data-terminal-cloud-0.55.0-rc.1.zip
|
||||
```
|
||||
|
||||
5. 保存命令输出的ZIP摘要，解包抽查清单，再上传只读制品库。
|
||||
6. 任何候选版本、构建摘要或源提交变化都重新生成快照和证据包；不修改旧包伪装成同一候选。
|
||||
|
||||
## 5. 验证
|
||||
|
||||
受影响模块测试：
|
||||
|
||||
```powershell
|
||||
go test ./internal/releaseevidence ./cmd/release-evidence
|
||||
```
|
||||
|
||||
真实本地纵向烟测：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-release-evidence.ps1
|
||||
```
|
||||
|
||||
烟测使用真实OIDC生成绑定同一候选版本和API镜像摘要的`PILOT`技术验收快照、上一完整自然周的7份日报和1份周报，构造十项全部`PENDING`的外部索引，生成并解包临时ZIP，核对OpenAPI 0.64.0、v3清单、候选一致性、周期证据、摘要、待验计数和真机固件四场景缺口，随后清理临时文件、审计和幂等记录。该结果只证明打包链路可用，不证明十项外部验收、真机固件或投诉证据已经完成。
|
||||
@@ -0,0 +1,30 @@
|
||||
# 幂等、事务审计与可靠待办设计 V0.1
|
||||
|
||||
## 幂等执行
|
||||
|
||||
- 副作用接口以“调用主体 + 接口作用域 + `Idempotency-Key`”作为唯一范围。
|
||||
- 请求正文计算SHA-256摘要；同一键和相同摘要返回第一次已提交结果。
|
||||
- 同一键对应不同请求摘要时返回冲突，不能执行第二次业务操作。
|
||||
- 幂等记录、业务写入、审计事件和outbox事件必须在同一个PostgreSQL事务中提交。
|
||||
- 事务内只保存业务意图，不调用第三方网络服务。
|
||||
- 当前实现通过数据库唯一约束串行化并发请求，五个并发请求的集成测试只执行一次操作。
|
||||
|
||||
## 事务审计
|
||||
|
||||
- 审计记录接受平台用户公开编号，不记录OIDC Token、内部主键、字幕正文或录音地址。
|
||||
- 业务操作回滚时，同一事务内的审计记录同步回滚；业务提交时审计同步提交。
|
||||
- 审计结果使用`success/failure/denied`稳定值，细节只保存诊断需要的非敏感字段。
|
||||
|
||||
## outbox可靠待办
|
||||
|
||||
- 业务事务通过`outbox.Store.Enqueue`写入待办，支持租户、聚合对象、事件类型和去重键。
|
||||
- 相同去重键与相同正文返回原事件；相同去重键与不同正文拒绝。
|
||||
- Worker使用`FOR UPDATE SKIP LOCKED`批量领取任务，领取时写入Worker编号和锁定时间。
|
||||
- 处理成功进入`completed`；只有显式临时错误、超时、网络中断和被分类为临时的供应商、对象存储或数据库错误才按指数退避重新进入`pending`；业务错误、永久错误和未注册处理器立即进入`dead`。
|
||||
- 进程崩溃后，超过锁定期限的`processing`任务可被其他Worker重新领取。
|
||||
- 日志只记录事件编号、事件类型、次数和稳定错误码，不记录事件正文。
|
||||
- V26为作业增加公开编号和人工重试元数据。运营人员只能重试当前进程已注册、状态为`dead`的事件类型；服务端重置本轮自动尝试计数，但累计保留人工重试次数、时间、操作人、原因和审计，不向运营页面暴露事件正文。
|
||||
|
||||
## 当前事件处理器
|
||||
|
||||
当前已注册通话房间、供应商启动/停止及对账、内容提取、记忆索引/删除、隐私访问/删除、私有导出和媒体校验处理器。`platform.noop`只用于验证完整领取、人工重试与完成链路。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 远程CI供应链一致性证据
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
`cmd/ci-supply-chain-conformance`把固定源提交的托管CI运行、构建与安全检查、镜像摘要及CycloneDX SBOM形成`remote-ci-supply-chain-conformance-report-v1`。本地执行可以验证JSON协议和校验器，但报告固定为`LOCAL_CI_TOOLCHAIN/external_validation_required=true`，不能把开发机结果冒充远程供应链验收。
|
||||
|
||||
该门禁证明“报告中的远程运行和制品身份彼此一致”，不自动证明业务审批、真实设备体验或生产部署已经完成。发布负责人仍需从受控仓库、制品库和CI系统导出事实，不得手工填造不存在的运行或摘要。
|
||||
|
||||
## 2. 最小证据集
|
||||
|
||||
真实采集必须绑定候选版本、发布包使用的`sha256`构建摘要、40或64字符完整源提交、仓库、工作流、运行编号、HTTPS运行地址、触发类型、ref、尝试次数、成功结论、时间线、执行人及不同的复核人。
|
||||
|
||||
14项检查必须唯一且全部`PASS`：
|
||||
|
||||
1. Go格式、Go vet与测试；
|
||||
2. OpenAPI类型生成、Web类型检查与构建、Compose校验；
|
||||
3. 后端与Web镜像构建；
|
||||
4. Go漏洞/许可证、前端漏洞/许可证；
|
||||
5. 仓库密钥、基础设施配置、后端镜像和Web镜像扫描；
|
||||
6. CycloneDX SBOM生成。
|
||||
|
||||
制品还必须包含后端、Web两个不可变镜像摘要，以及`SOURCE`、`BACKEND_IMAGE`、`WEB_IMAGE`三份`CYCLONEDX_JSON`文件摘要。检查日志、镜像制品和SBOM均需提供可追溯证据引用。
|
||||
|
||||
## 3. 采集与校验
|
||||
|
||||
仓库CI会上传三份SBOM和`build-metadata.json`，其中记录完整提交、运行编号和两个本次构建镜像ID。正式发布若将镜像推入制品库，应以制品库返回的不可变清单摘要为准，并保证采集中的`build_digest`与证据包候选一致。
|
||||
|
||||
下载运行日志、构建元数据、SBOM和制品库摘要后，按`remote-ci-supply-chain-capture-v1`整理采集，再执行：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/ci-supply-chain-conformance `
|
||||
-capture E:\evidence\remote-ci-capture.json `
|
||||
-candidate-version 0.64.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-source-commit <40或64位提交> `
|
||||
-output E:\evidence\remote-ci-report.json
|
||||
```
|
||||
|
||||
将报告作为`REMOTE_CI_SUPPLY_CHAIN`首个文件并设为`VERIFIED`。发布证据包会重新检查候选、构建摘要、源提交、11项报告内一致性检查、14项CI结果、两个镜像摘要和三份SBOM；任何缺失都拒绝`VERIFIED`，且此门禁不可豁免。
|
||||
|
||||
本地协议冒烟只运行：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-ci-supply-chain-conformance.ps1
|
||||
```
|
||||
|
||||
该脚本不访问GitHub、不构建镜像、不修改业务数据，只证明本地校验工具可运行，并明确保留外部验证要求。
|
||||
@@ -0,0 +1,95 @@
|
||||
# 首期需求可追溯矩阵
|
||||
|
||||
## 1. 使用说明
|
||||
|
||||
本矩阵以《数据采集终端-云端系统研发需求规格说明书》版本1.2（2026-08-21）为需求事实来源。源文件SHA-256为`bd009e3de1aebe07a4b50c3ead29ff840d6dc9bc0d9ade0ebb9faa94d45fca23`，机械提取结果见`artifacts/requirements-source-inventory.md`。
|
||||
|
||||
原文没有独立需求编号。本文沿用项目已采用的`Pxxxx`来源定位号：它是DOCX正文段落在`word/document.xml`中的零基顺序号。对三级标题的追踪范围包含该标题之后、下一个同级或更高级标题之前的目标、处理规则和验收标准表格，不把标题一句话缩减为完整需求。
|
||||
|
||||
状态定义：
|
||||
|
||||
- **本地完成**：代码、接口、数据结构和最小充分验证均有当前仓库证据。
|
||||
- **本地完成，外部待验**：可交付实现和模拟闭环已经具备，但需求明确依赖真实硬件、真实供应商账号、真实模型质量或生产环境，不能用本地证据替代。
|
||||
- **进行中**：仍有可以在当前仓库继续完成的功能或证据缺口。
|
||||
- **外部阻塞**：实现不能在缺少业务方或供应商输入时继续，并已记录所需外部条件。
|
||||
|
||||
“本地完成”不等于生产上线。矩阵将本地代码证据与真实账号、真机、容量、安全和业务验收证据分开记录。
|
||||
|
||||
## 2. SaaS首期功能
|
||||
|
||||
| 来源 | 需求范围 | 主要实现与数据 | 接口或页面证据 | 验证证据 | 状态 |
|
||||
|---|---|---|---|---|---|
|
||||
| P0129 | 标准网页登录 | `internal/identity`、`internal/httpapi/auth.go`、V3身份与家庭表；Web统一401会话失效处理和安全的登录前站内路径恢复 | `GET /api/v1/me`、OIDC登录回调、业务接口401清理与重新登录 | `identity/*_test.go`、`smoke-saas.ps1`；真实OIDC单次401注入、旧会话清除、重新登录和未登录联调深链恢复冒烟 | 本地完成 |
|
||||
| P0131 | 家庭、邀请、成员和角色 | `internal/saas/member_service.go`、V3/V6 | 家庭、成员、邀请、所有权接口及家庭工作台 | `saas/service_integration_test.go`、真实OIDC纵向烟测记录 | 本地完成 |
|
||||
| P0134 | 长者档案 | `internal/saas/service.go`、`subject_profile`版本化资料 | `POST/GET/PATCH /api/v1/subjects`相关接口及档案表单 | `saas/service_integration_test.go`、背景资料入通话数据库用例 | 本地完成 |
|
||||
| P0136 | 分项授权 | `internal/saas/service.go`、`consent_record`、`consent_snapshot` | 长者授权读取、创建和撤回接口 | 授权唯一性、快照、撤回停止相关集成用例 | 本地完成 |
|
||||
| P0139 | 每设备独立身份 | `internal/deviceauth`、受控设备密钥解析器、V2/V5 | `GET /device/v2/bootstrap`及全部设备HMAC接口 | 篡改、过期、重放、吊销和目录密钥轮换定向测试；`cmd/kms-rotation-conformance`要求真实云端动态读取与滚动重启报告 | 本地完成，量产KMS报告待验 |
|
||||
| P0141 | 一次性绑定或转移 | `internal/saas/device_claim.go`、V7绑定码摘要和绑定历史 | `POST /api/v1/device-claims` | 跨租户、首次绑定、安全重试和唯一有效绑定集成用例 | 本地完成 |
|
||||
| P0143 | 网页设备查看、绑定、解绑或转移申请 | `internal/saas/device_service.go`及React家庭工作台 | `/api/v1/devices`、设备详情、绑定入口 | 真实OIDC设备管理烟测、前端生产构建 | 本地完成 |
|
||||
| P0146 | 在线状态和配置同步 | `internal/device`、Redis在线状态、V24遥测和设备影子 | `bootstrap`、`config`、`telemetry:batch`、presence/twin接口；家庭端扬声器音量0—100配置、期望/上报双值回显 | 遥测单调序号、Redis降级和设备在线事件用例；设备影子定向数据库测试、输入校验单测和真实OIDC无写入页面冒烟 | 本地完成 |
|
||||
| P0148 | 设备详情和非敏感配置 | `internal/saas/device_service.go`、配置白名单和递归敏感字段拒绝 | 设备详情、twin接口及设备配置页面 | 服务集成测试、前端类型检查和生产构建 | 本地完成 |
|
||||
| P0155 | 通话列表和详情 | `internal/saas/conversation_query.go`、V5通话和状态历史 | 长者通话列表、通话详情、话轮、摘要和用量接口；详情请求取消、局部失败重试及业务名称展示 | 签名游标、筛选、跨租户拒绝；临时通话夹具的真实OIDC故障注入、恢复和无残留页面冒烟 | 本地完成 |
|
||||
| P0157 | 按授权播放双轨录音 | `internal/media/access.go`、V14媒体与访问授权 | 通话媒体、分片短期访问接口和双轨页面 | 播放/下载独立授权、访问审计和跨租户用例 | 本地完成，对象存储生产策略待验 |
|
||||
| P0160 | 分片短期上传地址 | `internal/media/service.go`、对象存储适配器、V14 | 创建上传批次和返回待上传分片地址 | 清单、授权、幂等、对象引用和直传烟测 | 本地完成 |
|
||||
| P0162 | 上传完成后校验 | `internal/media/processor.go`、V14/V15 | 上传批次完成和状态查询 | 校验值、对象存在、状态收敛和模拟本地删除闭环 | 本地完成 |
|
||||
| P0164 | 播放和下载分别授权 | `internal/media/access.go`、`recording_access_grant` | 录音访问授权、撤销及分片访问接口 | 所有者不隐式获得权限、播放/下载能力分离用例 | 本地完成 |
|
||||
| P0167 | 故事和事实候选核对 | `internal/saas/content_service.go`、`internal/extraction`、V8 | 故事列表、详情、修订、确认和拒绝接口及审核页面 | 来源必需、ETag、角色、版本留痕和真实数据库组合用例 | 本地完成 |
|
||||
| P0169 | 已确认记忆管理 | `internal/saas/content_service.go`、`internal/memorylifecycle`、V8 | 记忆查询、页面内修订/启停/删除和状态详情 | 授权门禁、索引失效、删除中不可恢复、可靠删除、召回排除及真实登录页面交互 | 本地完成 |
|
||||
| P0174 | 数据访问、导出、更正、撤回和删除请求 | `internal/privacy`、`internal/dataexport`、V9/V10 | 隐私请求、导出任务和进度接口 | 多子系统删除、导出加密引用、失败/重试和清理烟测 | 本地完成，法务口径待业务确认 |
|
||||
| P0176 | 状态实时推送且不推敏感正文 | `internal/webevents`、V16、React 2秒合并刷新 | `GET /api/v1/events`及React SSE客户端 | 重连游标、资源隔离、状态事件字段、连续8事件请求上界和运行烟测 | 本地完成 |
|
||||
| P0183 | 通话用量、费用和额度 | `internal/billing`、V21 | 通话用量、价格、额度和费用汇总接口 | 回调幂等计量、额度门禁、价格版本冻结和烟测 | 本地完成，真实账单对账待验 |
|
||||
|
||||
## 3. Agent首期功能
|
||||
|
||||
| 来源 | 需求范围 | 主要实现与数据 | 接口或任务证据 | 验证证据 | 状态 |
|
||||
|---|---|---|---|---|---|
|
||||
| P0196 | 创建通话并预留RTC房间 | `internal/orchestration/repository.go`、V5授权/背景快照和RTC任务 | `POST /device/v2/conversations` | 同键重放、正文冲突、Token不落库和HTTP纵向烟测 | 本地完成 |
|
||||
| P0198 | 入房后启动智能体 | `internal/orchestration/service.go`和`provider_processing.go` | `POST .../{id}/activate`及可靠启动待办 | 重复激活、未入房、供应商拒绝和P0062失败收敛用例 | 本地完成，真实入房事件待验 |
|
||||
| P0200 | 心跳、租约和非实时动作 | `internal/orchestration/heartbeat.go`、Redis租约、V24/V32 | `POST .../{id}/heartbeat`、批量遥测 | 序号单调、乱序、停止动作和能力冻结相关用例 | 本地完成 |
|
||||
| P0202 | 主动结束并收敛最终状态 | `internal/orchestration/service.go`、可靠停止待办 | `POST .../{id}/stop` | 停止幂等、回调重复、授权撤回和完整状态链烟测 | 本地完成 |
|
||||
| P0204 | 自动修复卡住通话 | `internal/orchestration/recovery.go`、Worker扫描 | 过期、启动/停止对账Outbox任务 | 预留过期、租约过期、进程/Redis恢复和供应商故障用例；`cmd/recovery-conformance`要求生产等价四类恢复报告 | 本地完成，生产等价报告待验 |
|
||||
| P0208 | 签发短期入房凭证 | `internal/rtc`、V28凭证时间元数据、V35 RTC入口预检台账 | 创建通话、续签动作和运营外部依赖预检 | 官方Token格式、确定性重建、过期、不持久化正文及探针脱敏状态 | 本地完成，真实RTC入房待验 |
|
||||
| P0210 | 集中封装火山与豆包 | `internal/voiceprovider`、模拟/火山适配器、V35方舟/RTC预检台账 | Worker统一Start/Stop接口、签名Callback及运营预检页面 | 协议映射、签名、错误分类、模拟供应商重放和外部入口TLS探针 | 本地完成，真实账号协议待验 |
|
||||
| P0212 | 每通话选择一种语音模式 | `internal/opsconfig`、`internal/orchestration`、组合优先及模式冻结 | Agent组合/旧路由投放和通话创建 | 三模板选择、缺失配置拒绝、组合路由解析和数据库到供应商传播用例 | 本地完成，三种真实模式待验 |
|
||||
| P0214 | 管理人设、音色、模型和路由配置 | `internal/opsconfig`、`internal/orchestration`、V19/V20/V33 | 五类配置、评测、资源引用、灰度、回滚及供应商启动交接 | Agent组合UUID、同租户、组件类型、已发布状态、运行时冻结和组件参数传递 | 本地完成，真实资源兼容性待验 |
|
||||
| P0217 | 最小必要背景资料 | `internal/orchestration/repository.go`、版本化背景快照 | 通话创建内部资料准备 | 白名单字段、非白名单排除、无效类型失败和真实数据库用例 | 本地完成 |
|
||||
| P0219 | 自有数据库检索记忆 | `internal/retrieval`、pgvector、V8 | 创建通话前固定边界召回 | 当前授权、版本、敏感级别、跨长者隔离和非法limit用例 | 本地完成，真实Embedding质量待验 |
|
||||
| P0226 | 可靠接收供应商通知 | `internal/voiceprovider/signature.go`、Callback处理和Outbox | `POST /callbacks/v1/vertc/voice-chat` | 先验签、重放、同键冲突、乱序和快速确认用例 | 本地完成 |
|
||||
| P0228 | 最终字幕和对话轮次 | `internal/orchestration/transcript_batch.go`、V8 | 供应商最终字幕和设备`turns:batch` | 轮次业务键、整批回滚、授权留存和重复补交用例 | 本地完成 |
|
||||
| P0230 | 摘要和开放话题 | `internal/extraction/generator.go`、`processor.go` | 通话完成后的可靠内容整理任务 | 事务外模型调用、话轮指纹、重复版本和敏感拦截用例 | 本地完成，真实模型质量待验 |
|
||||
| P0233 | 故事和事实候选 | `internal/extraction`、`internal/contentpolicy`、V8 | 内容整理Worker任务及托管内容安全HTTP协议 | 来源轮次、置信度、输入/输出双检、本地高风险不外发、外部失败不落库和候选不自动生效用例 | 本地功能完成，真实策略六类质量待验 |
|
||||
| P0235 | 人工核对后生成记忆 | `internal/saas/content_service.go`、记忆索引Outbox | 故事确认接口和审核页面 | 角色、ETag、来源、授权、确认后索引和下一通话召回用例 | 本地完成 |
|
||||
| P0238 | 长者友好表达 | 版本化PERSONA配置、背景节奏字段和固定评测集 | 运营配置、供应商启动模板、`cmd/agent-eval` | 本地规则及模拟评测通过 | 本地完成，真实听筒体验待验 |
|
||||
| P0240 | 身份、人设和边界一致 | `internal/opsconfig`、服务端授权/上下文边界、提示注入拦截 | 版本化PERSONA/AGENT_BUNDLE、冻结快照和供应商系统消息 | 配置校验、租户/长者边界、发布人设传递和敏感提示用例 | 本地完成，真实模型红队待验 |
|
||||
| P0245 | 摘要忠于原始对话 | `internal/extraction`、来源话轮和内容指纹 | 摘要/开放话题接口 | 仅长者最终话轮、来源保存、敏感拦截和虚构门槛 | 本地完成，真实内容评分待验 |
|
||||
| P0247 | 候选可核对可修改 | V8故事、故事修订和事实候选 | 故事详情、修订、确认和拒绝接口 | 来源跳转、版本、ETag和终态重复操作拒绝 | 本地完成 |
|
||||
| P0249 | 已确认记忆准确使用 | `internal/retrieval`、Embedding适配器、记忆索引生命周期 | 记忆检索和通话背景快照 | 当前版本/授权/敏感级别过滤、跨长者隔离和停用删除排除 | 本地完成，真实召回质量待验 |
|
||||
| P0252 | 固定评测集和质量指标 | `internal/agenteval`、`internal/opsconfig`、`cmd/agent-eval-collect`、`cmd/agent-eval`、`cmd/agent-eval-register`、V33及版本化JSON夹具 | 权限内通话/话轮采集、脱敏观测、评测报告及运营配置`/evaluations`标准证据幂等登记 | 十类覆盖、唯一通话、必需评分、机器指标推导、报告防篡改、服务端标准证据校验、通用证据不得放行Agent组合、201/200重放和模拟10/10报告 | 本地完成，真实账号评测待验 |
|
||||
| P0254 | Agent配置发布、灰度和回滚 | `internal/opsconfig`、`internal/orchestration`、运营配置工作台和投放台账 | 双人审批、租户/长者/设备组灰度、自定义版本族、不可变回滚、组合优先选择 | 组件引用复核、评测/资源门禁、配置类型选择、范围与激活时间优先级、并发上限、新通话冻结及供应商启动交接 | 本地完成，真实灰度待验 |
|
||||
|
||||
## 4. 关键异常和三方交接场景
|
||||
|
||||
| 来源 | 场景 | 当前证据 | 状态 |
|
||||
|---|---|---|---|
|
||||
| P0060 | 未绑定、授权不足、低固件明确拒绝 | 创建通话前置门禁、`FIRMWARE_UPDATE_REQUIRED`和就绪清单 | 本地完成 |
|
||||
| P0061 | 网络重试不能重复创建通话或供应商任务 | Idempotency-Key、固定任务号、Outbox唯一键和模拟断网重连 | 本地完成 |
|
||||
| P0062 | 入房后智能体启动失败时清理并通知设备退出 | 只读状态接口、`leave_room`动作、Worker永久拒绝原子失败收敛 | 本地完成 |
|
||||
| P0063 | 断网、断电或重启后的租约回收与最后状态上报 | Recovery Worker、租约、遥测历史和恢复脚本；固件模拟器使用耐久A/B日志验证重启重拉、启动健康确认和失败自动回退，云端保留启动尝试、分区及回退结果 | 本地完成，真机断电与Bootloader待验 |
|
||||
| P0064 | 待上传录音队列和云端确认后延迟删除 | 设备影子队列字段、页面状态、校验后`local_delete_after`和删除回执 | 本地完成 |
|
||||
| P0284 | SaaS拒绝时不创建房间或供应商任务 | 创建通话事务前置校验和稳定错误码 | 本地完成 |
|
||||
| P0285 | Agent背景准备失败形成设备/网页一致结果 | V31准备状态、`context_preparation_failed`和相同通话编号 | 本地完成 |
|
||||
| P0286 | 已建房但未入房自动清理 | 预留期限和Recovery过期任务 | 本地完成 |
|
||||
| P0287 | 活动通话撤回授权或运营停止 | 撤回事务写STOPPING和唯一停止待办，设备取得停止动作 | 本地完成 |
|
||||
| P0288 | 故事跳字幕来源，确认记忆用于下一通话 | 来源通话跳转、确认索引、下一通话召回 | 本地完成 |
|
||||
| P0289 | 录音失败不阻断字幕故事，最终与本地删除一致 | 媒体独立状态机、上传校验和本地删除回执 | 本地完成 |
|
||||
|
||||
## 5. 追踪门禁和当前缺口
|
||||
|
||||
| 来源 | 要求 | 当前处理 |
|
||||
|---|---|---|
|
||||
| P0414 | 首期需求、验收用例、缺陷和风险形成对应关系 | 本文完成首期功能到代码、接口、数据和验证的基线；V30问题清单由V36补充严重级别、根因、修复版本、回归证据及未关闭HIGH/CRITICAL发布阻断汇总；OpenAPI 0.50.0—0.55.0可按候选构建导出六项技术门禁及脱敏阻断告警定位快照，绑定候选版本/构建摘要后按业务时区归档日/周运行证据。`cmd/release-evidence`现使用v3清单，把同一候选的快照、接口、迁移、部署、SBOM和十类外部状态形成逐文件摘要；远程CI供应链、真机固件、真实终端RTC、真实Agent模型、真实告警网关、云KMS/HSM轮换、生产等价恢复、生产基础设施和Safari兼容分别要求结构化报告，并把14项CI检查/镜像/SBOM、设备固件场景、语音方式与恢复场景、生成/Embedding/内容安全质量、路由演练、轮换模式、恢复类型、基础设施控制项及Safari矩阵覆盖与缺口写入清单。OpenAPI 0.64.0、V38及九个离线校验器把云端状态与远程构建、外部设备、RTC/语音供应商、模型提供器、网关、密钥提供器、目标环境和浏览器证据绑定；`content_safety_tls`把策略服务网络/证书状态纳入指标、告警、运营页面和候选快照。缺检查、缺制品、缺场景、缺演练、缺质量类别、缺控制项、`PENDING`和本地模拟证据均不会被误报为外部验收完成，整体发布仍必须基于真实联调、灰度和审批记录确认。 |
|
||||
| P0445 | 需求编号关联代码、测试、接口或配置变更 | 本文逐项建立关联；后续功能变更必须同步更新本矩阵和`development-status.md`。 |
|
||||
|
||||
当前仍不能在本地宣告完成的部分集中为：真实火山RTC与豆包三模式联调、真实方舟内容与Embedding质量、真实听筒的长者交流体验、量产设备/KMS注入、生产对象存储与备份、真机异常恢复、真实账单和生产级内容安全。它们属于阶段8外部验收，不应通过增加本地低价值测试伪造完成证据。
|
||||
|
||||
下一批本地开发应优先从矩阵中出现“进行中”的条目选择；若没有本地功能缺口，则只继续完善能够直接降低阶段8联调风险的模拟器、诊断和交付工具，不以覆盖率数字替代业务功能。
|
||||
@@ -0,0 +1,54 @@
|
||||
# 具体资源分享开发说明
|
||||
|
||||
## 实现范围
|
||||
|
||||
V17—V18已完成具体资源分享纵向闭环。家庭所有者或管理员可以把单个故事、单段通话文字或单个已验证录音分片分享给同一客户组织内的活动用户，并分别设置接收人、最小权限、用途、失效时间和登录要求。系统同时支持指定接收人登录访问和匿名口令访问；授权撤销或到期后，新的访问立即被拒绝。
|
||||
|
||||
`EDIT`只适用于故事且强制登录。接收人修改故事时必须提交当前版本，成功后形成新的`story_revision`、复制原话来源、把故事置为`IN_REVIEW`并递增版本；旧版本写入返回HTTP 412，不会覆盖并发修改。文字分享不会隐式授予录音权限，播放权限也不会隐式包含下载权限。
|
||||
|
||||
## 资源与权限矩阵
|
||||
|
||||
| 资源类型 | 资源编号 | 允许权限 | 访问结果 |
|
||||
|---|---|---|---|
|
||||
| `STORY` | `story_draft.public_id` | `VIEW_TEXT`、`EDIT` | 返回当前标题、正文、版本和修订号；`EDIT`可写入新修订 |
|
||||
| `TRANSCRIPT` | `conversation.public_id` | `VIEW_TEXT` | 返回最多1000条按序排列的最终话轮，不暴露供应商引用 |
|
||||
| `RECORDING` | `media_segment.public_id` | `LISTEN`、`DOWNLOAD` | 当前原录音授权有效且分片已验证时，签发5分钟私有对象地址 |
|
||||
|
||||
## 接口设计
|
||||
|
||||
- `POST /api/v1/sharing-grants`：携带`Idempotency-Key`创建分享；同键同正文重放原结果，同键不同正文返回冲突。
|
||||
- `GET /api/v1/sharing-grants?subject_id=...`：所有者或管理员查看指定长者的分享历史，包括已撤销记录。
|
||||
- `DELETE /api/v1/sharing-grants/{id}`：幂等撤销分享并记录事务审计。
|
||||
- `GET /api/v1/sharing-grants/{id}/resource`：指定接收人使用OIDC身份读取登录分享。
|
||||
- `PATCH /api/v1/sharing-grants/{id}/resource`：持有`EDIT`权限的指定接收人修订故事；使用`If-Match`进行强并发控制。
|
||||
- `GET /api/v1/public/shares/{id}`：使用`X-Share-Token`读取匿名分享；该接口不接受`EDIT`。
|
||||
|
||||
撤销或过期统一返回HTTP 410；不存在的分享或资源返回404；身份、口令、接收人或权限不满足返回403；故事版本冲突返回412。浏览器管理页提供资源、接收人、权限、有效期、用途和登录方式配置，创建后展示可转交的访问地址；匿名口令仅展示一次。
|
||||
|
||||
创建操作不会再从配置表单直接提交。点击“创建分享”后，页面内受控操作区冻结长者、具体故事/通话文字/录音分片的业务名称与公开编号、接收成员、单项能力、用途、准确到期时间和登录方式。登录分享必须确认只有指定接收人能以OIDC身份访问，且同一接收人、资源和权限的旧有效分享会被替换；匿名分享必须确认地址和口令组合等同访问凭据，任何持有者都可能访问，口令只显示一次并应与地址分开传递。`EDIT`仍由表单和服务端共同强制登录。显式确认后才调用创建接口，成功后才清空用途并显示新地址/口令；打开或取消新确认区不会提前清除尚未保存的旧匿名口令。
|
||||
|
||||
分享撤销使用页面内受控操作表单，固定展示授权编号、具体资源、权限、登录方式、到期时间和行版本。操作者必须确认撤销后系统会立即拒绝新的访问，但接收人已经离线保存的副本无法由平台追回。取消，或切换页签、家庭、长者，都会清空草稿且不发送撤销请求；服务端角色、租户、授权状态和并发版本校验保持不变。
|
||||
|
||||
## 匿名口令设计
|
||||
|
||||
匿名分享的授权编号由服务端签名密钥、操作者、幂等键和请求摘要确定性派生，访问口令再由授权编号确定性派生。这样，同一幂等请求可以返回相同口令，而数据库只保存口令的SHA-256摘要，不保存或记录原始口令。访问时服务端使用常量时间比较摘要，降低时序侧信道风险。
|
||||
|
||||
`SHARE_TOKEN_SIGNING_SECRET`至少32字符。生产环境拒绝占位值，并要求它与游标签名、设备令牌、RTC令牌等API签名密钥互不相同。匿名口令相当于访问凭证，应把地址和口令分开传递；拥有完整地址和口令的人均可访问，因此管理页仍要求选择明确接收人，便于用途说明、追踪和撤销，但匿名模式不把OIDC身份作为访问条件。
|
||||
|
||||
## 数据库与审计
|
||||
|
||||
`sharing_grant`保存客户组织、家庭、长者、具体资源、接收人、单项权限、用途、授予人、登录要求、口令摘要、失效时间和撤销信息。数据库约束再次校验资源与权限组合，并禁止匿名`EDIT`。创建授权时，服务端从资源反向推导客户组织、家庭和长者，不接受浏览器上报这些安全边界；接收人必须是同一客户组织的活动账号。
|
||||
|
||||
`sharing_access_log`逐次保存成功或拒绝访问的账号、身份摘要、资源、权限、结果、稳定原因、请求关联编号和时间，不保存故事正文、字幕正文、录音地址、Bearer凭证或原始分享口令。拒绝原因包括`TOKEN_INVALID`、`GRANT_INACTIVE`、`RECIPIENT_MISMATCH`、`CONSENT_REQUIRED`和`RESOURCE_UNAVAILABLE`。
|
||||
|
||||
隐私主体删除会撤销分享并脱敏用途和拒绝原因；主体物理清理时分享及访问日志级联删除。录音分享每次访问都会重新检查当前`raw_audio_storage`授权和分片`VERIFIED`状态。撤销后不再签发地址；已经签发的地址最长在当前5分钟对象存储签名窗口后失效，该窗口仍需在家庭试点前结合对象存储能力验证并尽量缩短。
|
||||
|
||||
## 验证
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-sharing.ps1
|
||||
```
|
||||
|
||||
烟测覆盖登录分享、匿名口令、确定性幂等重放、错误口令、接收人隔离、跨租户拒绝、非法资源权限组合、故事编辑及旧版本412、撤销、过期、原始口令不落库和成功/拒绝访问审计，并在结束后清理合成资源。
|
||||
|
||||
日常前端改动采用一次真实OIDC无提交轻量冒烟，使用合成故事、通话和已验证录音分片依次打开三种资源的创建确认区，同时覆盖匿名口令和登录接收两种模式。检查固定资源、接收人、能力、用途、有效期、影响确认、取消关闭、零创建POST、授权表数量不变、页面无横向溢出且无非预期浏览器错误；不在每次页面修改后重复执行本节完整访问和并发回归。
|
||||
@@ -0,0 +1,80 @@
|
||||
# SaaS核心业务边界与首批接口冻结
|
||||
|
||||
## 1. 本阶段目标
|
||||
|
||||
本阶段把现有登录、家庭成员权限和设备通话数据扩展为家庭用户可使用的SaaS业务纵向链路。当前范围覆盖家庭、成员邀请与角色协作、长者档案、稳定事实、分项授权、设备绑定与状态、设备影子配置、通话查询、最终字幕、摘要、故事人工审核和已确认记忆；设备命令、录音对象管理及生产级模型供应商在后续批次按相同租户与家庭边界继续实现。
|
||||
|
||||
## 2. 服务端边界
|
||||
|
||||
- OIDC仅证明外部身份；平台根据`issuer + subject`解析有效账号、客户组织和家庭成员关系。
|
||||
- 集合查询不得接受浏览器直接提交内部租户主键。`X-Tenant-Id`使用公开客户组织编号，服务端仍需验证当前外部身份在该客户组织中存在有效账号。
|
||||
- 家庭、长者、设备、通话和授权查询必须同时带客户组织条件与家庭成员关系，跨家庭访问统一返回无权限或不存在，不泄露资源是否真实存在。
|
||||
- 家庭角色控制管理能力，但不自动授予录音播放、下载、字幕正文等高敏感数据访问权。
|
||||
- 家庭和长者修改使用强ETag与`If-Match`；版本不一致返回`VERSION_CONFLICT`，禁止静默覆盖。
|
||||
- 授权记录保存授予事实并只允许追加；撤回只填写原记录的`withdrawn_at`，不得修改授权类型、政策、告知摘要、证据或授权时间。
|
||||
- 每次授权变化创建新的授权快照供后续新通话使用。历史通话快照保持不可变；但活动通话正在使用的字幕、原录音、故事整理或个性化记忆授权被撤回时，为避免继续按旧权限处理数据，撤回事务同时把通话转入安全停止。家庭分享撤回只影响分享访问，不中断实时语音。
|
||||
- 长者档案中的背景和交流偏好允许扩展保存，但只有OpenAPI声明的背景、兴趣、交流目标、节奏和优先话题会进入新通话上下文；其他字段保留在SaaS业务域，不向语音供应商传递。
|
||||
|
||||
## 3. 首批网页接口
|
||||
|
||||
| 方法 | 路径 | 权限与并发规则 |
|
||||
|---|---|---|
|
||||
| GET/POST | `/api/v1/households` | 登录账号可读；创建必须选择并验证`X-Tenant-Id` |
|
||||
| GET/PATCH | `/api/v1/households/{id}` | `household.read` / `household.manage`；PATCH要求`If-Match` |
|
||||
| POST | `/api/v1/member-invitations/preview` | 登录后按一次性凭据只读预览目标客户组织、家庭、角色和到期时间；不创建账号或成员关系，响应禁止缓存 |
|
||||
| POST | `/api/v1/member-invitations/accept` | 以当前OIDC身份接受一次性邀请；事务内重新校验邀请状态、账号状态和既有成员关系 |
|
||||
| GET/POST | `/api/v1/households/{id}/subjects` | `subject.read` / `subject.write` |
|
||||
| GET/PATCH | `/api/v1/subjects/{id}` | `subject.read` / `subject.write`；PATCH要求`If-Match` |
|
||||
| GET | `/api/v1/subjects/{id}/conversation-readiness` | `subject.read`；汇总家庭可处理的首次通话阻断项与运行提醒，不替代创建时的额度和路由原子门禁 |
|
||||
| GET/POST/PATCH | `/api/v1/subjects/{id}/facts` | 候选与已确认事实分离；确认必须有来源，PATCH要求`If-Match` |
|
||||
| GET/POST | `/api/v1/subjects/{id}/consents` | 查看授权历史；有写权限才能授予 |
|
||||
| POST | `/api/v1/subjects/{id}/consents/{consent_id}/withdraw` | 有写权限；同一撤回请求可安全重复；涉及活动通话时同步保存停止意图 |
|
||||
| POST | `/api/v1/device-claims` | 一次性绑定码仅保存摘要；同一目标安全重试不生成第二条绑定 |
|
||||
| GET | `/api/v1/devices`、`/api/v1/devices/{id}` | 只返回当前用户家庭内设备及脱敏状态 |
|
||||
| GET/PATCH | `/api/v1/devices/{id}/twin` | 读写期望/实际配置；PATCH要求`If-Match`且禁止长期密钥字段 |
|
||||
| GET | `/api/v1/devices/{id}/presence` | 优先读取Redis热状态，缺失时返回数据库最后上报并标记离线 |
|
||||
| GET | `/api/v1/subjects/{id}/conversations` | `conversation.read`；HMAC签名游标分页 |
|
||||
| GET | `/api/v1/conversations/{id}` | 返回状态、快照版本、RTC任务摘要和状态历史，不返回Token或长期密钥 |
|
||||
|
||||
通话记录页面直接使用上述查询契约：状态、语音处理方式、创建时间下界和创建时间上界均作为服务端过滤条件，页面不会先拉取全部数据后在浏览器内筛选。默认每页20条；存在`next_cursor`时才显示“加载更多”，后续请求只回传服务端签发的游标，浏览器不解析、不修改游标。页面上的结束日期按用户所在时区的次日零点转换为接口的不包含上界，使所选结束日期当天仍被完整纳入查询。切换筛选条件会清理旧详情，普通SSE状态刷新则保留当前详情，避免用户阅读过程中被实时事件打断。
|
||||
|
||||
列表与详情把`s2s_pure`、`s2s_hybrid`、`cascade`以及三种保存策略转换为家庭成员可理解的业务名称，不直接展示内部枚举。打开通话时并行读取详情、话轮、整理结果和费用；切换通话或筛选条件会取消尚未完成的旧详情请求，避免迟到响应覆盖当前选择。任一核心详情请求失败时清空旧详情，在右侧显示本次错误和页面内重试入口，不把错误混入长者档案提示。仅当本次冻结策略为`transcript_and_audio`时才请求录音媒体；不保存录音的通话不会发起无意义的媒体权限请求。
|
||||
|
||||
首次登录但尚无家庭成员关系时，网页仍根据`/api/v1/me`返回的有效客户组织账号展示“创建第一个家庭”。创建入口先打开页面内受控操作区，固定展示客户组织、当前账号和新家庭名称，并明确当前账号将成为所有者以及家庭初始不包含长者、授权、设备或通话；确认前不发送创建请求。浏览器只提交所选公开客户组织编号和家庭名称；服务端重新验证当前OIDC身份在该客户组织中的有效账号，并在一个事务内创建家庭、所有者成员关系和审计记录。创建后网页重新读取家庭清单并选中新家庭，不依赖客户端自行伪造角色或能力。
|
||||
|
||||
## 4. 数据模型增量
|
||||
|
||||
- `subject_profile`补充语言、IANA时区、扩展资料、交流偏好及创建/修改人；`profile_version`继续作为乐观锁版本。
|
||||
- 新增长者档案使用页面内受控操作区，固定家庭、称呼、语言、时区、背景、兴趣、交流目标、节奏和优先话题，并展示经过数量和单项长度限制后实际保存的内容。操作者必须确认这些资料可作为长期个人档案保存、只从后续新通话开始按版本使用，并理解创建档案不等于授予通话、录音、故事或记忆权限；取消或切换业务上下文不发送创建请求。
|
||||
- 修订长者档案时，页面先按字段展示当前版本到下一版本的实际差异，并明确只影响后续新通话，当前和历史通话继续保留原冻结快照，分项授权也不会随档案修订扩大。无变化时禁止提交；确认后仍使用当前档案强ETag，其他成员已经保存新版本时返回冲突而不覆盖。
|
||||
- `subject_fact`单独保存稳定事实，明确来源类型、确认状态、敏感等级和版本，模型候选不能冒充已确认事实。
|
||||
- 家庭成员登记稳定事实时必须显式选择事实类型和敏感等级；选择健康背景会把默认等级提升为敏感，但允许操作者进一步核对调整。提交前的受控操作区固定长者、完整事实内容、家庭录入来源、敏感等级和待核对状态，并明确创建候选不会自动确认、创建记忆或改写历史通话。
|
||||
- 待核对稳定事实使用页面内受控确认区，固定展示长者、事实类型、完整内容、来源类型/引用、敏感等级、当前状态和行版本。操作者必须确认事实不是未经复核的模型推断，并理解确认只从后续新通话开始作为已核对背景，不改写历史通话；取消或业务上下文变化不发送PATCH。服务端继续要求来源引用、写权限和强`If-Match`。
|
||||
- `consent_record`保存五类分项授权、范围、政策版本、告知摘要、授权人、证据、有效期和撤回时间。
|
||||
- `consent_snapshot`仍是通话使用的不可变授权依据；网页授权变化不修改历史通话快照。
|
||||
- 新增分项授权先进入页面内受控操作区。网页冻结长者、授权类型、仅作用于后续新通话的范围、当前政策版本、告知摘要、证据引用和有效期，并按授权类型说明实际数据影响；操作者必须确认已经向长者或合法授权人单独说明数据范围、用途和撤回方式后才可提交。切换授权类型会清除上一类型的告知确认；当前长者已有同类型有效授权时，页面直接阻止重复提交，服务端仍在事务内二次校验并返回稳定冲突，避免并发绕过页面形成重复有效授权。
|
||||
|
||||
## 5. 不变量
|
||||
|
||||
1. 对外响应只使用公开随机编号，不返回数据库内部主键。
|
||||
2. 所有写操作在业务数据、审计和可靠待办需要同时成立时使用同一数据库事务。
|
||||
3. 自由文本、档案和授权证据不写入普通请求日志。
|
||||
4. 删除、撤回、邀请和绑定等跨资源动作在对应批次完成前不得以简单物理删除替代正式流程。
|
||||
|
||||
## 家庭成员协作边界
|
||||
|
||||
- 邀请使用256位随机凭据，明文只在创建响应中返回一次，服务端只保存SHA-256摘要；邀请可以撤销并具有明确过期时间。
|
||||
- 创建成员邀请使用页面内受控操作区，固定家庭、接收人提示、加入角色和七天有效期。页面明确接收人提示只供人工识别，不绑定或校验真实身份；实际持有凭据的登录账号会被映射到目标客户组织并以所选角色加入家庭。操作者确认凭据只显示一次、应通过受控渠道交付且泄露时立即撤销后，页面才调用创建接口；取消不生成邀请，也不提前清除上一条尚未保存的邀请凭据。
|
||||
- 接受邀请前，网页使用独立只读预览接口按凭据摘要解析目标客户组织、家庭、接收人提示、角色和到期时间；预览响应使用`Cache-Control: no-store`，页面只显示掩码凭据且不建立任何关系。操作者确认以当前登录身份加入所示家庭后才调用接受接口；正式提交仍在事务内重新校验邀请未使用、未撤销、未过期、账号未禁用且当前身份尚不是该家庭成员。
|
||||
- 接受邀请时以当前OIDC的`issuer + subject`建立目标客户组织内的平台账号映射；已有禁用账号不会被邀请流程自动重新启用。
|
||||
- 同一邀请只能使用一次；重复、过期或已撤销的接受请求返回稳定冲突错误，并保留失败审计。
|
||||
- 待接受邀请的撤销使用页面内受控操作表单，固定展示家庭、接收人提示、目标角色、邀请编号、到期时间和当前状态。操作者必须确认原一次性凭据将立即失效且已有成员关系不受影响；取消，或切换页签、家庭、长者，会清空草稿且不发送撤销请求。
|
||||
- 所有者不能通过普通角色修改或成员移除接口降级、删除；必须使用独立所有权转移事务，把新所有者提升和原所有者降为管理员同步提交。
|
||||
- 角色修改、成员移除和所有权转移使用强ETag，旧版本写入返回`412`。
|
||||
- 非所有者成员的角色调整不再由列表下拉框立即保存，而是打开页面内受控操作区，固定家庭、成员、当前角色、成员编号和行版本。目标角色变化会清除旧确认，页面逐项说明管理员、编辑者和查看者的一般能力，并明确角色不会隐式授予录音播放、下载或其他高敏感资源权限。
|
||||
- 授权撤回、成员移除和所有权转移使用页面内受控操作表单，不再依赖浏览器确认弹窗。表单固定展示长者/家庭、目标成员、角色、授权策略及行版本，并在提交前说明记忆停止使用、成员访问立即失效或原所有者降为管理员等业务影响。
|
||||
- 成员移除和所有权转移必须逐字输入目标成员显示名，授权撤回必须显式勾选影响确认。切换业务页签、家庭或长者，以及取消操作，都会清空尚未提交的操作草稿且不产生业务写入；服务端角色、租户、状态和ETag并发门禁保持不变。
|
||||
|
||||
邀请创建页面采用真实OIDC无提交轻量冒烟：验证家庭、提示、管理员角色、七天有效期、提示不绑定身份和一次显示说明，未确认时提交按钮禁用，取消后无凭据展示、零邀请POST且邀请表数量不变。家庭创建和邀请接受复用一次真实OIDC轻量烟测：创建确认区验证组织、账号、家庭名称和所有者影响；接受流程只发起一次只读预览并验证目标、角色、掩码凭据和二次确认，取消后零家庭创建/邀请接受请求，家庭、成员和邀请状态均不变。邀请随机数、摘要落库、一次消费、跨客户组织账号映射、撤销、过期和复用失败审计继续由既有服务集成测试覆盖。
|
||||
|
||||
分项授权与固件灰度创建复用一次真实OIDC无提交轻量冒烟：验证已有同类有效授权被明确提示并阻断、切换类型会清除旧告知确认、新授权确认区冻结长者/政策/证据/数据影响，取消后不创建授权；服务端的授权唯一性、政策版本、不可变快照和撤回语义继续由既有定向集成测试覆盖。
|
||||
@@ -0,0 +1,64 @@
|
||||
# Safari兼容性一致性证据说明
|
||||
|
||||
## 1. 目标与验证强度
|
||||
|
||||
`cmd/safari-conformance`用于把同一发布候选在macOS真实Safari上的关键流程结果形成`safari-compatibility-conformance-report-v1`。本项目采用最小充分矩阵：发布依据中的`CURRENT`和`PREVIOUS`两个Safari版本，各验证桌面`1440×1000`与平板响应式`1024×900`两种视口，以及六条关键业务流程，共24项结果。不在每个版本重复所有低风险按钮组合，也不以覆盖率或截图数量替代功能结论。
|
||||
|
||||
Playwright WebKit、Chrome、Edge、Windows上的浏览器或人工构造数据只能输出`NON_SAFARI_TOOLCHAIN/external_validation_required=true`。只有macOS真实Safari证据完整时，报告才为`REAL_SAFARI/external_validation_required=false`。
|
||||
|
||||
## 2. 六条关键流程
|
||||
|
||||
| 标识 | 验证范围 |
|
||||
|---|---|
|
||||
| `AUTH_SESSION` | OIDC登录、回调恢复、会话失效提示和重新登录 |
|
||||
| `FAMILY_WORKSPACE` | 家庭成员、长者授权、设备、固件、通话、故事记忆、分享和隐私八个页签可进入并正确渲染 |
|
||||
| `OPERATIONS_WORKSPACES` | 运行配置、费用额度、告警处置和联调诊断工作台可进入、刷新和恢复 |
|
||||
| `REALTIME_NAVIGATION` | SSE已连接，工作台URL刷新、前进、后退和深链恢复正确 |
|
||||
| `MEDIA_FILE_CONTROLS` | 音频控件可播放；上传/下载确认区、Web Crypto摘要和私有对象访问无浏览器阻断 |
|
||||
| `CONTROLLED_ACTIONS` | 代表性页面内受控表单能打开、校验、取消，目标冻结且不依赖浏览器弹窗 |
|
||||
|
||||
每项结果必须为`PASS`，并要求控制台错误、非预期失败请求和横向溢出均为0。预期的401恢复、被取消SSE或有意阻断请求应在执行记录中说明，不能笼统计为0来隐藏异常。
|
||||
|
||||
## 3. 采集结构
|
||||
|
||||
输入使用`safari-compatibility-capture-v1`：
|
||||
|
||||
- 顶层绑定`candidate_version`、`build_digest`、`environment`、版本发布依据、变更工单、执行人、独立复核人和采集时间；
|
||||
- `runs`恰好覆盖`CURRENT`与`PREVIOUS`，两者`browser_version`必须不同；
|
||||
- 真实证据中`browser_name`固定为`Safari`，同时记录macOS版本、脱敏机器引用以及`SAFARIDRIVER`或`MANUAL_OBSERVED`执行方式；
|
||||
- 每个运行包含六流程与两视口的12项`results`，每项保存截图、视频、日志或人工记录引用；
|
||||
- 不保存登录令牌、Cookie、录音正文、字幕正文、匿名分享口令或个人敏感信息。
|
||||
|
||||
“最近两个版本”不硬编码到校验器。QA应在每次候选冻结时依据Apple公开发布信息或组织批准的浏览器基线登记`release_reference_ref`，把当时的版本映射为`CURRENT/PREVIOUS`，避免升级后仍把旧版本误报为最新。
|
||||
|
||||
## 4. 一致性检查与证据包门禁
|
||||
|
||||
报告执行11项检查：采集模式、来源、候选身份、候选绑定、环境身份、Safari版本覆盖、视口覆盖、流程覆盖、功能结果、证据引用和时间线。
|
||||
|
||||
`SAFARI_COMPATIBILITY`不可豁免。索引标记`VERIFIED`时，第一个文件必须是同候选的`PASS/REAL_SAFARI`报告，并完整包含24项结果。证据包清单中的`safari_compatibility_validation`汇总两个版本、运行数、结果数和缺口。非Safari报告或缺任一版本时必须保持`PENDING`。
|
||||
|
||||
## 5. 现场执行步骤
|
||||
|
||||
1. 固定候选版本、镜像摘要、目标环境和Safari发布依据。
|
||||
2. 分别在两个真实Safari版本上执行两种视口；每个视口只跑六条关键流程。
|
||||
3. 保存脱敏截图/视频、控制台与网络失败摘要，并填写采集JSON。
|
||||
4. 由不同于执行人的QA复核版本、候选、错误计数和证据引用。
|
||||
5. 生成报告：
|
||||
|
||||
```powershell
|
||||
go run ./cmd/safari-conformance `
|
||||
-capture E:\evidence\safari-capture.json `
|
||||
-candidate-version 0.63.0-rc.1 `
|
||||
-build-digest sha256:<64位摘要> `
|
||||
-output E:\evidence\safari-report.json
|
||||
```
|
||||
|
||||
6. 将报告作为`SAFARI_COMPATIBILITY`首个文件并重建候选证据包，确认`coverage_complete=true`。
|
||||
|
||||
本地仅验证采集与报告工具链：
|
||||
|
||||
```powershell
|
||||
.\scripts\smoke-safari-conformance-toolchain.ps1
|
||||
```
|
||||
|
||||
该脚本不启动Safari、不声称页面兼容，也不会把外部门禁改为通过。
|
||||
@@ -0,0 +1,156 @@
|
||||
# 用量、费用与额度开发说明
|
||||
|
||||
> 对应数据库迁移：V21
|
||||
> 对应接口契约：OpenAPI 0.24.0
|
||||
> 适用范围：本地模拟供应商、客户组织运营工作台和家庭通话详情
|
||||
|
||||
## 1. 目标与边界
|
||||
|
||||
本模块解决四个问题：按通话接收并去重供应商最终用量；使用当时有效的不可变价格版本核价；向运营人员和家庭成员提供不含供应商内部编号的汇总；在新通话创建前执行客户组织或设备的日/月费用、并发通话和单次时长策略。
|
||||
|
||||
当前实现覆盖本地完整业务链，但不把模拟结果扩张为真实供应商验收。供应商账单对账、真实报价同步、汇率换算、异常费用增长告警和真实Agent“完成当前轮后停止”仍需后续外部联调或告警批次完成。
|
||||
|
||||
## 2. 核心设计
|
||||
|
||||
### 2.1 标准化用量分类
|
||||
|
||||
| 分类代码 | 含义 | 示例指标与单位 |
|
||||
|---|---|---|
|
||||
| `RTC` | 实时音视频资源 | `connected_minute / minute` |
|
||||
| `END_TO_END_VOICE` | 端到端语音智能体 | `agent_minute / minute` |
|
||||
| `ASR` | 语音识别 | `audio_minute / minute` |
|
||||
| `LLM` | 大模型推理 | `token / token` |
|
||||
| `TTS` | 语音合成 | `character / character` |
|
||||
| `STORAGE` | 媒体或结果存储 | `gigabyte_day / gb_day` |
|
||||
| `POST_PROCESSING` | 通话后整理任务 | `job / job` |
|
||||
|
||||
数量以最多六位小数的十进制字符串接收，避免JSON浮点数导致计量漂移。单价和费用均使用`bigint`保存百万分之一货币单位，例如`132450`表示`CNY 0.132450`。
|
||||
|
||||
### 2.2 价格版本
|
||||
|
||||
- 运营操作人员创建`DRAFT`价格版本，价格正文和全部费率一经创建不可修改。
|
||||
- 创建人不能发布自己的版本；运营审批人员使用`If-Match`发布。
|
||||
- 同一客户组织、同一供应商只保留一个`PUBLISHED`版本，旧版本变为`RETIRED`。
|
||||
- 费用行冻结价格版本、具体费率、数量、单价、费用和币种。后续调价不会重算历史费用。
|
||||
- 已发布的其他供应商价格和活动额度策略必须使用兼容币种，防止额度统计绕过。
|
||||
|
||||
管理端从具体草稿行打开页面内“审批并发布价格版本”确认区，不再使用浏览器输入弹窗。确认区固定价格版本公开编号、供应商、版本号、币种、费率项数、生效时间、创建人和行版本；发布依据必填且最长500字符。提交前必须确认审批人不是创建人，且报价/合同引用、币种、全部费率和生效时间已经复核，并明确旧发布版本会退役、历史费用不会重算。取消、切换客户组织或列表刷新会清除草稿，不发送发布请求；服务端继续执行角色、禁止自批、状态和`If-Match`校验。
|
||||
|
||||
### 2.3 用量幂等与核价事务
|
||||
|
||||
供应商发送`voice_chat.usage / FINAL`事件。服务端先验证回调签名、时间偏差和字段，再在同一数据库事务内完成：
|
||||
|
||||
1. 以`provider + event_id`保存供应商事件摘要；相同编号、不同正文返回冲突。
|
||||
2. 以客户组织、供应商、来源事件、分类、指标和单位建立用量唯一键。
|
||||
3. 完全相同的重复用量读取已有费用行，不产生第二次费用。
|
||||
4. 按事件发生时间选择已经发布且生效的价格版本和精确费率。
|
||||
5. 使用数据库十进制运算计算并四舍五入为整数微单位。
|
||||
6. 同时提交供应商事件、用量事件和冻结费用行；任一步失败均整体回滚。
|
||||
|
||||
供应商原始事件表只保存正文摘要和`usage_count`，不复制用量明细或业务正文。
|
||||
|
||||
### 2.4 额度策略
|
||||
|
||||
额度策略按`TENANT`或`DEVICE`范围版本化保存；同一范围的新版本激活时，原活动版本退役。策略包含：
|
||||
|
||||
- 账期时区和币种；
|
||||
- 日费用上限、月费用上限；
|
||||
- 最大同时通话数；
|
||||
- 单次最长通话时长；
|
||||
- `STOP_IMMEDIATELY`或`COMPLETE_CURRENT_TURN`在途处置动作。
|
||||
|
||||
创建通话时先使用策略时区计算日/月边界，再分别检查客户组织和设备累计费用及并发数。两级策略同时存在时逐级校验，并冻结更严格的费用及时长边界。达到硬额度返回HTTP 429和稳定错误码`USAGE_QUOTA_EXCEEDED`。
|
||||
|
||||
通话创建成功后，策略编号、账期边界、限额、最长时长、处置动作和创建时累计费用写入通话预算快照。后续修改策略不会改写已有通话。达到最长时长时，心跳返回`stop`或`stop_after_turn`；后台恢复扫描会对`STOP_IMMEDIATELY`通话可靠投递停止任务。
|
||||
|
||||
## 3. 接口设计
|
||||
|
||||
| 方法与路径 | 角色 | 用途 | 关键控制 |
|
||||
|---|---|---|---|
|
||||
| `GET /api/v1/ops/price-books` | 运营查看及以上 | 查询价格历史和费率 | 必须选择客户组织 |
|
||||
| `POST /api/v1/ops/price-books` | 运营操作及以上 | 创建不可变价格草稿 | `Idempotency-Key` |
|
||||
| `PATCH /api/v1/ops/price-books/{id}/publish` | 运营审批及以上 | 双人发布价格版本 | `If-Match`、禁止自批 |
|
||||
| `GET /api/v1/ops/quota-policies` | 运营查看及以上 | 查询活动与历史额度 | 客户组织隔离 |
|
||||
| `POST /api/v1/ops/quota-policies` | 运营审批及以上 | 创建并激活策略版本 | `Idempotency-Key`、事务审计 |
|
||||
| `GET /api/v1/ops/cost-summary` | 运营查看及以上 | 按时间范围聚合费用 | 最大366天、不返回任务编号 |
|
||||
| `GET /api/v1/conversations/{id}/usage` | 活动家庭成员 | 查看单次通话用量和费用 | 服务端反查家庭关系 |
|
||||
| `POST /callbacks/v1/vertc/voice-chat` | 签名供应商 | 接收`voice_chat.usage` | HMAC、时间窗、事件幂等 |
|
||||
| `POST /device/v2/conversations` | 签名设备 | 创建通话并冻结预算 | 创建前统一额度检查 |
|
||||
|
||||
所有Web响应使用统一`request_id + data`信封。运营和家庭汇总只返回标准化分类、指标、数量、单位、费用和币种，不返回供应商任务、供应商事件、内部价格版本或费率编号。
|
||||
|
||||
## 4. 数据库设计
|
||||
|
||||
| 表 | 作用 | 关键约束 |
|
||||
|---|---|---|
|
||||
| `billing_price_book` | 供应商价格版本 | 租户+供应商+版本唯一；单一发布版 |
|
||||
| `billing_price_rate` | 价格版本下的费率 | 价格版本+分类+指标+单位唯一 |
|
||||
| `usage_quota_policy` | 客户组织/设备额度版本 | 每范围单一活动版本；时区和币种受校验 |
|
||||
| `conversation_usage_event` | 标准化最终用量 | 来源事件和计量维度唯一；通话删除级联 |
|
||||
| `conversation_cost_line` | 不可变费用行 | 每用量事件一条；冻结版本、单价和费用 |
|
||||
| `conversation_usage_budget` | 通话预算快照 | 每通话一条；随通话删除级联 |
|
||||
|
||||
金额不使用浮点字段，币种使用三位大写代码，数量使用`numeric(24,6)`。费用行对价格版本和费率使用外键，保证历史可追溯；主体隐私删除时，用量、费用和预算随通话级联清理。
|
||||
|
||||
## 5. 业务流程
|
||||
|
||||
### 5.1 价格发布与用量入账
|
||||
|
||||
```text
|
||||
运营创建价格草稿
|
||||
→ 另一名审批人复核并发布
|
||||
→ 供应商发送最终用量签名回调
|
||||
→ 事件编号与正文摘要去重
|
||||
→ 标准化分类/指标/单位校验
|
||||
→ 按发生时间命中价格版本与费率
|
||||
→ 冻结用量、单价和费用
|
||||
→ 运营汇总与家庭通话详情可见
|
||||
```
|
||||
|
||||
### 5.2 新通话额度检查
|
||||
|
||||
```text
|
||||
设备提交签名创建请求
|
||||
→ 读取客户组织与设备活动策略
|
||||
→ 按策略时区计算日/月账期
|
||||
→ 校验累计费用
|
||||
→ 校验同时通话数
|
||||
├─ 达到任一硬边界：429 / USAGE_QUOTA_EXCEEDED
|
||||
└─ 未达到：创建通话并冻结预算快照
|
||||
```
|
||||
|
||||
### 5.3 通话时长处置
|
||||
|
||||
```text
|
||||
通话持续运行
|
||||
→ 当前时间超过冻结的最长时长
|
||||
├─ STOP_IMMEDIATELY：心跳返回stop，Worker可靠投递停止
|
||||
└─ COMPLETE_CURRENT_TURN：心跳返回stop_after_turn
|
||||
```
|
||||
|
||||
`COMPLETE_CURRENT_TURN`目前已经形成设备动作契约，但真实供应商/Agent对“轮次结束”的确认和可靠停止仍属于外部联调项。
|
||||
|
||||
## 6. 错误与安全处理
|
||||
|
||||
- 缺少费率或价格尚未发布：整个回调事务回滚，供应商可重试。
|
||||
- 同一供应商事件编号对应不同正文：HTTP 409 `PROVIDER_EVENT_CONFLICT`。
|
||||
- 达到费用或并发硬额度：HTTP 429 `USAGE_QUOTA_EXCEEDED`。
|
||||
- 价格创建人自批：HTTP 409 `SELF_APPROVAL_FORBIDDEN`。
|
||||
- `If-Match`过期：HTTP 412 `VERSION_CONFLICT`。
|
||||
- 跨客户组织、非家庭成员或角色不足：HTTP 403，不泄露资源是否存在。
|
||||
- 回调处理内部失败记录结构化服务端错误，但客户端只得到可重试通用错误，不返回SQL或内部资源信息。
|
||||
|
||||
## 7. 验证证据
|
||||
|
||||
`scripts/smoke-billing.ps1`使用真实本地OIDC、设备HMAC、供应商回调HMAC和PostgreSQL验证：租户隔离、价格草稿幂等、禁止自批、双人发布、七类最终用量、重复计费去重、同编号异文冲突、冻结总费用、运营汇总脱敏、家庭汇总脱敏、预算快照和硬额度429。脚本结束后清理全部合成价格、额度、通话、用量、费用、审计和幂等记录。
|
||||
|
||||
V21已完成单版本`down 1`和重新`up`，最终为`21|false`。实际Chrome 1440×1100检查了运营用量费用工作台，未发现失败请求、控制台错误或横向溢出；截图保存在`test/e2e/screenshots/operations/ops-billing-workspace.png`。
|
||||
|
||||
价格发布页面增量按低强度策略复用真实OIDC登录，只使用一条由另一运营账号创建的临时草稿检查目标/行版本绑定、空原因阻断、双人审批影响确认、取消关闭以及零发布PATCH；同时检查零横向溢出、零控制台错误和零非预期失败请求。脚本为`test/e2e/visual-ops-billing-publish.mjs`，截图为`test/e2e/screenshots/ops-billing-price-publish.png`，价格及费率夹具在`finally`中精确清理。该无提交检查用于证明页面不会误发布，不替代既有服务端双人审批纵向烟测。
|
||||
|
||||
## 8. 后续工作
|
||||
|
||||
1. 在告警批次增加费用异常增长、额度临界、核价失败和供应商用量迟到告警及处置台账。
|
||||
2. 对接真实供应商账单接口，建立供应商账单与平台费用行的日对账和差异处理。
|
||||
3. 在真实Agent能力明确后完成`stop_after_turn`可靠确认与超时降级。
|
||||
4. 在类生产环境执行高并发回调、活动通话和大时间范围汇总压测。
|
||||
@@ -0,0 +1,56 @@
|
||||
# Web登录会话与失效恢复说明
|
||||
|
||||
## 1. 登录边界
|
||||
|
||||
Web端使用OIDC授权码加PKCE完成登录，OIDC提供方只证明外部身份。浏览器取得短期访问令牌后调用`GET /api/v1/me`，由云端根据`issuer + subject`解析当前有效的平台账号、客户组织、家庭成员关系、运营角色和能力。业务工作台只在OIDC用户与云端账号映射同时有效时挂载，不依据浏览器保存的角色或客户组织自行放行。
|
||||
|
||||
OIDC客户端把当前用户状态保存在`sessionStorage`，关闭当前浏览器会话后不继续复用；启用自动静默续期，并在访问令牌到期前60秒发起续期。业务接口只通过`Authorization: Bearer`发送访问令牌，页面和业务状态不持久化令牌正文。
|
||||
|
||||
## 2. 首次登录和回调
|
||||
|
||||
1. 用户点击“登录研发环境”，浏览器跳转OIDC提供方；
|
||||
2. OIDC提供方完成账号验证和PKCE交换后返回`/auth/callback`；
|
||||
3. Web客户端只处理一次回调，并从OIDC事务状态恢复登录前的站内相对地址；无合法返回地址时回到`/`，同时拒绝协议相对地址、跨源地址和回调页自身，避免重复交换授权码和开放重定向；
|
||||
4. 客户端调用`/api/v1/me`取得服务端权限事实；
|
||||
5. 只有两层状态均成功时才展示家庭业务和当前账号允许的运营工作台。
|
||||
|
||||
回调失败、网络错误或云端账号映射失败时停留在身份区，不挂载业务工作台。若OIDC用户仍有效，页面允许重新读取云端账号；用户也可以重新发起认证。
|
||||
|
||||
## 3. 业务接口返回401
|
||||
|
||||
所有带令牌的API请求统一处理HTTP 401。任何家庭或运营接口返回401时，API客户端触发页面级`platform:authentication-required`事件，而不是只在当前子页面显示局部错误。认证状态管理器对并发401执行合并处理：
|
||||
|
||||
1. 清除`sessionStorage`中的旧OIDC用户和访问令牌；
|
||||
2. 立即清除云端账号状态，使全部家庭与运营工作台卸载；
|
||||
3. React组件卸载时取消仍在执行的业务请求和SSE读取；
|
||||
4. 身份区明确显示“登录状态已经失效，请重新登录”；
|
||||
5. 用户点击“重新登录”后重新执行OIDC与`/api/v1/me`双重校验，成功后重新挂载业务区。
|
||||
|
||||
401表示身份凭据已经失效；权限不足必须由服务端返回403，页面不得把403升级为全局退出。网络超时、503和普通业务冲突也只在对应页面提供恢复，不清除有效登录状态。
|
||||
|
||||
## 4. 令牌到期和静默续期失败
|
||||
|
||||
OIDC客户端发现已保存用户过期、收到访问令牌到期事件或静默续期失败时，同样删除本地旧用户并进入重新登录状态。不能继续保留顶部“已登录”账号卡片，也不能让已挂载工作台使用旧令牌反复请求。手工退出使用OIDC标准退出跳转，并在用户卸载事件后清空本地状态。
|
||||
|
||||
## 5. 工作台导航与恢复
|
||||
|
||||
家庭业务使用根地址；运营工作台分别使用`?workspace=config`、`billing`、`alerts`和`diagnostics`。点击工作台入口通过`history.pushState`写入浏览器历史，前进/后退通过`popstate`恢复页面；刷新或直接打开合法地址时，在OIDC身份和云端账号加载完成后恢复目标工作台。
|
||||
|
||||
URL只表达界面位置，不授予运营权限。客户端必须等待云端账号解析完成后检查`platform_role`：没有运营权限的账号即使直接输入运营地址，也回到家庭业务并使用`replaceState`清除无权访问或未知的`workspace`值。会话短暂失效时保留合法工作台位置，重新登录并重新取得同等权限后回到原工作台；如果新账号权限不同，则安全回退家庭业务。
|
||||
|
||||
页面切换不会把表单正文、密钥引用、访问令牌或客户组织编号写入URL。快速自动检查应按接近人工操作的节奏切换，避免把瞬时超过用户级读取突发值的脚本行为误判为导航故障；真实检查仍要求所有请求不出现429。
|
||||
|
||||
## 6. 轻量验证
|
||||
|
||||
`test/e2e/visual-authentication-recovery.mjs`使用真实本地OIDC登录，在家庭数据刷新时只注入一次401，验证：
|
||||
|
||||
- 身份区显示会话失效和重新登录入口；
|
||||
- 家庭工作台立即卸载；
|
||||
- 本地OIDC用户条目清零；
|
||||
- 未完成业务请求因组件卸载而取消；
|
||||
- 重新登录可利用仍有效的OIDC服务端会话恢复账号与业务工作台；
|
||||
- 除预期401和请求取消外，不出现失败请求、控制台错误或页面横向溢出。
|
||||
|
||||
该检查不修改业务数据，不替代生产OIDC会话时长、MFA、跨设备退出、管理员强制失效和真实反向代理Cookie/安全头验收。
|
||||
|
||||
`test/e2e/visual-workspace-navigation.mjs`另验证运行配置和费用额度选择写入URL、刷新恢复、浏览器后退/前进、未知值回退家庭业务，以及直接打开告警工作台地址。`test/e2e/visual-ops-sensitive-access-request.mjs`从未登录的联调诊断深链发起真实OIDC认证，验证回调后仍停留在目标工作台，再执行无提交的申请表单门禁检查。检查要求零429、零控制台错误、零非预期失败请求和零横向溢出。
|
||||
@@ -0,0 +1,139 @@
|
||||
# Web状态事件流开发说明
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
`GET /api/v1/events`用于把设备、通话、故事、媒体、导出、隐私请求和设备指令的状态变化推送到已登录的家庭工作台。该接口只承担“页面需要刷新哪些业务资源”的通知职责，不传输录音、转写、故事正文、设备指令参数、隐私申请原因或下载地址，也不替代各业务查询接口。浏览器收到事件后仍通过原有REST接口重新读取经过权限校验的最新状态。
|
||||
|
||||
本阶段采用“PostgreSQL事务事件表 + 短时续传窗口 + 认证SSE”的实现。状态变化和事件写入位于同一数据库事务，避免业务已提交但通知丢失；SSE连接失败不影响业务事务，客户端可使用最后事件编号恢复。
|
||||
|
||||
## 2. 事件模型
|
||||
|
||||
| 事件类型 | 产生条件 | 资源类型 | 状态示例 |
|
||||
|---|---|---|---|
|
||||
| `device.presence.changed` | 首次有效心跳使设备上线，或后台发现心跳超时使设备离线 | `device` | `online`、`offline` |
|
||||
| `conversation.started` | 通话进入`ACTIVE` | `conversation` | `ACTIVE` |
|
||||
| `conversation.completed` | 通话进入`COMPLETED` | `conversation` | `COMPLETED` |
|
||||
| `conversation.failed` | 通话进入`FAILED` | `conversation` | `FAILED` |
|
||||
| `story.created` | 新故事候选建立 | `story` | 故事当前状态 |
|
||||
| `story.revised` | 故事版本增加 | `story` | 故事当前状态 |
|
||||
| `media.upload.completed` | 媒体上传批次完成 | `upload_batch` | `COMPLETED` |
|
||||
| `export.ready` | 私有导出文件就绪 | `export_task` | `READY` |
|
||||
| `privacy_request.updated` | 隐私请求建立或状态变化 | `privacy_request` | 请求当前状态 |
|
||||
| `device.command.updated` | 可靠设备指令建立或状态变化 | `device_command` | `QUEUED`、`DELIVERED`、`SUCCEEDED`等 |
|
||||
|
||||
事件公开字段固定为`id`、`type`、`resource_type`、`resource_id`、可选`subject_id`、`status`和`occurred_at`。其中资源和长者编号均为公开UUID，数据库内部编号、正文、对象存储引用、签名、令牌、操作人员编号和请求幂等键不得进入事件数据。
|
||||
|
||||
## 3. 数据库设计
|
||||
|
||||
V16迁移新增以下对象：
|
||||
|
||||
- `web_event`：保存15分钟内可续传的最小状态事件，使用递增`bigserial`作为`Last-Event-ID`游标；按客户组织、家庭和长者记录授权边界。
|
||||
- `device_presence_state`：保存设备当前在线布尔值、最后心跳时间和最近一次状态变化时间。该表不保存心跳正文。
|
||||
- `append_web_event(...)`：统一写入最小事件；同时发送PostgreSQL通知，为后续把轮询优化成`LISTEN/NOTIFY`预留条件。当前服务端读取仍以数据库轮询为准。
|
||||
- 业务触发器：在会话、故事、媒体上传批次、导出、隐私请求和设备指令事务提交前生成事件。
|
||||
- `record_device_presence(...)`：有效且序号前进的设备心跳调用该函数；连续在线心跳仅刷新`last_seen_at`，不会重复产生上线事件。
|
||||
- `expire_device_presence(...)`：Worker按心跳租约扫描在线记录，超过阈值后原子切换为离线并产生一次离线事件；使用`FOR UPDATE SKIP LOCKED`支持多Worker安全竞争。
|
||||
|
||||
`web_event.subject_id`和`device_presence_state.subject_id`在主体物理清理时级联删除，确保15分钟临时事件不会阻塞隐私删除。Worker定期分批删除过期事件；主体隐私删除处理器也会主动清理该主体的历史事件。
|
||||
|
||||
## 4. 接口设计
|
||||
|
||||
### 4.1 请求
|
||||
|
||||
```http
|
||||
GET /api/v1/events HTTP/1.1
|
||||
Authorization: Bearer <OIDC access token>
|
||||
Accept: text/event-stream
|
||||
Last-Event-ID: 12345
|
||||
```
|
||||
|
||||
`Authorization`必需。`Last-Event-ID`可选，但一旦提供必须是大于0的整数，并且必须仍处于当前账号可访问的家庭范围和15分钟续传窗口内。
|
||||
|
||||
### 4.2 响应
|
||||
|
||||
```text
|
||||
retry: 2000
|
||||
id: 12345
|
||||
|
||||
id: 12346
|
||||
event: device.command.updated
|
||||
data: {"id":12346,"type":"device.command.updated","resource_type":"device_command","resource_id":"...","subject_id":"...","status":"SUCCEEDED","occurred_at":"..."}
|
||||
|
||||
: heartbeat
|
||||
```
|
||||
|
||||
首次连接不回放历史业务事件。服务端先返回当前账号可见的最新事件编号，浏览器保存该编号；此后发生的事件才能被推送。这样既避免登录后重复执行旧通知，也能覆盖“初始编号已收到、业务事件随后发生、连接中断”的恢复窗口。
|
||||
|
||||
### 4.3 状态码
|
||||
|
||||
| 状态码 | 错误码 | 处理方式 |
|
||||
|---|---|---|
|
||||
| 200 | — | 建立`text/event-stream` |
|
||||
| 400 | `EVENT_CURSOR_INVALID` | 游标格式错误；客户端记录诊断信息，不使用该值继续请求 |
|
||||
| 401 | `AUTHENTICATION_REQUIRED` | 登录失效；回到登录流程 |
|
||||
| 410 | `EVENT_CURSOR_EXPIRED` | 游标过期或不属于当前权限范围；清除本地游标，完整刷新业务数据后重新连接 |
|
||||
|
||||
跨租户游标、已移除家庭成员使用的游标和真正过期的游标统一返回410，不向调用者区分资源存在性。
|
||||
|
||||
## 5. 服务端业务流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant B as 业务事务
|
||||
participant P as PostgreSQL
|
||||
participant S as SSE接口
|
||||
participant W as Web工作台
|
||||
B->>P: 更新业务状态
|
||||
B->>P: 同事务写入web_event
|
||||
P-->>B: 提交成功
|
||||
W->>S: GET /events + Last-Event-ID
|
||||
S->>P: 校验账号、家庭成员和游标
|
||||
loop 每500毫秒
|
||||
S->>P: 查询id大于游标的可见事件，最多100条
|
||||
P-->>S: 最小事件列表
|
||||
S-->>W: id + event + data
|
||||
end
|
||||
W->>W: 保存最后编号并触发业务查询刷新
|
||||
```
|
||||
|
||||
服务端每10秒发送注释心跳以维持链路，每25秒主动结束一次连接，由客户端重连。这一连接轮换是当前本地基线，用于避免长连接无限占用失效网络状态；后续500连接专项压测将决定生产网关、连接时长和轮询间隔参数。
|
||||
|
||||
## 6. 设备在线状态流程
|
||||
|
||||
1. 设备提交严格递增序号的通话心跳。
|
||||
2. PostgreSQL更新权威租约和设备影子；同一事务调用`record_device_presence`。
|
||||
3. 设备此前不存在在线记录或已离线时，写入一次`online`事件；连续心跳只延长最后出现时间。
|
||||
4. Redis继续承担低延迟在线查询，PostgreSQL状态表承担状态转换和事件可靠性。
|
||||
5. Worker每个心跳周期扫描一次；最后出现时间超过两倍会话租约的记录切换为`offline`并只写入一次事件。
|
||||
6. 新的有效心跳可再次把离线记录切回在线并产生新的上线事件。
|
||||
|
||||
## 7. 浏览器重连与去重
|
||||
|
||||
原生`EventSource`不能可靠附带Bearer请求头，因此工作台使用`fetch`读取SSE字节流。客户端按当前登录账号集合隔离地把最后事件编号保存到`sessionStorage`，逐块解析`id`、`event`和`data`：
|
||||
|
||||
- 只接受编号大于本地最后编号的事件，重放事件不会触发重复刷新。
|
||||
- 收到事件后先保存游标，再把页面数据刷新加入合并队列；通知本身不直接启动下载、删除、授权等有副作用的操作。
|
||||
- 网络中断、服务端25秒轮换或临时错误后等待1秒重连，并显示“状态重连中”。
|
||||
- 收到410时清除游标，把一次完整业务刷新加入同一合并队列，等待1秒后以无游标方式建立新基线。
|
||||
- 页面展示“状态连接中 / 状态实时更新 / 状态重连中”，最近事件时间仅用于本地提示。
|
||||
|
||||
连续状态事件不会逐条触发成员、长者、授权、内容、设备和固件等整套REST查询。浏览器对SSE触发的刷新实行2秒最小间隔：第一条事件可立即刷新，间隔内后续事件合并到下一批；用户主动保存、撤回或重试成功后的刷新不进入该延迟队列。该策略保证最终读取仍来自服务端权威接口，同时避免500毫秒事件轮询放大为请求风暴并耗尽用户限流桶。
|
||||
|
||||
## 8. 安全与运维约束
|
||||
|
||||
- 每次建立连接及每批事件查询都按OIDC签发方、主体、活动账号和活动家庭成员关系过滤，不信任前端传入租户或家庭编号。
|
||||
- 响应使用`Cache-Control: no-store`和`X-Accel-Buffering: no`，代理层不得缓存或聚合事件正文。
|
||||
- 事件只用于状态失效通知；所有详情查询继续执行原业务权限、冻结、撤回和审计规则。
|
||||
- 当前实现使用500毫秒数据库轮询，适合作为本地正确性基线；生产扩容前需完成500个并发SSE连接、断线重连风暴和事件突发压测，再决定是否启用通知唤醒和独立事件网关。
|
||||
- 日志不得记录Bearer令牌、SSE数据正文或`Last-Event-ID`对应的资源内容；仅可记录请求编号、连接结果和稳定错误码。
|
||||
|
||||
## 9. 验证方式
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\smoke-web-events.ps1
|
||||
pwsh -NoProfile -File .\scripts\smoke-device-presence-events.ps1
|
||||
$env:PLAYWRIGHT_REQUIRE_FROM='C:\Users\19926\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules'
|
||||
node .\scripts\visual-sse-refresh-coalescing.cjs
|
||||
```
|
||||
|
||||
第一组验证事务事件生成、断点续传、已处理事件不重放、活动家庭成员可见、跨租户隔离、非法游标、过期游标和敏感字段不泄漏；第二组验证上线只通知一次、连续心跳去重以及心跳超时产生离线事件。浏览器合并回归分散注入8条最小事件，要求核心数据最多刷新5批、总业务响应不超过90、无HTTP 429或其他失败，并在结束时删除事件夹具。实际Chrome检查还会确认认证连接成功、状态提示可见、无控制台错误和无横向溢出。
|
||||
Reference in New Issue
Block a user