mirror of
https://github.com/LHY0125/Gobang-Game.git
synced 2026-06-29 00:45:55 +08:00
133 lines
4.7 KiB
Markdown
133 lines
4.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
## 项目概述
|
||
|
||
Gobang v2.0 — 五子棋桌面应用，Rust + Tauri 2.x + React 19 + TypeScript workspace 构建。
|
||
|
||
## 构建命令
|
||
|
||
```bash
|
||
# 安装前端依赖
|
||
npm install
|
||
|
||
# 开发模式（GUI 热更新）
|
||
npx tauri dev
|
||
|
||
# 仅前端（浏览器预览，无 Tauri 功能）
|
||
npm run dev
|
||
|
||
# 前端测试
|
||
npm test
|
||
npm run test:watch
|
||
|
||
# Rust workspace 全部检查
|
||
cargo check
|
||
|
||
# 仅核心库检查
|
||
cargo check -p gobang-core
|
||
|
||
# Rust 测试
|
||
cargo test
|
||
|
||
# Lint
|
||
cargo clippy -- -D warnings
|
||
|
||
# Rust 格式化
|
||
cargo fmt
|
||
|
||
# 前端类型检查
|
||
npx tsc -b
|
||
|
||
# 生产构建（生成 NSIS 安装包）
|
||
npx tauri build
|
||
```
|
||
|
||
## 架构
|
||
|
||
Cargo workspace 两 crate，前后端分离，通过 Tauri IPC 通信。
|
||
|
||
```
|
||
Gobang/
|
||
├── core/ # Rust 库 crate（零 Tauri 依赖）
|
||
│ └── src/
|
||
│ ├── types.rs # 基础类型 (Position, Color, CellState, GameConfig)
|
||
│ ├── board.rs # 棋盘引擎 (落子/胜负/悔棋/候选位)
|
||
│ ├── rules.rs # 禁手规则 (长连/双三/双四)
|
||
│ ├── ai/
|
||
│ │ ├── mod.rs # AiEngine trait
|
||
│ │ ├── evaluate.rs # 棋形评分
|
||
│ │ └── search.rs # Alpha-Beta 搜索
|
||
│ ├── record.rs # JSON 棋谱记录与复盘
|
||
│ ├── network.rs # renet 网络对战协议
|
||
│ └── llm.rs # LLM AI (OpenAI 兼容 API)
|
||
├── gui/ # Tauri 桌面应用（依赖 core）
|
||
│ └── src/
|
||
│ ├── main.rs # 入口
|
||
│ ├── lib.rs # Tauri Builder + AppState 注册
|
||
│ └── commands.rs # #[tauri::command] → 调用 core
|
||
├── src/ # React 前端 (TypeScript strict 模式)
|
||
│ ├── core/ # 纯逻辑 (types.ts, constants.ts)
|
||
│ ├── store/ # Zustand 状态管理
|
||
│ ├── components/
|
||
│ │ ├── board/ # BoardCanvas + board-renderer
|
||
│ │ ├── menu/ # MainMenu + 各模式 setup
|
||
│ │ ├── game/ # GameView / GameInfo / TimerDisplay / GameControls
|
||
│ │ └── replay/ # ReplayView / StepSlider / ReplayControls
|
||
│ ├── hooks/ # 通用 hooks
|
||
│ └── i18n/ # zh-CN / en
|
||
├── rust-toolchain.toml # 固定工具链版本
|
||
└── Cargo.toml # Workspace 根 + [workspace.package]
|
||
```
|
||
|
||
## IPC 接口（Rust → Frontend）
|
||
|
||
| Command | 参数 | 返回值 | 功能 |
|
||
|---------|------|--------|------|
|
||
| `new_game` | `mode: GameMode, config: GameConfig` | `Result<(), String>` | 开始新局 |
|
||
| `place_piece` | `x: usize, y: usize` | `Result<MoveResult, String>` | 落子 |
|
||
| `undo` | `steps: u32` | `Result<(), String>` | 悔棋 |
|
||
| `get_board` | — | `Result<Vec<Vec<i32>>, String>` | 获取棋盘 |
|
||
| `ai_move` | — | `Result<Option<(usize, usize)>, String>` | AI 走棋 |
|
||
| `get_game_state` | — | `Result<Value, String>` | 完整游戏状态 |
|
||
|
||
## Serde 序列化规则
|
||
|
||
- `GameConfig` 使用 `#[serde(rename_all = "camelCase")]` — 前端 camelCase ↔ Rust snake_case
|
||
- `GameMode` 无 rename — 保持 PascalCase (`Local`, `VsAi`, `Online`, `Replay`)
|
||
- `Color` 无 rename — 保持 PascalCase (`Black`, `White`)
|
||
|
||
## 错误处理
|
||
|
||
### 前端
|
||
|
||
| 场景 | 处理 |
|
||
|------|------|
|
||
| IPC 调用失败 | 返回 `Result<_, String>`，前端 `.catch()` 显示错误 |
|
||
| 落子并发双击 | `GameControls` 检查 `status === 'game_over'` 禁用按钮 |
|
||
| JSON 棋谱损坏 | `LoadReplay` try/catch，alert 提示 |
|
||
| 渲染异常 | Canvas `useRef` + 条件渲染兜底 |
|
||
|
||
### Rust
|
||
|
||
- Board 操作：`Result<Board, MoveError>`，中文 Display
|
||
- IPC 命令：`Result<T, String>`，`map_err(|e| e.to_string())`
|
||
- AI 禁手：`best_move()` 和 `negamax()` 内调用 `rules::is_forbidden()` 过滤
|
||
- LLM 阻塞：`best_move()` 使用 `reqwest::blocking`，调用方应通过 `spawn_blocking` 包装
|
||
|
||
## 关键约束
|
||
|
||
- **Rust 工具链**：`stable-x86_64-pc-windows-gnu`（`rust-toolchain.toml` 强制）
|
||
- **TypeScript**：`strict: true`，零编译错误
|
||
- **打包**：NSIS（`targets: "nsis"`），不使用 WiX/MSI
|
||
- **不可变风格**：`Board::place()` 和 `undo()` 返回新 Board，不修改 self
|
||
- **i18n 初始化**：`main.tsx` 必须 `import './i18n'` 引入，否则界面显示 key
|
||
|
||
## 版本号升级清单
|
||
|
||
| 文件 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| `Cargo.toml` | `[workspace.package] version` | Rust 端版本 |
|
||
| `package.json` | `version` | 前端版本 |
|
||
| `gui/tauri.conf.json` | `version` | 打包版本号 |
|
||
| `gui/tauri.conf.json` | 窗口 `title` | 标题栏显示 |
|