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

```bash
# 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)

```bash
# 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](../SERVICE_MANAGEMENT.md)

### Frontend Development (Vue 3 + Vben Admin)

```bash
# 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](../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:

```java
@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`:

```yaml
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:

```java
@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:
```bash
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:
```java
@SpringBootTest
class ChatServiceTest {
    @Test
    void testSendMessage() { ... }
}
```

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

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