# chess_tiny_analyser

**Repository Path**: wang_s_gitee/chess_tiny_analyser

## Basic Information

- **Project Name**: chess_tiny_analyser
- **Description**: 分析当前棋手的对局并找出历史对局形成题库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# chess_tiny_analyser

国际象棋智能习题生成与对局分析平台。

学员导入自己的对局（PGN 文本 / PGN 文件 / Lichess 链接），平台提取带 `!` `!!` `?` `??` `!?` `?!` 标注的关键局面，
在**写入时预计算**（Stockfish 最佳走法 + Chess Position Embedder 768 维向量 + Zobrist 去重），
在**读取时零引擎开销**地生成习题、支持相似局面检索与阶段性缺点分析，并通过 **SSE 流式协议**让自然语言直接驱动前端页面跳转。

## 技术栈

| 层 | 技术 |
|----|------|
| 后端 | Spring Boot 4.0.8 · Spring AI 2.0.1 · Java 17 · Maven |
| LLM | DeepSeek（OpenAI 兼容，`base-url=https://api.deepseek.com`） |
| 存储 | MongoDB Atlas Local（数据 + `$vectorSearch` 向量检索）· Redis（令牌/限流/幂等/流缓存） |
| 棋类 | chesslib 1.3.7（PGN/FEN/走法）· Stockfish（预计算）· ONNX Runtime + searchless-9m-mma（768 维向量） |
| 前端 | Vue 3 · Vite 8 · TypeScript · Pinia · Vue Router · vue3-chessboard · chess.js · markdown-it |

## 需求文档（唯一口径）

**全部需求说明位于 [`docs/`](docs/README.md)**，请从 [`docs/00-需求分析与功能点.md`](docs/00-需求分析与功能点.md) 与
[`docs/01-总体架构与技术选型.md`](docs/01-总体架构与技术选型.md) 开始阅读。

关键文档：

- [docs/00 · 需求分析与功能点清单](docs/00-需求分析与功能点.md)
- [docs/01 · 总体架构与技术选型](docs/01-总体架构与技术选型.md)
- [docs/02 · 数据模型设计](docs/02-数据模型设计.md)
- [docs/03 · 接口契约与统一约定](docs/03-接口契约与统一约定.md)
- [docs/04 · 流式传输与页面导航设计](docs/04-流式传输与页面导航设计.md)
- [docs/11 · Skill 设计与清单](docs/11-Skill设计与清单.md) · [docs/12 · Prompt 设计](docs/12-Prompt设计.md)
- [docs/16 · 初始化状态与实施路线](docs/16-初始化状态与实施路线.md)

## 工程状态（本次初始化）

> **当前仓库只包含可运行、可构建的"依赖壳子"，尚未实现任何业务逻辑。**
> 各模块的实现清单见 [`docs/16`](docs/16-初始化状态与实施路线.md)。

```text
backend/    Spring Boot 壳子（依赖已解析验证；仅含启动类、配置、空测试）
frontend/   Vue 3 壳子（依赖已安装、生产构建通过；仅含路由与占位页面）
docs/       需求与设计文档
```

## 快速开始

### 1. 启动中间件（MongoDB + Redis + Stockfish）

```bash
cp .env.example .env        # 填入 DEEPSEEK_API_KEY
docker compose up -d mongo redis stockfish
```

向量模型文件需自行下载后放到 `models/` 目录（两个文件必须同目录）：

```text
models/searchless-9m-mma.onnx
models/searchless-9m-mma.onnx.data
```

### 2. 后端

```bash
cd backend
mvn spring-boot:run            # http://localhost:8080
```

### 3. 前端

```bash
cd frontend
pnpm install
pnpm dev                       # http://localhost:5173（/api 已代理到 8080）
```

### 4. 全栈容器化

```bash
docker compose up --build
# web → http://localhost:3000
```

## 目录约定

| 路径 | 说明 |
|------|------|
| `docs/` | 需求与设计文档（唯一口径） |
| `backend/` | Spring Boot 服务 |
| `frontend/` | Vue 3 应用 |
| `models/` | ONNX 向量模型（**不入库**，需外挂） |
| `data/pgn/` | 上传的 PGN 落盘目录（**不入库**） |