87 lines
6.3 KiB
Markdown
87 lines
6.3 KiB
Markdown
# 微信小程序构建与验收说明
|
||
|
||
## 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. 本地配置
|
||
|
||
1. 复制 `.env.example` 为 `.env.local`。
|
||
2. 将项目方确认的微信小程序 AppID 写入 `UNI_MP_WEIXIN_APPID`。
|
||
3. 真机预览或上传前，将根目录 `project.config.json` 的 `appid` 从 `touristappid` 同步为相同的真实 AppID。
|
||
4. 远程 AI 为可选能力；留空 `VITE_TRAVEL_ASSISTANT_API_BASE_URL` 即使用本地 POC 规划器。服务端必须设置 `LLM_MODE=real` 才会作为真实 AI 展示；mock 仅用于联调演示。
|
||
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` 问题。这不改变构建产物，但开发模式的本机资源占用会略有增加。
|
||
|
||
开发模式启动后可运行 `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. 从“AI 助手”和“路线规划”进入偏好表单，分别验证当前位置快速规划和自选 2–8 个点位规划；拖动 2–10 小时时长，核对完整点位、顺序、时间、转场提示和来源说明。
|
||
9. 关闭网络后验证本地规划仍可生成；如启用远程服务，另测合法域名、超时和服务失败提示，确认客户端产物不含服务凭证。
|
||
10. 点击“定位到我”，验证首次授权、实时蓝点、拒绝后从设置恢复，以及切换 Tab 后停止前台监听。
|
||
11. 定位成功后生成路线，确认首站按当前位置优化；检查本机存储和远程请求均不包含精确坐标。
|
||
|
||
在项目方尚未提供正式 AppID、真实清权图片和冻结基准清单时，只能判定“样本链路通过”，不能判定正式内容或全域覆盖通过。
|