's'

cursor.md

@@ -1,6 +1,6 @@
 # NomadCNA — Cursor 项目上下文报告
 
-> 生成日期：2026-06-07  
+> 更新日期：2026-06-08  
 > 用途：为 Cursor AI 助手提供项目全貌、架构约定与开发指引。  
 > 生产站点：https://nomadro.cn
 
@@ -10,20 +10,21 @@
 
 **NomadCNA（游牧中国）** 是面向数字游民的生活操作系统，单仓 Monorepo 包含：
 
-- **主站**：城市探索、下一站决策、活动、社区、支付、统计等
+- **主站**：城市探索、下一站决策、活动、社区匹配、支付、统计、访谈视频等
 - **Digital 子站**（`/digital`）：指南、课程、电子书、远程工作、个人资料
 - **FastAPI 后端**：认证、业务 API、支付回调、PocketBase 集成
-- **外部服务**：PocketBase、MinIO、MiroTalk P2P、The Lounge + Ergo IRC
+- **VPS 自建开源服务**：MiroTalk P2P（视频）、The Lounge + Ergo IRC（Web 群聊）
 
 | 模块 | 说明 |
 |------|------|
 | 城市探索 | 18 城静态数据 + API，生活成本/网速/安全等指标 |
 | 下一站决策 | `/dashboard`，预算/气候/标签推荐 |
-| 活动 | 线上/线下/混合，MiroTalk 视频 + Web 群聊 |
-| 社区 | 交友匹配、讨论、任务赏金、反馈 |
+| 活动 | 线上/线下/混合；**统一活动间** `/meetups/[id]/live` 深度融合 MiroTalk + Lounge |
+| 访谈视频 | `/videos` 列表 + `/videos/[slug]` 详情 |
+| 社区匹配 | `/dating` 滑动匹配、意图/城市筛选、互赞、额度、撤销 |
 | 会员与支付 | ZPay / XorPay，加入表单 + VIP 状态 |
 | Digital 子站 | 课程章节、电子书 Markdown、资源导航 |
-| 媒体 | MinIO 上传 + 远程媒体代理缓存 |
+| 媒体 | MinIO 上传 + `app/lib/media.ts` + `/api/media/proxy` |
 
 ---
 
@@ -39,6 +40,8 @@
 | 后端 | FastAPI + uvicorn | ≥0.115 |
 | 数据库 | PocketBase | SDK 0.27 |
 | 对象存储 | MinIO | Node + Python SDK |
+| 视频会议 | MiroTalk P2P | VPS :9300 |
+| Web 群聊 | The Lounge 4.5 + Ergo IRC 2.18 | VPS :9000 / :6667 |
 | 支付 | ZPay / XorPay 适配层 | — |
 | 包管理 | pnpm | 10.25.0 |
 | Node 生产版本 | — | v22.13.1 |
@@ -75,8 +78,8 @@ flowchart TB
     NextAPI --> MinIO
     FastAPI --> PB
     FastAPI --> MinIO
-    Next --> MiroTalk
-    Next --> Lounge
+    Next -->|"活动间 iframe"| MiroTalk
+    Next -->|"活动间 iframe"| Lounge
     Lounge --> Ergo
 ```
 
@@ -104,52 +107,56 @@ destination: "http://127.0.0.1:8000/api/:path*"
 ```text
 .
 ├── app/
-│   ├── [locale]/              # 主站多语言页面（49 个 page.tsx）
+│   ├── [locale]/              # 主站多语言页面（~54 个 page.tsx）
+│   │   ├── dating/            # 匹配页 + components/
+│   │   ├── meetups/           # 活动列表、host、[id]/live 活动间
+│   │   ├── videos/            # 访谈列表 + [slug] 详情
 │   │   └── digital/           # Digital 子站页面路由
 │   ├── api/
-│   │   ├── digital/           # Digital 认证、支付、上传、VIP（13 个 route）
+│   │   ├── digital/           # Digital 认证、支付、上传、VIP
 │   │   └── media/proxy/       # 远程媒体代理
