Charity Backend — Microservices

Overview

Dự án gồm nhiều microservice Spring Boot đặt sau Spring Cloud Gateway, đăng ký với Netflix Eureka. Client chỉ cần gọi một base URL (/api/v1/... trên cổng 8888); gateway định tuyến tới đúng service. Identity cấp token JWT (HS512); các resource server xác thực cùng khóa ký (SIGNER_KEY).

---

Technology stack

Lĩnh vực	Lựa chọn
Ngôn ngữ & runtime	Java 22, Maven
Nền tảng	Spring Boot 3.x, Spring Cloud (Gateway, Eureka, OpenFeign)
Bảo mật	OAuth2 Resource Server, JWT HS512 dùng chung qua SIGNER_KEY
Dữ liệu	Mặc định JPA/H2; có driver MySQL cho cấu hình production
Cache	Redis + Spring Cache — hồ sơ user, chi tiết campaign & organization, chi tiết product-auction (xem phần chi tiết service)
Messaging	RabbitMQ — đặt giá & kết thúc đấu giá sản phẩm
Tích hợp	PayOS (thanh toán), Cloudinary (upload file)
Triển khai	Docker / Docker Compose

---

Architecture diagram of the project

---

Microservices — vai trò và cổng

Service	Port	Vai trò
discovery-service	8761	Eureka — service registry
gateway-service	8888	Điểm vào duy nhất: route /api/v1/..., filter StripPrefix=2
identity-service	8080	Đăng ký, đăng nhập, refresh token; phát JWT (context /identity)
user-service	8081	Hồ sơ user; cache Redis userProfiles theo userId
payment-service	8082	Tích hợp PayOS (context /payment)
campaign-service	8083	Chiến dịch, tổ chức, bình luận; cache Redis cho API đọc chi tiết
file-service	8084	Upload ảnh (Cloudinary qua biến môi trường)
product-service	8085	Đấu giá sản phẩm, bid qua RabbitMQ; Redis cho trạng thái đấu giá + cache response
chatbot-service	8087	API chat HTTP (stub; xem mục Spring AI)

---

Chi tiết từng service

gateway-service

• Routes (tiền tố ${app.api-prefix} = /api/v1): identity, users / user-profiles, campaigns / organizations, product-auctions, payment, images, chat / chat-with-image.
• Filter: StripPrefix=2 bỏ hai segment api và v1 trước khi forward tới từng service.

identity-service

• API xác thực dưới /identity/... (ví dụ sau gateway: /api/v1/identity/auth/... → service /identity/auth/...).
• Dùng chung SIGNER_KEY với các resource server.

user-service

• Tạo hồ sơ mặc định qua Feign từ identity khi đăng ký.
• Cache: @Cacheable userProfiles cho getProfileByUserId; @CacheEvict khi cập nhật hồ sơ.

campaign-service

• Chiến dịch và tổ chức; GET công khai trên /campaigns/** và /organizations/**.
• Cache (Redis): campaigns theo id chiến dịch cho getCampaign; xóa cache khi update/delete campaign, tạo/xóa comment. organizations theo id tổ chức cho getOrganization; xóa cache khi admin update/delete. TTL mặc định 30 phút (cấu hình Spring Cache + Redis).

product-service

• Đấu giá, xử lý bid qua consumer RabbitMQ, PayOS qua Feign tới payment-service.
• Redis: cache trạng thái đấu giá (auction state) để validate bid; response cache productAuctions cho getAuction — xóa khi bid thành công, khi kích hoạt auction pending, hoặc khi finalize xong.

payment-service

• PayOS checkout / webhook (cấu hình env theo môi trường triển khai).

file-service

• Endpoint upload; thông tin Cloudinary qua biến môi trường.

chatbot-service

• Endpoint chat REST; hiện là stub, trả nội dung placeholder.

---

Gọi API qua Gateway

Client chỉ nên dùng base URL của gateway:

• Base: http://localhost:8888/api/v1
• Ví dụ:
  • POST .../identity/auth/token
  • GET .../campaigns?page=1&size=10
  • GET .../product-auctions?page=1&size=10
  • GET .../user-profiles/{userId}

Gọi thẳng cổng từng service chủ yếu để debug hoặc gọi nội bộ (ví dụ Eureka lb://).

---

Integrating the Spring AI Chatbot

Mặc định ChatServiceImpl trong chatbot-service là stub. Để tích hợp Spring AI:

1. Thêm Spring AI BOM và starter (ví dụ OpenAI) vào chatbot-service/pom.xml, khớp phiên bản Spring Boot của project.
2. Cấu hình API key / model id qua biến môi trường hoặc application.yml (ví dụ SPRING_AI_OPENAI_API_KEY).
3. Inject bean ChatClient (hoặc ChatModel) và gọi từ ChatServiceImpl thay cho stub; map ChatRequest.message() sang input model.
4. Tuỳ chọn: thêm conversation memory (JDBC, Redis, hoặc in-memory) nếu cần hội thoại nhiều lượt.
5. Build lại chatbot-service; gateway đã route /api/v1/chat và /api/v1/chat-with-image tới service này.

Không cần đổi gateway trừ khi thêm path mới.

---

Docker — cách chạy

Từ thư mục gốc repo:

docker compose build
docker compose up -d

Compose khởi chạy Redis, RabbitMQ, Eureka và các service có Dockerfile. Đặt SIGNER_KEY thống nhất cho identity, user, campaign, product (và mọi service dùng JWT tương tự).

• campaign-service, user-service, product-service cần REDIS_HOST (Compose gán redis).
• product-service cần RABBITMQ_HOST (trong Compose là rabbitmq).

Mặc định H2 in-memory sẽ mất dữ liệu khi container restart; với môi trường lâu dài có thể trỏ MySQL/Postgres trong application.yml.

---

Build (local)

Cần JDK 22 và Maven:

mvn -f campaign-service/pom.xml -DskipTests package

campaign-service chạy Spotless ở phase compile; build Docker có thể thêm -Dspotless.check.skip=true nếu cần.

---

Pagination

Các API danh sách dùng ApiResponse<PageResponse<T>> với tham số page (mặc định 1) và size (mặc định 10).