Customersupport

SupportHub

为印度市场构建的多租户、人工智能原生客户支持平台。提供食品配送（第一阶段），作为白标B2B2C SaaS扩展到时尚、电子和杂货。

______________________________________________________________________

目录

1. 项目概述
2. 主要特点
3. 建筑
4. 仓库结构
5. 技术栈
6. 本地设置
7. 开发命令
8. 生产设置
9. CI/CD管道
10. 环境变量

______________________________________________________________________

1.工程概况

SupportHub暴露了四个表面区域：

主要用户： 终端客户、客户服务代理、运营管理员、人工智能聊天机器人代理（通过MCP）。

______________________________________________________________________

2.主要特点

• 票证生命周期 --创建、分配、状态机（打开→ 进行中→ 解决→ 关闭）、重新打开、升级
• AI情绪分析 --人类学Claude Haiku实时对每张票的情绪进行分类（支持英语、印地语、印度式英语、泰米尔语、泰卢固语等）
• AI分辨率建议 --Claude Sonnet使用RAG对常见问题+分辨率模板中的前3个可能分辨率进行排名
• 语义FAQ搜索 --pg向量余弦相似度+Elasticsearch BM25混合搜索
• MCP服务器 --暴露 create_ticket, get_ticket, list_tickets, search_faq 用于任何MCP兼容AI代理的SSE工具
• 多租户技术 --通过以下方式实现完全数据隔离 tenant_id +每个表上的PostgreSQL行级安全
• 实时 --STOMP over WebSocket用于代理仪表板上的实时工单更新
• 通知 -短信（MSG91），WhatsApp（Meta Business API），电子邮件（SendGrid），应用内
• 文件附件 --MinIO/AWS S3，带有15分钟预处理URL
• CQRS报告 --Kafka消费者将票证事件投影到Elasticsearch读取模型中

______________________________________________________________________

3.建筑

系统上下文

  [Customer]          [Agent]           [Admin]         [AI Chatbot]
      │                  │                  │                │
      └──────────────────┴──────────────────┴────────────────┘
                                  │ HTTPS / WSS
                        ┌─────────▼──────────┐
                        │   API Gateway :8080 │  ← JWT auth, tenant routing,
                        │  Spring Cloud GW    │    rate limiting, circuit breaker
                        └─────────┬──────────┘
                ┌─────────────────┼─────────────────────┐
                │                 │                       │
        ┌───────▼──────┐  ┌───────▼──────┐   ┌──────────▼──────┐
        │ auth   :8081 │  │ ticket :8082 │   │ customer :8083  │
        │ ai     :8084 │  │ notif  :8085 │   │ faq      :8086  │
        │ report :8087 │  │ tenant :8088 │   │ orders   :8089  │
        │ mcp    :8090 │  └──────────────┘   └─────────────────┘
        └──────────────┘
                │ Kafka (async events)
    ┌───────────┴──────────────────────────────────────────┐
    │  PostgreSQL  MongoDB  Redis  Elasticsearch  MinIO     │
    └──────────────────────────────────────────────────────┘

关键模式

Kafka事件流

ticket-service  ──► ticket.created         ──► ai-service (sentiment)
                                            ──► notification-service (customer notif)
                                            ──► reporting-service (ES projection)

ai-service      ──► sentiment.completed    ──► ticket-service (update fields)
                                            ──► reporting-service (ES update)

ticket-service  ──► ticket.status.changed  ──► notification-service
                                            ──► reporting-service

tenant-service  ──► tenant.onboarded       ──► notification-service (welcome comms)

______________________________________________________________________

4.存储库结构

