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

| 文档版本 | 创建日期 | 文档状态 | 版本简述 |
|---|---|---|---|
| V1.0 | 2026-07-29 | 评审稿 | 汇总三份附件并结合现有 `map-gm-app` uni-app 工程形成 POC 研发需求 |

| 项目项 | 内容 |
|---|---|
| 产品名称 | 光明区文旅全域地图及 AI 导览 POC |
| 产品形态 | 建议为微信小程序方向的可运行演示版本，待 Q-02 确认 |
| 前端工程 | `map-gm-app` |
| 已确认前端框架 | uni-app + Vue 3 + TypeScript |
| 原始工期 | 7 天 |
| 原始资源 | 前端 1 人、后端/AI 1 人、UI 设计支持 |
| 当前评审目标 | 锁定 POC 边界、演示过程、数据/API 合同和验收口径 |

## 目录

- [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 工程，制作一个用于客户演示和能力验证的光明区智慧文旅小程序 POC。POC 以全域地图为入口，展示已审核的文旅 POI；游客可查看点位详情、输入游玩偏好、获得 AI 生成的路线、在地图查看路线，并完成模拟打卡以获得积分和徽章。

三份附件的范围并不相同。最新 POC 方案约束为 7 天和约 10 个页面，而两份 PPT 同时描述了一期到三期的正式产品、商户交易、积分商城、优惠券、运营后台及多语种 AI 等能力。本评审稿建议将当前交付限制为“可稳定演示的一条主流程”，把交易和正式运营能力放入后续需求池；本期只保留必要的数据标识和接口扩展方向，不承诺实现后续功能。

当前最大的交付风险不是前端框架，而是开工输入尚未锁定：正式微信 AppID、地图服务商和 Key、审核后的 POI 样本、坐标系、AI API 与知识资料、路线结果合同、真实或模拟打卡边界。若这些输入不能在开发前准备完成，7 天只能交付本地静态演示，无法承诺稳定的真机在线演示。

## 2. 文档说明

### 2.1 信息标记

| 标记 | 定义 | 处理要求 |
|---|---|---|
| 已确认 | 用户明确指定，或已存在于当前工程 | 作为本版约束执行 |
| 资料事实 | 三份附件中的原始表达 | 保留来源，但仍需验证真实性和可行性 |
| 产品细化 | 为达到可开发、可测试目的而新增的规则 | 评审确认后转为正式需求 |
| 🔶 **假设** | 资料缺失时用于形成初稿的临时判断 | 开发承诺前必须确认 |
| 🔵 **待确认** | 会改变范围、技术方案、工期或验收的事项 | 按第 19 章关闭 |

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

| 编号 | 资料 | 用途 | 优先级 |
|---|---|---|---|
| S1 | `光明区文旅全域地图及AI导览POC建设方案.docx` | 定义当前 POC、页面类型、7 天计划和演示过程 | 1 |
| S2 | `文旅小程序三期规划方案202607091517.pptx` | 补充地图、POI、AI、路线和互动功能 | 2 |
| S3 | `文旅小程序三期规划方案20260709.pptx` | 提供问题背景、三期路线、运营及项目风险 | 3 |
| C1 | 当前 `map-gm-app` 工程 | 定义可复用的前端技术基础和现状 | 已确认工程事实 |
| U1 | 用户补充说明 | 指定当前 uni-app 工程为开发框架 | 最高 |

🔶 **假设**：冲突时采用 `U1/C1 > S1 > S2 > S3`。附件中未被 S1 纳入的长期功能不会因为在 PPT 出现而自动成为 7 天 POC 的交付范围；该顺序需在范围评审中确认。

### 2.3 产品边界

- 本文档描述 POC 产品行为、前端适配、前后端能力合同和验收条件。
- 本文档不指定后端必须使用 Node.js 或 Python，也不指定必须使用 JSON 或 SQLite；S1 将它们写为候选方案。
- 本文档不包含像素级视觉规范，最终样式以确认后的设计稿为准。
- 本文档不等同于生产系统安全设计、等保方案、正式运营方案或采购合同。
- 本版为评审稿；第 19 章 P0 问题关闭后，才能作为 7 天开发基线。

### 2.4 术语

| 术语 | 定义 |
|---|---|
| POC | Proof of Concept，用最小可运行范围验证关键能力，不等同于生产上线版本 |
| POI | Point of Interest，地图上的景点、场馆、餐饮、住宿、活动或公共设施点位 |
| AI 路线 | 根据用户偏好，从已审核 POI 集合中生成的有序游玩点位及说明 |
| 路线几何 | 地图用于绘制路线的坐标序列；可能是 POI 连线，也可能是地图服务提供的道路级路径 |
| 模拟打卡 | 不依赖真实定位和正式用户账户，由演示操作触发的打卡结果 |
| 演示用户 | POC 本机上的匿名状态，不代表正式微信会员 |
| 降级结果 | 在线 AI 或地图服务不可用时，用预置路线或静态数据保证演示可继续 |

## 3. 背景与问题

### 3.1 背景

**资料事实**：光明区希望提升文旅资源数字化展示和游客服务水平，并通过“地图 + 点位 + 线路 + 互动”验证未来文旅小程序方向。S3 还提出光明区具备科学、生态、美食、人文、赛事及港澳联动等文旅资源，但本 POC 不负责验证这些市场数据或运营结论。

### 3.2 用户问题

| 问题 | 用户影响 | 产品应对 | 证据状态 |
|---|---|---|---|
| 文旅信息分散、内容繁杂 | 游客筛选信息成本高 | 用地图、分类和详情统一呈现样本 POI | 来自 S3 的方案判断，缺少访谈或行为数据 |
| 缺少本地化、个性化行程建议 | 游客需要自行组合景点和时间 | 通过偏好输入生成 AI 路线 | 来自 S1/S2/S3，缺少用户验证 |
| 信息、路线、导航和互动分离 | 从决策到行动需要切换工具 | 将 POI、路线地图和打卡放在同一演示过程 | 来自 S1/S3，POC 仅验证流程连贯性 |
| 产品方向缺少可感知样例 | 决策方难以评估后续投入 | 用可运行 Demo 演示地图、AI 和互动能力 | 来自 S1 的明确 POC 目的 |

目前没有用户访谈、使用数据、竞品研究或现有产品漏斗数据。因此“游客确实需要这些能力”仍是待验证假设，本 POC 首先验证可用性和方案理解度，不应宣称已验证市场需求。

### 3.3 问题陈述

**产品细化**：对于计划在光明区短时游玩的游客，现有资料假设他们难以在分散信息中快速找到合适地点，并将地点组合成符合时间和兴趣的可执行路线。对于项目决策方，缺少一个可运行样例来判断全域地图、AI 路线和打卡互动是否值得进入正式建设。因此需要用 POC 验证一条从发现 POI 到生成路线再到模拟打卡的主流程。

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

### 4.1 产品目标

| ID | 目标 | 本期验证方式 |
|---|---|---|
| OBJ-01 | 验证地图承载光明区样本文旅资源的可行性 | 在微信小程序真机展示地图、分类和 POI 联动 |
| OBJ-02 | 验证 POI 数据能支持游客做基本判断 | 展示标准字段、缺失值和详情动作 |
| OBJ-03 | 验证 AI 能把用户偏好转换为可展示路线 | 对约定提示词生成只包含审核 POI 的结构化结果 |
| OBJ-04 | 验证路线能在地图上正确表达 | 显示有序站点、marker 和路线几何 |
| OBJ-05 | 验证互动激励的演示效果 | 模拟打卡后稳定展示积分和徽章，并在个人中心可回看 |
| OBJ-06 | 为后续是否进入正式一期提供事实依据 | 记录任务完成、失败原因和演示反馈 |

### 4.2 史诗假设

🔶 **假设**：如果为第一次到访光明区、时间有限的游客提供“地图探索 + 已审核 POI + AI 路线 + 模拟打卡”能力，那么他们能够在不离开小程序的情况下完成从发现地点到获得可执行行程的过程；项目决策方也能据此判断正式建设的价值和主要风险。

本假设通过两类低成本验证完成：

1. 使用约定的 10 组路线提示词执行端到端演示，记录生成成功率、错误类型和路线合理性。
2. 邀请 5 名未参与设计的测试者完成指定任务，记录完成率、耗时和主观评分。

### 4.3 POC 成功标准

附件没有量化目标。下表均为 **产品细化** 的评审建议，不是资料事实。

| 类型 | 指标 | 建议目标 | 测量时点 |
|---|---|---|---|
| 主指标 | 端到端演示成功率 | 约定设备和网络下，核心演示脚本连续执行成功率 100% | Day 7 |
| AI | 路线生成成功率 | 10 组约定提示词中不少于 9 组返回可解析路线 | Day 6-7 |
| AI | POI 真实性 | 路线站点 100% 可映射至审核 POI `id` | 每次生成 |
| 数据 | POI 必填字段完整率 | 100%；非必填字段按缺失规则展示 | 数据导入后 |
| 数据 | 坐标抽检准确率 | 抽检 POI 在目标地图上的位置准确率不低于 98% | Day 2-3 |
| 可用性 | 核心任务完成率 | 5 名测试者中至少 4 名无需指导完成“找点位 → 生成路线 → 打卡” | Day 6 |
| 可用性 | 演示体验评分 | 测试者对流程清晰度平均评分不低于 4/5 | Day 6 |
| 性能 | 地图首屏可交互时间 | 约定真机及网络下不超过 3 秒 | Day 6-7 |
| 性能 | AI 路线返回时间 | P95 不超过 10 秒；超时后能切换预置路线 | Day 6-7 |
| 质量 | 阻断级缺陷 | 0 个 | 演示前 |

### 4.4 决策门槛

POC 结束后不直接等同于正式立项。应按以下结果做判断：

- 通过：主流程稳定，AI 结果可控，地图和数据风险可接受，可进入正式一期需求与技术设计。
- 有条件通过：主流程可演示，但 AI、地图、数据或权限仍依赖人工兜底；先完成专项验证再立项。
- 不通过：路线不可控、关键数据无法获得、真机能力不稳定，或测试者无法理解主流程；调整方案或停止投入。

## 5. 用户与使用场景

### 5.1 用户角色

| 角色 | 角色定位 | 目标 | 本期权限与边界 | 状态 |
|---|---|---|---|---|
| 体验游客 | POC 主要操作人 | 发现 POI、获得路线、完成模拟打卡 | 匿名使用；状态只保存在演示设备 | 🔶 **假设**：首要用户 |
| 项目决策/验收人员 | 观看或亲自操作 Demo | 判断产品方向、能力和风险 | 使用演示脚本和验收记录，不进入管理后台 | **资料事实**：存在客户演示，具体人员待定 |
| 内容运营人员 | 提供和审核 POI/知识资料 | 确保演示内容准确 | 本期通过约定数据文件或接口交付，不建设 CMS | **产品细化**：支撑角色 |
| 开发/演示管理员 | 准备环境和恢复演示状态 | 保证演示可重复 | 可切换在线/降级模式、清空本地演示状态 | **产品细化**：支撑角色 |
| 商户/核销员/监管员 | 正式产品角色 | 管理商品、订单、核销或内容 | 本期不提供角色入口 | 后续范围 |

### 5.2 主要用户任务

| JTBD ID | 当…… | 我想要…… | 从而…… |
|---|---|---|---|
| JTBD-01 | 我准备在光明区游玩但不了解资源分布 | 从地图按类别浏览附近或热门地点 | 快速建立区域认知 |
| JTBD-02 | 我对某个点位感兴趣 | 查看图片、开放时间、特色和位置 | 判断是否值得加入行程 |
| JTBD-03 | 我的时间和兴趣已经确定 | 用自然语言或标签告诉 AI | 获得匹配的有序游玩路线 |
| JTBD-04 | 我已经获得路线 | 在地图查看站点和顺序 | 知道该去哪里、按什么顺序游玩 |
| JTBD-05 | 我完成一个演示点位 | 进行打卡并获得反馈 | 理解正式产品可提供的激励体验 |

### 5.3 核心用户旅程

```mermaid
flowchart TD
    A[打开小程序] --> B{地图和POI是否加载成功}
    B -- 是 --> C[浏览分类/点位]
    B -- 否 --> B1[显示重试或加载演示数据]
    B1 --> C
    C --> D[打开POI详情]
    D --> E[进入AI助手]
    E --> F[输入时长、主题、节奏或自然语言]
    F --> G{AI是否返回有效路线}
    G -- 是 --> H[查看路线列表与地图]
    G -- 否 --> G1[重试或选用预置路线]
    G1 --> H
    H --> I[选择路线点位]
    I --> J[完成模拟打卡]
    J --> K[获得积分和徽章]
    K --> L[个人中心回看结果]
```

## 6. 产品范围

### 6.1 本期必做范围 P0

| 能力 | 本期结果 | 范围说明 |
|---|---|---|
| 地图首页 | 可在目标微信小程序中打开并操作 | 展示光明区范围和样本 POI；支持拖动、缩放 |
| POI 分类与筛选 | 可按已配置分类切换点位 | 至少覆盖景区/场馆、餐饮、商业或住宿、公共设施中的约定类别 |
| POI 摘要与详情 | 点位点击后可查看标准信息 | 字段与缺失规则见第 11 章 |
| AI 偏好输入 | 支持标签和自然语言中的至少一种完整方式 | 必须包含时长信息或采用明确默认值 |
| AI 路线生成 | 返回结构化、有序、可映射 POI 的路线 | 不允许凭空生成未审核点位 |
| 路线结果 | 显示路线说明、站点顺序和地图路径 | 道路级路线为条件范围，POI 连线为最低交付 |
| 模拟打卡 | 在演示状态下完成打卡 | 不依赖正式位置权限和用户账户 |
| 积分与徽章展示 | 打卡后即时反馈并可回看 | 为演示资产，可重置，不等同正式积分账户 |
| 个人中心 | 汇总演示路线、打卡、积分和徽章 | 本机匿名状态，不跨设备同步 |
| 异常与降级 | 地图/AI/API 失败时演示可继续 | 提供重试、明确提示和预置数据 |

### 6.2 条件范围 P1

只有在对应依赖于 Day 1 前确认并准备完成时，相关能力才进入 7 天 POC：

| 能力 | 纳入条件 | 不满足时处理 |
|---|---|---|
| 关键词搜索 | POI 数量和搜索字段已确定 | 通过分类浏览完成演示 |
| 榜单排序 | 官方推荐、评分或热度数据有明确来源 | 仅展示运营配置的推荐列表，不宣称算法榜单 |
| 真实定位和 LBS 打卡 | 微信权限、隐私说明、坐标和真机验证通过 | 使用模拟打卡 |
| 开放式 AI 景点问答 | 知识库、内容审核和错误策略已准备 | 只做路线需求输入和生成 |
| 道路级路线 | 地图服务提供有效路径规划 API 和配额 | 使用 POI 顺序及直线/配置 polyline 展示 |
| 外部导航 | 确认使用 `openLocation` 或地图服务方案 | 仅展示目的地位置，不承诺实时导航 |
| 分享卡片/海报 | 模板、素材、微信分享行为完成真机验证 | 展示静态预览，不作为验收主流程 |

### 6.3 明确不在本期

- 正式微信登录、会员账户、跨设备同步和用户画像。
- 真实积分账户、积分流水、规则引擎、风控、积分商城和二维码核销。
- 游记发布、UGC 审核、评论、评分和社区运营。
- 活动报名、优惠券领取/核销、商品、库存、订单、支付、退款、分账和财务对账。
- CMS、运营后台、商户后台、监管端和数据大屏。
- 实时路况/客流、预约余量、自动重排、保存后编辑路线。
- AI 语音讲解、多语种导游、AI 客服、商家 AI 助手和 AR。
- 正式生产 SLA、万人并发、等保三级验收和长期运维。
- H5、App、支付宝等多端的本期验收；uni-app 保留后续编译能力，但 POC 默认只验微信小程序。

## 7. 产品方案

### 7.1 方案概述

POC 采用“地图发现、详情决策、AI 规划、路线展示、互动反馈”的五段式流程。地图和 AI 不直接信任自由文本：所有页面、路线及打卡均通过唯一 POI `id` 关联同一份审核数据，避免重名、错误坐标和 AI 虚构地点。

在线能力与演示兜底并存。正常情况下，POI 与 AI 路线从业务 API 获取；当网络、地图路径或大模型不可用时，系统可读取相同结构的预置 POI 和路线。兜底模式必须能被演示人员识别，不能把预置结果伪装为实时 AI 结果。

### 7.2 产品能力关系

```mermaid
flowchart TB
    subgraph Client[map-gm-app 微信小程序]
      MAP[地图与筛选]
      POI[POI详情]
      AI[AI偏好输入]
      TRIP[路线结果]
      REWARD[模拟打卡/徽章]
      PROFILE[个人中心]
    end

    subgraph Services[业务服务能力]
      POISVC[POI查询]
      AISVC[路线生成]
      ROUTESVC[路线几何/地图能力]
    end

    subgraph Data[审核数据]
      POIDATA[POI数据]
      KNOWLEDGE[文旅知识资料]
      FIXTURE[预置演示路线]
    end

    MAP --> POI
    POI --> AI
    AI --> TRIP
    TRIP --> REWARD
    REWARD --> PROFILE
    MAP --> POISVC
    POI --> POISVC
    AI --> AISVC
    TRIP --> ROUTESVC
    POISVC --> POIDATA
    AISVC --> POIDATA
    AISVC --> KNOWLEDGE
    AISVC -.失败降级.-> FIXTURE
```

### 7.3 默认产品决策

以下为 **产品细化**，用于在未回复时维持一套可执行初稿；评审确认前仍不是已批准决策：

1. POC 只验微信小程序，不承担多端一致性。
2. 游客匿名进入，不要求微信登录。
3. 地图首页是启动页，不设置底部 Tab；个人中心由地图页入口进入。
4. 打卡默认模拟，不申请真实位置权限。
5. AI 默认一次提交生成一条路线，不做多轮聊天和逐字流式输出。
6. AI 只能从审核 POI 中选点，并返回 POI `id`；前端负责映射内容和坐标。
7. 在线 AI 失败时允许用户明确选择“查看演示路线”。
8. 积分和徽章用 Pinia 本地持久化，提供一键重置演示数据。

## 8. 页面与导航

### 8.1 页面清单

S1 明确了六类页面，但同时称“约 10 个页面”。本期按六个路由页面设计，筛选、POI 卡片、结果提示和打卡反馈使用页面内浮层；这不会用拆页方式凑数量。

| 页面 ID | 页面 | 建议路由 | 主要职责 | 优先级 |
|---|---|---|---|---|
| PAGE-01 | 全域地图首页 | `/pages/map/index` | 地图、分类、筛选、POI marker、POI 摘要、AI/个人入口 | P0 |
| PAGE-02 | POI 详情页 | `/pages-poi/detail` | 展示标准 POI 信息和路线/地图动作 | P0 |
| PAGE-03 | AI 助手页 | `/pages-ai/assistant` | 收集偏好、发起生成、展示过程和异常 | P0 |
| PAGE-04 | 路线结果页 | `/pages-ai/route-result` | 路线摘要、站点、地图路径和点位联动 | P0 |
| PAGE-05 | 打卡徽章页 | `/pages-rewards/checkin` | 模拟打卡、积分/徽章反馈和已获得状态 | P0 |
| PAGE-06 | 个人中心 | `/pages-user/index` | 路线、打卡、积分、徽章汇总及演示重置 | P0 |

页面内载体包括：分类栏、组合筛选面板、POI 摘要卡、加载/空/失败面板、徽章结果弹层。是否将其中任一载体拆为独立页面，应由设计和前端根据交互决定，不改变业务范围。

### 8.2 导航关系

```mermaid
flowchart LR
    P1[PAGE-01 地图首页] --> P2[PAGE-02 POI详情]
    P1 --> P3[PAGE-03 AI助手]
    P1 --> P6[PAGE-06 个人中心]
    P2 --> P3
    P3 --> P4[PAGE-04 路线结果]
    P4 --> P2
    P4 --> P5[PAGE-05 打卡徽章]
    P5 --> P6
    P6 --> P4
    P6 --> P5
```

### 8.3 全局页面状态

所有依赖数据或服务的页面必须区分以下状态，不得只显示空白页或无限 Loading：

| 状态 | 展示要求 | 用户动作 |
|---|---|---|
| `initial` | 页面骨架或明确初始提示 | 等待或开始输入 |
| `loading` | 局部加载，地图拖动/筛选不锁住整页 | 可取消的操作提供取消入口 |
| `success` | 展示完整结果 | 继续浏览或进入下一步 |
| `empty` | 说明无数据的原因 | 清除筛选、返回或换条件 |
| `error` | 显示可理解的错误，不暴露密钥/堆栈 | 重试 |
| `fallback` | 明确提示正在查看演示数据 | 继续演示或再次尝试在线服务 |

## 9. 功能需求

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

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| MAP-001 | 地图初始化 | 打开首页后展示光明区默认中心和缩放级别；加载成功后允许拖动和缩放 | S1/S2；P0 |
| MAP-002 | POI marker | 将当前筛选结果渲染为 marker；不同类别使用可区分样式；marker 必须关联 POI `id` | S1/S2；P0 |
| MAP-003 | 核心地标 | 可由数据字段配置默认高亮点位，不在前端写死名称 | S2；产品细化；P0 |
| MAP-004 | 分类切换 | 展示约定类别；POC 默认单选主分类，“全部”恢复所有可见点位 | S2；产品细化；P0 |
| MAP-005 | 组合筛选 | 支持已提供字段的标签组合；无对应数据的筛选项不得展示 | S2；P1 |
| MAP-006 | 点位联动 | 点击 marker 后展示 POI 摘要卡；点击摘要进入详情 | S1/S2；P0 |
| MAP-007 | 渐进展示 | 根据地图视野请求或筛选 POI；marker 数量超过约定阈值时采用聚合或减少显示 | S2；阈值待确认；P1 |
| MAP-008 | 搜索 | 按 POI 名称、别名或标签匹配；无结果时可清空条件 | S2；P1 |
| MAP-009 | 定位 | 仅在真实定位进入范围时申请权限；拒绝后仍可用默认地图 | S2；条件范围 |
| MAP-010 | 数据异常 | POI API 失败时提供重试或加载审核后的本地演示数据 | 产品细化；P0 |

**用户故事 US-01：从地图发现文旅点位**

- 作为第一次了解光明区的体验游客，我希望按类别查看地图点位，从而快速发现与兴趣相关的地点。
- 场景：分类切换地图点位。
- Given：地图和审核 POI 数据已加载。
- When：游客选择一个主分类。
- Then：地图只展示属于该分类的 POI，并同步更新可见结果状态。

**验收补充：**

- marker 与摘要卡的名称、类别、坐标必须来自同一 POI 记录。
- 快速重复切换分类时，以最后一次选择结果为准，不出现旧请求覆盖新结果。
- 无结果时显示“当前条件下暂无点位”和清除筛选动作。
- 地图 API 不可用时不得假装地图已正常加载。

### 9.2 POI：点位摘要与详情

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| POI-001 | 摘要卡 | 至少展示名称、类别、封面、推荐信息或特色标签、与当前位置/地图中心的距离（有数据时） | S2；P0 |
| POI-002 | 基本详情 | 展示图集/封面、简介、地址、开放时间、特色标签、推荐指数或推荐理由 | S1/S2；P0 |
| POI-003 | 可选详情 | 电话、票价、评分、预约地址、无障碍信息仅在数据存在时展示 | S2；产品细化；P0 |
| POI-004 | 缺失处理 | 缺失字段隐藏对应组件；开放时间未知时显示“开放时间待确认”，不得显示错误默认值 | 产品细化；P0 |
| POI-005 | 路线入口 | 可带当前 POI 进入 AI 助手，作为必经点或兴趣上下文；具体是否必经由页面明确表达 | S2；产品细化；P0 |
| POI-006 | 地图动作 | 返回地图并定位到当前 POI | S1/S2；P0 |
| POI-007 | 导航/预约/收藏/分享 | 仅对已确认且可用的动作显示入口；不做空按钮 | S2；P1/后续混合 |

**用户故事 US-02：查看点位信息并做决定**

- 作为对某个地图点位感兴趣的游客，我希望查看经过审核的关键信息，从而判断是否将它加入行程。
- 场景：查看 POI 详情。
- Given：游客从 marker 或路线站点打开一个有效 POI。
- When：详情页完成数据加载。
- Then：页面展示该 POI 的必填字段，并按缺失规则处理所有可选字段。

**验收补充：**

- 无效或已下线 `poiId` 显示“点位不存在或已下线”，可返回地图。
- 图片失败时展示统一占位图，不影响文本阅读。
- 电话、预约等外部动作必须在真机验证可用后才能进入验收范围。

### 9.3 AI：偏好输入与路线生成

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| AI-001 | 偏好输入 | 至少支持自然语言输入；建议同时提供主题、时长、节奏标签 | S1/S2；P0 |
| AI-002 | 输入校验 | 空输入不可提交；自然语言建议限制 1 至 200 个字符；超限给出提示 | 产品细化；P0 |
| AI-003 | 默认值 | 若用户未提供起点，使用运营配置的默认起点或只生成 POI 顺序；不得假设精确位置 | 产品细化；待确认 |
| AI-004 | 提交控制 | 请求进行中禁止重复提交；支持重新生成；旧请求结果不得覆盖新请求 | 产品细化；P0 |
| AI-005 | 结构化结果 | 返回路线标题、说明、预计时长、有序站点及站点 POI `id`；可选返回路线几何 | S1/S2；产品细化；P0 |
| AI-006 | POI 白名单 | 所有站点必须来自当前审核 POI 数据；无法映射的站点使结果判为无效 | 产品细化；P0 |
| AI-007 | 基本约束 | 同一路线不得重复 POI；停留时长总和不得明显超过用户时长；已知闭馆信息必须提示或避开 | 产品细化；P0 |
| AI-008 | 领域限制 | 与光明文旅无关、违法违规或无法回答的输入返回明确边界提示 | 产品细化；P0 |
| AI-009 | 超时与失败 | 达到配置的超时阈值后结束加载，允许重试或查看预置路线 | 产品细化；P0 |
| AI-010 | 开放问答 | 景点知识问答、引用来源和多轮上下文仅在知识库能力确认后提供 | S1/S2；P1 |
| AI-011 | 展示声明 | AI 结果标明“建议行程，请以场馆实际开放和现场情况为准” | 产品细化；P0 |

**用户故事 US-03：用偏好生成路线**

- 作为时间有限的体验游客，我希望描述游玩时长和兴趣，从而获得一条符合条件的光明区路线。
- 场景：成功生成路线。
- Given：AI 服务可用，且审核 POI 数据已加载。
- When：游客提交合法的游玩偏好。
- Then：系统返回一条只包含审核 POI 的结构化路线并进入结果页。

**用户故事 US-04：从 AI 失败中恢复**

- 作为正在演示产品的体验游客，我希望 AI 失败时仍有明确的下一步，从而不中断整个体验。
- 场景：在线路线生成失败。
- Given：游客已提交合法偏好，但服务超时、报错或结果无法解析。
- When：系统确认本次在线生成失败。
- Then：页面停止加载并提供重试和“查看演示路线”两种动作。

**验收补充：**

- 小程序端不得包含模型供应商密钥。
- AI 返回自由文本但没有可解析 POI `id` 时，不得进入正常路线结果。
- 连续点击重新生成只保留最后一个有效请求结果。
- 降级路线必须符合与在线接口相同的数据结构。

### 9.4 ROUTE：路线结果与地图表达

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| ROUTE-001 | 路线摘要 | 展示标题、匹配说明、预计总时长、站点数和免责声明 | S1/S2；P0 |
| ROUTE-002 | 站点顺序 | 按序号展示 POI、建议停留时长和推荐理由 | S1/S2；P0 |
| ROUTE-003 | 地图 marker | 每个站点在地图显示序号且可与列表互相定位 | S1/S2；P0 |
| ROUTE-004 | 路线几何 | 最低交付为按站点顺序连接；道路级路径仅在地图服务可用时提供 | 产品细化；P0/P1 |
| ROUTE-005 | 详情联动 | 点击站点可查看 POI 摘要或进入详情，返回后保持路线状态 | S2；P0 |
| ROUTE-006 | 路线来源 | 在线 AI 与预置演示路线使用不同状态标记 | 产品细化；P0 |
| ROUTE-007 | 导航动作 | 可按单站点打开地图位置；完整实时导航不在最低范围 | S2；P1 |
| ROUTE-008 | 编辑路线 | 调整顺序、删除/替换点位、动态重排 | S3；本期不做 |

**用户故事 US-05：理解 AI 路线**

- 作为获得 AI 建议的游客，我希望同时查看站点顺序和地图位置，从而理解路线是否可执行。
- 场景：路线列表与地图联动。
- Given：系统已有一条有效的结构化路线。
- When：游客选择路线中的一个站点。
- Then：地图定位并突出该站点，同时保留整条路线的顺序信息。

**验收补充：**

- 站点列表、marker 序号和路线数据顺序必须一致。
- 任一 POI 被下线或缺失时，结果页应提示路线数据已变化，不得静默显示错误点位。
- 路线恢复或页面返回后不得重新调用 AI，除非用户主动重新生成。

### 9.5 CHECKIN：模拟打卡、积分与徽章

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| CHECK-001 | 打卡入口 | 从路线站点或 POI 详情进入，携带有效 `poiId` | S1/S2；P0 |
| CHECK-002 | 模拟模式 | 默认由用户点击确认完成，不请求精确定位；页面或演示设置可识别为模拟 | S1；产品细化；P0 |
| CHECK-003 | 防重复 | 同一演示用户对同一任务只发一次积分/徽章；重复操作显示已完成 | 产品细化；P0 |
| CHECK-004 | 奖励反馈 | 成功后展示 POI、积分变化、徽章名称/图标及下一步 | S1/S2；P0 |
| CHECK-005 | 状态保存 | 在本机保存打卡、积分和徽章，关闭再打开后仍可回看 | S1；产品细化；P0 |
| CHECK-006 | 演示重置 | 开发/演示管理员可二次确认后清空本地演示状态 | 产品细化；P0 |
| CHECK-007 | 真实 LBS | 定位校验、有效半径、防作弊和远端流水 | S2/S3；条件范围/后续 |
| CHECK-008 | 分享 | 微信分享卡片或海报 | S2；P1 |

**用户故事 US-06：模拟打卡获得反馈**

- 作为完成路线站点体验的游客，我希望打卡后马上看到奖励，从而理解后续会员激励的体验。
- 场景：首次模拟打卡。
- Given：游客打开一个尚未打卡且配置了奖励的有效 POI。
- When：游客确认完成模拟打卡。
- Then：系统只发放一次对应积分和徽章，并保存本机记录。

**用户故事 US-07：避免重复奖励**

- 作为演示管理员，我希望重复打卡不会重复加分，从而保证演示数据前后一致。
- 场景：重复模拟打卡。
- Given：当前演示用户已经完成该 POI 的打卡任务。
- When：再次触发相同打卡。
- Then：系统显示已完成状态且积分总数不发生变化。

### 9.6 PROFILE：个人中心与演示管理

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| PROFILE-001 | 身份表达 | 未登录时显示“演示用户”，不展示虚假微信头像或会员等级 | S1；产品细化；P0 |
| PROFILE-002 | 资产汇总 | 显示本机积分总数、已获徽章和打卡数量 | S1/S2；P0 |
| PROFILE-003 | 历史记录 | 展示最近一次有效路线和打卡列表 | 产品细化；P0 |
| PROFILE-004 | 空状态 | 没有路线或徽章时引导返回地图或 AI 助手 | 产品细化；P0 |
| PROFILE-005 | 数据重置 | 二次确认后清除路线、打卡、积分和徽章；不清除基础 POI 数据 | 产品细化；P0 |
| PROFILE-006 | 正式会员 | 登录、跨设备同步、券包、商城、订单和用户画像 | S2/S3；本期不做 |

**用户故事 US-08：回看演示成果**

- 作为完成路线和打卡的体验游客，我希望在个人中心回看结果，从而确认本次体验已经被记录。
- 场景：查看本机演示状态。
- Given：本机已有至少一条路线或打卡记录。
- When：游客进入个人中心。
- Then：页面显示与本机存储一致的路线、打卡、积分和徽章摘要。

### 9.7 DEMO：演示保障

| 需求 ID | 需求 | 详细规则 | 来源/状态 |
|---|---|---|---|
| DEMO-001 | 模式配置 | 支持在线模式和演示数据模式；切换方式不暴露给普通用户或需明确确认 | 产品细化；P0 |
| DEMO-002 | 预置数据 | 至少提供一条完整可演示路线及其 POI、奖励和图片 | 产品细化；P0 |
| DEMO-003 | 演示前检查 | 检查网络、API、地图 Key、POI 和 AI 状态，输出可读结果 | 产品细化；建议 P0 |
| DEMO-004 | 重置 | 演示前可恢复统一初始状态 | 产品细化；P0 |
| DEMO-005 | 来源透明 | 使用预置路线时显示“演示路线”，避免将静态结果宣称为实时 AI | 产品细化；P0 |

## 10. 业务规则

### 10.1 POI 规则

| 规则 ID | 规则 |
|---|---|
| BR-POI-01 | 每个 POI 必须有全局唯一且稳定的 `id`；页面、路线、打卡只通过 `id` 关联 |
| BR-POI-02 | 仅 `status=published` 且坐标合法的 POI 可出现在地图和 AI 路线中 |
| BR-POI-03 | 主分类使用统一枚举；一个 POI 有一个主分类，可有多个标签 |
| BR-POI-04 | 坐标系必须在数据合同中固定，不允许混用未转换的 WGS-84、GCJ-02、BD-09 |
| BR-POI-05 | 推荐指数、评分、热度没有来源时不得用暗示客观排行的名称；可改为“官方推荐”并保留运营说明 |
| BR-POI-06 | 点位关闭或内容下线后，历史路线不得继续把它当作正常可游览站点 |

### 10.2 AI 路线规则

| 规则 ID | 规则 |
|---|---|
| BR-AI-01 | 路线必须至少包含 1 个站点，最多站点数由时长和配置决定 |
| BR-AI-02 | 每个站点必须返回有效 `poiId`，前端不得用 AI 自由文本创建新 POI |
| BR-AI-03 | 同一路线不得出现重复 `poiId` |
| BR-AI-04 | 路线中的 POI 内容、坐标和开放信息以 POI 服务为准，AI 文本不覆盖主数据 |
| BR-AI-05 | AI 返回无法解析、POI 不存在或站点为空时，整条结果判为失败并进入恢复流程 |
| BR-AI-06 | 若路线没有道路级路径，页面必须避免使用“实时导航”措辞 |
| BR-AI-07 | 预置路线和在线生成路线使用相同结构，但保留 `source` 区分 |

### 10.3 打卡与奖励规则

| 规则 ID | 规则 |
|---|---|
| BR-REWARD-01 | POC 使用固定演示用户 `demo_user` 或等价本机标识，不创建正式会员资产 |
| BR-REWARD-02 | 奖励规则由数据配置，前端不在多个页面重复写死积分值 |
| BR-REWARD-03 | 唯一发放键建议为 `demoUserId + taskId`；重复触发不得重复计分 |
| BR-REWARD-04 | 徽章条件不满足时只能记录打卡和积分，不得提前授予徽章 |
| BR-REWARD-05 | 重置演示状态必须二次确认，并清空由 POC 产生的路线和奖励状态 |

### 10.4 状态与错误规则

| 错误类型 | 页面表现 | 恢复动作 |
|---|---|---|
| 网络不可用 | 提示检查网络 | 重试或加载演示数据 |
| POI 数据失败 | 地图保留基础状态，不显示错误 marker | 重试或加载本地 POI |
| AI 超时 | 停止生成动画，说明未生成成功 | 重试或查看演示路线 |
| AI 结果无效 | 不进入正常结果页 | 修改条件或查看演示路线 |
| 图片失败 | 使用占位图 | 不阻断主流程 |
| 地图位置权限拒绝 | 说明仍可浏览默认地图 | 继续匿名浏览或再次授权 |
| 本地存储失败 | 打卡结果仅本次会话有效并提示 | 重试或重置状态 |

## 11. 数据需求

### 11.1 POC 数据准备清单

| 数据包 | 最低内容 | 提供方 | 截止时间 |
|---|---|---|---|
| POI 主数据 | 审核后的点位、类别、坐标、简介、开放时间和图片 | 待指定内容负责人 | Day 0 |
| 分类与标签 | 分类编码、名称、图标/颜色和排序 | 产品/运营 | Day 0 |
| 路线测试集 | 10 组输入、预期约束和人工参考路线 | 产品/文旅专家 | Day 1 |
| 文旅知识资料 | AI 可使用的权威介绍、开放信息和注意事项 | 内容负责人 | Day 0 |
| 奖励配置 | 打卡任务、积分值、徽章名称和图片 | 产品/运营 | Day 1 |
| 演示素材 | Logo、主题色、占位图、分享图或徽章图 | UI/品牌负责人 | Day 1 |

### 11.2 POI 数据模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 稳定唯一标识 |
| `name` | string | 是 | 点位名称 |
| `aliases` | string[] | 否 | 搜索别名 |
| `categoryCode` | enum | 是 | 主分类编码 |
| `tags` | string[] | 否 | 特色、主题、适用人群等标签 |
| `longitude` | number | 是 | 经度，坐标系见数据说明 |
| `latitude` | number | 是 | 纬度，坐标系见数据说明 |
| `coordinateSystem` | enum | 是 | POC 全量应采用同一值 |
| `coverImage` | string | 是 | HTTPS 图片地址或小程序内资源 |
| `images` | string[] | 否 | 详情图集 |
| `summary` | string | 是 | 地图卡片短介绍 |
| `description` | string | 是 | 详情介绍 |
| `address` | string | 是 | 地址文本 |
| `openingHours` | string/null | 是 | 未知时传 `null`，不伪造默认营业时间 |
| `phone` | string/null | 否 | 联系电话 |
| `ticketInfo` | string/null | 否 | 票价或预约说明 |
| `accessibility` | string[] | 否 | 无障碍能力标签 |
| `recommendationType` | enum/null | 否 | 如 `official`，需有来源 |
| `recommendationReason` | string/null | 否 | 推荐理由 |
| `status` | enum | 是 | `draft`、`published`、`offline` |
| `updatedAt` | datetime | 是 | 内容更新时间 |

### 11.3 路线请求模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `requestId` | string | 是 | 用于去重和关联日志 |
| `freeText` | string | 条件必填 | 用户自然语言需求 |
| `durationMinutes` | number | 建议是 | 计划总时长；未提供时采用已确认默认值 |
| `themes` | string[] | 否 | 科学、生态、美食、文化等 |
| `pace` | enum | 否 | `relaxed`、`balanced`、`intensive` |
| `companions` | string[] | 否 | 亲子、情侣、团队等 |
| `mustIncludePoiIds` | string[] | 否 | 从 POI 详情发起时携带 |
| `startLocation` | object/null | 否 | 只有用户明确授权或选择后提供 |
| `locale` | string | 否 | POC 默认 `zh-CN` |

`freeText` 和结构化偏好至少有一项有效；若只提供标签，必须包含可执行的时长或采用页面明示的默认时长。

### 11.4 路线结果模型

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `routeId` | string | 是 | 路线唯一标识 |
| `source` | enum | 是 | `ai_online` 或 `demo_fixture` |
| `title` | string | 是 | 路线名称 |
| `summary` | string | 是 | 匹配说明 |
| `totalDurationMinutes` | number | 是 | 预计总时长 |
| `totalDistanceMeters` | number/null | 否 | 有地图路径数据时返回 |
| `stops` | RouteStop[] | 是 | 有序站点，不得为空 |
| `polyline` | Point[]/null | 否 | 地图路线几何 |
| `warnings` | string[] | 否 | 开放时间、预约、路线仅供参考等提示 |
| `generatedAt` | datetime | 是 | 生成时间 |

`RouteStop` 至少包含 `sequence`、`poiId`、`suggestedStayMinutes`、`reason`。POI 名称、图片和坐标应由客户端或聚合服务根据 `poiId` 读取主数据，不以 AI 文本作为最终依据。

### 11.5 打卡与徽章模型

| 实体 | 关键字段 | 说明 |
|---|---|---|
| 打卡任务 | `taskId`、`poiId`、`points`、`badgeId`、`status` | 奖励配置 |
| 打卡记录 | `recordId`、`demoUserId`、`taskId`、`poiId`、`mode`、`checkedAt` | `mode=simulated` 为默认 |
| 积分变动 | `transactionId`、`demoUserId`、`sourceRecordId`、`delta`、`createdAt` | 本地演示流水，便于保证幂等 |
| 徽章 | `badgeId`、`name`、`image`、`description`、`rule` | POC 可采用单任务授予规则 |
| 徽章授予 | `demoUserId`、`badgeId`、`sourceRecordId`、`awardedAt` | 同一徽章是否可重复由配置决定，默认不可重复 |

### 11.6 数据质量要求

- 坐标、名称、图片和简介须由指定内容负责人审核。
- 图片必须可在微信小程序合法域名或包内资源中访问，并明确使用权。
- POI 导入前执行唯一 ID、经纬度范围、必填字段、重复坐标和 URL 检查。
- AI 测试集不能只包含理想输入，至少覆盖空输入、超长输入、无关问题、矛盾条件、闭馆点位和服务超时。
- POC 结束后如进入正式建设，应重新制定数据责任、更新频率、审核记录和内容下线流程。

## 12. 接口能力要求

### 12.1 原则

- 小程序只调用业务服务，不直接携带 AI 供应商密钥。
- POI、路线和奖励使用稳定 ID 关联。
- 在线接口与本地 Fixture 使用一致的数据结构。
- 所有接口需返回可区分的成功、业务错误和系统错误，不依赖 HTTP 200 + 模糊文本。
- POC 可由后端聚合地图路径和 AI 结果；具体后端语言与存储实现不由本 PRD限制。

### 12.2 能力清单

| 能力 ID | 能力 | 建议方法 | 输入 | 输出 | 优先级 |
|---|---|---|---|---|---|
| API-POI-01 | 获取分类 | GET | 无或版本号 | 分类列表 | P0 |
| API-POI-02 | 获取 POI 列表 | GET/POST | 分类、标签、视野或关键词 | POI 摘要列表 | P0 |
| API-POI-03 | 获取 POI 详情 | GET/POST | `poiId` | POI 详情 | P0 |
| API-AI-01 | 生成路线 | POST JSON | RouteRequest | RoutePlan | P0 |
| API-MAP-01 | 获取路线几何 | 由地图服务或业务服务决定 | 起终点/站点坐标 | polyline、距离、时长 | P1 |
| API-AI-02 | 文旅开放问答 | POST JSON | 问题、可选上下文 | 答案、引用、相关 POI | P1 |
| API-REWARD-01 | 正式打卡/奖励 | POST JSON | 用户、任务、定位证明 | 记录与资产变化 | 后续 |

### 12.3 建议统一响应

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

建议业务状态至少区分：`OK`、`INVALID_ARGUMENT`、`NOT_FOUND`、`CONTENT_RESTRICTED`、`AI_TIMEOUT`、`AI_INVALID_RESULT`、`MAP_SERVICE_ERROR`、`RATE_LIMITED`、`INTERNAL_ERROR`。前端根据状态展示第 10.4 节定义的恢复动作。

### 12.4 AI 接口验收合同

- 请求可由 `requestId` 去重；重复提交不会生成难以关联的多份结果。
- 返回值是合法 JSON，符合 RoutePlan 模型。
- `stops[].poiId` 全部存在于当前发布 POI 中。
- 失败返回明确错误码，不在 `data` 中混入半成品路线。
- 达到超时阈值时可安全结束请求；前端再次提交不会被旧结果污染。
- 敏感内容、无关问题和提示词攻击不会让服务返回密钥、内部提示词或未审核数据。

## 13. 埋点与评估

### 13.1 事件清单

| 事件 | 触发时机 | 关键属性 | 用途 |
|---|---|---|---|
| `poc_app_open` | 打开首页 | `sessionId`、版本、模式 | 演示次数 |
| `map_load_result` | 地图完成或失败 | 耗时、结果、错误码 | 地图稳定性 |
| `poi_data_result` | POI 数据完成或失败 | 数量、耗时、来源 | 数据稳定性 |
| `poi_category_select` | 选择分类 | `categoryCode`、结果数 | 浏览行为 |
| `poi_detail_view` | 打开详情 | `poiId`、入口 | 点位兴趣 |
| `ai_route_submit` | 提交路线需求 | 结构化标签、字符数；不记录原始敏感文本 | AI 请求量 |
| `ai_route_result` | 路线成功/失败 | 耗时、结果、错误码、站点数、来源 | AI 成功率与时延 |
| `route_stop_select` | 选择站点 | `routeId`、`poiId`、顺序 | 路线理解度 |
| `checkin_result` | 打卡成功/重复/失败 | `poiId`、模式、结果 | 互动完成情况 |
| `badge_award` | 授予徽章 | `badgeId`、来源任务 | 激励演示 |
| `demo_reset` | 清除演示状态 | 执行入口 | 演示管理 |

### 13.2 隐私要求

- 未经明确授权，不记录精确位置、微信身份或用户输入原文。
- POC 采用本机日志时，演示结束可一键清除。
- 若使用第三方统计 SDK，必须在隐私说明和微信配置中披露；未完成合规前可用开发日志替代。

### 13.3 POC 评估记录

每次正式演示至少记录：设备型号、系统、微信版本/基础库、网络、应用版本、在线或演示模式、主流程结果、AI 提示词编号、耗时、失败原因和观察反馈。

## 14. 非功能需求

### 14.1 性能

| ID | 要求 | 建议验收值 | 状态 |
|---|---|---|---|
| NFR-PERF-01 | 地图首屏可交互 | 目标真机和约定网络下不超过 3 秒 | 产品细化 |
| NFR-PERF-02 | 分类/筛选响应 | 本地筛选不超过 300ms；网络筛选显示局部加载 | 产品细化 |
| NFR-PERF-03 | POI 详情 | 缓存命中不超过 1 秒，网络加载有骨架和超时 | 产品细化 |
| NFR-PERF-04 | AI 路线 | P95 不超过 10 秒；实际目标在模型联调后复核 | 产品细化 |
| NFR-PERF-05 | 图片 | 使用适合小程序的尺寸和懒加载，单张失败不阻断页面 | 产品细化 |

### 14.2 兼容性

- POC 默认验收微信小程序；最低基础库版本为 P0 待确认项。
- 至少在一台主流 iOS 和一台主流 Android 真机执行主流程。
- 地图原生组件上的浮层、点击、滚动和层级必须真机验证，不能只以 H5 结果代替。
- 编译包及分包应满足验收时微信小程序平台的现行限制。
- 低端机 marker 数量上限和聚合策略在样本规模确定后专项验证。

### 14.3 安全与隐私

- AI、地图服务端 Key 或其他密钥不得提交到小程序包或公开环境变量。
- 网络接口使用 HTTPS 和微信合法域名；开发工具中的 `urlCheck=false` 不视为生产可用。
- 错误提示不展示堆栈、内部 URL、提示词、Token 或密钥。
- 真实定位若纳入，必须采用按需申请、用途说明、拒绝后可继续使用和最小化存储。
- 上传照片、游记和公开分享不在 P0 范围；若纳入 P1，需增加内容安全和用户授权。

### 14.4 AI 质量与安全

- AI 只使用允许的数据源，不应把互联网未审核内容作为 POC 点位事实。
- 路线页显示开放时间、预约和现场情况的免责声明。
- 对无关、违法、危险或要求泄露系统信息的输入给出范围说明，不执行其指令。
- AI 的路线理由是建议，不替代 POI 主数据。
- 将解析失败、超时、限流、内容拦截分别记录，不能统一显示“服务器错误”。

### 14.5 可用性与无障碍

- 地图类别不能只靠颜色区分，同时使用图标或文字。
- 主要文字和按钮满足清晰对比；关键点击区域适合移动端触控。
- 所有图片提供占位或文本信息；核心路线不能只存在于地图，应同时有列表。
- 加载、失败、空状态均提供下一步动作。
- 位置权限拒绝、AI 失败、无搜索结果不应形成流程死路。

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

- POI、AI、路线、奖励类型在前端集中定义，禁止页面各自使用不一致结构。
- 地图供应商适配与页面业务分离，避免直接把供应商对象写入业务状态。
- 每个 API 请求带 `requestId`，关键错误和耗时可定位。
- 演示 Fixture 和生产/在线 API 明确分目录和模式，不允许临时修改代码切换数据。
- 关键业务逻辑至少覆盖类型检查、单元测试或可重复验收脚本。

## 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` | 可保存本机模拟积分和徽章 |
| 文件路由和分包 | 已配置 UniPages、Layouts 和示例分包 | 可按 POI、AI、奖励拆分业务页面 |
| 请求封装 | 已有 `@uni-helper/uni-network`、拦截器、上传和 Loading | 可改造成业务 API 层 |
| UI 基础 | 已有 uview-plus、UnoCSS | 可快速制作移动端页面和状态组件 |
| 工程质量命令 | 已有 lint、type-check、Vitest 和微信构建脚本 | 可用于 POC 基本质量检查 |

### 15.2 当前缺口

- 工程目前仍是 `unisave` 通用模板，首页请求 GitHub 示例接口，没有任何文旅业务代码。
- 没有地图、marker、polyline、定位、POI、AI、路线、打卡、徽章或用户会话实现。
- 应用名称仍为 `unisave`，微信 AppID 为 `testappid`，正式小程序身份未配置。
- API 协议仍按模板默认 POST + 表单编码，响应拦截逻辑未适配本项目。
- `.env.production` 没有正式环境配置；H5 代理和微信小程序合法域名也未完成。
- 当前页面和布局是模板演示，不适用于全屏地图；正式业务路由、分包和导航未建立。
- 当前测试只覆盖通用日期和校验工具，没有业务测试。

因此，现有工程可复用的是“工程骨架”，不能把它计为已完成任何 POC 业务功能。

### 15.3 建议前端结构

以下是工程适配建议，不限制研发根据实际情况调整文件名：

```text
src/
├── pages/map/                 # 主包地图首页
├── pages-poi/                 # POI分包
├── pages-ai/                  # AI和路线分包
├── pages-rewards/             # 打卡与徽章分包
├── pages-user/                # 个人中心分包（无Tab时）
├── components/map/            # marker、筛选、POI卡等
├── components/ai/             # 偏好、生成状态等
├── services/apis/             # poi、assistant、trip API
├── services/map/              # 地图供应商适配
├── stores/modules/            # map、poi、trip、assistant、rewards
├── types/                     # POI、路线、奖励类型
└── fixtures/                  # 审核后的演示数据和降级路线
```

### 15.4 建议状态划分

| Store | 内容 | 是否持久化 |
|---|---|---|
| `map` | 中心、缩放、分类、筛选、选中 POI、定位权限 | 否；不持久化精确位置 |
| `poi` | 分类、POI 字典、列表和详情缓存 | 可短期缓存，不作为主数据 |
| `trip` | 当前需求、生成状态、当前路线、最近路线 | POC 可保存最近一条 |
| `assistant` | 请求状态、错误和有限会话上下文 | 默认不永久保存原始输入 |
| `rewards` | 打卡记录、积分和徽章 | 是；仅本机演示数据 |
| `session` | 演示模式、会话 ID | 会话级 |

### 15.5 工程改造要求

| ID | 改造项 | 验收要求 |
|---|---|---|
| ENG-001 | 替换模板应用身份 | 名称、标题、AppID 和描述不再使用模板值 |
| ENG-002 | 替换示例首页/API | 不再请求 GitHub；首页进入文旅地图 |
| ENG-003 | 建立业务路由/分包 | 业务路由由 UniPages/SFC 配置生成，不直接维护生成文件 |
| ENG-004 | 改造请求协议 | 支持 JSON、统一响应、超时、业务错误、请求 ID 和取消/过期结果处理 |
| ENG-005 | 地图适配 | 封装 marker、polyline、视野和坐标；页面不直接依赖供应商私有数据结构 |
| ENG-006 | AI 安全调用 | 只调用业务 API，密钥不进入客户端 |
| ENG-007 | 演示模式 | 可配置在线/Fixture，且能重置演示状态 |
| ENG-008 | 真机验证 | 地图浮层、定位（若有）、分享（若有）和性能在目标真机通过 |

## 16. 验收方案

### 16.1 核心演示脚本

| 步骤 | 操作 | 预期结果 | 对应需求 |
|---|---|---|---|
| 1 | 打开小程序 | 进入光明区地图，地图和 POI 加载成功 | MAP-001/002 |
| 2 | 切换一个分类 | marker 和结果状态同步变化 | MAP-004 |
| 3 | 点击一个 marker | 展示摘要并进入正确 POI 详情 | MAP-006、POI-001/002 |
| 4 | 从详情进入 AI 助手 | 当前 POI 或上下文按规则带入 | POI-005 |
| 5 | 输入约定偏好并提交 | 防重复提交，显示生成状态 | AI-001/004 |
| 6 | 查看生成结果 | 路线只含审核 POI，列表和地图顺序一致 | AI-005/006、ROUTE-001/004 |
| 7 | 选择路线站点 | 地图与站点联动，可打开详情 | ROUTE-003/005 |
| 8 | 完成模拟打卡 | 积分和徽章只发放一次 | CHECK-002/003/004 |
| 9 | 打开个人中心 | 回看路线、打卡、积分和徽章 | PROFILE-002/003 |
| 10 | 重置演示并验证 AI 失败兜底 | 状态恢复；在线失败可进入演示路线 | PROFILE-005、DEMO-002/004 |

### 16.2 必测异常

| 测试项 | 预期 |
|---|---|
| 首次无网络打开 | 可理解提示；如本地数据齐全，可进入演示模式 |
| POI 列表为空 | 显示空状态并可清除条件 |
| 无效 POI ID | 显示下线/不存在并可返回 |
| AI 空输入 | 阻止提交并指出必填条件 |
| AI 超时 | 结束 Loading，允许重试或演示路线 |
| AI 返回不存在 POI | 结果判为无效，不展示错误路线 |
| 重复提交 | 不出现重复结果或旧结果覆盖 |
| 重复打卡 | 不重复增加积分或徽章 |
| 图片加载失败 | 占位图生效，流程不阻断 |
| 定位拒绝（若纳入） | 继续使用默认地图，不反复强制授权 |
| 本地状态重置 | 只清除演示用户状态，基础 POI 保留 |

### 16.3 缺陷等级

| 等级 | 定义 | 演示前要求 |
|---|---|---|
| S0 阻断 | 无法启动、主流程无法继续、崩溃、数据严重错误、密钥泄露 | 必须为 0 |
| S1 严重 | 核心功能错误但有困难的替代路径、路线/积分不一致 | 必须为 0 |
| S2 一般 | 非核心功能错误、明显样式或兼容问题 | 有明确处理结论 |
| S3 轻微 | 文案、间距等不影响演示的问题 | 可记录后修复 |

### 16.4 完成定义

单项需求只有同时满足以下条件才视为完成：

- 产品规则和验收条件已实现，加载、空、失败状态齐全。
- 目标微信开发者工具构建通过，并在约定真机完成验证。
- TypeScript 检查和 lint 通过；关键纯逻辑有测试或可重复测试用例。
- 不包含客户端 AI 密钥、模板 AppID、GitHub 示例接口或明显占位文案。
- 数据和接口文档与实际返回一致。
- 主流程演示脚本可从统一初始状态重复执行。

## 17. 交付物与计划

### 17.1 交付清单

| 交付物 | 必须内容 | 优先级 |
|---|---|---|
| 产品文档 | 评审后的 PRD、范围与待确认结论 | P0 |
| UI 交付 | 六类页面、浮层、加载/空/失败状态、品牌素材 | P0 |
| 前端源码 | `map-gm-app` 内可构建的业务实现 | P0 |
| 后端/AI 服务 | POI 和路线能力或可访问的演示服务 | P0 |
| 数据包 | 审核 POI、分类、奖励、知识资料、演示路线 | P0 |
| 接口文档 | 请求、响应、错误码、超时和示例 | P0 |
| 测试材料 | 用例、结果、设备/网络信息、已知问题 | P0 |
| 演示材料 | 演示账号/模式、脚本、重置方式和故障切换说明 | P0 |
| 构建说明 | 环境、命令、合法域名、AppID/Key 配置说明 | P0 |
| 设计源文件与资源授权说明 | 可编辑设计稿和图片/字体使用说明 | P1 |

### 17.2 Day 0 准入条件

7 天排期只有在以下条件满足后开始计算：

- P0 范围和页面清单已签字或书面确认。
- 微信 AppID、开发权限、合法域名负责人明确。
- 地图服务商、Key、坐标系、配额和路线能力明确。
- 审核 POI 样本和图片可用，数据格式已通过抽检。
- AI 服务账号、知识资料、接口负责人和降级路线明确。
- UI 品牌素材和最终评审人明确。
- 目标真机、网络和客户演示环境明确。

### 17.3 7 天执行建议

| 日期 | 工作重点 | 当日出口条件 |
|---|---|---|
| Day 1 | 锁定需求、页面结构、数据/API 合同；清理模板；建立业务骨架 | 页面/接口/数据合同冻结，主流程骨架可运行 |
| Day 2 | 地图、POI 数据、marker、分类 | 真机展示审核 POI，坐标抽检完成 |
| Day 3 | POI 摘要/详情、筛选与异常；AI 接口联调 | 地图到详情流程完成，AI Mock 合同通过 |
| Day 4 | AI 输入、生成状态、结果校验和降级 | 约定提示词能返回结构化路线或稳定 Fixture |
| Day 5 | 路线列表/地图联动、模拟打卡、积分徽章 | 核心主流程可端到端执行 |
| Day 6 | 个人中心、状态重置、UI 优化、双端真机与异常测试 | 可用性测试完成，S0/S1 清零计划明确 |
| Day 7 | 回归、性能检查、交付材料、客户演示彩排 | 验收记录完成，在线/降级两套演示均可执行 |

### 17.4 人员职责

| 角色 | 主要职责 |
|---|---|
| 产品/需求负责人 | 关闭 P0 问题、维护范围、提供测试集、组织验收 |
| 内容负责人 | 提供并审核 POI、图片、开放信息和知识资料 |
| 前端开发 | uni-app 页面、状态、地图适配、API 接入、真机验证 |
| 后端/AI 开发 | POI/AI 服务、结构化结果、错误码、日志和演示稳定性 |
| UI 设计 | 页面和状态设计、品牌素材、地图浮层真机适配支持 |
| 测试/演示负责人 | 用例、设备测试、缺陷记录、演示脚本和重置检查 |

若没有独立测试人员，产品与开发必须在 Day 6-7 明确分工，不能由同一实现者独自判断全部验收通过。

## 18. 依赖与风险

### 18.1 外部依赖

| 依赖 | 必需内容 | 未就绪影响 | 负责人 |
|---|---|---|---|
| 微信小程序 | AppID、主体权限、开发成员、合法域名 | 无法真机/体验版验收 | 待指定 |
| 地图服务 | Key、配额、白名单、坐标系、路线能力 | 地图/路线无法稳定展示 | 待指定 |
| POI 数据 | 审核样本、图片、坐标、分类 | “全域”和 AI 路线均无可靠输入 | 待指定 |
| AI 服务 | 模型/API、知识资料、调用限制 | 只能使用静态路线演示 | 待指定 |
| 设计与品牌 | Logo、色彩、徽章、占位图 | UI 只能使用临时素材 | 待指定 |
| 演示环境 | 设备、网络、投屏方式 | 性能和交互结果不可控 | 待指定 |

### 18.2 风险与应对

| ID | 风险 | 概率 | 影响 | 应对措施 | 触发条件 |
|---|---|---|---|---|---|
| R-01 | 7 天范围继续吸收积分商城、优惠券、游记等功能 | 高 | 高 | 以 P0/P1/后续清单控制；新增 P0 必须替换等量范围或调整工期 | 评审后新增主流程外功能 |
| R-02 | POI 数据晚到、坐标混乱或图片不可用 | 高 | 高 | Day 0 准入；先做数据校验；保留审核 Fixture | Day 1 仍无合格数据 |
| R-03 | AI 生成不存在或不合理点位 | 高 | 高 | 只允许返回 POI ID；结果校验；测试集；预置路线 | 出现任一无法映射站点 |
| R-04 | 地图路径被误认为实时导航 | 中 | 高 | 在文案和验收中区分 POI 连线、道路路径和外部导航 | 地图服务无路径 API |
| R-05 | 微信地图浮层或真机层级异常 | 中 | 高 | Day 2 即双端真机验证，地图页使用专门布局 | H5 正常但真机遮挡/失效 |
| R-06 | AI/地图网络或额度在演示现场失败 | 中 | 高 | 演示前检查、配额确认、Fixture 降级、完整彩排 | 错误率或时延超过阈值 |
| R-07 | 模拟积分被理解为正式会员资产 | 中 | 中 | 页面/演示说明模式；支持重置；不使用正式资产措辞 | 客户要求跨设备或兑换 |
| R-08 | 位置权限和隐私配置拖慢 POC | 中 | 中 | 默认模拟打卡；真实定位单独设条件门槛 | Day 1 未完成隐私配置 |
| R-09 | 现有模板请求和环境配置直接沿用 | 中 | 高 | Day 1 清理模板，统一 JSON/错误/超时协议，构建前检查 | 仍出现 GitHub 或 `testappid` |
| R-10 | 无用户研究却把 POC 视为需求已验证 | 高 | 中 | 增加 5 人任务测试；区分技术验证和用户价值验证 | 只完成客户演示，无测试记录 |

### 18.3 四类产品风险

| 风险类型 | 当前最弱证据 | POC 内验证方式 |
|---|---|---|
| 价值 | 没有游客访谈或使用数据 | 5 人任务测试和访谈，不以客户喜欢代替游客价值 |
| 可用性 | 地图浮层、AI 输入和路线理解尚无测试 | 双端真机任务测试 |
| 可行性 | 地图、AI、数据、微信权限均未联调 | Day 0 准入 + Day 2/4 技术关口 |
| 业务可行性 | 正式建设成本、数据责任和长期运营未确定 | POC 只记录依赖，不宣称已形成正式商业模式 |

## 19. 待确认事项

### 19.1 P0：开发基线前必须关闭

| ID | 问题 | 推荐默认项 | 影响 | 建议负责人 | 截止 |
|---|---|---|---|---|---|
| Q-01 | 7 天交付是否确认为 POC，而非 S3 一期 2 个月正式版本？ | 确认为 7 天 POC | 决定整体范围 | 项目决策人 | Day 0 |
| Q-02 | 目标端是否只验微信小程序？最低基础库和真机是什么？ | 只验微信；一台 iOS + 一台 Android | 兼容与工期 | 技术负责人 | Day 0 |
| Q-03 | “六类页面”与“约 10 页”按什么口径验收？ | 六个路由 + 页面内浮层，不按数量凑页 | UI 和开发拆分 | 产品/客户 | Day 0 |
| Q-04 | 正式微信 AppID、开发权限和合法域名由谁提供？ | 由项目方在 Day 0 提供 | 真机和体验版 | 项目方技术接口人 | Day 0 |
| Q-05 | 地图供应商、Key、坐标系和路线能力是什么？ | 选择一个供应商并统一 GCJ-02 等确定口径 | 地图和路线 | 技术负责人 | Day 0 |
| Q-06 | POC POI 数量、类别、数据/图片来源和审核人是谁？ | 先锁定可审核的代表性样本，不以 320+ 为本期承诺 | 数据和“全域”表述 | 内容负责人 | Day 0 |
| Q-07 | AI 是一次性路线生成，还是包含多轮开放问答、语音讲解？ | P0 只做一次性路线；开放问答 P1；语音后续 | 页面、接口、时延 | 产品/客户 | Day 0 |
| Q-08 | AI 模型/API、知识资料、是否可传第三方、账号和额度由谁提供？ | 服务端统一接入，客户端不持密钥 | 可行性与合规 | AI 负责人 | Day 0 |
| Q-09 | 路线最低验收是 POI 连线、道路级路径，还是实时导航？ | P0 为 POI 顺序+连线，道路路径 P1 | 地图成本 | 产品/技术 | Day 0 |
| Q-10 | 打卡使用模拟还是必须真实定位？ | 使用模拟打卡 | 权限、隐私、后端 | 产品/客户 | Day 0 |
| Q-11 | 是否匿名使用？个人中心是否只保存本机数据？ | 匿名 + 本机状态 | 登录与资产 | 产品/客户 | Day 0 |
| Q-12 | 谁是最终演示对象和验收签字人？演示网络与投屏方式是什么？ | 指定一名验收人和固定设备/网络 | 成功口径 | 项目经理 | Day 0 |

### 19.2 P1：对应功能开发前关闭

| ID | 问题 | 推荐默认项 | 截止 |
|---|---|---|---|
| Q-13 | 是否做搜索和算法榜单？榜单数据来自哪里？ | 只做分类；有权威配置时做官方推荐 | Day 2 |
| Q-14 | AI 默认时长、起点和最大站点数是什么？ | 页面明示默认值；由测试集校准 | Day 3 |
| Q-15 | 是否需要分享卡片、海报或朋友圈引导？ | P1；先确认素材和微信限制 | Day 3 |
| Q-16 | POI 详情中的电话、预约、收藏、评分哪些是真实可用？ | 无数据/无能力不展示 | Day 2 |
| Q-17 | 演示积分和徽章的具体规则与素材是什么？ | 每个演示任务固定配置，防重复 | Day 3 |
| Q-18 | UI 品牌规范和最终设计审核人是谁？ | Day 1 提供最小品牌包 | Day 1 |
| Q-19 | 成功指标建议值是否接受？ | 评审后形成正式验收表 | Day 1 |

### 19.3 决策记录

| 日期 | 决策 | 理由 | 决策人 |
|---|---|---|---|
| 2026-07-29 | 前端基线采用现有 `map-gm-app` uni-app 工程 | 用户明确指定 | 用户 |
| 待定 | 当前范围采用 POC 必做清单 | 等待评审 | 待定 |

## 20. 后续需求池

### 20.1 正式一期：内容与基础导览

- 全量 POI 管理、CMS、内容审核、批量导入和数据更新。
- 完整搜索、官方推荐/榜单、收藏、评价和预设主题路线。
- 真实定位、道路路线、外部导航、旅游巴士信息和预约入口。
- 正式打卡、积分账户、流水、规则和基础风控。
- 正式用户身份、跨设备同步和基础运营统计。

### 20.2 二期：运营与交易

- 活动发布/报名、优惠券、券包和到店核销。
- 商户入驻、商品/库存、订单、微信支付、退款、分账和对账。
- 积分商城、商品兑换、二维码核销和工作人员权限。
- 商户后台、运营后台、监管视图和数据看板。
- 徽章挑战、排行榜、游记、UGC 审核和分享增长。

### 20.3 三期：AI 与增值服务

- 多轮 AI 文旅助手、开放问答、引用溯源和个性化长期记忆。
- 实时路况/客流/开放状态驱动的路线调整。
- 语音导览、多语种、港澳与入境游客适配。
- AI 客服、运营分析、商家助手和正式推荐系统。
- AR 打卡及其他沉浸式体验。

每个后续阶段都需要独立 PRD、用户验证、技术评估和验收指标，不能直接把 PPT 功能列表当作研发合同。

## 21. 需求追溯

| 需求主题 | S1 | S2 | S3 | 本 PRD 处理 |
|---|---|---|---|---|
| 地图 + POI | 第 4、9 节 | 第 3-7 页 | 第 10-14 页 | MAP/POI P0 |
| AI 问答/路线 | 第 2、4、9 节 | 第 9 页 | 第 34-35 页 | 路线 P0；开放问答 P1；语音后续 |
| 路线地图 | 第 4、9 节 | 第 8-9 页 | 第 15-16、34 页 | 站点+连线 P0；道路路径 P1 |
| 打卡/徽章 | 第 4、9 节 | 第 10、13 页 | 第 18、31 页 | 模拟打卡 P0；真实 LBS 后置 |
| 个人中心 | 第 5 节 | 隐含于会员资产 | 第 8 页 | 本机演示汇总 P0 |
| 游记/海报 | 后续方向未明确列页 | 第 11 页 | 第 19 页 | P1/后续 |
| 积分商城/核销 | 后续扩展 | 第 12 页 | 第 20 页 | 后续 |
| 榜单挑战 | 未列 | 第 14 页 | 榜单与徽章相关页 | 后续或有数据时 P1 |
| 优惠券 | 未列 | 第 15 页 | 第 17、26-30 页 | 后续 |
| 订单/支付/分账 | 未列 | 未完整展开 | 第 25-32 页 | 后续二期 |
| CMS/运营后台 | 未列为 POC 页 | 隐含配置 | 第 7、21-30 页 | POC 不做，正式一期重定义 |
| 多语种/港澳 | 未列 | 未列 | 第 37、41-44 页 | 后续三期/运营 |

### 21.1 关键产品细化追溯

| 细化内容 | 产生原因 | 验证方式 |
|---|---|---|
| AI 只返回审核 POI ID | 附件未定义幻觉控制，路线必须能落图 | API 合同测试和提示词集 |
| 默认模拟打卡 | S1 明确“模拟”，S2/S3 又描述真实定位 | Q-10 决策；主流程验收 |
| 六路由 + 浮层 | 解决六类页面与约 10 页冲突 | Q-03 决策和 UI 评审 |
| 在线/Fixture 双模式 | 7 天 POC 对外部服务依赖高 | 断网和 AI 超时演练 |
| 本机匿名积分/徽章 | POC 未定义登录和正式资产 | 重复打卡与重置测试 |
| 只验微信小程序 | 用户指定 uni-app 工程但未要求多端 | Q-02 决策和双端真机测试 |

## 22. PRD 自检

### 22.1 最强部分

范围、功能规则和异常恢复较清晰。三份附件中的 POC 与长期规划已分开，AI、路线、打卡及工程适配均有可测试条件，能避免把 PPT 中的交易和运营功能误算为 7 天交付。

### 22.2 最弱部分

用户价值与成功目标证据最弱。附件没有用户访谈、现状数据或正式验收指标；当前用户画像、任务完成目标和性能阈值均为建议，不能在未经评审的情况下宣称已验证。

### 22.3 高风险假设

| 假设 | 错误时的影响 | 验证方式 |
|---|---|---|
| 本期是 7 天 POC，不是正式一期 | 整体范围、架构和工期失效 | Q-01 书面确认 |
| 可采用匿名、模拟打卡和本机状态 | 需新增登录、定位、后端资产和合规工作 | Q-10/Q-11 确认 |
| AI 可被约束为只输出审核 POI | 路线无法可靠落图，演示风险高 | Day 1 API Spike + 10 组提示词 |
| POI 数据能在 Day 0 提供 | 地图和 AI 均缺少可信输入 | 数据准入检查 |
| 微信真机中的地图浮层可按设计工作 | 关键页面可能需要重做 | Day 2 iOS/Android 验证 |

### 22.4 评审前的首要动作

由项目决策人一次性关闭第 19.1 节的 12 个 P0 问题，并提供 Day 0 输入。若只能优先回答三项，应先确认：当前是 7 天 POC 还是正式一期、地图/POI 数据由谁提供、AI/路线/打卡的最低验收边界。

本 PRD 在这些问题关闭前属于完整评审稿，而非已批准开发承诺。
