# 搜索快速查找：位置

入口为全局搜索 → 快速查找 → 位置。分类 tabs 下方铺满百度地图；点击地点后在地图底部浮出相关记录，宽窄窗口使用同一布局，关闭面板不改变地图范围。四类来源默认开启，收在地图左上角的「位置来源」按钮中：快记的位置、我发送的位置、发给我的位置、群聊中的位置。Escape 优先关闭筛选或地点面板，再关闭搜索。

日历「当天位置」复用同一视图并预选日历日期，可在弹窗内切换日期、查看所有位置和返回原日期。当前日期模式仍通过日历接口读取个人记录的设备定位点，页面有范围说明；四类来源的统一日期查询待后端确认。具体兼容行为、缓存边界与字段交接见 [日历位置统一交接](calendar-location-unification-handoff-2026-10-13.md)。

## 接口与边界

复用 Flutter 的现有只读接口，无新增云端接口或数据库迁移：

- `POST /api/v1/records/location/query`：历史位置记录，游标分页。
- `POST /api/v1/records/location/viewport-clusters/query`：当前视野的聚合点。
- `POST /api/v1/records/location/clusters/records/query`：指定聚合点关联的记录。
- 自己的精简记录投影通过已有 `records/detail` 补齐正文；通过 `records/location/context/get` 补齐相同坐标对应的地址。地点面板首批 6 条，继续加载每页 20 条，最多 4 路读取。

收到的位置保留聊天投影和原始记录归属，不通过个人接口读取发送者的私有设备位置。已锁定、无权限、删除的记录不补齐。坐标统一采用 WGS84 查询，显示前转换为百度坐标；视野反向转换与 Flutter 使用的坐标算法一致。

点击聚合点时保留该点对应的查询视野，后续分页不会误用移动地图后的新网格。快速切换地点会取消上一次读取。来源筛选不重新挂载地图，分页失败保留当前结果。

首屏只读取地图聚合，不预读整页记录。全球范围可能返回空聚合，但区域查询仍有数据；此时以 `limit: 1` 请求一个可读位置，初始化区域。仅在选中地点时读取其记录，支持继续翻页。不会自动请求实时定位权限。

缩放按钮下方的「定位到当前位置」仅在点击时请求定位。成功后居中到当前坐标并显示蓝点；再次点击可重新定位。当前位置不写入历史记录，不参与来源筛选和数量统计；关闭页面或切换账号后清除。定位失败保留原地图和历史地点，提示重试。

同一账号在内存中复用最近的地图范围、来源选择、选中地点、记录页及滚动位置。查询缓存最多 24 项，60 秒内复用，5 分钟内可先显示快照再后台更新；同一查询共享未完成的请求，离开页面不重复启动读取。地图画布离开后最多保留 5 分钟，仅一个非活动实例；转换坐标最多保留 1000 点，使用百度官方转换，每批最多 10 点、最多两批并行。账号切换或退出清除数据与地图，记录/隐私失效事件清除旧内容。数据均不落盘。原记录沿用已有聊天导航或个人快记详情入口。

本轮无需新增云端接口。首次打开地点时的逐条详情补齐仍受现有接口字段影响，后端批量摘要建议见 [位置加载性能交接](search-location-performance-handoff-2026-10-13.md)。

## 百度配置

复用 `baiduMapBrowserAk`。仓库 `cordis.patch.yml` 已在 `9ff81a21`（PR #779）配置浏览器端 AK。独立 Web 预览使用自己的 patch，需要同步这项配置；浏览器来源仍应符合公司百度控制台的域名授权。不得拿移动端 AK 或服务端 SK 替换。

若缺少配置或地图加载失败，显示明确提示，记录列表仍可阅读。测试环境的 patch、登录引导 URL 和本地状态不提交到仓库。

## 验证范围

覆盖查询参数校验、记录隐私过滤、归属 ID 保留、地址坐标匹配、过期响应取消、聚合分页视野、来源切换、分页失败保留结果、全球空聚合后的区域初始化，以及坐标转换。

真实账号的百度底图、地点标记、地点名称及记录正文在独立 3101 Web 环境验证。该预览借用客户端既有登录态，不修改客户端安装文件或客户端状态。