# 润滑油 CRM/ERP 系统 — 阶段性全栈复盘与架构白皮书

**项目代号**：天津硕博霖业财一体化 ERP（SHBL-ERP）  
**当前阶段**：Phase 1.5（核心业务闭环 + AI 中枢接入 / 内测上线态）  
**报告日期**：2026 年 3 月  
**系统版本**：v0.1.0  
**部署地址**：`http://192.168.1.100`（内网单节点）

---

## 一、系统技术基座 (Tech Stack & Dependencies)

本系统采用现代化前后端分离架构，AI 能力通过 Dify + Ollama 私有化部署实现，全栈可控。

### 1. 前端架构 (Frontend)

| 技术 | 说明 |
|------|------|
| **Vue 3** (Composition API) + TypeScript | 核心框架，14 个业务页面组件 |
| **Vite** | 构建工具，极速冷启动与 HMR |
| **Element Plus** | 企业级 UI，深度定制了报销单 `@media print` A4 打印样式 |
| **Pinia** | 全局状态管理（UserInfo、Token、RBAC 权限） |
| **Axios** | 封装全局 Request/Response 拦截器，自动处理 401 登出与业务异常 |
| **SSE (EventSource)** | AI 复盘报告实时流式输出 |

### 2. 后端架构 (Backend)

| 技术 | 说明 |
|------|------|
| **Python 3.10+ & FastAPI** | 核心框架，16 个 API 路由模块，自带 OpenAPI/Swagger 文档 |
| **Uvicorn** | ASGI 异步服务器 |
| **SQLAlchemy 2.0 + Asyncpg** | 全异步 ORM，19 张业务表 |
| **JWT + Passlib (Bcrypt)** | 认证体系（Token + 密码哈希） |
| **httpx** | 异步 HTTP 客户端，用于调用 Dify API 和 Ollama |

### 3. AI 能力层

| 组件 | 说明 |
|------|------|
| **Dify** (192.168.1.88) | AI 编排平台，承载 Workflow（复盘报告生成）和 Chat（AI 悬浮球对话） |
| **Ollama — RTX 3090** (192.168.1.88:11434) | 运行 `qwen3.5:27b`，用于复盘报告、企业画像等重任务 |
| **Ollama — RTX 4060** (192.168.1.88:11435) | 运行 `qwen3.5:4b`，用于发票 OCR 解析等轻任务 |

### 4. 数据持久层 (Database)

- **核心数据库**：PostgreSQL（宿主机直连，asyncpg 驱动）
- **19 张业务表**，覆盖 CRM、ERP、财务、AI、系统五大域
- **亮点特性**：`JSONB` 承载 AI OCR 提取数据 (`ai_extracted_data`)、强事务并发控制（库存/发货防重）

### 5. 部署架构

```
┌────────────────────────────────────────────────┐
│ 服务器 192.168.1.100 (Ubuntu, 61GB 磁盘)       │
│                                                │
│  Docker Compose                                │
│  ┌──────────────────┐ ┌──────────────────────┐ │
│  │ crm-frontend     │ │ crm-backend          │ │
│  │ Nginx:80 (95MB)  │ │ Uvicorn:8000 (889MB) │ │
│  │ bridge 网络      │ │ host 网络            │ │
│  └──────┬───────────┘ └──────────────────────┘ │
│         │ proxy_pass                ↓          │
│         └── host.docker.internal:8000          │
│                                                │
│  PostgreSQL (宿主机 :5432) ← 直连              │
└────────────────────────────────────────────────┘
          │
    ┌─────┴─────┐
    │ Dify + Ollama │  ← 192.168.1.88
    │ (RTX 3090/4060)│
    └───────────────┘
```

---

## 二、九大核心业务模块全景剖析

系统已点亮 **9 大核心模块 + 2 个 AI 模块**，实现从"线索"到"现金"的业财链路闭环，并接入大模型智能辅助。

### 模块 1：RBAC 权限与系统基座

- **功能**：用户登录、改密、角色管理、员工管理
- **核心亮点**：**`data_scope` 数据横向隔离机制** — `self`（本人）/ `dept_and_sub`（部门）/ `all`（全公司）三维度，所有业务查询均受拦截，杜绝越权
- **关键表**：`sys_users`、`sys_roles`、`sys_departments`

### 模块 2：CRM 客户管理

- **功能**：客户全生命周期管理（新增、编辑、归档、搜索筛选、导入/导出）
- **核心亮点**：
  1. 创建时自动绑定 `owner_id`，融入 `data_scope` 防线
  2. **联系人管理** — 独立 `crm_contacts` 表，支持多联系人关联
  3. **AI 企业画像** — 调用 Ollama 大模型生成企业分析卡片
  4. **AI 客情健康度评分** — 基于交互频率自动打分
  5. **批量 Excel 导入/导出** — 支持模板下载 + openpyxl 解析

### 模块 3：供应链与货品库存

