549 lines
19 KiB
Markdown
549 lines
19 KiB
Markdown
# NomadCNA 前端项目分析报告
|
||
|
||
生成日期：2026-06-06
|
||
|
||
## 1. 分析范围与结论
|
||
|
||
本报告只分析当前仓库中的前端项目现状。仓库内虽然存在 `app/api`、PocketBase、支付、MinIO 等旧接口适配代码，但根据当前开发方向，这部分后端实现已隔离，后续应由 FastAPI + PocketBase 重新设计和实现。因此本文不会把旧 `app/api` 作为未来后端实现依据，只把它们作为“前端当前依赖的接口形状”记录，方便后续替换。
|
||
|
||
总体判断：
|
||
|
||
- 当前项目是一个 Next.js 16 App Router 前端应用，核心体验已经具备较完整的页面骨架和视觉资产。
|
||
- 主要业务数据仍以 TypeScript 静态数据、配置文件和页面内 mock 数据为主。
|
||
- 前端已覆盖城市探索、下一站决策、社区加入、会员支付入口、聚会、匹配、讨论、赏金、工具箱、年报、地图、内容页和法律页等模块。
|
||
- 后续真实开发重点不是重写 UI，而是抽离接口层、设计 PocketBase 数据模型、用 FastAPI 承接认证、业务规则、支付、上传、AI、统计等后端能力。
|
||
- 当前前端和旧后端存在耦合，需要在后续开发中集中替换为统一 API client 和清晰的数据契约。
|
||
|
||
## 2. 技术栈概览
|
||
|
||
### 2.1 主要依赖
|
||
|
||
来自 `package.json`：
|
||
|
||
- Next.js：`16.1.6`
|
||
- React / React DOM：`19.2.3`
|
||
- TypeScript：`^5`
|
||
- Tailwind CSS：`^4`
|
||
- ECharts：`^6.0.0`
|
||
- PocketBase JS SDK：`^0.26.8`
|
||
- MinIO SDK：`^8.0.7`
|
||
- 包管理：`pnpm@10.25.0`
|
||
|
||
### 2.2 运行脚本
|
||
|
||
- `pnpm dev`：`next dev -p 3001 -H 0.0.0.0`
|
||
- `pnpm build`：生产构建
|
||
- `pnpm start`：生产启动
|
||
- `pnpm lint`：ESLint
|
||
|
||
注意：`README.md` 中写的是打开 `http://localhost:3000`，但实际 dev 脚本端口是 `3001`，文档需要同步。
|
||
|
||
## 3. 目录结构与职责
|
||
|
||
当前关键目录：
|
||
|
||
```text
|
||
app/
|
||
[locale]/ 多语言页面路由
|
||
components/ 通用前端组件
|
||
context/ Locale / Theme Context
|
||
data/ 静态业务数据
|
||
lib/ 前端工具库、旧服务适配、图表组件
|
||
api/ 旧 Next API Route，后续不建议作为目标后端保留
|
||
config/ 站点、导航、首页、页脚、服务配置
|
||
i18n/ 本地化导航封装
|
||
messages/ zh / en 文案
|
||
public/ 静态资源
|
||
```
|
||
|
||
### 3.1 前端核心文件
|
||
|
||
- `app/layout.tsx`：全局 HTML、主题脚本、ThemeProvider。
|
||
- `app/[locale]/layout.tsx`：语言路由布局，加载多语言消息，挂载 Navbar。
|
||
- `app/[locale]/page.tsx`：首页，包含 Hero、城市列表、筛选、热门路线、社区动态。
|
||
- `app/globals.css`：Tailwind 4 入口、深色模式、全局布局类、城市卡片和表单样式。
|
||
- `app/context/LocaleContext.tsx`：自定义 i18n Context 和路由跳转封装。
|
||
- `app/context/ThemeContext.tsx`：亮色/暗色主题，使用 localStorage 保存偏好。
|
||
|
||
### 3.2 配置文件
|
||
|
||
- `config/site.config.ts`：站点标题、描述、口号。
|
||
- `config/nav.config.ts`：顶部导航入口。
|
||
- `config/home.config.ts`：首页成员头像、路线、热门话题、统计数据。
|
||
- `config/footer.config.ts`：页脚链接。
|
||
- `config/services.config.ts`、`config/domain.config.ts`：旧服务配置。未来后端重写时应重构为前端只保留 `NEXT_PUBLIC_API_BASE_URL` 等必要公开变量。
|
||
|
||
## 4. 页面模块梳理
|
||
|
||
当前 `app/[locale]` 下页面较完整，页面数量约 31 个。
|
||
|
||
### 4.1 首页与城市探索
|
||
|
||
相关文件：
|
||
|
||
- `app/[locale]/page.tsx`
|
||
- `app/components/HeroSection.tsx`
|
||
- `app/components/FilterBar.tsx`
|
||
- `app/components/CityCard.tsx`
|
||
- `app/components/CityModal.tsx`
|
||
- `app/data/cities.ts`
|
||
|
||
能力现状：
|
||
|
||
- 首页展示城市卡片网格，支持按标签筛选和按综合评分、费用、网速、安全、游民数量、温度排序。
|
||
- 城市数据来自 `app/data/cities.ts`，共 18 个城市。
|
||
- `CityCard` 提供卡片 hover 评分展示。
|
||
- `CityModal` 提供接近 Nomad List 风格的城市详情弹窗，但大量 tab 内容仍是占位。
|
||
- 首页的成员、路线、热门话题、社区动态来自 `config/home.config.ts`。
|
||
|
||
后续真实化方向：
|
||
|
||
- 城市、城市指标、标签、封面图、热度、评分、评论、气候、网速、生活成本应迁入 PocketBase。
|
||
- 首页统计、热门路线、成员头像、热门话题应改由 FastAPI 聚合返回。
|
||
- 筛选逻辑目前在前端内存完成；真实数据量上来后应由后端分页、排序、过滤。
|
||
|
||
### 4.2 下一站决策仪表盘
|
||
|
||
相关文件：`app/[locale]/dashboard/page.tsx`
|
||
|
||
能力现状：
|
||
|
||
- 用户可设置预算、最低网速、时区、签证偏好、希望认识的人群。
|
||
- 实际筛选只使用预算和网速，数据来自本地 `cities`。
|
||
- 成本曲线、游民密度热力图、AI 推荐等为占位。
|
||
|
||
后续真实化方向：
|
||
|
||
- 建立城市推荐 API，根据预算、网速、气候、社区密度、签证、职业偏好等返回排序结果。
|
||
- AI 推荐可以由 FastAPI 调用模型服务，结果落库便于复盘。
|
||
- 图表数据需要后端提供时间序列、城市指标、用户偏好权重。
|
||
|
||
### 4.3 加入社区与会员支付
|
||
|
||
相关文件：
|
||
|
||
- `app/[locale]/join/page.tsx`
|
||
- `app/[locale]/join/paid/page.tsx`
|
||
- `app/components/JoinModal.tsx`
|
||
- `app/components/AuthModal.tsx`
|
||
- `app/components/HeroSection.tsx`
|
||
|
||
能力现状：
|
||
|
||
- 首页 Hero 支持输入邮箱并进入加入/支付流程。
|
||
- `/join` 是较完整的报名表单，包含昵称、性别、感情状态、职业、微信、手机、自我介绍、学历、毕业时间、头像/视频上传。
|
||
- 当前页面会调用旧接口：`/api/auth/me`、`/api/join`、`/api/join/status`、`/api/vip/check`、`/api/upload-media`、`/api/pay/status`、`/api/meetup/*` 等。
|
||
- 支付成功页负责完成订单、同步登录态、设置改密状态等。
|
||
|
||
后续真实化方向：
|
||
|
||
- FastAPI 统一接管登录、报名、会员状态、订单创建、支付回调、支付状态查询、媒体上传。
|
||
- PocketBase 存储用户、资料、报名表、会员权益、订单、支付流水。
|
||
- 前端应只调用 FastAPI，不直接处理 PocketBase 管理员逻辑。
|
||
- 支付状态和订单状态需要明确状态机，例如 `pending`、`paid`、`failed`、`expired`、`refunded`。
|
||
|
||
### 4.4 社区、匹配、聚会、讨论、赏金
|
||
|
||
相关页面：
|
||
|
||
- `app/[locale]/dating/page.tsx`
|
||
- `app/[locale]/meetups/page.tsx`
|
||
- `app/[locale]/meetups/host/page.tsx`
|
||
- `app/[locale]/discuss/page.tsx`
|
||
- `app/[locale]/gigs/page.tsx`
|
||
|
||
能力现状：
|
||
|
||
- 匹配页有 profile card、喜欢/不感兴趣按钮、匹配类型 tab，但使用页面内 mock。
|
||
- 聚会页有 upcoming / previous tab，聚会列表全部 hardcode。
|
||
- 发起聚会页有表单，文案明确“演示模式，数据不会保存”。
|
||
- 讨论页使用 `MOCK_TOPICS`，支持搜索过滤。
|
||
- 赏金墙使用 `MOCK_GIGS`。
|
||
|
||
后续真实化方向：
|
||
|
||
- 聚会：活动创建、审核、发布、报名、取消报名、参与者列表、城市筛选。
|
||
- 匹配：个人资料、目标类型、滑动记录、互相喜欢、举报/拉黑、推荐排序。
|
||
- 讨论：话题、评论、点赞、浏览数、标签、审核。
|
||
- 赏金：任务发布、接单、交付、评价、平台抽成、支付/托管。
|
||
|
||
### 4.5 工具箱、AI、年报、地图和数据报告
|
||
|
||
相关页面：
|
||
|
||
- `app/[locale]/tools/page.tsx`
|
||
- `app/[locale]/ai/page.tsx`
|
||
- `app/[locale]/report/page.tsx`
|
||
- `app/[locale]/report/data/page.tsx`
|
||
- `app/[locale]/map/page.tsx`
|
||
- `app/lib/charts/*`
|
||
|
||
能力现状：
|
||
|
||
- 工具箱包含静态汇率、税务估算、签证倒计时，FIRE 和气候查询为占位。
|
||
- AI 页面为即将上线状态。
|
||
- 年报页面是静态生成入口和展示样式。
|
||
- 地图和数据报告使用 `MAP_CITIES` 静态城市坐标和 ECharts 地图组件。
|
||
|
||
后续真实化方向：
|
||
|
||
- 汇率、天气、气候、签证政策属于外部数据集成，应由 FastAPI 定时同步或按需代理。
|
||
- 年报依赖用户行程、城市停留、消费、活动报名、社区互动等真实数据。
|
||
- 地图应聚合匿名化成员城市分布，避免暴露个人精确位置。
|
||
- AI 需要用户上下文、城市数据和安全边界。
|
||
|
||
### 4.6 内容与静态信息页
|
||
|
||
相关页面：
|
||
|
||
- `blog`、`careers`、`press`、`help`
|
||
- `about`、`contact`、`support`
|
||
- `terms`、`privacy`、`cookies`、`safety`、`guidelines`
|
||
|
||
能力现状：
|
||
|
||
- 多数内容来自 `app/data/mock.ts`。
|
||
- 页面完成度适合 MVP 展示，但没有 CMS 或后台维护能力。
|
||
|
||
后续真实化方向：
|
||
|
||
- 内容可先继续静态化，后期迁入 PocketBase 作为轻量 CMS。
|
||
- 法律、隐私、帮助中心等应有版本号和更新时间。
|
||
- 招聘、媒体报道、博客需要 slug、SEO metadata、草稿/发布状态。
|
||
|
||
## 5. 数据来源现状
|
||
|
||
### 5.1 静态数据
|
||
|
||
- `app/data/cities.ts`：18 个城市，含成本、网速、安全、温度、标签、封面、经纬度等。
|
||
- `app/data/map-cities.ts`：地图城市坐标和成员数。
|
||
- `app/data/mock.ts`：博客、招聘、媒体报道、帮助中心、安全指南、社区准则、联系信息、条款、隐私、Cookie。
|
||
- `config/home.config.ts`：首页社群头像、旅行中成员、聚会、热门话题、路线、统计。
|
||
- 页面内 mock：聚会、匹配、讨论、赏金等。
|
||
|
||
### 5.2 多语言数据
|
||
|
||
- `messages/zh.json`
|
||
- `messages/en.json`
|
||
|
||
当前 i18n 是自定义 Context，不依赖 next-intl。优点是简单可控，缺点是类型约束弱，缺少自动 key 检查，也没有格式化复数、日期、变量插值的完整能力。
|
||
|
||
### 5.3 外部资源
|
||
|
||
当前大量图片来自：
|
||
|
||
- `i.pravatar.cc`
|
||
- `images.unsplash.com`
|
||
- `api.dicebear.com`
|
||
- `logo.clearbit.com`
|
||
|
||
这些适合原型阶段，但生产环境需要明确版权、可用性、缓存策略、头像隐私和图片优化策略。
|
||
|
||
## 6. 前端状态与交互方式
|
||
|
||
当前项目大量使用 client component：
|
||
|
||
- `useState` 管理表单、弹窗、tab、筛选、排序。
|
||
- `useMemo` 做城市筛选、聚会分类。
|
||
- `localStorage` 保存主题、旧 PocketBase token、用户信息、支付订单。
|
||
- `document.cookie` 保存旧支付订单状态和服务端 session。
|
||
- `createPortal` 实现 AuthModal、JoinModal、CityModal。
|
||
- `window.location.href` / `replace` 用于语言切换、支付回跳和登录同步。
|
||
|
||
后续建议：
|
||
|
||
- 建立统一 `app/lib/api-client.ts` 或 `app/services/*`，集中处理 API base URL、鉴权、错误码、重试、超时。
|
||
- 把旧 PocketBase 前端 SDK 调用逐步移除，前端只通过 FastAPI 访问业务接口。
|
||
- 登录态统一为 httpOnly cookie + `/auth/me`，避免前端长期保存敏感 token。
|
||
- 表单建议引入 schema 校验，例如 Zod；至少在前后端共享字段约束。
|
||
|
||
## 7. 当前主要风险
|
||
|
||
### 7.1 敏感信息风险
|
||
|
||
`.env.example` 和 `.env.local` 中存在 PocketBase 管理员邮箱和密码字段，并且当前样例包含明文值。即使这些只是旧后端配置，也应立即视为泄露风险：
|
||
|
||
- 从仓库中移除真实凭据。
|
||
- 轮换 PocketBase 管理员密码。
|
||
- `.env.example` 只保留占位符。
|
||
- 后续 FastAPI 服务端使用 Secret Manager 或部署平台环境变量。
|
||
|
||
### 7.2 前端与旧后端耦合
|
||
|
||
多个核心前端组件直接调用旧路径：
|
||
|
||
- `Navbar`：`/api/auth/me`、`/api/auth/sync-session`
|
||
- `HeroSection`：`/api/auth/me`、`/api/meetup/check-user`、`/api/meetup/ensure-user`
|
||
- `JoinModal`：`/api/meetup/ensure-user`
|
||
- `join/page.tsx`：`/api/join`、`/api/join/status`、`/api/vip/check`、`/api/upload-media`
|
||
- `join/paid/page.tsx`：`/api/meetup/complete-order`、`/api/auth/change-password`
|
||
- payment hooks：`/api/pay`、`/api/pay/status`
|
||
- charts：`/api/geo/china`
|
||
|
||
这些路径后续需要迁移到 FastAPI，并通过统一 API client 映射。
|
||
|
||
### 7.3 大量业务仍为 mock
|
||
|
||
当前页面中明确存在“演示模式”“开发中”“即将上线”：
|
||
|
||
- 反馈提交
|
||
- 发起聚会
|
||
- 成员地图
|
||
- 数据报告
|
||
- AI
|
||
- FIRE 计算器
|
||
- 气候查询
|
||
- 仪表盘图表
|
||
|
||
这不是坏事，说明前端原型覆盖面广；但后续排期需要明确哪些 mock 优先变成真实闭环。
|
||
|
||
### 7.4 日期数据过期
|
||
|
||
当前日期为 2026-06-06，但聚会页仍把 2026-03 和 2026-04 的活动标记为“即将举办”。后续真实数据必须由后端按当前时间计算活动状态，不能依赖静态 `isUpcoming`。
|
||
|
||
### 7.5 文档与实际运行不一致
|
||
|
||
- README 写 `localhost:3000`，脚本实际是 `3001`。
|
||
- README 写 Node.js 18+，但 Next.js 16 / React 19 的实际运行要求需要在开发环境中确认并统一。
|
||
|
||
### 7.6 UI 资产和图片生产化不足
|
||
|
||
- 大量使用第三方随机头像和远程图片。
|
||
- 未系统使用 `next/image`。
|
||
- 没有图片域名、尺寸、占位、失败回退策略。
|
||
|
||
## 8. 后续 FastAPI + PocketBase 目标架构建议
|
||
|
||
### 8.1 推荐边界
|
||
|
||
建议后续边界如下：
|
||
|
||
```text
|
||
Next.js 前端
|
||
只负责页面、交互、渲染、调用 FastAPI
|
||
|
||
FastAPI
|
||
负责业务 API、认证会话、权限、支付、上传、AI、统计聚合、外部服务集成
|
||
|
||
PocketBase
|
||
负责数据存储、基础用户表、文件/记录管理、后台管理界面、必要的 realtime 能力
|
||
```
|
||
|
||
关键原则：
|
||
|
||
- 前端不要直接使用 PocketBase 管理员权限。
|
||
- 复杂业务规则放在 FastAPI，不散落在前端。
|
||
- PocketBase 作为数据和后台管理层，不承担所有业务流程。
|
||
- 支付回调、会员开通、退款、上传鉴权、AI 调用必须走 FastAPI。
|
||
|
||
### 8.2 建议数据模型
|
||
|
||
首批 PocketBase collections 可按以下方向设计：
|
||
|
||
- `users`：用户基础账号，可使用 PocketBase auth collection。
|
||
- `profiles`：昵称、头像、职业、城市、简介、标签、匹配偏好。
|
||
- `member_applications`：加入社区报名表。
|
||
- `memberships`：会员等级、有效期、权益、状态。
|
||
- `orders`：订单号、用户、金额、渠道、状态、业务类型。
|
||
- `payment_events`：支付回调原始事件和处理状态。
|
||
- `media_assets`：上传文件、类型、归属用户、用途。
|
||
- `cities`：城市基础信息、slug、多语言名称、坐标、封面。
|
||
- `city_metrics`：成本、网速、气候、安全、社区密度等指标。
|
||
- `city_guides`：城市攻略、共享办公、社区推荐、tips。
|
||
- `meetups`：聚会活动。
|
||
- `meetup_rsvps`：活动报名关系。
|
||
- `discussions`：讨论话题。
|
||
- `comments`：评论。
|
||
- `gigs`：赏金任务。
|
||
- `gig_applications`：接单/投递。
|
||
- `swipes`：匹配滑动记录。
|
||
- `matches`：互相喜欢记录。
|
||
- `feedback`：建议与 Bug 反馈。
|
||
- `annual_reports`：年报生成结果和快照。
|
||
|
||
## 9. FastAPI API 清单草案
|
||
|
||
### 9.1 认证与用户
|
||
|
||
- `POST /auth/register`
|
||
- `POST /auth/login`
|
||
- `POST /auth/logout`
|
||
- `GET /auth/me`
|
||
- `POST /auth/change-password`
|
||
- `GET /users/me/profile`
|
||
- `PATCH /users/me/profile`
|
||
|
||
### 9.2 加入社区与会员
|
||
|
||
- `GET /join/status`
|
||
- `POST /join/applications`
|
||
- `GET /memberships/me`
|
||
- `POST /payments/checkout`
|
||
- `GET /payments/{order_id}/status`
|
||
- `POST /payments/webhooks/{provider}`
|
||
|
||
### 9.3 媒体上传
|
||
|
||
- `POST /media/uploads`
|
||
- `GET /media/{id}`
|
||
- `DELETE /media/{id}`
|
||
|
||
### 9.4 城市与推荐
|
||
|
||
- `GET /cities`
|
||
- `GET /cities/{slug}`
|
||
- `GET /cities/{slug}/metrics`
|
||
- `GET /cities/{slug}/guide`
|
||
- `POST /recommendations/next-stop`
|
||
- `GET /routes/hot`
|
||
|
||
### 9.5 社区模块
|
||
|
||
- `GET /meetups`
|
||
- `POST /meetups`
|
||
- `GET /meetups/{id}`
|
||
- `POST /meetups/{id}/rsvp`
|
||
- `DELETE /meetups/{id}/rsvp`
|
||
- `GET /discussions`
|
||
- `POST /discussions`
|
||
- `GET /discussions/{id}/comments`
|
||
- `POST /discussions/{id}/comments`
|
||
|
||
### 9.6 匹配模块
|
||
|
||
- `GET /matches/candidates`
|
||
- `POST /matches/swipes`
|
||
- `GET /matches/me`
|
||
- `POST /reports/profile`
|
||
- `POST /blocks/profile`
|
||
|
||
### 9.7 赏金与反馈
|
||
|
||
- `GET /gigs`
|
||
- `POST /gigs`
|
||
- `POST /gigs/{id}/apply`
|
||
- `POST /feedback`
|
||
|
||
### 9.8 数据报告与 AI
|
||
|
||
- `GET /stats/member-map`
|
||
- `GET /stats/city-ranking`
|
||
- `POST /reports/annual/generate`
|
||
- `GET /reports/annual/{id}`
|
||
- `POST /ai/assistant`
|
||
|
||
## 10. 前端改造路线
|
||
|
||
### 阶段 0：清理与契约冻结
|
||
|
||
- 移除仓库中的真实密钥，轮换泄露风险凭据。
|
||
- 明确旧 `app/api` 全部为 legacy，不继续扩展。
|
||
- 建立 `NEXT_PUBLIC_API_BASE_URL`。
|
||
- 梳理当前前端调用接口，写成接口契约文档。
|
||
- 修正 README 端口和环境说明。
|
||
|
||
### 阶段 1：统一 API client
|
||
|
||
- 新增统一 API client，集中处理：
|
||
- base URL
|
||
- credentials
|
||
- JSON 解析
|
||
- 错误响应
|
||
- 登录失效
|
||
- loading / retry 策略
|
||
- 替换 `fetch("/api/...")` 为领域服务函数，例如 `authApi.me()`、`joinApi.submit()`。
|
||
- 前端保留 mock fallback，方便后端未完成时继续开发 UI。
|
||
|
||
### 阶段 2：认证、报名、支付闭环
|
||
|
||
优先原因：这是转化和会员收入核心链路。
|
||
|
||
- FastAPI 实现注册、登录、会话、改密。
|
||
- FastAPI 实现报名表提交。
|
||
- 实现支付下单、支付状态、支付回调、会员开通。
|
||
- 实现上传鉴权和媒体资产记录。
|
||
- 前端替换 Hero、JoinModal、JoinPage、JoinPaidPage、Navbar 的旧接口调用。
|
||
|
||
### 阶段 3：城市数据真实化
|
||
|
||
- 将 `cities.ts` 迁入 PocketBase。
|
||
- 前端首页和仪表盘改为调用 `/cities`。
|
||
- 城市详情弹窗拆分真实字段和占位字段。
|
||
- 建立城市 slug，避免只用中文城市名作为业务 key。
|
||
|
||
### 阶段 4：社区功能真实化
|
||
|
||
- 聚会列表和发起聚会落库。
|
||
- 讨论和评论落库。
|
||
- 匹配候选人、滑动、match 记录落库。
|
||
- 赏金墙发布和接单落库。
|
||
|
||
### 阶段 5：AI、年报、统计
|
||
|
||
- 接入 AI 助手。
|
||
- 根据真实用户行为生成年度报告。
|
||
- 地图、城市排名、增长趋势改由后端聚合。
|
||
|
||
### 阶段 6：运营后台与权限
|
||
|
||
- 使用 PocketBase Admin 作为轻量后台。
|
||
- 增加内容审核、聚会审核、举报处理、会员管理、订单查询。
|
||
- FastAPI 增加管理员 API 或管理脚本。
|
||
|
||
## 11. 建议优先级
|
||
|
||
P0：
|
||
|
||
- 凭据清理与轮换。
|
||
- 统一 API base URL 和 API client。
|
||
- 认证、报名、支付、会员状态真实闭环。
|
||
- 上传链路真实化。
|
||
|
||
P1：
|
||
|
||
- 城市数据迁移 PocketBase。
|
||
- 首页、城市详情、仪表盘接入真实城市 API。
|
||
- 聚会列表和报名真实化。
|
||
- 反馈提交真实化。
|
||
|
||
P2：
|
||
|
||
- 匹配、讨论、赏金墙真实化。
|
||
- 地图和数据报告真实化。
|
||
- AI 助手上线。
|
||
|
||
P3：
|
||
|
||
- 内容 CMS 化。
|
||
- SEO metadata 完善。
|
||
- 图片优化和 CDN 策略。
|
||
- 自动化测试和监控。
|
||
|
||
## 12. 测试与验收建议
|
||
|
||
前端：
|
||
|
||
- `pnpm lint`
|
||
- `pnpm build`
|
||
- 首页、加入表单、登录弹窗、支付回跳、城市筛选、语言切换、暗色模式的 Playwright E2E。
|
||
- 移动端视口检查，尤其是首页网格、Join 表单、CityModal。
|
||
|
||
后端：
|
||
|
||
- FastAPI 单元测试：认证、报名、支付状态机、权限。
|
||
- 支付 webhook 幂等测试。
|
||
- PocketBase collection rule 测试。
|
||
- 媒体上传大小、类型、权限测试。
|
||
|
||
契约：
|
||
|
||
- OpenAPI 自动生成。
|
||
- 前端类型从 OpenAPI 生成或至少共享 DTO schema。
|
||
- mock server 保持和 OpenAPI 一致。
|
||
|
||
## 13. 总结
|
||
|
||
当前项目的价值主要在前端产品原型和页面覆盖度：导航、首页、城市探索、会员加入、社区、工具、内容页都已经成型。短板集中在数据真实性、后端契约、认证支付安全、mock 数据和旧接口耦合。
|
||
|
||
后续开发不建议在旧 `app/api` 上继续补功能。更稳妥的路线是保留当前 Next.js 前端体验，新增 FastAPI 后端，PocketBase 作为数据和后台管理层，然后按“认证/报名/支付 -> 城市数据 -> 社区互动 -> AI/统计”的顺序逐步替换 mock 和旧接口。
|