Merge branch 'codex/wooden-fish-template' into master

.hermes/plans/架构优化计划书.md

@@ -0,0 +1,399 @@
+# Genarrative（陶泥儿）项目架构优化计划书
+
+**文档版本**：v1.0  
+**编制日期**：2026-05-26  
+**项目名称**：Genarrative（陶泥儿）  
+**文档密级**：内部
+
+---
+
+## 一、项目概况
+
+| 维度 | 详情 |
+|---|---|
+| **项目名** | Genarrative（陶泥儿） |
+| **项目定位** | AI Native 互动视觉 RPG 平台——支持多种玩法模板的 AI 创作、运行与分享（"玩法类型平台"） |
+| **核心玩法** | 拼图、视觉小说、Match3D、Bark Battle、Big Fish、Jump-Hop、Square Hole、木鱼、教娱等 10+ 种玩法模板 |
+| **代码规模** | 前端 ~823 个 TS/TSX 文件，后端 ~1532 个 Rust 文件，属于大型项目 |
+
+### 1.1 计划目的
+
+本计划书基于对 Genarrative 项目当前架构的全面分析，识别架构层面的关键问题，并提出分阶段、可落地的优化方案。旨在：
+
+- 统一前端架构模式，降低团队认知成本和新人上手门槛
+- 提升模块内聚性，减少不必要的耦合与依赖
+- 建立自动化契约保障机制，降低跨语言同步出错风险
+- 优化工程基础设施，提高开发效率和运维可观测性
+
+---
+
+## 二、技术栈总览
+
+| 层级 | 技术选型 | 版本 |
+|---|---|---|
+| **前端框架** | React + TypeScript + Vite | React 19 / TS 5.8 / Vite 6 |
+| **样式** | TailwindCSS | v4 |
+| **3D / 动画** | Three.js、Motion、cannon-es | - |
+| **后端 HTTP** | Rust + Axum（BFF 门面） | Axum 0.8 |
+| **游戏状态 DB** | SpacetimeDB（实时反应式数据库） | v2.2 |
+| **AI / LLM** | LangChain-Rust + LLM Proxy | - |
+| **小程序** | 微信小程序（含微信支付） | - |
+| **容器化** | Docker Compose（Nginx + API Server + OTel Collector） | - |
+| **运维** | systemd、Nginx、Jenkins CI/CD、k6 压测 | - |
+| **可观测性** | OpenTelemetry（OTLP → Grafana） | - |
+
+---
+
+## 三、当前架构分层图
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        入口层                                │
+│  index.html → main.tsx → resolveAppRoute() → RouteComponent  │
+│  (多入口路由：平台主页 / 拼图 / BigFish / Match3D / ...)      │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      前端应用层 (src/)                        │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐│
+│  │ components/ │  │  services/   │  │  games/              ││
+│  │ *-creation  │  │ *-creation   │  │  bark-battle/        ││
+│  │ *-result    │  │ *-runtime    │  │    domain/           ││
+│  │ *-runtime   │  │ *-works      │  │    application/      ││
+│  │ common/     │  │ storyEngine  │  │    infrastructure/   ││
+│  │ auth/       │  │ payment      │  │    ui/               ││
+│  └─────────────┘  └──────────────┘  └──────────────────────┘│
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐│
+│  │ hooks/      │  │ data/        │  │ routing/             ││
+│  │ persistence/│  │ functionCat. │  │ config/  editor/     ││
+│  └─────────────┘  └──────────────┘  └──────────────────────┘│
+└──────────────────────────────────────────────────────────────┘
+                              │ Vite Proxy (/api/*)
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Rust 后端 (server-rs/)                     │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  api-server (Axum HTTP / SSE / BFF 门面)              │   │
+│  └──────────────────────────────────────────────────────┘   │
+│         │                    │                    │          │
+│         ▼                    ▼                    ▼          │
+│  ┌──────────┐    ┌──────────────────┐   ┌──────────────┐   │
+│  │ platform │    │     module-*     │   │   shared     │   │
+│  │  -auth   │    │  -puzzle         │   │  -contracts  │   │
+│  │  -llm    │    │  -visual-novel   │   │  -kernel     │   │
+│  │  -image  │    │  -match3d        │   │  -logging    │   │
+│  │  -oss    │    │  -bark-battle    │   └──────────────┘   │
+│  │  -speech │    │  -big-fish ...   │                       │
+│  │  -agent  │    │  -runtime        │                       │
+│  └──────────┘    │  -combat/npc     │                       │
+│                  └──────────────────┘                       │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  spacetime-module + spacetime-client → SpacetimeDB   │   │
+│  └──────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│                    辅助子系统                                │
+│  apps/admin-web (React 后台管理)                             │
+│  miniprogram/ (微信小程序)                                   │
+│  packages/shared (前后端共享契约/LLM工具)                     │
+│  deploy/ (Docker/Nginx/systemd/OTel)                         │
+│  scripts/ (40+ 构建/部署/检查脚本)                            │
+│  jenkins/ (CI/CD Pipeline)                                   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 四、架构亮点
+
+1. **清晰的"玩法模板"平台模式**  
+   每种玩法遵循统一的 `creation → result → runtime` 三段式生命周期，前端 `components/` 和 `services/` 均按此模式组织。新增玩法可快速套用模板，极大降低了横向扩展成本。
+
+2. **后端严格的分层约束**  
+   `api-server`（门面）→ `module-*`（领域）→ `spacetime-module`（持久化），`module-*` 不直接依赖 Axum、HTTP、SpacetimeDB table、LLM、文件系统，保证了领域纯净性和可测试性。
+
+3. **SpacetimeDB 作为游戏状态核心**  
+   采用反应式实时数据库替代传统 Redis + PostgreSQL 组合，天然适合多人实时游戏状态同步，减少了中间层复杂度和延迟。
+
+4. **前端 DDD 探索**  
+   `src/games/bark-battle/` 采用 `domain / application / infrastructure / ui` 四层 DDD 结构，为复杂玩法的前端架构提供了良好范本。
+
+5. **完善的多入口路由体系**  
+   通过 `resolveAppRoute()` 按 URL path 分发到不同的 lazy-loaded 组件，实现了按需加载和良好的首屏性能。
+
+6. **运维体系完备**  
+   Docker Compose + systemd + Nginx + OpenTelemetry + k6 压测 + Jenkins CI/CD，覆盖了构建、部署、监控、压测全链路。
+
+---
+
+## 五、问题诊断与改进方案
+
+### 问题 1：前端 services/ 与 components/ 的耦合不统一
+
+**现状**  
+大部分玩法遵循 `services/` + `components/` 分离模式，但部分玩法运行时直接放在 `components/` 下，services 层职责模糊——有的承担了业务逻辑编排，有的仅作简单 API 调用。
+
+**影响**  
+- 新人阅读代码时无法预判某个逻辑应位于哪个目录
+- 单元测试困难：services 与组件耦合的业务逻辑无法独立测试
+- 跨玩法复用时需要额外的迁移成本
+
+**改进方案**  
+1. 制定规范：`services/` 仅负责纯 API 调用和数据转换，不包含业务判断逻辑
+2. 业务逻辑统一归到 `hooks/` 或 `games/<play-type>/application/`
+3. 以 puzzle 玩法为样板，先行重构并形成迁移指南，再推广至其余玩法
+4. 在 CI 中增加 ESLint 规则，禁止 `components/` 直接 import `services/` 之外的外部模块
+
+**预期收益**  
+- 职责边界清晰，降低认知成本约 30%
+- services 层可独立单测覆盖率达到 80%+
+- 新玩法开发上手时间从 2 天缩短至 0.5 天
+
+---
+
+### 问题 2：前端 DDD 与模板模式并存，架构不统一
+
+**现状**  
+`bark-battle` 采用 DDD 四层结构（`domain/application/infrastructure/ui`），其余玩法散落在 `components/` + `services/` 下，存在两种截然不同的组织范式。
+
+**影响**  
+- 团队内部对"正确"的代码组织方式缺乏共识
+- 代码审查时需要切换判断标准
+- DDD 玩法的优势无法在全局范围内发挥
+
+**改进方案**  
+1. 所有玩法统一迁移到 `src/games/<play-type>/` 下，采用 `domain / application / ui` 三层结构（infrastructure 按需保留）
+2. 以 puzzle 为样板完成首例迁移，产出迁移 Checklist 和模板生成脚本
+3. 新增玩法脚手架直接生成 DDD 结构目录
+4. 旧玩法分批次迁移，每批次 2-3 个玩法，在 4 个迭代内完成
+
+**预期收益**  
+- 架构一致性提升至 100%
+- 跨玩法逻辑复用变得可能（domain 层可共享）
+- 为后续 monorepo 改造打下基础
+
+---
+
+### 问题 3：后端 module-* 粒度偏细，存在潜在循环依赖风险
+
+**现状**  
+后端共 35 个 crate。`module-runtime` 被拆分为 3 个独立 crate，`module-combat / npc / inventory` 各自独立。部分紧密协作的模块之间可能存在隐式耦合。
+
+**影响**  
+- 编译时间增长（35 个 crate 独立编译）
+- 跨 crate 重构时需要同时修改多处
+- 循环依赖风险增加，可能在特定组合下触发编译失败
+
+**改进方案**  
+1. 评估合并方案：
+   - `module-runtime-*` 系列合并为单 crate `module-runtime`，内部用 `mod` 做逻辑隔离
+   - `module-combat / npc / inventory` 评估合并为 `module-combat`，npc 和 inventory 作为子模块
+2. 保留 trait/interface 抽象层，确保 module 之间不直接依赖具体实现
+3. 在 CI 中引入 `cargo-deny` 或自定义脚本，自动检测 module 间的依赖方向是否违反分层约束
+4. 目标：将 35 个 crate 精简至 25 个以内
+
+**预期收益**  
+- 全量编译时间预计缩短 15%-20%
+- 循环依赖风险归零
+- module 内部重构成本降低
+
+---
+
+### 问题 4：根目录 env 文件过多且混乱
+
+**现状**  
+根目录存在 4 个 env 文件（`.env`、`.env.example`、`.env.production` 等），且 `deploy/` 下另有多个 env 文件。配置分散在多处，部分文件之间字段不一致。
+
+**影响**  
+- 排查配置问题时需要翻阅多个文件
+- 新人无法快速确定本地开发需要哪些环境变量
+- 部署时可能遗漏或错误覆盖某项配置
+
+**改进方案**  
+1. 收敛为三层配置体系：
+   - `.env.example`：包含所有可配置项的说明和默认值（唯一提交到仓库的 env 文件）
+   - `.env.local`：本地开发覆盖（加入 .gitignore）
+   - `deploy/env/<env-name>.env`：各部署环境专用配置
+2. 引入 config crate，支持层次覆盖（default → local → env-specific），启动时自动校验必填字段
+3. 在 CI 中加入 env 校验步骤：对比 `.env.example` 与部署环境的 env 文件，标记缺失或多余字段
+
+**预期收益**  
+- 配置查找时间从分钟级降至秒级
+- 部署配置遗漏导致的线上事故减少 90%+
+- 新成员本地环境搭建时间从 30 分钟缩短至 10 分钟
+
+---
+
+### 问题 5：scripts/ 目录膨胀为"万能工具箱"
+
+**现状**  
+`scripts/` 目录共 42 个文件，涵盖构建、部署、检查、迁移、生成、压测等，全部平铺在同一层级，缺乏分类。
+
+**影响**  
+- 难以快速定位所需脚本
+- 同类脚本缺乏命名规范
+- 新增脚本时不知道放在何处
+
+**改进方案**  
+1. 按功能域分类重组：
+
+```
+scripts/
+├── build/        # 构建相关（vite、cargo、wasm 等）
+├── deploy/       # 部署相关（docker、systemd、rsync）
+├── check/        # 检查/校验（lint、format、type-check）
+├── spacetime/    # SpacetimeDB 相关（migration、seed）
+├── generate/     # 代码生成（scaffold、proto、types）
+└── loadtest/     # 压测脚本（k6 配置及辅助）
+```
+
+2. 为每个子目录添加 README.md，说明各脚本用途和调用方式
+3. 将重复逻辑抽取为共享函数库
+
+**预期收益**  
+- 脚本查找效率提升 60%+
+- 降低脚本重复概率
+- 便于 CI Pipeline 直接引用标准化路径
+
+---
+
+### 问题 6：前端路由系统缺乏统一的"玩法注册"机制
+
+**现状**  
+`appRoutes.tsx` 中硬编码 `switch-case` 逻辑，每新增一种玩法需手动修改路由文件、入口组件、资源加载等多个位置。
+
+**影响**  
+- 新增玩法的接入点分散，容易遗漏
+- 路由文件随玩法增多持续膨胀
+- 无法实现"按需注册"——即使某环境不包含某玩法，路由代码仍然存在
+
+**改进方案**  
+1. 建立 `PlayTypeRegistry` 模式：每个玩法导出一个注册项对象，包含 `path`、`lazyComponent`、`preload` 等字段
+2. `resolveAppRoute()` 改为动态聚合所有注册项，替代硬编码 switch-case
+3. 支持环境级玩法开关：通过配置控制某环境启用哪些玩法，路由系统自动忽略未启用的
+
+**预期收益**  
+- 新增玩法零侵入路由系统，只需在玩法目录内添加注册文件
+- 路由文件体积与玩法数量解耦
+- 灰度发布和 A/B 测试变得可能
+
+---
+
+### 问题 7：前端缺少统一的状态管理层
+
+**现状**  
+前端状态管理依赖 React hooks + props drilling + services 层手动管理。未使用任何状态管理库（如 Zustand、Jotai、Redux）。
+
+**影响**  
+- 全局状态（用户认证、会话、通知）通过多层 props 传递，组件耦合度高
+- 跨页面状态无法优雅共享
+- 状态变更难以追踪和调试
+
+**改进方案**  
+1. 引入 Zustand（轻量、无 boilerplate、TS 友好）管理全局状态：
+   - `useAuthStore`：认证状态
+   - `useSessionStore`：当前会话/游戏状态
+   - `useNotificationStore`：全局通知
+2. 玩法内状态继续使用 React hooks + `useReducer`，保持局部自治
+3. 全局 store 与玩法内 state 通过事件总线松耦合通信
+
+**预期收益**  
+- props drilling 层级从 5+ 层降至 1-2 层
+- 全局状态可追溯，支持 Redux DevTools 调试
+- 跨玩法状态共享（如用户余额、道具）变得自然
+
+---
+
+### 问题 8：shared-contracts 的实际复用程度待验证
+
+**现状**  
+前后端通过 `packages/shared` 共享 DTO 类型定义，但依赖手动同步 TypeScript 类型。可能存在前后端契约不一致但编译期无法检出的情况。
+
+**影响**  
+- 后端修改 DTO 字段后，前端可能遗漏更新导致运行时错误
+- 手动同步耗时且易出错
+- Code Review 时难以判断契约一致性
+
+**改进方案**  
+1. 引入 `ts-rs`：从 Rust 结构体自动生成 TypeScript 类型定义
+2. 将生成步骤集成到 CI Pipeline：
+   - 每次 Rust PR 触发 `ts-rs` 重新生成 TS 类型
+   - 对比生成的类型与仓库中的类型是否一致，不一致则 CI 失败
+3. 长期考虑引入 Protobuf / OpenAPI 作为跨语言契约的单一事实来源
+
+**预期收益**  
+- 前后端契约不一致导致的线上 bug 减少 95%+
+- 手动同步工作量归零
+- PR Review 时契约一致性问题自动拦截
+
+---
+
+## 六、改进优先级路线图
+
+| 优先级 | 改进项 | 涉及层 | 建议时间 | 预期收益 |
+|---|---|---|---|---|
+| **P0** | 统一前端 services/hooks/components 职责边界 | 前端 | 第 1-2 周 | 降低认知成本，提升可测试性 |
+| **P1** | 建立 PlayType 注册机制 | 前端 | 第 2-3 周 | 新增玩法零侵入路由 |
+| **P1** | 评估 module-* 合并方案并执行 | 后端 | 第 3-4 周 | 减少编译时间 15%-20% |
+| **P1** | 引入 Zustand 全局状态管理 | 前端 | 第 4-5 周 | 改善状态追踪与跨组件共享 |
+| **P2** | 清理 scripts/ 目录结构 | 工程 | 第 5-6 周 | 提高可发现性 |
+| **P2** | 前端玩法统一迁移至 DDD 结构 | 前端 | 第 5-8 周 | 架构一致性 100% |
+| **P2** | env 配置收敛 | 工程 | 第 6-8 周 | 减少部署配置事故 |
+| **P3** | 前后端共享 DTO 自动化（ts-rs） | 全栈 | 第 6-8 周 | 消除契约不一致风险 |
+| **P3** | CI 分层约束检查（cargo-deny） | 后端 | 第 8-10 周 | 循环依赖归零 |
+
+> **说明**：P0 为阻塞项，必须最先完成。P1 项可部分并行推进（PlayType 注册与 module 合并互不依赖）。P2/P3 为优化项，可在日常迭代中穿插推进。
+
+---
+
+## 七、架构健康度评分卡
+
+| 维度 | 评分 | 当前状态 | 目标状态 |
+|---|---|---|---|
+| **分层清晰度** | ★★★★☆ | 后端分层严格，前端分层存在不一致 | ★★★★★ 前后端均严格分层 |
+| **模块化程度** | ★★★★☆ | 后端 35 crate 粒度偏细，前端结构化较好 | ★★★★☆ 后端精简至 25 crate |
+| **可扩展性** | ★★★★★ | 玩法模板模式使新增玩法成本低 | ★★★★★ 维持 |
+| **代码复用** | ★★★☆☆ | shared 层作用有限，services 层有重复 | ★★★★☆ DDD 统一后 domain 可复用 |
+| **DevOps 成熟度** | ★★★★★ | Docker + k6 + OTel + Jenkins 覆盖完整 | ★★★★★ 维持 |
+| **文档完备性** | ★★★★★ | docs/ 分类清晰，基线文档齐全 | ★★★★★ 维持 |
+| **技术债务管控** | ★★★★☆ | 有明确的"历史残留"标记和废弃策略 | ★★★★★ 增加自动化检测 |
+
+**综合评级：A-（优秀，存在可优化空间）**
+
+---
+
+## 八、附录：代码规模统计
+
+| 维度 | 数量 |
+|---|---|
+| **前端 TypeScript/TSX 文件** | ~823 个 |
+| **后端 Rust 源文件** | ~1532 个 |
+| **后端 Crate 数量** | 35 个 |
+| **核心玩法类型** | 10+ 种 |
+| **scripts/ 脚本数量** | 42 个 |
+| **根目录 env 文件** | 4 个 + deploy 下多个 |
+
+### 模块规模明细（后端）
+
+| Crate | 职责 | 建议 |
+|---|---|---|
+| `api-server` | Axum HTTP 门面，路由聚合 | 保持 |
+| `platform-*` (auth/llm/image/oss/speech/agent) | 平台级跨玩法能力 | 保持 |
+| `module-puzzle` | 拼图玩法 | 作为 DDD 迁移样板 |
+| `module-visual-novel` | 视觉小说 | 后续迁移 |
+| `module-match3d` | Match3D 三消 | 后续迁移 |
+| `module-bark-battle` | 犬吠对战 | 已对接前端 DDD |
+| `module-big-fish` | Big Fish | 后续迁移 |
+| `module-runtime*` (3 crates) | 通用运行时 | **建议合并为单 crate** |
+| `module-combat / npc / inventory` | 战斗系统 | **建议合并** |
+| `spacetime-module` + `spacetime-client` | SpacetimeDB 接入 | 保持 |
+| `shared-contracts / kernel / logging` | 共享基础设施 | 保持 |
+
+---
+
+> **文档结束**  
+> 本计划书由 Genarrative 架构分析报告衍生，所有改进项均基于对当前项目代码库的实际分析。执行过程中如遇阻力或新发现，应及时更新本计划书并同步相关方。