#  ERP Smart Control Platform

**Repository Path**: yuruyimycodes/erp-smart-control-platform

## Basic Information

- **Project Name**:  ERP Smart Control Platform
- **Description**: 
ERP Smart Control Platform
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-13
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ERP智能管控平台

基于企业知识库的智能问答系统，六层知识注入架构，支持文档识别、RAG检索增强生成、Text2SQL、AgenticRAG闭环、多模态对话、实时语音对话。

## 技术栈

| 层级                 | 技术                                          |
| -------------------- | --------------------------------------------- |
| **后端**       | FastAPI + SQLAlchemy + MySQL + Redis          |
| **前端**       | Vue.js 3 + Vite + Element Plus                |
| **向量数据库** | Milvus 2.6 (Docker standalone)                |
| **嵌入模型**   | BGE-M3 (本地 4.3G, dense 1024d + sparse)      |
| **重排序**     | BGE-Reranker-Large (本地 6.3G, ONNX)          |
| **文档识别**   | PaddleOCR-VL-1.5 (本地 1.8G)                  |
| **大模型**     | qwen3.7-max / qwen3.7-max-preview (DashScope) |
| **依赖管理**   | uv (pyproject.toml, Python 3.12)              |

## 六层知识注入架构 (RAGAS 评测总分 94.72%)

```
用户查询 → Node1 意图路由(100%) → Node2 术语解析(93%)
         → Node3 RAG检索(100%) → Node4 Text2SQL(83%*)
         → Node5 SQL安全(100%) → Node6 AgenticRAG闭环(92%)
```

*Node4 实际100%，2个LLM ReadTimeout已修复(API_TIMEOUT 30s→120s)

### RAG 检索流水线

```
PaddleOCR-VL-1.5 → 文本提取 → 父子分块(parent=1200, child=400, 10%overlap)
  → BGE-M3 混合嵌入(dense 1024d×0.7 + sparse×0.3)
  → Milvus 混合检索 → 父块去重 → BGE-Reranker 重排
  → Vanna 上下文补充(76条 DDL+docs+SQL)
```

## 环境配置

### 后端环境

本项目使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理。

```bash
cd backend
uv sync
```

如需使用 pip 安装：

```bash
pip install -r backend/requirements.txt
```

**注意：** PaddleOCR 和 PaddlePaddle 需额外安装，numpy 必须 <2 以兼容 PaddleOCR。

### 前端环境

```bash
cd frontend
npm install
npm run dev  # 默认端口 3000
```

## 功能特性

### 核心功能

- **RAG 检索增强生成**：意图识别 → 查询扩展 → 混合检索(BGE-M3) → 重排序(BGE Reranker) → 流式生成(kimi-k2.6)
- **知识库管理**：创建/删除(软删除)/切换知识库，文档上传与解析，全局搜索
- **文档识别**：PaddleOCR 解析 PDF/图片，父子分块策略(1200/400 字符，10%重叠)
- **多模态对话**：Qwen2.5-VL 模型支持文本+图片混合输入（阿里百炼 API）
- **实时语音对话**：浏览器录音 → WebSocket 流式传输 → Fun-ASR 识别 → LLM 流式回复 → TTS 音频播报
  - 前端 MediaRecorder 录音 + Web Audio API 队列播放
  - VAD 静音检测自动结束语音采集
  - TTS 支持 Qwen3 TTS WebSocket 流式 / Edge-TTS 两种引擎
  - 语音播报文字高亮（已播/未播同步）
- **明暗主题切换**：系统级主题配置，支持亮色/暗色模式
- **响应式布局**：适配不同浏览器窗口尺寸和缩放比例
- **RBAC 权限控制**：用户/角色/权限管理，验证码系统

### 知识库特性

- 多知识库管理与切换
- 软删除与向量数据同步
- 知识库上限控制（默认 20 个）
- 全局搜索（跨知识库关键词搜索）

### 模型参数配置

- 后端配置化：temperature、top_p、history_rounds 等参数校验
- model_validator 自动回退非法参数值

