hzhub/docs/architecture

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-company	公司门户前端	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 服务接口

@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