feat: 实现游戏核心功能与前端界面

- 添加游戏核心系统：战斗、任务、日志、随机数生成等 - 实现前端主界面、HUD、底部导航和各类卡片组件 - 添加用户认证系统与游戏存档持久化 - 配置项目基础架构与开发环境 - 补充文档说明与Docker部署支持
2026-04-28 22:16:58 +08:00
parent 2e1b58bada
commit e783e6e533
124 changed files with 9759 additions and 1 deletions
@@ -0,0 +1,169 @@
+# 12 前端 HUD 架构与资产管线
+
+本文档记录当前 TinyWaste Online Web 客户端的 HUD 架构落地方式，目标是让后续继续扩内容、补系统、换美术时，仍然能保持模块边界清晰、资产可追溯、状态流可解释。
+
+## 12.1 技术栈结论
+
+当前重制版继续沿用并确认以下技术栈，不做二次摇摆：
+
+- 前端：React 19 + Vite + TypeScript
+- 客户端数据层：TanStack Query
+- 后端：Fastify + TypeScript
+- 存档与账号：Session Cookie + Drizzle ORM + SQLite
+- 共享规则层：`packages/game-core`
+- 共享内容层：`packages/content`
+
+选择原因：
+
+- React + Vite 适合构建高密度单屏 HUD，开发迭代成本低。
+- React Query 负责会话、存档和行动回写，能把“在线游戏状态”与“界面状态”明确分层。
+- `game-core` 与 `content` 把规则和内容从 UI 中剥离，符合文档 08 的分层目标。
+- Fastify + Drizzle 让账号与云存档可以继续扩展为多槽、迁移、审计和反作弊校验。
+
+## 12.2 当前前端分层
+
+按照文档 08 的 Presentation / Application / Domain / Data 思路，前端当前对应如下：
+
+- Presentation：`apps/web/src/features/game/components/*`、`apps/web/src/features/auth/components/*`
+- Application：`apps/web/src/features/session/useGameSession.ts`
+- Data：`apps/web/src/api.ts`
+- Domain：`packages/game-core`、`packages/content`
+
+职责约束：
+
+- `App.tsx` 只负责入口编排，不再直接堆叠完整 HUD 细节。
+- `useGameSession.ts` 只负责编排查询、认证、建档、行动提交与错误状态。
+- HUD 组件只消费 `GameView` 和回调，不直接触碰接口实现。
+- 游戏规则与内容定义禁止回流到 `apps/web` 内硬编码。
+
+## 12.3 组件结构
+
+当前 HUD 结构：
+
+```text
+App
+├─ AuthScreen / NewGameScreen / LoadingScreen
+└─ GameHud
+   ├─ TopHud
+   ├─ RoutePanel
+   ├─ CommandCenter
+   ├─ LoadoutPanel
+   ├─ BottomDock
+   └─ ModalShell (事件 / 战斗 / 胜负)
+```
+
+卡片级组件：
+
+- `AssetThumb`
+- `StatMeter`
+- `InventoryCard`
+- `RecipeCard`
+- `QuestCard`
+- `EmptyState`
+- `PanelHeader`
+
+这样拆分后的收益：
+
+- 左、中、右、底四个 HUD 区块可以独立重做，而不需要重新读一遍整个页面。
+- 小卡片组件可被更多系统复用，例如未来的交易、仓库、NPC 商店、任务详情。
+- `GameHud` 能承载局部交互状态，比如 `commandTab`、`sideTab`，而不会污染全局会话逻辑。
+
+## 12.4 状态流
+
+当前在线游戏状态流：
+
+```text
+浏览器 -> /api/auth/me -> 用户会话
+浏览器 -> /api/game/state -> 当前云端存档
+用户动作 -> /api/game/action -> 服务端结算 -> 返回新 GameView
+UI 组件 <- Query Cache <- 最新 GameView
+```
+
+具体规则：
+
+- 认证通过后才启用 `game-state` 查询。
+- 创建新游戏、旅行、制作、战斗、交易、休息都走服务端 authoritative action。
+- Query Cache 只保存最新服务端视图，不在前端自行推演核心规则。
+- HUD 内部 tab 只属于本地展示状态，不影响云端存档。
+
+## 12.5 视觉资产组织
+
+所有当前接入的 GPT-image-2 资产位于：
+
+- `apps/web/public/generated/`：地点背景
+- `apps/web/public/generated/ui/character-preview.png`：角色立绘
+- `apps/web/public/generated/ui/item-atlas.png`：物资图集原图
+- `apps/web/public/generated/ui/equipment-atlas.png`：装备图集原图
+- `apps/web/public/generated/ui/items/*`：切分后的物资图标
+- `apps/web/public/generated/ui/equipment/*`：切分后的装备槽素材
+
+对应映射入口：
+
+- `apps/web/src/features/game/uiAssets.ts`
+
+当前资产策略：
+
+- 地点图使用整图背景，服务于中央场景和左侧路线卡。
+- 物资与装备图使用 atlas + 裁切结果，服务于快捷栏、库存卡、角色槽位。
+- 所有引用都走 `uiAssets.ts`，避免组件里散落硬编码路径。
+
+## 12.6 HUD 信息职责
+
+### 12.6.1 TopHud
+
+- 时间
+- 生存状态条
+- 风险标签
+- 账号状态
+
+### 12.6.2 RoutePanel
+
+- 当前地点摘要
+- 路线列表
+- 风险强度
+- 节点式世界图
+
+### 12.6.3 CommandCenter
+
+- 场景主视觉
+- 行动矩阵
+- 交易终端
+- 实时日志
+- 当前目标
+- 蓝图视图
+
+### 12.6.4 LoadoutPanel
+
+- 角色 / 背包 / 任务三态切换
+- 角色立绘与槽位矩阵
+- 属性与状态效果
+- 快捷栏
+- 完整库存管理
+- 任务与休整
+
+### 12.6.5 BottomDock
+
+- 游戏化底部导航
+- 当前角色标识
+- 核心补给统计
+
+## 12.7 当前与参考图的对齐策略
+
+对齐的不是“像一张网站海报”，而是“像一套可操作的游戏终端”：
+
+- 维持单屏阅读，整页不滚动，滚动只发生在内部面板。
+- 中央区优先展示场景与决策，避免全文字堆叠。
+- 右侧区优先视觉化角色与装备，而不是继续做普通列表。
+- 底部区承担模式切换和系统导航，强化“游戏 HUD”心智。
+
+## 12.8 下一步扩展建议
+
+下一轮优先项：
+
+1. 继续补 GPT-image-2 资产：
+   - 头部、侧武器、弹药、医疗、食物第二批图集
+   - 天气、辐射、事件状态专用小图标
+2. 将 `LoadoutPanel` 的 tab 与底部导航进一步联动为统一模式系统。
+3. 为 `CommandCenter` 增加战斗专属视图和事件专属视图，而不是完全依赖弹层。
+4. 为物资卡补充更精细的分类过滤和排序逻辑。
+5. 引入可配置的 HUD 主题参数，支撑不同章节或区域切换皮肤。