338 lines
30 KiB
Markdown
338 lines
30 KiB
Markdown
# 数据采集终端—云端系统
|
||
|
||
这是依据《数据采集终端—云端系统研发需求规格说明书》建立的正式产品工程。当前已完成工程框架、公共能力、本地模拟语音闭环、家庭用户SaaS核心业务、字幕到人工确认记忆闭环，以及隐私、可靠设备命令、签名固件灰度、双轨录音、认证SSE状态事件流、具体资源分享、运营配置灰度发布、用量费用额度、告警处置、集成诊断和敏感数据临时提权闭环。
|
||
|
||
## 当前已实现
|
||
|
||
- Go模块化单体的`api`、`callbacks`和`worker`三个进程入口。
|
||
- 统一环境配置、JSON结构化日志、请求关联编号、请求体限制、安全响应头和优雅停机。
|
||
- PostgreSQL、pgvector和Redis连接及存活/就绪健康检查。
|
||
- OpenAPI 3.1基线与React类型生成。
|
||
- 设备API兼容门禁：拉取请求自动检查OpenAPI破坏性变化，v2新增行为使用显式可选能力位，不依赖固件`User-Agent`；终端不根据云端`engine_mode`改变采集或播放。
|
||
- React/TypeScript/Vite研发工作台，覆盖加载、失败、重试和状态展示。
|
||
- Web接口统一具备15秒超时、页面切换取消和明确的超时重试提示，避免操作长期悬挂。
|
||
- Web入口HTML禁止陈旧缓存，哈希静态资源长期缓存，并返回CSP、防嵌套、MIME嗅探和浏览器权限安全头。
|
||
- PostgreSQL首批迁移：扩展、租户、用户、审计、幂等记录和outbox可靠待办。
|
||
- Keycloak OIDC授权码+PKCE登录、`issuer + subject`账号映射和家庭角色权限。
|
||
- Web登录会话在访问令牌到期前自动续期；续期失败或令牌过期时立即退出业务视图并提示重新登录。
|
||
- 幂等并发串行化、事务审计、outbox领取/重试/死信和进程崩溃锁恢复。
|
||
- OpenTelemetry分布式追踪、Prometheus HTTP/依赖/outbox指标与结构化日志关联。
|
||
- Redis令牌桶限流、HMAC签名游标分页和ETag/If-Match乐观并发组件。
|
||
- 每设备独立请求签名、防重放、启动握手、版本化配置读取和可运行模拟设备。
|
||
- 逐设备生产密钥：设备表只保存`device-secret://<name>`引用，API从受控Secrets/KMS CSI目录按请求读取对应密钥；引用禁止路径穿越，密钥轮换原子替换文件后无需重启服务，本地模拟仍使用静态开发密钥。
|
||
- 两阶段通话主链：事务冻结授权/背景、房间分配、确定性短期Token、入房确认和可靠启动。
|
||
- 智能体启动结果闭环：设备入房后读取`wait/continue/leave_room`权威动作；供应商永久拒绝启动时通话、RTC任务、状态历史和审计原子收敛，模拟终端按稳定失败码及时退房。
|
||
- 背景资料准备失败闭环：白名单字段类型异常时保存`FAILED/context_preparation_failed`权威通话，不创建RTC房间；设备422、幂等重放、家庭详情和运营诊断展示同一结果。
|
||
- 活动通话授权撤回闭环：撤回通话正在使用的字幕、原录音、故事整理或个性化记忆授权时，同一事务保存停止状态和可靠Agent停止任务；设备心跳/遥测取得停止动作。
|
||
- 可运行模拟语音供应商：固定任务幂等受理、签名异步回调、重复事件去重和`ACTIVE`状态闭环。
|
||
- 序列化通话心跳：PostgreSQL权威租约、Redis热租约和设备在线状态，重复/乱序请求不续租。
|
||
- 可靠停止与终态收敛：固定任务Stop、结束/失败回调、幂等重放和租约释放。
|
||
- 后台异常回收：预留过期、心跳超时、启动/停止卡住任务扫描，对账动作和系统审计。
|
||
- 家庭、长者、稳定事实和五类分项授权首批网页API：服务端租户隔离、家庭角色能力、强ETag、事务审计、授权追加历史、撤回幂等和不可变授权快照。
|
||
- 设备列表、详情、在线状态、设备影子配置和一次性绑定码：非敏感配置白名单、敏感字段拒绝、Redis实时状态降级和安全重复绑定。
|
||
- 家庭业务React工作台：家庭切换、长者档案、稳定事实登记/确认、分项授权/撤回、设备绑定与配置、通话列表/详情及角色只读控制。
|
||
- 角色化业务导航：家庭用户只加载家庭业务，运营角色可按需切换运行配置、费用额度、告警处置和联调诊断，避免无权限页面与全部工作台同时加载。
|
||
- 家庭成员协作：成员列表、一次性邀请/撤销/接受、跨客户组织受邀账号映射、角色变更、成员移除和家庭所有权转移。
|
||
- 通话查询API：长者维度游标分页、状态过滤、脱敏详情、冻结快照摘要和完整状态历史。
|
||
- 长者扩展档案、稳定事实、授权记录、设备绑定、最终话轮、摘要、故事版本和已确认记忆数据库模型；V8迁移已完成空库升降级验证。
|
||
- 模型内容候选化：只使用可追溯长者话轮生成候选；人工确认和当前有效记忆授权共同控制长期记忆写入。
|
||
- 可切换内容生成器：本地使用确定性适配器，生产可通过火山方舟OpenAI兼容接口生成结构化摘要、开放话题、故事和事实候选；模型网络调用不占用数据库事务，写入前重新核对通话状态、授权和话轮指纹，敏感内容在本地拦截后不发送外部模型。
|
||
- 新通话在数据库层按租户、长者、当前授权、状态、敏感级别、有效期和索引状态检索已确认记忆，并把实际版本冻结到背景快照。
|
||
- 可切换记忆向量：本地使用1536维确定性向量，生产可通过火山方舟OpenAI兼容`/embeddings`接口完成索引和查询；两端共用同一模型及维度，外部调用均位于数据库事务外，查询服务临时不可用时通话可无记忆降级启动。
|
||
- 隐私数据访问请求：所有者幂等提交、Outbox/Worker子任务、八类数据范围盘点、无正文结果和审计。
|
||
- 私有数据导出：按长者和分类生成JSON，MinIO私有存储、SHA-256校验、短期签名下载和过期对象清理。
|
||
- 主体级隐私删除：精确称呼确认、活动通话保护、立即冻结读取/上传/召回，以及PostgreSQL、Redis、对象存储、pgvector、外部索引和私有导出六子系统的可重试对账与最小删除证明。
|
||
- 设备命令可靠链路：家庭端幂等排队、设备HMAC主动拉取、重复投递计数、确认/成功/失败回执和过期终态；Web设备卡片可下发诊断命令。
|
||
- 固件安全发布与管理页：Ed25519受信公钥、浏览器私有直传、大小与SHA-256校验、签名清单验证、确定性灰度、可靠命令、短期下载、暂停、已验证版本回滚，以及逐设备下载/安装/确认进度。
|
||
- 双轨录音媒体链路：near/far分片清单幂等、15分钟单对象直传、Outbox可靠校验、WAV PCM16容器/时长/大小/SHA-256核验、延迟删除本地密文及设备回执，以及PLAY/DOWNLOAD独立授权、授权列表/撤销、React双轨播放下载、5分钟私有访问和成功/拒绝审计。
|
||
- 联调问题闭环：按客户组织记录问题现象、严重级别、设备/通话/请求编号、责任方、根因、修复版本和脱敏回归证据；未关闭HIGH/CRITICAL形成发布阻断汇总，创建幂等、更新强ETag并全程审计。
|
||
- 认证SSE状态事件流：业务事务内生成最小事件，15分钟`Last-Event-ID`续传、活动家庭成员过滤、跨租户游标拒绝、重复事件抑制、设备上线去重/超时离线、React自动重连和2秒合并刷新，避免连续事件放大为整页请求风暴。
|
||
- 具体资源分享闭环：故事、通话文字和录音分片的登录定向或匿名口令授权、幂等创建、授权历史、撤销/过期、跨租户拒绝、故事共享编辑与强并发控制、5分钟录音短期地址、逐次访问审计及React管理页。
|
||
- 内部运营配置：独立平台运营角色、五类不可变版本、结构与敏感键校验、离线评测证据、受控凭据/音色/模型引用、双人审批、租户/试验对象/设备组灰度、稳定分桶、并发影响上限、投放台账、资源撤销和不可变回滚；新通话按范围优先级命中并冻结实际路由配置编号。
|
||
- 用量费用与额度：供应商七类最终用量签名回调、事件和计量双层幂等、不可变价格版本与双人发布、费用行版本/单价冻结、运营周期汇总、家庭通话用量展示，以及客户组织/设备日月费用、并发通话和最长时长硬额度。
|
||
- 真实RTC/语音供应商适配：本地使用确定性开发Token与Mock任务协议；生产可切换为火山RTC正式Token格式和经官方Go SDK签名的`StartVoiceChat/StopVoiceChat`，稳定任务编号、超时重试和停止幂等语义保持不变；冻结的`s2s_pure`、`s2s_hybrid`或`cascade`模式会选择各自独立的供应商模板。
|
||
- 生产启动安全门禁：生产环境强制OIDC HTTPS、数据库传输安全、Redis认证、对象存储TLS、火山RTC正式Token、签名VoiceChat OpenAPI、非占位且相互独立的签名密钥，并拒绝本地模拟供应商配置。
|
||
- k6研发压测入口和Prometheus基础告警：覆盖服务可用性、5xx、p95、Outbox积压/死信、隐私部分失败及固件失败/停滞。
|
||
- 分层限流和供应商容量保护：分别按网络、用户、客户组织和设备限流，并对供应商启动RPS与跨Worker活动任务数执行保护。
|
||
- 后台任务仅重试显式临时错误：网络、超时、供应商临时错误、对象暂不可见和可恢复数据库错误采用带随机变化的指数退避；永久错误立即进入死信。
|
||
- 集成诊断工作台：按设备、通话、房间、供应商任务和请求编号精确检索脱敏状态，并提供配置刷新、安全停止、状态对账、设备吊销、已注册死信受控重试和脱敏JSON诊断包。
|
||
- 敏感数据临时提权：按单次通话申请字幕读取/录音播放，最长4小时、申请人禁止自批、另一人审批、到期自动失效、5分钟录音短链及逐次成功/拒绝审计。
|
||
- Grafana业务、技术、安全三类仪表盘，以及供应商通知积压和证书30天/7天到期监测。
|
||
- 告警Webhook通知与联通测试：未静默的新告警和超时升级与事件记录同事务进入Outbox，Worker按临时/永久错误分类重试，并使用稳定事件编号和HMAC-SHA256签名投递；运营人员可针对活动路由发起不生成正式告警的联通测试，查询投递状态并受控重试失败任务。
|
||
- 告警接收器一致性报告：离线核对全部活动路由、云端`DELIVERED`任务、真实网关唯一验签回执、主/升级值班组映射和一次正式演练；本地模拟报告固定不能放行阶段8真实接收器门禁。
|
||
- KMS/HSM轮换一致性报告：绑定候选构建、工作负载身份、提供器版本、云审计、新旧凭据认证和业务连续性，同时覆盖动态读取与滚动重启；本地环境密钥演练固定不能放行真实云密钥门禁。
|
||
- 生产恢复一致性报告：同一候选必须覆盖PostgreSQL恢复、Redis重建、三个服务滚动重启和供应商停机恢复，并证明数据一致、业务连续和无重复效果；本地恢复子集不能放行生产门禁。
|
||
- 外部基础设施探针：API周期校验OIDC JWKS可读取且至少包含一把公钥；生产API/Worker对方舟和火山RTC执行无业务副作用的DNS、TCP和证书校验TLS握手，结果进入Prometheus且不因供应商短时故障驱逐健康Pod。
|
||
- 生产基础设施一致性报告：按同一候选核对域名TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控的真实控制项及证据引用；本地Compose可达性不会放行生产门禁。
|
||
- Safari兼容性一致性报告：以两个真实Safari版本、两种视口和六条关键流程组成24项精简矩阵；Chrome/Edge或Playwright WebKit不能冒充真实Safari验收。
|
||
- 真实终端RTC一致性报告：至少3台候选终端以6通精简矩阵覆盖三种语音方式正常闭环、凭证续签、网络切换恢复和受控停止；模拟供应商不能放行。
|
||
- 真实Agent模型一致性报告：重新计算已有10类Agent固定评测，并绑定Embedding六类召回/隔离、内容安全六类策略、数据条款和额度；本地模型不能放行。
|
||
- 远程CI供应链一致性报告：绑定完整源提交、托管CI运行、14项构建与安全检查、后端/Web镜像摘要和源码/双镜像三份CycloneDX SBOM；本地工具链不能放行。
|
||
- 发布候选证据包：技术验收快照通过后，把十类外部证据索引、OpenAPI、迁移、Kubernetes清单、关键交付文档和可用SBOM封装为逐文件SHA-256清单ZIP；真机固件门禁要求至少3台设备各完成4个硬件场景，`PILOT`类型还强制携带同租户、同候选版本/构建摘要、同自然周的7份日报和1份完整周报，任何缺口保持待验，不会把本地模拟冒充生产验收。
|
||
- 试点运行日报：绑定候选版本与不可变构建摘要后，按IANA业务时区自然日下载设备、通话、供应商、上传、告警和分币种费用的脱敏快照；日报有租户隔离、幂等和审计，但不保存服务端正文，也不代替真机体验、供应商账单或发布审批。
|
||
- 试点运行周报：绑定同一候选构建后，按周一开始的业务自然周下载内容审核、记忆、隐私请求、固件和配置差异；比例同时展示样本，无样本不伪造0%，投诉因无平台权威表固定要求附客服或CRM证据。
|
||
- Docker Compose本地环境：PostgreSQL、Redis、MinIO、Keycloak、迁移、三个后端进程、模拟供应商和Web。
|
||
- Kubernetes/Kustomize预生产与生产基线：API、Callbacks、Worker、Web、独立迁移Job、Secret只读卷、探针、资源限额、滚动发布、PDB/HPA、Ingress和入口网络隔离；清单不包含真实密钥。
|
||
- Secrets Store CSI生产覆盖层：应用和迁移Job可直接挂载外部KMS/Secret Manager内容，不经过普通ConfigMap或明文环境变量；逐设备密钥支持挂载后即时轮换，其他进程级密钥通过受控滚动重启生效。
|
||
- 本地检查脚本与持续集成基础流水线。
|
||
|
||
## 快速启动
|
||
|
||
前置条件：Go 1.26、Node.js 24、Docker Desktop与Docker Compose。
|
||
|
||
完整容器环境：
|
||
|
||
```powershell
|
||
Set-Location E:\Codex\story\platform
|
||
.\scripts\dev.ps1
|
||
```
|
||
|
||
启动成功后访问：
|
||
|
||
- Web：<http://localhost:3100>
|
||
- API存活检查：<http://localhost:58080/health/live>
|
||
- API就绪检查：<http://localhost:58080/health/ready>
|
||
- MinIO控制台：<http://localhost:59001>
|
||
- Keycloak：<http://localhost:58180>
|
||
- Prometheus：<http://localhost:59190>
|
||
- Grafana：<http://localhost:59300>
|
||
- 模拟语音供应商存活检查：<http://localhost:59200/health/live>
|
||
- 模拟告警接收器存活检查：<http://localhost:59210/health/live>
|
||
|
||
本地Web点击“登录研发环境”后可使用`owner`、`editor`或`outsider`三个合成账号，密码均为`LocalOnly123!`。账号只用于本机联调，权限说明见[家庭角色权限矩阵](docs/permission-matrix.md)。
|
||
|
||
Web镜像在容器启动时根据`WEB_OIDC_AUTHORITY`和`WEB_OIDC_CLIENT_ID`生成不缓存的`runtime-config.js`。dev、preprod和prod可复用同一镜像，只需为各环境设置对应OIDC地址和客户端编号；这些值是浏览器可见的公开配置，不能用于保存客户端密钥。
|
||
|
||
真实火山RTC模式由两组独立开关启用：API设置`RTC_TOKEN_ISSUER=volcengine`、`RTC_APP_ID`和`RTC_APP_KEY`，Worker设置`VOICE_PROVIDER=volcengine`、`VOLC_ACCESS_KEY_ID`、`VOLC_SECRET_ACCESS_KEY`、区域、接口版本以及`VOLC_VOICE_CHAT_TEMPLATE_FILE`。生产模板采用`voice-chat-template-bundle-v1`，分别提供`s2s_pure`、`s2s_hybrid`和`cascade`三个完整VoiceChat `Config/AgentConfig`；平台按通话冻结模式选择模板，再覆盖AppId、RoomId、TaskId、目标设备用户、智能体用户，并追加本次已授权且脱敏的背景摘要。可从[模板示例](deploy/volcengine/voice-chat-template.example.json)复制结构并按照已开通的官方能力替换每个完整`Config`对象；不要把AppKey、AK/SK、ASR/TTS Token提交到仓库。
|
||
|
||
生产API必须设置`DEVICE_SECRET_DIRECTORY`为容器内绝对路径，并把Docker/Kubernetes Secret或云KMS CSI卷只读挂载到该目录。每台设备的`credential_ref`写为`device-secret://terminal-001`，对应文件名为`terminal-001`，文件内容为至少32字节的独立随机密钥。解析器拒绝相对路径、子目录、越界符号、缺失文件和短密钥；每次验签重新读取文件，因此密钥文件原子轮换后立即生效。`DEVICE_LOCAL_SECRET`只允许本地模拟使用。
|
||
|
||
数据库连接串、Redis、RTC AppKey、火山AK/SK、方舟API Key、对象存储凭据、回调/告警签名等敏感配置同时支持`NAME_FILE=/run/secrets/name`。文件路径必须是容器内绝对路径、目标必须是普通文件且不超过64KiB；读取时只去掉末尾换行，不在错误中打印内容。`NAME`与`NAME_FILE`同时存在会拒绝启动，防止轮换时仍意外使用旧的明文环境变量。
|
||
|
||
独立启动后端时，告警外部通知在未配置地址时安全关闭；本地Compose默认连接仓库内的验签模拟接收器，便于验证真实Worker投递而不访问外部网络。接入企业协作平台或通知网关时，为Worker设置`ALERT_WEBHOOK_URL`、至少32字符的`ALERT_WEBHOOK_SECRET`和可选的`ALERT_WEBHOOK_TIMEOUT`；生产地址必须使用HTTPS。接收端应使用`X-Voice-Event-ID`去重，并按`v1=HMAC-SHA256(secret, timestamp + "." + body)`校验`X-Voice-Signature`。运营工作台可针对活动路由发起联通测试；测试原因只写审计，不发送给接收端。
|
||
|
||
外部依赖探针默认每30秒执行一次，可通过`EXTERNAL_PROBE_INTERVAL`调整。OIDC探针验证JWKS HTTP状态、JSON格式和非空密钥集；方舟、火山RTC及托管内容安全探针只验证DNS、TCP、TLS 1.2以上协议和受信证书，不调用推理、创建房间、启动语音任务或发送待分类正文。探针失败只产生指标与告警，不进入Kubernetes readiness，避免供应商故障引发Pod重启风暴。
|
||
|
||
内容生成默认使用`CONTENT_GENERATOR=local`。接入火山方舟时设置`CONTENT_GENERATOR=ark`、`ARK_BASE_URL`、`ARK_API_KEY`、`ARK_CONTENT_MODEL`和`ARK_REQUEST_TIMEOUT`；Worker调用`${ARK_BASE_URL}/chat/completions`。生产环境拒绝本地生成器、HTTP地址、占位API Key或本地模型编号。
|
||
|
||
内容安全默认使用`CONTENT_SAFETY_PROVIDER=local`作为开发基线。生产Worker必须配置`managed_http`、HTTPS端点、独立API Key、经批准的策略版本和超时；高风险输入先在本地拦截，其余输入及模型输出通过托管策略复核，策略服务异常时停止生成和落库。协议、错误语义与接入步骤见[《生产内容安全服务适配》](docs/content-safety-provider.md)。
|
||
|
||
进入目标环境联调前，可运行`scripts/stage8-preflight.ps1`检查候选提交、远程仓库、Compose本地基线和十类外部证据索引状态。预检不会读取密钥值或把本地模拟结果视为外部验收通过，详细说明见[《真机、真实供应商、试点与生产发布外部验收清单》](docs/external-acceptance-checklist.md)。
|
||
|
||
记忆向量默认使用`EMBEDDING_PROVIDER=local`。接入方舟时，API和Worker必须同时设置`EMBEDDING_PROVIDER=ark`、同一个`ARK_BASE_URL`、`ARK_API_KEY`和`ARK_EMBEDDING_MODEL`；平台请求并强校验1536维向量。生产环境拒绝本地向量提供器，避免索引向量和查询向量落入不同空间。
|
||
|
||
生产集群部署清单位于[`deploy/kubernetes`](deploy/kubernetes)，详细的镜像构建、外部依赖、Secret/CSI文件名、迁移、发布、轮换、检查和回滚步骤见[《Kubernetes部署手册》](docs/kubernetes-deployment.md)。基线中的`.example.invalid`、全零RTC App ID和`replace-with-*`均是故意保留的不可用占位值，生产启动门禁会拒绝这些值，必须由环境覆盖层替换后才能发布。
|
||
|
||
只启动基础依赖并在宿主机开发：
|
||
|
||
```powershell
|
||
docker compose up -d postgres redis minio keycloak migrate
|
||
go run ./cmd/api
|
||
```
|
||
|
||
宿主机默认使用API端口`58080—58082`、PostgreSQL端口`55432`、Redis端口`56379`、OTLP端口`54317`和Prometheus端口`59190`，避免与开发机现有服务冲突；可在`.env`中覆盖。容器间仍使用各组件的标准端口。
|
||
|
||
另开终端启动前端：
|
||
|
||
```powershell
|
||
Set-Location E:\Codex\story\platform\web
|
||
npm ci
|
||
npm run generate:api
|
||
npm run dev
|
||
```
|
||
|
||
## 质量检查
|
||
|
||
日常开发默认执行轻量功能就绪检查：
|
||
|
||
```powershell
|
||
Set-Location E:\Codex\story\platform
|
||
.\scripts\check-functional.ps1
|
||
```
|
||
|
||
该脚本检查必要容器、Web与三个后端进程、模拟供应商、模拟告警接收器、数据库/Redis/对象存储/OIDC依赖、Outbox积压和近期错误日志。功能改动再配合对应Go包测试或单项烟测，不要求每次执行全量回归。
|
||
|
||
发布候选或CI执行全量质量门禁：
|
||
|
||
```powershell
|
||
Set-Location E:\Codex\story\platform
|
||
.\scripts\check.ps1
|
||
```
|
||
|
||
该脚本执行Go格式检查、静态检查、单元测试、OpenAPI类型生成、前端类型检查、前端构建和Compose语法检查。
|
||
|
||
阶段8候选证据包的输入、十类外部门禁、真机固件场景覆盖、状态语义、归档结构和命令见[《发布候选证据包说明》](docs/release-evidence-bundle.md)，真实终端RTC六通矩阵见[《真实终端与RTC/语音供应商一致性证据》](docs/real-device-rtc-evidence.md)，生成/Embedding/内容安全见[《真实Agent模型质量一致性证据》](docs/real-agent-models-evidence.md)，生产七类组件采集见[《生产基础设施一致性证据》](docs/production-infrastructure-evidence.md)，真实Safari精简矩阵见[《Safari兼容性一致性证据》](docs/safari-compatibility-evidence.md)。可先执行`.\scripts\smoke-release-evidence.ps1`验证本地真实OIDC快照到ZIP清单的纵向链路；该烟测不会把外部待验项改为通过。试点每日证据见[《试点运行日报开发说明》](docs/pilot-daily-operations.md)，周度复盘口径、外部投诉缺口、接口和轻量烟测见[《试点运行周报开发说明》](docs/pilot-weekly-review.md)。
|
||
|
||
完整本地环境运行后执行身份与数据库集成冒烟：
|
||
|
||
```powershell
|
||
.\scripts\smoke-auth.ps1
|
||
```
|
||
|
||
执行设备签名、启动和配置联调：
|
||
|
||
```powershell
|
||
docker compose --profile simulation run --rm sim-device
|
||
```
|
||
|
||
执行模拟设备断网重连、完整通话、重复请求、字幕补交、遥测和命令场景：
|
||
|
||
```powershell
|
||
docker compose --profile simulation run --rm -e SIM_SCENARIO=offline,conversation,transcript,telemetry,commands sim-device
|
||
```
|
||
|
||
还可用`SIM_SCENARIO=media`和`SIM_CONVERSATION_ID`验证已授权通话的录音直传、后台校验、延迟删除及设备删除回执；详见`docs/device-integration.md`。
|
||
|
||
执行设备状态、错误和命令结果的批量遥测、幂等、事件判重及冲突回滚烟测：
|
||
|
||
```powershell
|
||
.\scripts\smoke-device-telemetry.ps1
|
||
```
|
||
|
||
执行创建、激活、供应商启动、重复回调、心跳租约、停止和最终`COMPLETED`状态的完整冒烟：
|
||
|
||
```powershell
|
||
.\scripts\smoke-conversation.ps1
|
||
```
|
||
|
||
执行家庭、长者、授权、角色隔离、ETag和授权快照纵向冒烟：
|
||
|
||
```powershell
|
||
.\scripts\smoke-saas.ps1
|
||
```
|
||
|
||
执行设备读取、在线状态、影子配置、敏感字段拒绝和一次性绑定码烟测：
|
||
|
||
```powershell
|
||
.\scripts\smoke-device-management.ps1
|
||
```
|
||
|
||
执行成员邀请、跨客户组织接受、角色并发、所有权保护与转移烟测：
|
||
|
||
```powershell
|
||
.\scripts\smoke-members.ps1
|
||
```
|
||
|
||
执行隐私数据访问请求的权限、幂等、后台子任务和范围盘点烟测：
|
||
|
||
```powershell
|
||
.\scripts\smoke-privacy.ps1
|
||
```
|
||
|
||
执行私有桶、导出范围、短期签名下载、摘要和过期删除烟测：
|
||
|
||
```powershell
|
||
.\scripts\smoke-export.ps1
|
||
```
|
||
|
||
执行主体立即冻结、活动通话保护、六子系统删除对账、正文脱敏和墓碑证明烟测（UTF-8脚本建议使用PowerShell 7）：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-privacy-delete.ps1
|
||
```
|
||
|
||
执行设备命令排队、签名拉取和分阶段回执烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-device-commands.ps1
|
||
```
|
||
|
||
执行固件角色、跨域私有直传、签名校验、列表查询、非法签名拒绝、灰度暂停、下载/安装进度和回滚烟测：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-firmware-rollout.ps1
|
||
```
|
||
|
||
执行双轨录音直传、后台校验、错误摘要拒绝、本地删除回执、独立播放/下载授权和访问审计烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-media-upload.ps1
|
||
```
|
||
|
||
执行SSE断点续传、权限隔离、过期游标及设备在线/离线状态事件烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-web-events.ps1
|
||
pwsh -NoProfile -File .\scripts\smoke-device-presence-events.ps1
|
||
```
|
||
|
||
执行具体资源分享的幂等、权限、撤销、过期和访问审计烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-sharing.ps1
|
||
```
|
||
|
||
执行运营角色、评测/资源门禁、灰度投放、资源撤销、回滚和新通话版本冻结烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-ops-config.ps1
|
||
```
|
||
|
||
执行价格双人发布、七类用量去重核价、运营/家庭脱敏汇总、预算快照和硬额度烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-billing.ps1
|
||
```
|
||
|
||
执行告警路由、自动发现、超时升级、版本冲突、确认—缓解—关闭、静默和重新打开烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-alerts.ps1
|
||
```
|
||
|
||
执行联调诊断的五类精确检索、跨租户拒绝、安全停止、状态对账、配置刷新、死信受控重试、脱敏诊断包、合成设备吊销和审计关联烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-diagnostics.ps1
|
||
pwsh -NoProfile -File .\scripts\smoke-acceptance-snapshot.ps1
|
||
```
|
||
|
||
执行敏感数据临时访问申请、自批拒绝、双人审批、申请人绑定、字幕读取和逐次审计烟测：
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\smoke-ops-sensitive-access.ps1
|
||
```
|
||
|
||
执行需求规定的本地专项容量、恢复和HTTP安全门禁：
|
||
|
||
```powershell
|
||
# 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
|
||
|
||
# 500回调/秒持续10分钟，并校验30万唯一事件
|
||
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
|
||
pwsh -NoProfile -File .\scripts\verify-postgres-restore.ps1
|
||
pwsh -NoProfile -File .\scripts\verify-runtime-recovery.ps1
|
||
pwsh -NoProfile -File .\scripts\verify-provider-outage.ps1
|
||
pwsh -NoProfile -File .\scripts\security-http-smoke.ps1
|
||
```
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
cmd/ 三个可部署进程入口
|
||
internal/ 平台公共能力及后续领域模块
|
||
migrations/ 仅追加的数据库迁移
|
||
openapi/ 对外接口契约基线
|
||
web/ 家庭用户和运营网页
|
||
deploy/ 容器构建与运行配置
|
||
docs/ 架构决策与研发基线
|
||
scripts/ 本地启动和质量检查脚本
|
||
test/ 契约、集成和端到端测试
|
||
```
|
||
|
||
公共接口约束与监控指标见[可观测性与接口治理设计](docs/observability-and-api-governance.md)，设备签名和模拟联调见[设备接入与启动配置联调说明](docs/device-integration.md)，设备命令见[设备命令可靠下发说明](docs/device-commands.md)，固件流程见[固件制品、签名、灰度与回滚开发说明](docs/firmware-rollout.md)，A/B升级与启动失败回退见[设备A/B分区固件升级与启动确认协议](docs/device-firmware-ab-protocol.md)，设备/云端时间线对账见[固件真机联调一致性证据采集与校验说明](docs/firmware-conformance-evidence.md)，双轨录音见[双轨录音上传、校验与访问开发说明](docs/media-upload-and-access.md)，网页状态通知见[Web状态事件流开发说明](docs/web-event-stream.md)，具体分享见[具体资源分享开发说明](docs/resource-sharing.md)，运营配置见[内部运营身份与运行配置版本开发说明](docs/operations-config.md)，用量费用与额度见[用量、费用与额度开发说明](docs/usage-cost-quota.md)，告警闭环见[告警监测与运营处置开发说明](docs/alert-operations.md)，真实网关归档见[告警接收器一致性证据](docs/alert-receiver-conformance-evidence.md)，云密钥轮换见[KMS/HSM轮换一致性证据](docs/kms-hsm-rotation-evidence.md)，生产恢复见[生产等价恢复演练一致性证据](docs/production-recovery-evidence.md)，生产基础设施见[生产基础设施一致性证据](docs/production-infrastructure-evidence.md)，联调工作台及发布候选验收快照见[集成诊断工作台开发说明](docs/integration-diagnostics.md)，试点每日证据见[试点运行日报开发说明](docs/pilot-daily-operations.md)，试点周度复盘口径、外部投诉缺口、接口和轻量烟测见[试点运行周报开发说明](docs/pilot-weekly-review.md)，敏感数据提权见[运营敏感数据临时访问开发说明](docs/ops-sensitive-access.md)，外部上线阶段见[真机、真实供应商、试点与生产发布外部验收清单](docs/external-acceptance-checklist.md)，生产门禁和压测告警见[压测、告警与生产安全门禁](docs/load-alerting-and-production-security.md)，专项实测证据见[性能、恢复、安全与兼容性专项验证报告](docs/performance-recovery-security-compatibility.md)，隐私数据访问见[隐私数据请求开发说明](docs/privacy-requests.md)，私有导出见[私有数据导出开发说明](docs/data-export.md)。
|
||
|
||
从框架搭建到生产落地的阶段任务、里程碑、人员、测试门禁、依赖和风险见[详细开发计划](docs/development-plan.md)，当前实际完成证据见[开发状态与门禁记录](docs/development-status.md)。
|
||
|
||
## 安全提醒
|
||
|
||
本地环境只允许使用合成数据。不要把生产Token、证书、设备私钥、供应商长期密钥、真实录音或真实个人资料写入仓库、`.env`、日志或测试夹具。
|