-│   ├── components/            # 主站通用组件（Navbar、Hero、AuthModal 等）
+│   ├── components/
+│   │   └── meetups/EventLiveRoom.tsx  # 活动间分屏 UI
 │   ├── context/               # LocaleContext、ThemeContext
-│   ├── data/                  # cities.ts、map-cities.ts、mock.ts
-│   ├── digital/               # Digital 子站组件、lib、context（与主站平行）
-│   └── lib/                   # api-client、payment、meetups、pocketbase、charts
+│   ├── data/                  # cities.ts、avatars.ts、mock.ts
+│   ├── digital/               # Digital 子站组件、lib、context
+│   └── lib/                   # api-client、meetups、media、payment、pocketbase
 ├── backend/
-│   ├── main.py                # FastAPI 入口（~50 个端点）
+│   ├── main.py                # FastAPI 入口（~70 个端点）
+│   ├── meetup_live.py         # 活动间 URL / 权限
+│   ├── avatar_assets.py       # 头像池（与前端 avatars.ts 同步）
 │   ├── settings.py            # 环境变量
 │   ├── pb_client.py           # PocketBase HTTP 客户端
 │   ├── payment.py             # ZPay / XorPay
-│   └── minio_storage.py       # MinIO 上传
+│   ├── minio_storage.py       # MinIO 上传
+│   ├── init_db.py             # 集合 schema + seed
+│   └── seed_data.py           # 种子数据
 ├── config/
+│   ├── remote-services.ts     # 线上服务地址、Windows 远程开发
 │   ├── site.config.ts         # 主站 SEO
 │   ├── nav.config.ts          # 顶部导航
-│   ├── home.config.ts         # 首页静态内容
-│   ├── services.config.ts     # 主站服务配置
 │   └── digital/               # Digital 子站专属配置
-├── i18n/
-│   ├── routing.ts             # locales: zh/en, default: zh
-│   └── navigation.ts          # 语言感知 Link/Router 导出
+├── scripts/
+│   ├── dev-tunnel.py          # SSH 隧道：MinIO → localhost:9100
+│   └── dev-windows.ps1        # Windows 一键开发
+├── i18n/                      # routing.ts、navigation.ts
 ├── messages/                  # zh.json、en.json 主站文案
