hankin
423baff73b
- Docker bridge 网络隔离（8000 端口封死） - Gunicorn 4 Worker 多进程 - Alembic 数据库迁移基线 - 日志轮转 20m×3 - JWT 密钥 + DB 密码 + CORS 收紧 - 3-2-1 备份链路（NAS + R740-B 冷备） - 连接池 pool_pre_ping + pool_recycle=3600
277 lines
13 KiB
Markdown
277 lines
13 KiB
Markdown
# 润滑油 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 阶段性存档，随系统迭代持续更新。*
|