agent_9art/CLAUDE.md

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)

# 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

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

# 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