企业 AI 智能报价审核系统

面向制造业报价审核场景的完整演示系统：工作人员粘贴客户原始报价需求 → AI 结构化识别 → 程序计算金额 → 缺失字段 / 金额异常检测 → 人工复核确认 → SQLite 持久化。

一、项目介绍

客户会通过文字、PDF、Excel、图片等方式提交报价信息。本系统把「AI 结构化识别」和「确定性计算/校验」分开：

• AI 只负责把非结构化文本识别为结构化字段，缺失字段输出 null，绝不猜测补全；
• 金额（数量 × 单价）与缺失/异常检测全部由程序代码完成，不依赖大模型结果；
• AI 识别结果必须经过人工复核确认才会成为正式数据。

无 API Key 时系统自动降级为内置 Mock 解析器，完整业务流程照常可跑通。

二、技术栈

层	选型
后端	Python 3.10+ / FastAPI / Pydantic v2 / SQLAlchemy 2
数据库	SQLite（默认，零安装；DATABASE_URL 可切换 MySQL/PostgreSQL）
AI	DeepSeek（OpenAI 兼容接口，JSON Mode + Pydantic 结构化校验）；Mock 兜底
前端	Vue 3（CDN 单页，零构建，FastAPI 直接托管）
测试	pytest + TestClient（Mock AI，无需网络/Key）
部署	Docker / docker-compose（可选）

三、项目结构

.
├── backend/
│   ├── app/
│   │   ├── main.py                  # FastAPI 入口（API + 静态页）
│   │   ├── config.py                # .env 配置
│   │   ├── database.py / models.py  # SQLAlchemy 连接与数据表
│   │   ├── schemas.py               # Pydantic：结构化输出约束 / API 契约
│   │   ├── api/
│   │   │   ├── quotes.py            # 提交需求 / 查询记录
│   │   │   └── review.py            # 人工复核：确认 / 驳回
│   │   ├── services/
│   │   │   ├── extractor.py         # 流程编排：识别→清洗→计算→检测
│   │   │   ├── calculator.py        # 金额计算（纯函数，核心）
│   │   │   ├── validator.py         # 缺失字段 / 金额异常检测
│   │   │   ├── prompt.py            # 系统提示词（禁止猜测约束）
│   │   │   └── ai/
│   │   │       ├── base.py          # Provider 抽象接口
│   │   │       ├── openai_compat.py # DeepSeek 等 OpenAI 兼容模型
│   │   │       └── mock.py          # 无 Key 时的演示解析器
│   │   └── static/                  # 前端单页（Vue CDN）
│   ├── tests/                       # pytest 自动化测试
│   ├── requirements.txt
│   ├── .env.example                 # 环境变量模板（提交用）
│   ├── run.bat                      # Windows 一键启动
│   └── Dockerfile
├── docker-compose.yml
└── .gitignore

四、如何启动

方式一（Windows 一键）：

cd backend
run.bat

方式二（手动）：

cd backend
python -m venv .venv
.\\.venv\\Scripts\\activate        # Windows；macOS/Linux 用 source .venv/bin/activate
pip install -r requirements.txt
copy .env.example .env             # 然后填入 DEEPSEEK_API_KEY
uvicorn app.main:app --host 127.0.0.1 --port 8000

浏览器打开 http://127.0.0.1:8000。

方式三（Docker）：

docker compose up --build

五、AI 模型如何接入

项目使用 OpenAI 兼容接口，一套代码可切换多家模型。在 backend/.env 中配置：

AI_PROVIDER=deepseek          # auto | deepseek | mock
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

• DeepSeek：默认配置即开即用；
• 其他 OpenAI 兼容模型（如 Qwen）：改 DEEPSEEK_BASE_URL 与 DEEPSEEK_MODEL；
• 无 Key / Mock：AI_PROVIDER=mock 或清空 Key 后 AI_PROVIDER=auto。

输入 / 输出格式

• 输入：客户原始文本（POST /api/quotes 的 raw_text）。
• 输出：由 schemas.py::ExtractedQuote 约束的 JSON，含客户、产品、规格、材质、数量、单价、客户填写金额、交货要求、表面处理等字段。
• 实现方式：response_format={"type": "json_object"} + 系统提示词硬性约束「未提供字段必须为 null，禁止猜测」+ Pydantic 二次校验。