## API 接口

### 认证接口

- `POST /api/v1/auth/login` - 登录
- `POST /api/v1/auth/register` - 注册
- `POST /api/v1/auth/refresh` - 刷新 Token

### 对话接口

- `POST /api/v1/chat/sessions` - 创建对话
- `GET /api/v1/chat/sessions` - 获取对话列表
- `POST /api/v1/chat/sessions/{id}/messages` - 发送消息
- `POST /api/v1/chat/sessions/{id}/multimodal` - 多模态对话
- `WS /api/v1/chat/ws` - 文本对话 WebSocket

### 语音接口

- `WS /api/v1/chat/voice-ws` - 实时语音对话 WebSocket（录音 → STT → LLM → TTS）
  - 二进制帧：音频数据（WebM 分片）
  - `{"type":"audio_end"}`：录音结束，触发识别
  - `{"type":"reset"}`：清空对话历史
- `POST /api/v1/chat/voice/transcribe` - 语音识别（HTTP，兼容旧接口）
- `POST /api/v1/chat/voice/synthesize` - 语音合成（HTTP，兼容旧接口）

### 知识库接口

- `POST /api/v1/kb` - 创建知识库
- `GET /api/v1/kb` - 获取知识库列表
- `GET /api/v1/kb/search` - 全局搜索
- `DELETE /api/v1/kb/{id}` - 删除知识库(软删除)
- `POST /api/v1/kb/{id}/documents` - 上传文档

### ChatBI / 智能查询接口

- `POST /api/v1/chatbi/query` - NL2SQL 查询
- `POST /api/v1/chatbi/query/preview` - SQL 预览
- `POST /api/v1/chatbi/query/stream` - 流式查询（SSE）
- `GET /api/v1/chatbi/query/history` - 查询历史
- `DELETE /api/v1/chatbi/query/history/{id}` - 删除历史
- `GET /api/v1/chatbi/vanna/status` - Vanna 训练状态
- `POST /api/v1/chatbi/vanna/train` - 触发 Vanna 训练
- `GET /api/v1/chatbi/metadata/*` - 元数据管理
- `GET /api/v1/chatbi/semantic/*` - 语义层管理

### 用户管理接口

- `GET /api/v1/users` - 用户列表
- `PUT /api/v1/users/{id}` - 更新用户
- `DELETE /api/v1/users/{id}` - 删除用户

## 微服务与可观测性 (Phase 3–8)

| 能力               | 入口                             | 配置                                       |
| ------------------ | -------------------------------- | ------------------------------------------ |
| MCP Server         | `POST /mcp` (Streamable HTTP)  | `MCP_AUTH_ENABLED`, `MCP_RATE_LIMIT_*` |
| A2A 编排           | `POST /api/agents/orchestrate` | `FEATURE_A2A_ORCHESTRATION_API`          |
| gRPC 基础服务      | 独立进程或同进程 fallback        | `GRPC_USE_REMOTE`, `GRPC_*_HOST/PORT`  |
| Prometheus         | `GET /metrics`                 | `GRPC_METRICS_ENABLED`                   |
| 断路器 / gRPC 状态 | `/api/observability/*`         | 需认证                                     |

```bash
# 独立 gRPC 微服务层（可选 overlay）
cd docker
docker compose -f docker-compose.yml -f docker-compose.grpc.yml up -d

# 开发热部署（uvicorn --reload + Vite HMR）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
```

详见 [`docs/项目总结.md`](docs/项目总结.md)、[`docs/standards/07-grpc-microservices.md`](docs/standards/07-grpc-microservices.md)。

## Docker 部署

```bash
# 启动所有核心服务（MySQL + Redis + Milvus + Backend + Frontend）
cd docker
docker compose up -d

# 仅启动基础设施
docker compose up -d mysql redis milvus-standalone attu

# 启动核心服务 + DataHub 元数据管理
docker compose -f docker-compose.yml -f docker-compose.datahub.yml up -d
```

