36-character-flower/docs/本次代码变更说明.md

本次代码变更说明

本文档总结当前这一次工作中，对仓库代码所做的主要改动，重点说明：

• 新增了哪些文件
• 修改了哪些已有文件
• 每个模块新增了什么能力
• 当前已经验证过什么

说明：

• 下文基于当前 Git 工作区中的变更整理
• 其中一部分文件为“新增文件”，一部分为“在已有文件基础上的修改”
• src/routeTree.gen.ts 属于路由生成产物，不是手写业务文件

1. 本次改动目标

本次工作的核心目标，是把项目从通用脚手架推进到“36 字花”游戏前端的业务骨架阶段，采用的落地方案是：

• 统一业务路由，不按设备拆成不同 URL
• 同一路由下按设备加载移动端 / 桌面端不同视图
• 共用一套游戏状态、数据模型、mock 数据和接口层
• 将页面内写死的中英文文案逐步收敛到 react-i18next 的语言包里

2. 新增模块总览

本次新增的核心模块有 5 个：

1. src/features/game/shared 说明：

• 定义 36 字花游戏的共享常量、类型、mock 数据、派生计算函数
• 作为游戏业务层的基础模型

2. src/store 说明：

• 基于 Zustand 实现游戏的状态容器
• 按模块拆分目录
• 当前分为 src/store/auth 和 src/store/game

3. src/features/game/api 说明：

• 建立游戏相关接口层和 DTO 映射
• 提供 mock bootstrap 获取函数，便于在未接真实后端前先跑 UI

4. src/features/game/components 说明：

• 新增共享展示组件
• 同时新增移动端页面壳和桌面端页面壳

5. src/features/game/entry 说明：

• 增加游戏路由适配页
• 负责把共享状态、共享组件和双端壳层接起来

3. 新增文件清单与说明

3.1 通用组件

src/components/language-link.tsx

新增内容：

• 抽出语言切换按钮组件
• 从 /$lang 布局文件中拆出，避免路由文件内混入过多内部组件

src/components/nav-link.tsx

新增内容：

• 抽出顶部导航按钮组件
• 供语言布局页复用

src/components/stat-card.tsx

新增内容：

• 抽出首页信息卡片组件
• 用于首页业务入口页展示

3.2 设备识别

src/lib/device/use-device-type.ts

新增内容：

• 基于窗口宽度判断当前设备是 mobile 还是 desktop
• 为同一路由下渲染不同视图提供支持

3.3 游戏共享模型

src/features/game/shared/constants.ts

新增内容：

• 36 宫格基础尺寸常量
• 回合阶段枚举
• 格子状态枚举
• 连接状态枚举
• 筹码默认配置等

src/features/game/shared/types.ts

新增内容：

• 游戏核心类型定义
• 包括格子、筹码、下注、历史、公告、连接、dashboard、bootstrap 快照等

src/features/game/shared/mock-data.ts

新增内容：

• 游戏 mock 启动数据
• 包括 36 个格子、筹码、历史记录、当前回合、公告、连接状态、桌面信息

src/features/game/shared/selectors.ts

新增内容：

• 各种纯函数派生逻辑
• 包括格子 view model、倒计时、公告筛选、趋势计算、下注汇总等

src/features/game/shared/untils.ts

新增内容：

• 对 shared 子模块统一导出

3.4 游戏状态层

说明：

• 游戏相关 store 已统一放入 src/store
• 并进一步按模块拆为子目录：
  • src/store/auth
  • src/store/game
• src/features/game/model/untils.ts 现在仅作为过渡导出层，用于维持 features/game 对外接口不变

src/store/game/game-round-store.ts

新增内容：

• 回合相关状态
• 包括格子、筹码、回合阶段、历史、趋势、下注选择
• 提供切换筹码、下注、清空、同步回合等动作

src/store/game/game-session-store.ts

新增内容：

• 会话类状态
• 包括公告、连接状态、dashboard 信息
• 提供已读公告、关闭公告、同步连接、同步 dashboard 等动作

src/store/game/game-ui-store.ts

新增内容：

• UI 控制类状态
• 当前只放了自动托管浮层、dashboard、规则面板开关

src/store/auth/auth-store.ts

说明：

• 认证相关 store
• 原有 auth-store 已归入 auth 子目录

src/store/auth/untils.ts

说明：

• 统一导出认证模块 store

src/store/game/untils.ts

说明：

• 统一导出游戏模块 store

src/store/untils.ts

新增内容：

• 统一导出 src/store 下各模块
• 当前包括 auth 和 game

src/features/game/model/untils.ts

新增内容：

• 作为过渡导出层，继续对 features/game 暴露游戏 store

3.5 游戏接口层

src/features/game/api/types.ts

新增内容：

• 游戏接口 DTO 类型定义

src/features/game/api/game-api.ts

新增内容：

• 游戏 API 包装
• 包括 bootstrap、round feed、announcement 的响应映射
• 提供 getMockGameBootstrap() 用于当前阶段 UI 接线

src/features/game/api/untils.ts

新增内容：

• 对 api 子模块统一导出

3.6 游戏共享 UI 组件

src/features/game/components/shared/game-action-bar.tsx

新增内容：

