开发文档

一、技术架构

• 技术栈：Next.js 16（App Router）+ React 19 + TypeScript + Prisma ORM + PostgreSQL + Redis；包管理 pnpm；
• 运行形态：Web 进程（next start，默认 127.0.0.1:3000）+ Worker 进程（后台任务/队列）；生产建议用 systemd 各起一个服务，前面挂 Nginx 反代 + HTTPS；
• 部署方式：仓库自带 Dockerfile 与 docker-compose.yml（含 Postgres/Redis），也可以不用 Docker 手工部署（Node 20+ / pnpm）。

二、目录结构

项目根/
├── src/
│   ├── app/            # Next.js App Router 路由（页面 + /api 接口）
│   ├── components/     # 前端组件
│   ├── db/             # Prisma 客户端与数据访问
│   ├── hooks/ lib/     # 前端 Hooks 与工具
│   ├── addons-host/    # 插件/扩展宿主
│   ├── styles/ types/  # 样式与类型定义
│   └── proxy.ts
├── prisma/
│   ├── schema.prisma   # 数据模型（唯一数据源）
│   ├── migrations/     # 迁移历史（生产用 migrate deploy）
│   └── seed.ts         # 初始化数据
├── docs/ scripts/      # 文档与运维脚本
├── public/             # 静态资源
├── next.config.mjs / tsconfig.json / write-guard.config.ts
└── Dockerfile / docker-compose.yml

三、数据模型（Prisma）

• 用户与认证：User、AuthAccount、AuthPasskey、OAuthClient / OAuthAuthorizationCode / OAuthAccessToken / OAuthRefreshToken / OAuthConsent；
• 社区内容与关系：Zone（分区）、Board（版块）、BoardFollow / UserFollow（关注）、ModeratorZoneScope / ModeratorBoardScope（版主权限范围）；
• 等级与成长：LevelDefinition、UserLevelProgress；
• 玩法/扩展：GobangMatch / GobangMove（五子棋）、YinYangChallenge*（阴阳挑战）、SelfServeAdOrder（自助广告）；
• 支付与权限：PaymentApplication / PaymentTransaction、AdminPermissionGrant（后台权限授权）。

四、关键机制

4.1 数据模型先行（Prisma）

改表结构 = 改 prisma/schema.prisma → pnpm prisma migrate dev 生成迁移 → 生产用 prisma migrate deploy。不要手写 SQL 改库，否则模型与库会不一致。

4.2 接口

接口按 App Router 约定放在 src/app/api/<模块>/route.ts（export async function GET/POST）。外部系统对接（自动开号/同步）就是新增一个 route 文件，例如演示站里的 /api/demo-account。

4.3 后台权限

权限粒度由 AdminPermissionGrant + 角色的组合控制；加一个后台功能时同时要登记权限点，否则管理员看不到入口。

五、二次开发指引

• 改完必须重新构建：pnpm build（约 1~2 分钟）→ 重启 Web 进程，否则页面还是旧的；
• 加页面：src/app/<路径>/page.tsx（+ 需要的 layout.tsx）；加接口：src/app/api/<路径>/route.ts；
• 加表：prisma/schema.prisma + 迁移；种子数据改 prisma/seed.ts；
• Node 脚本：要放在项目目录里执行（否则 Cannot find module '@prisma/client'）；
• 环境变量：数据库地址、Redis、密钥全在 .env（部署时生成，不入库）。

六、部署与升级

标准升级流程：拉新代码 → pnpm install → prisma migrate deploy → pnpm build → 重启服务。数据库迁移是幂等的，回滚请用迁移记录 + 备份（Postgres pg_dump）。