# 光明区文旅全域地图及AI导览POC产品需求文档 V1.1

| 文档版本 | 创建日期 | 文档状态 | 版本简述 |
|---|---|---|---|
| V1.0 | 2026-07-29 | 已归档 | 基于三份附件形成“地图 + AI 路线 + 模拟打卡”评审稿 |
| V1.1 | 2026-07-29 | 当前评审稿 | 按最新决策收敛为微信小程序 iOS 端“地图 + POI + 真实定位打卡 + 本机奖励”7 天 POC |

| 项目项 | 当前基线 |
|---|---|
| 产品名称 | 光明区文旅全域地图及 AI 导览 POC；本期不实现 AI 导览 |
| 交付性质 | 7 天 POC，不是正式上线版本 |
| 目标端 | 微信小程序 |
| 验证范围 | 仅 iOS；最低基础库、具体 iPhone 型号暂缓规定 |
| 前端工程 | `map-gm-app` |
| 开发框架 | uni-app + Vue 3 + TypeScript + Pinia |
| 地图供应商 | 高德地图 API |
| 地图凭证 | 已提供；本文仅记录脱敏尾号 `...554f` |
| 身份与数据 | 匿名使用；个人中心数据只保存在本机 |
| 本期核心 | 地图浏览、POI 详情、真实定位校验、打卡、积分、徽章、本机回看 |
| 本期排除 | AI、路径规划、产品内虚拟定位、正式账号及跨设备同步 |

## 目录

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

## 1. 执行摘要

本项目基于当前 `map-gm-app` uni-app 工程，在 7 天内制作一个微信小程序 POC。体验游客无需登录即可在地图浏览光明区样本 POI、按类别筛选并查看详情；到达支持打卡的 POI 后，小程序实时请求微信位置能力，以统一坐标系计算用户与 POI 的距离。只有定位样本有效且通过配置半径校验，系统才记录打卡、发放一次积分和徽章，并允许用户在个人中心从本机回看结果。

本期验证“地图发现 → 到点互动 → 本机奖励”是否可在 iOS 微信小程序稳定运行，不验证正式上线所需的账号、服务端资产、防作弊、多端兼容、运营后台和长期数据治理。AI 与路径规划已明确移出本期；即使存在其他人员完成的相关能力，也不纳入本 PRD 的页面、接口、指标、排期或验收。

高德地图 API 已确定且凭证已提供，但“凭证已提供”不等于技术接入已完成。微信小程序原生地图显示、高德小程序 SDK 与高德 Web Service 属于不同能力层；Key 类型、允许调用的 API、额度、白名单和客户端暴露方式须在 Day 1 用最小调用验证。完整凭证禁止写入本 PRD、公开仓库、日志或前端硬编码。

## 2. 文档说明

### 2.1 信息状态

| 状态 | 定义 | 使用要求 |
|---|---|---|
| 已确认 | 用户明确决定，或可从当前工程直接核实 | 作为 V1.1 基线 |
| 资料事实 | 三份附件中的原始表达 | 可用于背景，不自动形成交付承诺 |
| 产品细化 | 为形成可开发、可测试规则而补充 | 评审后执行；高风险项单独列出 |
| 假设 | 在证据不足时采用的临时判断 | 若不成立需调整范围或指标 |
| 待技术确认 | 产品方向已定，具体实现仍需验证 | 在对应开发开始前关闭 |
| 暂缓 | 本期不处理且不作为阻塞项 | 后续需要时重新决策 |

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

| 编号 | 资料 | 主要用途 | 当前优先级 |
|---|---|---|---|
| U1 | `用户需求决策记录 V1.0` | 定义 POC、平台、高德、真实定位、匿名、本机数据及排除项 | 1 |
| C1 | 当前 `map-gm-app` 工程 | 定义技术基线和实际实现现状 | 2 |
| S1 | `光明区文旅全域地图及AI导览POC建设方案.docx` | 提供 POC 背景、7 天约束和原始页面设想 | 3 |
| S2 | `文旅小程序三期规划方案202607091517.pptx` | 补充地图、POI、真实定位打卡、奖励及长期功能 | 4 |
| S3 | `文旅小程序三期规划方案20260709.pptx` | 提供三期产品、运营和商业化背景 | 5 |

冲突时采用 `U1 > C1 > S1 > S2 > S3`。S1 中的 AI 和模拟打卡已被 U1 替换；S2/S3 中的路线、交易、后台和正式会员能力不因出现在附件中而进入本期。

### 2.3 产品边界

- 本文定义 POC 的用户流程、业务规则、数据、前端适配、验收和 7 天交付范围。
- 本文不等同于正式版本 PRD、生产安全设计、等保方案、采购合同或长期运营方案。
- 本文不规定后端必须采用某一种语言、数据库或部署方式。
- 本文不提供像素级 UI、视觉尺寸和最终品牌规范。
- 本期只验证实际记录的 iOS、微信、基础库和网络组合，不外推为所有 iOS 设备兼容。
- 真实定位指调用微信/系统位置能力获得当前样本并完成规则校验，不代表具备生产级反作弊或能识别系统级位置伪造。

### 2.4 术语

| 术语 | 定义 |
|---|---|
| POC | Proof of Concept，用最小可运行范围验证关键能力，不等同正式产品 |
| POI | Point of Interest，地图上的景点、场馆、餐饮、住宿或公共服务点位 |
| 真实定位 | 在用户操作时通过微信小程序位置接口取得的当前系统定位样本，不由产品内手工填写 |
| 定位精度 | 位置接口返回的误差估计值，单位为米；数值越小通常表示样本越可信 |
| 打卡半径 | 以 POI 坐标为中心允许打卡的配置距离，单位为米 |
| 边界不确定 | 结合距离与定位精度后，无法高置信判断用户在打卡范围内或范围外的状态 |
| 匿名本机用户 | 不登录，由本机生成随机标识的 POC 用户；不形成正式会员身份 |
| 本机资产 | 当前设备微信存储中的打卡、积分和徽章数据；不跨设备、不可兑换 |
| GCJ-02 | 中国大陆互联网地图常用坐标系；本期 POI 和定位计算统一采用该口径 |

## 3. 背景与问题

### 3.1 背景

三份附件提出以全域地图整合光明区文旅资源，并逐步扩展路线、互动、会员、运营和交易能力。当前不是建设完整三期产品，而是用 7 天 POC 验证一段最小且可感知的体验：用户能否从地图找到点位，到达现场后完成真实定位打卡，并在本机看到奖励结果。

当前工程使用适合微信小程序开发的 uni-app 技术栈，但仍是通用模板，没有可核实的地图、POI、定位打卡或奖励业务实现。因此 POC 既要验证第三方地图和微信位置能力，也要验证本地业务状态是否能稳定衔接。

### 3.2 用户问题

| 问题 | 用户影响 | 本期应对 | 证据状态 |
|---|---|---|---|
| 光明区文旅信息分散，位置关系不直观 | 用户难以快速建立区域认知并找到感兴趣的地点 | 用地图、分类、marker 和详情统一展示样本 POI | 来自附件判断；缺少游客访谈和行为数据 |
| 到达点位后缺少轻量互动反馈 | 线下到访难以在产品内形成即时成就感 | 通过真实定位校验完成打卡，发放本机积分和徽章 | 来自 S2/S3 方向；价值仍需测试 |
| 项目方缺少可运行样例 | 难以判断地图和到点互动是否值得进入正式建设 | 用 iOS 微信小程序执行可重复的端到端验证 | S1 明确 POC 导向 |

AI 个性化路线原本用于解决行程组合问题，但用户已决定本期暂不处理，因此该问题不属于本期 POC 要证明的内容。

### 3.3 问题陈述

对于第一次了解或正在游览光明区的体验游客，当前资料假设他们需要一种直观方式发现文旅地点，并在真实到达点位后获得即时互动反馈。对于项目决策方，需要验证微信小程序能否稳定承载地图、POI、真实定位范围判定及匿名本机奖励。当前 POC 通过一条不依赖登录、AI 和路线规划的主流程验证上述可行性。

### 3.4 证据限制

- 未提供游客访谈、现有产品漏斗、活跃度或打卡意愿数据。
- 未提供正式业务指标基线，不能用本 POC 宣称提升游客量、停留时长或消费额。
- 当前用户画像和 5 人任务测试属于产品细化，用于降低可用性风险，不代表完成市场验证。
- POC 结论应区分“技术可运行”“用户能完成”“正式版本值得投入”三种证据层级。

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

### 4.1 产品目标

| ID | 目标 | 本期验证方式 |
|---|---|---|
| OBJ-01 | 验证高德相关地图能力与样本 POI 可在目标微信小程序运行 | 在实际 iOS 环境展示地图、marker、分类和点位联动 |
| OBJ-02 | 验证 POI 信息可支持基本浏览和到点判断 | 核对 POI 必填字段、详情、坐标和打卡配置 |
| OBJ-03 | 验证真实定位打卡规则可执行 | 在范围内、范围外、精度不足和权限异常场景执行判定 |
| OBJ-04 | 验证奖励幂等和本机持久化 | 首次打卡发奖，重复打卡不重复发奖，重启后可回看 |
| OBJ-05 | 验证匿名流程无需账号也能完成 | 从首次打开到个人中心全程不要求登录 |
| OBJ-06 | 为正式版本是否继续投入提供风险清单 | 输出实测环境、结果、失败原因和后续依赖 |

### 4.2 史诗假设

假设：如果为光明区体验游客提供“地图发现 + 审核 POI + 真实到点打卡 + 本机奖励”，那么未登录用户能够在 iOS 微信小程序内理解并完成从发现地点到获得互动反馈的过程；项目方也能识别地图接入、位置权限、坐标准确性和本机资产的主要风险。

验证方式：

1. 在一个可实地验证的 POI，执行范围内、范围外、权限拒绝、精度不足、重复打卡和重启恢复测试。
2. 邀请 5 名未参与设计的测试者完成“找点位 → 查看详情 → 尝试打卡 → 查看奖励”的任务，记录完成率、耗时和卡点。

### 4.3 POC 成功标准

下表为产品细化建议，最终阈值由产品和技术评审确认。由于没有现状基线，指标用于判断 POC 是否可演示，不用于证明业务增长。

| 类型 | 指标 | 建议目标 | 测量方式 |
|---|---|---|---|
| 主指标 | 核心交互稳定运行 | 约定环境连续执行 10 次，10 次均得到正确成功/失败/不确定状态且无崩溃、死路或错误发奖 | Day 6-7 实测；不要求每次定位都成功 |
| 地图 | 地图首屏可交互时间 | 20 次测试 P95 不超过 3 秒 | 实际 iOS、约定网络 |
| 数据 | POI 必填字段完整率 | 100% | 导入校验 |
| 数据 | 可打卡 POI 坐标抽检 | 目标测试 POI 100% 通过实地核对 | 实地测试 |
| 定位 | 明确范围内打卡成功率 | 10 次独立定位不少于 9 次成功；不确定或定位无效计为未成功，可按产品流程重试但不改写该次结果 | 距离边界留有安全余量的场内点 |
| 定位 | 明确范围外误放行率 | 10 次误放行 0 次 | 距离边界留有安全余量的场外点 |
| 奖励 | 重复发奖 | 首次成功后重复操作 20 次，重复发奖 0 次 | 含关闭重开场景 |
| 存储 | 本机状态一致率 | 杀进程并重开 10 次，记录、积分、徽章一致率 100% | 当前设备实测 |
| 可用性 | 核心任务完成率 | 5 名测试者中至少 4 名无需口头指导完成 | Day 6 任务测试 |
| 隐私 | 精确位置持久化 | 本机业务存储和业务日志中为 0 条 | 代码与数据检查 |
| 质量 | S0/S1 缺陷 | 演示前均为 0 | 缺陷清单 |

### 4.4 护栏指标

- 定位失败、拒绝权限或越界时，积分和徽章发放次数必须为 0。
- 地图或高德服务失败不得清除已有本机打卡资产。
- 不得把测试数据、产品内模拟位置或手工按钮当作真实定位成功。
- 不得把 POC 本机积分描述为可兑换、可跨设备或具备正式账户保障的资产。
- 不得将未测试的 Android、其他 iOS 设备或最低基础库区间表述为已兼容。

### 4.5 POC 决策门槛

| 结论 | 条件 | 下一步 |
|---|---|---|
| 通过 | 核心脚本稳定、真实定位判定可用、无越界误放行、奖励和本机状态一致 | 可进入正式一期需求和技术设计 |
| 有条件通过 | 主流程可运行，但高德接入、位置权限、坐标或现场环境依赖人工处理 | 先关闭专项风险，再决定正式建设 |
| 不通过 | 目标环境无法稳定显示地图、无法取得可信定位、错误授奖或流程难以理解 | 调整技术方案、打卡规则或停止投入 |

