AGENTS.md

1# AGENTS.md
2 
3## Giới Thiệu Dự Án
4 
5Đây là kho tài liệu giáo dục dành cho việc giảng dạy các kiến thức cơ bản về phát triển web cho người mới bắt đầu. Chương trình học là một khóa học toàn diện kéo dài 12 tuần được phát triển bởi Microsoft Cloud Advocates, bao gồm 24 bài học thực hành về JavaScript, CSS và HTML.
6 
7### Thành Phần Chính
8 
9- **Nội dung giáo dục**: 24 bài học có cấu trúc, tổ chức thành các mô-đun dự án
10- **Dự án thực hành**: Terrarium, Trò chơi gõ chữ, Tiện ích mở rộng trình duyệt, Trò chơi không gian, Ứng dụng ngân hàng, Trình soạn thảo mã, và Trợ lý trò chuyện AI
11- **Bài kiểm tra tương tác**: 48 bài kiểm tra với 3 câu hỏi mỗi bài (đánh giá trước/sau bài học)
12- **Hỗ trợ đa ngôn ngữ**: Dịch tự động sang hơn 50 ngôn ngữ qua GitHub Actions
13- **Công nghệ**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (cho các dự án AI)
14 
15### Kiến Trúc
16 
17- Kho tài liệu giáo dục theo cấu trúc dựa trên bài học
18- Mỗi thư mục bài học chứa README, ví dụ mã và giải pháp
19- Các dự án độc lập trong các thư mục riêng (quiz-app, các dự án bài học khác)
20- Hệ thống dịch thuật sử dụng GitHub Actions (co-op-translator)
21- Tài liệu được phục vụ qua Docsify và có sẵn dưới dạng PDF
22 
23## Các Lệnh Thiết Lập
24 
25Kho này chủ yếu dùng để truy cập nội dung giáo dục. Để làm việc với các dự án cụ thể:
26 
27### Thiết Lập Kho Chính
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Thiết Lập Ứng Dụng Quiz (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Khởi động máy chủ phát triển
40npm run build      # Xây dựng cho sản xuất
41npm run lint       # Chạy ESLint
42```
43 
44### API Dự Án Ngân Hàng (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Khởi động máy chủ API
50npm run lint       # Chạy ESLint
51npm run format     # Định dạng với Prettier
52```
53 
54### Các Dự Án Tiện Ích Mở Rộng Trình Duyệt
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Làm theo hướng dẫn tải tiện ích mở rộng theo trình duyệt cụ thể
60```
61 
62### Các Dự Án Trò Chơi Không Gian
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Mở index.html trong trình duyệt hoặc sử dụng Live Server
68```
69 
70### Dự Án Trò Chuyện (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Đặt biến môi trường GITHUB_TOKEN
76python api.py
77```
78 
79## Quy Trình Phát Triển
80 
81### Dành Cho Người Đóng Góp Nội Dung
82 
831. **Fork kho** về tài khoản GitHub của bạn
842. **Clone bản fork** về máy cục bộ
853. **Tạo nhánh mới** để thực hiện thay đổi
864. Thay đổi nội dung bài học hoặc ví dụ mã
875. Kiểm thử các thay đổi mã trong thư mục dự án liên quan
886. Gửi pull request theo hướng dẫn đóng góp
89 
90### Dành Cho Người Học
91 
921. Fork hoặc clone kho về
932. Di chuyển tuần tự đến các thư mục bài học
943. Đọc các file README cho mỗi bài học
954. Hoàn thành bài kiểm tra trước bài học tại https://ff-quizzes.netlify.app/web/
965. Làm các ví dụ mã trong thư mục bài học
976. Hoàn thành các bài tập và thử thách
987. Tham gia bài kiểm tra sau bài học
99 
100### Phát Triển Trực Tiếp
101 
102- **Tài liệu**: Chạy `docsify serve` ở thư mục gốc (cổng 3000)
103- **Ứng dụng Quiz**: Chạy `npm run dev` trong thư mục quiz-app
104- **Dự án**: Dùng tiện ích VS Code Live Server cho các dự án HTML
105- **Dự án API**: Chạy `npm start` trong các thư mục API tương ứng
106 
107## Hướng Dẫn Kiểm Thử
108 
109### Kiểm Thử Ứng Dụng Quiz
110 
111```bash
112cd quiz-app
113npm run lint       # Kiểm tra các vấn đề về phong cách mã
114npm run build      # Xác minh xây dựng thành công
115```
116 
117### Kiểm Thử API Ngân Hàng
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Kiểm tra các vấn đề về phong cách mã
122node server.js     # Xác minh máy chủ khởi động không có lỗi
123```
124 
125### Phương Pháp Kiểm Thử Chung
126 
127- Kho giáo dục này không có các bài kiểm thử tự động đầy đủ
128- Kiểm thử thủ công tập trung vào:
129  - Ví dụ mã chạy không lỗi
130  - Các liên kết trong tài liệu hoạt động chính xác
131  - Các dự án build thành công
132  - Ví dụ theo đúng thực tiễn tốt nhất
133 
134### Kiểm Tra Trước Khi Gửi
135 
136- Chạy `npm run lint` trong các thư mục có package.json
137- Xác minh các liên kết markdown hợp lệ
138- Kiểm thử các ví dụ mã trong trình duyệt hoặc Node.js
139- Kiểm tra dịch thuật duy trì cấu trúc chính xác
140 
141## Hướng Dẫn Phong Cách Mã
142 
143### JavaScript
144 
145- Dùng cú pháp ES6+ hiện đại
146- Tuân thủ cấu hình ESLint tiêu chuẩn trong các dự án
147- Đặt tên biến và hàm rõ nghĩa, dễ hiểu cho học viên
148- Thêm chú thích giải thích khái niệm cho người học
149- Định dạng mã bằng Prettier nếu được cấu hình
150 
151### HTML/CSS
152 
153- Các thành phần HTML5 có ngữ nghĩa
154- Nguyên tắc thiết kế đáp ứng (responsive)
155- Quy ước đặt tên class rõ ràng
156- Chú thích kỹ thuật CSS giải thích cho học viên
157 
158### Python
159 
160- Tuân thủ hướng dẫn phong cách PEP 8
161- Ví dụ mã rõ ràng, phù hợp giáo dục
162- Thêm chỉ dẫn kiểu (type hints) nếu giúp người học
163 
164### Tài Liệu Markdown
165 
166- Cấp độ tiêu đề rõ ràng
167- Khối mã khai báo ngôn ngữ lập trình
168- Liên kết nguồn tài liệu bổ sung
169- Ảnh chụp màn hình và hình ảnh trong thư mục `images/`
170- Văn bản thay thế (alt text) cho hình ảnh để tăng khả năng tiếp cận
171 
172### Tổ Chức Tệp
173 
174- Bài học đánh số tuần tự (1-getting-started-lessons, 2-js-basics, vv)
175- Mỗi dự án có thư mục `solution/` và thường có thư mục `start/` hoặc `your-work/`
176- Hình ảnh lưu trong thư mục `images/` riêng từng bài học
177- Bản dịch trong cấu trúc `translations/{language-code}/`
178 
179## Xây Dựng và Triển Khai
180 
181### Triển Khai Ứng Dụng Quiz (Azure Static Web Apps)
182 
183Ứng dụng quiz đã được cấu hình để triển khai với Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Tạo thư mục dist/
188# Triển khai thông qua quy trình làm việc GitHub Actions khi đẩy lên nhánh main
189```
190 
191Cấu hình Azure Static Web Apps:
192- **Vị trí ứng dụng**: `/quiz-app`
193- **Vị trí đầu ra**: `dist`
194- **Quy trình làm việc**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Tạo PDF Tài Liệu
197 
198```bash
199npm install                    # Cài đặt docsify-to-pdf
200npm run convert               # Tạo PDF từ docs
201```
202 
203### Tài Liệu Docsify
204 
205```bash
206npm install -g docsify-cli    # Cài đặt Docsify toàn cục
207docsify serve                 # Phục vụ trên localhost:3000
208```
209 
210### Build Riêng Cho Dự Án
211 
212Mỗi thư mục dự án có thể có quy trình build riêng:
213- Dự án Vue: chạy `npm run build` để tạo gói sản xuất
214- Dự án tĩnh: không cần bước build, phục vụ file trực tiếp
215 
216## Hướng Dẫn Pull Request
217 
218### Định Dạng Tiêu Đề
219 
220Dùng tiêu đề rõ ràng, mô tả khu vực thay đổi:
221- `[Quiz-app] Thêm bài kiểm tra mới cho bài học X`
222- `[Lesson-3] Sửa lỗi chính tả trong dự án terrarium`
223- `[Translation] Thêm bản dịch tiếng Tây Ban Nha cho bài học 5`
224- `[Docs] Cập nhật hướng dẫn thiết lập`
225 
226### Kiểm Tra Bắt Buộc
227 
228Trước khi gửi PR:
229 
2301. **Chất lượng mã**:
231   - Chạy `npm run lint` trong các thư mục dự án ảnh hưởng
232   - Sửa tất cả lỗi và cảnh báo lint
233 
2342. **Xác minh build**:
235   - Chạy `npm run build` nếu có
236   - Đảm bảo không có lỗi build
237 
2383. **Kiểm tra liên kết**:
239   - Thử tất cả các liên kết markdown
240   - Xác nhận hình ảnh hiển thị đúng
241 
2424. **Kiểm duyệt nội dung**:
243   - Đọc lại chính tả và ngữ pháp
244   - Đảm bảo ví dụ mã chính xác và phù hợp học thuật
245   - Xác nhận bản dịch giữ nguyên nghĩa
246 
247### Yêu Cầu Đóng Góp
248 
249- Đồng ý với Microsoft CLA (kiểm tra tự động khi PR đầu tiên)
250- Tuân thủ [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Tham khảo [CONTRIBUTING.md](./CONTRIBUTING.md) để biết hướng dẫn chi tiết
252- Tham chiếu số issue trong mô tả PR nếu có
253 
254### Quy Trình Đánh Giá
255 
256- PR được duyệt bởi người duy trì và cộng đồng
257- Ưu tiên tính rõ ràng trong giáo dục
258- Ví dụ mã tuân thủ thực tiễn tốt nhất hiện hành
259- Kiểm tra độ chính xác và phù hợp văn hóa của bản dịch
260 
261## Hệ Thống Dịch Thuật
262 
263### Dịch Tự Động
264 
265- Dùng GitHub Actions với workflow co-op-translator
266- Dịch tự động sang hơn 50 ngôn ngữ
267- Tệp nguồn trong các thư mục chính
268- Tệp được dịch lưu trong thư mục `translations/{language-code}/`
269 
270### Thêm Cải Tiến Dịch Thủ Công
271 
2721. Tìm tệp trong `translations/{language-code}/`
2732. Cải tiến nội dung giữ nguyên cấu trúc
2743. Đảm bảo các ví dụ mã hoạt động
2754. Kiểm thử nội dung quiz đã dịch
276 
277### Siêu Dữ Liệu Dịch Thuật
278 
279Tệp dịch có bao gồm đầu mục metadata:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Gỡ Lỗi và Khắc Phục Sự Cố
293 
294### Vấn Đề Thường Gặp
295 
296**Ứng dụng quiz không khởi động**:
297- Kiểm tra phiên bản Node.js (khuyến nghị v14+)
298- Xóa thư mục `node_modules` và file `package-lock.json`, chạy lại `npm install`
299- Kiểm tra xung đột cổng (mặc định Vite dùng cổng 5173)
300 
301**API server không khởi động**:
302- Đảm bảo phiên bản Node.js >= 10
303- Kiểm tra xem cổng có đang được sử dụng không
304- Đảm bảo cài đặt tất cả phụ thuộc với `npm install`
305 
306**Tiện ích mở rộng trình duyệt không tải được**:
307- Kiểm tra file manifest.json đúng định dạng
308- Xem console trình duyệt để phát hiện lỗi
309- Làm theo hướng dẫn cài đặt riêng của trình duyệt
310 
311**Vấn đề dự án chat Python**:
312- Cài đặt gói OpenAI: `pip install openai`
313- Xác nhận biến môi trường GITHUB_TOKEN đã được thiết lập
314- Kiểm tra quyền truy cập Models GitHub
315 
316**Docsify không phục vụ tài liệu**:
317- Cài docsify-cli toàn cục: `npm install -g docsify-cli`
318- Chạy từ thư mục gốc của kho
319- Kiểm tra file `docs/_sidebar.md` tồn tại
320 
321### Mẹo Phát Triển Môi Trường
322 
323- Dùng VS Code với tiện ích Live Server cho các dự án HTML
324- Cài ESLint và Prettier để định dạng nhất quán
325- Dùng DevTools trình duyệt để gỡ lỗi JavaScript
326- Với dự án Vue, cài đặt tiện ích Vue DevTools cho trình duyệt
327 
328### Cân Nhắc Hiệu Suất
329 
330- Số lượng tệp dịch lớn (hơn 50 ngôn ngữ) làm cho clone đầy đủ nặng
331- Dùng clone nông nếu chỉ làm việc nội dung: `git clone --depth 1`
332- Loại trừ thư mục dịch khỏi tìm kiếm khi làm việc với nội dung tiếng Anh
333- Quá trình build có thể chậm lần đầu (npm install, build Vite)
334 
335## Cân Nhắc Bảo Mật
336 
337### Biến Môi Trường
338 
339- Không được commit khóa API vào kho
340- Dùng các file `.env` (đã có trong `.gitignore`)
341- Ghi lại các biến môi trường cần thiết trong README dự án
342 
343### Dự Án Python
344 
345- Sử dụng môi trường ảo: `python -m venv venv`
346- Giữ phụ thuộc luôn được cập nhật
347- Token GitHub chỉ cần quyền tối thiểu cần thiết
348 
349### Quyền Truy Cập GitHub Models
350 
351- Cần Personal Access Tokens (PAT) cho GitHub Models
352- Lưu tokens dưới dạng biến môi trường
353- Không được commit tokens hoặc thông tin đăng nhập
354 
355## Ghi Chú Thêm
356 
357### Đối Tượng Hướng Đến
358 
359- Người mới bắt đầu hoàn toàn về phát triển web
360- Học sinh và người tự học
361- Giáo viên sử dụng chương trình trong lớp học
362- Nội dung thiết kế để dễ tiếp cận và xây dựng kỹ năng dần dần
363 
364### Triết Lý Giáo Dục
365 
366- Học qua dự án
367- Kiểm tra kiến thức thường xuyên (quiz)
368- Thực hành viết mã trực tiếp
369- Ví dụ ứng dụng thực tế
370- Tập trung vào kiến thức nền tảng trước khi học framework
371 
372### Bảo Trì Kho
373 
374- Cộng đồng học viên và người đóng góp năng động
375- Cập nhật thường xuyên các phụ thuộc và nội dung
376- Người quản lý theo dõi các issue và thảo luận
377- Cập nhật dịch tự động qua GitHub Actions
378 
379### Tài Nguyên Liên Quan
380 
381- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
382- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) được khuyến nghị cho học viên
384- Các khoá học bổ sung: AI tạo sinh, Khoa học dữ liệu, ML, IoT
385 
386### Làm Việc Với Các Dự Án Cụ Thể
387 
388Hướng dẫn chi tiết cho từng dự án xem trong các tệp README:
389- `quiz-app/README.md` - Ứng dụng quiz Vue 3
390- `7-bank-project/README.md` - Ứng dụng ngân hàng có xác thực
391- `5-browser-extension/README.md` - Phát triển tiện ích mở rộng trình duyệt
392- `6-space-game/README.md` - Phát triển trò chơi canvas
393- `9-chat-project/README.md` - Dự án trợ lý chat AI
394 
395### Cấu Trúc Monorepo
396 
397Mặc dù không phải monorepo truyền thống, kho này chứa nhiều dự án độc lập:
398- Mỗi bài học tự chứa
399- Các dự án không chia sẻ phụ thuộc
400- Làm việc riêng biệt từng dự án mà không ảnh hưởng lẫn nhau
401- Clone toàn bộ kho để trải nghiệm đầy đủ chương trình học
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Tuyên bố từ chối trách nhiệm**:  
407Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ bản địa nên được xem là nguồn thông tin chính thức. Đối với những thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hay giải thích sai nào phát sinh từ việc sử dụng bản dịch này.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->