​
技术栈

  • 框架：Next.js 16（App Router）+ React 19
  • 语言：TypeScript（strict）
  • 样式：Tailwind CSS v4
  • 数据库：PostgreSQL + Prisma
  • 内容：MDX（Blog / Reading / Travel）+ JSON（Travel index 与 hero）
  • 测试：tsx --test

​
业务模块

网站包含四个内容模块和一个后台模块：
  1. Blog（技术文章）
  2. Reading（读书笔记）
  3. Travel（旅行日志）
  4. Projects（项目作品）
  5. Admin（后台管理）

​
核心目录

app/                # 页面路由与 API 路由
components/         # 页面与业务组件
content/            # 内容源（MDX/JSON）
lib/                # 解析器、仓储、同步逻辑
prisma/             # 数据模型与迁移
scripts/            # 同步和运维脚本
tests/              # 测试

​
数据流（读取）

默认读取路径如下：
  1. 页面调用 lib/*/repository.ts 或 lib/travel/content.ts
  2. 如果存在 DATABASE_URL，优先尝试读取数据库
  3. 数据库不可用时回退到 content/* 文件
  4. 页面渲染列表或详情
这样做可以保证：
  • 本地无数据库时仍可预览主要内容
  • 生产有数据库时可用后台统一管理

​
数据流（写入/同步）

主要通过以下入口同步内容：
  • CLI：npm run content:sync
  • API：POST /api/admin/sync
同步逻辑会：
  1. 扫描内容目录（如 content/blog/*）
  2. 解析 frontmatter
  3. upsert 到数据库
  4. 处理标签、系列等关系
  5. 对本地已删除内容做归档状态更新（ARCHIVED）

​
路由总览

主要前台路由：
  • /
  • /blog、/blog/[slug]、/blog/tag/[slug]、/blog/series/[slug]
  • /reading、/reading/[slug]
  • /travel、/travel/[slug]
  • /projects、/projects/[slug]
主要后台路由：
  • /admin/login
  • /admin
  • /admin/posts
  • /admin/reading
  • /admin/travel
  • /admin/projects
主要后台 API：
  • POST /api/admin/login
  • POST /api/admin/logout
  • POST /api/admin/sync

​
你应该先读哪一页

  • 你负责内容编辑：从 /guides/content-blog 开始
  • 你负责后台运营：从 /guides/admin-dashboard 开始
  • 你负责上线维护：从 /guides/deployment 开始