POC 通过不等于正式版本可以上线。正式版仍需服务端资产、账号、隐私合规、反作弊、监控、多端兼容和数据治理设计。

## 5. 用户与场景

### 5.1 用户角色

| 角色 | 定位 | 主要目标 | 本期边界 | 状态 |
|---|---|---|---|---|
| 体验游客 | POC 主要用户 | 浏览 POI、到点打卡、获得奖励 | 匿名；数据只在当前设备 | 假设的首要用户 |
| POC 测试者 | 执行验收场景 | 验证范围内外、权限异常和状态恢复 | 不使用产品内虚拟定位 | 产品细化 |
| 内容负责人 | 提供和审核 POI | 保证坐标、图文和半径可用 | 本期不建设 CMS | 支撑角色 |
| 演示管理员 | 准备和恢复演示状态 | 重置本机数据、记录环境与结果 | 无后台管理权限 | 支撑角色 |
| 项目决策人员 | 查看 POC 结果 | 判断后续投资和主要风险 | 具体对象与签字人暂缓 | 附件中的相关角色 |
| 正式会员/商户/运营人员 | 后续产品角色 | 管理账户、交易、内容或活动 | 本期无入口 | 后续范围 |

### 5.2 主要用户任务

| JTBD ID | 当…… | 我想要…… | 从而…… |
|---|---|---|---|
| JTBD-01 | 我不了解光明区文旅资源分布 | 从地图按类别浏览地点 | 快速找到感兴趣的 POI |
| JTBD-02 | 我对一个点位感兴趣 | 查看位置、简介、开放信息和特色 | 判断是否前往或了解该地点 |
| JTBD-03 | 我已经到达支持打卡的地点 | 让小程序验证我的当前位置 | 完成真实到点互动 |
| JTBD-04 | 我完成打卡 | 立即看到积分和徽章反馈 | 获得成就感并理解激励设计 |
| JTBD-05 | 我稍后再次打开小程序 | 回看本机打卡、积分和徽章 | 确认本次体验被保留 |

### 5.3 核心用户旅程

```mermaid
flowchart TD
    A[打开微信小程序] --> B{地图与 POI 是否加载成功}
    B -- 否 --> B1[显示错误和重试]
    B1 --> B
    B -- 是 --> C[浏览或筛选 POI]
    C --> D[查看 POI 摘要和详情]
    D --> E{POI 是否支持打卡}
    E -- 否 --> C
    E -- 是 --> F[用户主动点击打卡]
    F --> G{位置权限和系统定位是否可用}
    G -- 否 --> G1[说明原因并提供恢复或返回]
    G1 --> D
    G -- 是 --> H[获取新的真实定位样本]
    H --> I{精度、时效和坐标是否合法}
    I -- 否 --> I1[不授奖，提示重试]
    I1 --> D
    I -- 是 --> J{是否通过距离与半径校验}
    J -- 否 --> J1[不授奖，提示未到达或结果不确定]
    J1 --> D
    J -- 是 --> K{是否已完成相同任务}
    K -- 是 --> K1[显示已打卡，不重复发奖]
    K -- 否 --> L[记录打卡并发放积分/徽章]
    K1 --> M[个人中心本机回看]
    L --> M
```

### 5.4 核心场景

| 场景 ID | 场景 | 预期结果 |
|---|---|---|
| SCN-01 | 首次打开并浏览地图 | 不要求登录；地图和 POI 正常展示 |
| SCN-02 | 切换类别并打开详情 | marker、摘要和详情保持同一 `poiId` |
| SCN-03 | 首次授权且位于有效范围内 | 获取新位置、通过校验、打卡和发奖一次 |
| SCN-04 | 位于范围外 | 明确提示未到达，不记录成功、不发奖 |
| SCN-05 | 拒绝位置权限 | 可返回浏览、重试或按平台能力打开设置，不形成死路 |
| SCN-06 | 定位精度不足或超时 | 停止加载，解释原因，可重试，不发奖 |
| SCN-07 | 重复打卡 | 显示已完成，积分和徽章不变化 |
| SCN-08 | 关闭并重新打开 | 本机历史、积分和徽章保持一致 |
| SCN-09 | 重置演示数据 | 二次确认后只清除 POC 用户状态，不清除基础 POI |

## 6. 产品范围

### 6.1 本期必做 P0

| 能力 | 本期结果 | 范围说明 |
|---|---|---|
| 地图首页 | 在目标 iOS 微信小程序中可打开、拖动和缩放 | 使用经技术验证可行的高德相关接入方案 |
| POI marker | 展示审核后的样本 POI | marker 关联稳定 `poiId`，类别可区分 |
| 分类与筛选 | 按已提供的主分类切换可见点位 | 无数据的筛选项不展示 |
| POI 摘要与详情 | 展示标准图文、位置和开放信息 | 缺失字段按规则处理 |
| 打卡入口 | 只在合法且已启用打卡的 POI 显示 | 不提供手工模拟成功入口 |
| 位置权限 | 按需说明用途并请求位置 | 拒绝、系统关闭和恢复均有明确状态 |
| 真实定位 | 每次打卡请求新的 GCJ-02 位置样本 | 不使用缓存成功结果直接发奖 |
| 定位有效性 | 校验坐标、精度、时效和接口状态 | 无效样本不得进入成功判定 |
| 距离校验 | 按 POI 配置半径判断范围内、范围外或不确定 | 规则见第 10 章 |
| 打卡幂等 | 同一本机匿名用户对同一任务只成功一次 | 重复操作不重复发奖 |
| 积分与徽章 | 成功后即时展示并保存本机 | 只代表 POC 演示资产 |
| 个人中心 | 回看本机打卡、积分和徽章 | 不登录、不跨设备同步 |
| 演示重置 | 二次确认后恢复统一初始状态 | 不提供虚拟定位或绕过校验开关 |
| 异常恢复 | 地图、数据、权限、定位和存储异常有下一步 | 不以假成功保证演示 |

### 6.2 条件范围 P1

| 能力 | 纳入条件 | 不满足时处理 |
|---|---|---|
| POI 名称搜索 | POI 数量足以产生搜索价值，名称和别名已提供 | 只保留分类浏览 |
| 组合筛选 | 标签字段、交互和样本量已确定 | 只保留单选主分类 |
| 官方推荐排序 | 有指定内容负责人和可解释配置 | 使用普通列表，不宣称热度榜单 |
| 电话/预约/外部位置动作 | 数据真实，微信端行为已在 iOS 验证 | 隐藏对应入口，不放空按钮 |
| 打卡结果分享 | 素材、隐私和微信分享行为已确认 | 不进入本期主流程 |

P1 不得挤占真实定位、奖励幂等和 iOS 异常测试时间。任何 P1 只有在所有 P0 已进入可验收状态后才能纳入。

### 6.3 明确不在本期

- AI 助手、开放问答、AI 路线、知识库、提示词、模型 API 和 AI 指标。
- 路径规划、路线结果页、站点顺序、polyline、道路路径、实时导航和动态重排。
- 产品内虚拟定位、坐标输入、位置切换、模拟成功和调试打卡开关。
- 正式微信登录、手机号登录、会员账户、跨设备同步和用户画像。
- 服务端积分账户、正式流水、兑换、核销、风控和生产级定位防作弊。
- 后台持续定位、轨迹记录、设备指纹和位置伪造识别。
- Android、H5、App、支付宝小程序等端的本期兼容与验收。
- CMS、运营后台、商户后台、监管端、数据大屏和正式统计平台。
- 游记、评论、UGC、活动、优惠券、商品、订单、支付、退款、分账和对账。
- 生产 SLA、万人并发、等保验收和长期运维承诺。

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

| 维度 | 本期 POC | 正式版本至少需要补充 |
|---|---|---|
| 身份 | 本机随机匿名 ID | 账号、授权、注销和身份合并 |
| 打卡判定 | 客户端按系统位置样本判断 | 服务端校验、风控、审计和反作弊 |
| 资产 | 本机积分和徽章 | 服务端账户、流水、幂等、补偿和兑换规则 |
| 数据 | 审核样本或 POC API | CMS、版本、审核、下线和更新责任 |
| 兼容 | 实际 iOS 环境 | 设备矩阵、最低基础库、Android 和回归策略 |
| 监控 | 测试记录或开发日志 | 生产监控、告警、隐私合规和数据治理 |

## 7. 产品方案

### 7.1 方案概述

POC 采用“地图发现、详情判断、真实定位、到点打卡、本机奖励”五段式方案。POI 是所有页面和状态的主数据：地图 marker、详情、打卡任务和奖励记录均通过稳定的 `poiId` 关联，避免名称、坐标和状态不一致。

用户只有在点击打卡时才触发位置请求。系统取得新的 GCJ-02 样本后，先验证接口结果、经纬度、时间和精度，再计算与 POI 的球面距离；明确在范围内才提交本地打卡事务。定位失败、越界或边界不确定均不产生成功记录和奖励。

成功状态由一个本地事务完成：写入打卡记录、积分变动和徽章授予，并更新个人中心汇总。`demoUserId + taskId` 作为奖励幂等键，确保重复点击、页面重进和应用重启不会重复发奖。精确位置样本仅用于内存中的当次判断，默认不持久化、不进入业务埋点。

### 7.2 能力关系

```mermaid
flowchart TB
    subgraph Client[map-gm-app 微信小程序]
      MAP[地图与筛选]
      POI[POI 详情]
      LOC[权限与真实定位]
      CHECK[距离判定与打卡]
      REWARD[积分与徽章]
      PROFILE[个人中心]
    end

    subgraph External[外部能力]
      AMAP[高德地图 API 或官方支持能力]
      WXLOC[微信小程序位置接口]
    end

    subgraph Data[审核数据与本机状态]
      POIDATA[POI 和打卡配置]
      LOCAL[匿名 ID/打卡/积分/徽章]
    end

    MAP --> POI
    POI --> LOC
    LOC --> CHECK
    CHECK --> REWARD
    REWARD --> PROFILE
    MAP --> AMAP
    LOC --> WXLOC
    MAP --> POIDATA
    POI --> POIDATA
    CHECK --> POIDATA
    CHECK --> LOCAL
    REWARD --> LOCAL
    PROFILE --> LOCAL
```

### 7.3 默认产品决策

| ID | 默认决策 | 状态 |
|---|---|---|
| PD-01 | 启动页为地图首页，不设置登录前置 | 已确认方向 |
| PD-02 | 使用四个业务路由：地图、POI 详情、打卡反馈、个人中心 | 产品细化；页面数量不作为 POC 成功指标 |
| PD-03 | 每个 POI 单独配置打卡开关和半径；未配置半径时建议默认 `200m` | 产品细化，Day 1 确认 |
| PD-04 | 位置样本精度大于 `100m` 或生成时间超过 `30s` 时不判定成功 | 产品细化，Day 1 真机校准 |
| PD-05 | 使用距离与精度的保守边界规则，无法明确在范围内时提示重试 | 产品细化，规则见 10.2 |
| PD-06 | 定位校验在客户端完成，只用于 POC；不宣称防作弊 | POC 边界 |
| PD-07 | 用户拒绝定位后仍可继续地图和 POI 浏览 | 已确认方向 |
| PD-08 | 匿名 `demoUserId`、打卡、积分和徽章使用 Pinia 本机持久化 | 已确认方向 |
| PD-09 | 重置功能清除 POC 用户状态，但不清除 POI 基础数据 | 产品细化 |
| PD-10 | 地图在线能力失败只允许重试或显示明确错误，不允许用静态图冒充在线地图成功 | 产品细化 |

### 7.4 状态流转

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> RequestingPermission: 用户点击打卡
    RequestingPermission --> PermissionDenied: 拒绝或系统不可用
    RequestingPermission --> Locating: 权限可用
    PermissionDenied --> Idle: 返回或恢复权限
    Locating --> LocationInvalid: 超时/报错/坐标或精度无效
    LocationInvalid --> Locating: 用户重试
    Locating --> Evaluating: 获得有效新样本
    Evaluating --> Outside: 明确范围外
    Evaluating --> Uncertain: 边界不确定
    Outside --> Idle: 返回详情
    Uncertain --> Locating: 用户重试
    Evaluating --> AlreadyChecked: 幂等键已存在
    Evaluating --> Committing: 明确范围内且未打卡
    Committing --> Success: 本机事务成功
    Committing --> PersistFailed: 本机写入失败
    PersistFailed --> Idle: 不展示已发奖
    AlreadyChecked --> [*]
    Success --> [*]
