【腾讯位置服务开发者征文大赛】我用JSAPI GL Skill动动嘴皮实现了智能找车位助手

# CHANGELOG

## v0.1.0 — 2026-04-19（首次迭代：MVP 可用版本）

### 🎯 背景

从一句话需求「出门找不到停车位 / 不知道哪个停车场实惠好停 / 希望知道周边免费临停」出发，两小时内从 0 交付一个可运行的 H5 原型。

### ✨ 核心功能（MVP）

#### 目的地与定位
- **真实 POI 搜索**：接入腾讯地图 Place Suggestion API（含 JSONP + SK 签名）
- **浏览器定位**：`getCurrentPosition` + 腾讯逆地址解析，一键"以我为中心"
- **智能模糊匹配**（三层兜底）：
  - 中文：精确 / 前缀 / 子串 / 跳字子序列（"三屯" → 三里屯）
  - 拼音：首字母精确 / 前缀 / 子串 / 跳字子序列（"sltql" → 三里屯太古里）
  - 城市 / 地址 包含匹配
- **命中高亮**：匹配字符用蓝色加粗展示
- **本地地标库**：内置 170+ 全国常见地标（13 个城市 · 商圈/机场/火车站/景区/大学）

#### 停车点展示
- **地图 marker**：腾讯地图 JS API GL，三色区分停车类型（蓝=停车场、橙=路内、绿=免费临停、灰=已满）
- **一句话推荐**：顶部醒目横幅直接告知最优选择
- **三种排序**：综合最优 / 最便宜 / 最近
- **免费临停筛选**：一键只看免费/限时免费点位
- **底部可上滑面板**：42% ↔ 70% 两档高度

#### 详情与交互
- **详情卡**：空位、步行距离、评分、收费、标签、限制、用户点评
- **一键导航**：调用腾讯地图 URI API（routeplan）
- **UGC 点评**：评分 + 文字，本地持久化
- **拍照记位**：停车时拍照，图片 base64 存储
- **停车记忆**：定位 + 备注 + 照片
- **带我回车**：步行导航模式

#### 偏好与个性化
- **车型偏好**：轿车 / SUV / 新能源
- **必须充电桩**：加分项
- **避开低限高**：<2.1m 车库降权
- **偏好感知排序**：综合最优会根据偏好调整打分；不匹配项给出黄色提示

#### 记账与统计
- **费用记录**：每次停车登记费用
- **月度统计**：柱状图展示每月次数 / 花费 / 平均单次
- **CSV 导出**：Excel 兼容（含中文 BOM）

#### 工程质量
- **实时空位模拟**：每 60s 自动刷新，±15% 波动
- **目的地切换自动重建周边停车点**（基于种子随机，稳定可复现）
- **localStorage 持久化**：停车记录 / 偏好 / UGC 点评
- **PWA 基础 meta**：图标、主题色、Apple 全屏、描述
- **自检面板**（dev）：左下角 🔧 按钮，实时检测关键元素是否渲染、是否被遮挡

### 🧪 测试覆盖

- **类型检查**：`tsc --noEmit` 通过
- **端到端交互**：23/23（搜索 / 排序 / 详情 / 点评 / 记账 / 偏好 / 导航 / 刷新 / 关闭）
- **模糊匹配**：13/13（5 个中文跳字 + 3 个拼音跳字 + 5 个基础匹配）
- **集成命令**：`npm run test` 一键跑全部

### 🐛 迭代中修复的真实 bug

1. **底部面板遮挡右侧按钮**：z-index 冲突，面板 z-20 吃掉了按钮的点击事件 → 按钮提升到 z-40
2. **搜索接口静默失败**：腾讯返回 199（未开 WebServiceAPI）时用户看不到任何反馈 → 加黄色提示条 + 自动降级本地匹配
3. **SK 签名校验**：腾讯控制台开启"SK 校验"后必须携带 sig → 实现前端 md5 签名（path + 排序参数 + SK）
4. **路径 bug**：`services/ranking.ts` 错误引用 `./utils/geo` → 改为 `../utils/geo`

### 🏗️ 技术栈

