Genarrative/docs/planning/EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md

Express 后端化工程重构规划（2026-04-08）

1. 背景

当前项目已经引入 Express 后端，且 server-node/ 已经承接了运行时鉴权、存档、设置、自定义世界、剧情生成、角色聊天、NPC 对话、运行时物品意图、任务生成等能力。

但从当前工程状态看，项目仍处于“后端已存在，但运行时领域层尚未完全脱前端”的过渡态，主要表现为：

• 前端 src/hooks/useStoryGeneration.ts 仍然承担了大量运行时编排、规则拼接与状态推进职责。
• 前端 src/services/ai.ts 仍然保留了完整的 AI 调用、提示词拼装和本地兜底实现。
• 前端 src/hooks/useGamePersistence.ts 仍在承担较重的存档恢复、schema 纠偏与归一化职责。
• server-node/src/** 当前仍在直接引用 src/types、src/data、src/services 中的内容，分层尚未真正闭合。
• 编辑器相关写接口仍然散落在前端组件与 jsonClient 中，运行时 API 与编辑器 API 还没有完全归口。

现在既然已经明确“前端只负责做表现，所有逻辑、数据都放到后端进行运算和存储”，就需要把这个原则升级成整个工程的硬边界，而不是只停留在一部分接口迁移完成的状态。

---

2. 重构总原则

本轮重构只坚持一个核心原则：

前端不是业务执行层，而是表现层；后端才是唯一的运行时真相来源。

进一步展开为：

• 前端只负责页面结构、动画演出、输入采集、局部交互态、加载态和错误态展示。
• 后端负责鉴权、会话、规则计算、剧情推进、AI 编排、任务推进、道具结算、Build 结算、存档读写与持久化。
• 浏览器内不再保留“正式运行时业务规则”的第二套实现。
• 浏览器内允许存在少量纯表现计算，但不允许成为游戏状态真相来源。
• 编辑器能力与正式运行时能力分离，避免 dev 工具链继续污染正式运行时边界。

---

3. 重构目标

3.1 目标状态

• 浏览器只发送“玩家意图”和必要的展示参数，不直接提交完整运行时真相。
• Express 后端成为唯一的运行时状态源、规则执行源和 AI 调度源。
• 运行时快照、任务状态、NPC 状态、背包、属性、Build、剧情历史全部以后端持久化结果为准。
• 前端不再直接 import 正式运行时 AI 逻辑、提示词逻辑和关键规则逻辑。
• server-node 不再依赖 src/** 中的前端实现细节，而是依赖独立共享层。
• 编辑器 API、运行时 API、资产生成 API 形成清晰命名空间和权限边界。

3.2 非目标

• 本轮不追求一次性重写所有玩法系统。
• 本轮不再讨论关系型数据库选型切换，当前后端以 PostgreSQL 为准。
• 本轮不改动已有中文剧情、设定和文案方向。
• 本轮不为了“前后端分离”牺牲移动端体验与当前主流程可玩性。

---

4. 职责边界

领域	前端职责	后端职责
页面与流程壳层	页面切换、面板开关、布局、自适应、动效、加载态	不负责页面 UI
用户输入	收集点击、拖拽、表单输入、选项选择	校验输入是否合法，解释输入对应的运行时动作
游戏状态	仅持有当前展示所需 view model 和局部 UI state	持有完整游戏状态、快照、事件日志、版本号
剧情推进	展示文本流、选项、动画时间线	生成剧情、决定选项集合、推进故事状态
战斗与数值	播放攻击、受击、死亡、位移	计算伤害、蓝耗、CD、死亡、掉落、逃跑结果
NPC/同伴交互	展示面板、聊天输入框、关系反馈演出	计算关系变化、招募条件、交易合法性、对话结果
背包/装备/Build	展示背包、装备栏、Build 面板	计算背包变化、装备结果、Build 收益与约束
任务系统	展示任务卡片、任务进度、奖励动画	生成任务、推进 signal、发放奖励
AI 调用	不直接请求正式运行时模型	统一做 prompt 组装、模型调用、超时重试、日志
持久化	最多保留极少量表现态缓存	负责存档、设置、用户数据、迁移、恢复
编辑器	调用 SDK、展示工具面板	负责写盘、生成任务、队列、权限与审计

4.1 前端允许保留的状态

• 当前面板是否打开
• 当前动画是否播放中
• 当前流式文本已经显示到哪一段
• 表单草稿、搜索词、临时筛选条件
• 与展示相关的 viewport / media / motion 状态

4.2 前端禁止继续承载的职责

• function 合法性判定
• 怪物/NPC/任务/物品结算
• 正式运行时 prompt 组装
• 正式运行时 AI fallback
• 存档 schema 迁移主逻辑
• 以 localStorage 作为正式运行时主存储
• 编辑器组件直接散落 fetch('/api/...') 访问写接口

---

5. 当前工程问题归纳

5.1 运行时领域逻辑仍然偏前端中心

• useStoryGeneration 仍然是大体量编排热区，承接了剧情、NPC、战斗后续、任务和部分故事引擎逻辑。
• src/services/ai.ts 体量很大，说明正式运行时 AI 编排尚未完全移出浏览器。
• 当前“后端接口 + 前端兜底”的过渡模式，容易让正式逻辑继续双份存在。

5.2 服务端分层还没真正闭合

• server-node 当前仍直接引用 src/types、src/data、src/services。
• 这意味着后端虽然有了入口，但核心领域模型仍然绑在前端目录结构上。
• 继续沿着这条路开发，会让后端无法独立测试、独立构建和独立演进。

5.3 运行时持久化边界还不够干净

• 虽然正式存档已经走远端接口，但前端仍承担较重的恢复、归一化、迁移纠偏逻辑。
• 这会导致“存档解释权”同时存在于前后端两边，后续迭代容易失配。

5.4 编辑器与运行时 API 仍然混杂

• 编辑器读写接口目前仍然有散落访问点。
• 资产生成、JSON 写盘、运行时 API 还没有形成清晰的接口分域。
• 继续混用会让权限控制、生产部署和后续多人协作变得困难。

5.5 当前协议更像“接口迁移”，还不是“后端驱动运行时”

• 目前很多接口是把已有前端逻辑搬成了远端调用入口。
• 但真正理想状态应该是：玩家点击后，后端完成规则结算、状态推进、AI 调用和持久化，再把展示模型返回给前端。

---

6. 目标架构

Browser
├─ 页面 / 动画 / 交互 / ViewModel 渲染
├─ 轻量前端 SDK（只负责请求与状态绑定）
└─ 局部 UI State

packages/shared
├─ contracts
├─ schemas
├─ domain-types
└─ api-client-types

server-node
├─ src/modules/auth
├─ src/modules/runtime-session
├─ src/modules/story
├─ src/modules/combat
├─ src/modules/npc
├─ src/modules/inventory
├─ src/modules/build
├─ src/modules/quest
├─ src/modules/custom-world
├─ src/modules/editor
├─ src/shared/http
├─ src/shared/infra
└─ src/shared/llm

storage
├─ postgres
├─ uploads
└─ generated

6.1 共享层原则

• packages/shared 只放类型、schema、协议、纯函数和序列化约定。
• 共享层不放浏览器专属实现，也不放 Node 专属 IO。
• 所有可执行运行时规则默认放后端，不放共享层。

6.2 前端目录目标

前端建议逐步收敛成下面的职责结构：

src/
├─ app
├─ pages
├─ widgets
├─ features
├─ entities
├─ shared/api
├─ shared/ui
└─ shared/lib

其中：

• shared/api 只保留面向后端 contract 的 SDK。
• features 只组织交互流程和 UI 组合，不再承载正式运行时规则。
• 超大 hook 逐步拆成“页面状态协调层 + 远端 action 调用层 + 表现层状态”。

---

7. 关键协议重构方向

当前最值得尽快统一的，不是继续加接口数量，而是把协议升级成“意图驱动”。

推荐核心动作协议：

{
  "sessionId": "runtime-session-id",
  "clientVersion": 12,
  "action": {
    "type": "story_choice",
    "functionId": "fight_attack",
    "targetId": "npc_merchant_01",
    "payload": {
      "optionId": "opt_02"
    }
  }
}

后端统一返回：

{
  "sessionId": "runtime-session-id",
  "serverVersion": 13,
  "viewModel": {},
  "presentation": {
    "storyText": "",
    "options": [],
    "battlePlayback": null,
    "toast": null
  },
  "patches": [],
  "meta": {
    "requestId": "req_xxx"
  }
}

协议约束：

• 前端不再提交完整 gameState 作为后端运算依据。
• 前端提交的是“玩家意图”，不是“玩家已经算好的结果”。
• 后端返回的是“下一帧该怎么演”的展示模型，而不是只回一个零散字段。

---

8. 分阶段重构路线

P0：先冻结边界，建立共享协议层

本阶段目标

把“前端只做表现，后端负责运行时真相”从口头原则变成工程边界。

主要任务

• 提取 shared contracts，把 server-node 对 src/** 的依赖逐步迁出。
• 固化统一的 API 响应结构、错误结构、requestId、版本字段。
• 明确运行时 API 命名空间与编辑器 API 命名空间。
• 新功能一律禁止再把正式运行时规则写回前端。
• 为关键运行时入口补健康检查、日志字段、耗时统计。

交付物

• 共享类型与 schema 目录
• 统一 API 约定文档
• 服务端模块边界草图
• 前端 SDK 基础层

验收标准

• server-node 可以不依赖 src/** 中的前端运行时实现继续编译。
• 新增运行时需求不再允许“前端先写一版、后端再补一版”。

P1：把运行时状态与持久化解释权收回后端

本阶段目标

让后端成为运行时状态、快照、恢复和迁移的唯一解释者。

主要任务

• 建立 runtime session / snapshot aggregate。
• 将存档恢复、版本迁移、默认值补齐、schema 纠偏迁到后端。
• 把前端 useGamePersistence 收敛为“拉取快照 + 触发保存 + 接收 view model”。
• 设置、快照、自定义世界库统一归入运行时仓储接口。
• 明确哪些内容允许本地缓存，哪些必须以后端结果为准。

交付物

• 统一的运行时 session API
• 快照版本迁移服务
• 服务端持久化 schema 文档

验收标准

• 前端不再承担正式存档恢复迁移的主逻辑。
• 同一份存档的解释权只存在于后端。

P2：把核心规则结算从前端迁到后端

本阶段目标

把“剧情推进、战斗、NPC、任务、物品、Build”这些真正影响状态的领域结算全部后端化。

主要任务

• 把 function 合法性过滤迁入后端。
• 把战斗结算、蓝耗、伤害、死亡、掉落、逃跑结果迁入后端。
• 把 NPC 交互决策、招募条件、关系变化、交易合法性迁入后端。
• 把任务推进 signal、奖励结算、运行时物品结果、Build 结果迁入后端。
• 前端收到的只是一份下一步展示所需的聚合 view model 与演出计划。

交付物

• 运行时 action resolver
• 统一领域服务接口
• 面向 UI 的 view model assembler

验收标准

• 前端点击一个选项时，发送的是 action，不是本地先算完再上传结果。
• 正式运行时的数值、资源、状态迁移不再依赖浏览器逻辑。

P3：把 AI 编排彻底收口到后端

本阶段目标

让浏览器彻底退出正式运行时 AI 调用与 prompt 组装。

主要任务

• 把剧情生成、角色聊天、NPC 对话、自定义世界生成、任务生成、物品意图生成等统一后端执行。
• 清理前端正式运行时代码中的 AI fallback。
• 将 prompt 构造、模型容错、超时、重试、日志、SSE 转发统一收口到后端。
• 对需要复用的 prompt 纯函数进行共享层抽取，但执行权只留在后端。

交付物

• 后端 AI orchestration 模块
• 统一 SSE/streaming 适配层
• 精简后的前端 AI SDK

验收标准

• 浏览器正式运行时代码不再直接 import 大体量 AI 编排模块。
• 无后端时，正式运行时不再默默回退到另一套浏览器逻辑。

P4：把编辑器与资产流程独立成正式后端模块

本阶段目标

让编辑器能力不再作为运行时副产物存在，而是成为有边界的工具后端模块。

主要任务

• 建立 /api/editor/*、/api/assets/* 等明确命名空间。
• 给编辑器写接口补权限、环境门禁、审计日志。
• 统一编辑器 JSON 读写、资产生成、任务查询接口。
• 前端编辑器组件全部改走统一 SDK，不再散落直连接口。

交付物

• editor API contract
• 统一 editor client SDK
• 生成任务与写盘适配器

验收标准

• 编辑器写接口不再散落在多个组件内部。
• 运行时 API 与编辑器 API 的职责边界清晰。

P5：补齐质量门禁、部署路径和观测能力

本阶段目标

让这次后端化重构可以稳定上线，而不是只在本地联调成立。

主要任务

• 为后端补单测、接口测试和关键链路 smoke。
• 为前端补 contract 测试，确保 UI 不依赖本地规则。
• 建立 Nginx/Caddy -> dist + /api 的同域部署路径。
• 为流式接口补代理配置、超时、取消和日志。
• 为数据库迁移、备份、回滚预留脚本。

验收标准

• web + server 可以独立构建、独立测试、联合部署。
• 关键主流程至少具备一条可自动验证的 smoke path。

---

9. 具体迁移清单

9.1 优先迁移对象

• src/hooks/useStoryGeneration.ts
• src/hooks/useGamePersistence.ts
• src/services/ai.ts
• src/services/aiService.ts
• src/services/storageService.ts
• src/services/authService.ts
• 编辑器持久化模块与 src/editor/shared/jsonClient.ts

9.2 优先抽离到共享层的内容

• 领域类型定义
• zod schema 或等价校验协议
• API 请求与响应 contract
• 纯序列化函数
• 前后端都要认识的 enum / id / status 常量

9.3 不建议抽到共享层的内容

• 依赖数据库、文件系统、LLM、日志的服务
• 正式运行时规则执行器
• 存档迁移执行器
• 资产生成任务调度器

---

10. 实施顺序建议

推荐顺序如下：

1. 先抽共享类型与协议，切断 server-node -> src/** 的反向依赖。
2. 再把运行时 session、快照解释权、存档迁移收回后端。
3. 再迁核心规则结算，让前端从“业务执行层”退回“表现协调层”。
4. 然后彻底收口 AI 编排，移除正式运行时浏览器 fallback。
5. 最后归整编辑器 API、部署路径、测试门禁和观测能力。

不建议的顺序：

1. 先零散把几个接口改成后端。
2. 继续保留前端完整 fallback。
3. 最后再补共享层和协议。

这个顺序会把“双份逻辑并存”的过渡期拖得很长，后面会越来越难收口。

---

11. 风险与控制点

• 最大风险不是“迁不动”，而是长期维持双份规则。
• 后端化期间必须避免再往前端加新的正式运行时规则。
• 协议演进要带版本号，否则快照和 UI 很容易错位。
• 前端瘦身不能牺牲移动端一屏体验，表现层拆分仍要遵守移动端优先。
• 编辑器 API 必须和正式运行时隔离，不要为了方便继续走混用路径。

---

12. 一句话结论

这次重构的核心不是“把几个请求改成走 Express”，而是：

把项目从“前端主导运行时、后端承接部分接口”的过渡架构，升级成“Express 后端统一持有运行时真相，前端只负责表现和交互”的正式工程架构。