trail-mate/docs/uiux/components/map_annotation_policy.md

地图标注策略：全级别无字底图方案

状态：2026-09-15 用户已同意本方案，正在实施。当前已交付验证包仍是 z1–15 带字、z16–18 无字加点状 POI；本规格不是当前固件的完成声明。

需求与对象边界

用户接受在标注规则合理的前提下，将 z1–18 全部改成无字瓦片。z16–18 道路名称是必要信息；当前图标密集、名称稀疏和先出现后消失的行为需要一起解决。

• 地理数据：源数据存在的道路、聚落、区域、设施及兴趣点。数据存在不等于每个缩放级别都应显示。
• 地图标注：地理对象的名称及屏幕表现，分为地名/区域名、道路名、点状 POI 名称与图标。道路不能退化成“只在道路中点放一个普通 POI”。
• 显示资格：按类别、缩放级别及用户预设确定，不由内存分配成功与否决定。
• 排布结果：在给定屏幕上满足可读性和稳定性的标注集合。名称未排下不代表数据缺失，不能由此删除数据或标记底图缺失。
• 资源上限：约束候选、缓存和绘制成本，不充当类别筛选规则。

始终复用共享地图视口、坐标投影、后台空间瓦片读取、事件/代际机制和资源生命周期。固件工作在 feat/wio-tracker-l2；不新建页面私有加载链路。

默认逐级显示资格

下表是初始样式方案。名称必须来自数据，行政级别/道路等级/人口或重要性用于分层；不是对所有数据源完整性的保证。具备资格仍需通过屏幕布局。

z	地名、区域与点状 POI	道路标注
1	大洲、主要国家；区域包可保留一个选区定位地名	无
2	国家、主要首都	无
3	国家、首都及少量重要城市	无
4	省/州级区域、省会及重要城市	无
5	主要城市、重要大型湖泊/山系	无
6	城市、主要县级城市及大型自然地标	无
7	县级聚落与重要城镇	少量重要高速/国道编号
8	城镇及重要乡镇；少量大型景区定位名	高速/国道编号，保持稀疏
9	乡镇、大村庄、重要山峰与景区	主要干线编号
10	村庄；重要登山入口、营地、避难所等户外目的地	重要干线编号或简短名称
11	村庄、重要自然地标；主要户外服务设施	干线名称、编号
12	社区/片区、主要公园；医院、主要停车场及户外设施	城市主干道、主要道路名称
13	社区、公园、景点；交通枢纽及主要公共设施	主次干道名称
14	街区/村庄、公园；常用公共设施与户外服务点	主次干道、重要支路名称
15	街区、重要建筑/目的地；水源、厕所、停车等实用 POI	支路、主要居民街道名称
16	当前附近有意义的命名设施、景点及户外 POI	主干道和普通有名街道必须具备显示资格；优先保证可见道路的名称
17	更细的附近设施、入口、小公园、建筑/目的地名称	普通街道、小路及有名称的步行通道
18	门前/路口级别设施、入口、命名建筑和微观地标	服务道路、支路、步行路径等有名称的细部道路

用户位置、当前路线、选中的目的地使用原有导航覆盖层，优先级独立于一般地理标注。普通医院/应急设施不应仅凭类别在国家尺度挤掉国家或城市名。

区域 PBF 不等于全球地名数据。z1–3 的国家/首都展示需要有对应数据源；仅有云南 PBF 时可显示真实选区定位地名，不能伪造全球覆盖。需要全球概览时，Center 要另行准备轻量地名数据，仍不依赖第三方成品栅格瓦片。

解决图标密、文字稀的问题

1. 道路名和地区名直接作为文字布局，不先创建图标占位。
2. 有名称的 POI 将“小图标 + 名称”作为一个组合候选进行布局。尚未选中的候选图标不能阻挡其他候选的文字。
3. 无名厕所、停车等类别图标只补充实用信息，不无条件铺满屏幕。同类密集点优先选择有用的代表，必要时用带数量的聚合表示；不同语义类别不盲目混成一个点。
4. 名称太长时进行 UTF-8 安全省略并保留可识别前缀，不因超过固定宽度就直接全部删除；不放大图标，不使用滚动文字。
5. 先完成碰撞布局再确定显示集合；被拒绝的候选释放位置后，允许后续合适候选补位。去掉“先取前 48 个，再避碰且不补位”的流程。
6. 道路、地名和 POI 有初始显示预算，未使用的预算允许其他类别使用。避免 48 个图标挤占空间而只剩几条名称。
7. 图标初始试用 10–12 px，常规文字试用 14–16 px，均为需要实机确认的样式参数。根据用户补充要求，所有道路、地名和 POI 文字必须透明背景，不绘制白色/米白色底板，也不绘制白色描边或光晕。可读性依靠字号、字重、颜色和避碰。