| 层 | 选型 |
|---|---|
| 构建 | Vite 5 |
| 框架 | React 18 + TypeScript 5.6 |
| 样式 | Tailwind CSS 3.4 |
| 状态 | Zustand 4 + localStorage |
| 地图 | 腾讯地图 JS API GL（动态加载） |
| WebService | JSONP + MD5 签名（SK 校验） |
| 测试 | Playwright + 系统 Chrome |

### 📁 最终目录结构


space1/
├── README.md                      使用文档
├── CHANGELOG.md                   本文件
├── 智能找车位助手-需求描述.md       PRD 文档
├── package.json                   含 test / test:e2e / test:fuzzy / typecheck
├── .env.example                   Key & SK 配置模板
├── index.html                     PWA meta
├── tests/
│   ├── e2e.mjs                    23 项交互 e2e
│   └── fuzzy-match.mjs            13 项模糊匹配
└── src/
    ├── App.tsx                    主页面
    ├── store.ts                   Zustand 全局状态
    ├── types.ts                   类型定义
    ├── mock.ts                    动态生成周边停车点 + 种子随机
    ├── data/
    │   └── landmarks.ts           170+ 全国地标（带拼音）
    ├── services/
    │   └── ranking.ts             排序/评分/推荐/月度统计/CSV
    ├── utils/
    │   ├── geo.ts                 距离、费用估算
    │   ├── md5.ts                 MD5（用于腾讯 sig 签名）
    │   └── qqmap.ts               SDK 加载 + Place/Geo API + 导航 + 定位
    └── components/
        ├── MapView.tsx            地图主视图
        ├── SearchBar.tsx          搜索（在线 + 本地模糊 + 高亮）
        ├── SortTabs.tsx           排序 tab + 免费筛选
        ├── SpotList.tsx           底部停车点列表
        ├── SpotDetail.tsx         详情弹层（点评/拍照/记位）
        ├── MyRecords.tsx          我的停车（记录/统计/CSV）
        ├── PreferenceModal.tsx    偏好设置
        └── DevPanel.tsx           开发期自检面板


### 📊 代码规模

- 20 个 TypeScript 文件
- ~2500 行业务代码
- 0 lint 错误 / 0 类型错误
- 136 个 npm 依赖（含 Playwright）

### 🚀 下次迭代建议

- [ ] 接入真实停车场空位 API（停简单 / ETCP / 政府开放数据）
- [ ] UGC 免费车位众包 + 后端审核
- [ ] 车位预订（接入 ETCP）
- [ ] 拼音库用 `pinyin-pro` 自动生成，不再手写
- [ ] 命中高亮扩展到在线 API 结果
- [ ] 部署到 EdgeOne Pages / CloudBase
- [ ] 后端代签 SK（替代前端 md5，消除泄露风险）

# prompt 如下：

我现在遇到了一个日常生活难题，需要你帮我制定一个解决这个生活难题的需求描述用于AI编码生成应用。
我的生活难题是这样的，每次开车出去都找不到停车位，也不知道最近的停车场是哪个且是否停满，甚至我还想知道哪个停车场最实惠且体验最好。
当然，如果能知道周边有免费的临时停车位或者可以路边临停的位置，那更好了。

# 智能找车位助手 —— AI 编码应用需求描述文档

> 版本：v1.0  
> 适用场景：交付给 AI 编码工具（Cursor / CodeBuddy / Claude Code 等）生成可运行的应用原型

---

## 一、背景与痛点

作为一名经常自驾出行的城市司机，我在到达目的地前后常常遇到以下困扰：

1. **找不到车位**：到达目的地后只能盲目绕圈，浪费时间和油费，还容易造成拥堵。
2. **不知道最近的停车场在哪儿**：即使地图能搜到，也看不到实时是否已停满。
3. **不知道哪个停车场最"值"**：价格、步行距离、进出难度、是否有充电桩、是否好停（车位宽窄）等信息散落在各处。
4. **免费资源被埋没**：很多商圈周边其实有**限时免费临停**、**夜间免费路边位**、**商场消费赠停**，但没人告诉我。

**一句话概括**：我希望出门前和到达前，有一个助手能直接告诉我「**现在，去哪儿停最快、最便宜、最省心**」。

