Birdmap Local Fullstack (No-RAG MVP)

本项目已包含前后端完整本地可运行版本：

• 后端：FastAPI + PostgreSQL + pgvector
• 前端：React + TypeScript + Vite（已接 API）
• RAG：暂不实现检索与生成，只保留接口与数据结构

当前能力

• 页面：
  • 半球地图页：/（Three.js 半球体地图）
  • 经典地图页：/classic（原二维地图）
  • 地点详情页：/location/:id（Tab：概览 / 鸟种图鉴 / 拍摄指南占位）
  • 鸟种百科页：/birds（基础搜索与分类）
  • 行程规划页：/plan（占位）
  • 热点详情侧栏（地点信息 + 本月鸟种 + 拍摄贴士）
  • AI 问答面板（调用 /api/chat 占位逻辑）
• API：
  • GET /healthz
  • GET /api/spots?month=4&type=wetland&bounds=lng1,lat1,lng2,lat2
    • 支持 scope=global（融合 iNaturalist 全球热点）
  • GET /api/spots/heatmap?month=4&type=wetland
  • GET /api/spots/:id?month=4
  • GET /api/spots/:id/recent（ebird_ 地点会优先走 eBird 实时，失败时本地兜底）
  • GET /api/birds?search=鹤&category=涉禽
  • GET /api/birds/taxonomy（目->科->种树结构）
  • GET /api/birds/:id/intro（iNaturalist Wikipedia 摘要优先，Wikipedia 中/英文兜底）
  • GET /api/birds/:id/photo（iNaturalist 代理 + DB 缓存）
  • GET /api/birds/:id/audio（xeno-canto v3 代理 + DB 缓存）
  • GET /api/birds/:id/distribution?month=4
  • GET /api/birds/:id/info?month=4（聚合：基础信息+图+音+分布，支持降级）
  • GET /api/birds/:id
  • GET /api/weather/layers（天气层列表）
  • GET /api/weather/tiles/{layer}/{z}/{x}/{y}.png（OpenWeather 瓦片代理）
  • POST /api/chat（占位逻辑，非 RAG）
  • GET /api/chat/suggestions
• RAG 预留：
  • rag_chunks 表（pgvector）
  • /api/chat 的 sources 字段

本地启动（Docker，一键）

如果你要启用真实高德地图，请先在当前 shell 设置 Key：

export VITE_AMAP_KEY=你的高德Web端Key

未设置时会自动降级为静态地图模式（其余功能正常）。

docker compose up --build

启动后访问：

• 前端：http://localhost:5173
• 后端文档：http://localhost:8000/docs
• 健康检查：http://localhost:8000/healthz

停止服务：

docker compose down

重置数据库（清空并重建）：

docker compose down -v
docker compose up --build

分开启动（可选）

1) 仅后端

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2) 仅前端

cd frontend
npm install
export VITE_AMAP_KEY=你的高德Web端Key   # 可选，不设则静态地图兜底
npm run dev

快速验证

curl "http://localhost:8000/api/spots?month=4"

curl "http://localhost:8000/api/spots/loc_beidaihe?month=4"

curl -X POST "http://localhost:8000/api/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "北戴河4月拍什么",
    "context": {
      "month": 4,
      "location_id": "loc_beidaihe",
      "location_name": "北戴河"
    }
  }'

导入 eBird 数据

先在 shell 配置 key（或写入 .env）：

export EBIRD_API_KEY=你的eBirdKey
export XENO_API_KEY=你的xeno-canto-v3-key  # 可选，未设置时 /api/birds/:id/audio 返回空列表
export OPENWEATHER_API_KEY=你的OpenWeatherKey  # 可选，未设置时天气层不可用

说明：

• EBIRD_API_KEY 还会被 /api/spots/:id/recent 使用（仅当 :id 是 ebird_ 前缀地点）。

在容器内执行导入脚本（推荐）：

docker exec bird-api python /app/scripts/import_ebird_recent.py \
  --api-key "$EBIRD_API_KEY" \
  --region CN \
  --back 7 \
  --max-results 500 \
  --locale zh \
  --with-images

仅预览不入库：

docker exec bird-api python /app/scripts/import_ebird_recent.py \
  --api-key "$EBIRD_API_KEY" \
  --region CN \
  --back 7 \
  --max-results 100 \
  --dry-run

如需对已导入的 ebird_ 鸟种再次做中文名/图片补全：

docker exec bird-api python /app/scripts/enrich_ebird_birds.py \
  --api-key "$EBIRD_API_KEY" \
  --with-images

初始化外部 API 结构（P0）

如果你在已有数据库上升级（不是新建库），需要执行一次新增表脚本：

docker exec bird-db psql -U postgres -d bird -f /docker-entrypoint-initdb.d/03_external_api_schema.sql

回填 species_mapping（后续跨 API 查询会用到）：

docker exec bird-api python /app/scripts/backfill_species_mapping.py
docker exec bird-api python /app/scripts/backfill_species_mapping.py --rebuild-conflicts

说明：

• --rebuild-conflicts 会重建 species_mapping_conflicts（用于记录同学名多 bird_id 冲突）。

回填 distribution_grid（鸟种分布网格）：

docker exec bird-api python /app/scripts/backfill_distribution_grid.py --grid-size 0.5

增量重算（只算某个月/某个鸟种）：

docker exec bird-api python /app/scripts/backfill_distribution_grid.py --month 4
docker exec bird-api python /app/scripts/backfill_distribution_grid.py --bird-id bird_red_crowned_crane
docker exec bird-api python /app/scripts/backfill_distribution_grid.py --month 4 --bird-id bird_red_crowned_crane

API 回归检查（最小集）

python scripts/regression_api_check.py --base-url http://localhost:8000

说明

• 当前 /api/chat 为无 RAG 模式，只返回结构化占位建议。
• 后续接 RAG 时，不需要改前端协议，只需在后端替换 chat 逻辑并填充 sources。