|
|
@@ -0,0 +1,526 @@
|
|
|
+# 现场记录详情页左侧：iOS 回放功能等价复刻 PRD
|
|
|
+
|
|
|
+版本：v1.0
|
|
|
+日期：2026-07-25
|
|
|
+目标项目：`/Users/yuxin/local/code/celestia-trace/frontend`
|
|
|
+
|
|
|
+## 1. 结论
|
|
|
+
|
|
|
+网页端当前左侧仅实现了“看起来像播放器和事件列表”的基础框架，尚未与 iOS 回放页功能等价。必须重做为真实数据驱动版本：
|
|
|
+
|
|
|
+- 只播放服务器实际音频；不得生成模拟音频掩盖文件缺失或下载失败。
|
|
|
+- 波形必须从实际音频按与 iOS 相同的规则提取；不得使用正弦函数绘制装饰波形。
|
|
|
+- 必须复刻三轨时间线、可拖动播放头、真实静音分析与跳过、照片/笔记/位置的增删改查、事件详情、全屏图片、标题持久化、同步状态和分享。
|
|
|
+- 网页端所有编辑必须写回云端，并能被 iOS 下一次同步正确拉取。
|
|
|
+- 页面结构、配色、字号、边框、圆角、图标语义和空状态应与 iOS 保持统一；网页右侧 AI 区域不在本 PRD 范围内。
|
|
|
+
|
|
|
+## 2. 产品目标
|
|
|
+
|
|
|
+用户在网页端打开一条已同步现场记录后，能够在左侧完成与 iOS `SessionDetailView` 相同的查看、回放、定位和事件编辑任务；同一条记录在网页与 iOS 之间应保持数据、时间位置和操作结果一致。
|
|
|
+
|
|
|
+## 3. 范围与基准
|
|
|
+
|
|
|
+### 3.1 iOS 功能基准
|
|
|
+
|
|
|
+以当前工作区源码为准：
|
|
|
+
|
|
|
+- `SessionDetailView.swift`
|
|
|
+- `MultiTrackTimeline.swift`
|
|
|
+- `PlaybackViewModel.swift`
|
|
|
+- `ChronoFeedRow.swift`
|
|
|
+- `ImagePicker.swift`
|
|
|
+- `TimelineLocationPicker.swift`
|
|
|
+- `CelestiaSession.swift`
|
|
|
+- `CelestiaTimelineEvent.swift`
|
|
|
+- `RemoteNetworkService.swift`
|
|
|
+
|
|
|
+注意：审计时 iOS 工作区的 `SessionDetailView.swift` 和 `MultiTrackTimeline.swift` 存在未提交修改，本 PRD按当前文件内容而非仅按 `master` 最新提交定义功能。
|
|
|
+
|
|
|
+### 3.2 页面范围
|
|
|
+
|
|
|
+网页详情页继续保留左右双栏：
|
|
|
+
|
|
|
+- 左侧：完整复刻 iOS 回放与事件管理能力，本 PRD范围。
|
|
|
+- 右侧：AI 逐字稿与报告区域，维持现状，不得影响左侧布局和滚动。
|
|
|
+- 顶部全局栏可保留“返回/关闭”，但记录标题、同步、Info、分享的布局和状态表达必须与 iOS 统一。
|
|
|
+
|
|
|
+## 4. 信息架构与页面顺序
|
|
|
+
|
|
|
+左侧内容从上到下固定为：
|
|
|
+
|
|
|
+1. 记录标题 + 紧凑同步状态。
|
|
|
+2. 三轨时间线：音频、图片、笔记。
|
|
|
+3. 回放控制卡。
|
|
|
+4. 事件列表。
|
|
|
+
|
|
|
+顶部或标题区同时提供：
|
|
|
+
|
|
|
+- 记录信息 Info。
|
|
|
+- 分享录音。
|
|
|
+- 返回/关闭网页详情。
|
|
|
+
|
|
|
+不得继续在左侧增加“与 iOS App 保持一致”等自我说明标签，也不得用独立的“添加网页端标记”表单替代轨道点击交互。
|
|
|
+
|
|
|
+## 5. PRD 功能清单
|
|
|
+
|
|
|
+### A. 页面加载与真实数据
|
|
|
+
|
|
|
+#### IOS-WEB-001 获取最新详情
|
|
|
+
|
|
|
+- 打开详情时必须调用 `GET /sessions/{id}`，不得只依赖列表页传入的旧对象。
|
|
|
+- 加载期间显示骨架或进度状态；失败时显示可重试错误。
|
|
|
+- 成功后统一建立 `session / events / assets / revision` 页面状态。
|
|
|
+- 事件按 `relativeTimeMs` 升序排列。
|
|
|
+
|
|
|
+验收：
|
|
|
+
|
|
|
+- 在另一端修改记录后，重新打开网页能读取新版本。
|
|
|
+- 详情请求失败时不展示伪造事件、音频、统计或同步状态。
|
|
|
+
|
|
|
+#### IOS-WEB-002 实际音频加载
|
|
|
+
|
|
|
+- 从 `assets` 中筛选 `kind=AUDIO` 的资源。
|
|
|
+- 若存在多个音频资产，按 iOS 同步规则选择最新有效资产，不得直接使用数组第一个。
|
|
|
+- 通过鉴权接口下载或流式读取真实音频。
|
|
|
+- 音频不存在、下载失败或解码失败时，显示明确不可播放状态。
|
|
|
+- 禁止创建合成 WAV 作为回退。
|
|
|
+
|
|
|
+验收：
|
|
|
+
|
|
|
+- 播放内容与用户实际现场录音一致。
|
|
|
+- 缺少音频时播放按钮不可伪装成功，并显示“当前记录没有可播放的录音文件”。
|
|
|
+
|
|
|
+### B. 标题、信息与分享
|
|
|
+
|
|
|
+#### IOS-WEB-010 记录标题展示与编辑
|
|
|
+
|
|
|
+- 标题左对齐，单行显示，过长截断。
|
|
|
+- 点击标题进入独立编辑浮层/弹窗，不使用常驻行内输入框挤压布局。
|
|
|
+- 自动聚焦；若标题以“现场记录”结尾，首次进入时只选中这四个字。
|
|
|
+- 保存前去除首尾空白；空标题禁止保存。
|
|
|
+- 保存后写回云端并更新 `revision`，不能只修改前端内存对象。
|
|
|
+- 取消时恢复原值。
|
|
|
+
|
|
|
+#### IOS-WEB-011 记录信息 Info
|
|
|
+
|
|
|
+Info 面板必须展示：
|
|
|
+
|
|
|
+- 开始日期与时间，中文格式，精确到秒。
|
|
|
+- 结束日期与时间；无结束时间时显示“进行中”。
|
|
|
+- 总时长。
|
|
|
+- 图片数量。
|
|
|
+- 笔记数量；普通 `MARKER` 计入，续录标记不计入。
|
|
|
+- 当前本地内容版本/网页正在编辑的版本。
|
|
|
+- “续录”入口。
|
|
|
+
|
|
|
+视觉要求：
|
|
|
+
|
|
|
+- 内容为紧凑卡片，不在主页面正文中常驻展开。
|
|
|
+- 分隔线、10–13px 辅助字号、等宽数字、1px 低对比边框与 iOS 一致。
|
|
|
+
|
|
|
+#### IOS-WEB-012 分享/导出实际录音
|
|
|
+
|
|
|
+- 分享文件名取记录标题，替换 `/:\?%*|"<>`、控制字符和换行，清除尾部句点与空白。
|
|
|
+- 空结果回退为“现场记录”。
|
|
|
+- 支持 Web Share API 时调用系统分享；不支持时直接下载。
|
|
|
+- 分享/下载的是实际音频文件。
|
|
|
+- 无音频时显示不可分享原因；不得仅显示“资源已准备”Toast。
|
|
|
+
|
|
|
+### C. 同步状态
|
|
|
+
|
|
|
+#### IOS-WEB-020 紧凑同步按钮
|
|
|
+
|
|
|
+状态至少包括：
|
|
|
+
|
|
|
+- 正在同步：圆环进度 + 旋转同步图标 + 百分比。
|
|
|
+- 已同步：金色云端完成图标。
|
|
|
+- 未同步：灰色上传云图标。
|
|
|
+- 失败：错误状态与重试入口。
|
|
|
+- 冲突：明确提示版本冲突，禁止静默覆盖。
|
|
|
+
|
|
|
+行为：
|
|
|
+
|
|
|
+- 未同步点击后执行保存/上传。
|
|
|
+- 正在同步点击后允许暂停或取消当前上传。
|
|
|
+- 已同步点击后打开同步信息。
|
|
|
+- 其他记录正在同步时，本记录按钮禁用或排队。
|
|
|
+
|
|
|
+#### IOS-WEB-021 同步信息面板
|
|
|
+
|
|
|
+展示：
|
|
|
+
|
|
|
+- 最近同步时间，中文，精确到秒。
|
|
|
+- 云端版本 `v{revision}`。
|
|
|
+- 云端记录 ID，可选择复制。
|
|
|
+
|
|
|
+#### IOS-WEB-022 网络、登录和大文件边界
|
|
|
+
|
|
|
+- 无网络：提示连接网络后重试。
|
|
|
+- 登录失效：进入重新登录流程，不得丢失未提交草稿。
|
|
|
+- 预计上传量达到 70 MiB：同步前显示文件大小、网络类型和确认。
|
|
|
+- 版本冲突：使用 `baseRevision` 触发 409 保护，不做最后写入者静默覆盖。
|
|
|
+
|
|
|
+### D. 三轨时间线
|
|
|
+
|
|
|
+#### IOS-WEB-030 总体结构
|
|
|
+
|
|
|
+时间线包含：
|
|
|
+
|
|
|
+1. 时间刻度。
|
|
|
+2. 音频轨：真实波形、静音背景、续录标记。
|
|
|
+3. 图片轨：照片记录点。
|
|
|
+4. 笔记轨：笔记和普通标记。
|
|
|
+5. 一条贯穿三轨的播放头。
|
|
|
+6. 下方图例：音频、图片、笔记；存在续录标记时增加“续录”。
|
|
|
+
|
|
|
+轨道左侧保留约 24–30px 图标区，分别使用波形、相机、文档图标。
|
|
|
+
|
|
|
+#### IOS-WEB-031 横向尺寸与刻度
|
|
|
+
|
|
|
+- 时间线最小内容宽度 400px。
|
|
|
+- 基准比例为约 2.5px/秒，并在左右各保留约 30px。
|
|
|
+- 长记录允许横向滚动，隐藏原生滚动条但保留触控板、滚轮和触摸拖动。
|
|
|
+- 小于等于 60 秒：每 5 秒刻度。
|
|
|
+- 60–300 秒：每 10 秒刻度。
|
|
|
+- 大于 300 秒：每 60 秒刻度。
|
|
|
+- 刻度格式为 `m:ss`。
|
|
|
+
|
|
|
+#### IOS-WEB-032 真实波形
|
|
|
+
|
|
|
+- 从实际音频以 50ms 为时间窗提取 RMS。
|
|
|
+- 振幅按 iOS 相同的 `-50dB → 0...1` 线性规则归一化。
|
|
|
+- 按可见宽度聚合采样，每列取该区间最大振幅。
|
|
|
+- 视觉规则：1px 柱宽、2px 间距、围绕中心线绘制、最大约占音轨高度 75%。
|
|
|
+- 音轨高度约 90px；事件轨高度约 34px。
|
|
|
+- 音频实际时长是回放、波形和时间线的权威总时长，不能优先使用墙钟时长。
|
|
|
+
|
|
|
+#### IOS-WEB-033 静音区间
|
|
|
+
|
|
|
+- 音频分析同一遍同时产出波形和静音区间。
|
|
|
+- 静音区间在音频轨用低对比背景矩形标示。
|
|
|
+- 分析中显示加载状态。
|
|
|
+- 分析完成显示“检测到 N 处静音”；没有静音时不伪造数量。
|
|
|
+
|
|
|
+#### IOS-WEB-034 播放头
|
|
|
+
|
|
|
+- 播放头是 1px 高对比竖线，贯穿时间线。
|
|
|
+- 可直接拖动；有效拖动热区至少 28px。
|
|
|
+- 拖动位置限制在 `0...实际音频时长`。
|
|
|
+- 拖动时实时同步音频位置和下方进度条。
|
|
|
+- 正常播放时播放头自动滚动到可视区域中央。
|
|
|
+- 用户拖动期间关闭自动居中和缓动，避免跳动。
|
|
|
+- 键盘可聚焦，方向键每次调整 1 秒，并暴露当前时间给辅助技术。
|
|
|
+
|
|
|
+#### IOS-WEB-035 轨道事件点
|
|
|
+
|
|
|
+- 同一毫秒位置的多张照片合并成一个相机点，并显示数量徽标。
|
|
|
+- 笔记显示文档图标。
|
|
|
+- 普通 `MARKER` 显示警示/标记图标。
|
|
|
+- 文本以“续录时间：”开头的 `MARKER` 显示在音频轨，使用续录图标。
|
|
|
+- 点击事件点先跳到对应音频时间，再打开事件详情。
|
|
|
+- 事件按钮应覆盖空白轨点击层，不能误触发新增。
|
|
|
+
|
|
|
+### E. 回放控制
|
|
|
+
|
|
|
+#### IOS-WEB-040 时间与进度
|
|
|
+
|
|
|
+- 左侧显示当前时间，右侧显示总时长。
|
|
|
+- 小于一小时为 `MM:SS`；达到一小时为 `H:MM:SS`。
|
|
|
+- 提供独立进度 Slider，与时间线播放头和 `<audio>` 双向同步。
|
|
|
+- 进度范围以实际解码音频时长为准。
|
|
|
+
|
|
|
+#### IOS-WEB-041 播放操作
|
|
|
+
|
|
|
+- 快退 10 秒，最低到 0。
|
|
|
+- 播放/暂停主按钮，48px 圆形高对比样式。
|
|
|
+- 快进 10 秒，最高到实际音频末尾。
|
|
|
+- 播放结束后停止播放并停在末尾，与 iOS 一致。
|
|
|
+- 播放或暂停状态必须由实际音频元素状态驱动。
|
|
|
+
|
|
|
+#### IOS-WEB-042 跳过静音
|
|
|
+
|
|
|
+- 默认开启，与 iOS 一致。
|
|
|
+- 播放进入静音区间时，立即跳到该区间结束时间。
|
|
|
+- 开关必须实际影响播放逻辑。
|
|
|
+- 图标、文案、加载状态和静音区间数量与 iOS 一致。
|
|
|
+
|
|
|
+### F. 事件列表
|
|
|
+
|
|
|
+#### IOS-WEB-050 列表排序与分组
|
|
|
+
|
|
|
+- 所有事件按 `relativeTimeMs` 升序。
|
|
|
+- 同一时间点的照片在列表中合并成一个记录项。
|
|
|
+- 不同时间点分别显示。
|
|
|
+- 无事件时显示托盘图标和“暂无会话事件”。
|
|
|
+
|
|
|
+#### IOS-WEB-051 事件卡片
|
|
|
+
|
|
|
+卡片展示：
|
|
|
+
|
|
|
+- 时间徽标。
|
|
|
+- 类型图标和中文类型：照片、笔记、标记、音频、续录。
|
|
|
+- 笔记/标记内容，最多两行。
|
|
|
+- 照片缩略图最多叠放三张，并显示总张数。
|
|
|
+- 第一条非空照片备注。
|
|
|
+- 地点名称。
|
|
|
+- 右侧进入箭头。
|
|
|
+
|
|
|
+点击卡片：
|
|
|
+
|
|
|
+- 音频跳转到事件时间。
|
|
|
+- 打开相应事件详情。
|
|
|
+
|
|
|
+### G. 新增笔记
|
|
|
+
|
|
|
+#### IOS-WEB-060 从笔记轨空白处新增
|
|
|
+
|
|
|
+- 点击笔记轨空白处，将横坐标换算为记录时间。
|
|
|
+- 立即跳转播放器到该时间。
|
|
|
+- 打开“添加笔记”弹窗，顶部显示“添加到 MM:SS”。
|
|
|
+- 多行文本输入，占位文案“这一刻的想法”。
|
|
|
+- 可添加位置。
|
|
|
+- 空白内容禁止保存。
|
|
|
+- 保存后创建 `NOTE` 事件、更新版本、刷新时间线和事件列表。
|
|
|
+- 失败时回滚页面乐观更新并保留草稿。
|
|
|
+
|
|
|
+### H. 新增照片
|
|
|
+
|
|
|
+#### IOS-WEB-070 从图片轨空白处新增
|
|
|
+
|
|
|
+- 点击图片轨空白处确定事件时间并打开“添加照片记录”。
|
|
|
+- 支持调用摄像头拍照；浏览器不支持或未授权时显示明确状态。
|
|
|
+- 支持一次从本地选择多张图片。
|
|
|
+- 每张照片独立预览、移除和填写备注。
|
|
|
+- 多张照片共用一个位置。
|
|
|
+- 读取中显示进度；部分读取失败时保留成功项并提示失败数量。
|
|
|
+- 没有照片时显示“还没有照片”空状态。
|
|
|
+- 保存按钮显示“保存 N 张”，无照片或读取中时禁用。
|
|
|
+- 上传前采用与 iOS 等价的 JPEG 质量目标；不得无上限上传原始超大图片。
|
|
|
+
|
|
|
+数据要求：
|
|
|
+
|
|
|
+- 同一批照片的 `relativeTimeMs` 相同。
|
|
|
+- 每张照片创建独立 `PHOTO` 事件和独立照片资产。
|
|
|
+- 照片资产 `clientId` 必须与事件稳定关联，遵循 `{eventClientId}-photo`。
|
|
|
+- 事件或资源任一步失败时执行补偿，不能留下只有事件没有图片的半成品。
|
|
|
+
|
|
|
+### I. 查看、编辑与删除事件
|
|
|
+
|
|
|
+#### IOS-WEB-080 照片点详情
|
|
|
+
|
|
|
+- 同一时间点的所有照片在一个详情弹窗中展示。
|
|
|
+- 顶部显示时间、照片总数和共同位置。
|
|
|
+- 每张照片展示序号、图片、独立备注和删除按钮。
|
|
|
+- 备注与位置有变化时才启用保存。
|
|
|
+- 保存成功后更新所有相关事件并刷新版本。
|
|
|
+- 图片资源缺失时显示“图片不可用”，不显示破图。
|
|
|
+
|
|
|
+#### IOS-WEB-081 全屏图片
|
|
|
+
|
|
|
+- 点击图片进入全屏黑底预览。
|
|
|
+- 支持 1–5 倍缩放。
|
|
|
+- 放大后支持拖动，并限制在图片可移动边界内。
|
|
|
+- 展示照片创建时间和非空备注。
|
|
|
+- 提供明确关闭按钮，Esc 也可关闭。
|
|
|
+
|
|
|
+#### IOS-WEB-082 笔记详情
|
|
|
+
|
|
|
+- 显示事件时间。
|
|
|
+- 笔记内容可编辑。
|
|
|
+- 位置可添加、修改或清除。
|
|
|
+- 内容为空禁止保存。
|
|
|
+- 没有变化时禁用保存。
|
|
|
+
|
|
|
+#### IOS-WEB-083 标记与续录详情
|
|
|
+
|
|
|
+- 普通标记内容只读展示，并可删除。
|
|
|
+- 续录标记标题为“续录详情”，展示记录内容，并可删除。
|
|
|
+- 不得把续录标记计入笔记数量。
|
|
|
+
|
|
|
+#### IOS-WEB-084 删除事件
|
|
|
+
|
|
|
+- 删除照片、笔记和标记前必须二次确认。
|
|
|
+- 删除照片时同时删除事件记录和对应云端照片资产。
|
|
|
+- 删除失败时恢复 UI，不得先永久移除本地状态。
|
|
|
+- 操作完成后更新照片/笔记计数、版本、时间线和列表。
|
|
|
+
|
|
|
+### J. 位置
|
|
|
+
|
|
|
+#### IOS-WEB-090 位置入口
|
|
|
+
|
|
|
+- 无位置时显示“所在位置 / 点击后根据 GPS 选择当前位置”。
|
|
|
+- 有位置时显示地点名称和地址。
|
|
|
+- 图标在有位置时使用品牌金色。
|
|
|
+- 支持修改或清除位置。
|
|
|
+
|
|
|
+#### IOS-WEB-091 位置选择器
|
|
|
+
|
|
|
+- 进入后请求浏览器定位权限；仅在用户主动打开位置选择器后请求。
|
|
|
+- 展示地图、当前位置、已选地点标记和回到当前位置按钮。
|
|
|
+- 默认加载当前位置 2km 内的附近地点。
|
|
|
+- 搜索范围以当前位置/已选位置为中心约 10km。
|
|
|
+- 提供“不显示位置”选项。
|
|
|
+- 地点条目显示名称、地址和选中状态。
|
|
|
+- 定位拒绝、定位失败、附近地点失败、无搜索结果分别显示对应错误和重试/设置指引。
|
|
|
+
|
|
|
+网页适配：
|
|
|
+
|
|
|
+- 地图和地点检索服务必须明确选型；不得在 PRD 实施阶段临时用静态占位图替代。
|
|
|
+- 保存字段统一为 `locationName / locationAddress / latitude / longitude`。
|
|
|
+
|
|
|
+### K. 续录
|
|
|
+
|
|
|
+#### IOS-WEB-100 续录入口与环境检查
|
|
|
+
|
|
|
+- 从 Info 面板点击“续录”。
|
|
|
+- 先暂停当前回放。
|
|
|
+- 网页端使用浏览器麦克风继续录音；如支持多输入设备，允许选择输入源。
|
|
|
+- 麦克风不可用或权限拒绝时明确说明原因。
|
|
|
+- 续录开始时以原音频实际时长作为偏移，创建续录标记：
|
|
|
+ - `eventType=MARKER`
|
|
|
+ - `relativeTimeMs=原音频时长`
|
|
|
+ - `textContent=续录时间：yyyy年M月d日 HH:mm:ss`
|
|
|
+- 结束后生成新的完整或可拼接音频资产，更新时长、波形、静音分析、版本和同步状态。
|
|
|
+
|
|
|
+平台限制：
|
|
|
+
|
|
|
+- 网页端不得假装支持 iOS 原生 Spark BLE 录音。
|
|
|
+- 若产品要求 Spark 设备完全等价，需另立 Web Bluetooth/设备网关技术方案；不支持的平台显示“当前浏览器不支持 Spark 续录”，并允许改用浏览器麦克风。
|
|
|
+
|
|
|
+## 6. UI 统一规范
|
|
|
+
|
|
|
+- 背景：跟随系统浅色/深色，分别接近 iOS `systemBackground`。
|
|
|
+- 卡片：接近 `secondarySystemBackground`，主内容使用约 15%–50% 的轻透明层级。
|
|
|
+- 边框：主文本色 12% 透明度，1px。
|
|
|
+- 圆角：主卡片 10px，事件卡片/输入 8px。
|
|
|
+- 主色：系统高对比前景色；不把品牌金色用于普通播放进度。
|
|
|
+- 品牌金：`#E6C687`，只用于已同步、选中位置等强调状态。
|
|
|
+- 录音红：`#E53935`。
|
|
|
+- 字体：系统 SF/等价系统字体；时间、版本和技术数字使用等宽字体。
|
|
|
+- 图标：网页使用 Lucide 中最接近的线性图标；线宽和尺寸保持 9–18px 的克制层级。
|
|
|
+- 禁止装饰性发光、脉冲和紫色 AI 视觉渗入左侧。
|
|
|
+- 左侧桌面宽度下完整显示；窄屏时独立纵向滚动，不允许控制区相互遮挡。
|
|
|
+
|
|
|
+## 7. 可访问性与键盘
|
|
|
+
|
|
|
+- 所有纯图标按钮必须有可读名称和 Tooltip。
|
|
|
+- 播放、同步、跳过静音、保存和删除状态须通过 `aria-live` 或等价方式通知。
|
|
|
+- 所有弹窗具备焦点锁定、Esc 关闭和关闭后的焦点恢复。
|
|
|
+- 时间线事件、播放头、Slider、照片删除和位置选择均可键盘操作。
|
|
|
+- 触控目标建议至少 44×44px；播放头视觉可为 1px，但命中区至少 28px，网页建议 32px。
|
|
|
+- 不依赖颜色单独表达同步、选中、错误或播放状态。
|
|
|
+- 图片提供语义化替代文本；地图存在文本列表替代。
|
|
|
+- 200% 缩放下左侧不得出现不可操作的横向页面溢出；只有时间线内部允许横向滚动。
|
|
|
+
|
|
|
+## 8. 当前网页实现差距
|
|
|
+
|
|
|
+### P0：阻止“完全一致”的问题
|
|
|
+
|
|
|
+- 使用 `createSyntheticFieldAudio()` 在无音频或下载失败时生成假音频。
|
|
|
+- 波形由 `Math.sin()` 生成，与真实录音无关。
|
|
|
+- 没有 iOS 三轨时间线、时间刻度、静音区间和可拖动播放头。
|
|
|
+- “跳过静音”只切换样式，不执行检测或跳转，且默认值与 iOS 不一致。
|
|
|
+- 标题编辑只修改 `session.title` 内存对象，不写后端。
|
|
|
+- `RecordDetailModal` 调用不存在的 `sessionAPI.addEvent`；并且 `App.jsx` 未传入 `onEventAdded`。
|
|
|
+- 分享按钮只显示 Toast，没有分享或下载实际音频。
|
|
|
+- 缺少照片新增、批量照片、照片备注、照片查看、全屏缩放、位置、编辑和删除。
|
|
|
+- 缺少笔记编辑、删除和位置。
|
|
|
+- 缺少事件按同一照片时间点分组。
|
|
|
+- 缺少续录。
|
|
|
+
|
|
|
+### P1：状态和体验不一致
|
|
|
+
|
|
|
+- 详情未在打开时重新请求最新数据。
|
|
|
+- 同步状态固定显示“已同步”，无真实进度、失败、冲突或暂停。
|
|
|
+- 信息面板字段和结构与 iOS 不一致。
|
|
|
+- 左侧存在额外说明标题、胶囊标签、装饰金色进度和网页专属表单。
|
|
|
+- 事件类型直接显示英文。
|
|
|
+- 音频结束后网页回到 0，iOS 停在末尾。
|
|
|
+- 对大文件使用一次性 Blob 下载，可能造成明显内存压力。
|
|
|
+
|
|
|
+## 9. 后端与接口缺口
|
|
|
+
|
|
|
+现有后端已具备：
|
|
|
+
|
|
|
+- 获取列表与详情。
|
|
|
+- `POST /sessions` 全量幂等 Upsert，支持 `baseRevision` 和 `deletedEventClientIds`。
|
|
|
+- 新增单个事件。
|
|
|
+- 上传/下载 AUDIO 与 PHOTO 资产。
|
|
|
+- 记录软删除。
|
|
|
+
|
|
|
+为了稳定完成网页/iOS 双端编辑，建议：
|
|
|
+
|
|
|
+### 必须补齐
|
|
|
+
|
|
|
+1. 前端 API 封装：
|
|
|
+ - `getSessionDetail`
|
|
|
+ - `syncSession`
|
|
|
+ - `uploadAsset`
|
|
|
+ - `addEvent`（若仍保留单事件接口）
|
|
|
+ - 统一错误码、409 和 413 处理。
|
|
|
+2. 删除照片资产接口：
|
|
|
+ - 当前没有 `DELETE /sessions/{sessionId}/assets/{assetId}`。
|
|
|
+ - 仅删除 PHOTO 事件会留下云端孤儿文件，无法达到 iOS“图片文件和记录一起删除”的语义。
|
|
|
+3. 资产与事件关联返回：
|
|
|
+ - 网页需用事件 `clientId` 对应 `{clientId}-photo` 资产。
|
|
|
+ - 建议详情响应直接返回 `event.asset` 或 `event.assetId`，减少前端猜测。
|
|
|
+4. 音频访问优化：
|
|
|
+ - 支持 Range/流式响应或安全的鉴权媒体 URL，避免超大录音全部进入内存 Blob。
|
|
|
+
|
|
|
+### 建议修正
|
|
|
+
|
|
|
+- `POST /sessions/{id}/events` 新增事件后应同步更新 `photoCount / noteCount / updatedAt / revision`。
|
|
|
+- 增加事件 PATCH/DELETE 接口，或明确网页统一使用全量 `POST /sessions` Upsert；不要两套写入语义混用。
|
|
|
+- 照片上传和事件创建提供事务化/补偿协议。
|
|
|
+- 续录后多个 AUDIO 资产的“当前权威音频”规则应在后端明确，不依赖数组顺序。
|
|
|
+- 提供可选的波形/静音分析缓存，减少每次打开大音频都重新解码。
|
|
|
+
|
|
|
+## 10. 推荐实施顺序
|
|
|
+
|
|
|
+### 阶段 1：真实回放底座
|
|
|
+
|
|
|
+- 详情重新获取。
|
|
|
+- 去除假音频。
|
|
|
+- 真实音频选择、错误态与分享下载。
|
|
|
+- 真实波形、静音检测、播放控制和可拖动播放头。
|
|
|
+- 三轨只读展示和事件列表分组。
|
|
|
+
|
|
|
+完成标准：用户看到和听到的内容全部来自真实记录。
|
|
|
+
|
|
|
+### 阶段 2：事件完整编辑
|
|
|
+
|
|
|
+- 标题云端保存。
|
|
|
+- 新增/编辑/删除笔记。
|
|
|
+- 新增/查看/编辑/删除照片。
|
|
|
+- 位置选择。
|
|
|
+- 全屏图片。
|
|
|
+- 版本冲突与失败回滚。
|
|
|
+
|
|
|
+完成标准：网页编辑后 iOS 同步能得到完全相同的事件、照片、备注和位置。
|
|
|
+
|
|
|
+### 阶段 3：同步、续录与大文件
|
|
|
+
|
|
|
+- 精确同步状态、进度、暂停、认证和大文件确认。
|
|
|
+- 浏览器麦克风续录和音频资产更新。
|
|
|
+- 流式/Range 音频、分析缓存和性能优化。
|
|
|
+
|
|
|
+完成标准：长录音、大照片批次、续录与冲突场景可可靠完成。
|
|
|
+
|
|
|
+## 11. 总体验收标准
|
|
|
+
|
|
|
+只有同时满足以下条件，才能宣称“网页左侧与 iOS 回放页功能统一”：
|
|
|
+
|
|
|
+1. 无任何模拟音频、模拟波形、固定同步状态或无效开关。
|
|
|
+2. 同一记录在 iOS 与网页显示相同标题、时长、照片数、笔记数、事件时间、备注、地点和版本。
|
|
|
+3. 两端播放同一实际音频，波形时间位置可对应听到的内容。
|
|
|
+4. 网页拖动三轨播放头、进度条或点击事件，音频位置一致。
|
|
|
+5. 跳过静音在真实静音区间生效。
|
|
|
+6. 网页新增/编辑/删除笔记和照片后，iOS 同步结果一致；反向亦然。
|
|
|
+7. 照片删除不残留云端孤儿资产。
|
|
|
+8. 标题和所有事件编辑均有版本保护、失败提示和回滚。
|
|
|
+9. 信息、同步、分享、位置、全屏图片和续录均具备完整状态，而非视觉占位。
|
|
|
+10. 桌面、窄屏、键盘和辅助技术下核心流程均可完成。
|
|
|
+
|
|
|
+## 12. 审计证据限制
|
|
|
+
|
|
|
+本 PRD完成了当前 iOS 与网页源码、数据模型、同步逻辑和后端路由的逐项核对。当前已启动模拟器停在麦克风权限请求，未在未获授权的情况下改变权限，因此本轮没有取得回放详情页的完整运行截图。视觉尺寸以 SwiftUI 当前源码为基准，实施时仍需用包含真实音频、照片、笔记、位置和续录标记的测试记录，分别在 iOS 和网页逐状态截图对照验收。
|
