如果说第六阶段的雷达图是房源的“体检报告”，那么这一阶段的地图模块就是带用户实地“看房”。在 readme7 中，我们定下了两个硬指标：打点精度 ≤10m 和 周边配套图层 ≥3 类。

这不仅仅是画几个点的问题，更是一场关于坐标系纠偏、数据并发加载与交互体验的综合战役。今天我们先从最基础的“基础设施”——图层定义与样式系统开始讲起。

1. 选型与架构：为什么选择 PyDeck？

在 Streamlit 生态中，地图组件主要有 st.map（极简）、Folium（Leaflet 封装）和 PyDeck（Deck.gl 封装）。

• 决策过程：
  • st.map：无法自定义复杂的 POI 图层和点击事件，Pass。
  • Folium：虽然功能强大，但在处理大量点位（如全城地铁线）时，DOM 节点过多容易导致浏览器卡顿。
  • PyDeck：基于 WebGL 渲染，性能极佳，且原生支持 Deck.gl 的 ScatterplotLayer 和 IconLayer，非常适合我们需要的高密度打点和多图层叠加需求。

最终，我决定使用 PyDeck 作为底层引擎，并配合 streamlit-folium（如果需要特定插件）或纯 PyDeck 实现。

2. 核心攻坚：坐标系与精度的“生死线”

国内地图开发最大的坑在于坐标系混乱。高德/腾讯使用 GCJ-02，百度使用 BD-09，而 GPS 原始数据是 WGS-84。如果直接混用，打点误差会达到几百米甚至几公里，完全无法满足任务书“≤10m”的要求。

解决方案：

我们在 app_lib/map_widget.py 的入口处建立了严格的坐标清洗机制。无论后端返回的是哪种坐标系，前端统一转换为底图（如高德/腾讯底图）所需的 GCJ-02 坐标。这一步通常在数据进入 render_map 之前完成，确保视觉上的绝对精准。

3. 图层管理系统：拒绝硬编码

为了让地图不仅“能看”而且“好看、易用”，我设计了 frontend/app_lib/map_layers.py。这个文件不仅仅是一个枚举列表，它是整个地图系统的样式控制中心。

A. 标准化的图层枚举

我们定义了 POILayer 枚举，明确了四大核心周边设施类型：
 

class POILayer(str, Enum):
    SUBWAY = "subway"      # 地铁
    SCHOOL = "school"      # 学校
    COMMERCIAL = "commercial" # 商业
    HOSPITAL = "hospital"  # 医院

这样做的好处是显而易见的：代码中不再出现魔法字符串（Magic Strings），所有的图层引用都通过枚举进行强类型约束，极大地降低了后续维护出错的风险。

B. 视觉样式的集中配置

为了让用户一眼区分不同类型的 POI，我为每个图层配置了专属的颜色和半径。这些配置直接对应无障碍设计中的对比度要求：
 

图层	颜色 (Hex)	半径 (米)	视觉含义
地铁	#1f77b4 (蓝)	55m	交通枢纽，范围较大
学校	#2ca02c (绿)	45m	教育资源，静谧感
商业	#ff7f0e (橙)	40m	繁华区域，高亮警示
医院	#9467bd (紫)	45m	医疗配套，稳重感

设计细节：注意 LAYER_RADIUS_M 的设置。地铁因为站点覆盖范围广，半径设为 55m；而商业网点密集，设为 40m 以避免视觉上的过度重叠。

C. 智能图例生成器

为了提升用户体验，我编写了 legend_markdown 函数。它不再是写死的 HTML，而是根据用户当前勾选的图层动态生成图例。

def legend_markdown(visible: list[str]) -> str:
    lines = ["**图例**"]
    # 始终显示房源标记
    lines.append("- 🔴 **房源**（点击选中的标记）")
    for lid in visible:
        color = LAYER_COLORS.get(lid, "#888")
        # 动态插入颜色圆点
        lines.append(f"- <span style='color:{color}'>●</span> {layer_label(lid)}")
    return "\n".join(lines)

这样，当用户在侧边栏关闭“医院”图层时，图例也会自动隐藏医院项，保持界面的整洁与一致性。

4. 核心渲染引擎：map_widget.py 的“图层组装术”

有了标准化的图层定义，接下来就是如何将这些数据高效地“画”在地图上。在 frontend/app_lib/map_widget.py 中，我构建了一个轻量级的渲染管道，核心逻辑分为三步：数据清洗、图层组装与交互绑定。

A. 动态图层过滤与组装

用户不会永远想看所有 POI。为了响应侧边栏的开关操作，render_map 函数接收一个 visible_layers 列表。我们不再遍历所有数据，而是通过字典映射直接提取当前可见的图层数据：
 

# map_widget.py 核心逻辑示意
def render_map(listings, visible_layers, pois_by_layer, ...):
    # 初始化基础图层（房源点）
    layers = [create_listing_layer(listings)]

    # 仅叠加用户勾选的 POI 图层
    for layer_id in visible_layers:
        if layer_id in pois_by_layer:
            poi_data = pois_by_layer[layer_id]
            # 从 map_layers 获取该图层的专属样式（颜色/半径）
            style = get_layer_style(layer_id)
            layers.append(create_poi_layer(poi_data, style))

    # 使用 PyDeck 统一渲染
    deck = pdk.Deck(layers=layers, initial_view_state=view_state)
    st.pydeck_chart(deck)

这种设计确保了即使后端返回了海量数据，前端也只会渲染用户关心的部分，大幅降低了 WebGL 的显存压力。

B. 交互状态的双向绑定

地图不是静态图片，它是决策的起点。为了实现“点击地图 -> 右侧出详情”的联动，我们在 ScatterplotLayer 中配置了 pickable=True 和 auto_highlight=True。

当用户点击某个房源标记时，PyDeck 会触发 Streamlit 的回传事件。我们通过 st.session_state["selected_listing_id"] 捕获这个 ID，并立即触发右侧 render_selected_listing_panel 的重新渲染。
 

5.总结与展望

通过 map_layers.py 的标准化配置与 map_widget.py 的高效渲染，我们成功打造了一个高精度、可交互、可扩展的地图模块。

• 精度达标：坐标系统一网关确保了 ≤10m 的视觉误差。
• 体验升级：动态图例与点击联动让地图从“展示工具”变成了“分析工具”。
• 架构清晰：枚举与样式分离，为后续新增“公园”、“健身房”等图层预留了零成本扩展空间。

至此，我们的智能体已经具备了“记忆（持久化）、表达（报告）、洞察（图表）、决策（地图）”四大核心能力。