**Docker 服务：**

| 服务              | 容器名           | 端口  |
| ----------------- | ---------------- | ----- |
| MySQL 8.0         | `erp_mysql`    | 13306 |
| Redis 7           | `erp_redis`    | 6379  |
| Milvus 2.6        | `erp_milvus`   | 19530 |
| Attu (Milvus GUI) | `erp_attu`     | 3000  |
| MinIO Console     | `erp_minio`    | 9001  |
| Backend (FastAPI) | `erp_backend`  | 8000  |
| Frontend (Nginx)  | `erp_frontend` | 80    |

详见 `docker/README.md`

## 启动服务

### 启动后端

```bash
cd backend
uv run python -m app.main  # 或 uv run uvicorn app.main:app --reload --port 8000
```

### 启动前端

```bash
cd frontend
npm run dev  # 端口 3000
```

## 配置说明

配置文件位于 `backend/.env`，主要配置项：

```env
# 数据库配置
DB_HOST=localhost
DB_PORT=13306
DB_USER=erp_user
DB_PASSWORD=erp123456
DB_NAME=erp_qa_system

# LLM 配置 (DashScope)
LLM_API_KEY=sk-your-key
LLM_MODEL_NAME=qwen3.7-max
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=2000
API_TIMEOUT=120.0

# 嵌入模型 (本地 BGE-M3)
EMBEDDING_MODEL_PATH=models/bge-m3
EMBEDDING_DIMENSION=1024
EMBEDDING_DENSE_WEIGHT=0.7
EMBEDDING_SPARSE_WEIGHT=0.3

# 重排序模型 (本地 BGE-Reranker)
RERANKER_MODEL_PATH=models/bge-reranker-large
RERANK_TOP_K=8

# PaddleOCR 视觉语言模型
PADDLE_OCR_VL_MODEL_PATH=models/PaddleOCR-VL-1.5

# 父子分块策略
PARENT_CHUNK_SIZE=1200
CHILD_CHUNK_SIZE=400
CHUNK_OVERLAP_RATIO=0.1

# 语音对话配置
VOICE_STT_PROVIDER=dashscope           # STT：dashscope = Fun-ASR
STT_MODEL=fun-asr-realtime
VOICE_TTS_MODE=qwen3-ws                # TTS：qwen3-ws / qwen3 / edge-tts
VOICE_TTS_MODEL=qwen3-tts-flash-realtime
VOICE_TTS_VOICE=longxiaochun
VOICE_TTS_SPEECH_RATE=1.0
VOICE_VAD_TIMEOUT=1.5                  # VAD 静音超时（秒）

# 知识库配置
MAX_KNOWLEDGE_BASES=20
DEFAULT_RETRIEVAL_TYPE=hybrid

# 向量检索配置
MILVUS_HOST=localhost
MILVUS_PORT=19530

# 重排序配置
RERANKER_MODEL_PATH=BAAI/bge-reranker-large
RERANK_TOP_K=5
```

## 数据库迁移

首次部署或升级后需要执行数据库迁移：

```bash
mysql -h localhost -u root -p erpQaSystem < backend/migrations/add_parent_chunk_fields.sql
```

详见 `backend/migrations/README.md`

## 模型下载

首次运行前需要下载所需模型：

```bash
python scripts/download_models.py
```

## 项目结构

