AI_Team/hzhub
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat: 添加ERP服务和系统服务，完善员工门户功能

Browse Source 
## 新增服务模块

### 1. ERP服务 (hzhub-erp)
- 新增独立的ERP数据适配服务
- 支持SQL Server 2008 R2数据源
- 提供动态API配置管理系统
- 包含客户管理、销售数据等业务接口

### 2. 系统服务 (hzhub-system)
- 新增独立的系统管理服务
- 用户、角色、权限、部门、菜单管理
- 租户管理、操作日志、在线用户监控
- 工作流引擎（warm-flow）集成
- 企业微信审批同步功能

### 3. API网关 (hzhub-gateway)
- 新增Spring Cloud Gateway网关服务
- JWT认证、路由分发、限流熔断
- XSS防护、请求日志记录
- 统一入口端口8080

## 后台管理功能增强

### ERP动态API管理
- 新增动态API配置管理界面
- API测试、文档预览、统计监控
- 错误日志查看、缓存管理
- 从数据库表自动导入API配置

### 系统管理增强
- 企业微信配置管理
- 企业微信审批同步配置
- 部门和用户管理优化

## 员工门户功能完善

### 业务页面
- 审批中心：工作流审批、待办任务
- CRM管理：客户关系管理
- 经销商管理：经销商数据展示
- 供应链管理：采购、库存、销售
- BI报表：数据可视化分析
- ERP数据探索：SQL Server数据查询

### 个人中心
- 基本设置：个人信息管理
- 安全设置：密码修改、登录日志
- 锁屏功能：自动锁屏、手动锁屏

### 其他功能
- 标签页管理：多标签页导航
- 页面缓存：keepAlive缓存机制
- 会话超时：自动检测并提示

## 经销商门户

### 页面路由
- 新增经销商管理页面路由
- AI聊天界面完善

## 文档更新

- ERP API数据库初始化指南
- ERP API前端完整实现文档
- ERP API测试和验证指南
- Gateway路由迁移计划
- 项目配置文档更新

## 部署脚本

- 统一启动/停止/重启脚本
- Docker Compose配置优化
- Nginx配置文件更新

## 技术栈

- 后端: Spring Boot 3.5.8, Java 17
- 前端: Vue 3, TypeScript, Element Plus, Vben Admin
- 工作流: warm-flow 1.8.2
- 网关: Spring Cloud Gateway
- 数据库: MySQL 8.0, SQL Server 2008 R2
- 缓存: Redis 7
- 向量库: Weaviate 1.25.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
大壮
2026-05-08 08:00:19 +00:00
parent e6fc123b1f
commit c2513849b4
1564 changed files with 52903 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
CLAUDE.md
View File

