hzhub/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

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)

# Start all services
cd hzhub-deploy
docker-compose up -d

# View service status
docker-compose ps

# View logs
docker-compose logs -f hzhub-ai
docker-compose logs -f hzhub-system

# Restart services
docker-compose restart hzhub-ai

# Stop all services
docker-compose down

Backend Development (Spring Boot)

# 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 system service locally (foreground)
cd hzhub-system
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Run ERP service locally (foreground)
cd hzhub-erp
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Run tests
mvn test

Important: hzhub-system depends on hzhub-ai's common modules. Always run mvn clean install -DskipTests in hzhub-ai first.

Frontend Development (Vue 3)

# Admin portal (Vben Admin + Ant Design Vue)
cd hzhub-admin
pnpm install
pnpm dev                    # Port 5666

# Employee portal (Element Plus)
cd hzhub-portal-employee
pnpm install
pnpm dev                    # Port 5137

# Dealer portal (Element Plus)
cd hzhub-portal-dealer
pnpm install
pnpm dev                    # Port 5138

Architecture

Multi-Service Structure

┌─────────────────────────────────────────┐
│           Frontend Layer                 │
│  hzhub-admin | hzhub-portal-employee    │
│              | hzhub-portal-dealer       │
└────────────┬────────────────────────────┘
             │
    ┌────────┴────────┐
    │  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
    └──────┘  └─────────────┘

Gateway Routes

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

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 (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-portal-employee (Element Plus):

• Vue 3 + TypeScript + Element Plus
• Features: dashboard, approval center, CRM, dealer management, supply chain, BI reports, AI chat, ERP

hzhub-portal-dealer (Element Plus):

• Vue 3 + TypeScript + Element Plus
• Features: AI chat interface only

Key Technologies

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:

• Vue 3 with Composition API
• Vben Admin framework (admin portal)
• Element Plus + element-plus-x (portal UI)
• Pinia for state management
• UnoCSS for atomic CSS

Infrastructure:

• MySQL 8.0 (business data)
• Redis 7 (cache, session, rate limiting)
• Weaviate 1.25.0 (vector database)
• n8n (workflow automation)
• MinIO (object storage)

Important Patterns

Backend API Structure

Controllers follow REST conventions:

@RestController
@RequestMapping("/chat")
public class ChatController {
    @PostMapping("/message")
    public R<ChatResponse> sendMessage(@RequestBody ChatRequest request) {
        // Response wrapper: R<T>
    }
}

Response wrapper R<T> from hzhub-common-core provides standardized API responses.

Multi-tenancy & Authentication

• Sa-Token handles JWT authentication
• Client ID header required: ClientID (passed in frontend requests)
• Token auto-injected via Authorization: Bearer <token>
• 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

hzhub-common-mybatis uses dynamic-datasource-spring-boot-starter:

spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:  # MySQL for business data
        erp:     # SQL Server (planned)

Switch datasource in code: @Ds("erp") annotation on service methods.

SSE Streaming

AI chat uses Server-Sent Events for streaming responses:

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestParam String message) {
    // Returns SSE stream
}

Frontend uses hook-fetch with sseTextDecoderPlugin to handle SSE.

Configuration Profiles

Backend uses Spring profiles:

• application.yml - Base configuration
• application-dev.yml - Development
• application-prod.yml - Production

Profile set via SPRING_PROFILES_ACTIVE env var or spring.profiles.active property.

Development Workflow

Service Dependencies

When running locally, backend services need infrastructure:

• MySQL (localhost:3306)
• Redis (localhost:6379)
• Weaviate (localhost:28080)

Start infrastructure via Docker Compose first:

cd hzhub-deploy
docker-compose up -d mysql redis weaviate

Environment Variables

Backend:

• SPRING_DATASOURCE_DYNAMIC_DATASOURCE_MASTER_URL: MySQL connection URL
• 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=http://localhost:8080 (Gateway URL)
• VITE_CLIENT_ID: Client identifier for auth
• VITE_WEB_TITLE: Page title

Testing

Backend tests use Spring Boot test framework:

@SpringBootTest
class ChatServiceTest {
    @Test
    void testSendMessage() { ... }
}

Deployment

Docker Image Building

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
• Served via Nginx

Service Ports

Service	Port	Access
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
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. 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 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")

Adding Frontend Features

For admin portal:

1. Add API call in apps/web-antd/src/api/
2. Create view in apps/web-antd/src/views/
3. Add route in apps/web-antd/src/router/
4. Add menu configuration

For portals (employee/dealer):

1. Add API module in src/api/ with index.ts and types.ts
2. Create page in src/pages/
3. Define route in src/routers/modules/
4. Add store if needed in src/stores/

Working with Weaviate

Weaviate is used for knowledge retrieval (RAG). Collection creation and querying handled by LangChain4j integration in hzhub-common-chat.

Notes

• Package naming: org.hzhub.* (renamed from org.ruoyi.*)
• 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)
• Build order: hzhub-ai → hzhub-system → hzhub-erp (hzhub-system depends on hzhub-ai common modules)