Initial commit: gmTouringMiniApp project
This commit is contained in:
周瑞哲
@@ -0,0 +1,86 @@
|
||||
# 微信小程序构建与验收说明
|
||||
|
||||
## 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 规划器。
|
||||
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 助手”和“路线规划”进入偏好表单，生成半日及一日行程，核对点位、顺序、时间、转场提示和来源说明。
|
||||
9. 关闭网络后验证本地规划仍可生成；如启用远程服务，另测合法域名、超时和服务失败提示，确认客户端产物不含服务凭证。
|
||||
10. 点击“定位到我”，验证首次授权、实时蓝点、拒绝后从设置恢复，以及切换 Tab 后停止前台监听。
|
||||
11. 定位成功后生成路线，确认首站按当前位置优化；检查本机存储和远程请求均不包含精确坐标。
|
||||
|
||||
在项目方尚未提供正式 AppID、真实清权图片和冻结基准清单时，只能判定“样本链路通过”，不能判定正式内容或全域覆盖通过。
|
||||
@@ -0,0 +1,60 @@
|
||||
# 高德 POI 离线采集与数据快照说明
|
||||
|
||||
## 1. 本次结果
|
||||
|
||||
- 采集时间：2026-07-30（Asia/Shanghai）。
|
||||
- 接口：高德 Web Service POI 2.0 关键字搜索。
|
||||
- 固定区域：深圳市光明区，`region=440311`、`city_limit=true`。
|
||||
- 查询：4 组文旅类型扫描及 21 个补召回关键词，共 62 次请求。
|
||||
- 原始结果：1185 条；按高德 POI ID 合并 475 条重复后为 710 个候选。
|
||||
- 本地发布：人工剔除企业、餐饮、普通培训机构、内部设施、重复入口和低价值点位后，精选 30 个 POC 点位。
|
||||
|
||||
这 30 个点位用于提升地图探索密度，不是项目方签字确认的权威全域基准清单。正式版本仍需内容负责人逐点确认纳入范围、名称、坐标、分类和来源。
|
||||
|
||||
## 2. 数据流
|
||||
|
||||
```text
|
||||
高德 POI 2.0
|
||||
-> 光明区严格过滤
|
||||
-> 高德 ID 去重
|
||||
-> 文旅价值与主资源人工筛选
|
||||
-> POC 字段映射
|
||||
-> src/data/poi/dataset.ts 本地冻结数据
|
||||
-> 微信小程序随包读取
|
||||
```
|
||||
|
||||
微信客户端不调用高德 Web Service，不携带 Key，也不依赖运行时网络获取 POI。
|
||||
|
||||
## 3. 重新采集
|
||||
|
||||
Key 只通过单次进程环境变量提供；默认输出到系统临时目录，不写入源码：
|
||||
|
||||
```bash
|
||||
AMAP_WEB_SERVICE_KEY=... corepack pnpm fetch:amap-pois
|
||||
corepack pnpm test:amap-fetch
|
||||
```
|
||||
|
||||
如指定 `--output`，采集器会拒绝写入 `src`、`scripts`、`test` 或 `tests`。候选 JSON 仍不得直接进入客户端，必须经过人工筛选和数据审核。
|
||||
|
||||
## 4. 字段口径
|
||||
|
||||
| 项目字段 | 当前来源与处理 |
|
||||
|---|---|
|
||||
| 名称 | 高德候选名称，已有业务点保留稳定业务 ID；别名单独保存 |
|
||||
| 经纬度 | 高德返回 GCJ-02 坐标，并通过光明区 POC 包络校验 |
|
||||
| 地址 | 高德候选地址；缺失时使用明确的待核验说明 |
|
||||
| 简介 | POC 原创说明，只描述候选用途，不冒充景点官方介绍 |
|
||||
| 开放时间 | 一律为“待确认”；高德营业时间不直接发布 |
|
||||
| 推荐指数 | POC 默认值，页面标注“待审核”；高德评分不参与换算 |
|
||||
| 特色标签 | 映射到项目受控标签库，每个点位 1-5 个 |
|
||||
| 图片 | 使用包内统一占位图；未使用高德图片 URL |
|
||||
| 来源标识 | 仅保存 `amap:<poiId>`，不保存 Key、请求 URL或带凭证参数 |
|
||||
|
||||
## 5. 正式发布门槛
|
||||
|
||||
- 内容负责人冻结全域基准清单，并记录纳入与排除理由。
|
||||
- 对同名、别名、父子景区和 30-50 米近邻点进行人工去重。
|
||||
- 逐点确认坐标、地址、简介、开放时间、标签及官方推荐指数。
|
||||
- 为每张真实图片补齐来源、授权证据和审核记录。
|
||||
- 在 iOS 微信真机逐个验证全部 marker 可点击且详情不串点。
|
||||
- 发布 POI 超过 50 个或出现明显遮挡时，先实现聚合或视野内渲染。
|
||||
Reference in New Issue
Block a user