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](/Users/jiaunun/Desktop/36-character-flower/src/components/language-link.tsx)
新增内容：
- 抽出语言切换按钮组件
- 从 `/$lang` 布局文件中拆出，避免路由文件内混入过多内部组件

#### [src/components/nav-link.tsx](/Users/jiaunun/Desktop/36-character-flower/src/components/nav-link.tsx)
新增内容：
- 抽出顶部导航按钮组件
- 供语言布局页复用

#### [src/components/stat-card.tsx](/Users/jiaunun/Desktop/36-character-flower/src/components/stat-card.tsx)
新增内容：
- 抽出首页信息卡片组件
- 用于首页业务入口页展示

### 3.2 设备识别

#### [src/lib/device/use-device-type.ts](/Users/jiaunun/Desktop/36-character-flower/src/lib/device/use-device-type.ts)
新增内容：
- 基于窗口宽度判断当前设备是 `mobile` 还是 `desktop`
- 为同一路由下渲染不同视图提供支持

### 3.3 游戏共享模型

#### [src/features/game/shared/constants.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/shared/constants.ts)
新增内容：
- 36 宫格基础尺寸常量
- 回合阶段枚举
- 格子状态枚举
- 连接状态枚举
- 筹码默认配置等

#### [src/features/game/shared/types.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/shared/types.ts)
新增内容：
- 游戏核心类型定义
- 包括格子、筹码、下注、历史、公告、连接、dashboard、bootstrap 快照等

#### [src/features/game/shared/mock-data.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/shared/mock-data.ts)
新增内容：
- 游戏 mock 启动数据
- 包括 36 个格子、筹码、历史记录、当前回合、公告、连接状态、桌面信息

#### [src/features/game/shared/selectors.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/shared/selectors.ts)
新增内容：
- 各种纯函数派生逻辑
- 包括格子 view model、倒计时、公告筛选、趋势计算、下注汇总等

#### [src/features/game/shared/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/shared/index.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](/Users/jiaunun/Desktop/36-character-flower/src/store/game/game-round-store.ts)
新增内容：
- 回合相关状态
- 包括格子、筹码、回合阶段、历史、趋势、下注选择
- 提供切换筹码、下注、清空、同步回合等动作

#### [src/store/game/game-session-store.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/game/game-session-store.ts)
新增内容：
- 会话类状态
- 包括公告、连接状态、dashboard 信息
- 提供已读公告、关闭公告、同步连接、同步 dashboard 等动作

#### [src/store/game/game-ui-store.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/game/game-ui-store.ts)
新增内容：
- UI 控制类状态
- 当前只放了自动托管浮层、dashboard、规则面板开关

#### [src/store/auth/auth-store.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/auth/auth-store.ts)
说明：
- 认证相关 store
- 原有 `auth-store` 已归入 `auth` 子目录

#### [src/store/auth/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/auth/index.ts)
说明：
- 统一导出认证模块 store

#### [src/store/game/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/game/index.ts)
说明：
- 统一导出游戏模块 store

#### [src/store/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/store/index.ts)
新增内容：
- 统一导出 `src/store` 下各模块
- 当前包括 `auth` 和 `game`

#### [src/features/game/model/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/model/index.ts)
新增内容：
- 作为过渡导出层，继续对 `features/game` 暴露游戏 store

### 3.5 游戏接口层

#### [src/features/game/api/types.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/api/types.ts)
新增内容：
- 游戏接口 DTO 类型定义

#### [src/features/game/api/game-api.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/api/game-api.ts)
新增内容：
- 游戏 API 包装
- 包括 bootstrap、round feed、announcement 的响应映射
- 提供 `getMockGameBootstrap()` 用于当前阶段 UI 接线

#### [src/features/game/api/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/api/index.ts)
新增内容：
- 对 `api` 子模块统一导出

### 3.6 游戏共享 UI 组件

#### [src/features/game/components/shared/game-action-bar.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-action-bar.tsx)
新增内容：
- 筹码区、主按钮、次按钮、附加 slot 区域

#### [src/features/game/components/shared/game-announcement-modal.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-announcement-modal.tsx)
新增内容：
- 强制公告弹层骨架

#### [src/features/game/components/shared/game-auto-spin-overlay.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-auto-spin-overlay.tsx)
新增内容：
- 自动托管运行遮罩骨架

#### [src/features/game/components/shared/game-board-cell.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-board-cell.tsx)
新增内容：
- 单个格子组件
- 支持状态、徽标、倍率、点击等展示

#### [src/features/game/components/shared/game-board.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-board.tsx)
新增内容：
- 36 宫格容器组件

#### [src/features/game/components/shared/game-history-list.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-history-list.tsx)
新增内容：
- 开奖历史列表组件

#### [src/features/game/components/shared/game-panel-card.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-panel-card.tsx)
新增内容：
- 通用游戏面板容器

