# 光明区文旅全域地图及POI数字化展示产品需求文档 V1.0

| 文档版本 | 创建日期 | 文档状态 | 适用交付 | 版本简述 |
|---|---|---|---|---|
| V1.0 | 2026-07-29 | 待产品、内容与技术评审 | 7 天微信小程序 POC | 根据上级细化任务，独立定义光明区全域地图探索与 POI 数字化展示需求 |

## 目录

- [1. 执行摘要](#1-执行摘要)
- [2. 文档说明](#2-文档说明)
- [3. 背景与问题](#3-背景与问题)
- [4. 产品目标与成功标准](#4-产品目标与成功标准)
- [5. 用户与使用场景](#5-用户与使用场景)
- [6. 产品范围](#6-产品范围)
- [7. 产品方案与信息架构](#7-产品方案与信息架构)
- [8. 功能需求](#8-功能需求)
- [9. 业务规则](#9-业务规则)
- [10. POI 数据需求](#10-poi-数据需求)
- [11. 能力、接口与工程适配](#11-能力接口与工程适配)
- [12. 非功能需求](#12-非功能需求)
- [13. 评估、隐私与安全](#13-评估隐私与安全)
- [14. 验收方案](#14-验收方案)
- [15. 交付物与 7 天计划](#15-交付物与-7-天计划)
- [16. 依赖与风险](#16-依赖与风险)
- [17. 决策与待确认事项](#17-决策与待确认事项)
- [18. 后续需求池](#18-后续需求池)
- [19. 需求追溯](#19-需求追溯)
- [20. PRD 自检](#20-prd-自检)

## 1. 执行摘要

本项目基于现有 `map-gm-app` uni-app 工程，在 7 天内交付一个面向微信小程序、仅在实际 iOS 环境验证的 POC。用户无需登录，也无需授权当前位置，即可打开深圳市光明区全域地图，了解经审核的文旅资源空间分布，按主分类探索 POI，点击地图 marker 查看摘要，并进入 POI 详情查看名称、图片、经纬度、简介、开放时间、官方推荐指数和特色标签等数字化信息。

本专项只验证“全域地图探索 + POI 数字化展示”的数据、交互和技术可行性。“全域地图导览”在本期特指地图浏览、拖动缩放、分类切换、marker 联动和 POI 信息查看，不包含 AI 问答、AI 路线、路径规划、路线绘制、实时导航或当前位置导览。此前讨论的真实定位打卡、积分、徽章和个人中心不属于本专项 P0，统一进入后续需求池。

“覆盖光明区全域”必须依据内容负责人签字确认的 POI 基准清单验收。未提供基准清单前，只能表述为“覆盖本期审核样本”，不能宣称已覆盖光明区全部文旅资源。高德地图供应商已确定且凭证已提供，但凭证类型、允许能力、配额、平台限制和微信小程序接入方式仍须在 Day 1 完成技术验证；完整凭证不得进入本文、代码仓库、截图或普通日志。

## 2. 文档说明

### 2.1 信息状态

| 标记 | 定义 | 执行要求 |
|---|---|---|
| 已确认 | 用户明确决定，或可从当前工程直接核实 | 作为本专项基线 |
| 资料事实 | 三份附件中的原始描述 | 用于背景和追溯，不自动形成 P0 承诺 |
| 产品细化 | 为形成可开发、可验收规则而补充 | 经产品评审后执行 |
| 假设 | 基于当前信息采用的临时方案 | 错误时需要调整数据、交互或排期 |
| 待确认 | 缺少内容、产品或技术决策 | 按第 17 章时限关闭 |
| 暂缓 | 本专项不处理且不阻塞本期 | 后续独立评审 |

### 2.2 资料来源与优先级

| 编号 | 来源 | 主要用途 | 优先级 |
|---|---|---|---|
| U2 | 用户最新上级细化任务 | 将本专项收敛为光明区全域地图探索与 POI 数字化展示，并明确 POI 必含信息 | 1 |
| U1 | `用户需求决策记录 V1.1` | 确认 7 天 POC、uni-app、微信小程序、iOS、高德及排除项 | 2 |
| C1 | 当前 `map-gm-app` 工程 | 确认技术基线和当前实现缺口 | 3 |
| S1 | `光明区文旅全域地图及AI导览POC建设方案.docx` | 提供全域地图、POI 和 7 天 POC 背景 | 4 |
| S2 | `文旅小程序三期规划方案202607091517.pptx` | 补充地图缩放、渐进展示、分类筛选和点位详情表达 | 5 |
| S3 | `文旅小程序三期规划方案20260709.pptx` | 提供长期文旅数据、运营和三期产品背景 | 6 |

发生冲突时采用 `U2 > U1 > C1 > S1 > S2 > S3`。附件中的 AI、路径规划、打卡、奖励、交易、后台和长期运营能力不会因为曾被提出而进入本专项。

### 2.3 产品、业务与技术边界

- 交付性质为 7 天 POC，不是正式上线版本，也不承诺生产 SLA、长期运营或完整数据治理。
- 目标端暂定微信小程序，本期只在实际记录的 iOS 环境验证，不验收 Android、H5、App 或其他小程序。
- 最低微信基础库和具体 iPhone 型号暂缓；每次测试必须记录实际 iPhone、iOS、微信、基础库、网络和构建版本。
- 前端使用现有 `map-gm-app` 的 uni-app、Vue 3、TypeScript、Pinia、uview-plus 和 UnoCSS 工程基线。
- 地图供应商确定为高德；具体 Key 类型、显示载体、SDK/Web Service 职责和安全限制属于技术准入项。
- POC 默认使用经审核的只读 POI 数据，不建设 CMS、运营后台、批量编辑或在线审核流程。
- 本文定义产品与验收规则，不替代像素级 UI 稿、接口详细设计、安全评审或地图供应商合同。

### 2.4 术语

| 术语 | 唯一定义 |
|---|---|
| POC | Proof of Concept，用最小可运行范围验证数据、交互和技术可行性，不等同正式产品 |
| POI | Point of Interest，本期指光明区内经确认需要数字化展示的文旅资源点位 |
| 全域地图 | 以光明区整体视野呈现本期有效 POI 的空间分布，并支持地图化探索 |
| 全域覆盖 | 经确认基准清单中的有效 POI 全部通过数据校验、发布并可从地图进入详情；不是泛指视觉上铺满地图 |
| 基准清单 | 由指定内容负责人去重、确认范围并签字的本期应上图 POI 集合 |
| marker | 地图上代表一个 POI 或一组聚合 POI 的可交互标记 |
| 摘要卡 | 点击单个 marker 后在地图页展示的 POI 简要信息浮层 |
| 官方推荐指数 | 由项目方指定负责人配置的 `1-5` 整数，不代表用户评分、平台热度或 AI 算法结果 |
| 特色标签 | 来自受控标签库、用于描述 POI 特色的标准标签，不接受自由文本同义词堆叠 |
| GCJ-02 | 中国大陆互联网地图常用坐标系；本期 POI 坐标统一采用该口径 |

## 3. 背景与问题

### 3.1 背景

三份附件均提出以地图承载光明区文旅资源，帮助用户建立区域认知，并逐步扩展路线、互动、会员、运营和交易能力。上级最新细化任务不要求一次建设完整文旅小程序，而是先把“光明区整体文旅资源分布”和“单个 POI 的标准数字档案”做成可运行、可检查的 POC。

当前 `map-gm-app` 可作为微信小程序开发骨架，但首页仍为 GitHub 示例请求，应用名称仍是模板名称，未发现地图、POI 或高德业务实现。因此，本期不能把现有工程视为已有地图业务，只能复用工程、组件、状态管理、样式和构建基础。

### 3.2 用户问题

| 问题 | 用户影响 | 本期应对 | 证据状态 |
|---|---|---|---|
| 光明区文旅资源信息分散，空间关系不直观 | 用户难以快速了解资源在哪里、如何分布 | 以光明区默认视野、marker 和分类呈现已审核资源 | 来自附件与上级任务，缺少游客研究数据 |
| POI 信息口径不统一 | 用户需要在多个来源之间查找图片、简介、开放时间等信息 | 建立统一 POI 字段合同和详情展示 | 来自上级明确字段要求 |
| 点位数据缺少可验收的覆盖口径 | “全域”容易变成无法验证的宣传表述 | 以基准清单覆盖率和字段完整率验收 | 产品细化 |
| 项目方尚未验证现有 uni-app 与高德能力的组合 | 7 天后可能只能展示静态原型，无法稳定运行 | Day 1 技术 Spike，Day 2 iOS 真机验证 | 当前工程核查结果 |

### 3.3 问题陈述

对于第一次了解或正在探索光明区的游客，需要一个无需登录和定位授权的地图入口，以较低操作成本了解文旅资源的整体分布，按兴趣分类发现地点，并查看可信、格式一致的 POI 信息。对于内容和项目负责人，需要一套明确的数据字段、审核状态、覆盖公式和验收用例，证明本期清单中的资源已经准确上图，而不是只完成若干演示点。

### 3.4 证据限制

- 未提供游客访谈、现有搜索路径、页面访问数据或业务转化基线。
- 未提供经官方确认的光明区 POI 基准清单、总数量、分类体系或街道维度。
- 未提供推荐指数的评分口径、配置人和更新责任。
- 未提供图片版权、开放时间来源和内容审核责任人。
- 因此，本 PRD 能形成研发和 POC 验收基线，但不能证明业务增长、游客偏好或正式版本投资回报。

## 4. 产品目标与成功标准

### 4.1 产品目标

| ID | 目标 | 本期验证方式 |
|---|---|---|
| OBJ-01 | 呈现光明区文旅资源整体空间分布 | 默认视野、全部 marker 和分类结果在目标 iOS 微信小程序正确展示 |
| OBJ-02 | 让用户完成从地图发现到详情查看 | 验证 `地图 -> 分类 -> marker -> 摘要卡 -> 详情` 主流程 |
| OBJ-03 | 建立统一、可审核的 POI 数字档案 | 校验名称、图片、经纬度、简介、开放时间、推荐指数、特色标签及治理字段 |
| OBJ-04 | 建立不夸大的全域覆盖口径 | 基准清单确定后按公式达到 100%；未确定前只验收审核样本 |
| OBJ-05 | 验证高德与现有 uni-app 工程的可行接入 | 完成高德最小调用、地图交互和 iOS 真机验证 |
| OBJ-06 | 为正式版本提供数据与技术风险清单 | 归档内容缺口、Key 限制、性能、图片域名和兼容结论 |

### 4.2 史诗假设

🔶 **假设**：如果把光明区经审核的文旅 POI 按统一字段发布到可分类探索的全域地图，并让用户从 marker 直接进入完整详情，那么未参与设计的体验用户能够在不登录、不授权位置的前提下理解资源分布，并找到和查看一个感兴趣的 POI；项目方能够据此识别正式建设所需的数据治理与地图技术投入。

验证方式：在目标 iOS 微信小程序完成数据验收、10 次核心脚本回归，并邀请 5 名未参与设计的测试者完成指定找点任务。5 人测试是 POC 可用性检查，不等同市场需求验证。

### 4.3 核心指标

| 类型 | 指标 | 目标 | 测量方式 |
|---|---|---|---|
| 主指标 | 基准清单有效上图覆盖率 | 基准清单确认后为 100% | 按第 9.1 节公式核对；无基准清单时不计算 |
| 数据 | POI 用户必看字段完整率 | 100% | 对已发布 POI 执行字段校验 |
| 数据 | 合法 GCJ-02 坐标率 | 100% | 数值、坐标系、光明区范围和人工审核校验 |
| 数据 | POI 真实封面验收可见率 | 100% | 对全部验收范围 POI 在交付构建和目标 iOS 环境逐一打开；占位图不计通过 |
| 一致性 | marker、摘要卡与详情映射准确率 | 100% | 对全部已发布 POI 按 `poiId` 抽检或自动核对 |
| 筛选 | 分类切换结果准确率 | 100% | 逐分类对比预期 POI ID 集合 |
| 交互 | 可点击 marker 选点准确率 | 100% | 对验收点位逐一点击或通过聚合逐一到达，共 N 次点击，正确摘要次数须为 N |
| 稳定性 | 核心浏览脚本 | 连续 10 次全部成功，无崩溃、错点或流程阻断 | 实际 iOS 环境执行第 14.1 节脚本 |
| 性能 | 地图首屏可交互时间 | 20 次测试 P95 不超过 3 秒 | 约定网络与同一构建版本 |
| 可用性 | 指定找点任务完成率 | 5 人中至少 4 人无需口头指导完成 | Day 6 任务测试 |
| 质量 | S0/S1 缺陷 | 交付前为 0 | 缺陷清单 |

### 4.4 护栏指标

- 未审核、草稿、已下线、坐标非法或坐标系未知的 POI 上图数量必须为 0。
- marker 点击后打开错误 POI 的次数必须为 0。
- 开放时间未知时不得伪造默认营业时间；推荐指数不得冒充用户评分、销量、热度或算法结论。
- 地图浏览不得要求登录、手机号、微信头像昵称或位置权限。
- 完整高德 Key、服务端安全密钥和签名材料进入文档、日志或仓库的数量必须为 0。
- 本期测试结论不得外推为所有 iOS 设备、Android 或未记录基础库版本均兼容。

### 4.5 POC 结论门槛

| 结论 | 条件 | 下一步 |
|---|---|---|
| 通过 | 已确认基准清单全部有效上图，主流程和指标达标，高德能力在记录环境稳定运行 | 可进入正式版本的数据后台、搜索和运营设计 |
| 样本通过 | 基准清单未确认，但本期审核样本全部有效上图且主流程达标 | 只证明样本方案可行，补齐清单后再验收“全域” |
| 有条件通过 | 地图和 POI 可运行，但图片域名、Key 限制、内容缺口或性能依赖人工处理 | 关闭专项风险后决定是否扩展 |
| 不通过 | 高德目标能力不可用、数据无法可信上图、错点或主流程不稳定 | 调整技术方案、数据责任或交付计划 |

## 5. 用户与使用场景

### 5.1 用户角色

| 角色 | 定位 | 主要目标 | 本期权限与边界 | 证据状态 |
|---|---|---|---|---|
| 地图探索游客 | 主要使用者 | 了解资源分布，按兴趣发现和查看 POI | 匿名浏览，无编辑能力 | 基于附件的假设用户 |
| 目的明确游客 | 次要使用者 | 在地图中识别已知 POI 并核对信息 | 名称搜索为 P1 | 基于常见场景的假设用户 |
| 内容负责人 | 数据责任人 | 确认基准清单、分类、字段来源和发布状态 | 本期通过线下数据表维护，不建设后台 | P0 支撑角色 |
| 产品负责人 | 范围与口径责任人 | 确认推荐指数、标签、覆盖规则和验收结论 | 维护决策记录 | P0 支撑角色 |
| 开发与测试人员 | 实现和质量责任人 | 验证高德、地图交互、数据校验和 iOS 表现 | 不得用假数据冒充内容验收 | P0 支撑角色 |

### 5.2 用户任务

| JTBD ID | 当…… | 我想要…… | 从而…… |
|---|---|---|---|
| JTBD-01 | 我不了解光明区有哪些文旅资源 | 打开一张覆盖整体区域的地图 | 快速建立资源分布认知 |
| JTBD-02 | 地图上的点位较多 | 按资源主分类切换 | 聚焦我感兴趣的地点类型 |
| JTBD-03 | 我看到一个感兴趣的 marker | 先查看名称、图片和摘要 | 判断是否值得进一步了解 |
| JTBD-04 | 我需要做访问决策 | 查看完整简介、开放时间、坐标、推荐指数和特色标签 | 获得格式一致的参考信息 |
| JTBD-05 | 我从详情返回地图 | 回到之前的地图位置和筛选状态 | 继续探索而不必重新操作 |

### 5.3 核心场景

| 场景 ID | 场景 | 预期结果 |
|---|---|---|
| SCN-01 | 首次打开地图 | 展示光明区默认视野和全部已发布 POI，不要求登录或定位 |
| SCN-02 | 切换主分类 | 只显示分类匹配的已发布 POI，并同步更新结果数和视野 |
| SCN-03 | 点击单个 marker | 显示与 marker 相同 `poiId` 的摘要卡和选中状态 |
| SCN-04 | 从摘要进入详情 | 展示全部必看字段和正确图文，不串点 |
| SCN-05 | 返回地图 | 恢复进入详情前的分类、中心、缩放和已选 POI |
| SCN-06 | 分类无结果 | 显示空状态和清除分类动作，不显示错误 marker |
| SCN-07 | POI 数据加载或解析失败 | 停止半成品渲染，显示可理解错误和重试 |
| SCN-08 | 图片加载失败 | 使用统一占位图，名称和其他文本仍可查看 |
| SCN-09 | POI 已下线或 ID 不存在 | 详情显示失效提示并可返回地图，不展示旧详情冒充成功 |

## 6. 产品范围

### 6.1 本期必做 P0

| 能力 | 本期结果 | 范围说明 |
|---|---|---|
| 光明区默认视野 | 打开首页可理解为光明区整体资源地图 | 默认中心、缩放或包含点位范围由配置决定 |
| 地图基础交互 | 支持拖动和缩放 | 不包含路线、导航和轨迹 |
| POI marker | 展示全部通过发布校验的 POI | 单个 marker 必须可追溯至稳定 `poiId` |
| 主分类 | 支持“全部”和经确认主分类单选 | 分类实际枚举由内容负责人确认 |
| 分类结果 | marker、数量、视野和空状态使用同一结果集 | 快速切换以最后一次选择为准 |
| marker 联动 | 点击 marker 展示选中态和 POI 摘要卡 | marker、摘要和详情保持同一 POI |
| POI 摘要卡 | 展示封面、名称、分类、短简介、官方推荐指数和特色标签 | 可进入详情 |
| POI 详情 | 展示名称、图片、经纬度、简介、开放时间、官方推荐指数、特色标签 | 同时建议展示分类、地址和更新时间 |
| 数据状态 | 只展示已审核、已发布且坐标合法的 POI | 草稿、驳回、下线和无效记录不上图 |
| 异常状态 | 覆盖加载、空、失败、重试、图片失败和失效 POI | 不显示半成品或错误关联 |
| 数据校验 | 校验必填字段、坐标、ID、分类、标签、推荐指数、图片和审核状态 | 校验失败必须给出具体记录和原因 |
| iOS POC 验收 | 在实际记录的 iOS 微信小程序环境完成回归 | 不外推未测环境 |

### 6.2 条件范围 P1

| 能力 | 纳入条件 | 不满足时处理 |
|---|---|---|
| POI 名称搜索 | POI 数量、别名数据和 UI 余量支持 | P0 只通过分类与地图探索 |
| 特色标签筛选 | 受控标签库已确认且样本量有区分价值 | 标签只在摘要和详情展示 |
| 街道维度筛选 | 街道编码和归属全部审核完成 | 不显示街道筛选 |
| 光明区行政边界 | 获得合法、准确的边界数据且 iOS 地图渲染验证通过 | 以默认视野和点位范围表达全域 |
| POI 聚合 | POI 数量超过阈值或实测出现性能、遮挡问题 | 数量较少且性能达标时直接渲染 marker |
| 官方推荐排序 | 推荐指数配置责任、同分规则和排序用途确认 | P0 只展示指数，不用于榜单或默认排序 |
| 坐标复制 | 产品确认用户确有复制需求且交互通过 | P0 只展示坐标 |
| 数据业务 API | 已有稳定后端、协议、合法域名和负责人 | 使用本地审核 JSON |

P1 只有在全部 P0 达到可验收状态后才可纳入。P1 不得挤占数据审核、高德接入、marker 映射和 iOS 回归时间。

### 6.3 明确不在本专项

- AI 助手、AI 问答、AI 推荐、AI 路线、知识库、模型接口和 AI 指标。
- 路径规划、站点编排、polyline、道路级路线、外部导航、实时导航和动态重排。
- 真实定位、当前位置、定位权限、到点判断、打卡、虚拟定位或模拟定位测试入口。
- 积分、徽章、任务、挑战、排行榜、个人中心和本机用户资产。
- 登录、会员、收藏、评论、游记、UGC、关注和个性化推荐。
- 活动、优惠券、商品、订单、支付、退款、核销、分账和对账。
- CMS、运营后台、商户后台、监管端、数据大屏和在线审核。
- Android、H5、App、其他小程序和最低基础库兼容承诺。
- 生产级监控、万人并发、等保验收和长期运维 SLA。

### 6.4 POC 与正式版本边界

| 维度 | 本期 POC | 正式版本至少需要补充 |
|---|---|---|
| POI 内容 | 审核后的本地数据或已有 API 快照 | CMS、角色权限、审批、版本、定时上下线和审计 |
| 覆盖 | 经确认清单或审核样本 | 持续盘点、增量发现、下线机制和覆盖周期 |
| 推荐指数 | 负责人手工配置的官方指数 | 评分标准、复核机制、更新频率和申诉规则 |
| 地图性能 | 针对本期数据量和单一 iOS 环境 | 多设备、海量点位、分级加载、缓存和监控 |
| 用户数据 | 无登录、无用户资产 | 身份、授权、隐私、账户和跨设备状态 |
| 运维 | 随包数据或受控服务 | 正式域名、发布、回滚、告警、SLA 和供应商配额治理 |

## 7. 产品方案与信息架构

### 7.1 方案概述

本期采用“地图作为入口、POI 作为唯一主数据”的两层方案。全域地图首页负责呈现空间分布、分类切换、marker 选择和摘要卡；POI 详情页负责呈现完整数字档案。地图 marker、摘要卡、详情路由和数据记录只通过稳定的 `poiId` 关联，不通过名称、数组下标或坐标反向猜测。

POI 数据在进入应用前完成标准化和审核。只有 `publishStatus=published`、`reviewStatus=approved`、必填字段完整且 GCJ-02 坐标合法的记录才能进入地图结果集。POC 默认采用本地审核 JSON 加远程或包内图片，降低 7 天内后端、合法域名和现场网络风险；若已有稳定业务 API，可在不改变 POI 合同的前提下替换数据仓储适配器。

### 7.2 核心用户流程

```mermaid
flowchart TD
    A[打开微信小程序] --> B{地图与 POI 数据是否可用}
    B -- 否 --> B1[显示错误原因和重试]
    B1 --> B
    B -- 是 --> C[展示光明区默认视野和全部 POI]
    C --> D{是否切换主分类}
    D -- 是 --> E[更新结果集 marker 数量和视野]
    D -- 否 --> F[继续浏览地图]
    E --> F
    F --> G[点击单个 POI marker]
    G --> H[选中 marker 并展示摘要卡]
    H --> I{是否查看详情}
    I -- 否 --> F
    I -- 是 --> J[按 poiId 打开 POI 详情]
    J --> K{POI 是否仍有效}
    K -- 否 --> K1[显示失效提示并返回地图]
    K -- 是 --> L[展示完整数字档案]
    L --> M[返回并恢复地图状态]
```

### 7.3 页面与浮层

| 页面/浮层 ID | 名称 | 建议路由/形态 | 主要内容 | 优先级 |
|---|---|---|---|---|
| PAGE-01 | 全域地图首页 | `/pages/map/index` | 地图、分类、marker、结果数、加载/空/失败状态 | P0 |
| OVERLAY-01 | POI 摘要卡 | 地图页浮层 | 封面、名称、分类、短简介、推荐指数、特色标签、详情入口 | P0 |
| PAGE-02 | POI 详情页 | `/pages/poi/detail?poiId=` | 用户必看字段、地址、数据更新时间和异常状态 | P0 |
| OVERLAY-02 | 聚合点列表或缩放反馈 | 地图页浮层/地图行为 | 触发聚合条件后负责聚合点展开、放大及逐个成员 POI 可达 | 条件 P0 |

本期只需要两个业务路由，不通过拆分浮层凑页面数量。地图首页应作为小程序启动页；详情返回使用页面栈恢复地图状态。

### 7.4 页面状态关系

| 状态 | 触发 | 页面表现 | 下一步 |
|---|---|---|---|
| `initial_loading` | 首次读取地图和 POI 数据 | 显示骨架或明确 Loading，不渲染半成品 marker | 成功或失败 |
| `ready` | 地图和数据均可用 | 展示当前结果集 | 浏览、筛选、选点 |
| `filter_empty` | 当前分类无已发布 POI | 展示“当前分类暂无点位”和清除动作 | 返回全部 |
| `data_error` | 数据读取、解析或校验失败 | 显示错误标识和重试，不保留错误 marker | 重试 |
| `map_error` | 地图能力初始化失败 | 显示地图服务暂不可用和重试 | 重试或记录阻塞 |
| `poi_selected` | 点击有效单点 marker | marker 选中，摘要卡展示同一 POI | 查看详情或取消 |
| `poi_invalid` | 详情 ID 不存在、已下线或校验失败 | 显示点位不可用，可返回地图 | 返回 |
| `image_fallback` | 图片加载失败 | 使用统一占位图，文本继续展示 | 可继续浏览 |

## 8. 功能需求

### 8.1 MAP：全域地图初始化与浏览

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| MAP-001 | 启动入口 | 小程序启动后进入全域地图首页，不显示模板示例页 | P0 |
| MAP-002 | 高德能力接入 | 使用 Day 1 验证通过的高德官方支持方案；失败返回可诊断错误，不静默换成未约定供应商 | P0 |
| MAP-003 | 默认区域 | 默认视野包含光明区经确认 POI 的整体分布；无有效 POI 时使用配置中心和缩放级别 | P0 |
| MAP-004 | 地图操作 | 支持单指拖动和双指缩放，操作期间不误触详情 | P0 |
| MAP-005 | 无位置依赖 | 首页加载、地图浏览和 POI 查看均不得申请用户位置权限 | P0 |
| MAP-006 | 结果数量 | 显示当前分类下有效 POI 数量；数量与 marker 数据源一致 | P0 |
| MAP-007 | 视野恢复 | 从详情返回时恢复进入前的中心、缩放、分类和选中 POI | P0 |
| MAP-008 | 初始化失败 | 地图失败时说明“地图服务暂不可用”，提供重试并记录脱敏错误码 | P0 |
| MAP-009 | POI 加载失败 | 数据失败时不渲染上一次错误或部分结果，提供重试 | P0 |
| MAP-010 | 行政边界 | 只有边界数据来源和真机渲染通过后才显示，不以虚构轮廓代替 | P1 |

**US-01：查看光明区整体资源分布**

作为第一次了解光明区的游客，我希望打开小程序后直接看到光明区文旅 POI 的整体分布，从而快速建立区域认知。

```gherkin
场景: 首次正常打开全域地图
  假如 高德地图能力和已审核 POI 数据均可用
  当 游客打开微信小程序
  那么 页面进入光明区默认视野
  并且 只显示所有符合发布规则的 POI marker
  并且 页面不要求登录或位置权限
```

```gherkin
场景: POI 数据中包含非法记录
  假如 一条记录的坐标系未知或必填字段缺失
  当 系统构建地图结果集
  那么 该记录不得生成 marker
  并且 校验结果指出记录 ID 和失败原因
```

### 8.2 FILTER：分类探索

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| FILTER-001 | 分类入口 | 地图页展示“全部”和当前启用的主分类；无已发布 POI 的分类默认不显示 | P0 |
| FILTER-002 | 单选规则 | P0 每次只允许选择一个主分类，“全部”清除分类限制 | P0 |
| FILTER-003 | 结果一致 | marker、结果数、空状态和视野使用同一 `poiId` 结果集 | P0 |
| FILTER-004 | 最后选择生效 | 快速连续切换时只提交最后一次有效选择，旧结果不得覆盖新结果 | P0 |
| FILTER-005 | 视野调整 | 非空分类切换后调整视野以包含筛选结果；空结果保留当前视野 | P0 |
| FILTER-006 | 选择失效 | 若当前选中 POI 不属于新分类，取消 marker 选中并关闭摘要卡 | P0 |
| FILTER-007 | 空结果 | 显示“当前分类暂无点位”和“查看全部”动作 | P0 |
| FILTER-008 | 标签筛选 | 仅在受控标签和交互确认后支持，可与主分类组合 | P1 |
| FILTER-009 | 名称搜索 | 支持名称或审核别名匹配，搜索规则另行确认 | P1 |
| FILTER-010 | 街道筛选 | 只有全部 POI 的街道编码审核完成后显示 | P1 |

**US-02：按分类探索 POI**

作为对某类文旅资源感兴趣的游客，我希望切换一个主分类，从而只查看属于该类的 POI。

```gherkin
场景: 切换有效主分类
  假如 当前展示“全部”且分类 A 有三个已发布 POI
  当 游客选择分类 A
  那么 地图只展示这三个 POI
  并且 结果数显示为 3
  并且 视野包含这三个结果
```

```gherkin
场景: 快速连续切换分类
  假如 游客依次快速选择分类 A 和分类 B
  当 分类 B 是最后一次有效选择
  那么 最终 marker 和结果数只对应分类 B
  并且 分类 A 的旧结果不得再次覆盖页面
```

### 8.3 MARKER：点位呈现与联动

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| MARKER-001 | 单点关联 | 每个单点 marker 关联唯一 `poiId`；若平台 marker ID 只接受数字，建立稳定数字 ID 到 `poiId` 的映射 | P0 |
| MARKER-002 | 分类识别 | 不同主分类使用可识别的图标或文字，不只依赖颜色 | P0 |
| MARKER-003 | 默认状态 | 未选中 marker 不遮挡主要地图操作，样式保持一致 | P0 |
| MARKER-004 | 选中状态 | 点击后突出当前 marker，并取消前一个 marker 的选中状态 | P0 |
| MARKER-005 | 点击联动 | 点击单点 marker 后，摘要卡必须展示同一 `poiId` 的数据 | P0 |
| MARKER-006 | 地图点击 | 点击非 marker 地图区域可关闭摘要卡并清除选中态 | P0 |
| MARKER-007 | 连续点击 | 快速点击不同 marker 时，以最后一次点击对应 POI 为准 | P0 |
| MARKER-008 | 下线同步 | 数据版本中已下线 POI 不得继续生成 marker | P0 |
| MARKER-009 | 重叠与性能 | 当 POI 数量或重叠导致性能/可点击性不达标时，聚合或视野分级渲染连同逐点展开能力整体升为 P0 | 条件 P0 |
| MARKER-010 | 聚合行为 | 启用聚合时，点击聚合 marker 后放大或展示组内点位，最终必须能选择每个成员 POI；不得直接打开任意一个 POI 详情 | 条件 P0 |

🔶 **假设**：初始 `markerRenderThreshold` 暂定为 `100`。当已发布 POI 数量超过该阈值，地图首屏 P95 超过 3 秒，或逐点选点准确率低于 100% 时，聚合或视野内渲染及其逐点展开交互整体升为 P0；阈值需根据目标 iOS 真机结果调整。

### 8.4 CARD：POI 摘要卡

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| CARD-001 | 展示字段 | 展示封面、名称、主分类、短简介、官方推荐指数和 1-5 个特色标签 | P0 |
| CARD-002 | 字段来源 | 所有字段来自当前 `poiId` 的同一版本记录，不跨记录拼接 | P0 |
| CARD-003 | 推荐标识 | 文案明确为“官方推荐指数 X/5”，不得只显示星形造成用户评分误解 | P0 |
| CARD-004 | 标签展示 | 标签按配置顺序展示；空间不足时截断数量，不截断为其他同义标签 | P0 |
| CARD-005 | 图片失败 | 封面失败时显示统一占位图，不隐藏名称和详情入口 | P0 |
| CARD-006 | 详情入口 | 点击卡片明确区域进入当前 `poiId` 的详情页 | P0 |
| CARD-007 | 关闭方式 | 支持点击地图空白区域或关闭控件收起卡片 | P0 |
| CARD-008 | 无效数据 | 当前 POI 在交互期间失效时关闭卡片并显示数据已更新提示 | P0 |

**US-03：从 marker 查看摘要**

作为正在浏览地图的游客，我希望点击 marker 后先看到简短信息，从而决定是否进入详情。

```gherkin
场景: 连续点击两个 marker
  假如 marker A 关联 POI-A，marker B 关联 POI-B
  当 游客先点击 A 再点击 B
  那么 最终只有 B 保持选中
  并且 摘要卡展示 POI-B 的名称、图片和信息
  并且 进入详情时路由参数为 POI-B 的 poiId
```

### 8.5 DETAIL：POI 数字化详情

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| DETAIL-001 | 名称 | 展示审核后的 POI 正式名称 | P0 |
| DETAIL-002 | 图片 | 展示封面或图集；至少一张审核可用图片，运行时失败使用占位图 | P0 |
| DETAIL-003 | 经纬度 | 展示经度、纬度并标注 `GCJ-02`，建议保留 6 位小数 | P0 |
| DETAIL-004 | 简介 | 展示完整简介；摘要和完整简介分别使用 `summary`、`description` | P0 |
| DETAIL-005 | 开放时间 | 展示经审核的开放时间；未知时固定显示“开放时间待确认” | P0 |
| DETAIL-006 | 推荐指数 | 展示“官方推荐指数 X/5”，数值只允许 `1-5` 整数 | P0 |
| DETAIL-007 | 特色标签 | 展示受控标签库中的 1-5 个标签 | P0 |
| DETAIL-008 | 补充信息 | 建议展示主分类、地址和数据更新时间，帮助用户理解数据时效 | P0 |
| DETAIL-009 | 图文滚动 | 长简介和多图内容可正常滚动，不与地图原生层级冲突 | P0 |
| DETAIL-010 | ID 不存在 | `poiId` 缺失或不存在时显示“点位不存在或已下线”，可返回地图 | P0 |
| DETAIL-011 | 状态复核 | 详情渲染前复核发布状态；已下线记录不得继续展示为有效详情 | P0 |
| DETAIL-012 | 返回恢复 | 返回地图后恢复原分类、中心、缩放和选中 POI | P0 |
| DETAIL-013 | 外部动作 | 电话、预约、购票、导航和分享不因字段存在自动显示 | 范围外/P1 |

**US-04：查看完整 POI 数字档案**

作为对一个 POI 感兴趣的游客，我希望查看完整且口径一致的信息，从而判断它是否符合我的兴趣和开放安排。

```gherkin
场景: 查看信息完整的已发布 POI
  假如 POI 已审核、已发布且所有必填字段合法
  当 游客从摘要卡进入详情
  那么 页面展示名称、至少一张图片、GCJ-02 经纬度、简介、开放时间、官方推荐指数和特色标签
  并且 所有内容都属于路由中的同一 poiId
```

```gherkin
场景: 开放时间未知
  假如 POI 的 openingHours.status 为 unknown
  当 游客查看详情
  那么 页面显示“开放时间待确认”
  并且 不显示任何伪造的默认营业时段
```

```gherkin
场景: 图片运行时加载失败
  假如 POI 文本字段合法但远程图片请求失败
  当 详情页完成加载
  那么 对应图片区域显示统一占位图
  并且 名称、简介、开放时间、推荐指数和标签仍可查看
```

### 8.6 DATA：数据加载、校验与版本

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| DATA-001 | 统一合同 | 本地 JSON 与业务 API 必须映射为第 10 章同一 POI 模型 | P0 |
| DATA-002 | 启动校验 | 读取后校验数据包版本、唯一 ID、字典引用、必填字段、坐标、状态和 URL | P0 |
| DATA-003 | 整包失败 | 数据包元信息/版本缺失、根结构错误、无法解析、字典重复或缺失、`id` 重复时整包失败，不展示任何 marker | P0 |
| DATA-004 | 单条隔离 | 仅当整包结构和字典有效、错误可明确归属单一 POI 时隔离该条；基准清单记录被隔离后覆盖率不得记为 100% | P0 |
| DATA-005 | 版本一致 | 列表、摘要和详情使用同一 `datasetVersion`，避免更新期间串版 | P0 |
| DATA-006 | 加载重试 | 网络或数据仓储失败时允许重试，旧请求不得覆盖新结果 | P0 |
| DATA-007 | 数据来源 | 每个 POI 记录内容来源、审核人和更新时间，前台至少展示更新时间 | P0 |
| DATA-008 | 本地数据 | 使用本地 JSON 时，发版即代表数据版本更新，不承诺无发版在线更新 | P0 |
| DATA-009 | API 数据 | 采用 API 时必须处理超时、业务错误、空数据、版本和取消旧请求 | 条件 P0 |

## 9. 业务规则

### 9.1 “全域覆盖”计算规则

设：

- `S`：由项目方认可的权威来源总表中，经过去重的候选文旅资源数量；总表必须声明资源类型范围、地理范围、统计截止日期、出具方和版本。
- `E`：来源总表中经内容负责人提出、产品负责人复核后明确排除的唯一 POI 数量；每条必须记录排除原因和证据。
- `B`：冻结基准清单的唯一 POI 数量，必须满足 `B = S - E`。
- `P`：`B` 中同时满足“审核通过、发布成功、必填字段合法、GCJ-02 坐标合法、可通过单点或聚合展开从地图到达、摘要可打开、详情可访问、真实封面在验收环境可见”的唯一 POI 数量。
- `C`：基准清单有效上图覆盖率。

计算公式：`C = P / B * 100%`。

执行规则：

1. `S=0`、`B=0`、来源总表未声明范围/截止日期/出具方，或基准清单未由内容负责人和产品负责人共同签字时，不得计算或宣称全域覆盖率。
2. 排除项必须保存在独立台账，至少包含原始记录、排除原因、证据、提出人、复核人、时间和清单版本；“字段不全、图片缺失、坐标错误、来不及处理”不得作为排除理由。
3. 因坐标、图片、开放时间、推荐指数或审核缺失而无法发布的记录仍保留在 `B` 中并计为缺口，不能为提高覆盖率而静默删除。
4. 基准清单冻结后，任何新增、排除、合并或拆分必须由内容负责人提出、产品负责人复核，生成新版本和新旧差异；旧版覆盖结果保留，禁止覆盖原记录。
5. 同一资源重复记录去重后只计一个 POI；去重规则、原始 ID、合并目标和证据须留档。
6. 启用聚合时，POI 只要能从聚合点通过确定交互最终选择并打开正确摘要，即满足“地图可达”；不要求默认缩放下同时呈现独立 marker。
7. 没有官方来源总表和双人冻结基准清单时，可计算“审核样本有效上图率”，名称必须包含“样本”，不得写为“光明区全域覆盖率”。

### 9.2 POI 发布与可见性规则

| 规则 ID | 规则 |
|---|---|
| BR-POI-01 | 每个 POI 必须有全局唯一、稳定且不复用的 `id` |
| BR-POI-02 | 只有 `publishStatus=published` 且 `reviewStatus=approved` 的记录可进入前台候选集 |
| BR-POI-03 | 候选记录必须通过必填字段、坐标、分类、标签、图片和推荐指数校验后才能上图 |
| BR-POI-04 | `draft`、`offline`、`pending`、`rejected` 或校验失败记录不得显示 marker、摘要或有效详情 |
| BR-POI-05 | marker、摘要、详情和验收记录必须通过 `poiId` 关联，不使用名称或数组下标作为业务键 |
| BR-POI-06 | 已发布 POI 下线后不得从旧缓存继续进入有效详情；返回地图时同步移除 marker |
| BR-POI-07 | 数据更新时间改变但 `id` 不变；不同数据包通过 `datasetVersion` 区分 |

### 9.3 分类与特色标签规则

- 一个 POI 必须且只能有一个启用的主分类 `categoryCode`。
- 主分类来自受控分类字典，分类编码一经发布不得随意复用给其他含义。
- 每个 POI 必须配置 `1-5` 个特色标签；标签通过 `tagCode` 引用受控标签字典。
- 标签不得使用未经审核的自由输入；“亲子”“亲子友好”等同义表达须合并为一个标准标签。
- 同一 POI 不得重复引用同一标签；失效标签不得继续展示。
- 标签顺序由 POI 配置决定；未配置顺序时按标签字典 `sortOrder`。
- 🔵 **待确认**：正式主分类、标签库及是否增加街道维度。本文不预设光明区实际资源分类，以免附件示例被误当作最终字典。

### 9.4 官方推荐指数规则

🔶 **假设**：本期采用运营人工配置的 `1-5` 整数，前台统一命名为“官方推荐指数”。

| 数值 | 展示语义 | 说明 |
|---|---|---|
| `1` | 1/5 | 基础推荐 |
| `2` | 2/5 | 一般推荐 |
| `3` | 3/5 | 推荐 |
| `4` | 4/5 | 重点推荐 |
| `5` | 5/5 | 强烈推荐 |

执行规则：

- `recommendationIndex` 是已发布 POI 的必填字段，只允许整数 `1-5`。
- 必须记录 `recommendationSource=official_editorial`、配置负责人和更新时间。
- 未确认评分依据前，本期只展示指数，不默认按指数排序，也不生成“热门榜”“口碑榜”。
- 页面不得使用“用户评分”“多少人评价”“热度”等无数据来源文案。
- 推荐指数缺失或越界时记录不得发布；不能以 `0` 或默认 `5` 兜底。

### 9.5 开放时间规则

| `openingHours.status` | `displayText` 规则 | 前台表现 |
|---|---|---|
| `known` | 必填，使用内容负责人审核文本 | 原样展示经审核时段 |
| `unknown` | 可为空 | 固定展示“开放时间待确认” |
| `by_appointment` | 必填预约说明 | 展示“需预约”及审核说明 |
| `temporarily_closed` | 必填临时关闭说明 | 明确展示“临时关闭”，不得只展示旧时段 |

- POC 不根据当前系统时间推断“营业中/已打烊”，除非后续提供结构化周历、节假日和临时闭馆规则。
- 开放时间文本需记录来源更新时间；无法确认时使用 `unknown`，不得从搜索结果或同类地点复制。

### 9.6 图片规则

- 每个已发布 POI 至少通过 `coverImageId` 引用一张审核可用的图片资产。
- `imageIds` 可引用 `0-8` 张详情图；为空时详情复用封面，不显示空轮播。
- 图片必须是包内合法资源或 HTTPS 地址；远程域名须加入微信小程序合法域名并在体验版验证。
- 每一张封面和详情图都必须记录来源、授权状态和授权证据；无法确认版权的图片不得进入交付数据。
- 发布校验验证 URL 格式和一次实际加载；运行时失败使用统一占位图并记录不含完整 URL 参数的错误。占位图只用于故障降级，不计入图片 P0 验收成功。
- 交付前须在目标 iOS 构建逐一打开全部验收范围 POI，至少真实封面可见率达到 100%；任一 POI 只显示占位图时不得计入 `P`。
- 图片不得携带高德 Key、用户信息或其他敏感查询参数。

### 9.7 经纬度规则

- `longitude`、`latitude` 必须为有限数值，经度范围 `[-180, 180]`，纬度范围 `[-90, 90]`。
- `coordinateSystem` 本期只允许 `GCJ02`；WGS-84、BD-09 或未知坐标不得直接上图。
- 坐标需经内容负责人确认位于光明区目标资源位置；存在合法行政边界数据时执行边界校验，否则保留人工核验记录。
- 零值、字符串、`NaN`、无穷值、经纬度颠倒、明显重复错误和不在目标区域的坐标均判定失败。
- 详情页建议展示 6 位小数并标注“GCJ-02”；显示精度不代表实地测量精度。
- POC 不进行用户位置计算，因此不申请定位权限，也不记录用户经纬度。

### 9.8 页面状态与一致性规则

- 初始加载完成前不展示可点击的半成品 marker。
- 分类切换、marker、摘要卡、详情和结果数必须源自同一筛选结果及数据版本。
- 进入详情后，地图页面状态至少在当前页面栈生命周期内保留。
- 返回地图时若 POI 已下线，清除选中态；仍有效时恢复选中 marker 和摘要卡。
- 网络或图片错误不得让用户误以为 POI 不存在；数据不存在与资源加载失败使用不同提示。
- 所有重试动作可重复执行，不产生重复 marker、重复分类或错乱选中状态。

## 10. POI 数据需求

### 10.1 数据包组成

| 数据包 | 最低内容 | 建议提供方 | 最晚时间 |
|---|---|---|---|
| 权威来源总表与排除台账 | 资源类型/地理范围、统计截止日期、出具方、版本、候选 POI、去重关系、排除原因、证据及双人复核 | 项目方/内容/产品负责人 | Day 0 |
| 冻结基准清单 | 由来源总表减去合规排除项生成的 POI 清单、版本及双人签字 | 内容/产品负责人 | Day 0 |
| POI 主数据 | 第 10.2 节全部必填字段 | 内容负责人 | Day 0 |
| 分类字典 | 编码、名称、图标、顺序和状态 | 产品/内容 | Day 0 |
| 标签字典 | 编码、名称、顺序和状态 | 产品/内容 | Day 0 |
| 图片素材 | 逐图 ID、文件/URL、用途、来源、授权状态和授权证据 | 内容/品牌 | Day 1 |
| 地图配置 | 默认中心、缩放、marker 样式、渲染阈值 | 产品/开发 | Day 1 |
| 数据版本 | `datasetVersion`、生成时间、审核人和变更说明 | 内容/开发 | 每次交付 |

### 10.2 POI 主数据模型

| 字段 | 类型 | 必填 | 校验与说明 | 来源 |
|---|---|---|---|---|
| `id` | string | 是 | 稳定唯一，建议 `poi_` 前缀；发布后不复用 | 产品细化 |
| `name` | string | 是 | 正式名称，去除首尾空格，不得为空 | 用户明确 |
| `aliases` | string[] | 否 | 审核别名，仅供 P1 搜索 | 产品细化 |
| `categoryCode` | string | 是 | 必须引用启用的分类字典 | 产品细化 |
| `tagCodes` | string[] | 是 | `1-5` 个唯一启用标签 | 用户明确/产品细化 |
| `longitude` | number | 是 | 合法 GCJ-02 经度 | 用户明确 |
| `latitude` | number | 是 | 合法 GCJ-02 纬度 | 用户明确 |
| `coordinateSystem` | enum | 是 | 本期固定 `GCJ02` | 技术细化 |
| `coverImageId` | string | 是 | 引用已清权的图片资产；不得只存不可追溯 URL | 用户明确/产品细化 |
| `imageIds` | string[] | 否 | 引用 `0-8` 张已清权详情图；为空时复用封面 | 用户明确/产品细化 |
| `summary` | string | 是 | 地图摘要短介绍，建议不超过 100 个中文字符 | 用户明确/产品细化 |
| `description` | string | 是 | 详情完整简介，不与其他 POI 拼接 | 用户明确/产品细化 |
| `address` | string | 是 | 审核后的地址文本 | 产品细化 |
| `openingHours` | object | 是 | 包含 `status`、`displayText` 和来源更新时间 | 用户明确/产品细化 |
| `recommendationIndex` | integer | 是 | `1-5`，官方人工配置 | 用户明确/假设 |
| `recommendationSource` | enum | 是 | 本期固定 `official_editorial` | 产品细化 |
| `recommendationConfiguredBy` | string | 是 | 推荐指数配置责任人 ID | 数据治理细化 |
| `recommendationUpdatedAt` | datetime | 是 | 推荐指数更新时间 | 产品细化 |
| `streetCode` | string/null | 否 | P1 街道筛选使用 | 待确认 |
| `dataSource` | string | 是 | 内容来源名称或内部来源编号 | 数据治理细化 |
| `sourceReference` | string/null | 否 | 可审计链接或资料编号，不一定前台展示 | 数据治理细化 |
| `contentRightsStatus` | enum | 是 | `cleared`、`restricted`、`unknown`；发布只允许 `cleared` | 数据治理细化 |
| `contentRightsEvidence` | string | 是 | 内容使用权或项目方授权证据编号 | 数据治理细化 |
| `reviewStatus` | enum | 是 | `pending`、`approved`、`rejected` | 数据治理细化 |
| `publishStatus` | enum | 是 | `draft`、`published`、`offline` | 数据治理细化 |
| `reviewedBy` | string | 条件必填 | 审核通过时必填，可用内部责任人 ID | 数据治理细化 |
| `reviewedAt` | datetime/null | 条件必填 | 审核通过时必填 | 数据治理细化 |
| `updatedAt` | datetime | 是 | 本条内容更新时间，详情页展示 | 产品细化 |

### 10.3 开放时间子模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `status` | enum | 是 | `known`、`unknown`、`by_appointment`、`temporarily_closed` |
| `displayText` | string/null | 条件必填 | 除 `unknown` 外必填，供前台直接展示 |
| `note` | string/null | 否 | 节假日、预约或临时说明 |
| `sourceUpdatedAt` | datetime/null | 条件必填 | `known`、`by_appointment`、`temporarily_closed` 时必填；`unknown` 可空 |

### 10.4 图片资产模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 全局唯一图片资产 ID |
| `url` | string | 是 | 包内路径或审核 HTTPS URL |
| `source` | string | 是 | 图片来源主体或内部来源编号 |
| `sourceReference` | string/null | 否 | 原始链接、文件或资料编号 |
| `copyrightStatus` | enum | 是 | `cleared`、`restricted`、`unknown`；POI 只允许引用状态为 `cleared` 的图片资产 |
| `licenseEvidence` | string | 是 | 授权文件、内部审批或可审计证据编号 |
| `reviewedBy` | string | 是 | 图片审核责任人 ID |
| `reviewedAt` | datetime | 是 | 图片审核时间 |
| `updatedAt` | datetime | 是 | 图片资产更新时间 |

### 10.5 分类字典模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | string | 是 | 稳定唯一编码 |
| `name` | string | 是 | 前台分类名称 |
| `markerIcon` | string | 是 | 默认 marker 图标资源 |
| `selectedMarkerIcon` | string | 是 | 选中态图标资源 |
| `sortOrder` | integer | 是 | 分类展示顺序 |
| `status` | enum | 是 | `enabled`、`disabled` |

“全部”是前台聚合选项，不写入 POI 的 `categoryCode`，也不作为真实分类记录。

### 10.6 标签字典模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | string | 是 | 稳定唯一编码 |
| `name` | string | 是 | 前台展示名称 |
| `sortOrder` | integer | 是 | 默认展示顺序 |
| `status` | enum | 是 | `enabled`、`disabled` |
| `synonyms` | string[] | 否 | 仅供导入清洗，不在前台重复展示 |

### 10.7 数据发布流程

```mermaid
flowchart LR
    A[收集原始 POI] --> B[基准清单去重与范围确认]
    B --> C[字段标准化与图片整理]
    C --> D[自动校验]
    D -- 失败 --> C
    D -- 通过 --> E[内容与版权审核]
    E -- 驳回 --> C
    E -- 通过 --> F[生成 datasetVersion]
    F --> G[iOS 预览与逐点核对]
    G -- 失败 --> C
    G -- 通过 --> H[发布与覆盖率验收]
```

数据职责：

- 内容负责人确认基准清单、名称、分类、简介、开放时间、推荐指数、标签和来源。
- 图片/品牌负责人确认图片使用权和可用素材。
- 开发负责数据结构、自动校验、坐标类型、字典引用、加载和版本一致性。
- 测试负责逐点核对 marker、摘要、详情、图片和筛选结果。
- 产品负责覆盖率口径、范围变更和最终验收结论。

### 10.8 数据校验错误码

| 错误码 | 条件 | 是否允许发布 |
|---|---|---|
| `DUPLICATE_ID` | `id` 重复 | 否 |
| `DATASET_STRUCTURE_INVALID` | 数据包元信息、根结构或必需字典无效 | 整包失败 |
| `REQUIRED_FIELD_MISSING` | 任一必填字段缺失 | 否 |
| `CATEGORY_INVALID` | 分类不存在或已禁用 | 否 |
| `TAG_INVALID` | 标签不存在、重复、禁用或数量不在 `1-5` | 否 |
| `COORDINATE_INVALID` | 经纬度非有限值、越界或明显错误 | 否 |
| `COORDINATE_SYSTEM_INVALID` | 坐标系不是 `GCJ02` | 否 |
| `OUTSIDE_TARGET_AREA` | 坐标经审核不属于目标光明区资源 | 否 |
| `IMAGE_INVALID` | 无封面、URL 不合法或审核不可用 | 否 |
| `COPYRIGHT_NOT_CLEARED` | 图片或内容使用权未确认 | 否 |
| `OPENING_HOURS_INVALID` | 状态与展示文本不符合规则 | 否 |
| `RECOMMENDATION_INVALID` | 推荐指数缺失或不为 `1-5` 整数 | 否 |
| `REVIEW_NOT_APPROVED` | 内容未审核通过 | 否 |
| `PUBLISH_STATUS_INVALID` | 状态不是 `published` | 不进入前台 |

## 11. 能力、接口与工程适配

### 11.1 数据源决策

🔶 **推荐默认项**：7 天 POC 使用“本地审核 JSON + 包内或远程审核图片”。该方案不需要新建后端，可减少请求协议、服务部署、合法域名和现场网络带来的交付风险。

以下条件全部成立时才切换为业务 API：

1. 已存在稳定后端和明确维护人。
2. 可在 Day 1 提供接口文档、测试环境和微信合法域名。
3. 返回模型可完整映射第 10 章字段，不要求前端猜测或补造数据。
4. 支持数据版本、错误码、超时和上下线状态。
5. API 接入不会挤占高德、数据审核和 iOS 回归时间。

### 11.2 前端数据仓储合同

无论数据来自本地还是 API，页面只依赖统一仓储能力：

| 能力 | 输入 | 输出 | 错误要求 |
|---|---|---|---|
| `getDatasetMeta` | 无 | `datasetVersion`、生成时间、审核信息 | 明确数据包不可用 |
| `getCategories` | 无 | 启用分类列表 | 字典错误不得继续筛选 |
| `getTags` | 无 | 启用标签字典 | 标签错误须阻止相关 POI 发布 |
| `getPublishedPois` | 分类/可选标签 | POI 摘要集合 | 返回已校验结果或明确失败 |
| `getPoiById` | `poiId` | 完整 POI 或 `not_found/offline` | 不返回其他 POI 兜底 |

若采用业务 API，建议统一响应：

```json
{
  "code": "OK",
  "message": "",
  "requestId": "req_masked",
  "data": {}
}
```

建议至少区分 `OK`、`INVALID_ARGUMENT`、`NOT_FOUND`、`DATA_INVALID`、`MAP_SERVICE_ERROR`、`RATE_LIMITED`、`NETWORK_ERROR` 和 `INTERNAL_ERROR`。HTTP 200 不自动等于业务成功。

### 11.3 高德地图能力

| 能力 ID | 能力 | 输入 | 输出 | 优先级 |
|---|---|---|---|---|
| CAP-MAP-01 | 地图显示 | 默认中心、缩放、合法 POI | 可拖动缩放的地图 | P0 |
| CAP-MAP-02 | marker 渲染 | marker ID、GCJ-02 坐标、图标 | 单点或聚合 marker | P0/条件 P0 |
| CAP-MAP-03 | marker 事件 | 平台 marker ID | 稳定映射后的 `poiId` | P0 |
| CAP-MAP-04 | 视野调整 | 当前 POI 坐标集合 | 包含结果的中心和缩放 | P0 |
| CAP-MAP-05 | 最小可用性检查 | 受控 Key、平台配置、测试请求 | 成功或脱敏错误码 | P0 |

技术准入规则：

- 地图供应商已经确定为高德，但微信原生 `map`、高德小程序 SDK 和高德 Web Service 不是同一种能力，不得混写。
- Day 1 必须确认已提供 Key 的产品类型、所属账号、允许 API、平台限制、配额、白名单及是否需要安全密钥/签名。
- 如果客户要求地图显示层必须由高德提供，技术 Spike 必须直接验证该官方方案，不能仅凭微信原生地图组件可用就宣称高德接入完成。
- 若凭证属于服务端 Web Service Key，小程序不得直接携带，应由受控服务代理调用。
- 若官方客户端能力必须携带客户端 Key，应使用专用、受限、可轮换的客户端凭证，并接受客户端值可被观察的事实。
- 已提供凭证只以脱敏尾号 `...554f` 识别；完整值不得写入本文、源代码、提交记录、截图或普通日志。

### 11.4 当前工程基线与缺口

| 维度 | 当前事实 | 本期影响 |
|---|---|---|
| 工程 | `map-gm-app` 版本 `1.1.1`，Node `>=18`、pnpm `>=8` | 可直接作为开发工作区 |
| 前端 | uni-app、Vue 3、TypeScript、Vite | 满足微信小程序页面与组件开发 |
| 状态/UI | Pinia、uview-plus、UnoCSS | 可管理地图页面状态和移动端 UI |
| 路由 | 使用 UniPages 从 SFC `<route>` 生成配置 | 不应手工维护生成的 `src/pages.json` |
| 微信构建 | 已有 `dev:mp-weixin` 和 `build:mp-weixin` | 可进行小程序构建 |
| 首页 | 仍请求 GitHub 示例接口 | 必须替换为地图入口 |
| 应用身份 | 名称仍为 `unisave`，生成配置含测试 AppID | 必须确认实际 AppID、名称和项目配置 |
| 业务代码 | 未发现地图、POI 或高德实现 | 地图与 POI 均按从零业务开发估算 |
| 请求层 | 仍按模板协议处理，错误辅助可能打印完整请求配置 | 若接 API，先统一协议并做日志脱敏 |
| 测试 | 只有通用工具测试 | 需新增 POI 校验与映射测试 |

### 11.5 建议前端结构

```text
src/
├── pages/map/                    # 全域地图首页
├── pages/poi/                    # POI 详情页
├── components/map/               # 分类、marker 适配、摘要卡
├── components/poi/               # 图片、开放时间、推荐指数、标签
├── data/                         # POC 本地审核数据与字典
├── domain/poi/                   # POI 类型、校验、筛选和映射纯逻辑
├── services/map/                 # 高德或平台地图适配
├── repositories/poi/             # 本地/API 数据仓储适配
└── stores/modules/map.ts         # 页面中心、缩放、分类和选中状态
```

该结构是技术建议，不强制具体文件名。两个业务页面可先放主包以降低 7 天内分包配置风险；如采用分包，应同步修改 UniPages 源配置，而不是直接修改生成文件。

### 11.6 工程改造要求

| ID | 改造项 | 验收要求 |
|---|---|---|
| ENG-001 | 替换模板应用身份 | 名称、标题、描述和启动页不再使用 `unisave` 示例 |
| ENG-002 | 删除 GitHub 示例首页请求 | 启动不访问无关示例接口 |
| ENG-003 | 建立地图与详情两个业务页面 | 路由通过既有 UniPages 机制生成 |
| ENG-004 | 完成高德接入 Spike | 记录 Key 类型、官方方案、最小调用、配额和错误码，全文脱敏 |
| ENG-005 | 建立地图适配层 | 页面不直接依赖难以替换的供应商原始事件结构 |
| ENG-006 | 建立 POI 仓储与校验 | 本地/API 使用同一合同，非法数据不上图 |
| ENG-007 | 建立稳定 marker 映射 | 平台 marker ID 与字符串 `poiId` 一一对应 |
| ENG-008 | 建立页面状态恢复 | 详情返回恢复地图中心、缩放、分类和选中状态 |
| ENG-009 | 日志脱敏 | 不打印完整 Key、完整请求配置或敏感查询参数 |
| ENG-010 | iOS 真机验证 | 地图层级、浮层、点击、滚动、图片和返回状态均实测 |
| ENG-011 | 清除范围外入口 | 无 AI、路线、定位、打卡、积分、徽章和个人中心占位入口 |

## 12. 非功能需求

### 12.1 性能

| ID | 要求 | 建议阈值 | 状态 |
|---|---|---|---|
| NFR-PERF-01 | 地图首屏可交互 | 20 次测试 P95 不超过 3 秒 | 产品细化 |
| NFR-PERF-02 | 本地分类切换 | 操作后 300ms 内完成可见结果更新 | 产品细化 |
| NFR-PERF-03 | marker 点击反馈 | 点击后 300ms 内出现选中反馈或 Loading | 产品细化 |
| NFR-PERF-04 | 详情文本首屏 | 本地数据下 1 秒内可查看名称和核心文本 | 产品细化 |
| NFR-PERF-05 | 图片加载 | 不阻塞核心文本；失败有占位图 | 已确认方向 |

性能计时须记录数据量、构建版本、设备、网络和是否冷启动。若数据量超过渲染阈值或指标失败，聚合/分级渲染成为交付前置项。

### 12.2 兼容性

- 仅验收微信小程序在实际 iOS 环境的表现。
- 暂不设最低微信基础库和具体 iPhone 型号；测试报告必须记录实际环境。
- 开发者工具、H5 或模拟器结果不能替代 iOS 微信真机的地图层级和交互结论。
- 地图浮层、长列表、图片轮播、返回恢复和安全区域均需真机检查。
- 若选用 API 本身存在最低基础库要求，研发应记录该事实，但不自动扩展成本期兼容承诺。

### 12.3 可用性与无障碍

- 分类和 marker 不只依赖颜色，应同时使用图标或文字。
- 核心可点击区域应满足移动端可操作性，避免 marker 摘要卡与地图手势相互抢占。
- 图片失败、数据为空、服务失败和 POI 下线使用不同文案和恢复动作。
- 长简介可滚动，文字不写在图片中作为唯一信息来源。
- 推荐指数必须有文本“官方推荐指数 X/5”，不能只靠星形图标。
- 坐标显示需同时标记坐标系，避免数字被误解为其他坐标口径。

### 12.4 可靠性与一致性

- 数据解析、筛选和 marker 映射逻辑应有自动化测试。
- 快速连续筛选或点击时，以最后一次用户意图为准，避免旧异步结果覆盖。
- 列表、摘要和详情必须使用同一数据版本；更新失败时不混用新旧字段。
- 页面重试不得产生重复 marker、重复分类或多个重叠摘要卡。
- 已下线或校验失败 POI 不得从缓存重新进入前台。

### 12.5 可维护性

- 分类、标签、地图中心、缩放、marker 阈值和占位图均配置化，不散落硬编码在页面。
- POI 类型、校验规则、数据仓储和地图适配与 UI 分离。
- 数据校验输出数据版本、记录 ID、错误码和字段，不输出完整凭证。
- 正式数据 API 接入时不改变页面消费的 POI 合同。

## 13. 评估、隐私与安全

### 13.1 POC 评估事件

本期没有正式分析平台时，可用测试记录表代替生产埋点。若已有合规埋点能力，建议记录：

| 事件 | 触发 | 建议字段 |
|---|---|---|
| `map_view_ready` | 地图和 POI 首次可交互 | `datasetVersion`、POI 数、耗时区间、构建版本 |
| `poi_category_select` | 选择主分类 | `categoryCode`、结果数 |
| `poi_marker_select` | 点击单点 marker | `poiId`、`categoryCode` |
| `poi_card_view` | 摘要卡成功显示 | `poiId` |
| `poi_detail_view` | 详情成功显示 | `poiId`、数据版本 |
| `poi_image_fallback` | 图片使用占位图 | `poiId`、图片序号、原因码 |
| `map_or_data_error` | 地图或数据失败 | 错误类型、脱敏错误码、构建版本 |

POC 的主验收依据是数据校验、iOS 测试和任务记录，不以埋点已上线作为前置条件。

### 13.2 数据最小化

- 地图浏览不请求微信登录、手机号、头像昵称或当前位置。
- 本期不需要生成匿名用户 ID，也不保存个人中心或用户资产。
- 若记录评估事件，只记录 POI、分类、数据版本、耗时区间和技术错误，不记录用户精确位置。
- 不收集与地图/POI POC 无关的设备指纹、通讯录、相册或后台位置。

### 13.3 凭证与日志安全

- 完整高德 Key 不得进入 PRD、Markdown、截图、测试报告、版本库、普通日志或前端业务常量。
- 所有 `VITE_*` 客户端构建变量均可能被观察，不得放置服务端高权限 Key、安全密钥或签名材料。
- 错误日志不得打印完整请求配置；只记录脱敏 Key 标识、错误码、请求 ID 和必要上下文。
- `urlCheck=false` 只可用于本地开发，不能视为体验版或交付版已配置合法域名。
- 若远程图片或 API 使用查询签名，日志和错误 UI 必须移除敏感参数。
- 发现完整凭证进入仓库或截图时按 S0 处理，停止使用并由凭证负责人轮换。

## 14. 验收方案

### 14.1 核心浏览脚本

| 步骤 | 操作 | 预期结果 | 对应需求 |
|---|---|---|---|
| 1 | 冷启动微信小程序 | 进入光明区全域地图，不登录、不请求定位 | MAP-001/003/005 |
| 2 | 等待地图加载完成 | 显示全部有效 marker 和正确结果数 | MAP-002/006、MARKER-001 |
| 3 | 选择一个有数据的主分类 | marker、数量和视野更新为同一结果集 | FILTER-001 至 006 |
| 4 | 点击一个单点 marker | 正确 marker 选中并显示同一 POI 摘要卡 | MARKER-004/005、CARD-001 |
| 5 | 从摘要卡进入详情 | 路由 `poiId` 正确，所有用户必看字段可见 | CARD-006、DETAIL-001 至 008 |
| 6 | 核对经纬度和推荐指数 | 显示 GCJ-02 坐标和“官方推荐指数 X/5” | DETAIL-003/006 |
| 7 | 返回地图 | 恢复原分类、视野、marker 和摘要卡 | MAP-007、DETAIL-012 |
| 8 | 清除分类 | 恢复全部有效 POI 和正确结果数 | FILTER-002/003 |

同一实际环境连续执行 10 次。任何一次崩溃、错点、字段串点、无法返回或流程死路均记为失败；修复后重新开始连续计数。

### 14.2 数据专项用例

| 用例 ID | 输入/操作 | 预期结果 |
|---|---|---|
| QA-DATA-01 | 从来源总表、排除台账、冻结基准清单到已发布数据逐一核对 | 满足 `B=S-E`；排除项双人复核；每个基准 POI 可从单点或聚合展开到达正确摘要和详情，覆盖率为 100% |
| QA-DATA-02 | 基准清单未提供 | 报告只写“审核样本有效上图率”，不宣称全域覆盖 |
| QA-DATA-03 | 重复 `id` | 数据校验失败，指出全部冲突记录，不发布 |
| QA-DATA-04 | 名称、封面、简介等必填字段缺失 | 记录不发布并返回 `REQUIRED_FIELD_MISSING` |
| QA-DATA-05 | 推荐指数为 `0`、`4.5`、`6` 或字符串 | 记录不发布并返回 `RECOMMENDATION_INVALID` |
| QA-DATA-06 | 标签为空、重复、超过 5 个或引用禁用标签 | 记录不发布并返回 `TAG_INVALID` |
| QA-DATA-07 | `openingHours.status=unknown` | 可发布，前台显示“开放时间待确认” |
| QA-DATA-08 | `known` 但 `displayText` 为空 | 记录不发布并返回 `OPENING_HOURS_INVALID` |
| QA-DATA-09 | 坐标系为 WGS-84、BD-09 或 unknown | 记录不生成 marker |
| QA-DATA-10 | 经纬度颠倒、非数字、越界或不在目标区域 | 记录不发布并返回对应坐标错误 |
| QA-DATA-11 | 任一被 POI 引用图片的版权状态为 `unknown` 或缺少授权证据 | 记录不发布并指出图片资产 ID |
| QA-DATA-12 | POI 从 `published` 改为 `offline` | 新版本地图无 marker，旧详情显示已下线 |
| QA-DATA-13 | 数据包根结构无效、数据版本缺失或分类字典重复 | 整包失败，不显示任何 marker |
| QA-DATA-14 | 一个非基准样本 POI 缺少简介，但整包结构和字典有效 | 仅隔离该 POI，其他合法样本可展示，并记录错误 |
| QA-DATA-15 | 冻结后以“图片缺失”申请从基准清单删除 POI | 变更被拒绝；该 POI 保留在分母并计为缺口 |
| QA-DATA-16 | `known` 开放时间没有来源更新时间 | 记录不发布并返回 `OPENING_HOURS_INVALID` |
| QA-DATA-17 | 推荐指数没有配置责任人 | 记录不发布并返回 `RECOMMENDATION_INVALID` |

### 14.3 地图与交互专项用例

| 用例 ID | 操作 | 预期结果 |
|---|---|---|
| QA-MAP-01 | 拖动、缩放和快速连续手势 | 地图稳定，无误进详情和页面卡死 |
| QA-MAP-02 | 快速切换 A/B/A 分类 | 最终只显示最后一次 A 的正确结果 |
| QA-MAP-03 | 选中 POI-A 后切换到不含 A 的分类 | A 取消选中，摘要卡关闭 |
| QA-MAP-04 | 连续点击 POI-A、POI-B | 最终选中 B，摘要和详情均为 B |
| QA-MAP-05 | 点击地图空白区域 | 摘要卡关闭，marker 清除选中状态 |
| QA-MAP-06 | 打开详情再返回 | 恢复中心、缩放、分类和选中 POI |
| QA-MAP-07 | 当前分类无结果 | 显示空状态，可一键查看全部，无残留 marker |
| QA-MAP-08 | 地图初始化失败后重试 | 停止 Loading，显示原因；恢复后只渲染一套 marker |
| QA-MAP-09 | 数据读取失败后重试 | 不显示半成品；恢复后结果和数量正确 |
| QA-MAP-10 | 注入单次远程图片运行故障 | 使用占位图，核心文本和返回流程正常；该用例只验证降级，不计图片验收通过 |
| QA-MAP-11 | POI 数量达到本期最大数据量 | 地图 P95 不超过 3 秒，逐点选点共 N 次且正确摘要 N 次；否则聚合/分级渲染及逐点展开升为 P0 后重新全量验收 |
| QA-MAP-12 | iOS 真机检查地图浮层和详情滚动 | 无原生层级遮挡、点击穿透或滚动冲突 |
| QA-MAP-13 | 在交付构建逐一打开全部验收范围 POI | 每个 POI 的真实封面均可见，占位图计失败，真实封面验收可见率 100% |
| QA-MAP-14 | 启用聚合后逐个选择全部成员 POI | 每个成员均可由聚合交互到达，摘要和详情 `poiId` 正确 |

### 14.4 必看字段验收矩阵

| 用户明确字段 | 摘要卡 | 详情页 | 数据校验 |
|---|---|---|---|
| 名称 | 是 | 是 | 非空、正式名称 |
| 图片 | 封面 | 封面/图集 | 至少一张、版权和 URL 合法 |
| 经度、纬度 | 否 | 是，标注 GCJ-02 | 有限数值、坐标系和目标区域合法 |
| 简介 | `summary` | `description` | 两字段均非空 |
| 开放时间 | 可选简写 | 是 | 合法状态；未知有固定兜底文案 |
| 推荐指数 | 是 | 是 | `1-5` 整数，官方来源 |
| 特色标签 | 是 | 是 | 受控标签 `1-5` 个 |
| 主分类 | 是 | 是 | 引用启用分类字典 |
| 地址 | 否 | 是 | 非空、经内容审核 |
| 数据更新时间 | 否 | 是 | 合法时间且与当前数据版本一致 |

### 14.5 缺陷等级

| 等级 | 定义 | 示例 | 交付要求 |
|---|---|---|---|
| S0 | 安全、凭证或结论真实性问题 | 完整 Key 泄露；非法点位被计入全域覆盖 | 立即阻断并修复/轮换 |
| S1 | 核心流程阻断或严重数据错误 | 地图打不开、marker 串点、必看字段错误、返回死路 | 交付前为 0 |
| S2 | 有替代路径但明显影响使用 | 图片占位异常、部分样式遮挡、非核心文案错误 | 评估修复或记录 |
| S3 | 轻微视觉或优化问题 | 非关键间距、细微动画问题 | 可进入已知问题 |

### 14.6 完成定义

- 本专项 PRD、P0/P1/范围外和待确认项已经产品评审。
- 基准清单已确认；若未确认，交付结论明确降级为“样本通过”。
- 所有已发布 POI 通过字段、坐标、字典、图片、审核和状态校验。
- marker、摘要、详情和覆盖清单可通过 `poiId` 一一追溯。
- 用户明确的七类信息在详情页全部可见，并按第 14.4 节通过验收。
- 主分类、地址和数据更新时间按第 14.4 节通过验收。
- 交付构建中全部验收范围 POI 的真实封面可见率为 100%；占位图只通过故障降级用例，不替代内容验收。
- 高德 Key 类型、接入方式、配额和限制已完成脱敏记录。
- 核心脚本连续 10 次通过，地图性能达到确认阈值。
- 实际 iOS 测试环境、数据版本、结果和已知限制已归档。
- S0/S1 为 0；范围外能力没有入口、占位页或隐性接口。

## 15. 交付物与 7 天计划

### 15.1 交付清单

| 交付物 | 必须内容 | 优先级 |
|---|---|---|
| 产品文档 | 本 PRD、范围差异、决策记录和未决项 | P0 |
| UI 交付 | 地图页、摘要卡、详情页、加载/空/失败/下线/图片占位状态 | P0 |
| 前端源码 | 当前 `map-gm-app` 中可构建的地图和 POI 实现 | P0 |
| POI 数据包 | 基准清单、主数据、分类、标签、图片和 `datasetVersion` | P0 |
| 数据校验结果 | 每条错误记录、错误码和覆盖率计算 | P0 |
| 高德接入记录 | Key 类型、官方方案、限制、配额和最小调用结果，只保留脱敏标识 | P0 |
| iOS 测试报告 | 实际环境、核心脚本、数据用例、地图用例、性能和缺陷 | P0 |
| 构建说明 | Node/pnpm、微信 AppID 配置、命令、域名和凭证注入方法，不含完整 Key | P0 |
| 已知限制 | 未覆盖环境、暂缓能力、样本/全域结论和后续风险 | P0 |

### 15.2 Day 0/Day 1 准入条件

- 内容负责人提供基准清单、POI 总量和至少一版完整字段数据。
- 内容与产品负责人共同确认来源总表、排除台账、冻结基准清单，以及 POI/图片总量。
- 产品确认主分类、标签库和推荐指数负责人；未确认项采用本文假设需得到显式批准。
- 图片来源、使用权、包内/远程方案和合法域名有结论。
- 高德凭证通过安全渠道提供给技术负责人，不进入文档或仓库。
- 微信实际 AppID、开发权限和 iOS 真机可用于测试。
- Logo、主题色、marker 图标和统一占位图至少有可用版本。

若基准清单、合法坐标或图片版权在 Day 1 仍不可用，POC 可继续验证技术样本，但不能按“光明区全域覆盖”验收。

🔶 **7 天容量假设**：以 `1` 名前端开发、`1` 名内容负责人和 `1` 名测试/产品协作人员为例，当前排期最多承诺 `50` 个 POI、每个 POI `1` 张封面和最多 `3` 张详情图的完整导入与逐点验收，即最多 `200` 张图片资产。该值不是产品容量上限，而是未完成实际工时测算前的 POC 准入上限。Day 0 必须用实际人数、POI 数、图片数和抽测 5 个 POI 的平均整理/核对耗时重新测算：`预计内容与验收工时 = POI数 * 单POI平均工时 + 图片数 * 单图平均工时`。超过可用人时必须增加内容/测试人力、缩小并明确改称审核样本，或调整交付日期；不得在范围不变时仍承诺 7 天全量交付。

### 15.3 7 天执行计划

| 日期 | 工作重点 | 当日出口条件 |
|---|---|---|
| Day 1 | 冻结专项 P0；清理模板；确认基准清单和数据合同；验证高德 Key 类型、官方接入方案和 iOS 最小地图 | 高德 Spike 有结论，数据校验可运行，阻塞项有负责人 |
| Day 2 | 实现地图首页、默认视野、marker 适配和 iOS 真机层级验证 | 审核样本可稳定上图、拖动缩放和点击 |
| Day 3 | 实现分类、结果数、快速切换、marker 选中和摘要卡 | 分类结果一致，marker 与摘要无串点 |
| Day 4 | 实现详情页、七类必看字段、图片/开放时间/下线异常和返回恢复 | 地图到详情主流程端到端完成 |
| Day 5 | 导入完整本期数据；逐点核对；处理聚合触发、性能、远程图片和数据错误 | 基准清单差异为 0 或形成明确缺口清单 |
| Day 6 | iOS 核心脚本、数据专项、性能和 5 人找点任务；修复 S0/S1 | 验收证据齐全，S0/S1 清零计划完成 |
| Day 7 | 全量回归、构建、凭证扫描、文档、已知限制和交付演示 | 完成定义满足，结果按“通过/样本通过/有条件通过/不通过”归档 |

### 15.4 人员职责

| 角色 | 主要职责 |
|---|---|
| 产品负责人 | 维护范围、推荐指数口径、覆盖公式、评审和验收结论 |
| 内容负责人 | 基准清单、POI 事实、分类、标签、开放时间、推荐指数和审核 |
| 图片/品牌负责人 | 图片使用权、视觉素材、marker 与占位图 |
| 前端开发 | uni-app 页面、高德适配、数据仓储、校验、状态和真机调试 |
| 技术负责人 | 高德 Key、安全配置、微信 AppID、合法域名和技术准入 |
| 测试负责人 | 逐点数据验收、iOS 用例、性能、缺陷和环境记录 |

没有独立测试人员时，内容、产品和开发至少进行交叉验收；同一实现者不能单独确认基准清单、全部坐标和全部映射均正确。

## 16. 依赖与风险

### 16.1 外部依赖

| 依赖 | 必需内容 | 未就绪影响 | 建议负责人 |
|---|---|---|---|
| POI 基准清单 | 范围、唯一记录、总量和版本签字 | 无法验收“全域覆盖” | 内容负责人 |
| POI 内容 | 七类必看字段、分类、地址、来源和更新时间 | 详情不完整，记录不能发布 | 内容负责人 |
| 坐标 | GCJ-02 声明和目标区域核验 | marker 错位或无法发布 | 内容/技术负责人 |
| 图片 | 使用权、可用文件/URL、合法域名 | POI 不能满足图片字段 | 图片/品牌负责人 |
| 推荐指数 | `1-5` 值、配置人、口径和更新时间 | 指数字段不可信或无法发布 | 产品/内容负责人 |
| 高德能力 | 正确 Key 类型、账号、允许 API、限制、配额和官方方案 | 地图 P0 无法完成 | 技术负责人 |
| 微信小程序 | 实际 AppID、开发权限、合法域名和体验版 | 无法完成真实小程序构建与验证 | 项目方技术接口人 |
| iOS 实测 | 可用 iPhone、微信和测试时间 | 地图层级和兼容结论无效 | 测试负责人 |

### 16.2 风险与应对

| ID | 风险 | 概率 | 影响 | 应对措施 | 触发条件 |
|---|---|---|---|---|---|
| R-01 | 没有基准清单却要求宣称全域覆盖 | 高 | 高 | 只输出“样本通过”；清单签字后重算 | Day 1 仍无清单 |
| R-02 | POI 数量或字段在开发中持续变化 | 高 | 高 | Day 1 冻结版本；变更生成新 `datasetVersion` 和差异表 | 无版本直接替换数据 |
| R-03 | 高德 Key 类型与目标能力不匹配 | 中 | 高 | Day 1 官方最小调用；必要时申请专用受限 Key | 平台/签名/权限错误 |
| R-04 | 完整凭证进入客户端、文档或日志 | 中 | 高 | 配置隔离、脱敏扫描；发现后按 S0 并轮换 | 扫描命中完整凭证 |
| R-05 | 坐标系混用导致系统性错位 | 中 | 高 | 统一 GCJ-02；导入校验和逐点地图核对 | marker 与实际位置不符 |
| R-06 | 图片无版权或域名不可用 | 高 | 高 | Day 1 确认来源；包内核心图或审核 CDN；统一占位 | 真机加载失败或来源不明 |
| R-07 | 推荐指数被误解为用户口碑 | 高 | 中 | 固定“官方推荐指数”文案，不显示评价数和热度榜 | UI 使用评分/热门文案 |
| R-08 | marker 过密或数量过多导致不可点/卡顿 | 未知 | 高 | 获取总量后压测；超过阈值或指标失败启用聚合/分级 | P95 或点击准确率不达标 |
| R-09 | iOS 原生地图层级遮挡浮层 | 中 | 高 | Day 2 真机 Spike，采用验证通过的浮层方式 | 摘要卡遮挡或点击穿透 |
| R-10 | 返回详情后地图状态丢失 | 中 | 中 | 明确 store/page-stack 状态，加入连续回归 | 返回后回到默认首页 |
| R-11 | 7 天内重新加入打卡、AI 或后台 | 高 | 高 | 以本专项范围为基线；新增 P0 必须替换范围或调整工期 | 出现范围外入口/接口要求 |
| R-12 | 单一 iOS 验证被对外表述为全面兼容 | 中 | 中 | 报告逐项记录实际环境和结论边界 | 出现“支持所有设备”表述 |

### 16.3 四类产品风险

| 风险类型 | 当前最弱证据 | POC 内验证方式 |
|---|---|---|
| 价值 | 没有游客研究证明地图比其他入口更有价值 | 5 人找点任务和简短访谈，只形成初步信号 |
| 可用性 | marker 密度、分类理解和地图浮层未实测 | iOS 任务测试、快速点击和返回恢复用例 |
| 可行性 | 高德 Key 类型、官方接入层次和目标数据量未知 | Day 1/2 Spike，Day 5 最大数据量压测 |
| 业务可行性 | 基准清单、版权、内容更新和推荐指数责任未确定 | 明确责任人、版本和发布流程；未就绪则降级结论 |

## 17. 决策与待确认事项

### 17.1 已确认决策

| ID | 决策 | 状态 | 对本专项影响 |
|---|---|---|---|
| D-01 | 7 天交付是 POC，不是正式版本 | 已确认 | 以最小可运行和可验收为目标 |
| D-02 | 使用当前 `map-gm-app` uni-app 工程 | 已确认 | 采用现有 Vue 3、TypeScript、Pinia 等基线 |
| D-03 | 目标端为微信小程序，暂只在 iOS 验证 | 已确认 | 不验收其他端，记录实际环境 |
| D-04 | 最低基础库和具体 iPhone 型号暂缓 | 已确认暂缓 | 不作为开工阻塞，不形成全面兼容承诺 |
| D-05 | 地图供应商为高德，凭证已提供 | 已确认 | Key 类型和接入方式仍需技术验证 |
| D-06 | AI 与路径规划本期不处理 | 已确认 | 不进入页面、接口、数据、指标、排期和验收 |
| D-07 | 上级任务聚焦全域地图探索和 POI 数字化展示 | 已确认 | 打卡、奖励和个人中心移出本专项 P0 |
| D-08 | POI 至少包含名称、图片、经纬度、简介、开放时间、推荐指数和特色标签 | 已确认 | 全部进入 P0 数据和详情验收 |
| D-09 | 用户无需正式登录，个人中心仅本机等原决策 | 已确认但本专项不触发 | 本专项不建设任何用户资产页面 |
| D-10 | 原 Q-12 暂不考虑 | 已确认暂缓 | 不阻塞当前产品和研发基线 |

### 17.2 开发前必须关闭的事项

| ID | 问题 | 推荐默认项 | 负责人 | 截止 | 阻塞影响 |
|---|---|---|---|---|---|
| OQ-01 | 光明区来源总表、排除台账、冻结基准清单、POI/图片总量和版本是什么？ | Day 0 内容与产品双人签字；没有则按样本 POC | 内容/产品负责人 | Day 0 | 阻塞“全域覆盖”和 7 天容量承诺 |
| OQ-02 | POI 主分类和特色标签字典是什么？ | 一个主分类、1-5 个受控标签 | 产品/内容 | Day 0 | 阻塞分类与数据发布 |
| OQ-03 | 推荐指数由谁配置、按什么口径更新？ | 官方人工配置 `1-5`，本期不排序 | 产品/内容 | Day 0 | 阻塞必填字段发布 |
| OQ-04 | 图片来源、版权、尺寸和合法域名是什么？ | 核心图随包或审核 HTTPS CDN | 图片/技术 | Day 1 | 阻塞图片字段和体验版 |
| OQ-05 | POI 数据使用本地 JSON 还是业务 API？ | 本地审核 JSON | 技术负责人 | Day 0 | 影响工程和域名 |
| OQ-06 | 已提供高德 Key 的类型、账号、API、限制和配额是什么？ | 官方最小调用验证，不猜 Key 类型 | 技术负责人 | Day 1 | 阻塞地图 P0 |
| OQ-07 | 高德在小程序中承担底图显示还是 LBS 服务？ | 按用户要求验证目标官方方案 | 技术负责人 | Day 1 | 影响地图架构 |
| OQ-08 | 实际微信 AppID 和开发/体验权限是否可用？ | 使用项目方确认配置 | 项目方接口人 | Day 1 | 阻塞真机构建 |
| OQ-09 | 本期完整 POI 数量是否触发聚合？ | 阈值先取 100，以 iOS 指标为准 | 开发/测试 | Day 2 | 影响 marker 方案 |
| OQ-16 | 实际人员和单 POI/单图核对工时是否支持 7 天全量？ | 先按不超过 50 个 POI、200 张图测算，超出则增人/缩样本/改期 | 产品负责人 | Day 0 | 阻塞 7 天范围承诺 |

### 17.3 可在 P0 开发后确认的事项

| ID | 问题 | 当前处理 | 优先级 |
|---|---|---|---|
| OQ-10 | 是否展示光明区行政边界？ | 有合法边界和真机余量再做 | P1 |
| OQ-11 | 是否需要街道维度？ | 字段预留，不展示筛选 | P1 |
| OQ-12 | 是否需要名称搜索？ | POI 规模体现价值后再做 | P1 |
| OQ-13 | 是否按推荐指数排序或展示榜单？ | 本期只显示指数 | P1 |
| OQ-14 | 是否允许复制坐标？ | 本期只展示 | P1 |
| OQ-15 | 最终最低基础库和设备矩阵是什么？ | 记录本期实际环境，正式版再定 | 暂缓 |

### 17.4 默认产品决策

以下规则在评审未提出异议时作为 POC 默认项：

- “全域”按基准清单覆盖率验收，没有清单则改称“审核样本”。
- POI 一个主分类、`1-5` 个特色标签，分类和标签均由受控字典维护。
- 推荐指数为官方人工配置的 `1-5` 整数，只展示，不做用户评分和默认排序。
- 开放时间未知显示“开放时间待确认”。
- POI 坐标统一 GCJ-02；未知或非法坐标不上图。
- POC 使用本地审核 JSON，图片使用包内资源或审核 HTTPS 域名。
- 地图初次展示全部有效 POI；分类切换自动调整视野包含结果。
- marker 数量超过 100 或性能/点击指标失败时启用聚合或视野分级渲染。

## 18. 后续需求池

### 18.1 地图与 POI 正式版本

- 完整 CMS、批量导入、字段编辑、审核、版本、定时上下线和审计。
- POI 名称搜索、别名、标签组合筛选、街道筛选、收藏和分享。
- 行政边界、分级聚合、海量点位、附近资源、排序和正式运营榜单。
- 推荐指数评分标准、复核、更新频率、解释文本和申诉机制。
- 正式数据监控、过期提醒、内容纠错、版权管理和供应商配额告警。
- Android、更多 iPhone、最低基础库和弱网兼容矩阵。

### 18.2 到点互动与用户资产

- 真实定位、位置权限、距离判定、打卡和生产级反作弊。
- 积分、徽章、任务、挑战、个人中心和跨设备服务端资产。
- 产品内虚拟定位测试能力仅在确有需要时独立评估，并与正式构建完全隔离。

此前“打卡必须使用真实定位、匿名使用、个人中心只保存本机”的决策仍可作为到点互动 POC 的输入，但不会自动恢复为本专项范围。

### 18.3 AI 与路径规划

- AI 文旅问答、知识库、引用溯源、内容安全和多轮上下文。
- AI 路线生成、站点组合、约束校验和结果解释。
- 高德路径规划、polyline、距离/时长、道路级导航和动态调整。

AI 与路径规划后续须使用独立 PRD、接口、指标、数据责任和验收，不从附件原始范围直接恢复。

### 18.4 运营、交易与后台

- 游记、评论、UGC 审核、活动、优惠券和排行榜。
- 商户、商品、库存、订单、支付、退款、核销、分账和对账。
- 商户后台、运营后台、监管端和数据大屏。

## 19. 需求追溯

### 19.1 上级任务到需求

| 上级任务 | PRD 落点 | 核心验收 |
|---|---|---|
| 光明区整体文旅资源分布 | OBJ-01、MAP、MARKER、第 9.1 节 | QA-DATA-01/02、核心脚本 1-2 |
| 地图化探索 | FILTER、MARKER、CARD | QA-MAP-01 至 07 |
| POI 点位数字化展示 | DETAIL、DATA、第 10 章 | 第 14.4 节字段矩阵 |
| 名称 | DETAIL-001、`name` | 非空且与 `poiId` 对应 |
| 图片 | DETAIL-002、`coverImageId/imageIds` | 至少一张真实封面，逐图清权；运行故障有占位图但不计内容验收通过 |
| 经纬度 | DETAIL-003、坐标规则 | 合法 GCJ-02 并在详情展示 |
| 简介 | DETAIL-004、`summary/description` | 摘要与详情均非空 |
| 开放时间 | DETAIL-005、第 9.5 节 | 已知正确；未知显示待确认 |
| 推荐指数 | DETAIL-006、第 9.4 节 | 官方 `1-5` 整数，不冒充评分 |
| 特色标签 | DETAIL-007、第 9.3 节 | 受控标签 `1-5` 个 |

### 19.2 附件到本专项范围

| 需求主题 | S1 | S2 | S3 | V1.0 处理 |
|---|---|---|---|---|
| 全域地图 | POC 核心 | 地图缩放和点位展示 | 一期数据入口 | P0，按基准清单验收 |
| POI 详情 | 概要点位 | 分类、榜单、点位详情 | 长期内容运营 | 七类信息 P0，补充治理字段 |
| 分类筛选 | 概要 | 详细功能表达 | 长期运营能力 | 主分类 P0，标签/街道筛选 P1 |
| 渐进展示 | 未细化 | 有相关表达 | 海量资源方向 | 按数量和性能条件触发聚合 |
| AI/路线 | 原 POC 内容 | 详细功能 | 三期方向 | 本专项明确排除 |
| 打卡/奖励 | 原 POC 内容 | 互动功能 | 会员运营方向 | 移入后续需求池 |
| 交易/后台 | 非核心 | 扩展功能 | 完整长期方案 | 本专项排除 |

### 19.3 目标覆盖矩阵

| 目标 | 主要需求 | 核心验收 |
|---|---|---|
| OBJ-01 整体分布 | MAP、FILTER、MARKER | 核心脚本 1-4、QA-MAP-01 至 07 |
| OBJ-02 地图到详情 | CARD、DETAIL、状态恢复 | 核心脚本 4-8、QA-MAP-04/06 |
| OBJ-03 POI 数字档案 | 第 9/10 章、DATA | QA-DATA-03 至 12、字段矩阵 |
| OBJ-04 全域口径 | 第 4.3、9.1、14.2 节 | 基准清单覆盖率或样本降级结论 |
| OBJ-05 技术可行性 | CAP-MAP、ENG、NFR | 高德 Spike、性能、iOS 真机 |
| OBJ-06 风险清单 | 第 15-17、20 章 | 交付物、风险与待确认项 |

## 20. PRD 自检

### 20.1 最强部分

本专项范围和 POI 数据合同较清晰。用户明确的七类 POI 信息已贯穿页面、数据字段、发布规则和验收矩阵；“全域覆盖”有明确分母、分子和降级口径；AI、路径规划、定位、打卡、奖励和个人中心已从 P0、页面、数据、接口、指标、排期和验收同步移除。

### 20.2 最弱部分

内容输入和高德技术结论仍最弱。当前没有签字基准清单、分类/标签字典、推荐指数责任、图片版权清单或完整数据量；高德 Key 的类型与微信小程序目标接入层次尚未验证。上述问题不影响形成评审稿，但会阻塞“全域通过”或地图技术验收。

### 20.3 高风险假设

| 假设 | 错误时影响 | 验证方式 |
|---|---|---|
| 官方推荐指数可由负责人按 `1-5` 人工配置 | 必填字段无法可信发布 | Day 0 产品/内容评审确认 |
| 一个主分类和 `1-5` 标签可表达本期 POI | 分类探索和数据导入需重构 | 用完整基准清单试分类 |
| 本地 JSON 满足 7 天内数据更新需要 | 临时变更需重新构建发版 | Day 0 确认更新频率和后端现状 |
| 已提供高德凭证支持目标小程序方案 | 地图 P0 无法按期实现 | Day 1 官方最小调用 |
| 初始 marker 阈值 100 适合目标 iOS 环境 | 可能卡顿、遮挡或过早增加聚合成本 | 用完整数据量真机压测 |
| 5 人找点任务可发现主要可用性问题 | 仍可能遗漏真实游客行为 | 正式版前开展用户研究和更大样本测试 |

### 20.4 自检结果

| 检查项 | 结果 |
|---|---|
| 问题、用户、目标、方案和指标是否一致 | 是，均聚焦地图探索和 POI 数字化展示 |
| 用户明确的七类 POI 信息是否都有页面、字段和验收 | 是 |
| “全域”是否可量化且避免无清单宣传 | 是 |
| P0 是否残留 AI、路径规划、定位或打卡 | 否 |
| 页面、数据、接口和排期是否残留积分、徽章或个人中心 | 否 |
| 推荐指数是否被误写为用户评分或算法热度 | 否 |
| 坐标系未知或坐标非法的 POI 是否允许上图 | 否 |
| 开放时间未知是否伪造默认时段 | 否 |
| 高德完整 Key 是否写入文档 | 否，仅保留脱敏尾号 |
| iOS 验证是否被误写为全面兼容 | 否 |
| 未决项是否有默认项、负责人、时限和阻塞影响 | 是 |

### 20.5 评审前首要动作

内容负责人应先提交并签字确认光明区 POI 基准清单、完整字段数据、分类/标签字典和图片使用权；技术负责人同时在 Day 1 完成高德 Key 类型与目标微信小程序接入方案的最小验证。前者决定能否宣称“全域覆盖”，后者决定地图 P0 能否按期交付。

本 PRD 经产品范围评审、内容数据准入和高德技术准入后，可作为 7 天地图/POI 专项 POC 的研发与验收基线；在此之前状态保持“待评审”，不构成正式上线或全域数据完备承诺。