supporthub/
├── run-local.sh                        ← single-command local runner
├── backend/                            ← Java 21 + Spring Boot 3.3 (Maven multi-module)
│   ├── pom.xml                         ← parent POM
│   ├── shared/                         ← shared DTOs, events, exceptions, security
│   ├── api-gateway/                    ← Spring Cloud Gateway — port 8080
│   ├── auth-service/                   ← OTP + agent login, JWT — port 8081
│   ├── ticket-service/                 ← ticket CRUD, SLA, WebSocket — port 8082
│   ├── customer-service/               ← customer profiles, addresses — port 8083
│   ├── ai-service/                     ← sentiment + resolution via Anthropic — port 8084
│   ├── notification-service/           ← SMS / WhatsApp / Email / in-app — port 8085
│   ├── faq-service/                    ← FAQ CRUD, pgvector search, Strapi sync — port 8086
│   ├── reporting-service/              ← Elasticsearch CQRS, CSV export — port 8087
│   ├── tenant-service/                 ← tenant onboarding, config — port 8088
│   ├── order-sync-service/             ← OMS proxy, Redis order cache — port 8089
│   └── mcp-server/                     ← Spring AI MCP tools over SSE — port 8090
│
├── frontend/                           ← npm workspaces (Node 20)
│   ├── apps/
│   │   ├── customer-portal/            ← React 18 + Vite — port 3000
│   │   ├── agent-dashboard/            ← React 18 + Vite — port 3001
│   │   └── admin-portal/               ← React 18 + Vite — port 3002
│   └── packages/
│       ├── customer-sdk/               ← headless TypeScript SDK (@supporthub/customer-sdk)
│       └── ui-components/              ← shared shadcn/ui + Tailwind component library
│
├── infrastructure/
│   ├── docker/
│   │   ├── docker-compose.yml          ← infra stack (Postgres, Mongo, Redis, Kafka, ES, MinIO, Strapi)
│   │   ├── docker-compose.services.yml ← all 11 services + 3 frontend apps
│   │   ├── .env.example                ← copy to .env and fill secrets
│   │   ├── nginx/spa.conf              ← nginx SPA config for frontend containers
│   │   ├── Dockerfile.template         ← multi-stage Java build template
│   │   └── init-db/                    ← PostgreSQL init scripts (pgvector extension)
│   ├── k8s/                            ← Kubernetes Kustomize manifests
│   └── terraform/                      ← AWS infrastructure (EKS, RDS, ElastiCache, MSK)
│
└── .github/workflows/
    ├── ci.yml                          ← PR validation (test, lint, build, OWASP scan)
    ├── deploy-staging.yml
    └── deploy-prod.yml

后端服务布局（每项服务）

{service}/src/main/java/in/supporthub/{service}/
├── {Service}Application.java
├── config/          ← Spring configs (Security, Kafka, Redis, etc.)
├── controller/      ← REST controllers (validate + delegate only)
├── service/         ← Business logic (@Transactional)
├── repository/      ← Spring Data interfaces (data access only)
├── domain/          ← JPA entities, enums (no service deps)
├── dto/             ← Java Records (request/response/event)
├── event/           ← Kafka producers + consumers
└── exception/       ← Typed exceptions extending AppException

______________________________________________________________________

5.技术栈

后端

前端

数据存储

基础设施

______________________________________________________________________

6.本地设置

先决条件

一个命令启动

git clone 
cd supporthub

# First run: copies .env.example → infrastructure/docker/.env
# Builds all JARs + frontend, starts every service
./run-local.sh

就是这样。脚本按顺序处理所有内容：

1. 检查先决条件
2. 副本 .env.example → infrastructure/docker/.env 首次运行
3. 构建所有11个Spring Boot JAR(./mvnw clean package -DskipTests)
4. 构建所有3个前端应用程序(npm run build --workspaces)
5. 启动基础架构堆栈（Postgres、Mongo、Redis、Kafka、Elasticsearch、MinIO、Strapi）
6. 等待每个infracontainer通过其健康检查
7. 启动所有11个微服务+3个nginx服务的前端应用程序
8. 对每项服务进行投票 /actuator/health 直到健康
9. 打印访问URL表

有用的标志

./run-local.sh --skip-build    # restart without rebuilding (fast after first run)
./run-local.sh --infra-only    # start only Postgres/Mongo/Redis/Kafka/ES/MinIO
./run-local.sh --down          # stop and remove all containers

访问URL（启动后）

首次配置

设置您的Anthropic API键 （AI功能需要）：

# Edit the generated .env file
nano infrastructure/docker/.env