#### [src/features/game/components/shared/game-status-card.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-status-card.tsx)
新增内容：
- 顶部状态卡片组件

#### [src/features/game/components/shared/game-trend-list.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/game-trend-list.tsx)
新增内容：
- 走势列表组件

#### [src/features/game/components/shared/types.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/types.ts)
新增内容：
- 共享展示组件的 props 类型

#### [src/features/game/components/shared/utils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/shared/utils.ts)
新增内容：
- 简单的 `cn` 工具

### 3.7 双端页面壳

#### [src/features/game/components/mobile/mobile-game-page.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/mobile/mobile-game-page.tsx)
新增内容：
- 移动端游戏页壳层
- 负责纵向编排

#### [src/features/game/components/desktop/desktop-game-page.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/desktop/desktop-game-page.tsx)
新增内容：
- 桌面端游戏页壳层
- 负责多栏编排

#### [src/features/game/components/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/components/index.ts)
新增内容：
- 对组件模块统一导出

### 3.8 游戏入口与总导出

#### [src/features/game/entry/entry-page.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/entry/game-route-page.tsx)
新增内容：
- 游戏路由页适配层
- 负责：
  - 读取 Zustand 状态
  - 拉 mock bootstrap
  - 组装状态卡片、历史、走势、面板内容
  - 根据设备类型切换移动端 / 桌面端壳层
  - 接公告弹窗、自动托管遮罩
  - 使用 i18n 文案

#### [src/features/game/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/features/game/index.ts)
新增内容：
- 对 `game` 功能模块统一导出

### 3.9 新游戏路由

#### [src/routes/$lang/game.tsx](/Users/jiaunun/Desktop/36-character-flower/src/routes/%24lang/game.tsx)
新增内容：
- 新增 `/$lang/game` 路由
- 作为游戏大厅的统一业务入口

## 4. 修改文件清单与说明

### 4.1 基础常量与全局信息

#### [src/constants/untils.ts](/Users/jiaunun/Desktop/36-character-flower/src/constants/index.ts)
修改内容：
- 将应用名称从通用模板名改为 `36字花`
- 更新默认描述文案
- 新增桌面断点常量 `DESKTOP_LAYOUT_MIN_WIDTH_PX`

#### [index.html](/Users/jiaunun/Desktop/36-character-flower/index.html)
修改内容：
- 更新站点标题
- 更新默认 description / OG / Twitter meta 信息

### 4.2 样式层

#### [src/styles.css](/Users/jiaunun/Desktop/36-character-flower/src/styles.css)
修改内容：
- 保持 `html/body/#root` 占满视口
- 增加全局游戏主题变量
- 增加游戏外壳、面板、光效等 utility 样式
- 增加深色游戏背景基础视觉

### 4.3 路由与页面

#### [src/routes/$lang/route.tsx](/Users/jiaunun/Desktop/36-character-flower/src/routes/%24lang/route.tsx)
修改内容：
- 把原来的简单 `Outlet` 布局升级成业务壳层
- 增加顶部导航
- 增加语言切换按钮
- 使用共享导航组件

#### [src/routes/$lang/index.tsx](/Users/jiaunun/Desktop/36-character-flower/src/routes/%24lang/index.tsx)
修改内容：
- 把原来的占位首页改成业务入口首页
- 增加进入游戏大厅 CTA
- 展示当前项目架构说明

#### [src/routeTree.gen.ts](/Users/jiaunun/Desktop/36-character-flower/src/routeTree.gen.ts)
修改内容：
- 因新增路由自动重新生成
- 非手写文件

### 4.4 国际化

#### [src/locales/zh-CN/common.ts](/Users/jiaunun/Desktop/36-character-flower/src/locales/zh-CN/common.ts)
修改内容：
- 更新首页和壳层文案
- 新增整套 `game.*` 文案
- 包括：
  - 游戏大厅标题、副标题
  - 状态卡片文案
  - 盘面、历史、走势文案
  - 公告弹窗、自动托管文案
  - 页脚说明文案
  - phase 展示文案

#### [src/locales/en-US/common.ts](/Users/jiaunun/Desktop/36-character-flower/src/locales/en-US/common.ts)
修改内容：
- 与中文语言包同步补齐英文版本 `game.*` 文案

## 5. 本次特别修复

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

涉及文件：
- [src/features/game/entry/entry-page.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/entry/game-route-page.tsx)

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

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

涉及文件：
- [src/features/game/entry/entry-page.tsx](/Users/jiaunun/Desktop/36-character-flower/src/features/game/entry/game-route-page.tsx)
- [src/routes/$lang/route.tsx](/Users/jiaunun/Desktop/36-character-flower/src/routes/%24lang/route.tsx)
- [src/locales/zh-CN/common.ts](/Users/jiaunun/Desktop/36-character-flower/src/locales/zh-CN/common.ts)
- [src/locales/en-US/common.ts](/Users/jiaunun/Desktop/36-character-flower/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` 可正常打开