---
description:
globs:
alwaysApply: false
---
# 开发指南和最佳实践

本项目的开发规范和编码最佳实践指南。

## 代码结构规范

### HTML结构
- 使用语义化HTML5标签
- 保持良好的代码缩进（2个空格）
- 添加必要的meta标签和SEO信息
- 使用中文注释说明复杂逻辑

### CSS组织
- 采用BEM命名规范
- 按功能模块组织样式
- 使用CSS自定义属性（CSS变量）
- 移动端优先的响应式设计

### JavaScript规范
- 使用现代ES6+语法
- 采用模块化编程思想
- 函数命名使用驼峰命名法
- 变量和函数使用中文注释

## 错误处理规范

### API调用错误处理
地图API加载需要完善的错误处理机制，参考 [travel-guide.html](mdc:travel-guide.html) 中的实现。

### 网络状态监控
实施离线检测和网络恢复处理，确保用户体验的连续性。

## 性能优化指南

### 图片优化
- 使用适当的图片格式
- 实施懒加载机制
- 提供不同分辨率的图片版本
- 压缩图片文件大小

### JavaScript优化
- 避免全局变量污染
- 使用事件委托减少事件监听器
- 实施防抖和节流机制
- 异步加载非关键脚本

## 响应式设计原则

### 移动端优先
基础样式针对移动端设计，然后通过媒体查询适配更大屏幕。

### 触摸友好设计
- 按钮最小点击区域44px×44px
- 适当的元素间距
- 支持滑动手势
- 避免悬停效果依赖

## 测试规范

### 浏览器兼容性测试
- Chrome (最新版本)
- Safari (最新版本)
- Firefox (最新版本)
- Edge (最新版本)

### 功能测试清单
- 地图正常加载和显示
- POI标记点击交互
- 路线规划功能
- 响应式布局适配
- 动画效果流畅性
- 错误处理机制

## 常见问题解决方案

### 地图相关问题
1. 地图不显示：检查API密钥和网络连接
2. POI位置错误：验证坐标系统和坐标值
3. 路线规划失败：检查起点终点坐标有效性

### 编码问题
避免在SVG中使用中文字符，防止btoa编码错误。使用英文字母或数字替代。
