# 日历当天位置与搜索所有位置：共用视图及日期筛选交接

## 本轮插件实现

- 日历入口直接调用搜索使用的 `ArkmeLocationQuickView`，默认带日历选定日期和时区；同一弹窗可以切换日期、查看所有位置、返回之前日期，不修改日历原选定日期。
- 两个入口共用 `ArkmeLocationMapFrame`、`ArkmeLocationSearchMap`：完整百度地图、默认折叠的来源、点击地点后的底部记录面板、缩放和当前位置按钮。
- 按账号、日期和时区保存当天位置快照：60 秒内复用，最长展示 5 分钟快照后刷新，最多保留 6 天；同日同请求复用在途任务，不因关闭重开重新扫描。改查其他日期会取消尚未完成的旧日扫描，隐私失效／删除／账号切换清除旧数据。
- 当天查询保留日历权限复核，读取并发由 2 路变为最多 4 路，首个有效位置即可显示；记录摘要有长度上限，完整正文仅在用户打开记录时读取。
- 按日期保存地图范围、筛选、选中地点和滚动位置；整个界面只保留一个可复用百度地图画布。空日期仍显示地图、日期和空态。

## 尚未对齐的数据口径

这次完成的是共用界面与日期适配层。当前生产接口尚未确认具备「所有位置按日期筛选」契约，不能声称四类来源已经完整按日贯通：

- 所有日期：使用 `/api/v1/records/location/query`、`viewport-clusters/query`、`clusters/records/query`；有快记、我发送、发给我、群聊四类位置。
- 选定日期：继续使用 `calendar.activity` 的个人原始记录详情，以及 `calendar.record-location` 的设备定位权限复核。包含个人记录（含本人发送记录）的设备采集点，不包含所有收到的位置卡片。
- 当前插件 `LocationQuery` 及已检查的 Flutter 请求序列化中，没有日期起止或时区参数。这仅证明现有调用未接入日期条件，不能证明未检查的后端版本不支持。
- 页面明确注明「当前日期显示个人记录的设备位置」，日期模式仅提供确有数据来源的快记和我发送筛选，避免将收到位置的缺项表现为完整统计。

## 后端同事需要确认并补齐

1. 在上述三个位置接口中统一支持日期过滤；最终字段名由后端确认，建议以选定本地日期＋IANA 时区换算半开时间区间 `[当日零时, 次日零时)`，覆盖夏令时日期。不要假定一天恒为 24 小时。
2. 明确日期依据：目前日历按记录的 `send_at` 归日，设备的 `captured_at` 用于展示采集时间，不应静默混用。若改按位置采集时间，日历、移动端、搜索、聚合及记录页需同步约定。
3. 统一个人设备采集位置、发送位置卡片、接收私聊与群聊位置的来源语义。定义是否包含设备定位点及如何去重，不能按接近时间或相同坐标直接合并原记录。
4. 聚合查询与点内分页必须携带相同日期范围、时区、来源条件。聚合数量应在完整鉴权和日期过滤后计算，分页不可混入其他日期；有界返回／截断必须明确。
5. 列表和聚合记录返回轻量已授权投影，避免每条再查详情与位置上下文。精确字段建议见 `search-location-performance-handoff-2026-10-13.md`。
6. 给出可验证的能力声明或版本边界，避免旧服务忽略未知日期字段却返回全部日期。未确认支持前，插件不会向现有接口发送猜测字段。

后端确认／上线后，将日期模式适配层替换为同一个位置查询服务，并将日期、时区加入所有查询缓存键；共用地图、筛选、记录面板和日历入口均可保留。移除设备位置兼容提示前，需验证以下验收。

## 验收

- 同账号同来源，选定日期结果等于所有位置在相同日期口径下的子集；覆盖跨午夜、不同时区、夏令时与空日期。
- 四类来源、不同记录拥有者、坐标相同但记录不同、权限撤回／隐私锁定／删除，均保持数量与明细一致。
- 首次打开、同日重开、快速切日、从全部返回、后台刷新，以及加载失败后重试；统计请求次数和首点／首条记录耗时。
- 位置来自记录的观测点，不是连续轨迹或停留时长；不能据此生成未被记录的位置。

本轮未修改、部署云端后端或已安装 Arkme 客户端。真实坐标、正文、鉴权信息不写入交接文档或测试日志。