446 lines
29 KiB
Markdown
446 lines
29 KiB
Markdown
# 数据采集终端—云端系统详细开发计划
|
||
|
||
> 依据：《数据采集终端—云端系统研发需求规格说明书》
|
||
> 计划口径：从工程框架搭建到生产落地
|
||
> 编制日期：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-26，本地工程已经完成阶段1—7的本地开发与验证闭环，并在阿里云单机环境部署标准HTTPS、OIDC、加密本机备份、主机健康签名上报和八项发布候选技术门禁。生产快照不能用演示部署模式、未验证的异地备份、未配置的外部告警或仍在运行的Mock服务冒充可上线。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. OSS异地备份已完成无长期AK的IMDSv2/ECS RAM角色适配；待云账号侧绑定角色、创建私有Bucket后执行真实上传回读验收。随后待真实火山RTC/豆包、大模型/Embedding账号、终端硬件、外部告警接收器和其余生产资源到位，完成阶段8真机联调、家庭试点、预生产恢复与灰度发布。
|
||
|
||
实际完成证据与未完成项持续维护在[开发状态与门禁记录](development-status.md)中；本计划只定义执行顺序和退出条件，不用计划状态替代测试证据。
|