LMS Maritime - Sổ tay học code và bảo vệ

1. Học Nhanh Trong 5 Phút

Đây là hệ thống LMS phục vụ đào tạo hàng hải. Hệ thống có bốn vai trò chính: ADMIN, ORG_ADMIN, TEACHER và STUDENT. Frontend viết bằng Angular, backend viết bằng Spring Boot, dữ liệu lưu trong PostgreSQL.

Thông tin cần nhớ

2. Cách Chạy Local

Cách khuyến nghị là chạy PostgreSQL và backend bằng Docker, còn frontend chạy local bằng Node để sửa UI nhanh hơn.

2.1. Kiểm tra trước khi chạy

git status --short --branch
docker --version
node -v
npm -v
java -version

2.2. Chạy backend và database bằng Docker

cd E:\Sach\Sua\LMS_hohulili
Copy-Item .env.dev.example .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d db backend

2.3. Kiểm tra backend đã chạy

curl.exe -s http://localhost:8088/actuator/health
curl.exe -s "http://localhost:8088/api/v3/courses?page=0&size=1"

Kết quả health mong muốn:

{"status":"UP"}

2.4. Chạy frontend

cd E:\Sach\Sua\LMS_hohulili\fe
npm install
npm start

Mở trình duyệt tại:

http://localhost:4200

2.5. Chạy toàn bộ stack bằng Docker

Cách này phù hợp khi cần môi trường gần production hơn, nhưng sửa UI sẽ chậm hơn.

cd E:\Sach\Sua\LMS_hohulili
Copy-Item .env.dev.example .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build --wait

2.6. Tắt local stack

cd E:\Sach\Sua\LMS_hohulili
docker compose -f docker-compose.yml -f docker-compose.dev.yml down

3. Khi Thầy Bảo Sửa Code Ngay

Khi thầy yêu cầu sửa một lỗi nhỏ trong lúc báo cáo, cần làm theo quy trình gọn: xác định màn hình, tìm đúng file, sửa đúng phạm vi, build/test, rồi refresh browser.

3.1. Quy trình an toàn

1. Ghi lại URL, màn hình và hành động gây lỗi.
2. Chạy git status --short --branch để biết repo có file đang sửa không.
3. Tìm route, component hoặc controller liên quan bằng rg.
4. Sửa ít nhất có thể, không refactor lớn trong lúc demo.
5. Chạy test hoặc build đúng phạm vi.
6. Refresh browser và nói rõ bằng chứng đã kiểm chứng.

3.2. Lệnh tìm code nhanh

cd E:\Sach\Sua\LMS_hohulili
rg "teacher/courses" fe/src/app
rg "CourseEditor" fe/src/app/features/teacher
rg "@GetMapping|@PostMapping|@PutMapping|@PatchMapping" backend/src/main/java/com/example/lms
rg "api/v3/courses|teacher/courses|video-assets" backend/src/main/java/com/example/lms fe/src/app

3.3. Nếu sửa frontend

cd E:\Sach\Sua\LMS_hohulili\fe
npm run build

Các file hay dùng khi sửa UI:

3.4. Nếu sửa backend

cd E:\Sach\Sua\LMS_hohulili\backend
mvn -DskipTests compile -B
mvn test -B

Các file hay dùng khi sửa backend:

3.5. Trước khi commit hoặc nộp PR

git status --short
git diff --stat
git diff
cd fe; npm run build
cd ..\backend; mvn -DskipTests compile -B

4. Kiến Trúc Tổng Quan

Hệ thống chia thành ba lớp lớn: frontend, backend, database/storage.

Backend modules

Frontend modules

5. Frontend Angular

Frontend dùng Angular 20.3, standalone component mặc định, Signals, inject(), @if/@for và ChangeDetectionStrategy.OnPush.

Route map quan trọng

Pattern component cần nắm

