# 录音日历音频文件管理后端交接

日期：2026-10-12（2026-10-14 更新自动分页说明）。插件前端新增按日管理已上传音频的入口，复用已有读取、删除和修改接口。本轮不新增或部署云端后端。后端同事需要补齐按日期直接查询和完整分页，减少前端遍历历史文件的开销。

## 已实现的交互

录音右侧新增「音频文件」标签，跟随日历选中日期。即使当天没有转写内容，或转写读取失败，仍可进入文件管理。

- 「当天录音」按录音时间与所选日的重叠范围筛选，跨日文件显示完整起止时间。
- 「当天上传」对云端文件使用 `createdAtMillis`，即会话创建时间；本机待上传文件使用任务添加时间。这两个值均不表示上传完成时间，界面有说明。
- 「全部文件」取消日期限制。三个范围均支持搜索已加载文件的文件名。
- 列表展示文件名、录音时间、时长、大小、归属和状态。云端文件复用修改录音时间、修改数据归属、删除整份文件操作；本机未完成任务通过现有取消接口移除。
- 删除需要二次确认，明确影响整份文件及跨日数据。操作失败保留弹窗和错误；成功后仅从文件列表移除对应行，保留筛选、已加载文件和滚动位置，可继续删除其他文件。当前录音日和日历月独立刷新，停止旧音频播放并关闭旧转写对比。

入口为 `src/client/ArkmeRecordingSurface.tsx`；列表为 `src/client/recordings/ArkmeRecordingFiles.tsx`；日期筛选及去重逻辑为 `src/client/recordings/recording-day-files.ts`。

## 现有接口和边界

| 插件操作 | 本轮用途与现有限制 |
| --- | --- |
| `recordings.import.list` | 本机未完成任务与云端活动任务；音频文件页传入 `toMillis`、`limit`、`offset`，按 `owner.hasMore` / `owner.nextOffset` 自动续读；不传分页参数的导入弹窗仍保留最近 20 条默认读取 |
| `recordings.import.history` | 已完成文件分页，输入 `toMillis`、`limit`、`offset`；当前按创建时间查询，不能直接按录音日期查找 |
| `recordings.import.session.update-start` | 修改文件录音开始时间，使用原有校验与权限 |
| `recordings.import.session.update-ownership` | 修改数据归属，使用原有校验与权限 |
| `recordings.import.session.delete` | 删除整份云端会话及关联数据，沿用原有服务逻辑 |
| `recordings.import.cancel` | 取消本机未完成导入，含 `importRef` 和 `expectedRevision`，沿用现有取消与清理逻辑 |

云端查询复用 `/api/v1/audio/get-session-ls`。插件网关当前只投影 `source === 2` 的上传会话；本入口不是全部自动录音、共享录音的资产目录。查询权限沿用当前账号上传文件的现有范围。

2026-10-14：音频文件页已取消筛选、搜索和手动续查。历史文件与未完成任务均自动每页读取 50 条，直到服务确认没有下一页；已读文件立即展示。加载状态放在标签数量旁，完成前数量带 `+`，完成后显示准确数量；读取失败保留已有行，仅提供重试。切换日期复用已加载结果，离开标签取消在途读取，返回后继续未完成分页；已完成快照在 1 分钟内复用，过期后重新进入会后台刷新。

每次刷新固定 `toMillis = Date.now()`，不能改成所选录音日的日末：旧录音可能今天才上传，按创建时间上界裁剪会漏掉它。现有 offset 分页并非稳定快照，任务完成、删除等并发变化可能移动分页位置；前端按稳定标识去重不能彻底解决漏读。插件网关现在复用同一账号、任务范围及查询上界的读取游标，避免每个前端分页都从零重扫；缓存短期且有数量限制，修改/删除时失效，缓存命中仍验证账号。服务端按录音日期筛选与稳定游标仍需补齐，才能免去首次遍历全历史及解决其他设备并发修改造成的分页漂移。

