Chinese Chess Online (中国象棋在线对战平台)

一个支持 人人对战 + 人机对战（UCCI/UCI/自定义 AI） 的在线中国象棋平台，内置象棋学堂系统。

功能特性

• 用户系统 — 支持游客模式和注册登录模式，JWT 认证
• 在线对战 — 基于 WebSocket 的实时人人对战，支持房间匹配
• AI 对战 — 支持三种 AI 引擎：
  • UCCI 引擎（象眼 ElephantEye）
  • UCI 引擎（Pikafish）
  • 内置自定义 AI 引擎（Java 实现，难度 1-10 级可调）
• 棋盘皮肤 — 40+ 精美棋盘背景，支持 SVG 棋子皮肤切换
• 象棋学堂 — 内置学习系统，包含基础走法、残局技巧、开局入门、中局战术、名局欣赏
• 对局记录 — 自动保存对局历史，支持复盘
• 头像上传 — 支持自定义用户头像

界面截图

技术栈

层次	技术
前端	Vue 3 + Element Plus + Pinia + Vue Router + Vite
后端	Spring Boot 3.5.9 + MyBatis-Plus 3.5.5
语言	Java 21 + JavaScript (ES6)
数据库	MySQL 8.0+
实时通信	WebSocket (Spring Boot 原生支持)
认证	JWT (jjwt)
构建	Maven + npm

快速启动

前置要求

• JDK 21+
• Maven 3.8+
• Node.js 18+
• MySQL 8.0+

1. 创建数据库和导入数据

# 连接 MySQL 并创建数据库（需先安装 MySQL）
mysql -u root -p -e "CREATE DATABASE chs DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入表结构和初始数据
mysql -u root -p chs < sql/schema.sql
mysql -u root -p chs < sql/init-data.sql

2. 配置数据库连接

修改 src/main/resources/application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/chs?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

3. 启动后端

mvn spring-boot:run

后端默认启动在 http://localhost:8088。

4. 启动前端

cd frontend
npm install
npm run dev

前端默认启动在 http://localhost:5173。

项目结构

├── frontend/                 # Vue 3 前端
│   └── src/
│       ├── api/              # API 接口封装
│       ├── chess/            # 棋盘逻辑（FEN 解析等）
│       ├── components/       # 通用组件（棋盘、棋子、AI 选择等）
│       ├── data/             # 学习课程数据（JSON）
│       ├── pages/            # 页面（首页、AI对战、在线对战、学堂等）
│       ├── store/            # Pinia 状态管理
│       └── router.js         # 路由配置
│
├── src/main/
│   ├── java/com/ctgu/uciproject/
│   │   ├── ai/               # AI 引擎层
│   │   │   ├── engine/ucci/  # UCCI 协议引擎（象眼）
│   │   │   ├── engine/uci/   # UCI 协议引擎（Pikafish）
│   │   │   └── engine/custom/ # 自定义 Java AI 引擎
│   │   ├── config/           # 配置（CORS、JWT、WebSocket 等）
│   │   ├── controller/       # REST 控制器
│   │   ├── entity/           # 实体类
│   │   ├── mapper/           # MyBatis-Plus Mapper
│   │   ├── service/          # 业务逻辑层
│   │   ├── websocket/        # WebSocket 房间管理
│   │   └── model/            # 数据传输对象
│   └── resources/
│       ├── config/           # 引擎文件、棋盘皮肤
│       └── application.yml   # 应用配置
│
├── sql/                      # 数据库脚本
│   ├── schema.sql            # 表结构
│   └── init-data.sql         # 初始数据
│
├── docs/                     # 文档
├── uploads/                  # 上传文件（头像等）
└── pom.xml                   # Maven 配置

API 概览

路径	说明
POST /api/user/login	用户登录
POST /api/user/register	用户注册
POST /api/user/guest	游客登录
GET /api/user/info	获取用户信息
POST /api/ai/move	AI 走棋
POST /api/ai/config	AI 配置
GET /api/ai/engines	获取可用引擎列表
GET /api/learn/modules	学习模块列表
GET /api/learn/lessons	课程列表
GET /api/learn/steps	课程步骤
GET /api/endgames	残局列表
GET /api/openings	开局列表
GET /api/game/history	对局历史
WebSocket /ws/game	在线对战 WebSocket

详细 API 文档见 docs/API.md。

AI 引擎说明

UCCI 引擎（象眼 ElephantEye）

经典的中国象棋 UCCI 引擎，位于 src/main/resources/config/engines/ElephantEye/。

UCI 引擎（Pikafish）

基于 Pikafish 的中国象棋 UCI 引擎，位于 src/main/resources/config/engines/pikafish/。

自定义 AI

纯 Java 实现的内置 AI，支持 1-10 级难度调节，无需外部引擎文件。

数据库

使用 MySQL (8.0+)，主要表：

• user — 用户信息
• game_history — 对局历史
• battle_record — 对战记录
• room — 在线房间
• ai_config — AI 配置
• learn_module / learn_lesson / learn_step — 学堂课程
• endgame_position — 残局题库
• opening_sequence — 开局题库