# nomadro · 数字游民旅居平台

品牌 **nomadro** — 用一行代码环游世界 🌏

**线上：** [https://nomadweb.nomadro.com](https://nomadweb.nomadro.com)

## 产品路径（环环相扣）

功能很多，但**不一次全部展示**。导航与首页按三条环串联，每页只露出「接下来」：

| 环 | 做什么 | 主要入口 |
|----|--------|----------|
| **探索 Explore** | 发现去哪 | 目的地、地图、下一站、签证；（离首页后再出现计划 / 对比） |
| **连接 Connect** | 遇见同行 | 活动 → 社区 → 匹配 → 私信 |
| **成长 Grow** | 路上做事 | 学院 → 赏金 → 工具箱（按需）→ 电子书 |

```
发现城市 ──► 写入计划 / 同城活动 ──► 社区 / 匹配 ──► 学院 / 赏金
```

- 顶栏：**探索 / 连接 / 成长** 三组下拉，**EN · 主题 · 通知** 固定在右上
- `Ctrl+K` 空态只给三环捷径；次要页面要搜索才出现
- 工具箱默认精选 +「展开全部」，不再当全站站点地图
- **连接闭环：** 活动报名需登录（可取消）；匹配 / 报名 / 讨论回复 / 赏金申请会写入通知中心；可选 ntfy 推送（`NTFY_ENABLED` + 设置里打开「推送」）
- **订阅：** 写入 PocketBase；配置 `LISTMONK_*` 后同步 Listmonk，未配置时文案如实提示「已登记」

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端 | Next.js 16 + React 19 | **仅 UI**；App Router、standalone |
| 后端 | FastAPI | **全部业务逻辑**（无 Next.js 业务 API Route） |
| 数据 | PocketBase | 主存储；本地可 Mock 降级 |
| 对象存储 | S3 兼容（生产 SeaweedFS） | 媒体上传 |
| 部署 | Caddy + systemd | 原生进程；勿与同机 dylive 业务互相干扰 |

## 项目结构

```
nomadweb/
├── frontend/                 # Next.js（页面与组件）
│   ├── src/app/              # 路由
│   ├── src/components/       # UI（含 RingNext 下一步条）
│   └── src/lib/              # api / auth / i18n / rings
├── backend/                  # FastAPI
│   ├── app/routers/          # REST
│   ├── app/services/         # PocketBase、S3、城市深度等
│   └── app/data/             # Mock 降级（开发）
├── wemini/                   # 微信小程序（Taro → weapp，可联网）
├── dymini/                   # 抖音小程序（Taro → tt，可联网）
├── redmini/                  # 小红书 miniTool（纯前端离线，禁止联网）
├── deploy/                   # Caddy、systemd、env 模板
├── scripts/                  # 本地开发与生产更新
└── pocketbase/               # PB 数据目录（本地可选）
```

### 小程序

| 目录 | 平台 | 联网 | 说明 |
|------|------|------|------|
| `wemini/` | 微信 | ✅ → `nomadweb.nomadro.com/api/v1` | `npm run dev:weapp` |
| `dymini/` | 抖音 | ✅ → 同上 | `npm run dev:tt` |
| `redmini/` | 小红书 | ❌ 纯离线 | `python scripts/assemble.py && python scripts/pack.py` |

Git 远程：`origin`（gitea）与 `nomadro`（[git.nomadro.cn/hackrobot/nomadweb](https://git.nomadro.cn/hackrobot/nomadweb.git)）。

## 快速开始

### 1. PocketBase（可选）

不启动则 API 使用 Mock。

```bash
docker run -d -p 8090:8090 -v ./pocketbase/pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest
```

### 2. FastAPI

```bash
cd backend
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000
```

文档：http://localhost:8000/docs

### 3. Next.js

```bash
cd frontend
cp .env.local.example .env.local
npm install --legacy-peer-deps
npm run dev
```

访问：http://localhost:3000

```powershell
.\scripts\dev.ps1   # Windows 一键
```

## 核心功能一览

按环归类（深度页会互相引导，避免平铺）：

### 探索
| 能力 | 路径 |
|------|------|
| 地图 / 目的地 | `/#map` `/#destinations` `/destinations/[slug]` |
| 智能匹配 | 首页 CTA / `M` |
| 下一站决策 | `/next-stop` |
| 城市对比 | `/compare` |
| 旅居计划 | `/plan`（时间轴、预算、签证提醒、清单、ICS） |
| 签证指南 | `/#visa` |

### 连接
| 能力 | 路径 |
|------|------|
| 活动 RSVP / 直播间 | `/meetups` `/meetups/[id]/live` |
| 社区讨论 | `/community` |
| 游民匹配 | `/dating` |
| 私信 | `/chat` |
| 通知 | `/notifications` |

### 成长
| 能力 | 路径 |
|------|------|
| 游民学院 | `/digital` |
| 赏金任务 | `/gigs` |
| 工具箱 | `/tools`（实用小工具，非功能总览） |
| 电子书 | `/book` |
| 会员 | `/join` `/pricing` |

演示账号：`demo@nomadro.com` / `demo123`

## 环境变量

**Backend**

```env
POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_ADMIN_EMAIL=...
POCKETBASE_ADMIN_PASSWORD=...
CORS_ORIGINS=http://localhost:3000
# S3（生产见服务器 deploy/nomadro-api.env）
```

**Frontend**

```env
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

生产构建：

```env
NEXT_PUBLIC_API_URL=https://nomadweb.nomadro.com/api/v1
NEXT_PUBLIC_SITE_URL=https://nomadweb.nomadro.com
```

## Git 与部署

仓库：
- [gitea.dsx2020.com/eric/nomadweb](https://gitea.dsx2020.com/eric/nomadweb)（`origin`）
- [git.nomadro.cn/hackrobot/nomadweb](https://git.nomadro.cn/hackrobot/nomadweb.git)（`nomadro`）

当前开发分支 **`dev2`**（亦保留 `dev1` / `main`）。

```bash
git checkout dev2
git pull origin dev2
# … 改代码 …
git push origin dev2
git push nomadro dev2
python scripts/deploy_update.py   # 服务器 pull + 增量构建重启
```

| 生产进程 | 地址 |
|----------|------|
| 网站 | https://nomadweb.nomadro.com |
| `nomadro-web` | `127.0.0.1:3055` |
| `nomadro-api` | `127.0.0.1:8055` |
| PocketBase | `127.0.0.1:8090` |
| S3 | `s3.nomadro.com` → SeaweedFS |

**注意：** 同机还跑有 [dylive.nomadro.com](https://dylive.nomadro.com/)（`/opt/douyinWEB`）。更新 nomadweb 时**不要**改动 / 限流 / 杀掉直播相关进程。

密钥仅放服务器 `deploy/nomadro-api.env`（模板见 `*.env.example`），勿提交。

## 快捷键

| 按键 | 功能 |
|------|------|
| `Ctrl+K` | 全局搜索（三环捷径） |
| `M` | 智能匹配 |
| `P` | 旅居计划 |
| `T` | 工具箱 |
| `?` | 帮助 |
| `Esc` | 关闭弹窗 |

## 相关

- 迭代说明：[/changelog](https://nomadweb.nomadro.com/changelog)
- 前端脚手架说明：`frontend/README.md`（以本文件为准）

## License

MIT