gmTouringMiniApp/docs/微信小程序构建与验收说明.md

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

## 1. 当前交付边界

- 本项目是光明区文旅全域地图、POI 数字化展示、本地行程规划与真实定位打卡 POC；AI 模型接入留待后续版本。
- 目标端为微信小程序，当前只要求在一台实际 iOS 设备验证。
- 用户主动授权后，地图可显示前台实时位置；当前位置快速规划要求使用 5 分钟内的位置快照优化首站和游览顺序。
- 行程由随包 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. 本地配置

1. 复制 `.env.example` 为 `.env.local`。
2. 将项目方确认的微信小程序 AppID 写入 `UNI_MP_WEIXIN_APPID`。
3. 真机预览或上传前，确认根目录 `project.config.json` 的 `appid` 与相同的真实 AppID 一致。
4. 本期 `createPlan` 已固定使用本地 POC 规划器，`server/` 及远程适配层仅作为后续 AI 接入预留，不纳入本期验收。
5. 不要在任何客户端环境变量中写入高德 Key、AI API Key 或模型凭证，也不要把 `.env.local` 提交或外发。

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

## 4. 安装和构建

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

```bash
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` 问题。这不改变构建产物，但开发模式的本机资源占用会略有增加。

微信产物启用了 `lazyCodeLoading: "requiredComponents"`，页面只注入实际使用的自定义组件，以减少小程序启动开销。该能力需要微信基础库 2.11.1 及以上；目标基础库尚未冻结时，应在 iOS 真机验收所用微信版本中确认兼容性。

开发模式启动后可运行 `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、微信、基础库、网络和构建版本。至少执行：

1. 匿名打开首页时不自动触发位置授权；地图可拖动、缩放。
2. “全部”及每个分类的 marker 和数量一致。
3. 连续点击 marker，摘要卡始终对应最后点击的 `poiId`。
4. 摘要进入详情，核对名称、图片、经纬度、简介、开放时间、POC 待审核推荐指数和特色标签。
5. 返回地图后恢复分类、中心、缩放和选中点位。
6. 验证空分类、数据错误、地图错误、点位失效和图片失败降级。
7. 专项检查原生地图层级、点击穿透、安全区和快速操作稳定性。
8. 从“文旅助手”和“路线规划”进入偏好表单，分别验证当前位置快速规划和自选 2–8 个点位规划；拖动 2–10 小时时长，核对完整点位、顺序、时间、转场提示和来源说明。
9. 关闭网络后验证本地规划仍可生成；确认当前业务入口不调用远程 AI，客户端产物不含模型凭证。
10. 点击“定位到我”，验证首次授权、实时蓝点、拒绝后从设置恢复，以及切换 Tab 后停止前台监听。
11. 定位成功后生成路线，确认首站按当前位置优化；检查本机存储不包含精确坐标，且调试面板没有远程规划请求。
12. 确认全部已发布 POI 的详情页均展示打卡入口，未发布或已下线 POI 不开放新打卡；从详情进入打卡页后，仅在点击按钮时重新请求一次位置，分别验证隐私授权、200 米范围内成功、范围外、精度不足、边界不确定和重复打卡。
13. 检查首次打卡增加 10 积分并解锁首枚徽章，重启后记录仍存在；“清除本机打卡数据”不得删除路线或偏好。
14. 扫描本机打卡存储，确认不包含经纬度、定位精度或轨迹；开发者工具模拟位置仅用于流程测试，正式成功验收必须使用 iOS 真机现场定位。

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