TripFlow 是一个基于全球地图的旅行地点管理、多日行程编排、真实路线事实和确定性可行性检查系统。它把“发现地点 → 保存地点 → 编排行程 → 记录事实 → 检查可行性”连成一条不依赖智能服务的开源 Core 流程。
- MapLibre GL + OpenFreeMap 全球地图，包含 OpenStreetMap attribution、URL 相机状态和渐进式地点展示。
- 自有 Place 的创建、查看、编辑、删除、照片、标签、来源和版本控制。
- 精选 Wikidata 全球地标目录；开放地标只有在用户确认保存或加入 Trip 后才成为自有 Place。
- Trip、TripDay、TripPlace、活动顺序、时间窗口、开始时间、时长和版本控制。
- 自有 Place / Trip 搜索、地图跳转、详情 Sheet 和桌面/移动端基础流程。
- RouteFact、OpeningFact、人工事实、Valhalla pedestrian provider、来源/观察时间/有效期/修订和
unknown语义。 - 可选的高德中国模式：高德 JS 地图、真实 POI 搜索/保存、高德步行路线和 GCJ-02 provider 坐标审计；默认不启用。
- 确定性 Trip Checker：
pass、conflict、unknown；缺失事实或 provider 失败不会被当作成功。 - 当前行程/日期上下文预选、一次确认加入、按日编号地图标记；活动与路段交错时间线，冲突就地显示、依据可展开。
环境要求：Node.js 24.x、Docker Compose，以及运行 Playwright 时可用的 Chrome 通道。
npm install
docker compose up -d db
npm run migrate
npm run seed
npm run dev:api另开一个终端启动 Web：
npm run dev:web打开 http://localhost:5173。API 健康检查为 http://localhost:3001/health。
开发流程只启动 Compose 的 db，API 和 Web 使用宿主机 Node。Compose 也提供容器 API、一次性迁移和 selfhost profile 下的 Web。数据库默认本地连接为 postgres://travel:travel@localhost:5432/travel_map；若更改数据库密码，宿主机 DATABASE_URL 必须同步。
首次部署前复制 .env.example 到本地 .env，为新数据库设置独立强密码 POSTGRES_PASSWORD，保留默认 MapLibre 配置即可。容器通过独立 PG 环境变量连接数据库，不使用指向宿主机 localhost 的 DATABASE_URL。
docker compose --profile selfhost up -d --build web打开 http://localhost:8080/map，健康检查为 http://localhost:8080/health。启动顺序是 DB 健康 → migration 成功 → API 健康 → Web；迁移失败会阻止新 API/Web 启动。端口默认仅绑定 127.0.0.1。这是个人自托管部署，当前写接口没有账号权限隔离；公网和多人部署另行设计鉴权及访问控制。
空库可直接创建地点和行程；演示地点与精选目录为可选导入，不在每次启动时自动 seed：
docker compose run --rm migrate seed迁移只追加，必需的 user 来源由 0010_user_content_source.sql 初始化；seed 不参与容器启动。基础 seed 包含语言与入门行程整理，建议仅在新库导入，已有用户数据先备份并审阅 seed 的更新语句。精选目录的 seed 单独保持 insert-only。
升级前先备份，然后构建、停止旧 Web/API，执行迁移，再启动完整服务：
docker compose --profile selfhost build
docker compose --profile selfhost stop web api
docker compose run --rm migrate
docker compose --profile selfhost up -d web迁移失败时保持旧服务停止，检查迁移错误，不要忽略失败继续启动。已执行迁移不能改写，回退应用前核实数据库兼容性。镜像锁定依赖使用 package-lock；当前本地镜像名称不代表正式发布 tag。
既有 mapweb_db_data 卷保留原密码，修改 .env 不会重设数据库密码。默认数据库卷位置和 Compose 名称保持兼容；不要用 down -v 解决连接或升级问题。
正式备份保存在项目外，不放入可清理的 .tmp/。以下流程导出数据库并在独立数据库恢复核对，不覆盖运行库：
$tripBackupDirectory = Join-Path $env:USERPROFILE 'TripFlowBackups'
New-Item -ItemType Directory -Force -Path $tripBackupDirectory | Out-Null
$tripBackupPath = Join-Path $tripBackupDirectory ('tripflow-' + (Get-Date -Format 'yyyyMMdd-HHmmss') + '.backup')
docker compose exec -T db pg_dump -U travel -d travel_map -Fc -f /tmp/tripflow.backup
$tripDbContainer = docker compose ps -q db
docker cp "${tripDbContainer}:/tmp/tripflow.backup" $tripBackupPath
docker cp $tripBackupPath "${tripDbContainer}:/tmp/tripflow-restore.backup"
docker compose exec -T db createdb -U travel tripflow_restore_check
docker compose exec -T db pg_restore -U travel -d tripflow_restore_check --exit-on-error /tmp/tripflow-restore.backup
docker compose exec -T db psql -U travel -d tripflow_restore_check -c 'SELECT count(*) FROM trip_places;'每条命令成功后再进行下一步。重复验证时选择新的恢复库名，保留核对结果；正式切换运行库应另行安排停写和连接切换。数据库备份不包含外部 provider 数据、在线地图服务或 .env，这些配置需单独保管。
部署依赖可用的在线底图、字形和路线服务。默认 Valhalla 公共 demo 仍仅用于小规模验证，正式路线容量与服务政策仍需另行确认。
复制 .env.example 为本地 .env，填入高德 Web 服务 Key、Web 端 JS Key 和 JS 安全密钥，然后设置：
TRAVEL_MAP_PROVIDER=amap
TRAVEL_ROUTE_PROVIDER=amap
TRAVEL_POI_PROVIDER=amap
Web Service Key 只由 API 使用；JS Key 和安全密钥由同源运行配置提供给高德 JS API。Amap POI 的精确坐标以 GCJ-02 保存在 provider 字段中，Core 的旧坐标字段保留带质量标记的 WGS84 近似值。当前只支持步行路线；缺 key、限流或 provider 返回不完整时，Checker 保持 unknown。高德数据、地图和额度受高德当前服务条款约束，正式发布前必须重新核验。
| Command | Purpose |
|---|---|
npm run dev:api |
Start the API in watch mode |
npm run dev:web |
Start the Vite web app |
npm run audit:catalog |
Validate catalog identities, Chinese labels, provenance and coordinate ranges |
node scripts/validation/verify-selfhost.mjs |
Verify built Docker images with disposable tmpfs databases on ports 3301/8088 |
npm run typecheck |
Type-check all workspaces |
npm run test:unit |
Shared and frontend unit tests |
npm run test:api |
API and service tests |
npm run test:integration |
PostGIS migration/seed/integration tests |
npm run test:ui |
Web component tests |
npm run test:e2e |
Regular Playwright E2E |
npm run test:e2e:full |
Full E2E with API and database |
npm run build |
Build the web application |
npm run audit:links |
Check local Markdown links |
npm run audit:release |
Check public-Core release boundaries |
npm run clean |
Remove only listed rebuildable output and cache |
apps/api Node HTTP API: route → service → repository → database
apps/web React + Vite frontend and MapLibre UI
packages/shared Shared types, categories and reveal rules
database PostgreSQL/PostGIS migrations, seeds and catalog
scripts Maintenance, audit and performance tools
docs/decisions.md Long-term technical decisions
PROJECT.md Current implementation facts
PLAN.md Future work only
Architecture and current contracts are documented in PROJECT.md. Future work and known backlog are in PLAN.md. Historical decisions are in docs/decisions.md.
© OpenStreetMap contributors— https://www.openstreetmap.org/copyrightTiles: OpenFreeMap— https://openfreemap.org/- The selected landmark catalog is a curated Wikidata snapshot, not a complete or live global POI database.
- Valhalla public/demo routing is suitable only for development or small demonstrations. Before a large or public deployment, choose a provider that meets the required capacity, terms and operational needs, or deploy Valhalla yourself.
Third-party data, tiles, routing and image providers retain their own licenses and service terms. Recheck those terms before public deployment.
Contribution workflow: CONTRIBUTING.md. Security reporting: SECURITY.md. Do not commit secrets, local database data, generated output, personal data or provider credentials.
The public Core deliberately excludes future private intelligent features. Do not add AI/LLM, JEV, AI recovery, private prompts, private datasets or weather-driven automatic replanning to this repository; record future ideas in PLAN.md instead.
TripFlow Core is licensed under the Apache License 2.0. See LICENSE for details.
系列计划入口：docs/series。当前状态见 PROJECT.md，未来工作见 PLAN.md。