```
erp-smart-control-platform/
├── backend/                       # FastAPI 后端
│   ├── app/
│   │   ├── agents/                # 多Agent智能体
│   │   │   ├── coordinator/       # 总控协调智能体（Supervisor + LangGraph）
│   │   │   │   ├── agent.py       # 编排器构建与流式调用
│   │   │   │   └── nodes.py       # LangGraph节点定义
│   │   │   ├── sales/             # 销售智能体
│   │   │   ├── inventory/         # 库存智能体
│   │   │   ├── procurement/       # 采购智能体
│   │   │   ├── production/        # 生产智能体
│   │   │   ├── finance/           # 财务智能体
│   │   │   ├── hr/                # 人力智能体（预留）
│   │   │   ├── business/          # 业务Agent工厂（兼容层）
│   │   │   └── factory.py         # 子Agent工厂（sql/retrieval/voice/multimodal）
│   │   ├── agent_loop/            # Agent Loop运行时
│   │   │   ├── skills/            # 技能目录
│   │   │   │   ├── business/      # 业务域Skills（5域×3=15个）
│   │   │   │   ├── system/        # 系统内置Skills（7个）
│   │   │   │   └── custom/        # 自定义Skill模板
│   │   │   ├── task_tracker.py    # 任务追踪器（监控数据持久化）
│   │   │   ├── orchestrator.py    # 多Agent编排调度
│   │   │   └── runtime.py         # Agent Loop运行时初始化
│   │   ├── prompts/               # 提示词模板（Jinja2工程化）
│   │   │   ├── base/              # 基础模板（base_agent/sub_agent/tool_call/error/output/security）
│   │   │   ├── coordinator/       # 总控Agent模板
│   │   │   ├── sales/             # 销售Agent模板
│   │   │   ├── inventory/         # 库存Agent模板
│   │   │   ├── procurement/       # 采购Agent模板
│   │   │   ├── production/        # 生产Agent模板
│   │   │   ├── finance/           # 财务Agent模板
│   │   │   ├── hr/                # 人力Agent模板
│   │   │   └── common/            # 跨模块通用模板
│   │   ├── utils/                 # 工具类
│   │   │   ├── prompt_loader.py   # Jinja2+LangChain提示词加载器
│   │   │   └── sql_loader.py      # SQL模板加载器
│   │   ├── core/                  # 核心配置、数据库、日志
│   │   │   ├── base_model.py      # 统一BaseModel（时间戳+软删除）
│   │   │   └── repository.py      # 通用Repository（泛型CRUD）
│   │   ├── api/                   # API 路由
│   │   ├── chatbi/                # ChatBI 智能问答
│   │   ├── mcp_server/            # MCP Server工具网关
│   │   ├── models/                # SQLAlchemy 模型
│   │   ├── schemas/               # Pydantic 模式
│   │   ├── services/              # 业务服务
│   │   └── seed_erp/              # ERP种子数据与治理
│   ├── sql/                       # SQL模板集中管理
│   │   ├── inventory/             # 库存域SQL（3个）
│   │   ├── finance/               # 财务域SQL（3个）
│   │   ├── procurement/           # 采购域SQL（3个）
│   │   ├── sales/                 # 销售域SQL（3个）
│   │   └── production/            # 生产域SQL（3个）
│   ├── pyproject.toml
│   ├── requirements.txt
│   ├── .env
│   └── Dockerfile
├── frontend/                      # Vue.js 前端
│   ├── src/
│   │   ├── api/                   # API 调用（Axios统一封装）
│   │   ├── stores/                # Pinia 状态管理
│   │   ├── views/                 # 页面视图
│   │   │   ├── chat/              # 智能对话
│   │   │   ├── knowledge/         # 知识库管理
│   │   │   └── agent-monitor/     # 业务智能监控
│   │   ├── components/            # 公共组件
│   │   └── styles/                # 主题与响应式
│   ├── Dockerfile
│   └── vite.config.js
├── docker/                        # Docker Compose 配置
├── models/                        # 本地模型存储
├── data/                          # 数据目录
└── scripts/                       # 运维脚本
```

## 规划中功能

- ChatBI 语义层增强（自动关系发现、指标推导）
- 语音对话 RAG 商品检索集成
- 多模态模型升级：Qwen2.5-VL 已集成（阿里百炼 API）

## 2026-06-12 架构升级 — 提示词工程化 + SQL统一管理 + 目录重组

### 提示词工程化（26个Jinja2模板）

