# M-20 周边地图 Widget PRD

版本：v0.5
状态：第一阶段 MVP 响应式交互原型已制作，待 Google 地图接入与开发

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-28 | v0.1 | 初始创建 | 定义项目固定位置、已配置 POI、Google 地图、分类切换、点位信息和移动端交互的 MVP 范围。 |
| 2026-07-28 | v0.2 | 重大：单语言发布规则 | M-20 在 MVP 中只读取页面实例确定的发布语言；POI、分类、说明和组件文案不得自动翻译或跨语言回退。 |
| 2026-07-29 | v0.3 | 重大：首次注意事项定稿 | 项目定义了地图注意事项时，用户在当前页面浏览会话首次进入 M-20 必须先看到并确认弹窗；未定义则不显示。 |
| 2026-07-29 | v0.4 | 重大：初始地图范围定稿 | 初始范围由 M-20 自动计算，包含项目锚点和默认分类有效 POI，不提供 A 端范围配置。 |
| 2026-07-29 | v0.5 | 重大：POI 图片必需性定稿 | POI 图片确认为可选；无图时隐藏图片区，不使用占位图或外部搜索图片。 |
| 2026-07-29 | v0.5 | 非重大：原型交付同步 | 已完成分类切换、项目锚点、POI 选择、信息卡、注意事项及局部错误的响应式交互原型；地图底图为原型模拟层。 |

## 1. Widget目标与使用页面

M-20 让顾客以固定项目位置为锚点，浏览项目已经配置并可公开的周边 POI。其数据是项目内闭环内容，不使用顾客定位、Google 自动搜索或实时路线结果补齐。

MVP 使用页面：[`../01-页面体系/02-周边地图页PRD.md`](../01-页面体系/02-周边地图页PRD.md)。

## 2. 内容清单与来源规则

| 内容 | 必需性 | 业务来源 | 使用规则 |
| --- | --- | --- | --- |
| 项目位置 | 必需 | 项目位置数据 | 使用已发布坐标作为唯一项目锚点；C 端不可拖动修改。 |
| Google 地图服务配置 | 必需 | 项目/环境级地图服务配置 | 只判断是否可用，不在 Widget 记录中保存密钥。 |
| POI 名称 | 必需 | 项目周边 POI 数据 | 只展示已配置且可公开点位。 |
| POI 坐标 | 必需 | 项目周边 POI 数据 | 无有效坐标的点位不展示。 |
| POI 分类 | 必需 | 项目周边分类数据 | 每个 POI 至少属于一个可用分类。 |
| POI 图片 | 可选 | POI 关联图片 | 无图时隐藏图片区域，不用 Google 搜索图片补位。 |
| POI 摘要/地址 | 可选 | POI 公开说明 | 只展示已配置内容；不自动推算距离或时间。 |
| 地图注意事项 | 可选 | 项目公开说明 | 有已定义且可公开内容时，在当前页面浏览会话首次进入时弹窗展示；未定义时不显示。 |

M-20 只使用页面实例传入的一种发布语言。POI 名称、分类名称、摘要/地址和注意事项必须来自同一语言上下文；当前语言必需内容缺失时不自动使用其他语言补位。

## 3. A端配置

| 配置项 | 规则 |
| --- | --- |
| 项目位置 | 自动读取项目已发布位置；本 Widget 不另建一套坐标。 |
| POI 选择 | 从项目已配置 POI 中选择进入本 Widget 的点位。 |
| POI 排序 | 支持配置点位顺序；未配置时使用项目数据默认顺序。 |
| 分类顺序 | 支持配置；无点位分类不进入 C 端。 |
| 默认分类 | 可选；未配置时使用第一个有可用点位的分类。 |
| 初始地图范围 | 不提供配置；由 M-20 自动包含项目锚点和默认分类有效 POI。 |
| 注意事项 | 可选内容；有定义则首次进入弹出，未定义则不出现空弹窗。 |
| 语言 | 不作为 Widget 内切换项；由页面实例统一传入发布语言。 |

## 4. 核心功能

### F-01 首次注意事项

- 项目定义了地图注意事项时，用户在当前页面浏览会话首次进入 M-20 必须先看到注意事项弹窗。
- 弹窗打开期间地图不可操作；用户通过明确的确认/关闭操作返回地图。
- 用户确认后，同一页面浏览会话内不重复弹出；新浏览会话再次按相同规则判断。
- 未定义注意事项时直接进入地图，不显示空弹窗或占位。
- 弹窗复用 VISTA C 弹窗组件语义；精确尺寸、位置和动效为 **待设计系统补充**。

### F-02 地图与项目锚点

- 加载 Google 地图并展示明确的项目锚点。
- 初次加载时自动计算可视范围，完整包含项目锚点和默认分类全部有效 POI。
- 自动范围需要保留标记与视口边缘之间的安全空间，并限制过近或过远的异常缩放；精确数值进入技术设计，不开放 A 端配置。
- 支持用户拖动、双指缩放和常规地图缩放。
- 提供“回到项目位置”动作，恢复以项目锚点为中心的可理解视野。

### F-03 POI 分类

- 只展示至少包含一个可用 POI 的分类。
- 手机端分类为单行横向滚动。
- 切换分类后更新地图标记，并清除前一分类的选中点位和信息卡。

### F-04 POI 选择与信息卡

