# auto-quote

**Repository Path**: taj5/auto-quote

## Basic Information

- **Project Name**: auto-quote
- **Description**: 智能报价助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AutoQuote 自动报价系统

AutoQuote 是一个面向干选项目的自动报价系统。系统通过上传价格知识库和工艺提资清册，自动完成设备识别、价格匹配、外围报价计算、干选机报价汇总，并导出 Excel 报价文件。

## 核心流程

```text
工艺提资清册
  ↓
设备识别与规格解析
  ↓
匹配价格知识库
  ├─ 标准品价格库 → 干选机报价
  └─ 外围设备价格库 → 外围成本计算
  ↓
报价系数换算
  ↓
项目总报价 = 外围报价 + 干选机报价
  ↓
导出 Excel
```

## 已实现功能

- 标准品报价库上传与入库
- 外围设备资料库上传与入库
- 工艺提资清册上传与解析
- 设备名称 + 型号规格的精确匹配
- 去括号规格归一化匹配
- RapidFuzz 模糊匹配
- 外围成本、外围报价、干选机报价、项目总报价自动计算
- 未匹配或需调整的明细支持人工填写单价 / 总价
- 历史报价查询
- 导出：
  - 工艺提资清册（带报价）
  - 项目分项报价表
  - ZIP 打包文件

## 技术栈

| 层级 | 技术 |
| --- | --- |
| 前端 | Vue 3、Vue Router、Element Plus、Vite、TypeScript |
| 后端 | FastAPI、SQLAlchemy、Pydantic Settings |
| Excel 处理 | pandas、openpyxl |
| 匹配算法 | RapidFuzz |
| 数据库 | 默认 SQLite，可切换 MySQL |
| 包管理 | uv、npm |

## 项目结构

```text
backend/   FastAPI 后端，负责 Excel 解析、价格库、匹配、报价计算、导出
frontend/  Vue 3 + Element Plus 前端，负责资料库上传、项目报价、历史报价
data/      样例价格库、样例清册
template/  分项报价表模板
```

后端主要模块：

```text
backend/app/api/       API 路由
backend/app/core/      配置与数据库连接
backend/app/excel/     Excel 解析、归一化、导出写入
backend/app/models/    SQLAlchemy 数据模型
backend/app/schemas/   Pydantic 接口模型
backend/app/services/  导入、匹配、报价、导出等业务逻辑
backend/tests/         后端单元测试
```

前端主要模块：

```text
frontend/src/api/         后端接口封装
frontend/src/components/  复用组件
frontend/src/views/       标准资料库、项目报价、历史报价页面
frontend/src/router/      页面路由
frontend/src/types/       API 类型定义
```

## 快速启动

### 1. 安装后端依赖

```bash
uv sync
```

### 2. 启动后端 API

```bash
uv run uvicorn app.main:app --reload --reload-dir backend/app --app-dir backend
```

后端默认地址：

```text
http://127.0.0.1:8000
```

健康检查：

```text
http://127.0.0.1:8000/health
```

默认使用 SQLite 数据库：

```text
backend/storage/autoquote.db
```

### 3. 安装前端依赖

```bash
cd frontend
npm install
```

### 4. 启动前端

```bash
npm run dev
```

前端默认地址：

```text
http://localhost:5173
```

Vite 会将 `/api` 和 `/health` 代理到后端 `http://127.0.0.1:8000`。

## 使用 MySQL

默认不需要 MySQL。如果要切换到 MySQL，先启动 Docker Compose：

```bash
docker compose up -d mysql
```

然后在项目根目录 `.env` 中配置：

```text
DATABASE_URL=mysql+pymysql://autoquote:autoquote@localhost:3306/autoquote?charset=utf8mb4
```

MySQL 默认连接信息：

| 配置 | 值 |
| --- | --- |
| 数据库 | autoquote |
| 用户名 | autoquote |
| 密码 | autoquote |
| 端口 | 3306 |

## 使用流程

1. 打开前端页面 `http://localhost:5173`。
2. 进入“标准资料库”。
3. 上传标准品报价库，例如：

   ```text
   data/美腾标准品报价20260617（合并）-脱敏.xlsx
   ```