@@ -4,14 +4,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
HZHub (汇智中台) is an enterprise-level business platform built on HZHub-AI, integrating AI capabilities with ERP data adaptation. It consists of multiple frontend portals, a backend AI service, an ERP service, and a gateway, orchestrated via Docker Compose.
HZHub (汇智中台) is an enterprise-level business platform integrating AI capabilities, system management, approval workflows, and ERP data adaptation. It consists of multiple frontend portals, backend microservices, and an API gateway, orchestrated via Docker Compose.
## Commands
### Docker Deployment (Production-like)
```bash
# Start all services (recommended for integration testing)
# Start all services
cd hzhub-deploy
docker-compose up -d
@@ -20,7 +20,7 @@ docker-compose ps
# View logs
docker-compose logs -f hzhub-ai
docker-compose logs -f hzhub-admin
docker-compose logs -f hzhub-system
# Restart services
docker-compose restart hzhub-ai
@@ -32,61 +32,47 @@ docker-compose down
### Backend Development (Spring Boot)
```bash
# Run AI service locally (foreground)
# Build hzhub-ai common modules first (required by hzhub-system)
cd hzhub-ai
mvn clean install -DskipTests
# Run AI service locally (foreground)
cd hzhub-ai/hzhub-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Run AI service locally (background)
cd hzhub-ai
./start.sh # Start service in background
./status.sh # Check service status
./logs.sh # View logs
./stop.sh # Stop service
./restart.sh # Restart service
# Run system service locally (foreground)
cd hzhub-system
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Build all modules
cd hzhub-ai
mvn clean package
# Build specific module
cd hzhub-ai/hzhub-modules/hzhub-chat
mvn clean package
# Run ERP service locally (foreground)
cd hzhub-erp
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Run tests
mvn test
```
**💡 Tip:** For background service management, see [SERVICE_MANAGEMENT.md](../SERVICE_MANAGEMENT.md)
**Important:** hzhub-system depends on hzhub-ai's common modules. Always run `mvn clean install -DskipTests` in hzhub-ai first.
### Frontend Development (Vue 3 + Vben Admin)
### Frontend Development (Vue 3)
```bash
# Admin portal development
# Admin portal (Vben Admin + Ant Design Vue)
cd hzhub-admin
pnpm install # Install dependencies
pnpm dev # Start dev server (foreground)
./start.sh # Start dev server (background)
./status.sh # Check service status
./logs.sh # View logs
pnpm build # Build all packages
pnpm --filter=@vben/web-antd build:prod # Build admin frontend
pnpm install
pnpm dev # Port 5666
# Employee portal development
# Employee portal (Element Plus)
cd hzhub-portal-employee
pnpm install
pnpm dev # Start dev server (foreground)
./start.sh # Start dev server (background)
./status.sh # Check service status
./logs.sh # View logs
pnpm dev # Port 5137
# Dealer portal development
# Dealer portal (Element Plus)
cd hzhub-portal-dealer
pnpm install
pnpm dev
pnpm dev # Port 5138
```
**💡 Tip:** For background service management (start/stop/restart/status/logs), see [SERVICE_MANAGEMENT.md](../SERVICE_MANAGEMENT.md)
## Architecture
### Multi-Service Structure
@@ -99,64 +85,79 @@ pnpm dev
└────────────┬────────────────────────────┘
│
┌────────┴────────┐
│ hzhub-gateway │ (API Gateway - planned)
│ Spring Cloud │ Auth, routing, rate limiting
└────────┬────────┘
│
┌────────┴────────┬────────────┐
│ hzhub-ai │ hzhub-erp │
│ (AI Service) │ (Planned) │
│ Spring Boot │ JDBC to │
│ 3.5.8 │ SQL Server│
└─────────────────┴────────────┘
│ hzhub-gateway │ (API Gateway, port 8080)
│ Spring Cloud │ JWT auth, routing, rate limiting, XSS
└───┬──────┬──────┘
│ │
┌───▼──┐ ┌▼────────────┐
│hzhub │ │ hzhub-system│ hzhub-erp
│ -ai │ │ (System Mgmt)│ (SQL Server)
│ 6039 │ │ 8083 │ 8082
└──────┘ └─────────────┘
```
### Backend Module Organization
### Gateway Routes
**hzhub-ai** is organized as a multi-module Maven project:
| Path Prefix | Target Service | Features |
|-------------|---------------|----------|
| `/ai/**` | hzhub-ai:6039 | AI chat, knowledge base, AI workflow |
| `/system/**` | hzhub-system:8083 | Users, roles, permissions, tenants, OSS |
| `/monitor/**` | hzhub-system:8083 | Operation logs, online users, cache |
| `/auth/**` | hzhub-system:8083 | Login, register, captcha, tenant list |
| `/resource/**` | hzhub-system:8083 | Email/SMS code, SSE, WebSocket |
| `/workflow/**` | hzhub-system:8083 | Approval workflows (warm-flow) |
| `/tool/**` | hzhub-system:8083 | Code generator (velocity) |
| `/erp/**` | hzhub-erp:8082 | ERP customer data |
- **hzhub-admin**: Main application entry point (`HZHubAIApplication.java`), configuration files
- **hzhub-common**: Shared utilities (core, redis, mybatis, security, satoken, oss, chat, etc.)
- **hzhub-modules**: Business modules
- **hzhub-chat**: Chat/AI conversation functionality
- **hzhub-system**: System management, users, roles, permissions
- **hzhub-workflow**: Workflow engine (Flowable-based)
- **hzhub-aiflow**: AI workflow orchestration
- **hzhub-generator**: Code generator
- **hzhub-extend**: Extensions (monitoring, job scheduling)
### Backend Service Organization
**hzhub-ai** (AI Service, port 6039):
- **hzhub-admin**: Main application entry point (`HZHubAIApplication.java`)
- **hzhub-common**: Shared utility modules (core, redis, mybatis, security, oss, chat, etc.)
- **hzhub-modules**:
- **hzhub-chat**: AI conversation, knowledge base, MCP
- **hzhub-aiflow**: AI workflow orchestration (LangGraph4j)
- **hzhub-extend**: Monitoring (spring-boot-admin), job scheduling
**hzhub-system** (System Service, port 8083):
- Independent Spring Boot service
- Depends on hzhub-ai common modules (must build hzhub-ai first)
- Entry point: `HZHubSystemApplication.java`
- **Auth**: login, register, captcha, tenant list (`/auth/**`, `/resource/**`)
- **System**: users, roles, menus, departments, dicts, config, posts, tenants, OSS, clients, social login (`/system/**`)
- **Monitor**: operation logs, online users, login logs, cache (`/monitor/**`)
- **Workflow**: approval process definitions, instances, tasks (`/workflow/**`)
- **Generator**: code generation from database tables (`/tool/gen`)
**hzhub-erp** (ERP Service, port 8082):
- SQL Server 2008 R2 data adapter
- Customer management, sales data exploration
### Frontend Architecture
**hzhub-admin** uses a monorepo structure with pnpm + turbo:
**hzhub-admin** (Vben Admin monorepo):
- Vue 3 + TypeScript + Ant Design Vue
- Pinia state management
- Features: system management, workflow, AI flow, knowledge base, chat, monitoring, code generator
```
hzhub-admin/
├── apps/
│ └── web-antd/ # Main admin application (Ant Design Vue)
│ ├── src/
│ │ ├── api/ # API calls
│ │ ├── views/ # Page components
│ │ ├── router/ # Vue Router config
│ │ └── store/ # Pinia stores
│ └── package.json
├── packages/ # Shared packages
└── package.json # Root monorepo config
```
**hzhub-portal-employee** (Element Plus):
- Vue 3 + TypeScript + Element Plus
- Features: dashboard, approval center, CRM, dealer management, supply chain, BI reports, AI chat, ERP
**Portal applications** (hzhub-portal-employee, hzhub-portal-dealer) are Vue 3 apps with:
- Composition API (`<script setup>`)
- Pinia state management with persistence
- Element Plus UI components
- hook-fetch for HTTP requests with SSE support
**hzhub-portal-dealer** (Element Plus):
- Vue 3 + TypeScript + Element Plus
- Features: AI chat interface only
### Key Technologies
**Backend (hzhub-ai)**:
- Spring Boot 3.5.8, Spring AI 2.0
- LangChain4j for AI/LLM integration
- Sa-Token for authentication (JWT-based)
**Backend**:
- Spring Boot 3.5.8, Java 17
- LangChain4j + LangGraph4j for AI/LLM integration
- Sa-Token for authentication (JWT-based, HmacSHA256)
- MyBatis-Plus for database access
- Dynamic datasource for multi-database support
- warm-flow 1.8.2 for approval workflows
- Velocity 2.3 for code generation templates
- Weaviate for vector database (knowledge retrieval)
**Frontend**:
@@ -168,7 +169,7 @@ hzhub-admin/
**Infrastructure**:
- MySQL 8.0 (business data)
- Redis 7 (cache, session)
- Redis 7 (cache, session, rate limiting)
- Weaviate 1.25.0 (vector database)
- n8n (workflow automation)
- MinIO (object storage)
@@ -177,7 +178,7 @@ hzhub-admin/
### Backend API Structure
Controllers in `hzhub-modules/*/controller/` follow REST conventions:
Controllers follow REST conventions:
```java
@RestController
@@ -197,7 +198,8 @@ Response wrapper `R<T>` from `hzhub-common-core` provides standardized API respo
- Sa-Token handles JWT authentication
- Client ID header required: `ClientID` (passed in frontend requests)
- Token auto-injected via `Authorization: Bearer <token>`
- User permissions checked via Sa-Token's permission system
- Gateway injects `X-User-Id`, `X-Client-Id`, `X-Gateway-Verified: true` headers
- Backend services trust `X-Gateway-Verified` header to skip redundant JWT validation
### Dynamic Datasource
@@ -256,13 +258,14 @@ docker-compose up -d mysql redis weaviate
**Backend**:
- `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_URL`: MySQL connection URL
- `SPING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_USERNAME`: DB username
- `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_USERNAME`: DB username
- `SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_PASSWORD`: DB password
- `SPRING_DATA_REDIS_HOST`: Redis host
- `SPRING_DATA_REDIS_PORT`: Redis port
- `JWT_SECRET`: Shared JWT secret (all services)
**Frontend** (in `.env.development`):
- `VITE_API_URL`: Backend API base URL (default: http://localhost:6039)
- `VITE_API_URL=http://localhost:8080` (Gateway URL)
- `VITE_CLIENT_ID`: Client identifier for auth
- `VITE_WEB_TITLE`: Page title
@@ -277,19 +280,15 @@ class ChatServiceTest {
}
```
Frontend uses Vitest for unit tests:
```bash
cd hzhub-admin
pnpm test:unit
```
## Deployment
### Docker Image Building
Backend Dockerfile in `hzhub-ai/Dockerfile`:
- Builds from Maven source
- Runs on port 6039
Backend Dockerfiles in each service directory:
- Multi-stage build (Maven → JRE)
- hzhub-ai: port 6039
- hzhub-system: port 8083
- hzhub-erp: port 8082
Frontend Dockerfiles in each portal directory:
- Builds with pnpm
@@ -299,27 +298,32 @@ Frontend Dockerfiles in each portal directory:
| Service | Port | Access |
|---------|------|--------|
| hzhub-admin (frontend) | 5666 | http://localhost:5666 |
| hzhub-gateway | 8080 | http://localhost:8080 (统一入口) |
| hzhub-ai | 6039 | http://localhost:6039 |
| hzhub-system | 8083 | http://localhost:8083 |
| hzhub-erp | 8082 | http://localhost:8082 |
| hzhub-admin | 5666 | http://localhost:5666 |
| hzhub-portal-employee | 5137 | http://localhost:5137 |
| hzhub-portal-dealer | 5138 | http://localhost:5138 |
| hzhub-ai (backend API) | 6039 | http://localhost:6039 |
| MySQL | 3306 | localhost:3306 |
| Redis | 6379 | localhost:6379 |
| Weaviate | 28080 | http://localhost:28080 |
| n8n | 5678 | http://localhost:5678 |
| MinIO | 9000/9001 | http://localhost:9000 (API), http://localhost:9001 (Console) |
## Common Tasks
### Adding a New Backend Module
1. Create module in `hzhub-ai/hzhub-modules/`
2. Add to parent `pom.xml` modules list
3. Include in `hzhub-admin` dependencies
1. Decide which service it belongs to (AI, system, or ERP)
2. For hzhub-ai: create module in `hzhub-ai/hzhub-modules/`, add to parent pom.xml
3. For hzhub-system: create package under `src/main/java/org/hzhub/`, add dependencies to pom.xml
4. Create controller, service, mapper following existing patterns
5. Add gateway route in `hzhub-gateway/src/main/resources/application.yml`
### Adding a New API Endpoint
1. Create controller in module's `controller/` package
1. Create controller in the appropriate service
2. Use `@RestController` and `@RequestMapping`
3. Return `R<T>` wrapper for responses
4. Add permission check if needed: `@SaCheckPermission("system:user:list")`
@@ -348,4 +352,5 @@ Weaviate is used for knowledge retrieval (RAG). Collection creation and querying
- **Java version**: JDK 17+
- **Node version**: Node 22+ with pnpm 10+
- **Code style**: ESLint `@antfu/eslint-config` for frontend; backend follows Spring conventions
- **Git hooks**: Lefthook configured (see `lefthook.yml`)
- **Git hooks**: Lefthook configured (see `lefthook.yml`)
- **Build order**: hzhub-ai → hzhub-system → hzhub-erp (hzhub-system depends on hzhub-ai common modules)