- 所有Agent提示词从Python代码剥离，存放于`app/prompts/`独立模板文件
- 公共片段提取为基础模板：`base_agent.j2`（业务Agent）、`sub_agent.j2`（子Agent）
- 模板继承体系消除重复：「重要指令」等公共规则只在基类维护一处
- `prompt_loader.py`：Jinja2渲染 + LangChain ChatPromptTemplate包装，不引入额外框架

### SQL统一管理（15个.sql模板 + Repository层）

- **第一层ORM**：`core/base_model.py`统一BaseModel（TimestampMixin+SoftDeleteMixin），`core/repository.py`泛型CRUD
- **第二层SQL模板**：`sql/{domain}/*.sql`按业务模块分类，Jinja2条件渲染+SQLAlchemy参数绑定
- `sql_loader.py`：统一加载和执行，消除MCP工具中f-string拼接SQL

### Agents目录重组

- 7域独立目录：`agents/{coordinator,sales,inventory,procurement,production,finance,hr}/agent.py`
- `coordinator/nodes.py`：LangGraph节点定义（classify/dispatch/fusion/fallback）
- 旧文件保留为兼容性重导出

### Skills技能目录

- `agent_loop/skills/business/`：5域×3个=15个业务Skill
- `agent_loop/skills/system/builtin.py`：7个系统内置Skill
- `agent_loop/skills/custom/template.py`：自定义Skill模板

### Bug修复

- MCP call_tool返回值双层嵌套→直接透传
- Fallback SQL统一使用模板（消除两套不同SQL）
- 消息格式元组→字典、会话thread_id查找修复
- 中文分词`str.split()`→`jieba.cut()`
- SQL模板`{% endif %}`换行粘连修复
- Docker MinIO端口冲突→19000/19001

## 安全修复记录

### 2026-06-08 - P0/P1/P2全面优化（27主任务/68子任务）

#### P0-安全加固（5项）

- WebSocket Token传递方式修复：从URL Query参数改为Sec-WebSocket-Protocol头，防止Token泄露
- 验证码Token哈希存储：使用`hash_token()`存储，`verify_token_hash()`验证，数据库无明文Token
- Vite代理端口一致性修复：8003→8000，支持环境变量`VITE_API_TARGET`
- CORS配置生产加固：移除通配符`*`，使用具体头列表，启动自检告警
- DEBUG模式禁用与错误脱敏：生产环境错误响应不含traceback，JWT Token日志脱敏

#### P1-可靠性修复（5项）

- 数据库连接池健康检查：主库/ChatBI/ERP库全部启用`pool_pre_ping=True`
- Redis限流原子性修复：Lua脚本原子执行INCR+EXPIRE，异常时降级为内存限流
- 时区处理统一化：`datetime.utcnow`→`datetime.now(timezone.utc)`
- ORM声明风格统一化：`Column()`→`Mapped[]`+`mapped_column()`
- SQLite Checkpointer并发安全：移除SQLite降级，强制PostgreSQL

#### P2-代码质量（6项）

- 前端safeJsonParse去重：统一导入`@/utils/json`
- 前端Token存储逻辑去重：`useAuth`组合式函数封装saveTokens/clearTokens
- 后端意图分类逻辑去重：统一使用`IntentClassifier`
- 后端知识库ID过滤去重：统一通过`KbAccessService.filter_for_user()`
- 用户上下文传递统一：`UserContext`数据类+ContextVar机制
- 前端API请求取消能力：`useAbortController`组合式函数，组件卸载自动取消

#### 性能优化（6项）

- N+1查询消除：已确认无N+1模式，ChatMessage无懒加载关联
- 缺失索引补充：ChatMessage.created_at添加index=True
- WebSocket背压控制：BackpressureManager类，缓冲区满时降速生成
- LLM摘要缓存：Redis缓存(TTL=5min)+content_hash去重
- 向量模型预热：已确认lifespan中包含BGE-M3预热逻辑
- Redis降级策略优化：Lua脚本+内存降级，禁止静默放行

### 2026-05-27 - 安全修复（70项）

#### P0 关键修复（13项）

