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 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.

Commands

Docker Deployment (Production-like)

# Start all services (recommended for integration testing)
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-admin

# Restart services
docker-compose restart hzhub-ai

# Stop all services
docker-compose down

Backend Development (Spring Boot)

# Run AI service locally (foreground)
cd hzhub-ai
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

# Build all modules
cd hzhub-ai
mvn clean package

# Build specific module
cd hzhub-ai/hzhub-modules/hzhub-chat
mvn clean package

# Run tests
mvn test

💡 Tip: For background service management, see SERVICE_MANAGEMENT.md

Frontend Development (Vue 3 + Vben Admin)

# Admin portal development
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

# Employee portal development
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

# Dealer portal development
cd hzhub-portal-dealer
pnpm install
pnpm dev

💡 Tip: For background service management (start/stop/restart/status/logs), see SERVICE_MANAGEMENT.md

Architecture

Multi-Service Structure

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

Backend Module Organization

hzhub-ai is organized as a multi-module Maven project:

• 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)

Frontend Architecture

hzhub-admin uses a monorepo structure with pnpm + turbo:

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

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

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)
• MyBatis-Plus for database access
• Dynamic datasource for multi-database support
• 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)
• Weaviate 1.25.0 (vector database)
• n8n (workflow automation)
• MinIO (object storage)

Important Patterns

Backend API Structure

Controllers in hzhub-modules/*/controller/ 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>
• User permissions checked via Sa-Token's permission system

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
• SPING_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

Frontend (in .env.development):

• VITE_API_URL: Backend API base URL (default: http://localhost:6039)
• 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() { ... }
}

Frontend uses Vitest for unit tests:

cd hzhub-admin
pnpm test:unit

Deployment

Docker Image Building

Backend Dockerfile in hzhub-ai/Dockerfile:

• Builds from Maven source
• Runs on port 6039

Frontend Dockerfiles in each portal directory:

• Builds with pnpm
• Served via Nginx

Service Ports

Service	Port	Access
hzhub-admin (frontend)	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

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
4. Create controller, service, mapper following existing patterns

Adding a New API Endpoint

1. Create controller in module's controller/ package
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)