```

## 8. 页面与导航

### 8.1 页面清单

| 页面 ID | 页面 | 建议路由 | 主要职责 | 优先级 |
|---|---|---|---|---|
| PAGE-01 | 全域地图首页 | `/pages/map/index` | 地图、分类、筛选、marker、POI 摘要、个人中心入口 | P0 |
| PAGE-02 | POI 详情 | `/pages-poi/detail` | 标准详情、可打卡状态、位置权限说明和打卡入口 | P0 |
| PAGE-03 | 打卡反馈 | `/pages-rewards/checkin` | 定位过程、距离判定、异常恢复、成功奖励或已完成状态 | P0 |
| PAGE-04 | 个人中心 | `/pages-user/index` | 匿名身份说明、打卡记录、积分、徽章和数据重置 | P0 |

分类栏、组合筛选、POI 摘要、权限说明、徽章结果可按设计采用页内浮层；是否拆分为独立 UI 组件不改变业务范围。本期不以“约 10 页”作为验收标准，也不通过拆分浮层凑页面数量。

### 8.2 导航关系

```mermaid
flowchart LR
    P1[PAGE-01 地图首页] --> P2[PAGE-02 POI 详情]
    P1 --> P4[PAGE-04 个人中心]
    P2 --> P1
    P2 --> P3[PAGE-03 打卡反馈]
    P3 --> P2
    P3 --> P4
    P4 --> P1
    P4 --> P2
```

### 8.3 全局页面状态

| 状态 | 展示要求 | 用户动作 |
|---|---|---|
| `initial` | 页面骨架或明确初始内容 | 开始浏览或打卡 |
| `loading` | 局部 Loading，不锁住无关操作 | 等待；超时后可重试 |
| `success` | 展示完整数据或结果 | 继续下一步 |
| `empty` | 说明无点位、无记录或无徽章 | 清除筛选或返回地图 |
| `error` | 说明发生了什么，不暴露内部信息 | 重试或返回 |
| `permission_denied` | 说明位置用途和未授权影响 | 再次申请、打开设置或继续浏览 |
| `location_invalid` | 说明超时、精度不足或系统定位不可用 | 移至开阔区域后重试 |
| `outside` | 说明尚未进入有效范围 | 返回详情或到达后重试 |
| `uncertain` | 说明当前定位无法可靠判定 | 重新获取位置，不授奖 |
| `already_checked` | 展示原打卡和奖励状态 | 查看个人中心，不重复发奖 |

### 8.4 页面共性要求

- 用户无需登录即可进入全部 P0 页面。
- 地图和位置权限失败不能导致白屏、无限 Loading 或无法返回。
- 每次打卡操作只处理最后一次有效请求；重复点击不得产生并发发奖。
- 页面返回后保留筛选和选中 POI，不保留精确当前位置样本。
- 个人中心必须明确提示“数据仅保存在当前设备；清除缓存、卸载或更换设备可能丢失”。
- 不显示 AI、路线规划、导航或虚拟定位入口及占位按钮。

## 9. 功能需求

### 9.1 MAP：地图与 POI 发现

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| MAP-001 | 地图初始化 | 打开首页后展示光明区配置中心点和缩放级别；成功后可拖动、缩放 | P0 |
| MAP-002 | 高德能力接入 | 只使用 Day 1 验证通过的官方接入方式；失败时显示明确错误和重试 | P0 |
| MAP-003 | POI marker | 将当前可见且 `status=published` 的 POI 渲染为 marker，并关联唯一 `poiId` | P0 |
| MAP-004 | 类别区分 | 不同主分类使用可识别的图标或文字；不能只依赖颜色 | P0 |
| MAP-005 | 分类切换 | 支持“全部”和已配置主分类单选；以最后一次选择结果为准 | P0 |
| MAP-006 | 条件筛选 | 只有数据中存在的标签才显示；清除条件后恢复当前分类结果 | P1 |
| MAP-007 | marker 联动 | 点击 marker 后展示同一 POI 的摘要；再次点击或点击摘要可进入详情 | P0 |
| MAP-008 | 选中状态 | 当前 marker、摘要和详情入口保持一致；地图移动不应切换到其他 POI | P0 |
| MAP-009 | 空结果 | 当前条件无结果时显示说明和“清除筛选”动作，不显示错误 marker | P0 |
| MAP-010 | 数据失败 | POI 数据失败时不渲染半成品，提供重试；若使用本地审核数据须标明数据来源 | P0 |
| MAP-011 | 位置展示 | 用户未主动打卡前不要求位置权限；地图浏览不依赖当前位置 | P0 |
| MAP-012 | 搜索 | 可按名称或别名匹配；无结果可清空关键词 | P1 |

**US-01：从地图发现点位**

作为第一次了解光明区的体验游客，我希望按类别查看地图点位，从而快速发现感兴趣的地点。

```gherkin
场景: 切换主分类
  假如 地图和审核 POI 数据已经加载
  并且 当前展示“全部”分类
  当 游客选择一个有效主分类
  那么 地图只展示属于该主分类且已发布的 POI
  并且 marker、结果数量和空状态使用同一筛选结果
```

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

### 9.2 POI：摘要、详情与打卡资格

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| POI-001 | 摘要卡 | 展示名称、主分类、封面、短介绍和特色标签；缺失可选字段时不留空白占位 | P0 |
| POI-002 | 基本详情 | 展示名称、图集或封面、简介、地址、开放时间和特色标签 | P0 |
| POI-003 | 可选详情 | 电话、票价、预约说明、无障碍信息仅在数据存在且可用时展示 | P0 |
| POI-004 | 缺失处理 | 开放时间未知显示“开放时间待确认”；图片失败使用统一占位图 | P0 |
| POI-005 | 坐标有效性 | 坐标缺失、越界或非 GCJ-02 时，该 POI 不得进入真实打卡流程 | P0 |
| POI-006 | 打卡状态 | 明确显示“可打卡”“已打卡”或“暂不支持打卡”，不得用无响应按钮代替 | P0 |
| POI-007 | 打卡说明 | 首次进入打卡前说明需要当前位置、判断用途和失败影响 | P0 |
| POI-008 | 打卡入口 | 只有 `checkinEnabled=true`、任务有效且坐标合法时显示可操作入口 | P0 |
| POI-009 | 已完成状态 | 已完成相同任务时显示原奖励摘要，仍可进入反馈页但不再次请求位置或发奖 | P0 |
| POI-010 | 无效点位 | `poiId` 不存在或已下线时显示可理解提示并允许返回地图 | P0 |
| POI-011 | 外部动作 | 电话、预约、分享等动作只有在数据及 iOS 行为验证通过后显示 | P1 |

**US-02：查看点位详情**

作为对某个地图点位感兴趣的游客，我希望查看经过审核的信息和打卡状态，从而判断是否到访并参与互动。

```gherkin
场景: 打开可打卡 POI
  假如 游客从 marker 打开一个已发布且坐标合法的 POI
  并且 该 POI 的打卡任务处于有效状态
  当 详情数据加载完成
  那么 页面展示标准详情字段
  并且 显示真实定位打卡入口和位置用途说明
```

```gherkin
场景: POI 坐标无效
  假如 POI 的坐标缺失、越界或坐标系不符合要求
  当 游客打开该 POI 详情
  那么 页面不允许进入成功打卡流程
  并且 显示“该点位暂不支持打卡”
```

### 9.3 LOC：权限与真实定位

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| LOC-001 | 按需申请 | 只在用户主动点击打卡后申请位置，不在启动时强制申请 | P0 |
| LOC-002 | 用途说明 | 权限文案说明“用于判断是否到达当前打卡点”，不得宣称持续追踪 | P0 |
| LOC-003 | 权限检查 | 区分未询问、已授权、已拒绝、系统定位关闭及接口不可用 | P0 |
| LOC-004 | 重新授权 | 拒绝后允许再次操作；按平台能力提供打开系统或小程序设置的恢复方式 | P0 |
| LOC-005 | 新定位请求 | 每次未完成任务的打卡尝试都发起新请求，要求 `type=gcj02` | P0 |
| LOC-006 | 请求互斥 | 定位过程中禁用重复提交；旧请求不得覆盖最新页面状态 | P0 |
| LOC-007 | 请求超时 | 建议 30 秒内未获得有效结果即停止 Loading、标记失败并允许重试 | P0 |
| LOC-008 | 坐标校验 | 经度必须在 `[-180, 180]`、纬度在 `[-90, 90]`，且均为有限数值 | P0 |
| LOC-009 | 精度校验 | 必须取得有效正数 `accuracy`；建议大于 `100m` 时不进入成功判定 | P0 |
| LOC-010 | 时效校验 | 只使用本次请求返回的样本；请求完成超过建议 30 秒或页面重新进入后重新定位 | P0 |
| LOC-011 | 近似位置 | iOS 关闭“精确位置”导致精度不足时说明影响，不将低可信样本判为成功 | P0 |
| LOC-012 | 生命周期恢复 | 从设置返回或应用重新激活后重新检查授权并发起新定位，不沿用旧失败或旧样本 | P0 |
| LOC-013 | 最小化使用 | 原始经纬度只在当次判定的内存中使用，默认不持久化、不上报、不打印 | P0 |
| LOC-014 | 产品内模拟禁用 | P0 页面、配置和业务代码不得允许输入坐标、选择虚拟地点或直接切换成功 | P0 |

🔶 **假设**：`100m` 精度阈值与 `30s` 请求时限适合当前 POC。Day 1 应在目标 iOS 环境实测；如需调整，必须更新配置、验收用例和本文档，不能只在代码中变更。

**US-03：授权并取得真实定位**

作为到达 POI 的匿名游客，我希望在明确知道用途后授权当前位置，从而让小程序判断我是否可以打卡。

```gherkin
场景: 首次同意位置权限
  假如 游客尚未完成当前打卡任务
  并且 位置权限尚未作出选择
  当 游客点击打卡并同意位置权限
  那么 系统发起新的 GCJ-02 定位请求
  并且 在位置有效性和距离判定完成前不生成成功记录或奖励
```

```gherkin
场景: 用户拒绝位置权限
  假如 游客点击打卡
  当 游客拒绝位置权限
  那么 系统停止定位状态
  并且 不记录成功、不发放积分或徽章
  并且 提供返回详情、再次尝试或按平台能力打开设置的动作
```

```gherkin
场景: 定位结果精度不足
  假如 用户已授权位置
  当 本次位置返回的精度大于配置阈值
  那么 系统将结果标记为定位无效
  并且 提示移动至开阔区域或开启精确位置后重试
  并且 不记录成功或发奖
```

### 9.4 CHECK：距离判定与打卡

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| CHECK-001 | 打卡资格 | 同时满足 POI 已发布、任务有效、坐标合法和用户未完成该任务才请求位置 | P0 |
| CHECK-002 | 半径读取 | 优先使用任务配置 `checkinRadiusMeters`；缺失时采用已确认默认值 | P0 |
| CHECK-003 | 距离计算 | 使用用户与 POI 的 GCJ-02 坐标按 Haversine 公式计算球面距离，单位为米 | P0 |
| CHECK-004 | 保守成功 | 只有 `distanceMeters + accuracyMeters <= radiusMeters` 才判定明确范围内 | P0 |
| CHECK-005 | 明确越界 | 当 `distanceMeters - accuracyMeters > radiusMeters` 时判定明确范围外 | P0 |
| CHECK-006 | 边界不确定 | 其他与边界重叠的结果标记为不确定，提示重新定位，不授奖 | P0 |
| CHECK-007 | 判定透明 | 页面说明“已在范围内”“尚未到达”或“定位无法确定”，不必展示精确坐标 | P0 |
| CHECK-008 | 幂等键 | 使用 `demoUserId + taskId` 作为唯一成功键；存在时直接显示已完成 | P0 |
| CHECK-009 | 原子提交 | 打卡记录、积分变化和徽章授予作为一个本机状态提交；任一步失败均不展示成功 | P0 |
| CHECK-010 | 成功反馈 | 展示 POI、打卡时间、积分变化、徽章和进入个人中心动作 | P0 |
| CHECK-011 | 重复反馈 | 重复操作展示原完成结果，积分总数和徽章数量不变化 | P0 |
| CHECK-012 | 定位失败 | 权限、接口、超时、精度、坐标或距离失败均不得创建成功记录 | P0 |
| CHECK-013 | 并发保护 | 快速重复点击、页面切换和生命周期恢复不得产生多个奖励事务 | P0 |
| CHECK-014 | 校验版本 | 成功记录保存规则版本，便于后续识别不同半径或判定规则生成的数据 | P0 |

🔶 **假设**：可打卡 POI 未单独配置时使用 `200m` 半径。该默认值必须在 Day 1 结合 POI 场地边界、公共可达区域和实测精度确认；敏感或小型场馆应覆盖为更合适的值。

**US-04：范围内首次打卡**

作为实际到达 POI 的游客，我希望通过真实定位完成一次打卡，从而获得积分和徽章反馈。

```gherkin
场景: 明确位于有效半径内
  假如 POI、任务、半径和奖励配置均有效
  并且 本机匿名用户尚未完成该任务
  当 系统取得有效的新定位样本
  并且 计算结果满足“距离 + 精度 <= 打卡半径”
  那么 系统一次性写入打卡、积分和徽章状态
  并且 展示成功反馈
  并且 原始经纬度不进入本机持久化状态
