🚀 快速开始指南

已完成的部分 ✅

我已经为您创建了完整的足迹管理系统代码：

✅ api/add-city.js       - 核心 API 函数（负责提交到 GitHub）
✅ admin.html            - 管理界面（用户输入表单）
✅ vercel.json           - Vercel 配置文件
✅ package.json          - Node.js 依赖配置
✅ .env.local            - 本地环境变量模板

快速预览 👀

想立即看到界面效果？有两种方式：

方式 1：在线静态预览（立即可用）

直接打开项目文件：

admin-preview.html

这是一个完整的界面展示，你可以看到最终成品的样子。

方式 2：部署到 Vercel（完整功能）

1. 创建 GitHub Token
   • 访问：https://github.com/settings/tokens
   • 点击 “Generate new token (classic)”
   • 勾选 repo 权限
   • 生成并复制 Token
2. 访问 Vercel
   • 打开：https://vercel.com
   • 用 GitHub 账号登录
3. 导入项目
   • New Project → Import Git Repository
   • 选择 pea1ce.github.io
   • Framework Preset 选择 Other
   • Build Command 输入：

     bundle install && bundle exec jekyll build
     

   • Output Directory 输入：_site

4. 配置环境变量

   在 Vercel Dashboard → 项目 Settings → Environment Variables 中添加：

   Key	Value
   GITHUB_TOKEN	你的 GitHub Token（第1步生成的）
   API_AUTH_TOKEN	你的管理密码（自己设定，比如：mypassword123）
   GITHUB_OWNER	pea1ce
   GITHUB_REPO	pea1ce.github.io
   GITHUB_BRANCH	master

5. 部署
   • 点击 Deploy
   • 等待 3-5 分钟构建完成
6. 测试功能
   • 访问：https://your-project.vercel.app/admin.html
   • 在表单中填写信息
   • 输入管理密码（第4步中的 API_AUTH_TOKEN）
   • 点击提交
   • 检查 GitHub 仓库，应该能看到新的 commit

完整的工作流程 🔄

┌─────────────────────────────────────────────────────────┐
│           用户在 admin.html 填写表单                      │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    表单验证 & 发送到 API (/api/add-city)                 │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    API 验证 Token & 读取 GitHub 数据                     │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    合并新城市到 travel_cities.json                       │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    提交到 GitHub（自动创建 commit）                      │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    GitHub Webhook 触发 Vercel 重新部署                   │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    Jekyll 重新构建网站（2-3 分钟）                       │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────┐
│    足迹地图自动显示新城市 ✅                             │
└─────────────────────────────────────────────────────────┘

功能特点 ✨

✅ 智能表单

• 国内城市：三级结构支持（省份 → 城市）
• 国外国家：直接添加国家名
• 可选字段：游记链接、旅行备注

✅ 安全认证

• Token 保护，防止未授权访问
• 浏览器本地存储，自动记住密码
• 输入清理，防止 XSS 攻击

✅ 自动同步

• 数据直接提交到 GitHub
• 保留完整的 Git 版本历史
• 可随时回滚到任何历史版本

✅ 零成本

• Vercel 免费额度足够使用
• GitHub API 免费调用
• 无需额外付费

示例用法

添加中国城市

用户：Oliver
国家：China
省份：浙江
城市：杭州市
备注：2024-03-15，参加技术大会

添加国外国家

用户：Oliver
国家：Japan
备注：2023-11-20，秋叶季旅行

常见问题

Q：提交数据后多久能看到地图更新？ A：GitHub 提交后，Vercel 通常 2-3 分钟内完成重新部署。刷新页面即可看到新数据。

Q：可以批量导入城市吗？ A：当前版本是逐个添加。如需批量导入，可后续增加 CSV 导入功能。

Q：管理密码忘记了怎么办？ A：在浏览器控制台执行：

localStorage.removeItem('apiToken')

然后刷新页面，下次提交时重新输入。

Q：GitHub Token 过期了怎么办？ A：

1. 在 GitHub 生成新 Token
2. 更新 Vercel 环境变量
3. 重新部署项目

下一步优化

部署完成后，可以考虑的增强功能：

1. 地图点击添加 - 在足迹地图上直接点击添加城市
2. 批量导入 - 支持 CSV/Excel 批量导入
3. 照片管理 - 为每个城市添加照片
4. 游记关联 - 自动关联博客文章
5. 统计面板 - 显示访问过的国家/城市总数
6. 分享功能 - 生成足迹分享卡片

获取帮助

如遇问题，请查看：

• 详细文档：LOCAL_SETUP.md
• 原始计划：/home/he/.claude/plans/foamy-humming-charm.md

祝你使用愉快！如有任何问题，欢迎继续提问。🎉