# hiking-platform

**Repository Path**: happydeedee/hiking-platform

## Basic Information

- **Project Name**: hiking-platform
- **Description**: 一个专注于户外徒步的开源平台，提供路线规划、活动组织和社区交流功能，旨在为徒步爱好者打造全方位的服务体验。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-23
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 徒步足迹 👣

面向上班族的徒步路线决策工具。不是信息展示平台，而是"这次出行能不能去徒步？"的决策引擎。

**核心体验**：≤5 秒完成核心输入并确认出发地 → 得到一组带决策理由的路线结果，其中 `bestMatch / available / unavailable / allCandidates` 是当前统一结果结构。

---

## 最初要解决的 8 个痛点

1. **信息分散**
   - 用户为了做一次徒步决策，需要在小红书、两步路/六只脚、天气 App、地图 App 之间来回切换。

2. **缺少直接结论**
   - 现有工具给了大量信息，但没有直接回答：**这次出行到底能不能去？**

3. **路线信息缺乏时效性**
   - 很多攻略、照片、轨迹是旧的，丰水期、枯水期、封路、维修、塌方等变化没有被及时反映。

4. **用户上传内容不够可靠**
   - 一条路线在上传时可走，不代表现在仍然适合；参考价值高，但决策可靠性低。

5. **现有工具门槛太高**
   - 普通上班族不会看轨迹、不会判断风险，也不想学习专业户外工具的使用方式。

6. **缺少人流 / 出行成本判断**
   - 用户不仅关心路线美不美，也关心堵不堵、停车难不难、会不会排队、人会不会太多。

7. **缺少一票否决机制**
   - 在极端天气、封山、塌方等场景下，系统应该直接劝退，而不是继续推荐。

8. **人工运营不可持续，缺少验证闭环**
   - 纯人工维护路线状态难以扩展；同时缺少轻量反馈和点名验证场景，无法持续刷新可信度。

**因此，这个项目不是"路线信息平台"，而是一个低门槛的徒步决策引擎：基于当前真实条件，快速给出 去 / 谨慎去 / 不去，以及为什么。**

---

## 当前进展

当前阶段、P0/P1、阻塞项与下一步任务以 [docs/current-status.md](docs/current-status.md) 为准；README 只保留高层摘要和运行方式，不维护会影响 agent 判断路径的详细看板。

### 已具备的核心能力摘要

- 项目基础架构（Next.js 16 + TypeScript + Tailwind CSS v4 + 现有业务组件体系）
- 数据库设计与迁移（Prisma + SQLite 当前开发环境）
- 路线库当前覆盖国内多省精选目的地，seed 首批以华南、华东和西南代表路线为主；地域扩展以 `Location` 坐标和路线数据审核为准
- 决策引擎（规则系统：天气 + 季节 + 人流 + 人工状态）
- 首页与结果主链路（基础条件 / 目的地条件 / 天气体验 → 返回 `bestMatch / available / unavailable / allCandidates`）
- 主推荐流必须带 `origin`；候选召回受 `origin / travelRange / travelBudgetMinutes / travelMode` 驱动，会先放大候选池，再按交通可达性与范围软排序收紧本次候选集合
- 结果卡片与地图结果视图（Leaflet + ArcGIS World Imagery / Shaded Relief 地貌图层主渲染，叠加自有地形底纹与业务 marker/label；高德标准底图仅作连续瓦片失败兜底；列表卡片、地图联动、结果页信息恢复；即使 `bestMatch = null` 也继续展示统一地图/列表结果容器）
- 路线详情页（从推荐页进入时透传 `date / tripDays / origin / travelMode` 等上下文；直达详情页仅保留无-origin 技术 fallback，不作为主推荐流）
- Open-Meteo 按目标日期查询 forecast + 4 小时缓存（按 `locationId + targetDate` 分桶），支持 1-16 天行程天气窗口聚合

## Agent startup

Agent 进入项目时，先读 `docs/current-status.md` 作为唯一状态入口；后续所需文档（包括 `docs/agent-operating-model.md`、`docs/autonomous-ops-governance.md` 与各专项文档）一律按 `docs/current-status.md` 的任务入口与阅读指引继续展开。

README 只保留高层摘要与运行方式，不作为当前状态真源。

---

## 文件结构

README 只保留当前仍稳定有效的入口，不再维护大而全的目录树快照。

### A 线：决策产品主链路

- `app/page.tsx` — 首页输入、结果视图与主决策入口
- `app/api/decide/route.ts` — 决策 API，对外返回 `bestMatch / available / unavailable / allCandidates / decisionContext`
- `app/routes/[id]/page.tsx` — 路线详情页
- `components/ResultCard.tsx`、`components/ResultMapView.tsx` — 列表卡片与地图结果视图（Leaflet 地貌主地图、Amap fallback）
- `lib/decision-engine.ts`、`lib/weather.ts`、`lib/crowd.ts` — 决策、天气、人流规则核心

### B 线：热点发现 / 候选入库线

- `app/api/hotspots/` — 热点采集 / 入库相关 API
- `app/api/destination-candidates/` — 候选审核、合并、转正相关 API
- `lib/hotspot-extractor.ts` — 地名抽取与清洗
- `lib/hotspot-region-resolver.ts` — 地区识别与 region rule 处理
- `lib/hotspot-ingest.ts` — 去重与入库主流程
- `lib/hotspot-xiaohongshu.ts` — 小红书输入格式适配
- `prisma/` — `coords:backfill`、`coords:verify` 等坐标与数据脚本

### 数据与基础设施

- `prisma/schema.prisma` — 核心数据模型
- `prisma/` — migration、seed 与数据脚本
- `docs/PRD.md`、`docs/map-decision-prd.md`、`docs/spec-map-decision.md` — A 线主文档
- `docs/current-status.md` — 当前项目阶段与 A/B 主线状态
- `__tests__/` — API、规则引擎、热点抽取 / 入库回归测试

如果目录说明与实际代码冲突，以代码和 `docs/current-status.md` 为准。

## 技术栈

| 层级 | 技术 |
|------|------|
| 框架 | Next.js 16（App Router） |
| 语言 | TypeScript |
| 样式 | Tailwind CSS v4 |
| 组件层 | 现有 Tailwind 业务组件 + 可选 shadcn 配置 |
| ORM | Prisma |
| 数据库 | SQLite（当前开发环境）/ PostgreSQL（后续生产阶段） |
| 图表 | D3 |
| 图标 | Lucide React |

---

## 如何运行

```bash
# 安装依赖
npm install

# 初始化数据库
npx prisma migrate dev
npx prisma db seed

# 开发模式
npm run dev

# 构建
npm run build
```

访问 http://localhost:3000

## 验证与交接

```bash
# agent 默认交接前验证
npm run verify

# UI、E2E、release 或大范围契约改动前验证
npm run verify:full
```

地图主视觉依赖公开 ArcGIS World Imagery / Shaded Relief 瓦片端点，无新增本地 env；如果 provider、网络或瓦片响应失败，地图会保留产品自有业务覆盖层，并在连续失败后切到高德标准底图兜底。外部瓦片只作为地貌参考层，不能替代业务坐标或决策数据。

如果 `verify:full` 因环境或外部服务失败，需要记录失败命令、失败原因、已通过的替代验证和剩余风险。

## 小红书热点采集

详见 [docs/collection-workflow.md](docs/collection-workflow.md)。


---

## GitHub 参考项目提取

详见 [docs/github-sources.md](docs/github-sources.md)。

---

## 产品定位



**做**：路线 + 天气 + 交通 + 人流 的一站式信息整合，以"决策"代替"浏览"。