# Set this line:
ANTHROPIC_API_KEY=sk-ant-your-real-key-here

在设置密钥之前，AI功能（情绪分析、解决方案建议）将显示“分析待定”。所有其他票务操作都可以在没有它的情况下工作。

创建租户 （购票前必须填写）：

curl -X POST http://localhost:8080/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Store","slug":"demo","planType":"TRIAL"}'

在本地运行服务（不使用Docker）

使用 --infra-only 只启动后备存储，然后本机运行服务：

./run-local.sh --infra-only

# Backend (from /backend)
./mvnw spring-boot:run -pl auth-service   -Dspring.profiles.active=dev
./mvnw spring-boot:run -pl ticket-service -Dspring.profiles.active=dev
# ... repeat per service

# Frontend (from /frontend)
npm run dev -w apps/customer-portal   # http://localhost:3000
npm run dev -w apps/agent-dashboard   # http://localhost:3001
npm run dev -w apps/admin-portal      # http://localhost:3002

______________________________________________________________________

7.开发命令

后端

cd backend

./mvnw clean package -DskipTests                            # build all services
./mvnw clean package -pl ticket-service -DskipTests         # build one service
./mvnw test -pl ticket-service                              # unit tests
./mvnw verify -pl ticket-service                            # integration tests (needs Docker)
./mvnw test -pl ticket-service -Dtest=TicketServiceTest     # single test class
./mvnw checkstyle:check spotbugs:check pmd:check -P analysis # static analysis
./mvnw dependency-check:check -pl ticket-service            # OWASP CVE scan

前端

cd frontend

npm ci                                      # install all workspace dependencies
npm run build --workspaces                  # build all apps + packages
npm run test --workspaces                   # run all Vitest tests
npm run lint --workspaces                   # ESLint all packages
npm run typecheck --workspaces              # TypeScript strict check

npm run dev -w apps/customer-portal         # dev server on :3000
npm run dev -w apps/agent-dashboard         # dev server on :3001
npm run dev -w apps/admin-portal            # dev server on :3002

E2E测试（剧作家）

# Requires all services running (./run-local.sh first)
cd frontend
npx playwright test
npx playwright test --ui                    # interactive UI mode

Docker编写（手册）

# Infrastructure only
docker compose -f infrastructure/docker/docker-compose.yml \
  --env-file infrastructure/docker/.env up -d

# All services + frontend
docker compose -f infrastructure/docker/docker-compose.services.yml \
  --env-file infrastructure/docker/.env up -d

# View logs
docker logs -f supporthub-api-gateway
docker logs -f supporthub-ticket-service

# Stop everything
docker compose -f infrastructure/docker/docker-compose.services.yml down
docker compose -f infrastructure/docker/docker-compose.yml down

______________________________________________________________________

8.生产设置

基础设施配置（Terraform）

cd infrastructure/terraform

# Initialise
terraform init

# Plan (review changes before applying)
terraform plan -var-file=environments/prod.tfvars

# Apply
terraform apply -var-file=environments/prod.tfvars

地形规定：EKS集群、RDS PostgreSQL Multi-AZ、ElastiCache Redis、MSK Kafka、OpenSearch、S3 bucket、ECR存储库、VPC、ALB、IAM角色。

容器图像

通过CI/CD构建并推送到ECR（在合并到ECR时触发 main).要手动构建，请执行以下操作：

# Authenticate to ECR
aws ecr get-login-password --region ap-south-1 | \
  docker login --username AWS --password-stdin .dkr.ecr.ap-south-1.amazonaws.com

# Build a service image
docker build \
  -f infrastructure/docker/Dockerfile.template \
  --build-arg SERVICE=ticket-service \
  -t .dkr.ecr.ap-south-1.amazonaws.com/supporthub/ticket-service:v1.0.0 \
  backend/

docker push .dkr.ecr.ap-south-1.amazonaws.com/supporthub/ticket-service:v1.0.0

Kubernetes部署

# Apply base manifests
kubectl apply -k infrastructure/k8s/base/

# Apply environment overlay
kubectl apply -k infrastructure/k8s/overlays/prod/