Pager 480×222 上，初始排布目标为：低级别约 4–10 条有效文字，中级别约 10–18 条，高级别约 20–30 条总文字。高级别可先为道路名预留约 6–10 条机会，其余给地名与 POI。它们是有足够数据且空间允许时的调试目标，不是承诺或强制填满的数量；实际地图视口比整屏小，最终应按可用面积及实机耗时调整。

道路名称的数据与布局

• Center 保存道路身份、名称/编号、道路等级、缩放资格、简化线段和多个候选位置。
• 仅合并拓扑连续且语义一致的同名路段；不能把不同地区同名道路合并。
• 候选位置覆盖长道路的多个部分，使道路中点在视野外时，视野内路段仍能显示名称。
• 设备只处理视野附近的简化候选；文字位置与道路匹配，始终保持屏幕可读方向，不继承底图整体旋转。
• 同一路段名称去重，并控制沿道路重复标注的屏幕间距；文字应完整落在可用视口内。
• “z16–18 道路名重要”通过显示资格与布局预算体现，不通过把某几条道路名称硬编码成例外实现。

时间稳定性与失败语义

• 使用稳定地理对象 ID 保持上一轮选择。仍合格、仍在视野内、没有实质冲突的标注优先保留。
• 新候选只有在重要性明显更高或出现足够可用空间时替换旧候选；不能因中心距离差一两像素反复互换。
• 邻近瓦片异步到达时合并更新。静止视野的数据逐渐加载不应持续让已显示名称闪现、消失。
• 仅在视野/级别、相关数据、字体度量或样式变化时重新排布；普通重绘复用已有结果。
• PSRAM 分配失败或暂时读取失败时，在旧内容仍对应当前视野/级别的前提下保留可用结果并延后更新。不得将错误状态当作“当前没有标注”。旧视野或旧级别的内容不能为了防闪而永久保留。

Center、数据包与内存

• 默认方案调整为“全无字底图 + 地图标注”。地名、道路名、点状 POI 分别配置；关闭设施 POI 不应把道路名一起关掉。
• 提供户外/城市预设及各组最小/最大级别，默认规则覆盖 18 级；不要求用户逐个维护 18×所有类别的开关。
• 城市预设可加入公共交通、学校、公园、命名目的地等；商店/餐饮等生活类 POI 由预设及类别选择控制，不承诺当前 9 类提取器已经具备这些能力。
• 扩展现有空间索引载荷，使统一地图标注管线能区分地名、道路和点状 POI。具体磁盘版本与迁移方式需随实现验证，不把旧 POI 文件和新标注文件变成两个同时生效的权威来源。
• 同一份缩放/样式规则用于 Center 标注预览、导出和设备消费；在线预览背景不能冒充本地最终无字底图效果。
• 字体资源覆盖所有导出标注名称，包含道路与地名；通过既有字体包机制加载。复制到 SD 的交付包需携带缺失的必要资源，不能依赖手工修补昆明专用字表。
• PBF 几何处理、简化、候选生成与级别分类放在 Center；设备不解析全区域路网，不建立常驻大对象或道路全量表。
• 缓存、候选和布局缓冲按需使用有硬预算的 PSRAM，复用后台读取 scratch；保持单个绘制层，不增加图标/文字控件池或额外整屏画布。
• 内存预算和显示密度分开：先改善布局算法，再按真实设备成本决定候选上限，不用简单调大 48/20 代替修正。

实施顺序与验收

1. 先打通道路、地区名从 PBF 到统一标注索引，再到共享地图绘制层的完整路径。
2. 修正文字组合布局、长名称省略、补位和稳定选择；明确失败时的保留/清空行为。
3. 接入逐级规则与 Center 预设、预览和字体资源打包。
4. 标注链路具备覆盖能力后，才生成 z1–18 全无字的下一版验证包，避免先删掉低级别文字而没有动态标注补上。
5. 用同一个昆明范围验证 z1–18；特别检查 z16–18 的普通街道名，长道路跨瓦片/视口边缘，同名道路去重，密集设施及长名称。
6. 静止地图逐步加载、轻微定位抖动、平移、缩放、出入页面、字体延迟加载和受限内存场景均需验证。记录候选数、实际道路/地名/POI 文字数与拒绝原因。
7. 检查原生 RAM/PSRAM 高水位、单次布局耗时、绘制耗时与任务栈。主机测试不能替代这些实机性能测量。

用户已同意逐级规则与改进方向，并明确禁止文字底板和白色描边。字号与密度参数仍需设备验证，本文不表示上述下一版功能已经交付。