5.3 KiB
HEL-748 · S1 实现与接线说明
本轮范围是可构建的完整前端及离线演示，不部署，不实现 B1–B3。基于正式仓库 main 的 1e9b08aed81b4ebf163721232a8d65707b1c3183 新建任务分支；检出时工作区干净，无仓库内额外 AGENTS，无平台关联 PR。未改 Python 核心、既有测试、服务配置、SSH 信任、端口、GPU 或模型。
依据为本卡《整套设计验收与施工裁定-v1》、HEL-746 R2、HEL-738 结构与接口边界和需求 v1.6。名字、关系不预选、未分享即隐藏三项裁定覆盖旧原型。首建底色明确为示例，真实排盘待接已有 Python 编译器，不在浏览器重写八字规则。
主要目录与职责：
web/src/app/：入口、首建守卫、导航、全局 UI 偏好、返回/主动/断线演示。web/src/manage/：四步首建；只读身份；关系/城市/服务/显示草稿；保存取消失败；外观标识；演示导出与同身份恢复。web/src/chat/：文字草稿、IME 与快捷键、字幕/记录、取消重试、模拟语音/观察授权及结束。web/src/life/：生活与四类回忆、双向关联、原位保留、手机详情推入、分页和深链守卫。web/src/domain/：模型、首建校验、公开视图。所有可见事件、回忆、消息、摘要统一经过publicView，未知关联默认拒绝；详情也从公开视图查找。web/src/adapters/：独立可替换聊天适配器、turn_id/epoch 门槛、AbortController、本地持久化、严格 JSON 重建校验。web/src/demo/：固定场景数据，与页面和传输分离。web/src/stage/：背景空间与FallbackPresenter。Presenter 只消费 SceneDesc，不写生活；参考图片失效也有文字降级，不黑屏。web/src/shared/：复用按钮、图标、字段、状态和带焦点边界的确认弹层。web/src/styles/：R2 单一 Token 和组件样式来源；没有第三方 UI 皮肤或叠加覆盖样式表。
两主题使用相同 DOM 和布局；人物拱窗、交谈展开、阅读面板与手机断点沿用获批样式。静帧仅呈现参考人物/房间，不渲染整页图片。语音/观察不访问 getUserMedia、不调用 ASR/TTS、不发外部请求。演示天气固定并标注模拟；当前视觉标签来自演示记录公开视图。
F1–F9 走法：
| 流程 | 入口与边界 |
|---|---|
| F1 | 无本机档案 → 四步创建 → 名字/成年生日/关系/勾选校验 → 本机持久化 → 首晚空生活 |
| F2 | 普通入口说明未接服务 → 明确演示入口；重开直接回到同一位她 |
| F3 | 演示场景 → 模拟两天后返回；只从已分享数据生成摘要，不生成后台生活 |
| F4 | 演示场景 → 主动消息；来源是已分享事件，回她定位聊天并保留来源区域 |
| F5 | 交流麦克风 → 模拟授权 → 倾听界面；文字发送推进思考/说话，可打断/结束；无真实收音 |
| F6 | 演示断线 → 暂停发送，保留草稿，结束模拟语音、取消旧轮；恢复失败可重试，不自动重发 |
| F7 | 设置城市 → 搜索/选择 → 保存成功/失败/重试；不调用天气 API |
| F8 | 本地演示素材 JSON → 结构检查/模拟对比/确认；只更新外观标识，真实媒体导入待后续 |
| F9 | 本地演示 JSON 下载/同身份校验/输入确认/先导出再恢复；服务器备份明确未接通 |
取消与错误：新轮、手动取消、切离交流会 abort 当前模拟回复；事件还需同时匹配 turn_id 与 epoch，非协作适配器的迟到消息同样被门槛拒绝。断线 resync 提升 epoch；恢复不自动续接旧轮。管理保存切区/关区会 abort；草稿保留，取消恢复上次提交值；存储损坏不进入新的首建覆盖。导入只执行 JSON.parse 后按固定 schema 重建；不执行脚本、不作为 HTML、不加载媒体/服务 URL。
后续接线清单（当前均未提供）：
- B1 同源 API 与 WS：hello/sync、游标和持久 epoch、能力声明、HTTP AbortSignal。真实模式不得直接替换成未经审定的 LLM URL。
- 服务端授权与隐私：必须在响应前裁剪未分享记录、未知引用、回忆和消息及摘要；本轮前端过滤不构成服务器权限控制。
- 接已有 Python 生辰预览/只读档案、真实关系更新；身份 ID、底色指纹由服务端负责。
- B2/B3 后台生活、主动性、记忆与增长层；前端只订阅 LifeScene/事件，不从素材反编生活。
- S2 流式文字；S3 ASR/TTS 二进制协议、session_id/seq 隔离、权限与实际中断；当前没有真实音频流，因此不声称达到延迟指标。
- S4 生活/回忆服务分页；S5 城市/天气、素材包校验和完整服务器备份/自动备份；演示 JSON 的 MIME 和结构不是媒体真伪校验。
- S6 视觉摘要时效与 HTTPS、真实权限；Presenter 的视频/音频/口型驱动器可注入，当前只交静帧降级。
测试部署由总工审核后执行。建议在独立目录安装构建，将 web/dist/ 作为静态站点挂到总工选定的未占用测试端口；正常路径 /，演示 /?demo=1。本轮未占用固定服务端口，也未更改 8010/18080/18081 或现网。部署若换 origin，浏览器本地演示资料不会自动迁移，可通过同身份演示 JSON 手动恢复。