异常情况如何处理

1. 调用失败 / 超时 / JSON 解析失败：自动重试一次；仍失败则降级为内置 Mock 解析器，并在记录 ai_warning 字段中说明，业务流程不中断；
2. 模型输出非法字段：Pydantic extra="ignore" 丢弃多余字段，缺失字段保持 null；
3. 数字带单位（如 "380元/套"）：calculator.py 统一清洗为数字，金额计算与展示全部由程序完成。

六、数据如何保存

SQLite 单表 quote_records（backend/data/quote_review.db），每条记录保存：

字段	说明
raw_text	客户原始需求
ai_result_json	AI 识别结果（含 null 缺失字段）
confirmed_result_json	人工确认后的最终数据
program_amount / customer_amount / amount_diff	程序计算金额 / 客户填写金额 / 差额
missing_fields / alerts_json	缺失字段 / 异常提示
status	PENDING_REVIEW → CONFIRMED / REJECTED
reject_reason	驳回原因
created_at / updated_at	创建 / 更新时间

如需切换数据库，修改 DATABASE_URL 为 MySQL/PostgreSQL 连接串即可（SQLAlchemy 已抽象）。

七、核心业务流程

粘贴原始需求 → AI 结构化识别（缺失=null）
      → 程序计算金额（数量×单价）
      → 缺失字段 / 金额异常检测
      → 人工复核页（可修改、可补充）
      → 确认保存（重新计算并校验）→ SQLite

八、已完成功能

• ✅ 功能一：客户原始需求录入（文本粘贴）
• ✅ 功能二：AI 结构化识别（DeepSeek JSON Mode + Pydantic 约束）
• ✅ 功能三：AI 禁止猜测（缺失字段 null + 程序判定缺失并提示人工确认）
• ✅ 功能四：金额由程序计算（calculator.py，20×380=7600）
• ✅ 功能五：金额异常检测（客户填写 vs 程序计算，展示差额）
• ✅ 功能六：人工复核界面（可修改识别结果、补充缺失、确认/驳回）
• ✅ 功能七：数据保存（SQLite，含原始需求/AI 结果/确认结果/金额/缺失/异常/状态/时间）
• ✅ Mock AI 兜底 + 清晰的模型接口设计（无 Key 可完整演示）
• ✅ README + .env.example + AI Coding 使用说明
• ✅ 自动化测试（金额计算、缺失检测、异常检测、API 全流程）
• ✅ Docker 一键部署（加分项）
• ✅ AI 调用失败自动降级（Retry / Fallback，加分项）

九、未完成功能 / 已知问题

• ⬜ PDF / Excel / 图片（OCR）上传解析：未做，已在服务层留出接口位
• ⬜ 多条产品明细：当前按单条产品设计，多明细需扩展数据结构
• ⬜ 字段来源证据 / AI 置信度：未做
• ⬜ 操作日志 / 更完整审核状态机：未做
• ⚠️ 已知问题：Vue 通过 CDN 引入，离线环境需将 vue.global.prod.js 下载到本地 static/ 并修改引用
• ⚠️ 已知问题：Mock 解析器基于正则，仅覆盖题目示例格式，复杂文本请使用真实模型

十、API 一览

方法	路径	说明
POST	/api/quotes	提交原始需求，AI 识别 + 计算 + 检测
GET	/api/quotes	审核记录列表
GET	/api/quotes/{id}	记录详情
POST	/api/quotes/{id}/confirm	人工确认（action: confirm）或驳回（action: reject）
GET	/api/health	健康检查

十一、AI Coding 使用情况

• 使用的 AI 工具：Codex（OpenAI）用于需求分析、代码脚手架搭建、测试编写与调试。
• AI 主要帮助完成的工作：根据需求文档拆解功能并生成 FastAPI 骨架、Pydantic 结构化 schema、前端单页、pytest 用例；协助排查编码/环境问题。
• 自己完成的技术决策： 技术选型（FastAPI + SQLite + Vue 单页）与数据库表结构设计。
• AI 是否生成过错误代码/方案，如何发现并解决：出现过相对导入路径错误与测试环境变量未生效问题，通过运行 pytest 定位后修正；生成的前端数字展示存在浮点精度隐患，改为整数分位计算并复用后端金额逻辑校验。所有代码均经过人工复核与自动化测试验证。