微信小程序构建与验收说明

1. 当前交付边界

本项目是光明区文旅全域地图、POI 数字化展示、AI 文旅助手与行程规划 POC。
目标端为微信小程序，当前只要求在一台实际 iOS 设备验证。
用户主动授权后，地图可显示前台实时位置；行程会用本次位置快照优化首站和游览顺序。
行程由随包 POI 和确定性规则生成，用于验证推荐链路，不提供道路级实时路况、路径导航或到达承诺。
不包含打卡、登录或个人中心；匿名偏好和最近行程保存在本机，精确位置只保留在内存会话中。
当前随包数据明确标注为 POC 审核样本，不能宣称已覆盖光明区全部文旅资源。

2. 地图和高德能力说明

首页使用 uni-app 的微信原生 map 组件展示 GCJ-02 POI marker。微信原生地图渲染层不等同于高德底图；高德 Web Service 仅在开发期离线采集 POI 候选，客户端读取审核后冻结的本地数据，因此不会把用户提供的高德凭证打入客户端包，也不会在用户打开小程序时消耗高德配额。

离线采集规则：

运行 AMAP_WEB_SERVICE_KEY=... corepack pnpm fetch:amap-pois，Key 只存在于单次进程环境。
采集器固定 region=440311、city_limit=true，并对返回记录再次校验 adcode=440311。
候选结果默认写入系统临时目录；不得直接写入 src，需人工剔除企业、内部设施、重复入口和低价值点位后再固化。
Web Service Key 不能写入小程序源码、VITE_* 环境变量、文档或构建产物。
只有高德官方明确允许客户端使用的专用受限 Key，才能在完成平台限制和配额配置后进入客户端。
日志、错误提示、测试截图和文档均不得出现完整 Key。

3. 本地配置

复制 .env.example 为 .env.local。
将项目方确认的微信小程序 AppID 写入 UNI_MP_WEIXIN_APPID。
真机预览或上传前，将根目录 project.config.json 的 appid 从 touristappid 同步为相同的真实 AppID。
远程 AI 为可选能力；留空 VITE_TRAVEL_ASSISTANT_API_BASE_URL 即使用本地 POC 规划器。服务端必须设置 LLM_MODE=real 才会作为真实 AI 展示；mock 仅用于联调演示。
不要在任何客户端环境变量中写入高德 Key、AI API Key 或模型凭证，也不要把 .env.local 提交或外发。

project.config.json 中已有的 AppID 属于模板现状，未经项目方确认不能视为本期正式身份。构建以 manifest.config.ts 读取的本地环境配置为准。

4. 安装和构建

推荐 Node.js 20 LTS 与 pnpm 9，并严格使用锁文件：

corepack pnpm install --frozen-lockfile
corepack pnpm lint
corepack pnpm type-check
corepack pnpm exec vitest run
corepack pnpm build:mp-weixin

运行并保持 corepack pnpm dev:mp-weixin，等待首次编译完成；它会生成微信 IDE 真正需要的 app.json 和页面四件套。prepare:mp-weixin 只创建空目标目录，不是构建命令，通常无需单独运行。

项目的微信开发与生产脚本默认对文件监听使用轮询，用于规避部分 macOS 会话中 EMFILE: too many open files, watch 问题。这不改变构建产物，但开发模式的本机资源占用会略有增加。

开发模式启动后可运行 corepack pnpm verify:mp-weixin，自动检查根目录 IDE 配置、启动页、五个业务页面、三个 tabBar 入口、图标和微信页面四件套是否完整。

开发模式产物位于 dist/dev/mp-weixin；根目录 project.config.json 已将微信开发者工具的 miniprogramRoot 和 srcMiniprogramRoot 指向该目录。先运行开发编译，再用微信开发者工具直接导入项目根目录。

macOS 可在另一个终端执行 corepack pnpm ide:mp-weixin 调起已安装的微信开发者工具。

生产构建产物位于 dist/build/mp-weixin，用于体验版或交付检查；如需直接预览生产包，可在微信开发者工具中单独导入该目录，或在 macOS 运行 corepack pnpm ide:mp-weixin:build。根目录配置固定读取开发产物，只执行生产构建不会更新根目录 IDE 当前加载的内容。

5. 内容替换

当前 src/data/poi/dataset.ts 是 30 个点位的高德候选精选 POC 数据包，封面均为开发占位素材。数据只证明样本交互链路，不构成全域权威清单。正式验收前必须由内容负责人提供并复核：

冻结的全域 POI 基准清单。
每个点位的名称、GCJ-02 坐标、简介、开放时间、官方推荐指数和 1-5 个受控标签；当前 POC 推荐指数不得视为官方配置。
每张图片的来源、版权状态和授权证据。
内容审核、发布状态及审核时间。

占位图只用于运行时和开发降级，不计入正式图片验收。

6. iOS 真机验收

每次测试记录 iPhone 型号、iOS、微信、基础库、网络和构建版本。至少执行：

匿名打开首页时不自动触发位置授权；地图可拖动、缩放。
“全部”及每个分类的 marker 和数量一致。
连续点击 marker，摘要卡始终对应最后点击的 poiId。
摘要进入详情，核对名称、图片、经纬度、简介、开放时间、POC 待审核推荐指数和特色标签。
返回地图后恢复分类、中心、缩放和选中点位。
验证空分类、数据错误、地图错误、点位失效和图片失败降级。
专项检查原生地图层级、点击穿透、安全区和快速操作稳定性。
从“AI 助手”和“路线规划”进入偏好表单，分别验证当前位置快速规划和自选 2–8 个点位规划；拖动 2–10 小时时长，核对完整点位、顺序、时间、转场提示和来源说明。
关闭网络后验证本地规划仍可生成；如启用远程服务，另测合法域名、超时和服务失败提示，确认客户端产物不含服务凭证。
点击“定位到我”，验证首次授权、实时蓝点、拒绝后从设置恢复，以及切换 Tab 后停止前台监听。
定位成功后生成路线，确认首站按当前位置优化；检查本机存储和远程请求均不包含精确坐标。

在项目方尚未提供正式 AppID、真实清权图片和冻结基准清单时，只能判定“样本链路通过”，不能判定正式内容或全域覆盖通过。

6.3 KiB Raw Permalink Blame History Unescape Escape