```

**US-05：越界或边界不确定时不发奖**

作为 POC 测试者，我希望只有明确到达范围内才允许打卡，从而避免定位波动造成错误奖励。

```gherkin
场景: 明确位于范围外
  假如 本次定位样本有效
  当 计算结果满足“距离 - 精度 > 打卡半径”
  那么 系统显示尚未到达
  并且 不创建成功记录、积分变化或徽章授予
```

```gherkin
场景: 定位误差范围与打卡边界重叠
  假如 本次定位样本有效
  当 结果既不满足明确范围内也不满足明确范围外
  那么 系统显示当前定位无法可靠判断
  并且 允许重新定位
  并且 不创建成功记录或奖励
```

**US-06：避免重复奖励**

作为完成过打卡的匿名游客，我希望再次操作时看到已完成状态，从而保证积分和徽章前后一致。

```gherkin
场景: 重复打卡同一任务
  假如 本机已存在相同 demoUserId 与 taskId 的成功记录
  当 游客再次进入打卡流程
  那么 系统显示原完成状态
  并且 不必再次申请位置
  并且 积分总数、记录数和徽章授予数均不变化
```

### 9.5 REWARD：积分与徽章

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| REWARD-001 | 奖励配置 | 积分值和徽章使用任务配置，不在多个页面重复写死 | P0 |
| REWARD-002 | 积分发放 | 每条首次成功打卡最多生成一条正向积分变动 | P0 |
| REWARD-003 | 徽章授予 | 只有任务配置有效徽章时授予；同一任务不得重复授予 | P0 |
| REWARD-004 | 结果一致 | 成功页、详情已打卡状态和个人中心使用同一持久化状态 | P0 |
| REWARD-005 | 资产声明 | 明确 POC 积分和徽章只在当前设备保存，不可兑换、转移或恢复 | P0 |
| REWARD-006 | 配置缺失 | 奖励配置非法时不得出现部分发奖；显示失败并记录可诊断错误码 | P0 |
| REWARD-007 | 合计计算 | 积分总数由有效积分变动汇总或校验，不信任独立可漂移的页面数字 | P0 |

### 9.6 PROFILE：匿名个人中心与本机数据

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| PROFILE-001 | 匿名身份 | 显示“匿名体验用户”或同等表达，不展示虚假微信头像、昵称或会员等级 | P0 |
| PROFILE-002 | 数据边界 | 固定提示数据只在当前设备保存，清缓存、卸载或换机可能丢失 | P0 |
| PROFILE-003 | 资产汇总 | 展示本机有效打卡数、积分总数和已获徽章 | P0 |
| PROFILE-004 | 打卡历史 | 按时间倒序展示 POI 名称快照、打卡时间和奖励摘要 | P0 |
| PROFILE-005 | 徽章列表 | 展示已获徽章名称、图标、说明和获得时间 | P0 |
| PROFILE-006 | 空状态 | 无记录时说明尚未打卡，并提供返回地图动作 | P0 |
| PROFILE-007 | 数据重置 | 二次确认后清除匿名 ID、打卡、积分和徽章；不清除 POI 主数据 | P0 |
| PROFILE-008 | 重置结果 | 重置完成后各页面立即回到未打卡状态；失败时不得假装已清除 | P0 |
| PROFILE-009 | 存储异常 | 读取失败时展示可恢复提示；不得使用损坏状态继续发奖 | P0 |
| PROFILE-010 | 版本迁移 | 本机状态带 `schemaVersion`；无法迁移的状态经确认后重置 | P0 |

**US-07：回看本机成果**

作为完成过打卡的匿名游客，我希望在个人中心回看记录、积分和徽章，从而确认本次体验被当前设备保存。

```gherkin
场景: 重启后回看结果
  假如 本机已存在一条有效打卡及对应奖励
  当 游客关闭并重新打开小程序后进入个人中心
  那么 打卡数、积分总数和徽章与成功时一致
  并且 页面提示数据仅保存在当前设备
```

```gherkin
场景: 重置演示数据
  假如 本机存在 POC 用户状态
  当 演示管理员确认执行重置
  那么 系统清除匿名 ID、打卡、积分和徽章
  并且 保留 POI 基础数据
  并且 不创建任何用于绕过定位的新入口
