# 搜索位置加载性能：前端优化与后端交接

## 当前问题与已完成范围

旧插件每次进入重新创建百度地图、读取聚合和整页记录，再为记录补齐正文/位置名称。20 条精简投影在字段均缺失时，可走 1 次列表 + 20 次 `records/detail` + 20 次 `records/location/context/get`，整页等待完成后才返回；另有权限目录和来源导航读取。该数值是代码路径上限，不是生产抓包统计。

插件本轮已改为地图铺满、来源折叠、点击地点后打开底部记录面板；默认不读取整页记录。全球聚合为空时只请求一个可读位置来初始化区域。地点面板首批 6 条，继续加载每页 20 条，避免为了显示底部几张卡片先补齐整页。查询结果短期按账号复用、同查询合并在途请求，重新进入保留地图/选择/滚动位置；失效时后台更新或按隐私要求清除。百度地图和转换坐标复用，转换最多两批并行。

没有新增或部署云端接口。本次插件可独立使用已有接口上线；下面是进一步缩短「第一次点击一个地点」等待时间的后端建议，不代表后端已经实现。

## 当前位置入口（无需新增后端）

地图缩放按钮下增加「定位到当前位置」。仅用户点击时复用插件现有的桌面权限桥／浏览器定位能力；取得 WGS84 坐标后通过百度官方转换接口转换，再居中地图并显示独立蓝点。没有自动定位或持续追踪，当前位置不写入历史记录、不参与记录数量，也不存入历史地点缓存。关闭页面后丢弃当前位置，切换账号或关闭期间返回的旧请求结果不再应用。

定位中禁用重复请求；权限拒绝、定位不可用或转换失败时保留地图视野并显示重试提示。自动化测试使用模拟坐标验证转换、居中、权限拒绝重试及请求生命周期；真实定位还取决于客户端／浏览器和系统授权，需要在对应设备上验收。

## 建议改进已有记录投影

优先让以下接口直接返回足够渲染位置列表的、已鉴权的轻量投影：

- `POST /api/v1/records/location/query`
- `POST /api/v1/records/location/clusters/records/query`

需要稳定包含：`record_uid`、精确的 `record_owner_user_id`、WGS84 `lat/lon`、`poi_name/address`、`source_type`、`send_at`、有界的 `preview_text`，以及源容器/会话定位字段。所有者 ID 不应通过浮点数转换而失真。

必须由后端统一排除已删除、无权限、隐私锁定的内容，并给出明确的投影权限语义/版本。收到的私聊与群聊位置应返回接收者可见的聊天投影，不能依赖读取发送者的私人设备上下文。没有地点名称或摘要时，需能区分「确实为空」和「接口未提供」，避免前端为真实空值反复补查。

返回这些字段后，插件可直接渲染列表；用户打开某条原记录时才读取完整详情。本轮保留既有权限校验与详情补齐，未因性能优化省略权限检查。

若无法调整现有响应，可提供有批量鉴权能力的投影补齐接口。接口名、版本字段及结构需要后端确认，本文不预设已经存在的新接口。

## 接口与性能验收

1. 同账号同地点，分别测量聚合响应、首条记录可见、完整记录页、重新进入耗时，以及 HTTP 请求数量；首次点击和缓存命中分开统计。
2. 一页 20 条位置记录不应为展示摘要额外请求 20 次详情和 20 次设备上下文；完整正文继续按需读取。
3. 保持现有游标/offset 的前进规则。聚合点的 records 查询使用该点生成时的 bounds、zoom、cluster_key，不与后续地图移动混用。
4. 覆盖四类来源、空摘要/空地址、权限收回、隐私锁定、删除、账号切换。失效提示要覆盖相关位置投影，使前端清除已有内容。
5. 目前没有 SQL 执行计划或服务端耗时证据，暂不能判定数据库瓶颈；服务端若仍慢，再结合日志分析空间查询和索引。

不在文档或日志里记录用户真实坐标、正文、登录凭据。