# Verify rollout
kubectl rollout status deployment/ticket-service -n supporthub
kubectl get pods -n supporthub

展开命令

始终遵循以下顺序以避免迁移/依赖失败：

1. Infrastructure (RDS, Redis, Kafka, ES) — must be healthy
2. DB migrations  — Flyway runs automatically on service startup
3. tenant-service — must be up before any authenticated requests
4. auth-service   — must be up before api-gateway validates JWTs
5. Core services  — ticket, customer, faq, notification, reporting (parallel)
6. ai-service     — can be delayed; ticket ops work without it
7. mcp-server     — can be delayed; chatbot integrations work without it
8. api-gateway    — last; routes to all services above
9. Frontend apps  — after gateway is healthy

秘密管理

所有秘密都存储在 AWS Secrets Manager服务在启动时通过以下方式加载它们 spring-cloud-aws-secrets-manager切勿将秘密储存于 application.yml 或Kubernetes清单。

每个服务所需的秘密（例如 ticket-service):

/supporthub/prod/ticket-service/db-password
/supporthub/prod/ticket-service/redis-password
/supporthub/prod/shared/jwt-public-key

健康检查

每项服务都暴露 /actuator/health （弹簧防尘套执行器）。Kubernetes活性和就绪性探测器配置在 infrastructure/k8s/base/{service}/deployment.yaml.

# Check gateway health
curl http://localhost:8080/actuator/health

# Check all pods
kubectl get pods -n supporthub

# Tail logs for a service
kubectl logs -f deployment/ticket-service -n supporthub

生产环境变量

与开发默认值不同的关键变量：

______________________________________________________________________

9.CI/CD管道

每次pull请求 develop 或 main 并行运行整个管道：

PR / Push
    │
    ├── backend-unit-tests          (./mvnw test)
    │       │
    │       └── backend-integration-tests  (./mvnw verify, Testcontainers)
    │
    ├── backend-security-scan       (OWASP Dependency Check — fails on CVSS ≥ 8)
    ├── backend-code-analysis       (Checkstyle + SpotBugs + PMD)
    │
    └── frontend-build-test         (typecheck + lint + vitest + build)
            │
            └── build-images        (Docker build → ECR push, on develop/tags only)
                    │
                    └── deploy-staging   (Kubernetes rolling update)
                            │
                            └── deploy-prod  (manual approval gate)

工作流文件： .github/workflows/ci.yml, deploy-staging.yml, deploy-prod.yml

______________________________________________________________________

10.环境变量

完整参考资料见 infrastructure/docker/.env.example.关键变量：

# ── PostgreSQL ──────────────────────────────────────
POSTGRES_USER=supporthub
POSTGRES_PASSWORD=supporthub_dev_password
DB_URL=jdbc:postgresql://localhost:5432/supporthub

# ── MongoDB ─────────────────────────────────────────
MONGODB_URI=mongodb://supporthub:supporthub_dev_password@localhost:27017/supporthub?authSource=admin

# ── Redis ───────────────────────────────────────────
REDIS_HOST=localhost
REDIS_PASSWORD=supporthub_dev_password

# ── Kafka ───────────────────────────────────────────
KAFKA_SERVERS=localhost:9092

# ── Elasticsearch ───────────────────────────────────
ELASTICSEARCH_URI=http://localhost:9200

# ── MinIO / S3 ──────────────────────────────────────
AWS_S3_ENDPOINT=http://localhost:9000     # remove in prod (uses real S3)
AWS_S3_BUCKET=supporthub-dev
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin

# ── AI (required for sentiment + resolution) ────────
ANTHROPIC_API_KEY=sk-ant-REPLACE_ME
ANTHROPIC_SENTIMENT_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_RESOLUTION_MODEL=claude-sonnet-4-5

# ── Notifications (optional in dev) ─────────────────
MSG91_API_KEY=
SENDGRID_API_KEY=
WHATSAPP_ACCESS_TOKEN=

# ── Observability (optional) ────────────────────────
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

运行前复制和编辑：

cp infrastructure/docker/.env.example infrastructure/docker/.env