# ai-chat-platform

**Repository Path**: midoucode/ai-chat-platform

## Basic Information

- **Project Name**: ai-chat-platform
- **Description**: AI问答平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-12
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 智能问答平台 · 实训脚手架

> **技术栈**：Spring Boot 3.3 + Vue 3 + Python (FastAPI) + RAG 知识库
> **环境要求**：JDK 17+ / Maven 3.9+ / Node 18+ / Python 3.10+ / MySQL 8
> **周期**：13 天 × 4 课时（52 课时）
> **定位**：大学生项目实训脚手架，开箱即用，每天有可见产出

---

## ✨ 核心亮点（"高大上 + 上手容易"）

| 功能 | 技术 | 学生改动量 |
|------|------|-----------|
| 流式打字机对话 | SSE (Server-Sent Events) | 只改前端渲染 |
| AI 大模型调用 | FastAPI + OpenAI 兼容接口 | 只改 Prompt / Key |
| 知识库问答 | ChromaDB + RAG | 只改检索逻辑 |
| 鉴权 | JWT (JJWT 0.12) | 脚手架已配好 |
| 现代 Java | switch 表达式 / Record / Lombok | Boot 3 原生支持 |

**降级机制**：`AI_API_KEY` 留空自动进入 **MOCK 模式**，仍按字流式输出 —— 没 Key / 没网也能演示全部效果。

---

## 🚀 快速开始（3 步跑起来）

```bash
# 0. 课前自检（强烈建议先跑）
bash check-env.sh          # Windows: check-env.bat

# 1. 克隆并进入项目
git clone <仓库地址> && cd ai-chat-platform

# 2. 初始化数据库（默认账号 root / 123456）
#    ★ Windows：双击 init-db.bat（自动绕过 PowerShell 的 < 重定向限制）
#    Mac/Linux：bash init-db.sh
#    手动方式：见下方「数据库初始化」说明
#    密码不是 123456？改 ai-backend\src\main\resources\application.yml
#    没有 MySQL？见 手动启动指南_Windows.md 的 H2 内存库方案

# 3. 一键启动（Mac/Linux）
bash start_all.sh
# Windows: 双击 start_all.bat

# 4. 浏览器打开
http://localhost:5173
```

### ⚠️ Windows 行尾（CRLF）特别说明（重要）

> 项目内 **所有 `*.bat / *.cmd / *.ps1` 已统一为 CRLF**，`*.sh / *.py / 源码` 统一为 LF，
> 规则锁定在 `.gitattributes`。若你看到 `'.' is not recognized`、`'PER_DIR'`、`'湴'` 等乱码报错，
> 说明脚本被转成了 LF / UTF-8 BOM，**CMD 解析错位**所致。

**一键修复**（在项目根目录执行任一）：
```powershell
# PowerShell（推荐）
powershell -ExecutionPolicy Bypass -File fix-line-endings.ps1
# 或 Git Bash
bash fix-line-endings.sh
```
修复后 `.\mvnw.cmd -version` 应输出 Maven 版本。若仍异常，见 `ai-backend/MVNW_ENCODING.md`。

### 💾 数据库初始化（Windows 特别注意）

> **直接双击 `init-db.bat`** 即可：自动建库 + 导入 `init.sql`。
> 若 MySQL 不在 PATH，用记事本打开脚本，把 `MYSQL=` 改成完整路径，例如：
> `set "MYSQL=C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe"`

**成功标志**：脚本末尾 `SHOW TABLES;` 列出 5 张表。
> ⚠️ PowerShell **不支持 `<` 重定向**（`'<为将来保留'` 报错），故请勿手动执行
> `mysql ... < init.sql`，改用 `init-db.bat` 或 `SOURCE` 命令。

启动顺序：MySQL → Redis(可选) → Python AI 引擎(8000) → Spring Boot 后端(8080) → Vue 前端(5173)

---

## 📁 目录结构

```
ai-chat-platform/
├── ai-backend/        # Spring Boot 3.3 后端（JDK 17, jakarta.*）
│   ├── pom.xml
│   ├── .mvn/wrapper/  # Maven Wrapper（无 Maven 也能编译）
│   ├── mvnw / mvnw.cmd
│   ├── sql/init.sql
│   └── src/
├── ai-frontend/       # Vue 3 + Vite + Element Plus
├── ai-engine/         # Python FastAPI（流式 SSE + RAG）
├── .vscode/           # 统一工作区配置（settings/launch/extensions）
├── docker-compose.yml # MySQL 8 + Redis
├── check-env.sh / .bat # 环境自检
├── init-db.sh / .bat    # 数据库初始化（Windows 双击即用）
├── start_all.sh / .bat  # 一键启动
├── ARCHITECTURE.md    # 架构与版本约定
└── 教学指南.md         # 13 天逐日教学流程（教师/学生共用）
```

---

## 🛠️ 开发工具：统一用 VS Code

一个编辑器写 Java / Vue / Python，三端共用一个窗口 + 三个终端。

**必装插件（8 个）**：Extension Pack for Java、Spring Boot Extension Pack、Lombok、Vue - Official(Volar)、ESLint、Prettier、Python、Pylance。
强烈推荐：REST Client、GitLens、Path Intellisense、Error Lens。
**别装**：Vetur（与 Volar 冲突）。

一键安装：`code --install-extension <id>`（完整清单见 教学指南.md 第 0 天）

---

## 🔑 API Key 预算（教师申请用）

- **零预算**：用免费额度（智谱 GLM-4-Flash、DeepSeek 新用户、阿里云百炼 100 万 Token）
- **最稳方案**：教师统一 1 个账号，充值 **50 元**，配后端代理 + 限流（每人每天 50 次）
- 成本控制：开 prompt cache、历史截断 10~20 条、默认 Flash/Turbo、超限返回 MOCK

详见 教学指南.md 附录 A。

---

## 📋 13 天进度一览

| 天 | 主题 | 情绪峰值 |
|----|------|---------|
| 0 | 环境准备（VS Code + JDK17） | |
| 1 | 环境打通 + Hello | |
| 2 | 注册登录 JWT | |
| 3 | 前端布局 | |
| 4 | 会话管理 | |
| 5 | AI 引擎联调 | |
| **6** | **SSE 流式打字机** | ⭐ |
| 7 | Markdown 渲染 | |
| 8 | Prompt 模板 | |
| **9** | **知识库 RAG** | ⭐ |
| 10 | 调用统计（可裁剪） | |
| 11 | 联调 Bug 修复 | |
| 12 | 打磨 + 文档 | |
| 13 | 答辩 | |

裁剪规则：P0 不可砍；P1 可简化；时间紧砍 Day 10。

---

## 🚨 常见报错速查

| 报错 | 原因 | 解决 |
|------|------|------|
| `switch 表达式 ... -source 8` | **JDK 不是 17** | 装 JDK 17，设 `JAVA_HOME` |
| `javax.* cannot resolve` | 混用了旧代码 | 全部改 `jakarta.*`（本项目已改好） |
| `BCryptPasswordEncoder cannot resolve` | 缺 Security 依赖 | Boot 3 已内置，检查是否误删 `SecurityConfig` |
| `Failed to resolve import "axios"` | 依赖未装 | `cd ai-frontend && npm install axios` |
| `ancient lockfile` 警告 | npm 版本旧 | 可忽略，或删 `package-lock.json` 重装 |
| 端口占用 | 8080/5173/8000 被占 | 改配置或杀进程 |

完整清单 + Day 1 自检命令见 教学指南.md。

---

## 📄 许可证

仅限教学用途。