# guozhenjiang-bot

**Repository Path**: git-xiaocui/guozhenjiang-bot

## Basic Information

- **Project Name**: guozhenjiang-bot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-19
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 国振江智能问答机器人 (Guozhenjiang QA Bot)

基于 DeepSeek + MySQL 的自然语言查询助手。用户用中文提问，系统自动转为 SQL 查询数据库并返回答案。

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Node.js + Express |
| AI | DeepSeek V4 (OpenAI 兼容 SDK) |
| 数据库 | MySQL + Sequelize ORM |
| 前端 | 可嵌入聊天小部件 (Vanilla JS) |
| 协议 | 多轮 Tool Calling (`describe_tables` + `query_database`) |

## 快速开始

### 1. 环境要求

- Node.js >= 18
- MySQL >= 5.7
- DeepSeek API 密钥（[申请地址](https://platform.deepseek.com/api_keys)）

### 2. 配置环境变量

```bash
# 复制并编辑 .env
cp .env.example .env
```

| 变量 | 说明 | 示例值 |
|------|------|--------|
| `DB_HOST` | 数据库地址 | `localhost` |
| `DB_PORT` | 数据库端口 | `3306` |
| `DB_DATABASE` | 数据库名 | `guozhenjiang` |
| `DB_USER` | 数据库用户 | `root` |
| `DB_PASSWORD` | 数据库密码 | `your_password` |
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | `sk-xxx` |
| `DEEPSEEK_BASE_URL` | API 地址 | `https://api.deepseek.com` |
| `DEEPSEEK_MODEL` | **模型名（注意：不能用旧名 `deepseek-chat`）** | `deepseek-v4-flash` |
| `PORT` | 服务端口 | `3000` |

> ⚠️ **模型名说明**：DeepSeek 已不再支持 `deepseek-chat`，必须使用 `deepseek-v4-pro` 或 `deepseek-v4-flash`。

### 3. 初始化数据库

```bash
# 先创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS guozhenjiang CHARACTER SET utf8mb4;"

# 导入表结构和种子数据
mysql -u root -p guozhenjiang < seed.sql
```

### 4. 安装依赖并启动

```bash
cd guozhenjiang-bot
npm install
npm start              # 生产模式
npm run dev            # 开发模式（nodemon 热重载）
```

服务默认运行在 **http://localhost:3000**，看到以下日志即启动成功：

```
数据库连接成功
数据表已同步
Sales QA Bot 已启动: http://localhost:3000
```

## API 接口

### 健康检查

```bash
GET /api/health
# → { "status": "ok", "time": "..." }
```

### 提交问题（带对话历史）

```bash
POST /api/query
Content-Type: application/json

{ "question": "今天A产品跑了多少量" }
```

### 单次查询（不带历史）

```bash
GET /api/query?q=今天A产品跑了多少量
```

## 嵌入式小部件

在任何 HTML 页面中嵌入聊天机器人：

```html
<script src="http://your-server:3000/widget.js"></script>
<script>
  SalesBot.init({ apiBase: 'http://your-server:3000/api' });
</script>
```

## 项目结构

```
guozhenjiang-bot/
├── server.js                    # 入口文件
├── config/
│   └── database.js              # Sequelize 数据库配置
├── routes/
│   └── query.js                 # 查询路由（API 入口）
├── services/
│   ├── deepseekService.js       # DeepSeek API 调用 + Tool Calling 主逻辑
│   ├── schemaService.js         # 表结构缓存与格式化
│   └── sqlAgent.js              # SQL 执行器（只读，拦截写操作）
├── models/
│   └── Conversation.js          # 会话模型（Sequelize）
├── public/
│   ├── index.html               # 聊天界面
│   └── widget.js                # 可嵌入聊天小部件
├── seed.sql                     # 数据库初始化脚本
└── .env                         # 环境变量配置
```

## 数据库表

| 表名 | 字段 | 说明 |
|------|------|------|
| `g_doc` | `id, name, create_time, total, type_code, person_code` | 文档/产品主表 |
| `g_doc_msg` | `id, doc_id, msg, create_time, is_used` | 文档消息记录 |
| `g_doc_dict` | `id, code, name, parent_id` | 字典表（产品类型、人群分类等） |

## 开发说明

- **只读查询** — 所有 SELECT 查询通过 `sqlAgent.js` 执行，`INSERT/UPDATE/DELETE` 被拦截
- **表结构缓存** — 缓存 5 分钟，修改表结构后等待缓存刷新或重启服务
- **会话存储** — 当前为内存 Map，服务重启后丢失（适合开发测试）
- **多轮推理** — 模型可多次调工具（`describe_tables` 查看结构 → `query_database` 执行 SQL），最多 6 轮
- **DeepSeek V4 兼容性** — 调用时使用了 `tools` 参数，但**不支持 `tool_choice: 'required'`**，代码中已设置为 `'auto'`

## 常见问题

**Q: 启动报错 `400 The supported API model names are deepseek-v4-pro or deepseek-v4-flash`**
→ 检查 `.env` 中 `DEEPSEEK_MODEL` 是否为 `deepseek-v4-pro` 或 `deepseek-v4-flash`，旧名 `deepseek-chat` 已失效。

**Q: 启动报错 `400 Thinking mode does not support this tool_choice`**
→ DeepSeek V4 不支持 `tool_choice: 'required'`，代码中已统一使用 `'auto'`。

**Q: 报错 `getaddrinfo ENOTFOUND api.deepseek.com`**
→ 网络/DNS 问题，检查能否访问 `api.deepseek.com`，或更换网络环境。