Gobang-Game/CLAUDE.md

CLAUDE.md

项目概述

Gobang v2.0 — 五子棋桌面应用，Rust + Tauri 2.x + React 19 + TypeScript workspace 构建。

构建命令

# 安装前端依赖
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	标题栏显示