• 筹码区、主按钮、次按钮、附加 slot 区域

src/features/game/components/shared/game-announcement-modal.tsx

新增内容：

• 强制公告弹层骨架

src/features/game/components/shared/game-auto-spin-overlay.tsx

新增内容：

• 自动托管运行遮罩骨架

src/features/game/components/shared/game-board-cell.tsx

新增内容：

• 单个格子组件
• 支持状态、徽标、倍率、点击等展示

src/features/game/components/shared/game-board.tsx

新增内容：

• 36 宫格容器组件

src/features/game/components/shared/game-history-list.tsx

新增内容：

• 开奖历史列表组件

src/features/game/components/shared/game-panel-card.tsx

新增内容：

• 通用游戏面板容器

src/features/game/components/shared/game-status-card.tsx

新增内容：

• 顶部状态卡片组件

src/features/game/components/shared/game-trend-list.tsx

新增内容：

• 走势列表组件

src/features/game/components/shared/types.ts

新增内容：

• 共享展示组件的 props 类型

src/features/game/components/shared/utils.ts

新增内容：

• 简单的 cn 工具

3.7 双端页面壳

src/features/game/components/mobile/mobile-game-page.tsx

新增内容：

• 移动端游戏页壳层
• 负责纵向编排

src/features/game/components/desktop/desktop-game-page.tsx

新增内容：

• 桌面端游戏页壳层
• 负责多栏编排

src/features/game/components/untils.ts

新增内容：

• 对组件模块统一导出

3.8 游戏入口与总导出

src/features/game/entry/entry-page.tsx

新增内容：

• 游戏路由页适配层
• 负责：
  • 读取 Zustand 状态
  • 拉 mock bootstrap
  • 组装状态卡片、历史、走势、面板内容
  • 根据设备类型切换移动端 / 桌面端壳层
  • 接公告弹窗、自动托管遮罩
  • 使用 i18n 文案

src/features/game/untils.ts

新增内容：

• 对 game 功能模块统一导出

3.9 新游戏路由

src/routes/$lang/game.tsx

新增内容：

• 新增 /$lang/game 路由
• 作为游戏大厅的统一业务入口

4. 修改文件清单与说明

4.1 基础常量与全局信息

src/constants/untils.ts

修改内容：

• 将应用名称从通用模板名改为 36字花
• 更新默认描述文案
• 新增桌面断点常量 DESKTOP_LAYOUT_MIN_WIDTH_PX

index.html

修改内容：

• 更新站点标题
• 更新默认 description / OG / Twitter meta 信息

4.2 样式层

src/styles.css

修改内容：

• 保持 html/body/#root 占满视口
• 增加全局游戏主题变量
• 增加游戏外壳、面板、光效等 utility 样式
• 增加深色游戏背景基础视觉

4.3 路由与页面

src/routes/$lang/route.tsx

修改内容：

• 把原来的简单 Outlet 布局升级成业务壳层
• 增加顶部导航
• 增加语言切换按钮
• 使用共享导航组件

src/routes/$lang/index.tsx

修改内容：

• 把原来的占位首页改成业务入口首页
• 增加进入游戏大厅 CTA
• 展示当前项目架构说明

src/routeTree.gen.ts

修改内容：

• 因新增路由自动重新生成
• 非手写文件

4.4 国际化

src/locales/zh-CN/common.ts

修改内容：

• 更新首页和壳层文案
• 新增整套 game.* 文案
• 包括：
  • 游戏大厅标题、副标题
  • 状态卡片文案
  • 盘面、历史、走势文案
  • 公告弹窗、自动托管文案
  • 页脚说明文案
  • phase 展示文案

src/locales/en-US/common.ts

修改内容：

• 与中文语言包同步补齐英文版本 game.* 文案

5. 本次特别修复

5.1 修复 /$lang/game 的循环更新错误

涉及文件：

• src/features/game/entry/entry-page.tsx

修复内容：

• 之前直接把会返回新引用的派生 selector 传给 Zustand hook，导致 React 触发无限更新
• 现已改成：
  • 只从 store 读取原始 state
  • 在组件内通过 useMemo 派生数据

5.2 清理页面里的硬编码双语判断

涉及文件：

• src/features/game/entry/entry-page.tsx
• src/routes/$lang/route.tsx
• src/locales/zh-CN/common.ts
• src/locales/en-US/common.ts

修复内容：

• 将大量 i18n.language === 'zh-CN' ? ... : ... 改为统一走 t('...')
• 避免将用户可见文案写死在业务代码里

6. 当前完成度

本次完成的是“业务骨架阶段”，不是最终成品。当前已经具备：

• 统一游戏路由
• 双端页面壳
• 共享游戏状态模型
• 共享 mock 数据和接口映射
• 公告、自动托管、历史、走势等模块骨架
• 国际化接线

当前尚未完成的内容包括：

• 真实后端接口联调
• WebSocket 实时同步
• 完整的回合状态机
• 完整下注规则约束
• 最终视觉打磨和高级动效

7. 已验证结果

本次代码在当前状态下已完成以下验证：

• pnpm lint 通过
• pnpm build 通过
• http://localhost:5174/zh-CN/game 可正常打开