# 周边地图页 PRD

版本：v0.11
状态：第一阶段 MVP 页面与通用组件范围已确认；响应式原型为设计参考，待 Google 地图接入与开发

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-28 | v0.1 | 初始创建 | 按“页面可分可合”原则创建周边地图页 PRD。 |
| 2026-07-28 | v0.2 | 重大：内容与移动端重写 | 以 M-20 地图主体、分类、POI 和移动端触控流程重写；现有周边地图截图仅作为功能证据，不继承其桌面悬浮布局。 |
| 2026-07-28 | v0.3 | 重大：导航退出 MVP | 确认本页 MVP 仅通过独立链接交付，不显示导航入口或页面集合；未来导航作为通用组件挂载，不改变地图 Widget。 |
| 2026-07-28 | v0.4 | 重大：分享退出 MVP | 确认分享属于未来通用组件；本页 MVP 仅保留独立访问 URL，不显示分享入口或分享弹窗。 |
| 2026-07-28 | v0.5 | 重大：国际化退出 MVP | 确认本页 MVP 不显示语言切换入口；分类、POI 和组件文案统一使用页面实例的发布语言，不做跨语言回退。 |
| 2026-07-28 | v0.6 | 重大：项目联系组件定稿 | 将原联系页脚改为页尾联系入口；点击后弹窗展示官网、邮箱、电话中的有效项，至少一项有效是本页发布前置。 |
| 2026-07-29 | v0.7 | 重大：首次注意事项定稿 | 项目定义了地图注意事项时，用户在当前页面浏览会话首次进入必须先确认弹窗；未定义时直接进入地图。 |
| 2026-07-29 | v0.8 | 重大：初始地图范围定稿 | 地图初始范围由 M-20 自动计算并包含项目锚点与默认分类有效 POI，不提供 A 端范围配置。 |
| 2026-07-29 | v0.9 | 重大：POI 图片必需性定稿 | POI 图片确认为可选；无图时信息卡仅展示有效文字内容，不保留图片占位。 |
| 2026-07-29 | v0.10 | 重大：顾客登录与权限进入 MVP | 本页支持公开访问和顾客登录后访问；受限访问先调用登录组件，登录后无本页授权进入 403，页面无效进入 404。 |
| 2026-07-29 | v0.10 | 非重大：原型交付同步 | 已完成分类、项目锚点、POI 选择、注意事项和局部错误的响应式交互原型；原型地图层为模拟视图，正式开发仍须接入 Google 地图。 |
| 2026-07-29 | v0.11 | 重大：项目 Logo 与导航进入 MVP | 本页增加独立项目 Logo 组件和“入口按钮＋全屏展开”导航组件；导航只显示同一集合内当前顾客可访问的同级页面，不改变 M-20。 |

## 1. 页面目标与范围

周边地图页让顾客以项目固定位置为锚点，查看项目已配置的周边设施及其分类关系。MVP 通过本页独立 URL 访问。

本页只有一个业务 Widget：**M-20 周边地图 Widget**。地图分类、项目锚点、POI 标记和 POI 信息卡是 M-20 的内部内容/组件，不拆成其他 Widget。项目 Logo、页面导航和项目联系是页面通用组件；顾客登录组件在页面展示前处理受限访问。它们均不属于 M-20。

## 2. 页面 Widget 与内容结构

进入地图内容前先按 [`../05-权限与访问控制规则.md`](../05-权限与访问控制规则.md) 完成访问判断。受限页面必须在加载 Google 地图、项目坐标和 POI 前调用 [`../03-通用组件体系/13-顾客登录组件PRD.md`](../03-通用组件体系/13-顾客登录组件PRD.md)，登录且有本页授权后才加载 M-20。

| 层级 | 页面对象 | 本页使用内容 | 用户动作 | 详细规则来源 |
| --- | --- | --- | --- | --- |
| 页面层 | 项目 Logo 组件 | 有效项目 Logo；缺失或加载失败时隐藏 | 只识别项目，不触发导航 | [`../03-通用组件体系/01-项目识别组件PRD.md`](../03-通用组件体系/01-项目识别组件PRD.md) |
| 页面层 | 页面导航组件 | 入口按钮与可访问同级页面的全屏导航 | 打开/关闭、切换页面 | [`../03-通用组件体系/02-页面导航组件PRD.md`](../03-通用组件体系/02-页面导航组件PRD.md) |
| 1 | 周边地图主体 | Google 地图、项目锚点、已配置 POI 标记 | 缩放、拖动、选择点位 | [`../02-Widget体系/Widget需求/03-周边地图Widget-PRD.md`](../02-Widget体系/Widget需求/03-周边地图Widget-PRD.md) |
| 2 | M-20 分类与点位信息 | POI 分类、当前点位名称、图片/摘要等可用信息 | 切换分类、查看/关闭点位卡 | 同上 |
| 3 | 项目联系组件 | 页尾联系入口；弹窗内展示有效的项目公共官网、邮箱、电话 | 打开/关闭弹窗，访问官网、发邮件或拨打电话 | [`../03-通用组件体系/03-项目联系组件PRD.md`](../03-通用组件体系/03-项目联系组件PRD.md) |