- JWT密钥空值校验，防止未签名Token通过验证
- 验证码改用`secrets.choice`安全随机数，防止可预测性
- 用户/角色更新API白名单校验，防止任意字段setattr注入
- 数据库连接池修复（NullPool→连接池），解决连接泄漏
- `time.sleep`→`asyncio.sleep`，修复异步阻塞
- WebSocket session上下文管理器，防止连接泄漏
- Token刷新Promise死锁修复
- 面包屑导航修复
- 分片上传FormData格式修复
- 迁移SQL parent_id类型修复+content_id补全
- pyproject.toml补全5个核心依赖

#### P1 重要修复（30项）

- Redis pipeline原子性、异常日志完善、死循环重试上限
- remember_me Token重新生成、精确异常捕获
- CORS headers配置、密码重置Token哈希存储
- 路径遍历防护、文件上传大小校验
- 前端：safeJsonParse、logout通知后端、路由守卫过期检查
- 前端：validate纯Promise模式（11个组件）、Token不暴露URL
- 前端：fetch→axios统一、API调用移入onMounted、WebSocket状态实例化

#### P2 次要修复（27项）

- `datetime.utcnow`→`datetime.now(timezone.utc)`（9文件）
- `get_event_loop`→`get_running_loop`
- debug路由条件注册、UPLOAD_DIR从config读取
- 内存泄漏清理、ChatView移除keep-alive
- N+1查询批量优化、fitz上下文管理器
- config.py移除硬编码默认值、.env.production清理废弃配置

## 六层架构

```
┌─────────────────────────────────────────────────┐
│                API 网关层                         │
│   FastAPI路由 / WebSocket / 认证鉴权 / 限流       │
├─────────────────────────────────────────────────┤
│              Agent 编排层                         │
│   LangGraph 6节点状态机: 意图→路由→工具→反思→融合→记忆 │
├──────────────────────┬──────────────────────────┤
│     检索层 (RAG)      │    Text2SQL 层           │
│  向量检索/重排序/网络搜索│  NL2SQL/安全校验/结果修复  │
├──────────────────────┴──────────────────────────┤
│              统一语义层                           │
│   业务术语表 / 同义词映射 / 领域本体 / 实体链接     │
├─────────────────────────────────────────────────┤
│           Catalog 主数据层                        │
│   DataHub血缘追踪 / 质量监控 / 表字段级权限         │
├─────────────────────────────────────────────────┤
│             导入治理层                            │
│   Airbyte+Dagster / 多源接入 / 清洗脱敏 / 增量同步  │
└─────────────────────────────────────────────────┘
```

## 测试

### Agent 层测试

```bash
cd backend
uv run pytest tests/agent/ -v -m agent          # Agent六节点单元测试
uv run pytest tests/agent/test_agent_chain.py -v # 集成链路测试
```

### AgenticRAG 自主思考测试

```bash
uv run pytest tests/agenticrag/ -v               # 全部自主思考测试
uv run pytest tests/agenticrag/ -v -m agenticrag_think       # 推理链测试
uv run pytest tests/agenticrag/ -v -m agenticrag_reflect     # 多轮反思测试
uv run pytest tests/agenticrag/ -v -m agenticrag_decision    # 决策路径测试
uv run pytest tests/agenticrag/ -v -m agenticrag_hallucination # 幻觉自检测试
```

### 全量测试

```bash
uv run pytest tests/ -v --ignore=tests/agent --ignore=tests/agenticrag  # 已有测试（无回归）
uv run pytest tests/ -v                                                  # 全量
```

## 开发指南

### 依赖管理

```bash
cd backend
uv add <package>          # 添加运行时依赖
uv add --dev <package>    # 添加开发依赖（pytest等）
uv sync                   # 同步安装依赖
```

### 代码规范

- 遵循华为编码要求规范
- 类型注解：所有函数参数和返回值需标注类型
- Docstring：公共函数和类需添加docstring
- 提交规范：feat/fix/docs/test/refactor/chore

## License

MIT