第一章：整体架构1.1 设计理念本项目的后端 API 采用Next.js 13 App Router的Route Handlers能力构建。你可以把它理解为：每个 API 端点都是一个独立的“小服务”，它们共同组成了一个完整的游戏后端。所有业务接口都统一放在/api/game这个“大门”下，这样做的好处是：路径清晰：一眼就能看出这是游戏相关的功能便于管理：相关的功能模块集中存放易于扩展：新增功能只需在game下新建目录1.2 技术架构图HTTP Request验证通过验证失败参数校验校验失败校验通过读取操作命中未命中写入操作完成后SSE事件数据统一格式客户端鉴权中间件Route Handlerssrc/app/api/game/*/route.ts返回401错误Zod Schema返回400错误业务处理层LRU缓存返回结果Prisma + PostgreSQL事务保证实时推送1.3 目录结构说明src/app/api/game/ ├── start/ # 游戏初始化 │ └── route.ts ├── action/ # 玩家动作 │ └── route.ts ├── combat/ # 战斗日志 │ └── route.ts ├── achievements/ # 成就系统 │ └── route.ts ├── alliances/ # 联盟系统 │ └── route.ts ├── policy/ # 政策系统 │ └── route.ts └── events/ # 实时事件 └── route.ts每个route.ts文件都保持精简，只做三件事：校验身份 → 校验参数 → 调用核心逻辑。第二章：通用约定规范2.1 HTTP 方法使用规范方法使用场景示例GET查询数据，不改变服务器状态查询联盟列表、获取政策详情POST创建资源或触发动作提交战斗指令、解锁成就PUT/PATCH更新现有资源修改玩家配置DELETE删除资源退出联盟（少数情况）2.2 统一的返回格式所有的 API 都遵循相同的“包装格式”，就像快递包裹一样：// 成功时{success:true,data:{/* 具体的业务数据 */}}// 失败时{success:false,error:"具体的错误信息"}2.3 鉴权机制验证服务API Gateway客户端验证服务API Gateway客户端