18 KiB
18 KiB
首期需求可追溯矩阵
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.68.0可按候选构建导出八项技术门禁及脱敏阻断告警定位快照，绑定候选版本/构建摘要后按业务时区归档日/周运行证据。第七项门禁要求主机健康快照在15分钟内且全部检查正常；第八项在PRODUCTION强制要求生产部署模式、三个业务进程实际APP_ENV=prod、身份服务非开发模式、已验证异地备份、外部告警配置及Mock服务退出，在LAB/STAGING明确标记不适用。cmd/release-evidence现使用v3清单，把同一候选的快照、接口、迁移、部署、SBOM和十类外部状态形成逐文件摘要；远程CI供应链、真机固件、真实终端RTC、真实Agent模型、真实告警网关、云KMS/HSM轮换、生产等价恢复、生产基础设施和Safari兼容分别要求结构化报告，并把14项CI检查/镜像/SBOM、设备固件场景、语音方式与恢复场景、生成/Embedding/内容安全质量、路由演练、轮换模式、恢复类型、基础设施控制项及Safari矩阵覆盖与缺口写入清单。V38及九个离线校验器把云端状态与远程构建、外部设备、RTC/语音供应商、模型提供器、网关、密钥提供器、目标环境和浏览器证据绑定；content_safety_tls把策略服务网络/证书状态纳入指标、告警、运营页面和候选快照。缺检查、缺制品、缺场景、缺演练、缺质量类别、缺控制项、PENDING和本地模拟证据均不会被误报为外部验收完成，整体发布仍必须基于真实联调、灰度和审批记录确认。 |
| P0445 | 需求编号关联代码、测试、接口或配置变更 | 本文逐项建立关联；后续功能变更必须同步更新本矩阵和development-status.md。 |
当前仍不能宣告完成的部分集中为：真实火山RTC与豆包三模式联调、真实方舟内容与Embedding质量、真实听筒的长者交流体验、量产设备/KMS注入、跨故障域生产对象存储与备份、真机异常恢复、真实账单和生产级内容安全。阿里云单机环境已经形成加密全组件归档、数据库隔离恢复和Redis RDB校验，但同机归档不能替代托管PITR、异地副本和生产恢复演练。这些剩余项属于阶段8外部验收，不应通过增加本地低价值测试伪造完成证据。
下一批本地开发应优先从矩阵中出现“进行中”的条目选择；若没有本地功能缺口，则只继续完善能够直接降低阶段8联调风险的模拟器、诊断和交付工具，不以覆盖率数字替代业务功能。