---

## 二、目标用户与使用场景

### 目标用户
- 城市有车一族（25–55 岁）
- 对停车费敏感、时间敏感的通勤族与周末出行家庭
- 新手司机（对路边临停规则不熟悉）

### 典型使用场景
| 场景 | 用户动作 | 期望结果 |
|---|---|---|
| 出发前规划 | 输入目的地 | 看到目的地周边 500m 内所有可选停车点排名 |
| 到达前 1 公里 | 打开 App | 自动推荐当前最优停车场并导航过去 |
| 绕圈找位 | 快速查"附近免费临停" | 地图上直接显示可路边临停点位 |
| 停车后 | 记录停车位置、费用 | 离开时一键导航回车、查看花费 |

---

## 三、核心功能清单

### 3.1 MVP（最小可用版本，必须有）

#### F1. 目的地搜索与周边停车点聚合
- 输入目的地（或选"当前位置附近"）
- 在地图上展示周边 **1 公里范围内** 的停车资源，包括：
  - 收费停车场（地下 / 地上 / 路内）
  - 免费/限时免费临停点
  - 允许路边停车的路段

#### F2. 停车场详情卡
每个停车点展示：
- 名称、距离目的地步行距离、预计步行时间
- **实时空位数 / 总车位数**（数据源见第六节）
- 收费标准（白天 / 夜间 / 过夜封顶）
- 综合评分（1–5 星，基于用户评价）
- 标签：`便宜` `好停` `有充电桩` `新能源优先` `消费赠停` `24 小时` `限高 2.1m`
- 用户真实点评（最近 3 条）

#### F3. 智能排序与一键推荐
提供三种排序模式：
1. **最省钱**（按预估停车费用）
2. **最近步行距离**
3. **综合最优**（价格 × 空位率 × 评分 × 距离 加权）

顶部给出一句话推荐：  
> "推荐去 XX 商场 B2，步行 3 分钟，现在还有 42 个空位，首小时 5 元。"

#### F4. 免费/临停资源地图图层
- 独立图层高亮显示免费临停点
- 标注限制信息：**可停时段、时长上限、是否工作日限行**
- 用户可上传/修正这些信息（UGC 众包）

#### F5. 一键导航
- 选中某停车场 → 调用高德 / 百度 / 腾讯地图进行路径导航

---

### 3.2 进阶功能（有了更好）

#### F6. 到达自动签到 & 停车记忆
- 检测到车辆静止超过 5 分钟自动记录停车位置（含楼层、区域号，支持拍照+语音备注）
- 返回时一键"带我回车"

#### F7. 费用记账与报销
- 自动或手动记录每次停车花费
- 月度统计、导出 Excel（方便公司报销）

#### F8. 社区点评与爆料
- 用户上传「实测好停车场」「避雷停车场」
- 爆料隐藏免费车位（审核后入库）

#### F9. 车位预订（若接入第三方）
- 支持接入 ETCP、停简单等平台实现提前锁定车位

#### F10. 个性化偏好
- 车型设置：SUV / 新能源 / 限高敏感
- 偏好：优先便宜 / 优先近 / 必须带充电桩

---

## 四、非功能性需求

| 维度 | 要求 |
|---|---|
| **平台** | 优先微信小程序（无需下载，打开即用）；次选 H5 + iOS/Android 原生 |
| **响应速度** | 地图加载 < 2s，搜索结果返回 < 1s |
| **定位精度** | 误差 < 10m，支持室内楼层识别（可后期） |
| **离线能力** | 最近一次停车位置需本地缓存（防断网） |
| **隐私** | 位置数据仅在使用时上传；停车记录默认本地存储，云端同步需用户授权 |
| **数据更新** | 实时空位数据刷新频率 ≥ 60s/次 |

---

## 五、数据模型草图

