# 周边地图 Widget PRD

版本：v0.3
优先级：P0  
状态：已完成产品定义，待原型与实现验收

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-08-03 | v0.1 | 初始创建 / 重大重构 | 按当前 Widget 规范重写周边地图；明确项目锚点、POI 分类、路线、距离和时间参考均属于顾客任务的一部分。 |
| 2026-08-03 | v0.2 | 交互规则补充 | 根据 DeepSeek PM 评审明确地图视图调整及路线方式默认优先级，消除地图交互与默认路线的歧义。 |
| 2026-08-11 | v0.3 | 地图控制补充 | 增加指北针、回到当前位置、路线显示开关、缩放、街景，以及卫星/交通视图切换控制。 |

## 1. 基本信息

| 属性 | 定义 |
| --- | --- |
| Widget 名称 | 周边地图 |
| 唯一标识 | `surroundings-map` |
| 分类 | 周边环境 |
| 一句话介绍 | 以项目为起点浏览周边设施，并查看到指定地点的路线、距离和预估时间参考。 |
| 封面图 | 地图/周边环境的类型级展示图；实际运行内容以可交互地图为准。 |
| 设计图 | 可附地图、分类筛选、路线面板设计示意；示例点位须标注“设计示意”。 |

## 2. 目标与场景

目标顾客为评估通勤、日常生活便利度和周边可达性的潜在购房顾客。适用于项目介绍后的区位理解，也可作为独立周边环境内容。

顾客任务是确认项目位置、按类别查看 POI，并选择一个目的地获取从项目出发的路线、距离与时间参考。完成结果是顾客能对“去哪里、怎么去、大致多远/多久”形成判断；实际出行仍以地图服务当时结果为准。

## 3. 内容与数据

| 内容 | 必需性 | 内容来源与选择 | 有效条件 |
| --- | --- | --- | --- |
| 项目锚点与名称 | 必需 | 项目位置资料 | 坐标与顾客可读名称均有效。 |
| 基础地图 | 必需 | 已配置地图服务 | 服务可用并可覆盖项目锚点。 |
| POI 名称、位置、分类 | 必需 | 项目已选择的公开周边点位 | 至少有一个有效 POI。 |
| POI 图片、说明、营业信息 | 可选 | POI 资料 | 缺失时隐藏字段，不影响点位浏览。 |
| 路线、距离、时间参考 | 条件必需 | 地图服务针对选中 POI 的结果 | 顾客主动选择路线后加载；可用时显示。 |

POI 可多选并按分类、推荐顺序组织。项目锚点与 POI 必须属于当前项目的公开配置；不从其他项目或外部搜索结果中补点。

## 4. 使用与配置

| 配置项 | 规则 |
| --- | --- |
| POI 集合与分类 | 选择公开 POI；每个点必须归入至少一个顾客可读分类。 |
| 默认地图范围 | 以项目锚点与已选 POI 自动适配；没有有效 POI 时以项目锚点为中心。 |
| 默认分类 | 可指定一个分类；无效时显示全部。 |
| 路线方式 | 步行、驾车、公共交通可配置启用项；未配置时按“步行→公共交通→驾车”的首个当前可用方式作为默认。 |
| 路线入口 | 默认启用；关闭时仍可浏览地图与点位，但不显示路线操作。 |
| 地图控制 | 指北针、放大/缩小、路线显示开关、街景、卫星视图与交通视图切换默认可用；街景仅在地图服务支持当前点位时显示。 |
| 回到当前位置 | 默认启用；顾客授权定位后回到设备当前位置。未授权、定位失败或设备不支持时隐藏该动作，不以项目锚点冒充顾客当前位置。 |
| 无效配置 | 项目锚点或地图服务不可用时显示地图不可用状态；个别 POI 失效仅从列表与地图移除。 |

## 5. C端 UI 与交互

默认层级为：地图画布与项目锚点 → 分类筛选 → POI 标记/列表 → 选中 POI 详情 → 路线结果。初始显示项目锚点和默认/全部类别的有效点位。

顾客可缩放、平移地图，使用指北针恢复北向，切换分类、点击地图标记或列表项查看同一 POI 详情；地图视图调整不会改变当前分类或已选 POI。顾客授权定位后可回到设备当前位置；未授权、定位失败或设备不支持时不显示该动作。在详情中点击“查看路线”后选择可用方式，显示路线、距离和时间参考，并可通过路线显示开关隐藏或恢复当前路线。顾客可在可用时进入街景，并切换标准、卫星或交通视图。路线加载中显示局部加载；服务失败时保持地图和 POI 可用，显示“暂时无法获取路线”及重试。地图底图失败时显示 Widget 级地图不可用状态，仍可展示可读 POI 列表及其地址文本。窄屏使用全宽地图与可展开的 POI/路线底部面板；采用 VISTA C 地图、筛选、抽屉与加载/错误组件，精确地图控件规格待设计系统补充。

## 6. 用户用例与验收

**UC-01 按分类看周边**：顾客选择“交通”等分类，地图和列表同步显示该分类 POI，并可查看任一点位详情。

**UC-02 查询路线**：顾客选择一个 POI 和出行方式，取得由项目锚点出发的路线、距离与时间参考；失败时仍可回到点位详情。

| 验收编号 | 验收条件 |
| --- | --- |
| AC-01 | 项目锚点、地图和至少一个有效 POI 满足时，顾客可看到地图与分类点位。 |
| AC-02 | 分类切换、地图标记和列表项始终指向同一份有效 POI 结果。 |
| AC-03 | 查询路线后可显示所选方式对应的路线、距离和时间参考；切换方式会刷新结果。 |
| AC-04 | 路线失败仅影响路线区域，可重试且不清除已选 POI。 |
| AC-05 | 底图失败时仍保留可读 POI 列表；项目锚点或地图服务整体失效时显示明确的 Widget 级不可用状态。 |
| AC-06 | 移动端可完成筛选、选点、路线选择和返回浏览，不遮挡地图的关键操作。 |
| AC-07 | 顾客可使用指北针、缩放、路线显示开关、街景和卫星/交通视图切换；服务或设备不支持的控制不显示。 |
| AC-08 | 顾客授权定位后可回到设备当前位置；未授权、定位失败或设备不支持时不显示该动作，且不误导为已定位。 |