# CLAUDE.md

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

## Project Overview

九艺AI坐席辅助系统 — A real-time script recommendation system for course consultants/sales reps at 9artedu.com. It captures WeCom (企业微信) conversations, analyzes intent, builds customer profiles, and recommends sales scripts to agents via a sidebar H5 interface.

## Architecture

The system uses a microservices architecture with 10 backend services, all sharing a `common` module. An API Gateway routes requests by path prefix to individual services.

```
nginx (port 80)
  → gateway (port 8080) — Spring Cloud Gateway, routes by /api/v1/*
    → auth-service         (8081) — WeCom OAuth, JWT, JS-SDK signing
    → archive-service      (8082) — WeCom archive C SDK via JNA, RSA decrypt, callbacks
    → conversation-service (8083) — Session management, context windows (Redis List)
    → intent-service       (8084) — Intent recognition (40 scenarios), customer profiles
    → recommendation-svc   (8085) — 3-layer recall, multi-factor ranking, MMR reranking
    → generation-service   (8086) — Tongyi Qianwen (DashScope) API, prompt engine
    → kb-admin-service     (8087) — Script CRUD, category management, import/export
    → analytics-service    (8088) — Statistics, script effectiveness analysis
  → admin frontend (port 5174) — React + Ant Design (script library management, dashboards)
  → sidebar frontend (port 5173) — React + Ant Design Mobile (agent-facing H5 sidebar)
```

### Key Design Patterns

- **Unified API response**: All services use `Result<T>` from `common` module (`code: 0` = success, `code: -1` = failure, with `message` and `timestamp`)
- **Pagination**: `PageResult<T>` for list responses
- **Database**: MyBatis-Plus with logical delete (`deleted` field: 0/1), auto-fill handler for timestamps
- **Config**: All services use environment variables for infra hosts (`MYSQL_HOST`, `REDIS_HOST`, `RABBITMQ_HOST`), allowing local dev with `localhost` and containerized with service names
- **Data pipeline**: WeCom callback → archive-service → RabbitMQ → conversation-service → intent-service → recommendation-service → WebSocket push to sidebar

## Development Commands

### Backend (Java 8 / Spring Boot 2.7.18)

```bash
# Build all services from backend/
cd backend && mvn clean package -DskipTests

# Run a single service locally (e.g., conversation-service)
cd backend/conversation-service && mvn spring-boot:run

# Run a specific test
cd backend/conversation-service && mvn test -Dtest=ConversationControllerTest

# Run all tests
cd backend && mvn test
```

### Frontend

```bash
# Sidebar (agent-facing H5)
cd frontend/sidebar && npm install && npm run dev

# Admin dashboard
cd frontend/admin && npm install && npm run dev

# Build for production
cd frontend/sidebar && npm run build
cd frontend/admin && npm run build
```

### Docker (full stack)

```bash
# Start all services
docker compose up -d

# Start only infrastructure (MySQL, Redis, RabbitMQ)
docker compose up -d mysql redis rabbitmq

# View logs for a service
docker compose logs -f conversation-service

# Rebuild and restart a specific service
docker compose up -d --build recommendation-service
```

### Database

- `init.sql` — Full schema (15+ tables) + seed data. Loaded into MySQL on first `docker compose up`.
- `backend/utterances_cg.sql` — CG training script seed data
- `add_utterances.sql` — Additional utterance data

## Service Ports Reference

| Service | Port |
|---------|------|
| Gateway | 8080 |
| Auth | 8081 |
| Archive | 8082 |
| Conversation | 8083 |
| Intent | 8084 |
| Recommendation | 8085 |
| Generation | 8086 |
| KB Admin | 8087 |
| Analytics | 8088 |
| Admin Frontend | 5174 |
| Sidebar Frontend | 5173 |
| Nginx (unified entry) | 80 |

## Tech Stack

- **Backend**: Spring Boot 2.7.18, Spring Cloud 2021.0.8, MyBatis-Plus 3.5.5, Java 8
- **Infra**: MySQL 5.7, Redis 6.x, RabbitMQ 3.x
- **Frontend**: React 18, TypeScript, Vite 5, Ant Design 5 / Ant Design Mobile 5
- **LLM**: DashScope (Tongyi Qianwen qwen-turbo/qwen-plus)
- **Auth**: JWT (jjwt 0.11.5), WeCom OAuth2
- **Deployment**: Docker + Docker Compose, Nginx

## Important Constraints

- **MySQL 5.7**: No native JSON functions beyond basics, no vector types. Vectors are stored in Redis.
- **Java 8**: All services compile to Java 1.8 (not the Dockerfile's Temurin 17 JRE, which is forward-compatible)
- **No Spring Cloud Discovery**: Services use static gateway routing, not Eureka/Consul