4d8bc95063
1. 为ScriptRecommend组件新增customerId参数，支持从父组件传入客户ID 2. 添加动态获取最后一条学员消息的逻辑，从后端API拉取会话历史 3. 为ArchiveMessageEvent类添加Jackson忽略未知属性注解 4. 新增部署文档和项目说明文档AGENTS.md、CLAUDE.md
121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# 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
|