96 lines
17 KiB
Markdown
96 lines
17 KiB
Markdown
# 首期需求可追溯矩阵
|
|
|
|
## 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注入、跨故障域生产对象存储与备份、真机异常恢复、真实账单和生产级内容安全。阿里云单机环境已经形成加密全组件归档、数据库隔离恢复和Redis RDB校验，但同机归档不能替代托管PITR、异地副本和生产恢复演练。这些剩余项属于阶段8外部验收，不应通过增加本地低价值测试伪造完成证据。
|
|
|
|
下一批本地开发应优先从矩阵中出现“进行中”的条目选择；若没有本地功能缺口，则只继续完善能够直接降低阶段8联调风险的模拟器、诊断和交付工具，不以覆盖率数字替代业务功能。
|