- **功能**：左树（无限级分类）右表（SKU）经典布局
- **核心亮点**：
  1. **无限级分类树**：`erp_product_categories` 自关联支持 N 级嵌套
  2. **安全库存变更**：一切库存变动必须通过 `POST /api/products/inventory/flow` 提交出入库流水，后端强事务加减库存，留存 `erp_inventory_flows` 审计轨迹
  3. **库存预警**：`stock_qty <= warning_threshold` 自动标红提示
  4. **批量 SKU 导入**：Excel 模板 + SKU 编码防重

### 模块 4：订单交易枢纽

- **功能**：主子表嵌套的沉浸式开单体验，支持多 SKU 明细行
- **核心亮点**：**B2B 智能动态定价（一客一价）** — 选中 SKU 时静默调用 `/api/orders/price/calculate`，自动调取该客户历史专属拿货价

### 模块 5：物流与发货执行

- **功能**：发货单管理，指导仓库拣货出库
- **核心亮点**：
  1. **五步原子事务防超发**：校验 `发货量 ≤ 订单总量 - 已发量`，订单状态更新 + 库存扣减 + 发货单生成毫秒级级联
  2. **数据级联预加载**：发货单透出客户名称、包装规格等

### 模块 6：财务报销与票据中心

- **功能**：三 Tab 一站式财务管理 — 统一票据池 / 新建报销 / 报销大盘
- **核心亮点**：
  1. **发票 AI 智能解析**：拖拽上传 PDF/JPG/PNG/MD → 调用 Ollama 4060 (qwen3.5:4b) 自动提取发票号、金额、日期等字段 → 存入 `fin_invoice_pool.ai_extracted_data` (JSONB)
  2. **批量上传队列**：支持多文件并行处理，逐一显示解析进度
  3. **发票状态机**：发票被报销单选中瞬间 `is_used` 锁定，驳回自动释放
  4. **高级科目定制**：硬编码"天津硕博霖"专属原始种类（招待费、交通费）和冲顶类型（税务费用）
  5. **A4 打印**：CSS `@media print` 标准黑白审批单，带四大签字占位符

### 模块 7：销项发票管理

- **功能**：独立的销项发票（开票）管理模块
- **核心亮点**：
  1. 客户名称/发票号搜索 + 回款状态筛选 + 开票日期范围
  2. AI 发票文本提取（与票据池共用 Ollama 解析引擎）
  3. 独立 `finance_sales_invoices` 表

### 模块 8：销售日志

- **功能**：销售人员每日拜访/沟通记录管理
- **核心亮点**：
  1. 独立 `sales_logs` 表，支持关键字搜索 + 日期筛选
  2. **AI 智能审阅** — 调用大模型对日志内容进行质量评分和建议
  3. 数据同时作为 AI 复盘报告的原始素材

### 模块 9：Dashboard 工作台

- **功能**：首页 KPI 总览 + 快捷操作入口
- **核心亮点**：
  1. **四大 KPI 卡片**：本月订单数 / 待出库发货 / 库存预警 SKU / 本月营收 — 后端 `GET /api/dashboard/stats` 聚合查询实时计算
  2. 快捷按钮一键跳转至订单、发货、库存、日志页面

---

## 三、AI 中枢模块

### AI 模块 A：智能复盘报告（Dify Workflow + SSE）

- **架构**：`前端 → 后端 SSE → Dify Workflow → Ollama 3090 (27B)`
- **流程**：
  1. 前端选择时间范围，后端查询 `sales_logs` 并序列化
  2. 通过 httpx 异步调用 Dify Workflow API（streaming 模式）
  3. Workflow 内部：HTTP 获取日志 → LLM 分析生成 → HTTP 回调存档
  4. 后端 SSE 实时推送 `text_chunk` 到前端逐字渲染
  5. 生成完毕自动保存至 `ai_report_drafts`，支持历史加载和再编辑
- **关键配置**：httpx 600s 超时 + nginx `proxy_buffering off` + 600s 读超时

### AI 模块 B：全局 AI 助手（浮球对话）

- **架构**：`前端 FloatingChat → 后端 /api/chat → Dify Chat API`
- **功能**：全页面右下角悬浮球，随时与 AI 对话，支持上下文记忆
- **底层引擎**：Dify Chat 应用，对接 Ollama

---

## 四、核心数据模型约束

所有核心表均遵守以下企业级约束：

| 约束 | 说明 |
|------|------|
| **主键策略** | 全局 UUID (`uuid4`)，防爬虫遍历 |
| **软删除** | 所有表包含 `is_deleted` (Boolean)，严禁物理 DELETE |
| **时间戳** | `created_at` / `updated_at`，SQLAlchemy 监听器自动维护 |
| **数据隔离** | 业务查询均受 `data_scope` + `owner_id` 拦截 |

### 数据库全表清单（19 张）

