Trung tâm Xử lý Sự cố

Hướng dẫn này cung cấp giải pháp cho các vấn đề phổ biến nhất gặp phải trong quá trình phát triển và tích hợp nền tảng.

---

🛡️ Xác thực & SSO

1. Lỗi "401 Unauthorized" từ Satellite API

Triệu chứng: Giao diện satellite của bạn tải được, nhưng các cuộc gọi API thất bại với lỗi 401.

• Nguyên nhân A: VITE_SHELL_API_URL bị sai.
• Cách sửa: Kiểm tra ui/.env.development. Nó phải trỏ đến API của Shell (ví dụ: http://localhost:3000).
• Nguyên nhân B: Satellite API không thể kết nối tới JWKS của Shell.
• Cách sửa: Kiểm tra api/.env. Đảm bảo APP_ENV_SHELL_JWKS_URL có thể truy cập được từ terminal của satellite.

2. UserMenu hiển thị chữ "U" thay vì Tên/Email

Triệu chứng: Thanh tiêu đề của Shell hiển thị biểu tượng "U" mặc định.

• Nguyên nhân: Cơ chế fallback của UserProvider bị thất bại.
• Cách sửa: Đảm bảo tệp token-broadcast.ts của bạn có hàm getUserFromShellJwt() để giải mã token trực tiếp từ localStorage['token'].

---

🧩 Module Federation

3. Màn hình trắng trong Shell (Không có lỗi)

Triệu chứng: Khi điều hướng đến app của bạn, không gian làm việc hiển thị trống trơn.

• Nguyên nhân: URL remoteEntry.js bị sai trong DB của Shell.
• Cách sửa: Sử dụng CLI veni register một lần nữa hoặc kiểm tra bảng apps trong cơ sở dữ liệu Shell.

4. Lỗi "Cannot read properties of null (reading 'useState')"

Triệu chứng: Ứng dụng chỉ bị crash khi được tải bên trong Shell.

• Nguyên nhân: Xung đột phiên bản React hoặc vấn đề "Double React".
• Cách sửa: Đảm bảo vite.config.ts của bạn có shared: {} cho React. Không sử dụng singleton: true, import: false trừ khi bạn khớp chính xác bản build của Shell.

---

📦 Hạ tầng & Docker

5. Lỗi "Relation 'xxx' does not exist"

Triệu chứng: Các truy vấn cơ sở dữ liệu thất bại sau khi khởi động app.

• Nguyên nhân: Chưa chạy migration.
• Cách sửa: Chạy bun run db:migrate trong thư mục api/ của bạn.

6. Container liên tục khởi động lại (CrashLoopBackOff)

Triệu chứng: docker ps cho thấy container đang dừng hoặc đang khởi động lại.

• Nguyên nhân: Thiếu biến môi trường.
• Cách sửa: Kiểm tra log bằng lệnh docker-compose logs <tên-service>. Tìm các lỗi xác thực Zod.

---

📡 Mạng & Điều hướng

7. Lỗi CORS trong trình duyệt

Triệu chứng: Trình duyệt chặn các yêu cầu từ UI đến API.

• Cách sửa: Shell API và các Satellite API phải cho phép origin của Shell. Đảm bảo VITE_SHELL_URL được cấu hình chính xác trong môi trường của bạn.

8. Lỗi 404 với tệp remoteEntry.js

Triệu chứng: Tab network hiển thị lỗi 404 cho tệp entry của federation.

• Cách sửa: Đảm bảo bản build UI của bạn có base: '/' và publicPath: '/' trong vite.config.ts.

---

Vẫn gặp khó khăn?

Nếu bạn không tìm thấy giải pháp ở đây, hãy mở Gemini CLI hoặc Claude Code và dán thông báo lỗi chính xác. AI có thể phân tích nhật ký (logs) cụ thể của bạn.