# erpnext_datahub

**Repository Path**: fwr567/erpnext_datahub

## Basic Information

- **Project Name**: erpnext_datahub
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: version-16
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-06
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ERPNext DataHub

> 企业集成与数据平台（Enterprise Integration & Data Platform）
> 基于 Frappe / ERPNext v16 的**统一集成中枢**，让所有系统只对接一次。

[![Frappe](https://img.shields.io/badge/Frappe-v16-blue)]()
[![ERPNext](https://img.shields.io/badge/ERPNext-16.x-informational)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()

---

## 一、平台定位

传统企业里，N 个系统两两对接会产生 `N×(N-1)` 条接口，每加一个系统就要改动所有旧接口。
DataHub 把这张网收敛成一颗**星型中枢**：任何系统只与 DataHub 对接一次，接口数降为 `N`。

```
   MES ─┐                          ┌─ WMS
   PLM ─┤                          ├─ SRM
   CRM ─┼──►  ERPNext DataHub  ◄───┼─ 电商平台
   OA  ─┤     （统一集成中枢）      ├─ 财务系统
   IoT ─┘                          └─ BI / 数据仓库
```

### 五大职责

| # | 职责 | 说明 |
|---|------|------|
| ① | **Integration Hub** | 统一连接器框架，所有外部系统只接一次 |
| ② | **Master Data Hub (MDM)** | 主数据唯一真相源，黄金记录 + 跨系统 ID 映射 |
| ③ | **Event Hub** | 统一事件模型，发布/订阅解耦 |
| ④ | **API Gateway** | 对外统一出入口，鉴权 / 限流 / 审计 |
| ⑤ | **Data Governance** | 元数据、血缘、质量、审计全链路可追溯 |

---

## 二、十二大核心模块

| 模块 | 能力 | 关键 DocType |
|------|------|--------------|
| ① Connector Framework | 统一 SDK，12 种内置连接器类型 | DataHub Connector / Connector Type / Connector Endpoint |
| ② Master Data (MDM) | 黄金记录、匹配去重、ID 映射 | Golden Record / Master Domain / Match Rule / ID Mapping |
| ③ Mapping Engine | 两段式字段映射（源→标准→目标） | Mapping Profile / Field Map / Value Map |
| ④ Event Hub | 统一事件模型、订阅分发 | Event / Event Definition / Subscription |
| ⑤ Queue Center | 异步任务、重试、死信 | Queue Job / Dead Letter |
| ⑥ Transformation Engine | 值转换、脚本、公式 | Transform Rule / Value Map Item |
| ⑦ Synchronization Engine | 全量/增量/实时同步、冲突处理 | Sync Profile / Sync Run / Sync Record / Sync Conflict |
| ⑧ API Gateway | 资源路由、客户端鉴权、限流 | API Resource / API Client / API Request Log |
| ⑨ Workflow Integration | 与 erpnext_bpm 软集成的审批联动 | （复用 BPM，未装时自动放行） |
| ⑩ Monitor Center | 指标采集、健康巡检、告警 | Metric Snapshot / Alert Rule / Alert |
| ⑪ Audit Center | 全量操作留痕与数据血缘 | Audit Log |
| ⑫ AI Integration | 面向 AI 的统一数据入口与智能映射 | （`core/ai.py`，能力自描述 + 字段推荐） |

---

## 三、四条同步原则

### 1. 对象分四类，同步策略各不相同

| 分类 | 举例 | 同步方向 | 频率 |
|------|------|----------|------|
| **Master Data** 主数据 | 物料、客户、供应商、BOM | DataHub 单向下发 | 实时 / 准实时 |
| **Reference Data** 参考数据 | 单位、币种、国家、税率 | DataHub 单向下发 | 低频 |
| **Transaction Data** 业务数据 | 采购单、工单、发货单 | 业务系统 → DataHub | 实时 |
| **Analytics Data** 分析数据 | 汇总、KPI、报表 | DataHub → BI | 批量 |

### 2. 单向不循环

每个对象**只能有一个权威源系统（Source of Truth）**，其余系统均为消费方。
平台在 `DataHub Metadata Object` 上强制登记 `owner_system`，同步引擎据此阻断反向写入，杜绝 A→B→A 死循环。

### 3. 六种交互模式

`Publish` · `Subscribe` · `Request` · `Response` · `Webhook` · `Event`

### 4. 两个统一模型

- **统一同步模型**：所有同步都表达为 `Sync Profile`（源 → 映射 → 目标 → 调度 → 冲突策略）
- **统一事件模型**：全企业只有 8 种标准事件

  `ObjectCreated` `ObjectUpdated` `ObjectDeleted` `Released` `Approved` `Rejected` `Cancelled` `Closed`

---

## 四、三个企业级能力

### 1. Metadata Registry（元数据注册中心）

所有参与集成的业务对象必须先在 `DataHub Metadata Object` 登记：数据分类、权威系统、是否追踪变更、是否对 AI 开放、字段清单。
未登记的 DocType 不会产生任何事件开销 —— 这也是通配 `doc_events` 能做到近零成本的原因。

### 2. Canonical Data Model（标准数据模型）

平台内置 7 个标准模型种子：`Item` `BOM` `Customer` `Supplier` `PurchaseOrder` `WorkOrder` `Inventory`。

映射一律走**两段式**：

```
   源系统字段 ──[Source→Canonical]──► 标准模型 ──[Canonical→Target]──► 目标系统字段
```

新增第 N+1 个系统时，只需写 1 组映射（对标准模型），而不是 N 组。

### 3. Integration Studio（集成工作台）

可视化拓扑 + 一键建流向导 + 智能字段映射，页面路径 `/app/integration-studio`。

---

## 五、统一 Connector SDK

所有连接器继承 `BaseConnector`，实现同一套契约：

```python
from erpnext_datahub.connectors.base import BaseConnector

class MyConnector(BaseConnector):
    def connect(self):        ...   # 建立会话
    def test(self):           ...   # 连通性测试（页面「测试连接」按钮）
    def read(self, resource, filters=None, **kw):   ...   # 拉取
    def write(self, resource, payload, **kw):       ...   # 推送
    def delete(self, resource, key, **kw):          ...   # 删除
    def close(self):          ...   # 释放
```

内置 12 种连接器类型：

`REST` `ERPNEXT_REST` `WEBHOOK` `LOCAL` `NULL` `SOAP` `DATABASE` `CSV` `SFTP` `KAFKA` `RABBITMQ` `MQTT`

注册自定义连接器：在 `DataHub Connector Type` 新建一条记录，`handler_path` 填写你的类路径即可，无需改动平台代码。

---

## 六、安装

```bash
cd ~/frappe-bench
bench get-app https://gitee.com/fwr567/erpnext_datahub --branch version-16
bench --site <your-site> install-app erpnext_datahub
bench --site <your-site> migrate
bench build --app erpnext_datahub
bench restart
```

安装脚本（`install.py`）**幂等**，会自动完成：

- 创建 3 个角色：`DataHub Manager` / `DataHub Operator` / `DataHub Viewer`
- 注册 8 种标准事件定义
- 注册 12 种内置连接器类型
- 登记本地 ERPNext 系统 + `LOCAL` 连接器
- 创建 7 个标准数据模型种子
- 创建 5 条告警规则（默认停用）
- 初始化 `DataHub Settings`

---

## 七、快速上手

### 场景：把 ERPNext 的物料主数据下发给 MES

```
1. 系统登记    DataHub System        → 新建 "MES"
2. 建连接器    DataHub Connector     → 类型 REST，填 MES 的 base_url / 认证
3. 登记对象    DataHub Metadata Object → Item，分类 Master Data，权威系统 ERPNEXT，勾选「追踪变更」
4. 建映射      Integration Studio → 新建集成流 → 自动生成两段式映射（可用「智能字段映射」推荐）
5. 建同步方案  DataHub Sync Profile  → 源 ERPNEXT / 目标 MES / 增量 / 每 5 分钟
6. 观察        DataHub Monitor       → 看队列、成功率、告警
```

上面第 4-5 步可在 **Integration Studio** 里一键完成。

---

## 八、API 网关

### 两种调用入口

```bash
# 方法式
curl -X POST 'https://erp.example.com/api/method/erpnext_datahub.core.gateway.dispatch' \
     -H 'X-DataHub-Client: MES_CLIENT' \
     -H 'X-DataHub-Secret: ****' \
     -d 'resource=item&action=read&data={"filters":{"item_group":"Products"}}'

# 路径式
curl 'https://erp.example.com/dh/item?action=read&limit=20' \
     -H 'Authorization: Bearer <client_secret>'
```

### 支持的 action

`read` · `list` · `get` · `create` · `update` · `delete` · `submit` · `cancel` · `meta` · `schema` · `run` · `sync`

### 内置能力

- 客户端鉴权（Client ID / Secret，支持一键重置密钥）
- 资源级权限（`DataHub API Client Resource` 白名单）
- 方法级限制 + 速率限制（按分钟窗口）
- 全量请求日志 `DataHub API Request Log`
- 自动生成 OpenAPI 描述：`gateway.openapi_spec`
- 面向 AI 的工具清单：`gateway.ai_tools`

---

## 九、AI 集成

`core/ai.py` 让平台对 AI Agent 可自描述、可调用：

| 函数 | 用途 |
|------|------|
| `context()` | 返回平台能力总览 |
| `tools()` | 返回可调用工具清单（OpenAI function-calling 风格） |
| `describe_object(code)` | 描述某个业务对象的结构与语义 |
| `search(keyword)` | 跨所有「对 AI 开放」的对象做检索 |
| `call(resource, action, data)` | 经网关执行操作（同一套鉴权与审计） |
| `suggest_field_map(...)` | 基于名称/类型相似度推荐字段映射 |
| `apply_suggestions(...)` | 把推荐结果写入映射方案 |

字段映射推荐为**纯本地算法**（`difflib` 相似度 + 类型兼容度），不依赖任何外部大模型服务。

---

## 十、与 erpnext_bpm 的软集成

`core/bpm.py` 做了能力探测：

- **已安装 erpnext_bpm** → 高风险同步任务（如删除、跨系统主数据变更）自动发起审批，任务置为 `Awaiting Approval`，审批通过后回调 `on_approval_result` 重新入队
- **未安装** → `request_approval` 直接返回 `None`，任务照常执行

因此 DataHub **不强依赖** BPM，可独立部署。

---

## 十一、数据模型总览（38 个 DocType）

<details>
<summary>展开查看</summary>

**DataHub Core（7）**
`Settings` `System` `Metadata Object` `Metadata Field`(子) `Canonical Model` `Canonical Field`(子) `Audit Log`

**DataHub Connector（4）**
`Connector` `Connector Type` `Connector Endpoint`(子) `Connector Health Log`

**DataHub MDM（6）**
`Master Domain` `Domain Key Field`(子) `Golden Record` `ID Mapping` `Match Rule` `Match Field`(子)

**DataHub Mapping（5）**
`Mapping Profile` `Field Map`(子) `Transform Rule` `Value Map` `Value Map Item`(子)

**DataHub Event（5）**
`Event Definition` `Event` `Subscription` `Queue Job` `Dead Letter`

**DataHub Sync（4）**
`Sync Profile` `Sync Run` `Sync Record` `Sync Conflict`

**DataHub Gateway（4）**
`API Resource` `API Client` `API Client Resource`(子) `API Request Log`

**DataHub Monitor（3）**
`Alert Rule` `Alert` `Metric Snapshot`

</details>

---

## 十二、调度任务

| 频率 | 任务 |
|------|------|
| 每分钟 | `queue.process_queue` —— 推进队列 |
| 每 5 分钟 | `sync.run_scheduled` —— 执行到期同步方案 |
| 每小时 | `monitor.health_check_all` —— 连接器健康巡检 |
| 每小时（长） | `monitor.collect_metrics` —— 指标快照 |
| 每日（长） | `events.purge` / `queue.purge` / `audit.purge` / `monitor.purge_metrics` —— 数据保留清理 |

保留天数在 `DataHub Settings` 内配置。

---

## 十三、界面

| 入口 | 路径 |
|------|------|
| 工作区 | `/app/datahub` |
| 集成工作台 | `/app/integration-studio` |
| 监控中心 | `/app/datahub-monitor` |
| 平台设置 | `/app/datahub-settings` |

监控中心每 30 秒自动刷新，含 KPI 卡、队列趋势图、活动告警、连接器健康、失败热点 TOP、最近同步批次与事件。

---

## 十四、目录结构

```
erpnext_datahub/
├── connectors/          # ① 连接器框架
│   ├── base.py          #   BaseConnector 抽象基类
│   ├── registry.py      #   类型注册与实例化
│   ├── rest.py soap.py database.py file_conn.py messaging.py local.py
├── core/                # 核心引擎
│   ├── metadata.py      #   元数据注册中心
│   ├── mdm.py           #   ② 主数据中心
│   ├── mapping.py       #   ③ 映射引擎
│   ├── events.py        #   ④ 事件中心
│   ├── queue.py         #   ⑤ 队列中心
│   ├── transform.py     #   ⑥ 转换引擎
│   ├── sync.py          #   ⑦ 同步引擎
│   ├── gateway.py       #   ⑧ API 网关
│   ├── bpm.py           #   ⑨ 工作流集成
│   ├── monitor.py       #   ⑩ 监控中心
│   ├── audit.py         #   ⑪ 审计中心
│   └── ai.py            #   ⑫ AI 集成
├── datahub_*/           # 8 个模块，38 个 DocType + 页面
├── api.py               # Studio / Monitor 页面数据层
├── install.py           # 幂等初始化
├── hooks.py             # 事件挂载 / 调度 / 路由
└── www/dh.py            # /dh/<route> 网关入口
```

---

## 十五、许可

MIT License · Copyright (c) 2026 fwr567