| 域 | 表名 | 用途 |
|----|------|------|
| CRM | `crm_customers` | 客户主表 |
| CRM | `crm_contacts` | 客户联系人 |
| ERP | `erp_product_categories` | 产品分类树 |
| ERP | `erp_product_skus` | 产品 SKU |
| ERP | `erp_inventory_flows` | 库存变动流水 |
| ERP | `erp_orders` | 订单主表 |
| ERP | `erp_order_items` | 订单明细行 |
| ERP | `erp_shipping_records` | 发货单主表 |
| ERP | `erp_shipping_items` | 发货明细行 |
| 财务 | `fin_invoice_pool` | 报销发票池 |
| 财务 | `fin_expense_records` | 报销单主表 |
| 财务 | `fin_expense_details` | 报销明细行 |
| 财务 | `finance_sales_invoices` | 销项发票 |
| 协同 | `sales_logs` | 销售日志 |
| AI | `ai_chat_sessions` | AI 对话记录 |
| AI | `ai_report_drafts` | AI 复盘报告草稿 |
| 系统 | `sys_users` | 系统用户 |
| 系统 | `sys_roles` | 角色权限 |
| 系统 | `sys_departments` | 部门组织 |

---

## 五、API 接口全景（16 个路由模块）

| 模块 | 前缀 | 核心端点示例 |
|------|------|-------------|
| auth | `/api/auth` | login, me, password |
| customers | `/api/customers` | CRUD + 归档 + AI 画像 |
| contacts | `/api/contacts` | 客户联系人 CRUD |
| orders | `/api/orders` | CRUD + 动态定价 |
| shipping | `/api/shipping` | 发货 + 原子事务 |
| products | `/api/products` | SKU + 分类树 + 库存变更 |
| finance | `/api/finance` | 票据池 + 报销 + 审批 |
| sales_invoice | `/api/sales-invoices` | 销项发票 CRUD |
| sales_logs | `/api/sales-logs` | 销售日志 CRUD + AI 审阅 |
| reports | `/api/reports` | AI 复盘 SSE 生成 + 历史 |
| dashboard | `/api/dashboard` | KPI 聚合统计 |
| chat | `/api/chat` | AI 浮球对话 |
| dify_tools | `/api/dify-tools` | Dify 回调工具端点 |
| import_export | `/api` | 模板下载 + Excel 导入导出 |
| sys_settings | `/api/settings` | 用户/角色/部门管理 |
| deps | — | 鉴权依赖注入 |

---

## 六、Phase 1 → Phase 2 演进规划

### 已完成（Phase 1 → 1.5 增量）

| 项目 | 原状态（Phase 1） | 现状态（Phase 1.5） |
|------|-------------------|---------------------|
| 发票 AI 识别 | `setTimeout` 模拟 | ✅ Ollama 4060 真实解析 |
| Dashboard KPI | 硬编码 `--` 占位符 | ✅ 后端聚合 API 实时计算 |
| AI 复盘报告 | 无 | ✅ Dify Workflow + SSE 流式输出 |
| AI 对话助手 | 无 | ✅ Dify Chat + 浮球组件 |
| 联系人管理 | 无 | ✅ 独立模块 |
| 销项发票 | 无 | ✅ 独立模块 |
| 销售日志 | 无 | ✅ 独立模块 + AI 审阅 |

### Phase 2 规划

| 优先级 | 方向 | 说明 |
|--------|------|------|
| **P0** | HTTPS | 内网 CA 自签证书，保护 JWT Token 传输安全 |
| **P0** | Alembic 迁移 | 引入数据库 schema 版本管理，告别手工 DDL |
| **P1** | 数据可视化 | ECharts 接入 Dashboard — 月度趋势折线图、报销占比饼图 |
| **P1** | 操作审计日志 | 记录关键操作（删除、审批、密码重置）的完整审计轨迹 |
| **P1** | 文件存储优化 | 对接 MinIO / 阿里云 OSS，替代本地 uploads 目录 |
| **P2** | 移动端适配 | 响应式布局或微信小程序，支持外出销售人员使用 |
| **P2** | 外网访问 | VPN / Cloudflare Tunnel 实现远程办公访问 |
| **P2** | 监控告警 | Prometheus + Grafana 仪表板 + 钉钉/微信告警推送 |
| **P3** | 多租户 | 如需扩展到集团其他子公司，引入租户隔离架构 |

---

## 七、关键架构决策记录 (ADR)

| # | 决策 | 理由 |
|---|------|------|
| ADR-001 | 后端 Docker 使用 `network_mode: host` | 直连宿主机 PostgreSQL，免改 `pg_hba.conf`，简化内网部署 |
| ADR-002 | 前端 Docker 使用 `bridge + extra_hosts` | 通过 `host.docker.internal` 解析宿主机，隔离前端网络 |
| ADR-003 | AI 引擎选择 Dify + Ollama 私有化 | 数据不出内网，满足工业企业信息安全合规要求 |
| ADR-004 | 复盘报告采用 SSE 而非 WebSocket | 单向推送场景 SSE 更轻量，nginx 配置更简单 |
| ADR-005 | 全表 UUID 主键 | 防止 ID 遍历攻击，适配分布式未来扩展 |
| ADR-006 | 库存变更仅允许流水模式 | 杜绝直接篡改库存，确保账实一致 + 审计可追溯 |

---

*本文档为 SHBL-ERP CRM 系统 Phase 1.5 阶段性存档，随系统迭代持续更新。*