# HZHub 架构设计文档

## 1. 系统概述

### 1.1 项目背景

HZHub（汇智中台）是基于 HZHub-AI 构建的企业级业务中台系统，旨在：
- 对内包装对接 ERP 系统
- 对外打通企业微信
- 提供 AI 能力赋能业务

### 1.2 核心目标

1. **业务中台系统建设**：三大门户（后台管理、公司门户、经销商门户）
2. **ERP 智能开发助手**：通过 AI 方式开发和维护 ERP 系统
3. **产品供应链管理优化**：智能库存、供应商绩效等

## 2. 系统架构

### 2.1 整体架构

```
前端层 → 网关层 → 服务层 → 数据层
```

### 2.2 服务划分

| 服务 | 职责 | 技术栈 |
|------|------|--------|
| hzhub-gateway | 统一入口、鉴权、路由 | Spring Cloud Gateway |
| hzhub-ai | AI 核心能力 | Spring Boot 4.0 + Spring AI 2.0 |
| hzhub-erp | ERP 数据适配 | Spring Boot 4.0 + JDBC |
| hzhub-admin | 管理后台前端 | Vue 3 |
| hzhub-portal-employee | 公司门户前端 | Vue 3 |
| hzhub-portal-dealer | 经销商门户前端 | Vue 3 |

### 2.3 数据存储

| 存储 | 用途 | 说明 |
|------|------|------|
| MySQL | 业务数据 | 用户信息、权限、配置 |
| Milvus | 向量数据 | 知识库文档向量、语义检索 |
| SQL Server 2008 R2 | ERP 数据 | 直连 ERP 数据库 |

## 3. 关键设计决策

### 3.1 ERP 服务独立部署

**决策**：ERP 服务独立为一个微服务

**理由**：
- 数据源完全隔离，避免双数据源复杂性
- SQL Server 2008 R2 驱动兼容性风险隔离
- 未来 ERP 升级或替换不影响 AI 服务

### 3.2 AI 能力以组件形式集成

**决策**：AI 用户端不独立部署，以组件形式嵌入两个门户

**理由**：
- 减少独立系统维护成本
- 用户体验更统一
- 权限管理更简单

### 3.3 企业微信多实体分别对接

**决策**：四个企业微信实体（集团/汇亚/恒福/玛缇）分别对接

**实现**：门户层通过 `corpId` 区分实体，共用一套代码

## 4. 接口契约（预留）

### 4.1 ERP 服务接口

```java
@RestController
@RequestMapping("/erp/v1")
public interface ErpApi {
    
    @PostMapping("/query")
    Result<PageResult> query(@RequestBody ErpQueryRequest request);
    
    @PostMapping("/execute")
    Result<Void> execute(@RequestBody ErpExecuteRequest request);
    
    @GetMapping("/schema/{tableName}")
    Result<TableSchema> getSchema(@PathVariable String tableName);
}
```

### 4.2 AI 服务接口

复用 hzhub-ai 提供的接口，通过网关暴露。

## 5. 部署架构

### 5.1 网络分区

| 服务 | 部署位置 | 访问方式 |
|------|---------|---------|
| 管理后台 | 内网 | 内网访问 |
| 公司门户 | 内网 | 内网 + 企业微信 H5 |
| 经销商门户 | 外网（DMZ） | 公网 + 企业微信 H5 |
| 网关/AI/ERP/n8n | 内网 | 网关统一入口 |

### 5.2 安全边界

- 外网入口：Nginx SSL + WAF + IP 白名单
- 网关层：JWT 鉴权 + 接口权限 + 限流
- 服务间：内网隔离，Feign 调用 + Token 传递

## 6. 技术风险

| 风险 | 影响 | 应对措施 |
|------|------|---------|
| SQL Server 2008 R2 驱动兼容性 | ERP 服务无法启动 | 预留双数据源，可切换 |
| Spring Boot 4.0 较新 | 第三方库适配问题 | 优先使用官方 starter |
| hzhub-ai 早期阶段 | API 可能变化 | 复制代码而非 fork，自主可控 |

## 7. 后续待办

1. ERP 数据架构专项调研
2. SQL Server JDBC 驱动兼容性验证
3. Milvus Docker 部署测试
4. 企业微信多实体对接方案细化

---

创建时间：2026-03-26