- 点击地图标记或点位入口后选中对应 POI。
- 信息卡至少展示 POI 名称；图片、摘要、地址按可用性展示。
- POI 无图片时隐藏图片区域，不保留空白图片框，也不使用项目图、分类图标或外部图片补位。
- 手机端使用底部信息卡/面板，可关闭或展开；关闭不重置当前分类和地图视野。
- 不显示路线、距离/时间和外部地图按钮。

### F-05 局部失败与重试

- Google 地图失败：显示 Widget 局部错误和重试。
- 单个 POI 失败：移除该点位，不阻断其他点位。
- 分类数据部分失败：仅保留可用分类。
- Widget 局部失败不得触发任何整页系统状态。

## 5. 核心用户用例

### UC-01 确认首次注意事项

1. 用户首次进入当前页面浏览会话。
2. 项目已定义地图注意事项时，M-20 打开注意事项弹窗。
3. 用户阅读并确认/关闭。
4. 弹窗关闭并进入地图；当前浏览会话内不再重复显示。

项目未定义注意事项时跳过本用例，直接进入地图。

### UC-02 从项目位置浏览周边

1. Widget 加载项目锚点和默认分类 POI，并自动计算包含全部标记的初始范围。
2. 用户缩放/拖动地图。
3. 用户点击 POI。
4. Widget 展示该点位信息卡。

### UC-03 切换分类

1. 用户横向浏览分类并选择新分类。
2. Widget 清除旧选中状态。
3. 地图更新为新分类 POI。
4. 用户选择点位继续查看。

### UC-04 回到项目位置

1. 用户已拖动或缩放到其他区域。
2. 点击“回到项目位置”。
3. 地图重新显示项目锚点和当前分类的有效上下文。

### UC-05 Google 地图不可用

1. 地图服务加载失败。
2. Widget 显示局部错误和重试。
3. 用户可重试或离开本 Widget；页面其他组件继续可用。

## 6. 移动端与响应式

| 视口 | 内容与交互规则 |
| --- | --- |
| 320px / 375px | 地图主体；分类横向滚动；POI 详情使用底部面板；所有地图操作支持触控。 |
| 768px | 可按横竖屏选择底部或侧边详情，但不得遮挡项目锚点。 |
| 1024px / 1440px | 可将点位信息与地图并列；使用同一分类与选中逻辑，不复制旧 Demo 双层底栏布局。 |

## 7. 状态

| 状态 | 处理 |
| --- | --- |
| 可启用 | 项目位置、地图服务、至少一个 POI 和分类完整。 |
| 不可启用 | 任一必需前置缺失；阻止发布。 |
| 有注意事项且会话首次进入 | 先显示注意事项弹窗；确认后进入地图。 |
| 无注意事项 / 会话内已确认 | 不显示注意事项弹窗。 |
| 正常未选中 | 显示项目锚点、分类与 POI。 |
| 已选中 POI | 显示对应信息卡。 |
| POI 无图/无摘要 | 隐藏对应区域，保留有效点位，不显示占位图片。 |
| Google 地图失败 | 局部错误 + 重试。 |
| 部分 POI 失败 | 移除失败对象，其他内容继续。 |

## 8. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-M20-01 | 配置完整 | 320px、375px 打开 | 项目锚点、分类和 POI 可触控操作。 |
| AC-M20-02 | 用户切换分类 | 旧分类有选中点位 | 旧详情被清除，显示新分类点位。 |
| AC-M20-03 | 用户选择 POI | POI 有名称、可选图片/摘要 | 信息卡只展示可用内容，不推算路线或时间。 |
| AC-M20-04 | 用户拖离项目 | 点击回到项目位置 | 项目锚点重新进入明确视野。 |
| AC-M20-05 | Google 地图失败 | Widget 已加载 | 显示局部错误与重试，不触发全局错误页。 |
| AC-M20-06 | 必需配置缺失 | A 端发布 | Widget 不可启用，不用自动搜索结果补位。 |
| AC-M20-07 | PAD/PC 打开 | 视口扩展 | 可改变详情位置，但功能、数据和状态一致。 |
| AC-M20-08 | 项目已定义地图注意事项 | 用户在当前页面浏览会话首次进入 | 先显示注意事项弹窗；确认后进入地图且本会话不重复弹出。 |
| AC-M20-09 | 项目未定义地图注意事项 | 用户进入页面 | 不显示空弹窗，直接进入地图。 |
| AC-M20-10 | 项目锚点和默认分类 POI 有效 | 地图初次完成加载 | 初始视野自动完整包含项目锚点和全部默认分类 POI，不依赖 A 端范围配置。 |
| AC-M20-11 | POI 没有图片但其他必需数据有效 | 用户打开点位信息卡 | 正常显示文字信息，图片区域不占位且不使用替代图片。 |

## 9. 明确不做与待确认

**明确不做：** Google 自动搜索、用户定位、路线规划、距离/时间承诺、政府/风险图层、外部地图、收藏、预约和埋点。

**待确认：**

- 当前无阻塞开发的待确认项。

## 10. 截图参考边界

`截图/C端实际Demo/16-周辺マップ/16-周辺マップ.jpg` 用于确认项目锚点、POI 分类、点位标记、点位信息和首次注意事项的功能事实。旧桌面导航、浮动工具位置、底部双层列表及弹窗尺寸不继承。