# 发给自己日历：后端视图接口对接

## 范围与依据

2026-09-18 对接同事提供的《发给自己日历：最终实现方案与对接说明》，并核对 Record 后端 master `e130682`（实现 `e2c4d9b`）的 `gin/api/calendar_bucket.go` 和 `gin/compound/calendar_view.go`。

仅升级发给自己全部、未分类、主题及可见后代；不改独立全局日历，不改私聊/群聊统计，不将仍在讨论的互动日历方案当作已发布接口。

## 请求和展示

| 当前范围 | view_scope_kind | bucket_scope_kind | 额外参数 |
|---|---:|---:|---|
| 发给自己全部 | 1 | 1 | 无 |
| 未分类 | 2 | 1 | 无 |
| 主题及后代 | 3 | 2 | 签名 sourceRef 对应的根主题 UID；include_descendants=true |

- host 验证账号和签名 sourceRef 后生成参数，不转发调用者任意指定的 owner、视图枚举或主题 UID。
- 每个加载月份一次 `/api/v1/calendar/buckets/query`。多月可见窗口与相邻月份预取各自按需查询；“一次”不是整个日历生命周期只有一次网络请求。
- 不逐日读取内容、不在客户端枚举子主题，不重算或加减服务端已过滤的 count。后端负责首页准入、归属、隐私和去重。不能以旧来源分类过滤已经进入首页的聊天来源记录。
- 明确保持自然日策略 `{kind:1}` 与当前 IANA 时区，两条接口相同。校验响应时区和策略；本次不增加 Smart/固定切日设置，也不将响应额外字段原样传回请求。
- 点击日期请求 `oldest_first=true, limit=1`，第一页无游标，找到当天最早可见记录后沿用原定位流程。月份 `first_*` 表示最新记录，不当作当天最早定位锚点或第一页游标。
- 当天分页只使用响应游标对，排序方向、范围、时区、策略不变。验证重复条目、排序、游标推进与可见内容，不静默截掉异常条目后假装成功。
- 复用记录内容/媒体/历史头像投影、定位加载提示、取消重试与请求竞态保护；界面布局和已保存日历高度不变。
- SDK 的 calendarBuckets/calendarRecords 支持同一签名 sourceRef；不另建一套统计逻辑或新增 DSH 工具。

## 失败、缓存和回滚

- 新视图仅接受业务 `code=0`，HTTP 200 不代表业务成功。缺少数组、日期/计数/has_records/策略不一致不作为空月份缓存。
- 40001/50001 与视图响应校验失败展示错误，清除当前过期摘要与锚点，允许显式重试；不自动改用旧总日历、不无限重试业务错误。
- 服务层保留原 60 秒、账号/范围/时区/月份/修订隔离的摘要缓存与并发合并；新视图不叠加传输缓存。浏览器缓存升级为 v2，隔离旧客户端重算结果，键包含自然日语义；仅存摘要，不存正文或媒体地址。
- 数据、归属及隐私变化继续复用现有失效通知；账号切换和失效后的晚返回不会覆盖当前界面。跨页不是数据库快照，并发修改后应重新加载。
- `selfCalendarViewsEnabled` 默认 true；部署方可明确设置 false，恢复原客户端精确过滤统计路径（更慢），不是失败降级。生产发布前仍需后端确认所有实例兼容，单次联调不能证明全实例部署完成。
- 回滚日历缓存语义时应重启预览/客户端并刷新统计。旧路径按天分页精确过滤，日期起点必要时扫描当天，不返回未过滤全局数字。

## 验证要求

自动化覆盖三种范围、单请求统计、空月、缓存隔离/失效、稳定正反序分页、最早记录定位、保留合法聊天来源记录、沿用历史内容投影、错误码、异常响应、完整游标、旧契约与私聊/群聊不回归。

真实联调另外检查月份加载、早期日期定位、未分类/主题切换。构建和 mock 测试不等同于生产性能或全部后端实例验收。

## 本次验证结果（2026-09-18）

- 全量测试：628 个测试文件通过、8 个跳过；7,464 项测试通过、11 项跳过，无失败。类型检查及最终构建通过。
- 本地 Web 预览已更新，使用已有账号验证全部、未分类、主题及可见后代，三种范围均返回业务 code=0、自然日策略 kind=1。
- 本次账号的月份请求样本耗时 105—698 ms，覆盖有数据月份及空月。打开和滚动日历只产生按月统计请求，没有逐日拉取正文来计算数量；这些耗时是后端请求样本，不是端到端响应承诺。
- 全部范围点击 8 月 12 日，最早记录请求约 249 ms；主题范围点击 9 月 3 日约 199 ms。两次均以 oldest_first=true、limit=1 查询，界面显示定位中间态后完成定位。
- 主题重新打开日历时仍聚焦 9 月 3 日；切回全部后恢复其原阅读日期 8 月 12 日，已检查选中日期状态。
- 本次验证只更新本地 Web 预览插件，保留更新前备份；未修改原生客户端安装包，不代表原生安装包或生产发布验收。仍需在实际发布环境验收后端全实例兼容性。
- 推送前再次刷新远端，确认基于最新 master `886ecbdd`；复跑 9 个相关测试文件、252 项测试及类型检查，全部通过。