4. 上传外围设备资料库，例如：

   ```text
   data/TDS系统外围设备资料库20260617（合并）-脱敏.xlsx
   ```

5. 进入“项目报价”。
6. 上传工艺提资清册，例如：

   ```text
   data/AI训练-干选项目清册A.xlsx
   ```

7. 系统自动匹配价格并计算报价。
8. 对未匹配或需调整的行，人工填写单价或总价。
9. 导出“工艺提资清册（带报价）”“项目分项报价表”或 ZIP 文件。
10. 在“历史报价”中查看已计算项目并重新下载导出文件。

## 报价规则

### 匹配规则

系统会按顺序尝试：

1. `设备名称@型号规格` 精确匹配
2. 去括号后的规格归一化匹配
3. RapidFuzz 模糊匹配

示例：

```text
TDS专用振动布料器 + TDS20-300-Z1824
→ TDS专用振动布料器@TDS20-300-Z1824
```

### 价格优先级

单条成本明细的价格来源优先级：

1. 人工填写总价
2. 人工填写单价
3. 匹配到的价格库单价
4. 未定价

### 汇总公式

外围成本：

```text
外围成本 = Σ(外围设备单价 × 数量)
```

外围报价：

```text
外围报价 = 外围成本 / 报价系数
```

项目总报价：

```text
项目总报价 = 外围报价 + 干选机报价
```

## 常用开发命令

### 后端测试

运行全部测试：

```bash
uv run pytest
```

运行单个测试文件：

```bash
uv run pytest backend/tests/unit/test_pricing_service.py
```

运行单个测试用例：

```bash
uv run pytest backend/tests/unit/test_pricing_service.py::test_manual_total_has_priority
```

### 前端构建

```bash
cd frontend
npm run build
```

构建命令会先运行 TypeScript 类型检查，再执行 Vite 生产构建。

### 前端预览

```bash
cd frontend
npm run preview
```

## 主要 API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/health` | 健康检查 |
| GET | `/api/knowledge/imports` | 查看资料库导入批次 |
| POST | `/api/knowledge/upload?source_type=standard` | 上传标准品报价库 |
| POST | `/api/knowledge/upload?source_type=peripheral` | 上传外围设备资料库 |
| GET | `/api/knowledge/products` | 查看产品预览 |
| POST | `/api/quotes/upload-checklist` | 上传清册并创建报价 |
| GET | `/api/quotes` | 查看历史报价 |
| GET | `/api/quotes/{quote_id}` | 查看报价详情 |
| PATCH | `/api/quotes/{quote_id}/parameters` | 更新项目名称或报价系数 |
| PATCH | `/api/quotes/{quote_id}/items/{item_id}` | 更新明细人工价格 |
| POST | `/api/quotes/{quote_id}/recalculate` | 重新计算报价 |
| GET | `/api/quotes/{quote_id}/exports/checklist` | 导出带报价清册 |
| GET | `/api/quotes/{quote_id}/exports/itemized` | 导出项目分项报价表 |
| GET | `/api/quotes/{quote_id}/exports/all` | 导出 ZIP |

## 配置项

后端配置位于 `backend/app/core/config.py`，可通过 `.env` 覆盖：

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `DATABASE_URL` | `sqlite:///./backend/storage/autoquote.db` | 数据库连接 |
| `UPLOAD_DIR` | `backend/storage/uploads` | 上传文件目录 |
| `EXPORT_DIR` | `backend/storage/exports` | 导出文件目录 |
| `TEMPLATE_FILE` | `template/分项报价表.xlsx` | 分项报价表模板 |
| `MATCH_FUZZY_THRESHOLD` | `85` | 模糊匹配阈值 |

## 数据文件

`data/` 目录包含可用于本地验证的样例文件：

```text
美腾标准品报价20260617（合并）-脱敏.xlsx
TDS系统外围设备资料库20260617（合并）-脱敏.xlsx
AI训练-干选项目清册A.xlsx
```