列表首次进入、上传回调或修改文件信息后读取；重新读取期间保留现有行，不定时重复扫描整份历史列表。删除成功不重载文件列表；当前账号视图保留删除标记，晚到结果不能恢复已删除的行。删除期间暂停接纳分页结果，完成后调整已读取文件对应的 offset 并继续，避免本次删除造成分页跳项；其他设备的并发变化仍需服务端稳定游标解决。

## 建议后端补齐的查询能力

以下是待后端确认的合同要求，尚未实现或调用。可以扩展现有接口，也可以提供统一文件列表接口；请先确定路径、鉴权、成功码和字段，再适配插件操作层。

| 能力 | 建议语义 |
| --- | --- |
| 日期范围 | Unix 毫秒 `fromMillis` 和 `toMillis`，区间为 `[from, to)`；前端按用户当地日界线计算，不能假定每天固定 24 小时 |
| 录音日期查询 | `startAtMillis < toMillis && endAtMillis > fromMillis`；跨日文件返回一次且保留整份文件起止时间；零时长待上传任务另行明确归属规则 |
| 上传日期查询 | 明确按添加时间、进入云端时间还是上传完成时间；若需要真正完成时间，应新增独立字段，不复用 `create_at` 冒充 |
| 状态 | 同一查询覆盖未上传完、处理中、完成、部分失败和失败；支持完整分页，不截断前 20 个活动任务 |
| 文件名搜索 | 由服务端在当前日期范围内查询，不要求先加载所有历史记录 |
| 稳定分页 | 提供 cursor 或 snapshot，排序至少使用时间和稳定 ID；处理任务跨状态迁移，避免漏项、重复及翻页漂移 |
| 完整性 | 返回 `hasMore`、可靠的总数或明确的完整性状态；无权限、请求失败、部分结果与确实为空分开 |
| 文件字段 | 稳定 ID、可用于现有操作的会话引用、文件名、字节数、音频时长、完整起止时间、来源、归属、创建时间、处理状态与更新时间 |

不能用客户端文件名作为身份键。同名文件、不同来源设备的录音保持独立。若扩大至自动录音或收到的共享录音，请另行对齐权限：可读不等于可删除原拥有者文件。

## 修改与删除的刷新要求

保持既有账号校验、归属判断和服务端任务并发校验。删除以整份文件为单位，不因从某一天进入而只删除片段；确认文案必须对应真实删除范围。

修改录音时间可能改变文件所属日期。后端应保证原日期与新日期的转写、时间轴、存储和时长统计随后读取一致；归属修改与删除也需同步相关派生数据。前端本轮刷新当前日与可见月份，其他日期进入时重新读取，不在客户端推算权威统计。

## 联调验收

1. 当天上传旧日期录音：「当天上传」可查到；「当天录音」只在实际录音日可查到。
2. 23:50 至次日 00:10 的录音两天均可查到，展示完整范围，删除前提示整份文件影响。
3. 超过 50 个已完成文件、超过 20 个活动任务、超过 500 个历史文件时，完整查询能找到对应文件，不误报为空。
4. 上传中变为处理中再变为已完成，同一文件不丢失、不重复；同名不同文件不合并。
5. 空转写、转写读取失败、目录读取失败分别处理；目录失败不能显示为确认无文件。
6. 删除取消不发修改请求；删除失败保留文件和错误；删除成功仅移除对应行，可连续操作而无需重载历史列表，日历统计独立刷新。旧请求晚到、分页中删除和删除失败后的续读均不能恢复已删行或跳过下一页文件。
7. 修改录音时间跨日、修改归属后，相关日期的数据一致；刷新失败明确提示。
8. 切换账号、日期或离开页面时，过期响应不串账号，旧弹窗不继续操作新账号文件。
9. 时区与夏令时日界线、边界恰好午夜、未知上传时间均符合正式合同。

请后端同事交付最终合同、可联调环境、脱敏响应样例和以上验收结果。本轮自动测试使用模拟文件，未执行真实录音删除；生产删除及跨日数据清理的端到端验收需使用专门测试文件。