crm_project/SHBL-ERP_CRM_架构白皮书_v0.2.0.md

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

项目代号：天津硕博霖业财一体化 ERP（SHBL-ERP）
当前阶段：Phase 2.0（多租户隔离 + AI 交互优化 / 内测上线态）
报告日期：2026 年 3 月 19 日
系统版本：v0.2.0
部署地址：http://192.168.1.100（内网单节点）
变更基线：基于 v0.1.0 (Phase 1.5) 增量更新

---

一、系统技术基座 (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 权限、当前公司 ID）
Axios	封装全局 Request/Response 拦截器，自动处理 401 登出、业务异常及 X-Company-Id 头部注入
SSE (EventSource)	AI 复盘报告实时流式输出

2. 后端架构 (Backend)

技术	说明
Python 3.10+ & FastAPI	核心框架，17 个 API 路由模块，自带 OpenAPI/Swagger 文档
Uvicorn	ASGI 异步服务器
SQLAlchemy 2.0 + Asyncpg	全异步 ORM，24 张业务表
Alembic	数据库 Schema 版本管理（4 个迁移脚本），async 模式
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 驱动）
• 24 张业务表，覆盖 CRM、ERP、财务、AI、系统五大域 + 多租户域
• Alembic 迁移管理：4 个版本化迁移脚本（baseline → 多租户 → 新宇公司 → sales_logs 业务标签）
• 亮点特性：
  • JSONB 承载 AI OCR 提取数据 (ai_extracted_data)
  • ARRAY(UUID) 承载 sales_logs.involved_company_ids（多公司业务标签）
  • 强事务并发控制（库存/发货防重）
  • 行级多租户隔离（company_id 外键 + GIN 索引）

5. 部署架构

┌────────────────────────────────────────────────┐
│ 服务器 192.168.1.100 (Ubuntu, 61GB 磁盘)       │
│                                                │
│  Docker Compose                                │
│  ┌──────────────────┐ ┌──────────────────────┐ │
│  │ frontend         │ │ backend              │ │
│  │ Nginx:80 (95MB)  │ │ Uvicorn:8000 (889MB) │ │
│  │ bridge 网络      │ │ host 网络            │ │
│  └──────┬───────────┘ └──────────────────────┘ │
│         │ proxy_pass                ↓          │
│         └── host.docker.internal:8000          │
│                                                │
│  PostgreSQL (宿主机 :5432) ← 直连              │
│                                                │
│  Alembic (宿主机 venv) ← 迁移管理             │
│    ↕ 127.0.0.1:5432 (env.py 自动替换)          │
└────────────────────────────────────────────────┘
          │
    ┌─────┴─────┐
    │ Dify + Ollama │  ← 192.168.1.88
    │ (RTX 3090/4060)│
    └───────────────┘

---

二、多租户架构（v0.2.0 新增）

设计原则

采用行级数据隔离（Row-Level Isolation），同一数据库、同一张表，通过 company_id 列区分不同公司数据。

已注册公司

公司	UUID	说明
天津硕博霖	aaaaaaaa-bbbb-cccc-dddd-eeeeeeee0001	默认公司
新宇润滑油	aaaaaaaa-bbbb-cccc-dddd-eeeeeeee0002	第二家公司

隔离矩阵

表	隔离方式	说明
erp_orders	company_id FK	订单按公司隔离
erp_shipping_records	company_id FK	发货单按公司隔离
erp_inventory_flows	company_id FK	库存流水按公司隔离
erp_sku_inventory	company_id FK	库存快照按公司隔离
fin_invoice_pool	company_id FK	报销发票池按公司隔离
fin_expense_records	company_id FK	报销单按公司隔离
finance_sales_invoices	company_id FK	销项发票按公司隔离
sales_logs	involved_company_ids ARRAY(UUID)	业务标签：一条日志可关联多个公司
crm_customers	全局共享	客户资源跨公司共享
erp_product_categories	全局共享	产品分类跨公司共享
erp_product_skus	全局共享	产品 SKU 跨公司共享

技术实现链路

前端 Pinia(currentCompanyId)
      ↓ Axios 拦截器自动注入
请求 Header: X-Company-Id: <uuid>
      ↓
后端 Depends(get_current_company_id)
      ↓ IDOR 校验（sys_user_companies 验证归属）
service 层 .where(Model.company_id == company_id)

• IDOR 防护：get_current_company_id 依赖会查 sys_user_companies 表验证当前用户确实关联了该公司，防止伪造 Header 越权
• 前端公司切换：登录页公司选择 + 首页顶部 Header 下拉切换
• sales_logs 特殊处理：使用 ARRAY.any(company_id) 包含查询 + GIN 索引加速

---

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

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

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

• 功能：用户登录、改密、角色管理、员工管理、公司管理与切换
• 核心亮点：
  1. data_scope 数据横向隔离 — self / dept_and_sub / all 三维度
  2. 多租户公司隔离 — sys_companies + sys_user_companies 多对多关联，支持用户归属多个公司
  3. X-Company-Id 依赖注入 — 所有私有数据查询均受公司视角拦截，双层校验（JWT + 公司归属）
• 关键表：sys_users、sys_roles、sys_departments、sys_companies、sys_user_companies

模块 2：CRM 客户管理

• 功能：客户全生命周期管理（新增、编辑、归档、搜索筛选、导入/导出、转移负责人）
• 核心亮点：
  1. 创建时自动绑定 owner_id，融入 data_scope 防线
  2. 联系人管理 — 独立 crm_contacts 表，支持多联系人关联
  3. AI 企业画像 — 调用 Ollama 大模型生成企业分析卡片（Dify Workflow 回调双轨写入）
  4. AI 客情健康度评分 — 基于交互频率自动打分
  5. 批量 Excel 导入/导出 — 支持模板下载 + openpyxl 解析
  6. 客户转移 — 管理员可跨人员重新分配客户负责人
  7. 全局共享 — 客户数据跨公司共享，不受 company_id 隔离
• 关键表：crm_customers、crm_contacts、crm_follow_up_logs

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

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

模块 4：订单交易枢纽

• 功能：主子表嵌套的沉浸式开单体验，支持多 SKU 明细行
• 核心亮点：
  1. B2B 智能动态定价（一客一价） — 选中 SKU 时静默调用 /api/orders/price/calculate，自动调取该客户历史专属拿货价
  2. 按公司隔离 — 订单数据通过 company_id 实现多租户隔离

模块 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 发票 OCR 识别 — 调用 Ollama 视觉模型提取 merchant/buyer/amount/date 等字段
  3. 批量 OCR → 待确认列表（v0.2.0 新增）：批量上传后不直接创建，OCR 结果暂存可编辑表格，不完整字段标黄高亮，用户审核修正后"一键全部创建"批量入库
  4. 单文件模式：OCR 结果预填到新增表单，buyer 字段自动匹配 CRM 客户
  5. 独立 finance_sales_invoices 表

模块 8：销售日志

• 功能：销售人员每日拜访/沟通记录管理
• 核心亮点：
  1. 独立 sales_logs 表，支持关键字搜索 + 日期筛选
  2. AI 智能审阅 — 调用大模型对日志内容进行质量评分和建议
  3. 数据同时作为 AI 复盘报告的原始素材
  4. 多公司业务标签（v0.2.0 新增）：involved_company_ids (ARRAY UUID) — 一篇日志可关联1~N个公司，切换公司视角时通过 ARRAY.any() 包含过滤，GIN 索引加速

模块 9：Dashboard 工作台

• 功能：首页 KPI 总览 + 快捷操作入口 + 公司切换
• 核心亮点：
  1. 四大 KPI 卡片：本月订单数 / 待出库发货 / 库存预警 SKU / 本月营收 — 后端 GET /api/dashboard/stats 聚合查询实时计算
  2. 快捷按钮一键跳转至订单、发货、库存、日志页面
  3. 顶部公司切换下拉 — 支持在不同公司视角间即时切换

---

四、AI 中枢模块

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

• 架构：前端 → 后端 SSE → Dify Workflow → Ollama 3090 (27B)
• 流程：
  1. 前端选择时间范围，后端查询 sales_logs 并序列化（按 involved_company_ids 过滤当前公司）
  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 读超时
• 多租户感知（v0.2.0）：generate_report 端点注入 company_id 依赖，仅提取涉及当前公司的日志，防止跨公司分析幻觉

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 + company_id 三重拦截
迁移管理	Alembic async 模式，所有 DDL 变更必须通过版本化迁移脚本

数据库全表清单（24 张）

域	表名	用途	隔离方式
CRM	crm_customers	客户主表	全局共享
CRM	crm_contacts	客户联系人	全局共享
CRM	crm_follow_up_logs	跟进记录	全局共享
ERP	erp_product_categories	产品分类树	全局共享
ERP	erp_product_skus	产品 SKU	全局共享
ERP	erp_sku_inventory	库存快照（stock_qty + warning_threshold）	company_id
ERP	erp_inventory_flows	库存变动流水	company_id
ERP	erp_orders	订单主表	company_id
ERP	erp_order_items	订单明细行	— (随主表)
ERP	erp_shipping_records	发货单主表	company_id
ERP	erp_shipping_items	发货明细行	— (随主表)
财务	fin_invoice_pool	报销发票池	company_id
财务	fin_expense_records	报销单主表	company_id
财务	fin_expense_details	报销明细行	— (随主表)
财务	finance_sales_invoices	销项发票	company_id
协同	sales_logs	销售日志	involved_company_ids (ARRAY)
AI	ai_chat_sessions	AI 对话记录	—
AI	ai_report_drafts	AI 复盘报告草稿	—
系统	sys_users	系统用户	—
系统	sys_roles	角色权限	—
系统	sys_departments	部门组织	—
系统	sys_companies	公司/租户主表	—
系统	sys_user_companies	用户-公司多对多 (含 is_default)	—
系统	alembic_version	Alembic 迁移版本号	—

Alembic 迁移清单

序号	Revision	说明
1	03d8dcc2d72a	v0.1.0 baseline（19 张表）
2	a1b2c3d4e5f6	多租户隔离：新增 sys_companies / sys_user_companies，8 张表添加 company_id
3	b2c3d4e5f6a7	新增新宇润滑油公司 + 全员关联
4	c3d4e5f6a7b8	sales_logs.company_id → involved_company_ids (ARRAY UUID) + GIN 索引

---

六、API 接口全景（17 个路由模块）

模块	前缀	核心端点示例	多租户
auth	/api/auth	login, me, password, user-info (含公司列表)	—
customers	/api/customers	CRUD + 归档 + AI 画像 + 转移	共享
contacts	/api/contacts	客户联系人 CRUD	共享
companies	/api/companies	公司列表、用户关联公司查询	—
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 审阅 (company_ids 数组)	✅ ARRAY
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	—	鉴权依赖注入 + get_current_company_id	—

---

七、v0.1.0 → v0.2.0 变更日志

已完成增量（Phase 1.5 → 2.0）

项目	v0.1.0 状态	v0.2.0 状态
Alembic 迁移	❌ 手工 DDL	✅ 4 个版本化迁移脚本，async 模式
多租户	❌ 仅天津硕博霖	✅ 行级 company_id 隔离，IDOR 防护
公司切换	❌	✅ 登录页选择 + 首页下拉切换
新宇润滑油	❌	✅ 第二家公司，全员关联
客户转移	❌	✅ 管理员可跨人员重新分配
sales_logs 多公司	无 company 概念	✅ involved_company_ids ARRAY + GIN 索引
AI 复盘公司过滤	提取所有日志	✅ 仅提取涉及当前公司的日志
发票 OCR buyer 字段	❌ 映射缺失	✅ 修复 buyer/buyer_name/customer_name 链
发票批量交互	自动创建 + 5s 消失	✅ 待确认列表 + 字段标黄 + 一键创建
报销上传队列	3s 自动清空	✅ 手动关闭
Dashboard 库存预警	erp_product_skus.warning_threshold	✅ 修正为 erp_sku_inventory 表
数据库表数量	19 张	24 张（+5）
API 路由模块	16 个	17 个（+companies）

Phase 3 规划

优先级	方向	说明
P0	HTTPS	内网 CA 自签证书，保护 JWT Token 传输安全
P1	数据可视化	ECharts 接入 Dashboard — 月度趋势折线图、报销占比饼图
P1	操作审计日志	记录关键操作（删除、审批、密码重置）的完整审计轨迹
P1	文件存储优化	对接 MinIO / 阿里云 OSS，替代本地 uploads 目录
P1	通知公告模块	实现系统内通知与公告发布功能
P2	移动端适配	响应式布局或微信小程序，支持外出销售人员使用
P2	外网访问	VPN / Cloudflare Tunnel 实现远程办公访问
P2	监控告警	Prometheus + Grafana 仪表板 + 钉钉/微信告警推送
P2	AI 复盘页修复	排查 SSE 流 / 前端组件加载问题

---

八、关键架构决策记录 (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	库存变更仅允许流水模式	杜绝直接篡改库存，确保账实一致 + 审计可追溯
ADR-007	行级多租户而非 Schema 隔离	公司数量有限（2~5 家），行级隔离实现简单，共享表无需冗余
ADR-008	sales_logs 使用 ARRAY UUID 而非单 company_id	CRM 日志需保持"以客户为中心"完整性，一篇日志可能涉及多个公司业务
ADR-009	Alembic async 模式 + env.py 地址替换	Docker 内 .env 用 host.docker.internal，Alembic 在宿主机执行时自动替换为 127.0.0.1
ADR-010	X-Company-Id Header + IDOR 校验	比 Cookie/Session 更适配 SPA 前后端分离，校验 sys_user_companies 防止伪造

---

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