页面不增加路线、搜索、顾客定位、外部地图或政府图层。

## 3. 移动端优先布局

### 3.1 手机端 320px / 375px

1. 项目 Logo 与导航入口不得遮挡项目锚点、地图分类、缩放和回到项目等核心触控区域。
2. 地图是首屏主体，占据主要可视区域。
3. 项目定义注意事项时，当前页面浏览会话首次进入先显示注意事项弹窗；确认后才能操作地图。
4. POI 分类使用单行横向滚动，当前分类始终可识别；不得把全部分类挤成多行小按钮。
5. 选择 POI 后，从地图底部出现点位信息卡/底部面板；默认只占必要高度，可展开阅读、可关闭。
6. 点位没有图片时不显示空白图片区；文字信息仍按正常卡片布局展示。
7. 点位面板不得永久遮住项目锚点；打开时地图应保持可拖动与缩放。
8. 项目联系入口位于地图内容之后，不悬浮覆盖地图；联系方式只在点击后通过弹窗展示。

### 3.2 PAD / PC 响应式扩展

- 768px、1024px：地图保持主体，点位信息可根据横竖屏使用底部面板或侧边面板。
- 1440px：允许点位列表/详情与地图并列，但仍使用与手机端相同的分类、点位选择和关闭逻辑。
- 不继承现有截图中的左上导航、右侧工具排列、底部双层横栏和提示弹窗尺寸。

## 4. 核心用户用例

### UC-MAP-01 查看项目位置和周边设施

**前置条件：** 页面已发布；项目位置、Google 服务配置及至少一个可公开 POI 可用。

**主流程：**

1. 用户在手机打开周边地图页。
2. 如项目定义了注意事项，页面先显示弹窗，用户确认后进入地图。
3. 页面自动计算初始范围，并显示项目锚点和默认分类下全部有效 POI。
4. 用户拖动或缩放地图理解空间关系。
5. 用户点击 POI 标记或点位入口。
6. 页面显示该 POI 的信息卡；无图片时只展示有效文字。

**成功结果：** 用户无需路线规划或定位权限即可理解项目与周边设施的关系。

### UC-MAP-02 切换 POI 分类

1. 用户横向浏览可用分类。
2. 点击一个分类。
3. 地图只显示该分类的可用 POI，并清除前一分类已选点位及信息卡。
4. 用户可继续选择新分类中的点位。

**成功结果：** 分类和点位结果一致，不残留不可见分类的详情。

### UC-MAP-03 地图或部分 POI 失败

- Google 地图加载失败：M-20 显示局部错误和重试，不进入全局错误页。
- 单个 POI 资料缺失：隐藏缺失字段；点位名称/定位不足以成立时不展示该点位。
- 某分类无可用 POI：该分类不显示。
- 项目联系组件在地图失败时仍可使用。

### UC-MAP-04 登录后查看受限地图

1. 顾客打开不允许未登录访问的周边地图页。
2. 页面在请求项目坐标、POI 和 Google 地图前调用顾客登录组件。
3. 登录成功后校验当前顾客对本页面实例的授权。
4. 有授权时加载原地图页；无授权时进入 403。
5. 页面不存在、未发布、已下线或链接无效时进入 404。

## 5. 页面状态

| 状态 | 页面处理 |
| --- | --- |
| 正常 | 地图、项目锚点、分类和 POI 可用。 |
| 首次注意事项 | 有定义且当前浏览会话首次进入时显示；确认后关闭并进入地图。 |
| POI 已选中 | 显示底部点位卡；关闭后回到当前地图与分类。 |
| Google 地图失败 | Widget 局部错误与重试；其他页面对象可用。 |
| 部分分类/POI 不可用 | 隐藏无效对象，不影响其他可用内容。 |
| M-20 必需配置缺失 | 阻止页面发布，不显示空地图。 |
| 项目 Logo 缺失或失败 | 隐藏项目 Logo，不影响地图或导航。 |
| 没有其他可访问页面 | 隐藏导航入口，地图页仍独立可用。 |
| 受限页面尚未有效登录 | 调用顾客登录组件；不请求或渲染项目坐标、POI 和地图。 |
| 已登录但无本页授权 | 进入统一 403。 |
| 项目/页面不存在、未发布、已下线或链接无效 | 进入统一 404。 |

