92 lines
7.3 KiB
Markdown
92 lines
7.3 KiB
Markdown
# 微信小程序构建与验收说明
|
||
|
||
## 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、真实清权图片和冻结基准清单时，只能判定“样本链路通过”，不能判定正式内容或全域覆盖通过。
|