前述，前言，预览效果

最后一篇放出程序和源码，敬请期待。

一、项目定位与技术目标

1.1 项目定位

这是一款基于 Web 的回合制策略/叙事游戏，面向中文玩家群体。游戏设定在三国的虚构历史分支中，玩家需要在政治、军事、外交、占星等多个维度进行决策，每个选择都将影响世界走向。

核心体验：系统通过大语言模型（LLM）动态生成文言风格的叙事文本，并在关键时刻给出“蝴蝶效应”提示，让玩家感受到决策的深远影响。
大模型如果配置失败则返回错误信息，如下图所示：

1.2 技术目标

为了保证项目的长期可维护性和团队协作效率，我确立了以下技术原则：

目标	实现方式	收益
类型安全	TS + Prisma	编译时发现错误，IDE 智能提示
高可维护性	三层架构分离	修改 UI 不影响逻辑，更换数据库无痛
可观测性	日志 + SSE + Cron	问题可追溯，状态实时可见
可扩展性	插件化设计	新增功能不破坏现有代码

---

二、核心子系统详解

2.1 子系统全景图

2.2 各子系统职责

🎮 Narrative Engine（叙事引擎）

路径：src/lib/game/engine.ts

这是游戏的心脏。它负责：

• 构造上下文：收集当前游戏状态（年份、季节、玩家资源、角色属性、历史事件）
• 调用 LLM：将上下文发送给 ZAI 大模型，请求生成叙事和世界变化
• 解析结果：将 LLM 返回的 JSON 转换为可执行的世界变更指令
• 记录日志：将每次回合的关键事件写入日志表

⚔️ Combat System（战斗系统）

位于同一文件的 resolveCombat 函数。输入敌我双方数据、地形、天气，输出战斗叙事和伤亡统计，并写入 CombatLog 表。

🤝 Diplomacy System（外交系统）

processDiplomacy 函数处理同盟、停战、贸易等提案，返回包含关系变化量的 DiplomacyResult。

🔮 Astrology（占星系统）

根据游戏内的季节和星象配置，消耗玩家资源（如祭品），生成带有预言性质的随机事件。

📜 Policy System（政策系统）

玩家激活不同的政策卡，每张卡影响资源产出或角色属性，效果持久化到 Policy 表。

🏆 Achievement System（成就系统）

路径：src/lib/game/achievements.ts

持续监测世界状态的变化，当满足特定条件时（如“累计斩杀 100 敌将”），解锁成就并推送到前端。

📦 Store / State Layer（状态管理层）

路径：src/lib/game/store.ts

基于 Zustand + Immer 的全局单例 Store。它承担以下职责：

• 持有前端所有游戏状态
• 提供 dispatchAction 方法分发用户操作
• 提供 fetchLatest 方法从后端同步最新数据
• 作为 UI 层与后端之间的桥梁

🔔 Real‑time Notification（实时通知）

路径：src/app/api/game/events/route.ts + use-game-notifications Hook

使用 Server-Sent Events (SSE) 技术，将后端产生的回合结果、成就解锁等事件实时推送给前端，无需用户刷新页面。

⏰ Cron / Scheduler（定时调度器）

由网关的 Cron 作业执行，处理：

• 季节更替事件
• 每日/每周任务重置
• 自动存档

---

三、技术栈全景

3.1 技术分层图示

3.2 关键选型说明

类别	技术	选型理由
框架	Next.js 13	App Router 支持服务端组件，API Routes 一站式后端
状态管理	Zustand	轻量级，比 Redux 简单，与 Immer 配合 immutable 更新
数据获取	SWR	内置缓存、重试、自动重新验证
ORM	Prisma	类型安全的数据库操作，自动生成 TS 类型
数据库	SQLite/PostgreSQL	开发期 SQLite 零配置，生产期 PG 高并发
LLM SDK	ZAI	统一接口，支持多模型切换
反向代理	Caddy 2	自动 HTTPS，配置简单，原生支持 rate-limit
容器化	Docker + Compose	开发生产环境一致，一键启动

---

四、业务流程详解

4.1 完整回合循环

4.2 步骤拆解

步骤	触发动作	后端处理	结果
1	用户登录	useAuth 请求 JWT	前端保存 token
2	启动新局	POST /api/game/start → engine.startGame	创建 GameSession、角色、初始世界状态
3	用户决策	底部操作栏点击 → POST /api/game/action	进入回合处理
4	读取状态	获取最新 GameSession、角色、历史事件	构造 LLM 上下文
5	LLM 生成	buildContextMessage → callLLM	返回叙事 + worldChanges
6	应用变更	applyWorldChanges 写库	属性/资源/事件更新
7	更新回合	年份/季节推进 → 写库	回合数 +1
8	成就检测	checkAchievements	必要时解锁并推送
9	实时推送	SSE 发送 turnResult	前端 Store 更新，UI 重绘

4.3 后台定时任务流程

---

五、可扩展性路线图

5.1 已规划的扩展方向

5.2 具体实现方案

🔌 插件化剧情

在 src/app/api/game/<module>/ 下创建独立路由，并在 engine 中注册对应的处理函数。新增剧情模块无需修改核心代码。

🌐 多语言支持

• 使用 Next.js 内置 i18n 支持 zh-CN 和 en
• 所有 UI 文案抽离到 src/locales/*.json
• LLM Prompt 动态注入语言标记，让模型输出对应语言

👥 社区功能

新增 Friendship、Guild、Leaderboard 数据表：

• 好友：双向确认、在线状态
• 联盟：共同任务、资源池
• 排行榜：按声望/战力/成就点数排序

🤖 AI 助手

提供可选的高级 AI 服务：

• 战略建议：分析当前局势推荐行动
• 占星解读：解读预言背后的深层含义
• 独立微服务，不影响主游戏性能

---