// 停车点
interface ParkingSpot {
  id: string;
  name: string;
  type: 'garage' | 'roadside' | 'free_temp';  // 停车场/路内/免费临停
  location: { lat: number; lng: number };
  address: string;
  totalSlots: number;
  availableSlots: number;        // 实时空位
  pricing: {
    firstHour: number;
    perHourAfter: number;
    dailyCap?: number;
    freeMinutes?: number;        // 免费时长
    nightFree?: boolean;
  };
  tags: string[];                // ['24h', 'ev_charging', 'low_clearance']
  rating: number;                // 0-5
  reviewCount: number;
  restrictions?: string;         // "工作日 7-9 点禁停"
  photos: string[];
  updatedAt: number;
}

// 用户停车记录
interface ParkingRecord {
  id: string;
  userId: string;
  spotId: string;
  startTime: number;
  endTime?: number;
  cost?: number;
  locationNote?: string;         // "B2-A 区-37 号"
  photoUrl?: string;
}

// 用户点评
interface Review {
  spotId: string;
  userId: string;
  rating: number;
  content: string;
  tags: string[];                // ['好停', '便宜', '难找']
  createdAt: number;
}


---
## 六、关键技术点与数据来源

1. **地图与导航**：高德地图开放平台（含停车场 POI、实时空位接口）或腾讯位置服务
2. **实时空位**：
   - 一线城市可接入 **停简单 / ETCP / 捷顺** 等停车场管理系统开放 API
   - 政府开放数据平台（部分城市已开放路内泊位实时数据）
3. **免费临停数据**：初期以 UGC 众包 + 运营人工补录为主
4. **定位**：微信小程序 `wx.getLocation` / 浏览器 `navigator.geolocation`
5. **推荐算法**（综合最优）：
   
   score = w1 × (1/price) + w2 × availability_ratio 
         + w3 × rating + w4 × (1/walking_distance)
   
   权重可配置，默认 `w1=0.3, w2=0.3, w3=0.2, w4=0.2`

---

## 七、主要交互流程


[打开应用]
     ↓
[自动定位 / 输入目的地]
     ↓
[地图展示周边停车点 + 一句话推荐]
     ↓
用户点击某点 → [查看详情卡] → [一键导航]
     ↓
[到达后自动记录位置]
     ↓
[离开时记账 → 可选点评]


---

## 八、MVP 验收标准

- [ ] 用户输入任意城市地址，能在地图上看到 ≥ 5 个周边停车点
- [ ] 每个停车点至少展示：名称、距离、价格、空位（可为模拟数据）
- [ ] 能按"最便宜/最近/综合"三种方式排序
- [ ] 免费临停点以不同颜色图标单独展示
- [ ] 点击"导航"能成功唤起第三方地图
- [ ] 能记录并查看我的上一次停车位置

---

## 九、交付物建议

1. 可运行的微信小程序 / H5 原型
2. 使用 **模拟数据（mock）** 跑通全流程，数据接口预留，便于后续替换为真实 API
3. 代码结构清晰，分层：`pages / components / services / mock / utils`
4. README 中说明：如何切换 mock 与真实 API、如何接入高德 key

---

## 十、一句话 Prompt（可直接粘给 AI 编码工具）

> 请用 **微信小程序 + 云开发**（或 React + Vite + TypeScript 的 H5）实现一个名为"**智能找车位助手**"的应用。核心功能：输入目的地后，在地图上展示周边 1 公里内的停车场、路边停车位和免费临停点；每个点展示实时空位、价格、评分；支持按"最便宜/最近/综合最优"排序并给出一句话推荐；支持一键导航、停车位置记忆、费用记账。第一版使用 mock 数据，预留真实 API 接口（高德地图 + 停简单）。UI 现代简洁，以地图为主视图，底部为可上滑的停车点列表。具体需求详见附件 PRD。

# 克隆仓库到本地
git clone https://github.com/TencentLBS/TencentMap_jsapi_skills.git

# 进入目录
cd TencentMap_jsapi_skills

# 输入测试问题：

帮我使用腾讯地图 JSAPI GL 开发一个地图应用:
1. 地图中心点设置在北京天安门
2. 添加一个自定义标记点
3. 点击标记显示信息窗体

# prompt 指令如下：
请结合腾讯地图 以H5 的形态来完成
# 没错，就是这么随意的指令

# 安装依赖
npm install --cache /tmp/npm-cache

# 启动开发服务器
npm run dev
# → http://localhost:5173/