1880 lines
48 KiB
Markdown
1880 lines
48 KiB
Markdown
# Cappadocia AI Travel Planner 需求文档
|
||
|
||
## 1. 应用概述
|
||
|
||
### 1.1 应用名称
|
||
Cappadocia AI Travel Planner
|
||
|
||
### 1.2 应用描述
|
||
一款专为卡帕多西亚（土耳其内夫谢希尔地区）设计的企业级 AI 驱动旅行规划系统。系统使用 OpenAI 生成个性化行程，并通过 Google Maps APIs 验证所有地点，确保准确性和可靠性。应用提供媲美 Wanderlog 的高端、情感化用户体验，具备精致的视觉设计、流畅的动画和直观的交互。
|
||
|
||
## 2. 核心功能
|
||
|
||
### 2.1 行程规划
|
||
- 基于步骤的向导表单，带实时预览地图
|
||
- 步骤 1：日期选择
|
||
- 步骤 2：兴趣偏好
|
||
- 步骤 3：旅行风格和节奏
|
||
- AI 根据用户输入生成行程建议
|
||
- 所有建议地点通过 Google Places API 验证
|
||
- 未验证的地点自动丢弃
|
||
- 最终行程显示已验证地点及完整详情
|
||
|
||
### 2.2 行程管理
|
||
- 查看详细的每日时间线，采用高端卡片设计
|
||
- 拖放重新排序每日地点
|
||
- 重新排序后自动重新计算路线
|
||
- 显示每日总距离、时长和预估预算
|
||
- 地点之间的旅行时间块，显示驾驶时长
|
||
- 本地保存多个行程
|
||
- 删除已保存行程
|
||
|
||
### 2.3 交互式地图
|
||
- 粘性地图视图与时间线同步（30% 宽度）
|
||
- 将所有地点显示为自定义 SVG 标记
|
||
- 显示地点之间的路线折线
|
||
- 活动标记弹跳动画
|
||
- 点击时间线项目以居中地图并高亮标记
|
||
- InfoWindow 显示地点图片、评分和在 Google Maps 中打开按钮
|
||
- 平滑地图过渡
|
||
|
||
### 2.4 地点信息
|
||
- 大型 16:9 图片为主的卡片布局
|
||
- Google 验证的地点名称和地址
|
||
- 评分显示为徽章
|
||
- AI 生成的描述
|
||
- 预估访问时长
|
||
- 每个活动的时间段，图片上带徽章叠加
|
||
- 悬停效果带高度和柔和阴影动画
|
||
|
||
### 2.5 AI 探索
|
||
- 动态卡帕多西亚探索建议
|
||
- 基于兴趣的推荐
|
||
- 实时 AI 驱动内容生成
|
||
|
||
### 2.6 账户管理
|
||
- 查看所有已保存行程
|
||
- 访问行程历史
|
||
- 管理已保存行程
|
||
- 个人资料管理
|
||
- 偏好设置
|
||
- 隐私和安全控制
|
||
|
||
### 2.7 认证系统
|
||
- 电子邮件和密码登录
|
||
- Google OAuth 登录（OSS Google 登录方式）
|
||
- 记住我功能
|
||
- 密码重置流程
|
||
- 双因素认证支持
|
||
- 跨设备会话管理
|
||
|
||
## 3. 技术架构
|
||
|
||
### 3.1 系统流程
|
||
1. 用户通过基于步骤的向导提交行程表单
|
||
2. OpenAI 生成仅包含地点名称的行程
|
||
3. 对于每个建议地点：
|
||
- 查询 Google Places Text Search API
|
||
- 解析 place_id
|
||
- 获取地点详情
|
||
- 检索照片和评分
|
||
4. 用已验证的 Google 数据替换 AI 建议
|
||
5. 构建最终行程结构
|
||
6. 使用 Google Directions API 计算路线
|
||
7. 渲染带动画的时间线和地图
|
||
8. 将行程存储在 localStorage 中
|
||
|
||
### 3.2 核心架构规则
|
||
- 无内部 POI 数据库
|
||
- OpenAI 仅作为建议引擎
|
||
- Google APIs 作为地点真实性引擎
|
||
- 所有地点必须经过 Google 验证后才能渲染
|
||
- 无法验证的地点将被丢弃
|
||
|
||
### 3.3 服务层结构
|
||
- openaiService.ts：AI 行程生成
|
||
- googleVerificationService.ts：地点验证和解析
|
||
- googlePhotoService.ts：照片 URL 生成
|
||
- directionsService.ts：路线计算
|
||
- itineraryBuilder.ts：合并 AI 和 Google 数据
|
||
- itineraryValidator.ts：验证和去重
|
||
|
||
### 3.4 状态管理
|
||
- Zustand store 用于行程状态
|
||
- localStorage 用于持久化
|
||
- 基于 UUID 的行程标识
|
||
|
||
### 3.5 API 集成
|
||
|
||
#### OpenAI API
|
||
- 系统提示强制仅限卡帕多西亚建议
|
||
- Temperature：0.3 以保持一致性
|
||
- 仅返回地点名称和类别（无坐标）
|
||
- JSON 验证带重试逻辑
|
||
- 允许的区域：Göreme、Uçhisar、Ürgüp、Avanos、Ortahisar、Çavuşin、Derinkuyu、Kaymaklı
|
||
|
||
#### Google Maps JavaScript API
|
||
- 地图渲染和交互
|
||
- 自定义 SVG 标记放置
|
||
- InfoWindow 显示增强内容
|
||
|
||
#### Google Places API
|
||
- Text Search 用于地点解析
|
||
- Place Details 用于完整信息
|
||
- Photo references 用于图片
|
||
|
||
#### Google Directions API
|
||
- 有序地点之间的路线计算
|
||
- 折线生成
|
||
- 距离和时长计算
|
||
|
||
#### Supabase Authentication
|
||
- 用户注册和登录
|
||
- 会话管理
|
||
- 密码重置功能
|
||
- OAuth 集成（Google）
|
||
|
||
#### Supabase Database - 缓存表
|
||
- places_cache：存储已验证的 Google Places 数据
|
||
- directions_cache：存储路线计算结果
|
||
|
||
#### Supabase Storage
|
||
- place-photos：存储地点照片二进制数据的公共存储桶
|
||
|
||
### 3.6 领域特定规则
|
||
- 热气球之旅安排在日出时分（约 05:00）
|
||
- 日落山谷访问在 17:30 之后
|
||
- 每天最多 5 个地点
|
||
- 行程中无重复地点
|
||
- 跨天的地理分布
|
||
- 基于兴趣的包含项：
|
||
- 热气球 → 第 1 天日出
|
||
- 美食 → 传统餐厅
|
||
- 骑马 → Rose Valley 或 Love Valley
|
||
- ATV → Love Valley 或 Sword Valley
|
||
- 地下城市 → Derinkuyu 或 Kaymaklı（仅一个）
|
||
|
||
## 4. 页面结构
|
||
|
||
### 4.1 落地页（/）
|
||
|
||
#### 目标文件
|
||
- 文件：src/pages/LandingPage.tsx
|
||
- 章节：Hero + Features + How It Works + Testimonials + CTA + Footer
|
||
- 样式：Tailwind CSS + 自定义渐变
|
||
|
||
#### 章节 1：Hero 部分
|
||
|
||
**背景：**
|
||
- 基础：卡帕多西亚热气球高分辨率照片
|
||
- 叠加：径向渐变（中心透明 → 边缘深色）
|
||
- 模糊：backdrop-blur-sm
|
||
- 视频替代：卡帕多西亚 15 秒 B-roll（自动播放、静音、循环）
|
||
|
||
**布局：**
|
||
- 全视口高度（100vh）
|
||
- Flex 居中
|
||
- 最大宽度：1200px
|
||
- 内边距：48px
|
||
|
||
**内容：**
|
||
|
||
1. 眉标文本：🎈 Yapay Zeka Destekli Seyahat Planlayıcı
|
||
- 大小：14px
|
||
- 粗细：500
|
||
- 颜色：白色/强调色
|
||
- 背景：rgba(white, 0.1)，圆角全，px-4 py-2
|
||
|
||
2. 主标题：
|
||
- 文本：Kappadokya'da Her Anınızı Kıymetli Yapın
|
||
- 大小：64px（桌面）/ 40px（移动）
|
||
- 粗细：700
|
||
- 颜色：白色
|
||
- 行高：1.2
|
||
- 最大宽度：800px
|
||
|
||
3. 副标题：
|
||
- 文本：Yapay zekamız kişisel tercihlerinize göre mükemmel Kappadokya itinerarısı oluşturur. Balonlar, müzeler, gizli vadiler... Hepsi elinizin altında.
|
||
- 大小：20px（桌面）/ 16px（移动）
|
||
- 粗细：400
|
||
- 颜色：rgba(white, 0.9)
|
||
- 最大宽度：700px
|
||
- 行高：1.6
|
||
|
||
4. CTA 按钮（2 个并排）：
|
||
- 主要：Planlamaya Başla（大小：18px，内边距：16px 32px）
|
||
* 背景：线性渐变（#3B82F6 → #2563EB）
|
||
* 悬停：亮度增加 10%，shadow-2xl
|
||
* 箭头图标：右侧
|
||
|
||
- 次要：Nasıl Çalışır?（透明按钮）
|
||
* 边框：2px 白色
|
||
* 文本：白色
|
||
* 悬停：背景 white/10
|
||
|
||
5. 信任徽章（按钮下方）：
|
||
- ⭐ 4.9 Yıldız | 👥 2.5K+ Gezgin | 🗺️ 50+ Rota
|
||
- 间距：24px 水平
|
||
- 字体：14px，半粗体
|
||
|
||
#### 章节 2：功能
|
||
|
||
**布局：**
|
||
- 3 列网格（移动：1，平板：2）
|
||
- 间隙：32px
|
||
- 内边距：80px 水平，60px 垂直
|
||
- 背景：白色
|
||
|
||
**功能（共 6 个）：**
|
||
|
||
1. 功能：AI-Powered Itineraries
|
||
- 图标：Sparkles（大，48px，#3B82F6）
|
||
- 标题：Zeki Rota Oluşturma
|
||
- 描述：OpenAI tarafından desteklenen yapay zeka, 1000+ Kappadokya noktasını analiz ederek sizin için özel rotalar hazırlar.
|
||
- 强调：图标后面的柔和蓝色背景圆圈
|
||
|
||
2. 功能：Real-Time Map
|
||
- 图标：MapPin（48px，#EC4899）
|
||
- 标题：Canlı Harita & Navigasyon
|
||
- 描述：Google Maps entegrasyonu ile tüm mekanları harita üzerinde görün, mesafeleri hesaplayın ve sıralamayı değiştirin.
|
||
|
||
3. 功能：Smart Scheduling
|
||
- 图标：Clock（48px，#10B981）
|
||
- 标题：Akıllı Zaman Planlama
|
||
- 描述：Günlük tempo tercihlerinize göre, her mekanın ziyaret saati otomatik olarak belirlenir.
|
||
|
||
4. 功能：Drag & Drop
|
||
- 图标：GripVertical（48px，#F59E0B）
|
||
- 标题：Kolay Düzenle
|
||
- 描述：Sürükle-bırak yöntemiyle itinerary'nizin sırasını değiştirin, mesafeler anında güncellenir.
|
||
|
||
5. 功能：Save & Share
|
||
- 图标：Share2（48px，#8B5CF6）
|
||
- 标题：Kaydet & Paylaş
|
||
- 描述：Rotanızı hesabınıza kaydedin, arkadaşlarınızla QR kod veya link aracılığıyla paylaşın.
|
||
|
||
6. 功能：Multi-Day Support
|
||
- 图标：Calendar（48px，#06B6D4）
|
||
- 标题：Çok Günlü Planlar
|
||
- 描述：1 günlük kısa turlardan 2 haftaya kadar uzun gezilere kadar, istediğiniz her duruma rota oluşturun.
|
||
|
||
**卡片设计：**
|
||
- 边框：1px #E5E7EB，rounded-2xl
|
||
- 内边距：32px
|
||
- 悬停：scale-105，shadow-lg，border-primary/20
|
||
- 过渡：300ms cubic-bezier(0.4, 0, 0.2, 1)
|
||
|
||
#### 章节 3：How It Works
|
||
|
||
**布局：**
|
||
- 4 步流程，移动端垂直
|
||
- 背景：线性渐变（#F3F4F6 → #E5E7EB）
|
||
|
||
**步骤（编号 1-4）：**
|
||
|
||
1. Tercihlerinizi Seçin
|
||
- 图标：CheckCircle2
|
||
- 描述：Tarihler, ilgiler ve tempo tercihlerinizi seçin
|
||
|
||
2. Yapay Zeka Planlar
|
||
- 图标：Sparkles
|
||
- 描述：Sistemimiz binlerce veri noktasını analiz eder
|
||
|
||
3. Rotanızı Görüntüleyin
|
||
- 图标：Map
|
||
- 描述：İnteraktif harita ve timeline'da keşfedin
|
||
|
||
4. Seyahat Edin & Tadını Çıkarın
|
||
- 图标：Navigation
|
||
- 描述：Rehberimizle Kappadokya'yı keşfet
|
||
|
||
**连接线：**
|
||
- 虚线，主色，垂直（移动）或水平
|
||
|
||
#### 章节 4：Testimonials / Social Proof
|
||
|
||
**布局：**
|
||
- 轮播或静态 3 列网格
|
||
|
||
**卡片：**
|
||
- 头像：48x48 圆形图片
|
||
- 姓名：16px 粗体
|
||
- 位置：14px 柔和
|
||
- 评分：⭐⭐⭐⭐⭐
|
||
- 引用：16px，斜体，最大宽度 400px
|
||
- 内边距：24px
|
||
- 边框：1px #E5E7EB
|
||
- 圆角：16px
|
||
|
||
**示例推荐：**
|
||
|
||
1. 姓名：Zeynep K. | 位置：İstanbul
|
||
引用：Daha önce Kappadokya'ya gelmiş olsaydım, bu app'i keşfeterdim. Harika!
|
||
|
||
2. 姓名：John D. | 位置：USA
|
||
引用：Best AI travel planner I've used. Better than Wanderlog for Cappadocia specifically.
|
||
|
||
3. 姓名：Ahmet T. | 位置：Ankara
|
||
引用：Zaman ayırmanız gerekmeyecek. Her şey düzenli, pratik ve harika.
|
||
|
||
#### 章节 5：CTA - Call to Action
|
||
|
||
**布局：**
|
||
- 居中，全宽
|
||
- 背景：主色渐变
|
||
- 内边距：80px
|
||
|
||
**内容：**
|
||
|
||
- 标题：Rotanızı Oluşturmaya Hazır mısınız?
|
||
* 大小：40px
|
||
* 粗细：粗体
|
||
* 颜色：白色
|
||
|
||
- 副标题：
|
||
* 文本：Kappadokya'nın en güzel anlarını, yapay zeka rehberliğinde yaşayın.
|
||
* 大小：18px
|
||
* 颜色：rgba(white, 0.9)
|
||
|
||
- 按钮：
|
||
* 文本：Planlamaya Başla (Ücretsiz)
|
||
* 大小：18px
|
||
* 内边距：16px 40px
|
||
* 背景：白色
|
||
* 文本颜色：主色
|
||
* 悬停：shadow-2xl，scale-105
|
||
|
||
- 社会证明：✅ Üyelik yok, Kredi kartı gerekmez
|
||
|
||
#### 章节 6：Footer
|
||
|
||
**布局：**
|
||
- 4 列网格（移动端 1 列）
|
||
- 背景：#1F2937（深色）
|
||
- 颜色：白色
|
||
- 内边距：48px
|
||
|
||
**列：**
|
||
|
||
1. 品牌
|
||
- Logo + 标语
|
||
- 社交链接（图标）
|
||
|
||
2. 产品
|
||
- Planner
|
||
- Explore
|
||
- My Trips
|
||
|
||
3. 公司
|
||
- About
|
||
- Blog
|
||
- Contact
|
||
|
||
4. 法律
|
||
- Privacy
|
||
- Terms
|
||
- Cookies
|
||
|
||
**底部栏：**
|
||
- 版权文本
|
||
- 语言选择器
|
||
|
||
#### 排版层次
|
||
|
||
**Hero：**
|
||
- H1：64px / 40px 移动，700，白色
|
||
- H2：20px，400，white/90%
|
||
- P：14px，500，white/80%
|
||
|
||
**功能：**
|
||
- 标题：24px，600，gray-900
|
||
- 描述：16px，400，gray-600
|
||
|
||
**按钮：**
|
||
- 全部：16px，600，字母间距 0.5px
|
||
|
||
#### 调色板
|
||
- 主色：#3B82F6
|
||
- 次要色：#EC4899
|
||
- 强调色 1：#10B981
|
||
- 强调色 2：#F59E0B
|
||
- 背景：#FAFAFA
|
||
- 深色：#1F2937
|
||
- 边框：#E5E7EB
|
||
|
||
#### 动画
|
||
- Hero 淡入：加载时 600ms ease-out
|
||
- 功能卡片：交错淡入（每个延迟 100ms）
|
||
- CTA 按钮：微妙脉冲动画（连续）
|
||
- 滚动显示：元素进入视口时淡入
|
||
- 推荐轮播：自动滚动（5 秒间隔）
|
||
|
||
#### 响应式断点
|
||
|
||
**移动：<640px**
|
||
- Hero 内边距：24px
|
||
- H1：40px
|
||
- 功能：1 列
|
||
- 间隙：24px
|
||
|
||
**平板：640px - 1024px**
|
||
- H1：48px
|
||
- 功能：2 列
|
||
- 内边距：32px
|
||
|
||
**桌面：>1024px**
|
||
- H1：64px
|
||
- 功能：3 列
|
||
- 内边距：48px
|
||
|
||
#### 可访问性
|
||
- 标题层次：h1 → h2 → h3（正确顺序）
|
||
- 图片 alt 文本：所有图片的描述性文本
|
||
- 颜色对比度：所有文本的 WCAG AA+
|
||
- 焦点环：所有交互元素可见
|
||
- 键盘导航：Tab 顺序逻辑
|
||
- 视频：隐藏字幕 + 文字记录
|
||
|
||
### 4.2 行程规划器（/planner）
|
||
- 现代 Wanderlog 风格的设计体验
|
||
- Hero 部分带全宽卡帕多西亚热气球背景图片和渐变叠加
|
||
- 大而醒目的标题：Hayalinizdeki Kapadokya Gezisini Planla
|
||
- 标题下方的描述性副标题
|
||
- 表单卡片采用偏移设计，出现在 hero 部分上方
|
||
- Z-index 层次：表单卡片叠加在 hero 部分上
|
||
|
||
#### 表单卡片设计
|
||
- 最大宽度：900px（桌面友好）
|
||
- 玻璃态效果：backdrop-blur 带 rgba 背景
|
||
- 柔和阴影：shadow-xl 带环效果
|
||
- 边框半径：32px（现代，圆角）
|
||
- 内边距：48px（宽敞，专业）
|
||
- 标题下方的细渐变分隔线
|
||
|
||
#### 进度指示器
|
||
- 顶部部分：3 步进度条
|
||
- 步骤 1：Tarihler（✓）
|
||
- 步骤 2：İlgiler（当前）
|
||
- 步骤 3：Tercihler（待定）
|
||
- 移动端：折叠进度指示器
|
||
|
||
#### 日期选择（日期选择器）
|
||
- 自定义日期范围选择器（Wanderlog 风格）
|
||
- 并排布局（开始/结束日期）
|
||
- 视觉反馈：
|
||
- 焦点状态：主色光晕
|
||
- 悬停：微妙背景变化
|
||
- 已选择：粗体视觉指示器
|
||
- 自动计算并显示行程时长（例如，5 gün 徽章）
|
||
- 快速预设：Bu hafta、Sonraki hafta、Sonraki ay 按钮
|
||
|
||
#### 兴趣选择
|
||
- 3 列网格布局（移动端：2 列）
|
||
- 卡片：图标 + 文本 + 复选框
|
||
- 图标：Lucide-react 图标（Balloon、History、Hiking 等）
|
||
- 动画：悬停时平滑缩放（1 → 1.05）
|
||
- 已选择状态：
|
||
- 背景：主色带 10% 不透明度
|
||
- 边框：2px 实线主色
|
||
- 图标颜色：主色
|
||
- 可访问性：键盘导航（Tab + Space）
|
||
|
||
#### 每日节奏选择（每日时间表）
|
||
- 水平单选组（3 个选项）
|
||
- 最小边框卡片设计带悬停效果
|
||
- 代表节奏级别的图标
|
||
- 信息工具提示：悬停时显示详细信息（例如，2-3 durak）
|
||
- 视觉差异：每个选项都有小图标
|
||
|
||
#### 附加偏好（偏好文本区域）
|
||
- 占位符带示例：Vejetaryen yemekler, çocuk dostu...
|
||
- 最小高度：120px
|
||
- 字符计数器：右下角（0/500）
|
||
- 调整大小：仅垂直
|
||
- 富文本支持：面向未来的结构（markdown-ready）
|
||
|
||
#### 提交按钮
|
||
- 全宽：是
|
||
- 高度：56px（大，触摸友好）
|
||
- 文本：图标 + 标签（Rota Oluştur 带 Sparkles 图标）
|
||
- 加载状态：
|
||
- 旋转器 + Rotanız Hazırlanıyor...
|
||
- 按钮禁用 + 不透明度 75%
|
||
- 悬停状态：缩放 + 阴影增加
|
||
- 活动状态：轻微缩小（0.98）
|
||
|
||
#### 调色板
|
||
- 主色：#3B82F6（蓝色，信任和宁静）
|
||
- 次要色：#EC4899（粉色，强调）
|
||
- 背景：#FAFAFA（浅灰色）
|
||
- 边框：#E5E7EB（非常浅的灰色）
|
||
- 文本：#1F2937（深灰色）
|
||
- 柔和：#9CA3AF（中灰色）
|
||
|
||
#### 排版
|
||
- 标题（H1）：32px，700 粗细，行高 1.2
|
||
- 标题（H2）：24px，600 粗细
|
||
- 正文：16px，400 粗细，行高 1.5
|
||
- 小：14px，400 粗细
|
||
|
||
#### 响应式断点
|
||
- 移动（< 640px）：单列，100% 宽度表单
|
||
- 平板（640px - 1024px）：优化的 2 列日期选择器
|
||
- 桌面（> 1024px）：带侧边栏展示的完整布局
|
||
|
||
#### 交互性
|
||
- 表单验证：实时反馈（不激进）
|
||
- 错误消息：Toast 通知（sonner）
|
||
- 成功反馈：成功提交时的庆祝动画
|
||
- 防止双重提交：API 调用期间按钮禁用
|
||
|
||
#### 可访问性
|
||
- 所有表单输入的 ARIA 标签
|
||
- 键盘导航：完全支持
|
||
- 颜色对比度：WCAG AA 标准
|
||
- 焦点可见：可预测的 tab 顺序
|
||
|
||
### 4.3 行程视图（/trip/[id]）
|
||
- 带行程名称、日期和分享按钮的标题
|
||
- 布局：时间线（70%）| 粘性地图（30%）
|
||
- 带可折叠部分的每日时间线
|
||
- 带总公里数、时长和预估预算徽章的大型日标题
|
||
- 图片为主的地点卡片（16:9 比例）带时间徽章叠加
|
||
- 卡片右上角的评分徽章
|
||
- 地点之间的旅行时间块（例如，20 分钟车程）
|
||
- 带高度和柔和阴影动画的悬停效果
|
||
- 颜色编码的天数：第 1 天（橙色强调），第 2 天（柔和琥珀色），第 3 天（柔和红色）
|
||
- 拖放重新排序
|
||
- 地图上的路线可视化
|
||
|
||
### 4.4 登录页面（/login）
|
||
|
||
#### 目标文件
|
||
- 文件：src/pages/LoginPage.tsx
|
||
- 认证：Supabase + miaoda-auth-react
|
||
- 表单：react-hook-form + zod 验证
|
||
|
||
#### 布局结构
|
||
|
||
**分割设计（桌面）：**
|
||
- 左侧（50%）：Hero 部分带品牌信息
|
||
- 右侧（50%）：登录表单
|
||
|
||
**移动端：**
|
||
- 单列（表单占全宽）
|
||
|
||
#### 左侧部分（仅桌面）
|
||
|
||
**背景：**
|
||
- 线性渐变（#3B82F6 → #1E40AF）
|
||
|
||
**内容：**
|
||
- Logo：大，居中，白色
|
||
- 标题：Kappadokya'ya Hoşgeldin
|
||
- 副标题：Yapay zeka rehberliğinde unutulmaz deneyimler yarat
|
||
- 优势列表（垂直）：
|
||
* 🚀 AI Powered Planning
|
||
* 🗺️ Real-time Maps
|
||
* 💾 Save Your Plans
|
||
* 👥 Share with Friends
|
||
- 页脚文本：Güvenlik: Verileriniz 256-bit SSL ile korunur
|
||
|
||
#### 右侧部分：登录表单
|
||
|
||
**卡片设计：**
|
||
- 背景：白色
|
||
- 边框：无
|
||
- 阴影：shadow-xl
|
||
- 边框半径：16px
|
||
- 内边距：48px（桌面）/ 32px（移动）
|
||
- 最大宽度：420px
|
||
|
||
**表单部分：**
|
||
|
||
1. 标题：
|
||
- 标题：Giriş Yap
|
||
- 副文本：Rotanızı yönetin ve seyahatinizi planlayın
|
||
|
||
2. 电子邮件输入：
|
||
- 标签：E-posta
|
||
- 类型：email
|
||
- 占位符：name@example.com
|
||
- 验证：实时
|
||
- 错误消息：内联，红色
|
||
|
||
3. 密码输入：
|
||
- 标签：Şifre
|
||
- 类型：password（切换眼睛图标）
|
||
- 占位符：••••••••
|
||
- 忘记密码链接：右对齐，小文本
|
||
|
||
4. 记住我（复选框）：
|
||
- 标签：Beni hatırla
|
||
- 默认：未选中
|
||
|
||
5. 提交按钮：
|
||
- 全宽
|
||
- 高度：44px
|
||
- 文本：Giriş Yap
|
||
- 禁用状态：API 调用期间不透明度 60%
|
||
- 加载：显示旋转器 + Giriş yapılıyor...
|
||
|
||
6. 分隔线：VEYA
|
||
|
||
7. 社交登录按钮：
|
||
- Google 按钮：44px 高度，全宽
|
||
- 图标 + Google ile giriş yap
|
||
- 悬停：微妙阴影增加
|
||
- 实现：OSS Google 登录方式
|
||
|
||
8. 页脚：
|
||
- Hesabınız yok mu? Kayıt ol
|
||
- 链接颜色：主蓝色
|
||
|
||
#### 表单验证
|
||
|
||
**实时验证（onChange）：**
|
||
- 电子邮件：有效格式检查
|
||
- 密码：最少 6 个字符警告
|
||
- 显示状态：✓ 或 ✗ 图标
|
||
|
||
**错误处理：**
|
||
- 无效凭据：E-posta veya şifre hatalı
|
||
- 用户未找到：Bu e-posta ile hesap yok
|
||
- 网络错误：Bağlantı hatası. Lütfen tekrar deneyin
|
||
|
||
**成功流程：**
|
||
- 重定向到 /explore（如果没有引用者）
|
||
- 或重定向到上一页（如果存在引用者）
|
||
- 显示成功 toast：Hoşgeldin, [Name]!
|
||
|
||
#### 样式
|
||
|
||
**表单输入：**
|
||
- 高度：44px
|
||
- 内边距：0 16px
|
||
- 边框：1px #E5E7EB
|
||
- 边框半径：8px
|
||
- 焦点：蓝色边框 + 阴影
|
||
- 字体：16px（防止 iOS 缩放）
|
||
|
||
**标签：**
|
||
- 字体：14px 粗体
|
||
- 下边距：8px
|
||
- 颜色：#1F2937
|
||
|
||
**按钮：**
|
||
- 主要：蓝色背景，白色文本，44px 高度
|
||
- 次要：轮廓样式
|
||
- 禁用：不透明度 50%，无指针事件
|
||
|
||
#### 可访问性
|
||
- 表单标签：<label> 带 htmlFor
|
||
- 错误消息：aria-describedby
|
||
- Tab 顺序：逻辑流程
|
||
- 焦点可见：清晰环
|
||
- 屏幕阅读器：字段描述
|
||
- 移动端：16px 字体防止缩放
|
||
|
||
#### 响应式
|
||
|
||
**移动（<640px）：**
|
||
- 内边距：16px
|
||
- 按钮高度：48px
|
||
- 单列布局
|
||
|
||
**平板：**
|
||
- 内边距：24px
|
||
|
||
**桌面：**
|
||
- 内边距：32px
|
||
- 分割布局（50/50）
|
||
|
||
#### 动画
|
||
- 表单错误：抖动动画
|
||
- 成功 toast：滑入（300ms）
|
||
- 按钮悬停：微妙缩放
|
||
|
||
### 4.5 账户页面（/account）
|
||
|
||
#### 目标文件
|
||
- 文件：src/pages/AccountPage.tsx
|
||
- 认证：Supabase + miaoda-auth-react
|
||
- 表单：react-hook-form + zod 验证
|
||
|
||
#### 布局结构
|
||
|
||
**导航选项卡（顶部）：**
|
||
- Profile
|
||
- Trips
|
||
- Preferences
|
||
- Privacy
|
||
- Logout
|
||
|
||
**移动端：**
|
||
- 选项卡水平滚动
|
||
|
||
#### 选项卡 1：Profile
|
||
|
||
**部分：**
|
||
|
||
a) 头像和基本信息：
|
||
- 头像：120x120px 圆形
|
||
- 上传按钮：Profil fotoğrafını değiştir
|
||
- 下方：全名 + 电子邮件
|
||
- 编辑按钮：铅笔图标
|
||
|
||
b) 个人信息（编辑模式）：
|
||
- 全名输入
|
||
- 电子邮件输入（只读）
|
||
- 电话输入（可选）
|
||
- 简介文本区域（最多 200 个字符）
|
||
- 提交 / 取消按钮
|
||
|
||
c) 账户创建：
|
||
- 日期：Hesap oluşturulma tarihi
|
||
- 显示：15 Ocak 2025
|
||
|
||
#### 选项卡 2：My Trips
|
||
|
||
**网格布局：**
|
||
- 3 列（桌面）/ 2 列（平板）/ 1 列（移动）
|
||
|
||
**每个行程的卡片：**
|
||
- 图片：行程中的 Hero 图片
|
||
- 标题：行程名称
|
||
- 日期：Jan 15-20, 2025
|
||
- 统计：5 days • 12 places
|
||
- 操作：
|
||
* 编辑（铅笔图标）
|
||
* 分享（分享图标）
|
||
* 删除（垃圾桶图标，带确认）
|
||
|
||
**空状态：**
|
||
- 插图：手提箱
|
||
- 标题：Henüz rota yok
|
||
- CTA：İlk rotanızı oluşturun
|
||
|
||
#### 选项卡 3：Preferences
|
||
|
||
**设置列表：**
|
||
|
||
1. 电子邮件通知：
|
||
- 复选框：Öğün önerileri
|
||
- 复选框：Yeni özellikler
|
||
- 复选框：İpuçları ve rehberler
|
||
|
||
2. 语言：
|
||
- 下拉菜单：Türkçe / English
|
||
- 自动：从浏览器检测
|
||
|
||
3. 主题：
|
||
- 单选组：Light / Dark / System
|
||
- 预览：小切换
|
||
|
||
4. 时间格式：
|
||
- 单选组：24h / 12h AM/PM
|
||
|
||
5. 距离单位：
|
||
- 单选组：km / mi
|
||
|
||
#### 选项卡 4：Privacy & Security
|
||
|
||
**部分：**
|
||
|
||
1. 密码：
|
||
- Şifrenizi değiştir 按钮
|
||
- 打开模态框：
|
||
* 当前密码
|
||
* 新密码（带强度指示器）
|
||
* 确认密码
|
||
- 带验证的保存按钮
|
||
|
||
2. 双因素认证：
|
||
- 状态：Devre dışı / Etkinleştirilmiş
|
||
- 启用按钮：打开设置模态框
|
||
- 禁用按钮：带确认
|
||
|
||
3. 活动会话：
|
||
- 设备名称：Chrome on Windows
|
||
- 最后活动：2 minutes ago
|
||
- 位置：Istanbul, Turkey
|
||
- 注销按钮：Bu oturumu kapat
|
||
|
||
4. 数据导出：
|
||
- 按钮：Verilerinizi indir
|
||
- 说明：Tüm rotalarınız ve tercihleriniz
|
||
|
||
5. 删除账户：
|
||
- 警告按钮（红色）
|
||
- 确认模态框：Bu işlem geri alınamaz
|
||
- 复选框：İlkini sil 以启用按钮
|
||
|
||
#### 选项卡 5：Logout
|
||
|
||
- 大型警告区域
|
||
- 按钮：Tüm oturumlardan çık
|
||
- 确认：Diğer cihazlardaki oturumlar kapatılacak
|
||
|
||
#### 样式
|
||
|
||
**表单输入：**
|
||
- 高度：44px
|
||
- 内边距：0 16px
|
||
- 边框：1px #E5E7EB
|
||
- 边框半径：8px
|
||
- 焦点：蓝色边框 + 阴影
|
||
- 字体：16px（防止 iOS 缩放）
|
||
|
||
**标签：**
|
||
- 字体：14px 粗体
|
||
- 下边距：8px
|
||
- 颜色：#1F2937
|
||
|
||
**按钮：**
|
||
- 主要：蓝色背景，白色文本，44px 高度
|
||
- 次要：轮廓样式
|
||
- 危险：红色背景
|
||
- 禁用：不透明度 50%，无指针事件
|
||
|
||
**选项卡：**
|
||
- 活动：粗体文本 + 底部边框（主色）
|
||
- 非活动：柔和文本
|
||
- 过渡：200ms
|
||
|
||
**卡片（行程列表）：**
|
||
- 边框：1px #E5E7EB
|
||
- 圆角：12px
|
||
- 悬停：Shadow-md，border primary/20
|
||
- 内边距：16px
|
||
|
||
#### 验证规则
|
||
|
||
**密码强度：**
|
||
- 最少 8 个字符
|
||
- 大写字母
|
||
- 数字
|
||
- 特殊字符
|
||
- 显示带反馈的进度条
|
||
|
||
**电子邮件：**
|
||
- 有效格式
|
||
- 唯一（如果更改）
|
||
- 验证：如果更改则发送链接
|
||
|
||
#### 可访问性
|
||
|
||
- 表单标签：<label> 带 htmlFor
|
||
- 错误消息：aria-describedby
|
||
- Tab 顺序：逻辑流程
|
||
- 焦点可见：清晰环
|
||
- 屏幕阅读器：字段描述
|
||
- 移动端：16px 字体防止缩放
|
||
|
||
#### 响应式
|
||
|
||
**移动（<640px）：**
|
||
- 内边距：16px
|
||
- 按钮高度：48px
|
||
- 卡片网格：1 列
|
||
|
||
**平板：**
|
||
- 内边距：24px
|
||
- 卡片网格：2 列
|
||
|
||
**桌面：**
|
||
- 内边距：32px
|
||
- 卡片网格：3 列
|
||
|
||
#### 性能
|
||
|
||
- 图片优化：延迟加载头像
|
||
- 表单防抖：电子邮件验证（500ms）
|
||
- 列表虚拟化：许多行程（100+）
|
||
- 代码分割：延迟加载账户页面
|
||
|
||
#### 动画
|
||
|
||
- 选项卡切换：淡入 + 滑动（200ms）
|
||
- 表单错误：抖动动画
|
||
- 成功 toast：滑入（300ms）
|
||
- 删除确认：模态框放大
|
||
|
||
### 4.6 探索页面（/explore）
|
||
|
||
#### 目标文件
|
||
- 文件：src/pages/ExplorePage.tsx
|
||
- 功能：搜索 + 过滤 + 网格画廊 + 详细视图
|
||
|
||
#### 布局结构
|
||
|
||
**1. 搜索和过滤栏**
|
||
|
||
位置：粘性（top: 0，z-index: 40）
|
||
背景：白色带阴影
|
||
内边距：20px 水平，16px 垂直
|
||
|
||
内容（3 个部分）：
|
||
|
||
a) 搜索输入：
|
||
- 图标：搜索（左侧）
|
||
- 占位符：Mekanları, kategorileri, keşifet...
|
||
- 宽度：100%（移动）/ 360px（桌面）
|
||
- 高度：44px
|
||
- 边框半径：24px
|
||
- 焦点：蓝色边框 + 阴影
|
||
- 防抖：300ms
|
||
|
||
b) 过滤按钮（移动端水平滚动）：
|
||
- 芯片：Tümü、Müzeler、Doğa、Aktiviteler、Yemek
|
||
- 样式：最初轮廓，活动时填充
|
||
- 间距：8px 间隙
|
||
- 活动时平滑过渡
|
||
|
||
c) 视图切换（右侧）：
|
||
- 网格视图：4 列（默认）
|
||
- 列表视图：全宽
|
||
- 图标：布局选项（lucide-react）
|
||
|
||
**2. 面包屑（如适用）：**
|
||
- 路径：Anasayfa / Keşfet / Doğa
|
||
- 样式：12px，柔和颜色
|
||
- 交互式：链接工作
|
||
|
||
**3. 主内容区域**
|
||
|
||
背景：#FAFAFA
|
||
内边距：24px
|
||
最大宽度：1400px（居中）
|
||
|
||
**网格布局：**
|
||
|
||
桌面（>1024px）：
|
||
- 列：4
|
||
- 间隙：20px
|
||
|
||
平板（640px - 1024px）：
|
||
- 列：3
|
||
- 间隙：18px
|
||
|
||
移动（<640px）：
|
||
- 列：2
|
||
- 间隙：16px
|
||
|
||
**地点卡片设计：**
|
||
|
||
基本卡片：
|
||
- 纵横比：3:4（纵向）
|
||
- 边框半径：16px
|
||
- 溢出：隐藏
|
||
- 过渡：300ms 全部
|
||
|
||
部分：
|
||
a) 图片区域（70%）：
|
||
- Object-fit：cover
|
||
- 位置：相对
|
||
|
||
叠加：
|
||
- 徽章（右上角）：类别（白色背景，圆角全）
|
||
- 收藏按钮（左上角）：心形图标（切换状态）
|
||
- 评分（左下角）：⭐ 4.5（白色背景带 backdrop-blur）
|
||
|
||
悬停效果：
|
||
- 缩放：1.08
|
||
- 叠加：渐变（透明 → dark/40%）出现
|
||
- CTA 按钮：Detayları Gör 出现在底部
|
||
|
||
b) 内容区域（30%）：
|
||
- 内边距：12px
|
||
- 标题：16px 粗体，截断
|
||
- 描述：13px，柔和，2 行夹紧
|
||
- 间距：8px
|
||
|
||
状态：
|
||
- 默认：边框 #E5E7EB
|
||
- 悬停：Shadow-lg，border primary/30
|
||
- 活动/收藏：边框主色，星形图标填充
|
||
|
||
**4. 详细视图（模态框 / 表单）**
|
||
|
||
触发器：点击卡片
|
||
|
||
模态框结构：
|
||
- 关闭按钮：右上角（X 图标）
|
||
- 背景：渐变背景
|
||
- 宽度：90vw，最大 900px
|
||
- 高度：90vh，最大 800px
|
||
- 边框半径：24px
|
||
|
||
内容部分：
|
||
a) 图片轮播：
|
||
- 多张高分辨率照片
|
||
- 移动端滑动
|
||
- 分页点
|
||
- 全点击时灯箱
|
||
|
||
b) 标题：
|
||
- 标题：32px 粗体
|
||
- 评分：星星 + 计数
|
||
- 保存按钮：轮廓样式
|
||
- 分享按钮：图标
|
||
|
||
c) 信息部分：
|
||
- 地址：位置图标 + 文本（可点击导航）
|
||
- 电话：电话图标 + 文本（可点击）
|
||
- 营业时间：时钟图标 + 文本
|
||
- 网站：链接图标 + 链接
|
||
|
||
d) 描述：
|
||
- 全文（如果 >200 个字符则可展开）
|
||
- 阅读更多 / 显示更少按钮
|
||
|
||
e) 详细信息网格：
|
||
- 时长：2 hours
|
||
- 难度：Easy / Moderate / Hard
|
||
- 距离：5 km from city center
|
||
- 最佳时间：Morning / Evening
|
||
|
||
f) 底部 CTA：
|
||
- Rotaya Ekle 按钮（主要）
|
||
- Detayları Ziyaret Et 按钮（次要）
|
||
|
||
g) 评论部分：
|
||
- 3-4 个示例评论
|
||
- 姓名 + 日期 + 评分 + 文本
|
||
- Tüm yorumları gör 链接
|
||
|
||
**5. 空状态**
|
||
|
||
无结果：
|
||
- 插图：放大镜 + 风景
|
||
- 标题：Aranan bulunamadı
|
||
- 文本：Başka bir şey deneyin
|
||
- 建议：Filtreleri sıfırla 链接
|
||
|
||
无收藏：
|
||
- 插图：心形轮廓
|
||
- 标题：Henüz favori yok
|
||
- 文本：Kalpinize gelen mekanları işaretleyin
|
||
|
||
#### 过滤逻辑
|
||
|
||
类别：
|
||
- Müzeler（博物馆）
|
||
- Doğa & Yürüyüş（自然和徒步）
|
||
- Aktiviteler（活动：热气球、ATV 等）
|
||
- Yemek & İçecek（食品和饮料）
|
||
- Altı（地下）
|
||
- Fotoğraf（摄影）
|
||
|
||
评分过滤器：
|
||
- 4.5+ ⭐
|
||
- 4.0+ ⭐
|
||
- 全部
|
||
|
||
时长过滤器：
|
||
- < 1 hour
|
||
- 1-2 hours
|
||
- 2-4 hours
|
||
- > 4 hours
|
||
|
||
#### 搜索功能
|
||
|
||
用户输入时实时：
|
||
- 防抖：300ms
|
||
- 搜索字段：名称、描述、类别
|
||
- 高亮匹配项
|
||
- 建议下拉菜单（前 5 个结果）
|
||
|
||
#### 排序选项
|
||
|
||
下拉菜单：
|
||
- 相关性（默认）
|
||
- 评分（从高到低）
|
||
- 受欢迎程度
|
||
- 距离（最近优先）
|
||
- 最新添加
|
||
|
||
#### 数据结构
|
||
```typescript
|
||
interface Place {
|
||
id: string
|
||
name: string
|
||
description: string
|
||
category: string
|
||
rating: number
|
||
user_ratings_total: number
|
||
images: string[]
|
||
address: string
|
||
phone?: string
|
||
hours?: string
|
||
duration: number
|
||
difficulty: Easy | Moderate | Hard
|
||
distance_from_center: number
|
||
best_time: Morning | Afternoon | Evening | Any
|
||
reviews: Review[]
|
||
}
|
||
|
||
interface Review {
|
||
author: string
|
||
date: string
|
||
rating: number
|
||
text: string
|
||
avatar?: string
|
||
}
|
||
```
|
||
|
||
#### 样式
|
||
|
||
卡片：
|
||
- 边框：1px #E5E7EB，rounded-2xl
|
||
- 过渡：transform 300ms，shadow 300ms
|
||
- 悬停：transform-gpu（更好的性能）
|
||
- 阴影：shadow-md → shadow-xl 悬停时
|
||
|
||
模态框：
|
||
- 背景：实心 #000 带 50% 不透明度
|
||
- 动画：淡入 + 放大（200ms）
|
||
- 拖动：通过背景点击可关闭
|
||
|
||
#### 交互元素
|
||
|
||
收藏按钮：
|
||
- 未填充：轮廓心形图标
|
||
- 填充：实心心形（主色）
|
||
- 动画：切换时缩放脉冲
|
||
- 持久化：localStorage（临时）+ DB（如果已登录）
|
||
|
||
分享按钮：
|
||
- 选项：复制链接、通过 WhatsApp 分享、电子邮件、二维码
|
||
- 弹出窗口：位于按钮附近
|
||
- 复制反馈：Toast 通知
|
||
|
||
添加到行程按钮：
|
||
- 模态框：如果已认证则选择天数
|
||
- 未认证：重定向到登录
|
||
|
||
#### 可访问性
|
||
|
||
- 图片 alt 文本：描述性
|
||
- 标题：页面标题为 h1，部分标题为 h2
|
||
- 按钮：清晰标签（不仅仅是图标）
|
||
- 键盘：通过卡片的 Tab 导航
|
||
- 焦点可见：焦点时可见环
|
||
- 模态框：焦点陷阱，Escape 关闭
|
||
- ARIA：role=dialog，aria-labelledby 等
|
||
|
||
#### 性能
|
||
|
||
- 图片：延迟加载
|
||
- 网格：100+ 项的虚拟滚动
|
||
- 搜索：防抖
|
||
- 过滤器：实时预览（无页面重新加载）
|
||
- 模态框：代码分割（按需加载）
|
||
|
||
#### 动画
|
||
|
||
- 卡片悬停：平滑缩放 + 阴影
|
||
- 模态框打开：淡入 + 缩放（200ms cubic-bezier）
|
||
- 过滤器过渡：不透明度变化
|
||
- 滚动显示：卡片出现时淡入
|
||
- 加载状态：带脉冲动画的骨架卡片
|
||
|
||
### 4.7 导航栏组件
|
||
|
||
#### 目标文件
|
||
- 文件：src/components/layout/Navbar.tsx
|
||
- 样式：Tailwind CSS，shadcn/ui
|
||
|
||
#### 结构
|
||
|
||
**固定位置：** top-0，z-index 50
|
||
**高度：** 64px
|
||
**背景：** 白色带微妙阴影（shadow-sm）
|
||
**内边距：** 0 24px（桌面）/ 0 16px（移动）
|
||
|
||
**布局：** Flex，space-between
|
||
|
||
#### 左侧部分
|
||
- Logo + 品牌名称（水平布局）
|
||
- Logo：32x32px，SVG 或 PNG
|
||
- 文本：Kappadokya（16px，600 粗细，主色）
|
||
- 链接：到主页（/）
|
||
- 右边距：auto（推动中间内容）
|
||
|
||
#### 中间部分（仅桌面）
|
||
- 导航链接（水平）
|
||
- 链接：Keşfet、Blog、Hakkımızda
|
||
- 样式：14px，柔和颜色，小写
|
||
- 悬停：颜色变为主色，下划线（1px）
|
||
- 间距：32px 间隙
|
||
- 移动端不可见
|
||
|
||
#### 右侧部分
|
||
|
||
**桌面：**
|
||
- 搜索图标（可点击 → 打开搜索模态框）
|
||
- 主题切换（太阳/月亮图标）
|
||
- 通知铃（如果已登录）
|
||
* 徽章：通知数量（红色圆圈）
|
||
* 点击：带最近通知的下拉菜单
|
||
- 用户菜单（如果已登录）：
|
||
* 头像：36x36px 圆形
|
||
* 点击：带选项的下拉菜单：
|
||
- Profile
|
||
- My Trips
|
||
- Settings
|
||
- Logout
|
||
- 登录按钮（如果未登录）：
|
||
* 文本：Giriş Yap
|
||
* 样式：轮廓
|
||
* 大小：44px 高度
|
||
* 链接：/login
|
||
|
||
**移动端：**
|
||
- 搜索图标
|
||
- 汉堡菜单（3 条线）
|
||
* 点击：打开侧边栏导航
|
||
* 包含：所有链接 + 用户菜单项
|
||
|
||
#### 下拉菜单
|
||
|
||
**用户菜单下拉菜单：**
|
||
- 位置：绝对，top-100%，right: 0
|
||
- 宽度：240px
|
||
- 背景：白色
|
||
- 边框：1px #E5E7EB
|
||
- 边框半径：12px
|
||
- 阴影：shadow-lg
|
||
- Z-index：60
|
||
- 项目：
|
||
* 标题：用户名 + 电子邮件（无操作）
|
||
* 分隔线
|
||
* Profilim → /account/profile
|
||
* Rotalarım → /account/trips
|
||
* Tercihler → /account/preferences
|
||
* 分隔线
|
||
* Çıkış Yap → 注销操作
|
||
- 动画：淡入 + 缩放（100ms）
|
||
|
||
**通知下拉菜单：**
|
||
- 位置：类似于用户菜单
|
||
- 宽度：300px
|
||
- 高度：最大 400px（可滚动）
|
||
- 项目（最多 5 个）：
|
||
* 每个通知的小卡片
|
||
* 图标（铃、勾、警报等）
|
||
* 标题 + 消息
|
||
* 时间：2 min ago
|
||
* 点击：导航到相关页面
|
||
- 页脚链接：Tüm bildirimleri gör
|
||
|
||
**搜索模态框：**
|
||
- 全屏叠加（移动）/ 居中模态框（桌面）
|
||
- 输入：大，自动聚焦
|
||
- 占位符：Mekan, rota, rehber ara...
|
||
- 结果：用户输入时实时
|
||
- 最近搜索：如果没有输入任何内容
|
||
- 类别：按类型分组结果
|
||
* Places
|
||
* Your trips
|
||
* Blog articles
|
||
* Users（如果有社交功能）
|
||
- 关闭：Escape 键或背景点击
|
||
|
||
#### 移动汉堡菜单
|
||
|
||
**侧边栏导航：**
|
||
- 位置：固定，left: 0，top: 0
|
||
- 宽度：100% 或 80%（取决于设计）
|
||
- 高度：100vh
|
||
- 背景：白色
|
||
- Z-index：55（在叠加之上，在模态框之下）
|
||
- 动画：从左侧滑入（300ms）
|
||
|
||
**内容：**
|
||
- 关闭按钮：右上角（X 图标）
|
||
- Logo：顶部（居中或左对齐）
|
||
- 导航链接（垂直）：
|
||
* Home
|
||
* Explore
|
||
* Blog
|
||
* About
|
||
* 间距：项目之间 12px
|
||
- 分隔线
|
||
- 如果已登录：
|
||
* 用户信息：头像 + 姓名 + 电子邮件
|
||
* 账户链接（与下拉菜单相同）
|
||
- 如果未登录：
|
||
* Giriş Yap 按钮（全宽）
|
||
* Kayıt Ol 按钮（全宽，轮廓）
|
||
|
||
**背景：**
|
||
- 位置：固定，全屏
|
||
- 背景：rgba(0,0,0,0.5)
|
||
- Z-index：50
|
||
- 点击：关闭侧边栏
|
||
- 动画：淡入（300ms）
|
||
|
||
#### 样式
|
||
|
||
**链接：**
|
||
- 颜色：#6B7280（柔和）
|
||
- 悬停：#3B82F6（主色）
|
||
- 过渡：color 200ms
|
||
- 下划线（悬停时）：2px 实线主色
|
||
|
||
**头像：**
|
||
- 大小：36x36px（导航栏）
|
||
- 边框半径：50%
|
||
- Object-fit：cover
|
||
- 后备：彩色背景上的首字母
|
||
|
||
**图标：**
|
||
- 大小：20px（大多数图标）
|
||
- 颜色：#6B7280（默认）/ #3B82F6（活动）
|
||
- 光标：指针
|
||
- 悬停：缩放 1.1，颜色变化
|
||
|
||
**按钮：**
|
||
- 登录按钮：44px 高度，px-6，rounded-lg
|
||
- 样式：border-2 border-primary，text-primary，hover:bg-primary/5
|
||
|
||
#### 响应式
|
||
|
||
**桌面（>1024px）：**
|
||
- 完整导航栏可见
|
||
- 中间部分：可见
|
||
- 用户菜单：下拉菜单
|
||
- 汉堡：隐藏
|
||
|
||
**平板（640px-1024px）：**
|
||
- Logo 大小：较小（28px）
|
||
- 中间部分：隐藏或折叠
|
||
- 汉堡：可见
|
||
- 右侧部分：图标 + 用户菜单
|
||
|
||
**移动（<640px）：**
|
||
- 完整汉堡菜单
|
||
- 仅 logo + 图标（搜索、菜单）
|
||
- 无中间部分
|
||
- 无用户菜单下拉菜单
|
||
|
||
#### 粘性行为
|
||
|
||
**向下滚动：**
|
||
- 导航栏保持固定在顶部
|
||
- 出现/增加微妙阴影
|
||
- Logo 保持可见
|
||
|
||
**向上滚动：**
|
||
- 与上述相同（始终可见）
|
||
|
||
#### 可访问性
|
||
|
||
- Logo 链接：aria-label=Home
|
||
- 导航链接：语义 <nav> 标签
|
||
- 图标：图标上的 aria-label
|
||
- 下拉菜单：role=menu，aria-expanded
|
||
- 移动菜单：aria-label=Navigation menu
|
||
- 关闭按钮：Escape 键 + 点击
|
||
|
||
#### 动画
|
||
|
||
所有过渡：200ms ease
|
||
- 链接悬停：颜色淡入
|
||
- 下拉菜单打开：淡入 + 放大
|
||
- 移动侧边栏：从左侧滑入
|
||
- 背景：淡入
|
||
|
||
## 5. 全局组件
|
||
|
||
### 5.1 页面标题组件
|
||
|
||
**用法：** 每个页面的顶部
|
||
|
||
**内容：**
|
||
- 标题（h1）
|
||
- 面包屑（可选）
|
||
- 操作按钮（可选）
|
||
|
||
**示例：**
|
||
- 页面：My Trips
|
||
- 面包屑：Home / Account / Trips
|
||
- 按钮：+ New Trip、Import、Export
|
||
|
||
### 5.2 加载骨架
|
||
|
||
**用法：** 数据获取时
|
||
|
||
**类型：**
|
||
- 卡片骨架：多个灰色占位符
|
||
- 文本骨架：带脉冲动画的线条
|
||
- 头像骨架：圆形占位符
|
||
- 表格骨架：占位符行
|
||
|
||
**动画：** 脉冲（不透明度 0.5 → 1 → 0.5）
|
||
|
||
### 5.3 空状态组件
|
||
|
||
**用法：** 无数据时
|
||
|
||
**属性：**
|
||
- icon：Lucide 图标
|
||
- title：字符串
|
||
- description：字符串
|
||
- action：按钮或链接
|
||
- image：可选插图
|
||
|
||
**示例：**
|
||
- 图标：手提箱
|
||
- 标题：No trips yet
|
||
- 描述：Create your first itinerary
|
||
- 按钮：Create now
|
||
|
||
### 5.4 错误边界组件
|
||
|
||
全局错误捕获
|
||
- 显示友好的错误消息
|
||
- 显示错误详细信息（仅开发）
|
||
- 重新加载按钮
|
||
- 主页链接
|
||
|
||
### 5.5 面包屑组件
|
||
|
||
**属性：**
|
||
- items：[{label, href}]
|
||
- separator：/（可自定义）
|
||
|
||
**样式：**
|
||
- 字体：12px，柔和
|
||
- 链接：悬停时下划线
|
||
- 响应式：移动端隐藏（仅显示当前页面）
|
||
|
||
### 5.6 徽章组件
|
||
|
||
shadcn/ui 中已有，但变体：
|
||
- 默认：填充背景
|
||
- 轮廓：仅边框
|
||
- 次要：较浅背景
|
||
- 大小：小（12px）、中（14px）、大（16px）
|
||
|
||
### 5.7 卡片组件
|
||
|
||
shadcn/ui 中已有，但确保一致：
|
||
- 内边距：16px - 32px（可扩展）
|
||
- 边框：1px #E5E7EB
|
||
- 边框半径：12px - 16px
|
||
- 阴影：shadow-sm → shadow-lg（悬停时）
|
||
|
||
## 6. UI/UX 要求
|
||
|
||
### 6.1 设计系统
|
||
|
||
#### 调色板
|
||
- 主色：#3B82F6
|
||
- 主色深：#1E40AF
|
||
- 次要色：#EC4899
|
||
- 成功绿：#10B981
|
||
- 警告橙：#F59E0B
|
||
- 错误红：#EF4444
|
||
- 背景：#FAFAFA
|
||
- 表面：#FFFFFF
|
||
- 边框：#E5E7EB
|
||
- 文本主要：#1F2937
|
||
- 文本次要：#6B7280
|
||
- 文本柔和：#9CA3AF
|
||
- 卡帕多西亚橙：#ea580c
|
||
- 深色：#1f2937
|
||
- 柔和背景：#fafaf9
|
||
- 强调：#f97316
|
||
|
||
#### 排版
|
||
- 现代间距比例
|
||
- 清晰的视觉层次
|
||
- 高端字体选择
|
||
|
||
#### 组件
|
||
- 圆角 2xl 卡片
|
||
- 深度柔和阴影
|
||
- 选定元素上的玻璃态效果
|
||
- 微妙渐变
|
||
|
||
### 6.2 动画和交互
|
||
- Framer Motion 用于平滑过渡
|
||
- 数据获取期间的骨架加载器
|
||
- 带模糊效果的图片延迟加载
|
||
- 悬停效果：高度和柔和阴影动画
|
||
- 地图上的活动标记弹跳动画
|
||
- 点击时间线项目时平滑地图过渡
|
||
|
||
### 6.3 时间线组件
|
||
- 带可折叠部分的可滚动日列
|
||
- 带摘要徽章（距离、时长、预算）的大型日标题
|
||
- TimelineItem 卡片显示：
|
||
- 大型 16:9 Google Place 照片
|
||
- 图片上的时间徽章叠加
|
||
- 地点名称
|
||
- 评分徽章（右上角）
|
||
- 简短描述
|
||
- 地点之间的旅行时间块
|
||
- 点击交互：
|
||
- 在地点上居中地图
|
||
- 缩放到级别 14
|
||
- 用弹跳动画高亮标记
|
||
- 打开 InfoWindow
|
||
|
||
### 6.4 地图组件
|
||
- 粘性定位（30% 宽度）
|
||
- 与时间线滚动同步
|
||
- 地点的自定义 SVG 标记
|
||
- 显示路线的折线
|
||
- 带图片、评分和在 Google Maps 中打开按钮的 InfoWindow
|
||
- 响应式缩放和平移
|
||
- 平滑过渡
|
||
|
||
### 6.5 加载状态
|
||
- AI 生成期间的进度条
|
||
- 带模糊地图背景的设计您的旅程动画
|
||
- 地点卡片的骨架屏幕
|
||
- 图片延迟加载模糊效果
|
||
|
||
### 6.6 移动体验
|
||
- 底部表单地图界面
|
||
- 可滑动的日选项卡
|
||
- 底部固定优化路线按钮
|
||
- 完全响应式布局
|
||
- 触摸优化交互
|
||
|
||
## 7. 数据模型
|
||
|
||
### 7.1 OpenAI 响应格式
|
||
```
|
||
{
|
||
days: [
|
||
{
|
||
day: 1,
|
||
items: [
|
||
{
|
||
place_name: Göreme Open Air Museum,
|
||
category: museum,
|
||
estimated_duration_minutes: 120,
|
||
description: Short explanation
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7.2 已验证地点对象
|
||
- place_id
|
||
- name
|
||
- lat
|
||
- lng
|
||
- rating
|
||
- formatted_address
|
||
- photo_reference
|
||
- image_url
|
||
- description
|
||
- category
|
||
- estimated_duration_minutes
|
||
|
||
### 7.3 最终行程结构
|
||
```
|
||
{
|
||
id: UUID,
|
||
days: [
|
||
{
|
||
day: 1,
|
||
total_distance: 25 km,
|
||
total_duration: 6 hours,
|
||
estimated_budget: $150,
|
||
items: [
|
||
{
|
||
place_id: ChIJ...,
|
||
name: Göreme Open Air Museum,
|
||
lat: 38.6431,
|
||
lng: 34.8347,
|
||
rating: 4.6,
|
||
image_url: https://maps.googleapis.com/...,
|
||
formatted_address: Göreme, Nevşehir,
|
||
description: UNESCO World Heritage site,
|
||
start_time: 09:00,
|
||
end_time: 11:00
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 8. 性能优化
|
||
|
||
### 8.1 缓存策略
|
||
- 在 Supabase places_cache 表中缓存 Google Places 解析结果
|
||
- 在 Supabase directions_cache 表中缓存 Google Directions API 响应
|
||
- 在 Supabase Storage place-photos 存储桶中缓存地点照片二进制数据
|
||
- 避免对相同地点的重复 API 调用
|
||
- 首次获取后存储照片 URL
|
||
|
||
### 8.2 优化技术
|
||
- 防抖表单提交
|
||
- 带模糊效果的延迟加载图片
|
||
- 优化 React 重新渲染
|
||
- 对时间线项目使用 React.memo
|
||
- 如果需要，虚拟化长列表
|
||
- Framer Motion 性能优化
|
||
|
||
## 9. 错误处理
|
||
|
||
### 9.1 API 失败
|
||
- OpenAI 超时后备带重试
|
||
- Google API 失败处理带用户通知
|
||
- 服务不可用时的优雅降级
|
||
|
||
### 9.2 数据验证
|
||
- OpenAI 响应的 JSON 验证
|
||
- 删除重复地点
|
||
- 防止重叠时间段
|
||
- 验证 place_id 解析
|
||
|
||
### 9.3 用户反馈
|
||
- 清晰的错误消息
|
||
- 处理期间的加载状态
|
||
- 成功确认
|
||
|
||
## 10. 安全要求
|
||
|
||
### 10.1 API 密钥管理
|
||
- OpenAI API 密钥仅存储在服务器端
|
||
- Google Maps API 密钥受域限制
|
||
- 所有敏感密钥在环境变量中
|
||
- 永远不要在客户端代码中暴露密钥
|
||
|
||
### 10.2 数据保护
|
||
- 验证所有用户输入
|
||
- 存储前清理数据
|
||
- 安全的 localStorage 使用
|
||
|
||
### 10.3 认证安全
|
||
- Supabase 处理认证
|
||
- 密码哈希和加密
|
||
- 安全会话管理
|
||
- 双因素认证支持
|
||
- 所有通信仅 HTTPS
|
||
|
||
## 11. 未来可扩展性
|
||
|
||
### 11.1 数据库集成
|
||
- localStorage 结构设计为易于迁移
|
||
- 基于 UUID 的标识支持数据库键
|
||
- 数据模型与关系型/NoSQL 数据库兼容
|
||
- Supabase 缓存表用于 API 响应优化
|
||
|
||
### 11.2 可扩展性
|
||
- 模块化服务架构
|
||
- 关注点分离
|
||
- 易于添加新功能或区域
|
||
- 可插拔 AI 提供商
|
||
|
||
## 12. 技术实现细节
|
||
|
||
### 12.1 文件结构
|
||
- 目标文件：src/pages/LandingPage.tsx
|
||
- 目标文件：src/pages/PlannerPage.tsx
|
||
- 目标文件：src/pages/ExplorePage.tsx
|
||
- 目标文件：src/pages/LoginPage.tsx
|
||
- 目标文件：src/pages/AccountPage.tsx
|
||
- 目标文件：src/components/layout/Navbar.tsx
|
||
- 技术栈：React + TypeScript + Tailwind CSS + shadcn/ui
|
||
- 现有依赖：@dnd-kit、lucide-react、sonner（toast）、react-hook-form、zod
|
||
- 认证：Supabase + miaoda-auth-react
|
||
- 数据库：Supabase（缓存表）
|
||
- 存储：Supabase Storage（地点照片）
|
||
|
||
### 12.2 数据库架构
|
||
|
||
#### places_cache 表
|
||
- id：uuid 主键
|
||
- place_name_normalized：text（小写，修剪 - 用作查找键）
|
||
- place_id：text NOT NULL
|
||
- name：text
|
||
- formatted_address：text
|
||
- lat：float8
|
||
- lng：float8
|
||
- rating：float4
|
||
- user_ratings_total：int4
|
||
- photo_reference：text
|
||
- created_at：timestamptz DEFAULT now()
|
||
- updated_at：timestamptz DEFAULT now()
|
||
- place_name_normalized 上的唯一约束
|
||
- RLS 禁用（通过 service_role 密钥访问）
|
||
|
||
#### directions_cache 表
|
||
- id：uuid 主键
|
||
- cache_key：text UNIQUE NOT NULL（格式：origin_lat,lng|dest_lat,lng）
|
||
- response：jsonb
|
||
- created_at：timestamptz DEFAULT now()
|
||
- RLS 禁用（通过 service_role 密钥访问）
|
||
|
||
#### 迁移文件
|
||
- 文件路径：supabase/migrations/00004_add_cache_tables.sql
|
||
|
||
## 13. 其他要求
|
||
|
||
### 13.1 地点缓存层重构
|
||
|
||
**目标文件：** supabase/functions/generate-itinerary/index.ts
|
||
|
||
**实现要求：**
|
||
|
||
1. Supabase 客户端初始化：
|
||
- 在 Edge Function 内部使用 Supabase service_role 客户端
|
||
- 从 https://esm.sh/@supabase/supabase-js@2 导入 createClient
|
||
- 使用 Deno.env.get('SUPABASE_URL') 和 Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')
|
||
|
||
2. 地点验证循环优化（步骤 2，调用 Google Places Text Search 的位置）：
|
||
|
||
在为每个项目调用 Google Places API 之前：
|
||
|
||
a) 规范化地点名称：
|
||
- 转换为小写
|
||
- 修剪空格
|
||
|
||
b) 查询 places_cache 表：
|
||
- 执行查询：SELECT * FROM places_cache WHERE place_name_normalized = normalizedName LIMIT 1
|
||
|
||
c) 缓存命中处理：
|
||
- 如果找到缓存行，直接使用它（完全跳过 Google API 调用）
|
||
- 在代码中记录注释：// Cache HIT - skipping Google API call
|
||
|
||
d) 缓存未命中处理：
|
||
- 如果未找到，按原样调用 Google Places Text Search
|
||
- 然后将结果 INSERT 到 places_cache 中，使用规范化名称
|
||
- 在代码中记录注释：// Cache MISS - fetching from Google and caching
|
||
|
||
3. 缓存优势：
|
||
- 相同地点（例如 Göreme Open Air Museum）只会从 Google 获取一次
|
||
- 之后永久从缓存提供
|
||
- 显著减少 API 调用次数和响应时间
|
||
|
||
### 13.2 路线缓存层重构
|
||
|
||
**目标文件：** supabase/functions/get-directions/index.ts
|
||
|
||
**实现要求：**
|
||
|
||
1. Supabase 客户端初始化：
|
||
- 在 Edge Function 内部使用 Supabase service_role 客户端
|
||
- 从 https://esm.sh/@supabase/supabase-js@2 导入 createClient
|
||
- 使用 Deno.env.get('SUPABASE_URL') 和 Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')
|
||
|
||
2. 路线计算优化：
|
||
|
||
在调用 Google Directions API 之前：
|
||
|
||
a) 构建缓存键：
|
||
- 格式：`${origin}|${destination}|${waypoints?.join(',') ?? ''}`
|
||
- origin 和 destination 为坐标字符串（如 38.6431,34.8347）
|
||
- waypoints 为可选的中间点数组
|
||
|
||
b) 查询 directions_cache 表：
|
||
- 执行查询：SELECT * FROM directions_cache WHERE cache_key = cacheKey LIMIT 1
|
||
|
||
c) 缓存命中处理：
|
||
- 如果找到缓存行且 created_at 距今不超过 30 天，直接返回缓存的 response jsonb
|
||
- 在代码中记录注释：// Cache HIT - returning cached directions
|
||
|
||
d) 缓存未命中或过期处理：
|
||
- 如果未找到或缓存已过期（超过 30 天），调用 Google Directions API
|
||
- 然后将结果 UPSERT 到 directions_cache 中（使用 cache_key 作为唯一键）
|
||
- 在代码中记录注释：// Cache MISS or expired - fetching from Google and caching
|
||
|
||
3. 缓存优势：
|
||
- 相同路线（相同起点、终点和途经点）只会从 Google 计算一次
|
||
- 30 天内重复请求直接从缓存返回
|
||
- 显著减少 API 调用次数和响应时间
|
||
- 避免重复计算相同路线
|
||
|
||
### 13.3 卡帕多西亚景点数据预填充
|
||
|
||
**目标文件：** supabase/migrations/00005_seed_cappadocia_places.sql
|
||
|
||
**实现要求：**
|
||
|
||
1. 创建新的 Supabase 迁移文件，用于预填充 places_cache 表
|
||
|
||
2. 插入卡帕多西亚最常见景点的真实数据，包括：
|
||
- Göreme Open Air Museum
|
||
- Uçhisar Castle
|
||
- Derinkuyu Underground City
|
||
- Kaymaklı Underground City
|
||
- Pasabag (Monks Valley)
|
||
- Devrent Valley (Imagination Valley)
|
||
- Love Valley
|
||
- Rose Valley (Güllüdere)
|
||
- Pigeon Valley
|
||
- Zelve Open Air Museum
|
||
- Avanos Pottery
|
||
- El Nazar Church
|
||
- Dark Church (Karanlık Kilise)
|
||
- Çavuşin Village
|
||
|
||
3. 数据要求：
|
||
- 使用真实的 Google place_id（从 Google Maps 获取）
|
||
- 包含准确的经纬度坐标
|
||
- 包含真实的评分数据
|
||
- place_name_normalized 设置为小写英文名称
|
||
|
||
4. 预填充优势：
|
||
- 首次用户请求也能命中缓存
|
||
- 消除冷启动时的 Google API 调用成本
|
||
- 提升首次用户体验的响应速度
|
||
|
||
### 13.4 地点照片缓存层重构
|
||
|
||
**目标文件：** supabase/functions/get-place-photo/index.ts
|
||
|
||
**实现要求：**
|
||
|
||
1. Supabase Storage 存储桶创建：
|
||
- 创建名为 place-photos 的公共存储桶
|
||
- 配置为公共访问
|
||
|
||
2. Supabase 客户端初始化：
|
||
- 在 Edge Function 内部使用 Supabase service_role 客户端
|
||
- 从 https://esm.sh/@supabase/supabase-js@2 导入 createClient
|
||
- 使用 Deno.env.get('SUPABASE_URL') 和 Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')
|
||
|
||
3. 照片缓存逻辑：
|
||
|
||
在调用 Google Places Photo API 之前：
|
||
|
||
a) 构建存储路径：
|
||
- 格式：`photos/${photo_reference}.jpg`
|
||
- photo_reference 为 Google Places API 返回的照片引用 ID
|
||
|
||
b) 检查文件是否存在：
|
||
- 使用 supabase.storage.from('place-photos').getPublicUrl(path) 获取公共 URL
|
||
- 尝试 HEAD 请求检查文件是否存在
|
||
|
||
c) 缓存命中处理：
|
||
- 如果文件存在，直接返回重定向到 Supabase Storage 公共 URL
|
||
- 在代码中记录注释：// Cache HIT - redirecting to storage URL
|
||
|
||
d) 缓存未命中处理：
|
||
- 如果文件不存在，从 Google Places Photo API 获取图片
|
||
- 将图片上传到 Supabase Storage，content-type 设置为 image/jpeg
|
||
- 然后返回重定向到 Supabase Storage 公共 URL
|
||
- 在代码中记录注释：// Cache MISS - fetching from Google and uploading to storage
|
||
|
||
4. 缓存优势：
|
||
- 相同照片只会从 Google 获取一次
|
||
- 之后永久从 Supabase Storage 提供
|
||
- 消除重复的 Google Places Photo API 调用成本
|
||
- 提升照片加载速度和稳定性
|
||
|
||
## 14. 参考文件
|
||
|
||
1. 设计模型：ChatGPT Image 13 Şub 2026 12_19_59.png |