Files

T

hankin 423baff73b v0.1.0: CRM/ERP 系统内测版本 - 安全加固完成

- Docker bridge 网络隔离（8000 端口封死）
- Gunicorn 4 Worker 多进程
- Alembic 数据库迁移基线
- 日志轮转 20m×3
- JWT 密钥 + DB 密码 + CORS 收紧
- 3-2-1 备份链路（NAS + R740-B 冷备）
- 连接池 pool_pre_ping + pool_recycle=3600

2026-03-16 07:31:37 +00:00

13 KiB

Raw Blame History

润滑油 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 阶段性存档，随系统迭代持续更新。

13 KiB Raw Blame History Unescape Escape