```

### 9.7 DEMO：POC 测试保障

| 需求 ID | 需求 | 详细规则 | 优先级 |
|---|---|---|---|
| DEMO-001 | 环境记录 | 每次正式测试记录 iPhone 型号、iOS、微信、基础库、网络和应用版本 | P0 |
| DEMO-002 | 数据检查 | 测试前检查目标 POI 坐标、半径、任务和奖励配置 | P0 |
| DEMO-003 | 在线检查 | 测试前验证高德相关能力和 POI 数据源是否可用，不展示完整凭证 | P0 |
| DEMO-004 | 统一初态 | 通过个人中心重置到匿名未打卡状态 | P0 |
| DEMO-005 | 实地测试 | 范围内外验收使用实际 iOS 真机和真实物理位置 | P0 |
| DEMO-006 | 结果标记 | 开发工具或外部虚拟位置结果不得计入真实定位 P0 验收 | P0 |
| DEMO-007 | 凭证保护 | 测试记录、截图、日志和错误提示不包含完整高德 Key 或其他密钥 | P0 |

## 10. 业务规则

### 10.1 POI 与坐标规则

| 规则 ID | 规则 |
|---|---|
| BR-POI-01 | 每个 POI 必须有全局唯一且稳定的 `id`；地图、详情、打卡和历史只通过 `id` 关联 |
| BR-POI-02 | 只有 `status=published` 的 POI 可在地图正常展示 |
| BR-POI-03 | 只有 `checkinEnabled=true`、GCJ-02 坐标合法且存在有效任务的 POI 可进行打卡 |
| BR-POI-04 | POI 和用户定位必须统一为 GCJ-02 后才能计算；不得直接混用 WGS-84、BD-09 或未知坐标 |
| BR-POI-05 | 一个 POI 有一个主分类，可有多个标签；分类和标签枚举集中配置 |
| BR-POI-06 | POI 下线或任务停用后，不得新增打卡；历史记录使用成功时的名称和奖励快照 |
| BR-POI-07 | 评分、热度或榜单没有可信来源时不得展示为客观排序；可使用有负责人和理由的“官方推荐” |

### 10.2 定位与距离规则

| 规则 ID | 规则 |
|---|---|
| BR-LOC-01 | 用户主动打卡前不请求位置；授权仅用于本次到点判定 |
| BR-LOC-02 | 每次未完成任务的尝试必须取得本次新样本，不能用上次成功坐标直接判断 |
| BR-LOC-03 | 定位类型固定为 GCJ-02；接口返回失败、非有限坐标或缺失精度时判定无效 |
| BR-LOC-04 | 默认有效精度阈值为 `100m`，默认请求时限为 `30s`；均须可配置并记录版本 |
| BR-LOC-05 | 两点距离使用 Haversine 公式，地球平均半径取 `6371008.8m`，中间值使用浮点，展示值可四舍五入 |
| BR-LOC-06 | 设距离为 `d`、精度为 `a`、半径为 `r`：`d + a <= r` 才判定范围内 |
| BR-LOC-07 | `d - a > r` 判定范围外；其余情况为边界不确定，需要重新定位 |
| BR-LOC-08 | 定位无效、范围外或不确定均不得生成成功记录、积分变动或徽章授予 |
| BR-LOC-09 | 从设置返回、应用重新激活或页面重新进入后，打卡必须重新取得权限状态和位置样本 |
| BR-LOC-10 | 原始经纬度、轨迹和系统定位对象默认只存在内存，不进入持久化、业务埋点或普通日志 |
| BR-LOC-11 | 客户端规则只能证明“本次系统接口样本通过 POC 规则”，不能证明没有系统级位置伪造 |

### 10.3 打卡与奖励规则

| 规则 ID | 规则 |
|---|---|
| BR-REWARD-01 | 首次启动生成随机 `demoUserId`；不得使用固定全局用户导致不同设备共享概念 |
| BR-REWARD-02 | 唯一成功键为 `demoUserId + taskId`，对应记录最多一条 |
| BR-REWARD-03 | 奖励由任务快照决定，前端页面不得各自计算不同积分值 |
| BR-REWARD-04 | 打卡记录、积分变动和徽章授予必须先计算完整下一状态，再一次提交本机存储 |
| BR-REWARD-05 | 本机提交失败时整次操作视为失败，不展示已打卡或已获得奖励 |
| BR-REWARD-06 | 重复操作返回已存在的成功结果，不重复请求位置、不新增积分或徽章 |
| BR-REWARD-07 | 徽章配置为空时可以只发积分，但该规则必须在任务配置中明确；非法徽章配置不得部分成功 |
| BR-REWARD-08 | 本机积分和徽章不可兑换、转移、恢复或作为正式权益证明 |

### 10.4 本机存储规则

| 规则 ID | 规则 |
|---|---|
| BR-STORE-01 | POC 用户状态使用一个带 `schemaVersion` 的持久化数据包，避免多个独立键部分写入 |
| BR-STORE-02 | 持久化内容只包含匿名 ID、业务记录、奖励和必要快照，不包含精确位置或轨迹 |
| BR-STORE-03 | 启动时校验数据结构、唯一键和积分一致性；异常状态不得继续发奖 |
| BR-STORE-04 | 清除微信缓存、卸载或更换设备可能导致数据丢失，产品必须明确告知 |
| BR-STORE-05 | 重置需二次确认，并只清除 POC 用户状态；基础 POI 数据和应用配置不受影响 |
| BR-STORE-06 | 不提供云端备份、跨设备同步或找回承诺 |

### 10.5 错误与恢复规则

| 错误类型 | 页面表现 | 恢复动作 | 是否可发奖 |
|---|---|---|---|
| 地图初始化失败 | 显示地图服务暂不可用和错误标识 | 重试 | 否 |
| POI 数据失败 | 不显示半成品 marker | 重试 | 否 |
| 位置权限拒绝 | 说明未授权影响 | 再次尝试、打开设置或继续浏览 | 否 |
| 系统定位关闭 | 说明需在 iOS 开启定位 | 打开设置或返回 | 否 |
| 定位接口超时/失败 | 停止 Loading，显示失败原因 | 重试 | 否 |
| 精度不足 | 说明当前位置不够精确 | 开启精确位置或移动后重试 | 否 |
| 明确范围外 | 显示尚未到达 | 到达后重试 | 否 |
| 边界不确定 | 说明当前误差覆盖边界 | 移动或等待后重试 | 否 |
| 重复打卡 | 展示原成功状态 | 查看个人中心 | 不新增 |
| 本机存储失败 | 不展示成功结果 | 重试或检查存储 | 否 |
| 本机状态损坏 | 显示数据异常 | 经确认后重置 | 否 |

## 11. 数据需求

### 11.1 POC 数据准备清单

| 数据包 | 最低内容 | 建议提供方 | 最晚时间 |
|---|---|---|---|
| POI 主数据 | 审核点位、分类、GCJ-02 坐标、简介、开放时间和图片 | 内容负责人 | Day 0 |
| 分类与标签 | 编码、名称、图标/颜色和排序 | 产品/运营 | Day 0 |
| 打卡配置 | 可打卡 POI、任务 ID、半径、有效期和状态 | 产品/内容 | Day 0 |
| 奖励配置 | 积分值、徽章 ID、名称、图标和说明 | 产品/运营 | Day 1 |
| 测试点位 | 可合法到达的场内点、场外点和现场注意事项 | 测试/内容 | Day 1 |
| 视觉素材 | Logo、主题色、占位图和徽章图 | UI/品牌 | Day 1 |

### 11.2 POI 数据模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 稳定唯一标识 |
| `name` | string | 是 | 点位名称 |
| `aliases` | string[] | 否 | 搜索别名 |
| `categoryCode` | enum | 是 | 主分类编码 |
| `tags` | string[] | 否 | 特色、主题或适用人群标签 |
| `longitude` | number | 是 | GCJ-02 经度 |
| `latitude` | number | 是 | GCJ-02 纬度 |
| `coordinateSystem` | enum | 是 | 本期只允许 `GCJ02` |
| `coverImage` | string | 是 | 合法 HTTPS 地址或包内资源 |
| `images` | string[] | 否 | 详情图集 |
| `summary` | string | 是 | 地图摘要短介绍 |
| `description` | string | 是 | 详情介绍 |
| `address` | string | 是 | 地址文本 |
| `openingHours` | string/null | 是 | 未知传 `null`，不伪造默认营业时间 |
| `phone` | string/null | 否 | 联系电话 |
| `ticketInfo` | string/null | 否 | 票价或预约说明 |
| `accessibility` | string[] | 否 | 无障碍信息 |
| `checkinEnabled` | boolean | 是 | 是否允许进入打卡流程 |
| `checkinTaskId` | string/null | 条件必填 | 可打卡时必须关联有效任务 |
| `status` | enum | 是 | `draft`、`published`、`offline` |
| `updatedAt` | datetime | 是 | 内容更新时间 |

### 11.3 打卡任务与奖励模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `taskId` | string | 是 | 稳定唯一任务标识 |
| `poiId` | string | 是 | 对应 POI |
| `checkinRadiusMeters` | number | 是 | 正数；未单配时由导入流程写入已确认默认值 |
| `locationAccuracyMaxMeters` | number | 是 | POC 默认 `100`，可按任务覆盖 |
| `locationTimeoutMs` | number | 是 | POC 默认 `30000` |
| `points` | integer | 是 | 非负整数 |
| `badgeId` | string/null | 否 | 对应徽章；可配置无徽章任务 |
| `validFrom` | datetime/null | 否 | 任务开始时间 |
| `validTo` | datetime/null | 否 | 任务结束时间 |
| `status` | enum | 是 | `active`、`inactive` |
| `verificationVersion` | string | 是 | 如 `poc-location-v1` |

徽章模型至少包含 `badgeId`、`name`、`image`、`description` 和 `status`。徽章图片须有合法使用权并可在微信小程序访问。

### 11.4 瞬时定位样本模型

该模型只用于当次内存计算，不进入本机持久化或普通埋点。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `longitude` | number | 是 | 本次 GCJ-02 经度 |
| `latitude` | number | 是 | 本次 GCJ-02 纬度 |
| `accuracyMeters` | number | 是 | 正数精度估计 |
| `requestStartedAt` | datetime | 是 | 本次请求开始时间 |
| `receivedAt` | datetime | 是 | 本次返回接收时间 |
| `coordinateSystem` | enum | 是 | 固定 `GCJ02` |

### 11.5 本机 POC 状态模型

| 实体 | 关键字段 | 说明 |
|---|---|---|
| 状态包 | `schemaVersion`、`demoUserId`、`checkins`、`pointTransactions`、`badgeAwards`、`updatedAt` | 统一持久化单元 |
| 打卡记录 | `recordId`、`idempotencyKey`、`taskId`、`poiId`、`poiNameSnapshot`、`checkedAt`、`verificationVersion`、`rewardSnapshot` | 不包含经纬度、轨迹和系统位置对象 |
| 积分变动 | `transactionId`、`sourceRecordId`、`delta`、`createdAt` | 每个打卡记录最多一条正向变动 |
| 徽章授予 | `awardId`、`badgeId`、`sourceRecordId`、`badgeSnapshot`、`awardedAt` | 使用获得时快照回看 |

`idempotencyKey` 由 `demoUserId + taskId` 生成，但持久化实现不得在日志中输出完整状态包。积分总数应由有效变动求和并与页面展示一致。

### 11.6 数据质量要求

- 可打卡 POI 的名称、坐标、半径、现场可达性、图片和简介须由指定负责人审核。
- 所有 POI 导入前检查唯一 ID、经纬度范围、GCJ-02 声明、必填字段、重复坐标和 URL。
- 每个 `checkinTaskId` 必须唯一关联一个 POI；每个活动任务引用的徽章必须存在且有效。
- 目标测试 POI 必须完成至少一次实地坐标核对，不能只依赖网页检索结果。
- 半径不得为零、负数或明显覆盖无关区域；采用默认 `200m` 时应记录原因。
- 图片和字体须明确使用权，远程资源域名需符合微信小程序要求。
- POI 或任务下线后不得新增打卡；历史快照仍可回看。

## 12. 能力与接口要求

### 12.1 总体原则

- 地图供应商确定为高德，但接入层次必须通过 Day 1 技术验证，不把微信原生 `map` 自动等同于高德底图。
- 高德 Web Service、客户端 SDK 和微信原生位置接口按不同安全和使用规则管理。
- 本期无 AI、路线生成或路径规划接口。
- POI 可来自审核后的本地数据或业务 API；两种来源使用同一数据模型。
- 位置请求和距离校验默认在客户端完成，只用于 POC，不构成生产级可信打卡服务。
- 所有失败必须返回可区分状态，不依赖模糊文本判断。

### 12.2 外部能力清单

| 能力 ID | 能力 | 输入 | 输出 | 优先级 | 说明 |
|---|---|---|---|---|---|
| CAP-MAP-01 | 地图显示与交互 | 中心点、缩放级别、marker | 地图视图和交互事件 | P0 | 采用技术验证通过的高德相关官方方案 |
| CAP-MAP-02 | 高德最小可用性检查 | Key、平台限制和测试请求 | 成功、错误码、额度/限制信息 | P0 | 不在界面或日志显示完整 Key |
| CAP-POI-01 | 获取分类 | 无或数据版本 | 分类列表 | P0 | 可由本地审核数据实现 |
| CAP-POI-02 | 获取 POI 列表 | 分类、标签或关键词 | POI 摘要列表 | P0/P1 | 搜索和组合筛选为 P1 |
| CAP-POI-03 | 获取 POI 详情 | `poiId` | POI 详情和打卡任务 | P0 | 不返回无效任务供前端猜测 |
| CAP-LOC-01 | 检查位置授权 | 无 | 授权及系统可用状态 | P0 | 区分拒绝和系统关闭 |
| CAP-LOC-02 | 获取当前位置 | `type=gcj02`、可用时请求高精度 | 经度、纬度、精度或明确错误 | P0 | 每次打卡发起新请求 |
| CAP-LOC-03 | 打开权限设置 | 用户主动操作 | 设置结果或生命周期恢复 | P0 | 以实际基础库能力为准 |
| CAP-STORE-01 | 保存本机状态 | 完整下一状态包 | 成功或失败 | P0 | 不保存精确位置 |

### 12.3 POI 业务 API 合同

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

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

建议至少区分 `OK`、`INVALID_ARGUMENT`、`NOT_FOUND`、`DATA_INVALID`、`MAP_SERVICE_ERROR`、`RATE_LIMITED`、`NETWORK_ERROR` 和 `INTERNAL_ERROR`。前端不把 HTTP 200 自动视为业务成功。

### 12.4 位置与打卡内部合同

距离判定函数应为无副作用的纯逻辑，输入和输出如下：

| 方向 | 字段 | 说明 |
|---|---|---|
| 输入 | `userPoint` | GCJ-02 经度、纬度和精度 |
| 输入 | `poiPoint` | 合法 GCJ-02 经纬度 |
| 输入 | `radiusMeters` | 正数打卡半径 |
| 输入 | `accuracyMaxMeters` | 最大允许精度值 |
| 输出 | `distanceMeters` | Haversine 原始计算值 |
| 输出 | `result` | `inside`、`outside`、`uncertain` 或 `invalid` |
| 输出 | `reasonCode` | 可诊断但不含精确位置的原因码 |

建议原因码包括 `PERMISSION_DENIED`、`LOCATION_DISABLED`、`LOCATION_TIMEOUT`、`LOCATION_ERROR`、`COORDINATE_INVALID`、`ACCURACY_MISSING`、`ACCURACY_TOO_LOW`、`OUTSIDE_RADIUS`、`BOUNDARY_UNCERTAIN`、`ALREADY_CHECKED`、`REWARD_CONFIG_INVALID` 和 `LOCAL_STORE_FAILED`。

### 12.5 高德凭证与安全要求

- 已提供凭证只以脱敏尾号 `...554f` 识别；不得把完整值写入 PRD、测试报告、提交记录、截图或普通日志。
- 🔵 **待技术确认**：Key 的产品类型、绑定平台、所属账号、允许的 API、额度、白名单、安全密钥或签名要求。
- 若该 Key 属于服务端 Web Service 凭证，小程序不得直接携带，应由受控业务服务代理调用。
- 若官方客户端 SDK 必须在包内使用客户端 Key，应创建或确认专用受限 Key，并接受客户端值可被观察的事实；不得复用服务端高权限凭证。
- Key 配置与页面业务代码分离；错误提示只显示错误码和脱敏标识。
- 生产或体验版启用微信合法域名校验；开发工具中的 `urlCheck=false` 不视为可交付配置。

### 12.6 不存在的本期接口

本 PRD 不定义或验收以下能力：AI 问答、AI 路线、路线请求、路线结果、polyline、道路路径、实时导航、服务端正式打卡、服务端积分账户、虚拟定位或测试坐标切换。研发不得因预留这些接口而延迟 P0。

## 13. 评估与埋点

### 13.1 事件清单

本期可使用本机测试日志或轻量埋点。若第三方统计 SDK 的隐私配置未完成，优先使用开发/测试记录，不为埋点引入新的 P0 依赖。

| 事件 | 触发时机 | 允许记录的关键属性 | 用途 |
|---|---|---|---|
| `poc_app_open` | 打开地图首页 | `sessionId`、应用版本、平台为 iOS | 记录测试会话 |
| `map_load_result` | 地图成功或失败 | 耗时、结果、脱敏错误码 | 地图稳定性 |
| `poi_data_result` | POI 数据成功或失败 | 数量、耗时、数据版本、来源 | 数据稳定性 |
| `poi_category_select` | 选择主分类 | `categoryCode`、结果数 | 浏览任务分析 |
| `poi_detail_view` | 打开详情 | `poiId`、入口 | 详情联动验证 |
| `location_permission_result` | 权限流程结束 | 授权状态、恢复入口结果 | 权限问题分析 |
| `location_request_result` | 定位请求结束 | 耗时、成功/失败、精度区间、原因码 | 定位稳定性 |
| `checkin_evaluation` | 距离判定结束 | `poiId`、`taskId`、`inside/outside/uncertain/invalid`、距离区间、精度区间、规则版本 | 判定验证 |
| `checkin_commit_result` | 本机事务结束 | `poiId`、`taskId`、成功/重复/失败、原因码 | 幂等和存储验证 |
| `badge_award` | 首次授予徽章 | `badgeId`、`taskId` | 奖励一致性 |
| `profile_view` | 进入个人中心 | 打卡数、徽章数、积分区间 | 本机回看验证 |
| `demo_reset` | 重置用户状态 | 成功/失败、旧记录数 | 演示恢复 |

### 13.2 禁止采集

- 不记录或上报精确经度、精确纬度、位置轨迹、系统位置对象和完整地址反查结果。
- 不记录完整高德 Key、微信密钥、请求签名、安全密钥或内部配置对象。
- 不记录微信身份、手机号、设备指纹或可用于跨应用识别个人的标识。
- 不记录没有必要的自然语言输入；本期没有 AI 文本输入场景。
- 测试截图和视频如可能暴露系统位置或凭证，应脱敏后保存。

### 13.3 区间化建议

为诊断定位问题而不保存精确值，可在内存中将距离和精度转换为区间后记录：

- 精度区间：`0-20m`、`21-50m`、`51-100m`、`>100m`。
- 距离与半径关系：`deep_inside`、`near_boundary`、`outside`，不记录原始米数。
- 定位耗时：`<1s`、`1-3s`、`3-10s`、`10-30s`、`timeout`。

### 13.4 POC 评估记录

每次正式验收至少记录：

| 字段 | 说明 |
|---|---|
| 测试编号 | 可追溯的会话编号 |
| 应用版本 | 构建版本或提交标识 |
| 设备环境 | iPhone 型号、iOS、微信版本、实际基础库 |
| 网络 | Wi-Fi/蜂窝及现场描述 |
| POI/任务版本 | 被测试点位、任务和规则版本 |
| 物理测试位置 | “场内安全点”“场外安全点”等描述，不在普通报告保存精确用户坐标 |
| 操作结果 | 成功、越界、不确定、拒绝、超时、重复或存储失败 |
| 耗时 | 地图、定位和完整任务耗时 |
| 观察 | 用户卡点、错误文案和环境异常 |

## 14. 非功能需求

### 14.1 性能

| ID | 要求 | 建议验收值 | 状态 |
|---|---|---|---|
| NFR-PERF-01 | 地图首屏可交互 | 实际 iOS 和约定网络下，20 次 P95 不超过 3 秒 | 产品细化 |
| NFR-PERF-02 | 分类切换 | 本地筛选不超过 300ms；网络请求显示局部 Loading | 产品细化 |
| NFR-PERF-03 | POI 详情 | 缓存命中不超过 1 秒；网络加载有超时和失败状态 | 产品细化 |
| NFR-PERF-04 | 位置请求 | 30 秒内完成或结束为超时；期间不重复发起 | 产品细化 |
| NFR-PERF-05 | 距离判定 | 有效位置返回后 100ms 内完成纯逻辑判定 | 产品细化 |
| NFR-PERF-06 | 本机提交 | 正常存储下 500ms 内完成或返回明确失败 | 产品细化 |
| NFR-PERF-07 | 图片 | 合理压缩、懒加载；单张失败不阻断文字和打卡 | 产品细化 |

### 14.2 兼容性

- 本期只验微信小程序在 iOS 的实际运行结果，不验收 Android、H5 或 App。
- 最低微信基础库和具体 iPhone 型号暂缓规定，不作为当前开工阻塞项。
- 每次测试必须记录实际 iPhone、iOS、微信和基础库版本；结论只覆盖实际组合。
- 位置授权、系统定位关闭、iOS“精确位置”关闭、从设置返回和杀进程恢复必须在实际 iOS 验证。
- 地图原生组件的层级、浮层、滚动和点击必须真机验证，不能以 H5 或开发者工具结果替代。
- 采用的 API 若存在基础库最低要求，研发须在 Day 1 列出并做能力检查；暂缓产品口径不等于可以忽略技术兼容条件。

### 14.3 安全与凭证

- 完整高德 Key、服务端 Key、安全密钥、微信密钥不得写入版本化文档、页面常量、错误提示或普通日志。
- 任何需要服务端权限的高德请求必须经受控服务代理，小程序不携带高权限凭证。
- 若使用官方客户端 Key，必须是专用受限类型，按高德官方能力配置平台限制和额度。
- 所有网络请求使用 HTTPS；体验版/正式版使用微信合法域名。
- 页面和测试工具不得显示堆栈、内部 URL、完整配置、Token 或签名材料。
- 代码提交前扫描常见凭证模式，发现疑似密钥按 S0 处理并立即轮换。

### 14.4 隐私与数据最小化

- 在用户点击打卡前说明位置用途，并按微信平台要求完成隐私声明和接口配置。
- 用户拒绝后仍可使用地图和 POI 浏览；不得反复无上下文弹出权限请求。
- 不持续定位、不后台定位、不采集轨迹，不以打卡为由申请无关权限。
- 精确位置只在当次内存计算中使用，默认不保存、不上传、不进入埋点。
- 本机存储只保存完成结果和奖励，不保存位置证据原文。
- 用户可通过个人中心重置 POC 状态；卸载、清缓存或换机的丢失风险需明确提示。

### 14.5 可用性与无障碍

- 地图分类和 marker 不只靠颜色区分，同时提供图标或文字。
- 主要按钮和文字有足够对比度，点击区域适合移动端触控。
- 加载、空、失败、拒绝、越界、不确定、重复和成功状态都有明确下一步。
- 位置错误文案说明“发生了什么”和“如何恢复”，避免只显示错误码。
- 成功与失败不能只用颜色表示，应配合文字和图标。
- 个人中心的本机数据边界在首次进入及相关说明处可见。

### 14.6 可靠性与一致性

- 定位、距离计算、奖励幂等和本机状态校验应作为独立可测试逻辑。
- 快速重复点击、应用切后台、页面返回和生命周期恢复不得重复发奖。
- 任何页面都不得直接修改积分总数，应通过统一奖励事务更新。
- 成功页、详情页和个人中心不得读取不同数据源造成状态不一致。
- 地图、高德或 POI 请求失败不得破坏已有本机资产。
- 本机状态带结构版本；发现损坏时停止打卡并提供可控重置。

### 14.7 可维护性与可观察性

- POI、打卡任务、定位结果、判定结果和奖励类型集中定义，禁止页面各自复制不同结构。
- 地图供应商适配与页面业务分离，业务状态不直接持有供应商私有对象。
- 高德 Key、阈值和数据源使用环境或配置层管理，不在多个文件写死。
- 关键操作携带 `requestId` 或会话 ID，日志只记录脱敏错误和区间值。
- Haversine、边界判断、幂等和本机状态迁移必须有单元测试。
- 演示数据与线上数据来源明确区分，但两者均不得绕过真实定位规则产生成功打卡。

## 15. 现有工程适配

### 15.1 已具备的工程基础

| 工程能力 | 当前事实 | 对 POC 的价值 |
|---|---|---|
| uni-app / 微信构建 | `package.json` 存在 `dev:mp-weixin` 和 `build:mp-weixin` | 可作为微信小程序前端脚手架 |
| Vue 3 + TypeScript | 工程采用 Vue 3、`script setup` 和 TS | 可建立 POI、定位与奖励类型 |
| Pinia 持久化 | 已接入 `pinia-plugin-persist-uni` | 可承载匿名本机 POC 状态 |
| 文件路由和分包 | 已配置 UniPages、Layouts 和示例分包 | 可按 POI、奖励和用户拆分页面 |
| 请求封装 | 已有网络请求、拦截和 Loading 基础 | 可改造为 POI 或地图业务请求 |
| UI 基础 | 已有 uview-plus 和 UnoCSS | 可快速实现移动端页面和状态 |
| 质量命令 | 已定义 type-check、lint 和 Vitest | 可验证关键纯逻辑和构建质量 |

### 15.2 当前工程现状与缺口

- 当前业务代码仍是 `unisave` 通用模板，首页请求 GitHub 示例接口。
- 应用名称仍为 `unisave`，生成配置中的微信 AppID 仍为 `testappid`；项目配置中的其他 AppID 不能未经确认直接当作本期正式身份。
- 代码中未发现高德地图、文旅地图页、POI、`getLocation`、距离校验、真实定位打卡、积分或徽章业务实现。
- 当前 Store 只有示例计数状态；虽然持久化插件已接入，但匿名资产模型尚未建立。
- 当前路由和布局为模板页面，不适合全屏地图和位置权限流程。
- 当前测试只覆盖通用工具，没有坐标、距离、边界、幂等和存储迁移测试。

因此，现有工程可复用的是技术骨架，而不是已经完成的文旅业务。用户提到的 AI、路径规划或其他人已完成能力不在当前工作区可核实范围内，且本期不做接入。

### 15.3 建议前端结构

```text
src/
├── pages/map/                   # 主包地图首页
├── pages-poi/                   # POI 详情分包
├── pages-rewards/               # 定位、打卡和奖励反馈
├── pages-user/                  # 匿名个人中心
├── components/map/              # marker、分类和 POI 摘要
├── components/location/         # 权限、定位状态和恢复提示
├── services/apis/               # POI 业务 API
├── services/map/                # 高德/地图显示适配
├── services/location/           # 微信定位封装
├── domain/checkin/              # 距离、判定、幂等和事务纯逻辑
├── stores/modules/              # map、poi、rewards、session
├── types/                       # POI、任务、定位和本机状态类型
└── fixtures/                    # 审核后的 POC POI/奖励数据
```

本期不建立 `pages-ai`、路线 Store、路线模型、polyline 服务或产品内位置模拟目录。

### 15.4 建议状态划分

| Store | 内容 | 是否持久化 |
|---|---|---|
| `map` | 中心、缩放、分类、筛选、选中 POI、地图错误 | 否 |
| `poi` | 分类、POI 字典、列表和详情缓存 | 可缓存；不作为用户资产 |
| `checkin` | 当前任务、权限、定位请求、判定和错误 | 否；精确位置只在内存 |
| `rewards` | 状态版本、匿名 ID、打卡、积分变动和徽章 | 是；统一状态包 |
| `session` | 会话 ID、应用版本和当前测试数据版本 | 会话级 |

### 15.5 工程改造要求

| ID | 改造项 | 验收要求 |
|---|---|---|
| ENG-001 | 替换模板应用身份 | 名称、标题和描述不再使用 `unisave`；AppID 使用经确认配置 |
| ENG-002 | 替换示例首页/API | 不再请求 GitHub；启动进入文旅地图 |
| ENG-003 | 建立四个业务页面 | 路由由项目既有 UniPages 机制生成，不手工维护生成文件 |
| ENG-004 | 高德接入 Spike | Day 1 验证 Key 类型、官方接入方式、错误码和 iOS 显示 |
| ENG-005 | 地图适配 | 封装地图、marker、视野和事件，页面不依赖供应商私有结构 |
| ENG-006 | 微信位置封装 | 按需权限、GCJ-02、超时、生命周期恢复和错误分类 |
| ENG-007 | 打卡领域逻辑 | Haversine、保守边界、幂等和本机事务与 UI 分离 |
| ENG-008 | 本机状态 | 单一版本化状态包，不保存精确位置；支持校验和重置 |
| ENG-009 | 凭证管理 | 完整 Key 不进入文档、硬编码、普通日志和公开提交 |
| ENG-010 | iOS 真机验证 | 地图、权限、精确位置、边界、重启和恢复均在实际环境验证 |
| ENG-011 | 删除范围外入口 | 无 AI、路线、导航和虚拟定位按钮或占位 |

## 16. 验收方案

### 16.1 核心演示脚本

下表定义一轮主流程。连续 10 轮稳定性测试要求每轮都返回与输入条件一致的可恢复状态且不错误发奖；其中场内首次定位的独立成功率按第 4.3 节另行统计，出现合法的 `uncertain` 或定位无效不等于应用流程阻断。

| 步骤 | 操作 | 预期结果 | 对应需求 |
|---|---|---|---|
| 1 | 打开微信小程序 | 匿名进入光明区地图，地图和 POI 加载成功 | MAP-001/002/003 |
| 2 | 切换一个分类 | marker 和结果状态同步更新 | MAP-005/009 |
| 3 | 点击 marker 并打开详情 | 摘要、详情和 `poiId` 一致，打卡状态正确 | MAP-007/008、POI-001/006 |
| 4 | 在明确范围外点击打卡并授权 | 获取新定位，判定范围外，不生成记录或奖励 | LOC-005、CHECK-003/005/012 |
| 5 | 到达场内安全点后再次打卡 | 新定位通过精度和保守范围规则，成功一次 | LOC-009、CHECK-004/009/010 |
| 6 | 立即重复操作 | 显示已完成，积分和徽章不变化 | CHECK-008/011 |
| 7 | 杀死并重新打开小程序 | 详情和个人中心仍显示一致的本机状态 | PROFILE-003/004/005 |
| 8 | 进入个人中心 | 显示匿名、本机边界、记录、积分和徽章 | PROFILE-001/002/003 |
| 9 | 二次确认重置 | 清除 POC 用户状态，保留 POI，回到未打卡 | PROFILE-007/008 |

### 16.2 位置与权限专项用例

| 用例 ID | 场景 | 前置条件/操作 | 预期结果 |
|---|---|---|---|
| QA-LBS-01 | 首次授权 | 权限未选择，点击打卡并同意 | 请求新位置；判定前不发奖 |
| QA-LBS-02 | 明确范围内 | `d + a <= r` | 打卡成功，奖励各发放一次 |
| QA-LBS-03 | 明确范围外 | `d - a > r` | 不打卡、不授奖，可重试 |
| QA-LBS-04 | 边界不确定 | 精度范围与半径边界重叠 | 提示不确定，不授奖，要求重试 |
| QA-LBS-05 | 用户拒绝权限 | 首次或再次拒绝 | 无死路；可返回、重试或打开设置 |
| QA-LBS-06 | 系统定位关闭 | iOS 定位服务关闭 | 给出系统级提示，不判成功 |
| QA-LBS-07 | 精确位置关闭 | iOS 返回精度超过阈值 | 提示开启精确位置或移动后重试 |
| QA-LBS-08 | 定位超时/报错 | 自动化测试中令位置封装请求悬挂至超时或返回失败；真机另测系统定位关闭 | 停止 Loading，不授奖，提供重试；模拟故障结果不计入真实定位成功率 |
| QA-LBS-09 | POI 坐标非法 | 打开无合法坐标的 POI | 隐藏可操作入口或显示暂不支持 |
| QA-LBS-10 | 快速重复点击 | 定位中连续点击多次 | 只存在一个有效请求和至多一个事务 |
| QA-LBS-11 | 重复打卡 | 已有相同幂等键 | 不重新发奖，资产不变化 |
| QA-LBS-12 | 设置返回 | 拒绝后到设置授权再返回 | 重新检查权限和位置，不沿用失败状态 |
| QA-LBS-13 | 杀进程恢复 | 成功后关闭并重开 | 记录、积分、徽章一致 |
| QA-LBS-14 | 地图失败 | 高德相关能力异常 | 不影响已保存资产；地图提供重试 |
| QA-LBS-15 | 重置状态 | 确认重置 | 只清用户状态，基础 POI 仍可浏览 |
| QA-LBS-16 | 本机提交失败 | 自动化测试令存储适配器返回失败 | 不显示成功；打卡、积分和徽章均不出现部分更新 |
| QA-LBS-17 | 本机状态损坏 | 注入结构非法、积分不一致或不支持的 `schemaVersion` | 停止发奖并提示数据异常；只有用户确认后才重置 |

故障注入通过测试替身或存储适配器完成，只存在于自动化测试环境，不提供生产构建中的隐藏开关，也不模拟用户位置。

### 16.3 距离计算与边界测试向量

实现必须使用固定向量执行自动化测试，避免不同开发者用肉眼地图距离验收公式。距离允许误差只用于浮点计算，不得改变边界比较符号。

| 用例 ID | 输入 | 预期 |
|---|---|---|
| QA-GEO-01 | 两点均为 `(113.930000, 22.750000)` | Haversine 距离为 `0m` |
| QA-GEO-02 | 点 A `(113.930000, 22.750000)`，点 B `(113.931000, 22.750000)` | 以 `R=6371008.8m` 计算为约 `102.54m`，允许误差 `±0.10m` |
| QA-GEO-03 | `d=80m`、`a=20m`、`r=100m` | `d+a=r`，结果为 `inside` |
| QA-GEO-04 | `d=80.001m`、`a=20m`、`r=100m` | `d+a>r` 且 `d-a<=r`，结果为 `uncertain` |
| QA-GEO-05 | `d=120m`、`a=20m`、`r=100m` | `d-a=r`，结果为 `uncertain`，不是 `outside` |
| QA-GEO-06 | `d=120.001m`、`a=20m`、`r=100m` | `d-a>r`，结果为 `outside` |
| QA-GEO-07 | `accuracy` 为 `0`、负数、缺失、`NaN` 或无限值 | 结果为 `invalid`，不得进入距离成功判定 |
| QA-GEO-08 | 半径为 `0`、负数、`NaN` 或无限值 | 配置无效，入口不可用或结果为 `invalid` |

### 16.4 隐私与凭证专项

| 用例 | 预期 |
|---|---|
| 检查版本化 Markdown 与源码 | 不存在已提供高德 Key 的完整值 |
| 检查构建产物与网络调用 | 服务端高权限 Key 不在小程序包；客户端 Key 类型及限制有记录 |
| 检查本机持久化状态 | 不存在经纬度、轨迹或系统位置对象 |
| 检查普通日志和埋点 | 不存在完整 Key、精确位置或微信身份 |
| 拒绝定位后继续浏览 | 地图和 POI 仍可用，不强迫授权 |
| 清除 POC 状态 | 用户可清除本机记录、积分和徽章 |

### 16.5 测试位置要求

- 设任务最大允许精度为 `a_max`，现场测距附加容差为 `m`；POC 默认建议 `m=20m`。
- 范围内测试点应满足 `物理预估距离 <= 半径 - a_max - m`，即距离边界至少保留 `a_max + m` 的内侧余量。
- 范围外测试点应满足 `物理预估距离 > 半径 + a_max + m`，即超过边界多于 `a_max + m`。
- 例如 `a_max=100m`、`m=20m`、半径 `200m` 时，场内测试点应距离 POI 不超过 `80m`，场外测试点应距离 POI 大于 `320m`。
- 若半径或现场条件无法提供上述余量，应选择其他测试点或重新审核半径，不把边界波动当成产品缺陷或成功证据。
- 真实 P0 验收必须在实际 iOS 真机和真实物理位置执行。微信开发者工具、Xcode 或其他外部位置模拟可用于开发调试，但结果标记为“模拟环境”，不计入真实定位验收成功率。
- 本期不建设小程序内虚拟定位能力。

### 16.6 缺陷等级

| 等级 | 定义 | 演示前要求 |
|---|---|---|
| S0 阻断 | 无法启动、主流程中断、崩溃、范围外错误授奖、重复发奖、精确位置或密钥泄露 | 必须为 0 |
| S1 严重 | 地图/POI 错联、权限无法恢复、本机资产不一致、成功状态无法保存 | 必须为 0 |
| S2 一般 | 非核心筛选、文案或特定环境问题，有明确替代路径 | 有处理结论 |
| S3 轻微 | 不影响操作和理解的视觉问题 | 可记录后修复 |

### 16.7 完成定义

单项 P0 同时满足以下条件才视为完成：

- 产品规则、主状态和错误恢复已实现，定位失败不产生成功结果。
- 微信小程序构建通过，并在记录的 iOS 环境完成对应真机用例。
- TypeScript 和 lint 通过；距离、边界、幂等和本机状态逻辑有自动化测试。
- 不包含模板名称、GitHub 示例请求、范围外入口、完整高德 Key 或明显占位文案。
- POI、任务和奖励数据通过校验，接口/配置文档与实际一致。
- 本机持久化不包含精确位置，成功/重复/重启/重置状态一致。
- 核心脚本能从统一初态重复执行，实际结果有测试记录。

## 17. 交付物与计划

### 17.1 交付清单

| 交付物 | 必须内容 | 优先级 |
|---|---|---|
| 产品文档 | 评审后的 V1.1 PRD、范围、决策和待技术确认项 | P0 |
| UI 交付 | 四类页面、页内浮层、权限及全部异常状态 | P0 |
| 前端源码 | `map-gm-app` 内可构建的地图、POI、打卡和本机资产实现 | P0 |
| POI/配置数据 | 审核 POI、分类、坐标、半径、任务、积分和徽章 | P0 |
| 高德接入记录 | Key 类型、接入方式、受限配置、额度和最小调用结果；仅脱敏记录 | P0 |
| 位置规则说明 | 权限、坐标系、距离公式、阈值和结果状态 | P0 |
| 测试材料 | 用例、实际环境、结果、缺陷和已知限制 | P0 |
| 隐私检查 | 位置用途、本机存储字段和敏感信息扫描结果 | P0 |
| 构建说明 | 环境、命令、AppID、合法域名和安全配置方法，不含完整凭证 | P0 |
| 演示说明 | 初态、实地测试点说明、重置和异常恢复方式 | P0 |

### 17.2 Day 0/Day 1 准入

7 天排期以以下输入可用为前提：

- P0 范围和“AI/路径/虚拟定位不做”已记录，本版已完成。
- 微信 AppID、开发成员、位置接口及隐私配置有负责人。
- 高德凭证可用于技术验证；完整值通过安全渠道配置，不进入文档。
- 至少一个可实地测试 POI 的 GCJ-02 坐标、半径、任务和奖励已审核。
- iOS 真机可在开发周期内进行现场或等价物理位置测试。
- Logo、主题色、POI 图片和徽章素材至少有可用版本。

若 Day 1 无法取得真实位置权限或没有可验证 POI，真实定位 P0 无法验收。不得自动降级为模拟打卡后仍宣称达到本 PRD；应记录为阻塞并重新协商范围或交付日期。

### 17.3 7 天执行计划

| 日期 | 工作重点 | 当日出口条件 |
|---|---|---|
| Day 1 | 冻结 V1.1；清理模板；验证高德 Key 类型/接入；确认微信位置能力、坐标和半径 | 地图与定位技术 Spike 有结论，POI/任务合同冻结 |
| Day 2 | 地图首页、POI 数据、marker、分类；iOS 地图真机验证 | 目标 iOS 显示审核 POI，坐标抽检通过 |
| Day 3 | POI 摘要/详情、打卡资格、位置权限及错误恢复 | 地图到详情完成；授权、拒绝和设置返回可测 |
| Day 4 | 新定位请求、Haversine、精度/时效/边界规则和纯逻辑测试 | 范围内、外、不确定和无效状态可重复验证 |
| Day 5 | 幂等打卡、积分、徽章、个人中心和统一本机状态 | 首次/重复/重启/重置流程端到端完成 |
| Day 6 | UI 完善、隐私/凭证检查、iOS 实地与异常测试、5 人任务测试 | 核心指标有记录，S0/S1 清零计划明确 |
| Day 7 | 回归、性能、文档、构建、交付和彩排 | 完成定义满足，风险和已知限制归档 |

### 17.4 人员职责

| 角色 | 主要职责 |
|---|---|
| 产品/需求负责人 | 维护范围、确认阈值与指标、组织评审和验收 |
| 内容负责人 | 审核 POI、GCJ-02 坐标、半径、图片和开放信息 |
| 前端开发 | uni-app 页面、高德适配、微信定位、状态和真机验证 |
| 技术负责人 | 确认高德接入、安全配置、AppID/域名和位置能力边界 |
| UI 设计 | 四类页面、地图浮层、权限和异常状态、徽章素材 |
| 测试负责人 | 实地位置用例、设备环境、缺陷、隐私和回归记录 |

若没有独立测试人员，产品和开发须在 Day 6-7 明确交叉验收，不能由同一实现者单独认定所有定位边界用例通过。

## 18. 依赖与风险

### 18.1 外部依赖

| 依赖 | 必需内容 | 未就绪影响 | 建议负责人 |
|---|---|---|---|
| 微信小程序 | AppID、开发权限、位置接口、隐私声明、合法域名 | 无法真机取得真实定位或访问 API | 项目方技术接口人 |
| 高德能力 | 正确 Key 类型、所属账号、额度、白名单/平台限制及官方接入方案 | 地图不能稳定运行 | 技术负责人 |
| POI 数据 | 审核样本、GCJ-02 坐标、分类和图片 | 地图与打卡无可信目标 | 内容负责人 |
| 打卡规则 | 每个任务的半径、有效期、积分和徽章 | 无法形成一致判定与奖励 | 产品负责人 |
| iOS 实测 | 可用真机和可合法到达的场内/场外测试点 | 只能完成开发调试，不能完成 P0 验收 | 测试负责人 |
| 设计与品牌 | Logo、色彩、占位图和徽章 | 只能使用临时素材 | UI/品牌负责人 |

### 18.2 风险与应对

| ID | 风险 | 概率 | 影响 | 应对措施 | 触发条件 |
|---|---|---|---|---|---|
| R-01 | 7 天范围重新加入 AI、路线或长期功能 | 高 | 高 | 以 P0/P1/范围外清单控制；新增 P0 必须调整工期或替换范围 | 出现范围外页面或接口要求 |
| R-02 | 已提供高德 Key 类型与接入方式不匹配 | 中 | 高 | Day 1 最小调用验证；必要时申请正确的专用受限 Key | 官方调用返回平台/签名/权限错误 |
| R-03 | 完整 Key 被写入小程序、文档或日志 | 中 | 高 | 安全配置、脱敏、扫描；发现即按 S0 并轮换 | 扫描或截图发现完整凭证 |
| R-04 | POI 坐标或半径错误导致误判 | 高 | 高 | 实地核对、统一 GCJ-02、配置校验、场内外安全余量 | 首次场测与预期不符 |
| R-05 | iOS 精确位置关闭或环境遮挡导致精度不足 | 高 | 中 | 显示精度不足、引导开启或移动，不用放宽规则掩盖 | 精度超过配置阈值 |
| R-06 | 客户端打卡被误解为生产级防作弊 | 中 | 高 | 文档和页面说明 POC 边界；正式版采用服务端校验和风控 | 提出权益兑换或可信审计要求 |
| R-07 | 本机数据因清缓存、卸载或换机丢失 | 高 | 中 | 明确提示；本期不承诺恢复；正式版建设账户与服务端资产 | 用户更换环境后要求找回 |
| R-08 | 快速点击或存储失败导致重复/部分发奖 | 中 | 高 | 请求互斥、幂等键、单一状态包和故障测试 | 积分、徽章与记录不一致 |
| R-09 | 地图原生组件在 iOS 浮层或点击异常 | 中 | 高 | Day 2 真机验证专用布局，不依赖 H5 结论 | 真机遮挡、失焦或事件失效 |
| R-10 | 无游客证据却将 POC 当作需求验证完成 | 高 | 中 | 5 人任务测试；区分技术、可用性和业务价值证据 | 只完成演示，无用户记录 |
| R-11 | 没有真实物理测试点，改用虚拟位置冒充验收 | 中 | 高 | 明确模拟环境不计 P0；缺少现场条件时报告阻塞 | 验收记录来自开发工具或模拟器 |
| R-12 | 暂不定机型和基础库被理解为全面兼容 | 中 | 中 | 每次记录实际环境，结论仅覆盖实际组合 | 对外宣称“支持所有 iOS” |

### 18.3 四类产品风险

| 风险类型 | 当前最弱证据 | POC 内验证方式 |
|---|---|---|
| 价值 | 没有游客访谈或互动意愿数据 | 5 人任务测试及简短访谈，不以项目方喜欢代替游客价值 |
| 可用性 | 地图、权限、定位错误和本机边界尚无设计验证 | 实际 iOS 任务测试和错误恢复用例 |
| 可行性 | 高德 Key 类型、地图方案、微信位置权限和实地精度尚未联调 | Day 1/2 Spike 和 Day 4/6 实地测试 |
| 业务可行性 | 正式数据责任、账号、反作弊和长期运营未确定 | POC 记录差距，不宣称具备正式运营条件 |

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

### 19.1 已确认决策

| 原问题 | 决策 | 状态 | 影响 |
|---|---|---|---|
| Q-01 | 7 天交付为 POC，不是正式版本 | 已解决 | 全部范围以验证为目标 |
| Q-02 | 目标端为微信小程序，只在 iOS 验证 | 部分解决 | 最低基础库和具体机型暂缓 |
| Q-05 | 地图供应商为高德，凭证已提供 | 部分解决 | Key 类型、接入方式和安全配置待技术确认 |
| Q-07 | AI 本期不处理 | 已解决并后置 | 无 AI 页面、接口、指标和验收 |
| Q-08 | AI 服务、知识资料和额度本期不考虑 | 已解决并后置 | 不作为本期依赖 |
| Q-09 | 路径规划本期不处理 | 已解决并后置 | 无路线、polyline 和导航 |
| Q-10 | 打卡必须使用真实定位 | 已解决 | 定位失败不得模拟成功或发奖 |
| Q-11 | 匿名使用，个人中心只保存本机数据 | 已解决 | 无登录、无服务端资产、无跨设备同步 |
| Q-12 | 演示对象、签字人、网络和投屏暂不考虑 | 暂缓 | 不作为当前阻塞项 |

### 19.2 开发前需关闭的技术项

这些不是产品方向选择，而是已定范围能否实现的技术准入项。

| ID | 技术项 | 推荐动作 | 影响 | 截止 |
|---|---|---|---|---|
| T-01 | 已提供高德 Key 的类型、账号、允许 API、额度和限制 | 用安全渠道配置并完成官方最小调用 | 地图在线能力 | Day 1 |
| T-02 | 高德地图在微信小程序中的显示/服务接入层次 | 明确原生 `map`、官方 SDK 或 Web Service 各自职责 | 地图架构与安全 | Day 1 |
| T-03 | 微信 AppID、位置接口和隐私配置 | 实际 iOS 完成首次授权、拒绝和设置恢复 | 真实定位 | Day 1 |
| T-04 | 目标 POI 坐标、半径和实地审核 | 统一 GCJ-02，确认场内/外安全测试点 | 打卡正确性 | Day 1 |
| T-05 | `100m` 精度阈值、`30s` 时限和 `200m` 默认半径 | iOS 场测后确认或更新配置/文档 | 边界判定 | Day 2 |
| T-06 | 当前工程中应使用的正式/体验版微信 AppID | 由项目方确认，不默认采用模板或其他配置值 | 构建与真机 | Day 1 |

### 19.3 数据与设计待确认

| ID | 问题 | 推荐默认项 | 优先级 |
|---|---|---|---|
| Q-03 | 四路由 + 浮层是否接受，不按“约 10 页”验收？ | 接受四个业务路由，不凑页 | P0 评审 |
| Q-06 | POC POI 数量、分类、图文来源和审核人是谁？ | 先锁定可实地审核的代表性样本 | P0 输入 |
| Q-13 | 是否需要搜索和组合筛选？ | P0 只做分类；有数据和余量再做 | P1 |
| Q-16 | 电话、预约、分享等哪些真实可用？ | 未验证的入口不显示 | P1 |
| Q-17 | 每个任务的积分、徽章和半径是多少？ | 配置化，不在页面写死 | P0 输入 |
| Q-18 | 最小品牌规范和设计审核人是谁？ | Day 1 提供 Logo、主题色和徽章素材 | P0 输入 |
| Q-19 | 第 4.3 节的指标阈值是否接受？ | 评审后形成验收表 | P0 评审 |

### 19.4 暂缓且不阻塞本期

- 最低微信基础库版本和具体 iPhone 型号。
- 最终演示对象、验收签字人、演示网络和投屏方式。
- 产品内虚拟定位测试能力。
- AI、路径规划及其他人员已完成能力的后续接入。

“暂缓”不等于已验证。若实际开发所用 API 有最低基础库要求，研发仍须记录该技术事实；如果未来要对外承诺兼容范围，需要重新建立测试矩阵。

### 19.5 决策日志

| 日期 | 决策 | 理由 | 来源 |
|---|---|---|---|
| 2026-07-29 | 前端采用当前 `map-gm-app` uni-app 工程 | 用户明确指定 | U1 |
| 2026-07-29 | 7 天为 POC，微信小程序仅 iOS 验证 | 用户明确指定 | U1 |
| 2026-07-29 | 地图使用高德 API，凭证已提供 | 用户明确指定 | U1 |
| 2026-07-29 | AI 和路径规划移出本期 | 用户明确指定 | U1 |
| 2026-07-29 | 打卡必须真实定位，产品内虚拟定位本期不开发 | 用户明确指定 | U1 |
| 2026-07-29 | 匿名使用，个人中心仅保存本机数据 | 用户明确指定 | U1 |
| 2026-07-29 | Q-12 暂缓 | 用户明确指定 | U1 |

## 20. 后续需求池

### 20.1 正式一期：可靠地图与到点互动

- 完整 POI 管理、CMS、批量导入、审核、版本和内容下线。
- 正式用户身份、账号注销、跨设备同步和服务端用户资产。
- 服务端打卡校验、幂等、积分流水、补偿、审计和基础反作弊。
- 更完整搜索、官方推荐、收藏、评价和运营统计。
- 多设备和最低基础库兼容矩阵，包括 Android。
- 正式隐私政策、安全测试、监控、告警和长期运维。

### 20.2 AI 与路径规划

- AI 文旅问答、知识库、引用溯源、内容安全和多轮上下文。
- 基于审核 POI 的路线生成、站点顺序、约束校验和结果解释。
- 高德路径规划、道路级 polyline、距离/时长和外部导航。
- 实时开放状态、路况或客流驱动的路线调整。
- 语音导览、多语种、港澳与入境游客适配。

AI 与路径规划进入后续版本时必须独立定义 PRD、接口、指标、数据责任和验收，不从 V1.0 直接恢复旧范围。

### 20.3 测试与定位增强

- 产品外部的受控测试方案、测试账号、自动化环境和证据标记。
- 若确有业务需要，再评估产品内虚拟定位测试能力；必须与用户界面、生产构建和正式打卡完全隔离。
- 服务端位置风险识别、速率限制、异常轨迹、设备风险和人工申诉。

### 20.4 运营与交易

- 活动、优惠券、券包、到店核销和积分商城。
- 商户、商品、库存、订单、微信支付、退款、分账和对账。
- 游记、评论、UGC 审核、挑战、排行榜和分享增长。
- 商户后台、运营后台、监管端和数据大屏。

## 21. 需求追溯

### 21.1 附件到本期范围

| 需求主题 | S1 | S2 | S3 | V1.1 处理 |
|---|---|---|---|---|
| 地图 + POI | POC 核心 | 详细功能页 | 一期数据底座 | MAP/POI P0 |
| 分类与筛选 | 概要 | 分类、标签、榜单 | 内容运营方向 | 主分类 P0；组合筛选 P1；榜单需官方配置 |
| AI 问答/路线 | POC 原始内容 | 路线功能 | 三期 AI | 本期明确排除，进入后续独立 PRD |
| 路径/导航 | 路线展示 | 地图路线 | 正式导览 | 本期明确排除 |
| 打卡 | 模拟打卡 | 真实定位表达 | 正式互动体系 | 真实定位 P0；模拟打卡被最新决策替换 |
| 积分/徽章 | 演示反馈 | 积分和徽章 | 正式会员资产 | 本机 POC 资产 P0；正式账户后续 |
| 个人中心 | POC 页面 | 隐含会员资产 | 正式用户中心 | 匿名、本机回看 P0 |
| 游记/分享 | 未明确 | 功能页 | 增长方向 | P1/后续 |
| 交易/后台 | 不在 POC | 部分扩展 | 三期完整方案 | 本期排除 |
| 多语种/港澳 | 不在 POC | 未重点定义 | 长期方向 | 后续 |

### 21.2 最新决策到需求

| 用户决策 | 落点 |
|---|---|
| 7 天 POC | 1、2.3、4、6.4、17、18 章 |
| 微信小程序，仅 iOS 验证 | 2.3、4.3、14.2、16、17 章 |
| 暂不定最低基础库和机型 | 14.2、19.1、19.4 |
| 高德 API 与已提供凭证 | 1、7.2、9.1、12.2/12.5、18、19 章 |
| AI 与路径规划不处理 | 1、3.2、6.3、8、12.6、17、20.2 |
| 打卡必须真实定位 | 5.3、6.1、9.3/9.4、10.2、16.2 |
| 产品内虚拟定位不开发 | 6.3、9.3、16.5、19.4、20.3 |
| 匿名使用 | 5、7、9.6、10.3/10.4、11.5 |
| 个人中心只保存本机 | 6.4、9.6、10.4、11.5、14.4 |
| Q-12 暂缓 | 19.1、19.4 |

### 21.3 需求覆盖矩阵

| 目标 | 主要需求 | 核心验收 |
|---|---|---|
| OBJ-01 地图与 POI | MAP-001 至 MAP-011、POI-001 至 POI-010 | 核心脚本 1-3、地图性能 |
| OBJ-02 信息和资格 | POI-001 至 POI-010、BR-POI-* | QA-LBS-09、数据校验 |
| OBJ-03 真实定位 | LOC-001 至 LOC-014、CHECK-001 至 CHECK-007 | QA-LBS-01 至 08、12 |
| OBJ-04 奖励和持久化 | CHECK-008 至 014、REWARD-*、PROFILE-* | QA-LBS-10/11/13/15 |
| OBJ-05 匿名流程 | PROFILE-001/002、BR-REWARD-01、BR-STORE-* | 核心脚本全程无登录 |
| OBJ-06 风险输出 | DEMO-*、13.4、17.1、18、19 | 测试材料和已知限制 |

## 22. PRD 自检

### 22.1 最强部分

本期范围、真实定位判定、奖励幂等和本机数据边界较清晰。AI、路径规划、模拟或虚拟定位、多端和正式资产已经从主流程、页面、数据、接口、指标、排期和验收同步移除；定位失败不会通过“演示兜底”伪装为成功。

### 22.2 最弱部分

用户价值证据、高德接入技术结论和现场数据仍最弱。附件没有游客访谈或业务基线；已提供 Key 的类型、官方接入层次、目标 POI 坐标和实际 iOS 定位精度尚未验证。V1.1 因此是完整评审稿，但技术阈值和在线能力仍需 Day 1/2 实测确认。

### 22.3 高风险假设

| 假设 | 错误时影响 | 验证方式 |
|---|---|---|
| 已提供的高德凭证支持目标小程序接入方式 | 地图 P0 无法按期在线运行 | Day 1 官方最小调用和安全配置核对 |
| 目标 POI 可统一为准确 GCJ-02 坐标 | 距离判定出现系统性偏差 | 数据校验和实地抽检 |
| 默认 `200m` 半径适合未单配的 POC 点位 | 可能覆盖无关区域或导致现场难以成功 | 场地审核和场内/外安全点测试 |
| `100m` 精度阈值和 `30s` 时限适合目标 iOS 环境 | 成功率过低或误放行风险增加 | Day 1/2 iOS 样本测试后校准 |
| 本机单状态包能够满足 POC 重启一致性 | 可能发生部分写入或损坏 | 故障注入、重复和重启测试 |
| 地图加到点奖励对游客有理解价值 | POC 可运行但不值得正式建设 | 5 人任务测试和访谈 |

### 22.4 自检结果

| 检查项 | 结果 |
|---|---|
| 问题、用户、方案和指标是否一致 | 一致，均聚焦地图发现和真实定位打卡 |
| P0 是否出现 AI 或路径规划 | 否 |
| 页面、接口和数据模型是否残留路线能力 | 否 |
| 是否仍允许模拟打卡作为失败兜底 | 否 |
| 是否把产品内虚拟定位列为本期能力 | 否 |
| 定位失败、越界和不确定是否禁止发奖 | 是 |
| 匿名、本机数据是否贯穿页面和规则 | 是 |
| iOS 验证是否被误写为全面兼容 | 否 |
| 高德完整 Key 是否写入文档 | 否，仅记录脱敏尾号 |
| 未决项是否区分产品决策、技术确认和暂缓 | 是 |

### 22.5 评审前首要动作

技术负责人应在 Day 1 完成高德 Key 类型/官方接入方式与微信真实定位权限的双 Spike，同时由内容负责人锁定至少一个可实地测试的 GCJ-02 POI、半径和奖励。若任一项失败，不得回退为虚拟或模拟打卡后仍按本 PRD 验收，应明确报告阻塞并重新决定范围或工期。

本 PRD 经产品范围评审、Day 1 技术准入和测试阈值确认后，可作为 7 天 POC 的研发与验收基线；它不构成正式版本上线承诺。