@Component({
  selector: 'app-example',
  imports: [CommonModule],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @if (isLoading()) {
      <p>Đang tải</p>
    } @else {
      @for (item of items(); track item.id) {
        <div>{{ item.name }}</div>
      }
    }
  `
})
export class ExampleComponent {
  private service = inject(MyService);
  items = signal<Item[]>([]);
  itemCount = computed(() => this.items().length);
}

6. Backend Clean Architecture / DDD

Backend không để controller thao tác trực tiếp với database. Controller gọi UseCase, UseCase dùng repository port, còn Infrastructure adapter mới nối với JPA.

Quy tắc vàng

Ví dụ câu trả lời

"Em tách domain model và JPA entity để domain không bị phụ thuộc framework. Nếu sau này đổi persistence, business rule vẫn nằm trong domain/use case. Infrastructure chỉ là lớp chuyển đổi và đọc ghi database."

7. Database

Database là PostgreSQL 16, migration bằng Flyway trong backend/src/main/resources/db/migration/. Các bảng chính gồm: schema hiện có 78 application tables và 2 materialized views theo catalog sinh từ migration.

Lệnh xem database local

docker compose -f docker-compose.yml -f docker-compose.dev.yml exec db psql -U lms -d lms
\dt
select count(*) from users;
select count(*) from courses;

Nếu dùng DBeaver local: host localhost, port 5432, database lms, user lms, password lms khi chạy dev compose mặc định.

8. Các Luồng Chính Cần Thuộc

8.1. Đăng nhập và phân quyền

8.2. Teacher tạo khóa học

8.3. Admin duyệt khóa học

8.4. Student học bài

8.5. Quiz và assignment

9. Upload, Video, Offline

9.1. Upload tài liệu, ảnh, video

Upload hiện đại không đẩy file lớn qua backend trực tiếp. Hệ thống dùng presigned upload:

9.2. Video adaptive

Video nội bộ dùng Cloudflare R2 private + Shaka Packager để tạo HLS/DASH. Production có dedicated video worker để ingest video, tránh để web backend bị nghẽn.

9.3. Offline/PWA

Offline là dữ liệu cục bộ trên từng thiết bị. Dữ liệu học offline nằm trong IndexedDB/Dexie, tiến độ sync theo hướng cộng dồn và tiến lên, không ghi đè lùi tiến độ trên server.

File nên đọc:

• fe/src/app/core/db/lms-offline.db.ts
• fe/src/app/core/services/course-download.service.ts
• fe/src/app/core/services/offline-sync.service.ts
• fe/src/app/api/interceptors/offline.interceptor.ts

10. Bảo Mật Và Phân Quyền

Bảo mật chính gồm JWT, route guards, backend method security, CORS/CSP, rate limiting và tách role theo quyền.

Files quan trọng

• backend/src/main/java/com/example/lms/config/SecurityConfig.java
• backend/src/main/java/com/example/lms/config/JwtAuthenticationFilter.java
• fe/src/app/core/guards/role.guard.ts
• fe/src/app/api/interceptors/auth.interceptor.ts

11. Debug Nhanh

Backend không lên

docker compose -f docker-compose.yml -f docker-compose.dev.yml logs backend --tail=100
docker compose -f docker-compose.yml -f docker-compose.dev.yml ps

• Not a managed type: JPA repository đang trỏ tới domain model thay vì *JpaEntity.
• DB connection fail: kiểm tra container db có healthy không.
• R2/access key fail ở dev: kiểm tra config dev và biến môi trường dev.

Frontend không gọi được API

curl.exe -s http://localhost:8088/actuator/health
rg "apiUrl|baseUrl|localhost:8088" fe/src/environments fe/src/app

Port bị chiếm

netstat -ano | findstr :4200
netstat -ano | findstr :8088

Build frontend lỗi

cd E:\Sach\Sua\LMS_hohulili\fe
npm run build

Test backend quá chậm

cd E:\Sach\Sua\LMS_hohulili\backend
mvn -DskipTests compile -B

Khi sửa logic quan trọng, cần chạy test liên quan hoặc full mvn test -B.

12. Mở Code Để Sửa Khi Cần

Cách học dự án nhanh nhất là mở theo luồng người dùng, không mở ngẫu nhiên từng file. Khi thầy chỉ một màn hình bất kỳ, hãy truy ngược theo chuỗi: route → component → service/store → API endpoint → controller → use case → repository → migration/database.

12.1. Mở project bằng VS Code

cd E:\Sach\Sua\LMS_hohulili
code .

Nên mở 3 terminal trong VS Code:

12.2. Mở backend bằng IntelliJ IDEA

Backend là Maven project. Có thể mở thẳng thư mục backend/ bằng IntelliJ để IDE nhận Java 21, Spring Boot, Maven dependency và test runner. Nếu mở bằng VS Code vẫn được, nhưng IntelliJ dễ đọc luồng Controller → UseCase → Repository hơn.

cd E:\Sach\Sua\LMS_hohulili\backend
mvn -DskipTests compile -B

12.3. Mở database bằng DBeaver

DBeaver phù hợp để xem sơ đồ tổng, bảng, khóa ngoại và dữ liệu mẫu. Với local Docker, kết nối thường là:

12.4. Cách tìm đúng file trong Angular

cd E:\Sach\Sua\LMS_hohulili
rg "path: 'curriculum'|course-editor|teacher-dashboard" fe/src/app
rg "updateCourseInfo|submitForApproval|getCourseDraft" fe/src/app/features/teacher
rg "#0056D2|--c-primary|--c-accent|bg-\[" fe/src

Các màn teacher/course editor quan trọng nằm ở:

• fe/src/app/features/teacher/teacher.routes.ts: route lớn của teacher.
• fe/src/app/features/teacher/course-editor/course-editor.routes.ts: route con info, curriculum, competency, settings, classes.
• fe/src/app/features/teacher/course-editor/store/course-editor.store.ts: state, cache, readiness checklist, optimistic UI.
• fe/src/app/features/teacher/course-editor/services/course-authoring.service.ts: DTO và các API gọi backend.

12.5. Cách tìm đúng file trong backend

rg "@RequestMapping|@GetMapping|@PostMapping|@PutMapping|@PatchMapping|@DeleteMapping" backend/src/main/java/com/example/lms
rg "submitForApproval|createCourse|updateCourse" backend/src/main/java/com/example/lms/course_authoring
rg "video-assets|adaptive|playback" backend/src/main/java/com/example/lms/learning_delivery

Backend đi theo Clean Architecture/DDD. Nếu sửa nghiệp vụ, ưu tiên sửa ở application/usecase hoặc domain/model. Controller chỉ nhận request, kiểm quyền, validate nhẹ và gọi use case.

13. Kịch Bản Sửa Code Hay Gặp

13.1. Đổi màu hoặc giao diện

13.2. Đổi logic frontend

Ví dụ thầy yêu cầu: "đổi điều kiện cho phép publish course". Cách lần:

1. Tìm chữ đang hiển thị hoặc action button trong template: rg "publish|submitForApproval|Gửi duyệt" fe/src/app.
2. Mở component hoặc store liên quan, thường là CourseEditorStore hoặc page trong course-editor/pages/.
3. Nếu logic là state UI, sửa signal/computed trong frontend.
4. Nếu logic là nghiệp vụ thật, sửa backend use case để không bị bypass bằng API.
5. Chạy cd fe && npm run build; nếu có backend đổi thì chạy thêm cd backend && mvn -DskipTests compile -B.

13.3. Đổi logic backend

Ví dụ thầy yêu cầu: "khóa học trả phí phải có giá lớn hơn 0". Luồng sửa đúng:

Nếu chỉ đổi rule, thường sửa ở application/usecase hoặc domain/model. Nếu thêm cột/bảng, tạo migration mới trong backend/src/main/resources/db/migration/, ví dụ V136__add_course_field.sql. Không dựa vào ddl-auto để production tự sinh schema.

13.4. Thêm trường mới vào Course

13.5. Sửa tiếng Việt và i18n/ARB

Dự án hiện là Angular, không dùng file .arb kiểu Flutter. Phần lớn chữ tiếng Việt đang nằm trực tiếp trong template/component, route title, toast message và backend response message. Khi cần sửa chữ:

rg "Từ cần sửa|Không thể|Gửi duyệt|Khóa học" fe/src backend/src

Nếu sau này muốn i18n chuẩn, nên thiết kế riêng bằng Angular i18n hoặc JSON translation files. Không tự thêm lẻ tẻ một hệ ARB vào giữa dự án khi chưa có quyết định kiến trúc.

13.6. Wiii/Pointy và metadata DOM an toàn

LMS đã có các target như data-wiii-id, data-wiii-click-safe, data-wiii-click-kind ở teacher dashboard, course creation, course editor sidebar, section editor và preview dialog. Chỉ gắn data-wiii-click-safe="true" cho thao tác điều hướng, mở panel hoặc form step an toàn. Không gắn safe cho submit quiz, delete, publish, enroll, grade, payment.

rg "data-wiii-id|data-wiii-click-safe|data-wiii-click-kind" fe/src/app/features/teacher fe/src/app/features/ai-chat

14. Shaka, ABR, Media Và Upload

14.1. Phân biệt ARB và ABR

Nếu hỏi về ARB theo nghĩa file dịch ngôn ngữ thì dự án hiện không dùng ARB. Nếu hỏi về ABR, đó là Adaptive Bitrate: trình phát tự đổi chất lượng video theo băng thông và tình trạng buffer.

14.2. Frontend Shaka Player nằm ở đâu?

14.3. Các dòng ABR quan trọng

rg "abr:|defaultBandwidthEstimate|switchInterval|selectQuality|resolveAdaptivePlayUrl" fe/src/app/features/learning/components/adaptive-video-player

14.4. Backend đóng gói video bằng Shaka như thế nào?

14.5. Muốn đổi chất lượng encode hoặc profile

Có hai lớp cần phân biệt:

• Profile tạo file: chỉnh VIDEO_ADAPTIVE_PROFILES, VIDEO_OFFLINE_PROFILES, VIDEO_ADAPTIVE_SEGMENT_DURATION_SECONDS, VIDEO_FFMPEG_PRESET.
• Hành vi phát trên trình duyệt: chỉnh ABR trong adaptive-video-player.component.ts.

rg "VIDEO_ADAPTIVE_PROFILES|VIDEO_OFFLINE_PROFILES|VIDEO_FFMPEG_PRESET|adaptive-segment" backend docker-compose*.yml docs

14.6. Smoke test video local

1. Chạy backend và frontend local.
2. Đăng nhập teacher, upload video vào lesson hoặc section.
3. Kiểm tra asset có trạng thái xử lý xong.
4. Đăng nhập student, mở bài học có video.
5. Mở DevTools Network, kiểm tra có request master.m3u8 hoặc manifest.mpd.
6. Thử menu chất lượng: Tự động, 360p, 720p nếu có.

15. Kiểm Thử Trước Khi Nộp Hoặc Báo Cáo

15.1. Baseline nhanh

cd E:\Sach\Sua\LMS_hohulili\fe
npm run build

cd E:\Sach\Sua\LMS_hohulili\backend
mvn -DskipTests compile -B

cd E:\Sach\Sua\LMS_hohulili
docker compose -f docker-compose.yml -f docker-compose.dev.yml config -q
curl.exe -s http://localhost:8088/actuator/health

15.2. Khi sửa frontend

• Chạy cd fe && npm run build.
• Mở http://localhost:4200, đăng nhập đúng role và bấm flow vừa sửa.
• Nếu sửa PWA/offline/video/payment, cân nhắc chạy cd fe && npm run test:e2e:smoke.

15.3. Khi sửa backend

• Chạy cd backend && mvn -DskipTests compile -B trước để bắt lỗi compile.
• Nếu sửa use case hoặc rule, chạy test liên quan bằng Maven.
• Nếu sửa schema, chạy lại Docker DB local từ trạng thái sạch hoặc kiểm Flyway migration.

15.4. Checklist trước khi nói "done"

16. Câu Hỏi Bảo Vệ Thường Gặp

Vì sao tách frontend và backend?

Để UI và business API độc lập. Frontend Angular tối ưu trải nghiệm người dùng, backend Spring Boot đảm nhận security, transaction và nghiệp vụ.

Vì sao dùng Clean Architecture/DDD?

Vì hệ thống LMS có nhiều nghiệp vụ: course, learning, assessment, payment, video. Tách domain/use case/infrastructure giúp code dễ bảo trì, dễ test, và tránh việc controller hoặc JPA bị trộn với business rule.

Vì sao dùng publication snapshot?

Teacher có thể sửa bản nháp mà không ảnh hưởng học viên đang học. Học viên đọc nội dung đã công bố/approved, còn bản nháp mới chỉ ra ngoài sau khi submit và admin duyệt.

Vì sao upload file qua presigned URL?

File lớn không nên đi qua backend web request. Presigned upload cho phép browser upload trực tiếp lên storage, backend chỉ quản lý session, quyền truy cập và metadata.

Vì sao video có worker riêng?

Encode/packaging video tốn CPU và thời gian. Tách dedicated video worker giúp backend web vẫn phục vụ user ổn định khi có nhiều video đang ingest.

Nếu thầy hỏi "em đóng góp phần nào?"

Hãy trả lời theo module/luồng mình nắm chắc. Ví dụ: "Em nắm luồng teacher tạo khóa học, student học bài, upload/video, và cách backend DDD xử lý từ controller đến database."

17. Lịch Học Tới Ngày 20