-├── content/digital/           # Digital 主题数据（tools.json 等）
-├── public/                    # 静态资源
-├── next.config.ts
-├── package.json
-└── pnpm-workspace.yaml
+└── next.config.ts
 ```
 
 ### 主站 vs Digital 子站代码边界
 
 | 区域 | 路径 | 说明 |
 |------|------|------|
-| 主站页面 | `app/[locale]/*` | 城市、活动、社区等 |
-| 主站组件 | `app/components/` | Navbar、Sidebar、CityCard 等 |
-| 主站工具 | `app/lib/` | api-client、meetups、payment |
+| 主站页面 | `app/[locale]/*` | 城市、活动、匹配、视频等 |
+| 主站组件 | `app/components/` | Navbar、EventLiveRoom 等 |
+| 主站工具 | `app/lib/` | api-client、meetups、media、payment |
 | Digital 页面 | `app/[locale]/digital/*` | 课程、电子书、工作等 |
 | Digital 组件 | `app/digital/components/` | 独立 Header、Hero、课程区块 |
 | Digital 工具 | `app/digital/lib/` | 平行的 payment、pocketbase、learning |
 | Digital 配置 | `config/digital/*` | 课程、域名、视觉主题 |
 
-两套代码存在 **有意平行**（非完全共享），修改时注意对应目录。
+两套代码 **有意平行**（非完全共享），修改时注意对应目录。
 
 ---
 
@@ -157,54 +164,44 @@ destination: "http://127.0.0.1:8000/api/:path*"
 
 - 语言：`zh`（默认）、`en`，路由 **始终带前缀**（`/zh/...`、`/en/...`）
 - 配置：`i18n/routing.ts`
-- 文案：`messages/zh.json`、`messages/en.json`；Digital 另有 `content/digital/themes/.../messages/`
-- 运行时 i18n：`LocaleContext` + `t("key.path")` 点分键
-- 语言感知导航：**必须**使用 `i18n/navigation.ts` 导出的 `Link`、`useRouter`
+- 文案：`messages/zh.json`、`messages/en.json`
+- 语言感知导航：**必须**使用 `i18n/navigation.ts` 的 `Link`、`useRouter`、`useTranslation`
 
 ```tsx
-// ✅ 正确
 import { Link, useRouter, useTranslation } from "@/i18n/navigation";
-
-// ❌ 避免直接用 next/link（会丢失 locale 前缀）
-import Link from "next/link";
 ```
 
-新页面流程：
-1. 在 `app/[locale]/` 下创建 `page.tsx`
-2. 在 `messages/zh.json` 和 `messages/en.json` 补充文案键
-3. 如需导航入口，更新 `config/nav.config.ts`
+新页面：在 `app/[locale]/` 建 `page.tsx` → 补 `messages/*.json` → 必要时改 `config/nav.config.ts`。
 
 ---
 
 ## 6. API 端点速查
 
-### 6.1 Next.js Route Handlers（`app/api/digital/`）
+### 6.1 Next.js Route Handlers
 
 | 路径 | 作用 |
 |------|------|
-| `auth/login`、`register`、`logout`、`me`、`sync-session` | Digital 认证 |
-| `join` | 加入申请表单 → PocketBase |
-| `pay`、`pay/status`、`pay/confirm` | Digital 支付 |
-| `vip/check` | VIP 状态 |
-| `upload-media` | 媒体上传 MinIO |
-| `jobs` | 远程工作列表 |
-| `media/proxy` | 远程媒体抓取缓存 |
+| `app/api/digital/auth/*` | Digital 认证 |
+| `app/api/digital/join`、`pay/*`、`vip/check` | 加入、支付、VIP |
+| `app/api/digital/upload-media` | 媒体上传 MinIO |
+| `app/api/media/proxy` | 远程媒体抓取/缓存 |
 
 ### 6.2 FastAPI（`backend/main.py`）
 
-| 分类 | 端点示例 |
-|------|----------|
-| 健康 | `GET /api/health` |
-| 认证 | `POST /api/auth/email`、`/google`、`GET /api/auth/me` |
-| 加入/支付 | `POST /api/join`、`/api/pay`、`GET /api/pay/status` |
-| 城市/内容 | `GET /api/cities`、`/api/content/home`、`POST /api/content/submissions` |
-| 活动 | `GET/POST /api/meetups` |
-| 社区 | `GET/POST /api/discussions`、`/api/gigs`、`/api/profiles`、`/api/matches/swipes` |
-| 通知 | `GET/POST /api/notifications/*` |
-| 统计 | `GET /api/stats/member-map`、`/overview`、`/city-ranking` |
-| 推荐 | `POST /api/recommendations/next-stop` |
-| 其他 | `POST /api/feedback`、`POST /api/ai/assistant`（占位） |
-| 支付回调 | `/cnomadcna/zpay_order_status`、`/cnomadcna/xorpay_notify` |
+| 分类 | 端点 |
+|------|------|
+| 健康/认证 | `GET /api/health`，`POST /api/auth/email|google`，`GET /api/auth/me` |
+| 加入/支付 | `POST /api/join`，`POST /api/pay`，`GET /api/pay/status` |
+| 城市/内容 | `GET /api/cities`，`GET /api/content/home`，`GET /api/content/{slug}` |
+| **视频** | `GET /api/videos` |
+| **活动** | `GET/POST /api/meetups`，`GET /api/meetups/{id}`，**`GET /api/meetups/{id}/session`** |
+| **匹配** | `GET /api/matches/candidates|likes|mutual|quota|profile/me`，`POST /api/matches/swipes`，`POST /api/matches/swipes/undo` |
+| 社区 | `GET/POST /api/discussions`，`/api/gigs`，`GET /api/profiles` |
+| 通知/统计 | `/api/notifications/*`，`/api/stats/*` |
+| 其他 | `POST /api/feedback`，`POST /api/recommendations/next-stop` |
+| 支付回调 | `/cnomadcna/zpay_order_status`，`/cnomadcna/xorpay_notify` |
+
+**注意**：`/api/videos` 必须独立路由，不能走 `/api/content/{slug}`（slug=`videos` 会 404）。
 
 ---
 
@@ -212,37 +209,63 @@ import Link from "next/link";
 
 ### 7.1 城市探索
 
-- 静态数据：`app/data/cities.ts`（18 城）
-- 首页：`app/[locale]/page.tsx` + `FilterBar`、`CityCard`、`CityModal`
-- 详情：`app/[locale]/city/[slug]/page.tsx`
-- API 补充：`GET /api/cities`、`/api/cities/{slug}`
+- 静态：`app/data/cities.ts`（18 城）
+- 首页：`app/[locale]/page.tsx` + FilterBar、CityCard、CityModal
+- API：`GET /api/cities`、`/api/cities/{slug}`
 
-### 7.2 活动 / 视频 / 群聊
+### 7.2 活动 / 视频 / 群聊（深度融合）
 
-- 页面：`app/[locale]/meetups/`、`meetups/host/`
-- 核心逻辑：`app/lib/meetups.ts`
-  - MiroTalk 房间 slug 生成：`createMiroTalkRoomSlug()`
-  - 默认视频地址：`NEXT_PUBLIC_MIROTALK_URL`
-  - 默认群聊地址：`NEXT_PUBLIC_LOUNGE_URL`
-- 线上/混合活动展示 MiroTalk iframe + The Lounge 入口
+| 层级 | 文件 |
+|------|------|
+| 列表/弹窗 | `app/[locale]/meetups/page.tsx` |
+| **活动间** | `app/[locale]/meetups/[id]/live/page.tsx` |
+| UI 组件 | `app/components/meetups/EventLiveRoom.tsx` |
+| 前端逻辑 | `app/lib/meetups.ts` |
+| 后端逻辑 | `backend/meetup_live.py` |
+| 会话 API | `GET /api/meetups/{id}/session` |
 
-### 7.3 支付
+流程：
 
-- 前端：`app/lib/payment/`（client、config、usePayStatusPoll）
-- Digital 平行：`app/digital/lib/payment/`
-- 后端：`backend/payment.py`（ZPayProvider、XorPayProvider）
+1. 用户打开活动详情 → **「进入活动间」**
+2. Live 页请求 `/api/meetups/{id}/session`（带 Cookie）
+3. 返回 `videoUrl`（MiroTalk + `name=`）、`chatUrl`（Lounge channel deep link）、`canJoin`
+4. `EventLiveRoom` 分屏 iframe 嵌入；支持只看视频/只看群聊
+
+PocketBase `meetups` 关键字段：`mode`、`accessLevel`、`mirotalkRoom`、`loungeChannel`、`features`。
+
+### 7.3 访谈视频
+
+- 列表：`app/[locale]/videos/page.tsx` → `GET /api/videos`
+- 详情：`app/[locale]/videos/[slug]/page.tsx`
+- 首页 video 卡片 `targetUrl` 固定 `/videos`（见 `app/[locale]/page.tsx` 的 `normalizeHomeContentItem`）
+
+### 7.4 社区匹配（Dating）
+
+- 页面：`app/[locale]/dating/page.tsx`
+- 组件目录：`app/[locale]/dating/components/`
+  - `IntentTabs`、`CityFilter`、`SwipeStack`、`SwipeCard`
+  - `LikesPanel`、`MatchModal`、`AdvancedFilters`、`SwipeQuota`
+- 常量/类型：`constants.ts`、`types.ts`、`utils.ts`
+- 头像：`app/data/avatars.ts` ↔ `backend/avatar_assets.py`
+- Schema：`profiles`（lookingFor、gender、citySlug）、`swipes`（intent）、`match_connections`
+
+### 7.5 支付
+
+- 前端：`app/lib/payment/`
+- Digital：`app/digital/lib/payment/`
+- 后端：`backend/payment.py`
 - 配置：`config/services.config.ts`、`config/digital/services.config.ts`
 
-### 7.4 认证
+### 7.6 媒体
 
-- 主站 Cookie：`app/lib/auth-cookie.ts`
-- PocketBase 封装：`app/lib/pocketbase/auth.ts`
-- FastAPI 会话：`backend/pb_client.py`
+- `app/lib/media.ts`：URL 规范化、Unsplash 直连、MinIO 公开路径
+- `app/api/media/proxy/route.ts`：代理失败时 passthrough 原图
 
-### 7.5 图表与年报
+### 7.7 认证
 
-- `app/lib/charts/`：ECharts 封装（ReportChart、MembersMap）
-- 页面：`app/[locale]/report/`、`report/data/`
+- Cookie：`app/lib/auth-cookie.ts`
+- PocketBase：`app/lib/pocketbase/auth.ts`
+- FastAPI 会话：`backend/pb_client.py` + `current_user()`
 
 ---
 
@@ -250,125 +273,111 @@ import Link from "next/link";
 
 | 文件 | 用途 |
 |------|------|
-| `config/site.config.ts` | 主站标题、描述、SEO |
-| `config/nav.config.ts` | 顶部导航链接 |
-| `config/home.config.ts` | 首页成员头像、路线、统计 |
-| `config/footer.config.ts` | 页脚链接 |
-| `config/filter.config.ts` | 城市筛选选项 |
+| `config/site.config.ts` | 主站 SEO |
+| `config/nav.config.ts` | 顶部导航 |
+| `config/home.config.ts` | 首页静态块 |
+| `config/remote-services.ts` | nomadro.cn 各服务 URL、MinIO/PB 解析、`isRemoteDevMode()` |
 | `config/services.config.ts` | 主站 PocketBase/支付/MinIO |
-| `config/runtime-env.ts` | `APP_ENV` 运行时判断 |
-| `config/digital/site.config.ts` | Digital 功能开关、主题 |
-| `config/digital/course.ts` | 课程模块数据 |
-| `config/digital/lessons.ts` | 课程章节内容 |
-| `config/digital/domain.config.ts` | 域名与服务地址推导 |
-
-环境判断：`IS_DEVELOPMENT` / `IS_PRODUCTION` 来自 `config/runtime-env.ts`。
+| `config/runtime-env.ts` | `APP_ENV` 判断 |
+| `config/digital/*` | Digital 子站 |
 
 ---
 
 ## 9. 开发命令
 
 ```bash
-# 安装
 pnpm install
+pnpm dev                    # http://localhost:3001
 
-# 前端开发（端口 3001，非 README 中的 3000）
-pnpm dev
+# 后端（Windows）
+python -m venv backend/.venv
+backend\.venv\Scripts\pip install -r backend/requirements.txt
+backend\.venv\Scripts\uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload
 
-# 后端开发
-python3 -m venv backend/.venv
-# Windows: backend\.venv\Scripts\activate
-pip install -r backend/requirements.txt
-uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload
+# Windows 连线上 MinIO
+python scripts/dev-tunnel.py
 
-# 质量检查
+# 初始化 PocketBase 集合 + 种子
+python -m backend.init_db
+
+# 质量检查（上线前）
 pnpm lint
 pnpm exec tsc --noEmit --pretty false
-
-# 生产构建
-APP_ENV=production NEXT_PUBLIC_APP_ENV=production NODE_ENV=production pnpm build
-pnpm start
 ```
 
-本地需同时运行 **Next.js (:3001)** 和 **FastAPI (:8000)** 才能完整调试 API。
+**PowerShell 不支持 `&&`**，命令分步执行。
+
+本地需 **Next.js (:3001) + FastAPI (:8000)** 同时运行。8000 端口若被多个旧 uvicorn 占用，新路由不会生效——先杀干净再启一个实例。
 
 ---
 
 ## 10. 环境变量要点
 
-> ⚠️ 切勿将 `.env.local`、`backend/.env` 或真实密钥提交到 Git。  
-> `.env.example` 中可能含示例/历史值，生产密钥应通过 systemd Environment 或服务器私密配置管理。
+> ⚠️ 勿提交 `.env.local`、`backend/.env` 或真实密钥。
 
 ### 前端（`.env.local`）
 
 | 变量 | 说明 |
 |------|------|
-| `APP_ENV` / `NEXT_PUBLIC_APP_ENV` | development / production |
-| `NEXT_PUBLIC_SITE_URL` | 站点根地址 |
-| `NEXT_PUBLIC_API_BASE_URL` | API 基础路径，生产通常为 `/api` |
-| `NEXT_PUBLIC_POCKETBASE_URL` | 浏览器可访问的 PocketBase |
-| `NEXT_PUBLIC_MIROTALK_URL` | MiroTalk P2P |
-| `NEXT_PUBLIC_LOUNGE_URL` | The Lounge Web 群聊 |
-| `NEXT_PUBLIC_MINIO_PUBLIC_URL` | MinIO 公开文件地址 |
+| `NEXT_PUBLIC_SITE_URL` | 本地 `http://localhost:3001` |
+| `NEXT_PUBLIC_API_BASE_URL` | 生产 `/api`；本地可留空走 rewrite |
+| `FASTAPI_PROXY_TARGET` | rewrite 目标，默认 `http://127.0.0.1:8000` |
+| `NEXT_PUBLIC_POCKETBASE_URL` | PocketBase |
+| `NEXT_PUBLIC_MIROTALK_URL` | MiroTalk |
+| `NEXT_PUBLIC_LOUNGE_URL` | The Lounge |
+| `NEXT_PUBLIC_MINIO_PUBLIC_URL` | MinIO 公开读 |
+| `DEV_SSH_*` | dev-tunnel 用（勿提交密码） |
 
 ### 后端（`backend/.env`）
 
 | 变量 | 说明 |
 |------|------|
-| `PB_URL` / `POCKETBASE_URL` | PocketBase 内网地址 |
-| `PB_ADMIN_EMAIL` / `PB_ADMIN_PASSWORD` | 管理员凭据 |
-| `FRONTEND_ORIGINS` | CORS 白名单 |
-| `PAYMENT_PROVIDER` | zpay 或 xorpay |
-| `MINIO_*` | MinIO 连接与桶配置 |
-| `DEV_AUTO_PAY` | 开发环境自动完成支付 |
+| `POCKETBASE_URL` | 内网或公网 PB |
+| `MIROTALK_URL` / `LOUNGE_URL` | 活动间 URL 生成 |
+| `MINIO_*` | 对象存储 |
+| `DEV_AUTO_PAY` | 开发自动完成支付 |
+
+完整列表见 `.env.example` 与 `README.md`。
 
 ---
 
 ## 11. AI 编码约定
 
-修改代码时请遵循以下原则：
-
 ### 必须遵守
 
-1. **最小改动**：只改与任务相关的文件，不重构无关代码
-2. **匹配现有风格**：命名、import 路径（`@/`）、组件结构与服务作者一致
-3. **国际化**：新 UI 文案走 `messages/*.json`，使用 `t()` 而非硬编码中文/英文
-4. **路由**：新页面放 `app/[locale]/`，链接用 `@/i18n/navigation` 的 `Link`
-5. **API 调用**：主站用 `app/lib/api-client.ts` 的 `apiFetch`
-6. **配置分离**：主站配置 → `config/`，Digital → `config/digital/`
-7. **媒体**：上传/代理优先走 MinIO 相关模块
-8. **支付**：复用 `app/lib/payment` 与 `backend/payment.py`，不重复实现
-9. **活动**：视频/群聊逻辑复用 `app/lib/meetups.ts`
-10. **不提交密钥**：`.env*`、凭据文件永不入库
+1. **最小改动**：只改任务相关文件
+2. **匹配现有风格**：`@/` import、组件结构一致
+3. **国际化**：UI 文案走 `messages/*.json` + `t()`
+4. **路由**：`app/[locale]/` + `@/i18n/navigation` 的 `Link`
+5. **API**：主站用 `app/lib/api-client.ts` 的 `apiFetch`
+6. **活动**：复用 `app/lib/meetups.ts` + `backend/meetup_live.py`
+7. **媒体**：复用 `app/lib/media.ts`
+8. **支付**：复用 `app/lib/payment` + `backend/payment.py`
+9. **不提交密钥**
 
 ### 文件选择决策树
 
 ```
-新功能属于 Digital 子站？
+新功能属于 Digital？
 ├── 是 → app/[locale]/digital/ + app/digital/ + config/digital/
 └── 否 → app/[locale]/ + app/components/ + config/
 
 需要新 API？
-├── Digital 专属 → app/api/digital/
+├── Digital → app/api/digital/
 ├── 媒体代理 → app/api/media/
-└── 主站业务 → backend/main.py（FastAPI）
+└── 主站业务 → backend/main.py
 
-需要新文案？
-├── 主站 → messages/zh.json + messages/en.json
-└── Digital → content/digital/themes/.../messages/ 或 messages/
+线上活动？
+├── 列表/弹窗 → meetups/page.tsx
+├── 活动间 → meetups/[id]/live + EventLiveRoom.tsx
+└── URL/权限 → meetups.ts + meetup_live.py + /session API
 ```
 
-### TypeScript 约定
-
-- `strict: true`，避免 `any`
-- 客户端组件文件首行 `"use client"`
-- Server Component 默认，仅在需要 hooks/事件时使用 client
-
 ### Python 约定
 
-- Pydantic `BaseModel` 做请求体验证
-- PocketBase 操作统一走 `pb_client.py`
-- 新端点加在 `backend/main.py`，配置放 `settings.py`
+- 请求体用 Pydantic `BaseModel`
+- PocketBase 走 `pb_client.py`
+- 新端点加 `main.py`，配置加 `settings.py`
 
 ---
 
@@ -379,12 +388,12 @@ pnpm start
 | nomadro.cn | :4002 | Next.js（cnomadcna.service） |
 | api.nomadro.cn | :8000 | FastAPI |
 | pocketbase.nomadro.cn | :8090 | PocketBase |
-| minio.nomadro.cn | :9100/9101 | MinIO API/Console |
+| minio.nomadro.cn | :9100/9101 | MinIO |
 | mirotalk.nomadro.cn | :9300 | MiroTalk P2P |
 | lounge.nomadro.cn | :9000 | The Lounge |
 | ergo.nomadro.cn | HTTPS 重定向 | → lounge（IRC 仅本机 :6667） |
 
-生产代码目录：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna`
+VPS：`82.157.112.245`，代码目录 `/home/ubuntu/gitlab-instance-0a899031_cnomadcna`。
 
 上线前端：
 
@@ -393,19 +402,23 @@ APP_ENV=production NEXT_PUBLIC_APP_ENV=production NODE_ENV=production pnpm build
 systemctl restart cnomadcna.service
 ```
 
+活动间相关改动需同步部署 **Next.js + FastAPI**，VPS 上 MiroTalk/Lounge 配置变更需 `systemctl restart`。
+
 ---
 
 ## 13. 常见陷阱
 
 | 问题 | 说明 |
 |------|------|
-| dev 端口 | `pnpm dev` 监听 **3001**，不是 3000 |
-| API 分流 | `/api/digital/*` 不走 FastAPI rewrite |
-| 双套 lib | 主站 `app/lib/` 与 Digital `app/digital/lib/` 各自独立 |
-| 静态 vs API 数据 | 城市等仍以 `app/data/` 静态为主，部分模块接 FastAPI |
-| Ergo 公网 | `ergo.nomadro.cn` 不开放 IRC 端口，仅 The Lounge 内网连接 |
-| PROJECT_ANALYSIS_REPORT | 2026-06-06 报告认为旧 `app/api` 应逐步替换；当前仓库已并存 FastAPI + Next digital API |
-| 密钥泄露 | `.env.example` 含历史示例值，生产必须使用独立密钥 |
+| dev 端口 | `pnpm dev` → **3001**，不是 3000 |
+| API 分流 | `/api/digital/*`、`/api/media/*` 不走 FastAPI |
+| `/api/videos` | 独立路由；`/api/content/videos` 会 404 |
+| 8000 多进程 | 多个 uvicorn 占端口时 session 等新路由可能不生效 |
+| PowerShell | 不支持 `&&`，分步执行 |
+| 双套 lib | `app/lib/` vs `app/digital/lib/` 各自独立 |
+| MiroTalk embed | `ALLOWED_EMBED_ORIGINS` 需含 nomadro.cn 与 localhost:3001 |
+| Ergo 公网 | 不开放 IRC 6697；仅 The Lounge 内网连 Ergo |
+| 密钥 | `.env.example` 仅示例，生产用独立密钥 |
 
 ---
 
@@ -414,27 +427,27 @@ systemctl restart cnomadcna.service
 | 场景 | 文件 |
 |------|------|
 | 新增主站页面 | `app/[locale]/`、`messages/*.json` |
-| 新增 Digital 页面 | `app/[locale]/digital/`、`app/digital/components/` |
+| 活动间 | `meetups/[id]/live/page.tsx`、`EventLiveRoom.tsx`、`meetup_live.py` |
+| 活动 URL/权限 | `app/lib/meetups.ts` |
+| 访谈视频 | `videos/page.tsx`、`GET /api/videos` |
+| 社区匹配 | `dating/page.tsx`、`dating/components/*` |
 | 调用后端 | `app/lib/api-client.ts` |
-| 活动视频链接 | `app/lib/meetups.ts` |
-| 支付流程 | `app/lib/payment/`、`backend/payment.py` |
-| 主题切换 | `app/context/ThemeContext.tsx` |
-| 导航配置 | `config/nav.config.ts` |
-| API 代理规则 | `next.config.ts` |
+| 封面/媒体 URL | `app/lib/media.ts` |
+| 头像池 | `app/data/avatars.ts`、`backend/avatar_assets.py` |
+| 远程开发 | `config/remote-services.ts`、`scripts/dev-tunnel.py` |
+| API 代理 | `next.config.ts` |
 | 后端入口 | `backend/main.py` |
-| PocketBase 客户端 | `backend/pb_client.py` |
-| 完整运维文档 | `README.md` |
-| 前端专项分析 | `PROJECT_ANALYSIS_REPORT.md` |
+| DB 初始化 | `backend/init_db.py`、`seed_data.py` |
+| 完整运维 | `README.md` |
 
 ---
 
 ## 15. 相关文档
 
-- `README.md` — 完整业务介绍、部署、服务运维、安全注意事项
-- `PROJECT_ANALYSIS_REPORT.md` — 前端模块梳理与后续开发方向（2026-06-06）
-- `app/lib/charts/README.md` — 图表组件使用说明
-- `.env.example` / `backend/.env.example` — 环境变量模板
+- `README.md` — 业务介绍、部署、MiroTalk/Lounge 运维、Windows 本地开发
+- `.env.example` — 环境变量模板
+- `app/lib/charts/README.md` — 图表组件
 
 ---
 
-*本文件供 Cursor AI 在编辑 NomadCNA 代码库时快速建立上下文。重大架构变更后请同步更新此文档。*
+*本文件供 Cursor AI 编辑 NomadCNA 时快速建立上下文。重大架构变更后请同步更新。*