Troubleshooting
Trang này gom lỗi hay gặp từ AGENTS.md và runbook để search nhanh khi demo hoặc sửa code.
Backend
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
Not a managed type: class X |
JPA repository dùng domain model thay vì *JpaEntity |
Đổi JpaRepository<DomainModel, UUID> thành JpaRepository<XJpaEntity, UUID> và dùng adapter/mapper |
| Backend không start vì R2 key blank |
Dev config đang yêu cầu R2 thật |
Kiểm tra application-dev.yml, tắt/đổi storage dev theo config hiện hành |
| Flyway migration fail vì default/id |
Table cũ thiếu default gen_random_uuid()/now() |
Migration mới nên set default tạm, backfill, rồi drop default nếu cần |
| Production DB password failed |
Compose prod chạy thiếu --env-file .env.prod hoặc DB password lệch |
Dùng deploy.sh hoặc compose prod đúng env file |
| YAML indentation sai |
spring/server block lồng nhầm |
Validate application-prod.yml, giữ top-level rõ |
text[] type mismatch |
Hibernate validate PostgreSQL array |
Production dùng Flyway, không dựa vào ddl-auto validate/update cho schema |
Not a managed type
Lỗi Not a managed type gần như luôn là dấu hiệu repository JPA đang dùng nhầm domain model. Backend Clean Architecture của LMS yêu cầu:
JpaRepository<CourseJpaEntity, UUID>
Không dùng:
JpaRepository<Course, UUID>
Frontend/PWA
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
| API connection failed |
Backend chưa lên hoặc sai base URL |
Check http://localhost:8088/actuator/health, environment.ts |
| Service worker không install |
ngsw.json reference CSS chunk không còn |
Build script fe/scripts/fix-ngsw.js xử lý sau build |
| Offline app stale/trắng |
Service worker/cache/IndexedDB lỗi |
Mở /pwa-repair, /reset-sw, /clear-site-data |
| Text/button vỡ mobile |
CSS component chưa có responsive constraint |
Sửa component .scss/template, test desktop + mobile |
Font/encoding docs
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
| Browser hiển thị chữ Việt thành ký tự lạ |
File hoặc response bị mojibake/thiếu charset |
Kiểm <meta charset="utf-8">, search source bằng pattern mojibake, rebuild Jekyll |
| Browser hiển thị đúng nhưng PowerShell output bị ký tự lạ |
Console code page không hiển thị UTF-8 đúng |
Tin vào browser/source UTF-8; nếu cần chạy chcp 65001 hoặc dùng Node đọc file để kiểm |
| Chữ tiếng Việt nhìn mỏng/lệch |
Font stack không ưu tiên font Windows hỗ trợ tiếng Việt |
Docs site dùng Segoe UI, Noto Sans, Arial/system font trong custom Sass |
Course/content
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
| Learner không thấy bài/video mới |
Learner đọc course_publications, không đọc draft |
Submit for approval và approve để tạo publication mới |
| Class vẫn học version cũ |
Class đang pinned publication cũ |
Dùng publication version picker hoặc bulk adopt |
| Upload Word/PDF có preview pending |
Async document conversion đang chạy hoặc file lớn deferred |
Kiểm tra previewStatus, DocumentConversionService, storage |
| Video URL ngoài bị chặn |
Policy ép video mới đi qua asset pipeline nội bộ hoặc YouTube |
Upload internal video asset rồi gắn videoAssetId |
Payment
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
| Simulated checkout bị chặn |
Đang ở production profile |
Dùng VNPay/SePay thật hoặc dev profile |
| Student đã trả tiền nhưng chưa vào học |
Activation/enrollment đang pending hoặc instructor-led cần manual activation |
Kiểm tra payment history, enrollment, delivery mode |
| ORG_ADMIN không thấy giao dịch |
Query lọc theo organization/course teacher |
Kiểm tra organizationId của teacher/course |
Wiii
| Triệu chứng |
Nguyên nhân thường gặp |
Cách xử lý |
| Wiii iframe không nhận context |
iframe chưa connect hoặc origin sai |
Check environment.wiiiEmbedUrl, CSP/frame/connect, WiiiContextService.connectIframe |
| Pointy không click |
Target thiếu data-wiii-click-safe="true" hoặc disabled/hidden |
Chỉ thêm safe metadata cho navigation/open-panel an toàn |
| Wiii apply fail |
Thiếu preview_token/approval token hoặc kind không khớp |
Mở operator preview dialog, approve rồi apply |