## 6. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-MAP-01 | 320px、375px 正常数据 | 用户打开页面 | 地图为主体，分类可横向操作，点位详情从底部出现且可关闭。 |
| AC-MAP-02 | 用户切换分类 | 前一分类有选中点位 | 前一详情被清除，只显示新分类 POI。 |
| AC-MAP-03 | 用户选择 POI | 点位资料可用 | 信息卡展示对应点位，不遮死项目锚点和地图操作。 |
| AC-MAP-04 | Google 地图失败 | 页面已进入 | 显示局部错误与重试，不进入整页系统状态。 |
| AC-MAP-05 | PAD/PC 打开 | 视口变宽 | 可改为侧边信息区，但分类、选择、关闭逻辑与手机端一致。 |
| AC-MAP-06 | 检查全部可见功能 | 用户操作 | 不出现搜索、定位、路线、外部地图、政府图层、预约。 |
| AC-MAP-07 | 页面实例指定一种发布语言 | 用户查看分类与点位 | 分类名称、POI 名称/摘要和组件文案使用同一语言，不自动混入其他语言。 |
| AC-MAP-08 | 页面正常发布且联系方式有效 | 用户点击页尾联系入口 | 弹窗打开并只展示有效的官网、邮箱、电话项，不遮死地图且可以关闭。 |
| AC-MAP-09 | 项目已定义地图注意事项 | 用户在当前页面浏览会话首次进入 | 弹窗先于地图操作出现；确认后本会话不重复弹出。 |
| AC-MAP-10 | 默认分类存在有效 POI | 地图初次加载完成 | 项目锚点和默认分类全部有效 POI 均在初始可视范围内。 |
| AC-MAP-11 | 选中的 POI 无图片 | 信息卡打开 | 不显示图片占位，名称及其他有效文字仍可读。 |
| AC-MAP-12 | 本页允许未登录访问 | 匿名顾客打开 | 直接加载 M-20，不出现登录组件。 |
| AC-MAP-13 | 本页不允许未登录访问且顾客尚未登录 | 打开链接 | 先显示登录组件，不请求或泄露项目坐标、POI 和地图内容。 |
| AC-MAP-14 | 顾客登录成功 | 完成当前页面授权校验 | 有授权加载原地图页；无授权进入 403。 |
| AC-MAP-15 | 页面集合存在其他可访问页面 | 用户打开并关闭导航 | 全屏导航只显示可访问同级页面；关闭后地图范围、分类和已选 POI 保持。 |
| AC-MAP-16 | 页面显示项目 Logo 与导航入口 | 用户操作地图 | 两个组件彼此独立，且不遮挡项目锚点、分类和地图核心触控。 |
| AC-MAP-17 | 当前没有其他可访问页面 | 页面渲染 | 导航入口隐藏，地图页仍可通过自身 URL 完成任务。 |

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

**明确不做：** Logo 与导航入口复用、固定首页/父子页面、分享入口、语言切换入口、自动翻译、复制链接、渠道面板、自动地点搜索、用户定位、路线规划、距离/时间承诺、政府/风险图层、外部地图跳转、预约、比较、顾客注册/找回密码、401 及 5xx 状态页和埋点。

**待确认：**

- 导航集合的既有 B 端来源待技术方案映射；项目 Logo 与导航入口的最终位置待设计稿确定。

## 8. 截图证据

- `截图/C端实际Demo/16-周辺マップ/16-周辺マップ.jpg` 证明现有能力包含首次注意事项、项目锚点、POI 分类、点位标记和点位图片/摘要。
- 截图中的桌面横屏排布、悬浮工具位置和完整导航不作为新布局要求。

## 9. 供 Codex 使用的执行说明

- 页面布局以移动端规则为准；M-20 内容与交互以 Widget PRD 为准。
- 不得把截图中的旧桌面布局直接响应式压缩到手机。
- 页面分别挂载项目 Logo 和导航组件；导航打开、关闭不得改变地图范围、分类或已选 POI。
- MVP 原型不显示分享占位；未来分享组件不得进入 M-20 或覆盖地图核心触控区域。
- MVP 原型不显示语言切换占位；M-20 只消费页面传入的一种发布语言。
- 受限页面登录和授权通过前不得初始化 Google 地图或请求项目坐标与 POI。
- 原型必须先验证 320px、375px 的地图触控、分类滚动和点位底部面板。