AGENTS.md

1# AGENTS.md
2 
3## ภาพรวมของโครงการ
4 
5นี่คือที่เก็บหลักสูตรการศึกษาสำหรับการสอนพื้นฐานการพัฒนาเว็บสำหรับผู้เริ่มต้น หลักสูตรนี้เป็นหลักสูตรครบวงจร 12 สัปดาห์ที่พัฒนาโดย Microsoft Cloud Advocates ซึ่งประกอบด้วยบทเรียนลงมือทำทั้งหมด 24 บทเรียนที่ครอบคลุม JavaScript, CSS และ HTML
6 
7### ส่วนประกอบหลัก
8 
9- **เนื้อหาการศึกษา**: บทเรียนที่มีโครงสร้าง 24 บทเรียน จัดเป็นโมดูลตามโครงการ
10- **โครงการเชิงปฏิบัติ**: Terrarium, เกมพิมพ์ดีด, ส่วนขยายเบราว์เซอร์, เกมอวกาศ, แอปธนาคาร, ตัวแก้ไขโค้ด และผู้ช่วยแชท AI
11- **แบบทดสอบเชิงโต้ตอบ**: แบบทดสอบ 48 ชุด โดยแต่ละชุดมี 3 คำถาม (สำหรับประเมินก่อนและหลังบทเรียน)
12- **รองรับหลายภาษา**: การแปลอัตโนมัติสำหรับมากกว่า 50 ภาษา ผ่าน GitHub Actions
13- **เทคโนโลยี**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (สำหรับโครงการ AI)
14 
15### สถาปัตยกรรม
16 
17- ที่เก็บการศึกษาที่มีโครงสร้างตามบทเรียน
18- โฟลเดอร์แต่ละบทเรียนประกอบด้วย README, ตัวอย่างโค้ด และคำตอบ
19- โครงการแยกต่างหากในไดเรกทอรีต่างหาก (quiz-app, โครงการบทเรียนต่างๆ)
20- ระบบแปลโดยใช้ GitHub Actions (co-op-translator)
21- เอกสารให้บริการผ่าน Docsify และมีในรูปแบบ PDF
22 
23## คำสั่งการตั้งค่า
24 
25ที่เก็บนี้สำหรับการบริโภคเนื้อหาการศึกษาหลัก สำหรับการทำงานกับโครงการเฉพาะ:
26 
27### การตั้งค่าที่เก็บหลัก
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### การตั้งค่า Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # เริ่มเซิร์ฟเวอร์พัฒนา
40npm run build      # สร้างสำหรับการผลิต
41npm run lint       # รัน ESLint
42```
43 
44### Bank Project API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # เริ่มต้นเซิร์ฟเวอร์ API
50npm run lint       # รัน ESLint
51npm run format     # จัดรูปแบบด้วย Prettier
52```
53 
54### โครงการส่วนขยายเบราว์เซอร์
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# ปฏิบัติตามคำแนะนำการโหลดส่วนขยายเฉพาะของเบราว์เซอร์
60```
61 
62### โครงการเกมอวกาศ
63 
64```bash
65cd 6-space-game/solution
66npm install
67# เปิดไฟล์ index.html ในเบราว์เซอร์หรืใช้ Live Server
68```
69 
70### โครงการแชท (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# ตั้งค่าตัวแปรสภาพแวดล้อม GITHUB_TOKEN
76python api.py
77```
78 
79## ขั้นตอนการพัฒนา
80 
81### สำหรับผู้ร่วมสร้างเนื้อหา
82 
831. **Fork ที่เก็บนี้** ไปยังบัญชี GitHub ของคุณ
842. **โคลน fork ของคุณ** ลงในเครื่อง
853. **สร้างสาขาใหม่** สำหรับการเปลี่ยนแปลงของคุณ
864. ทำการเปลี่ยนแปลงเนื้อหาบทเรียนหรือโค้ดตัวอย่าง
875. ทดสอบการเปลี่ยนแปลงโค้ดในไดเรกทอรีโครงการที่เกี่ยวข้อง
886. ส่ง pull request ตามแนวทางการร่วมมือ
89 
90### สำหรับผู้เรียน
91 
921. Fork หรือโคลนที่เก็บนี้
932. ไปยังไดเรกทอรีบทเรียนตามลำดับ
943. อ่านไฟล์ README สำหรับแต่ละบทเรียน
954. ทำแบบทดสอบก่อนบทเรียนที่ https://ff-quizzes.netlify.app/web/
965. ทำงานกับตัวอย่างโค้ดในโฟลเดอร์บทเรียน
976. ทำแบบฝึกหัดและความท้าทายให้เสร็จ
987. ทำแบบทดสอบหลังบทเรียน
99 
100### การพัฒนาแบบสด
101 
102- **เอกสาร**: รัน `docsify serve` ที่รากโปรเจ็ค (พอร์ต 3000)
103- **Quiz App**: รัน `npm run dev` ในไดเรกทอรี quiz-app
104- **โครงการ**: ใช้ส่วนขยาย VS Code Live Server สำหรับโครงการ HTML
105- **โครงการ API**: รัน `npm start` ในไดเรกทอรี API ตามลำดับ
106 
107## คำแนะนำการทดสอบ
108 
109### การทดสอบ Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # ตรวจสอบปัญหาสไตล์โค้ด
114npm run build      # ตรวจสอบการสร้างให้สำเร็จ
115```
116 
117### การทดสอบ Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # ตรวจสอบปัญหาสไตล์โค้ด
122node server.js     # ยืนยันว่าเซิร์ฟเวอร์เริ่มทำงานโดยไม่มีข้อผิดพลาด
123```
124 
125### แนวทางการทดสอบทั่วไป
126 
127- ที่เก็บนี้เป็นที่เก็บการศึกษาโดยไม่มีการทดสอบอัตโนมัติครบถ้วน
128- การทดสอบด้วยตนเองเน้นที่:
129  - ตัวอย่างโค้ดทำงานได้โดยไม่มีข้อผิดพลาด
130  - ลิงก์ในเอกสารทำงานอย่างถูกต้อง
131  - การสร้างโครงการสำเร็จ
132  - ตัวอย่างทำตามแนวปฏิบัติที่ดีที่สุด
133 
134### การตรวจสอบก่อนส่ง
135 
136- รัน `npm run lint` ในไดเรกทอรีที่มี package.json
137- ตรวจสอบลิงก์ markdown ว่าถูกต้อง
138- ทดสอบตัวอย่างโค้ดในเบราว์เซอร์หรือ Node.js
139- ตรวจสอบว่าการแปลรักษาโครงสร้างที่ถูกต้อง
140 
141## แนวทางสไตล์โค้ด
142 
143### JavaScript
144 
145- ใช้ไวยากรณ์ ES6+ สมัยใหม่
146- ปฏิบัติตามการตั้งค่า ESLint มาตรฐานในโครงการ
147- ใช้ชื่อตัวแปรและฟังก์ชันที่มีความหมายเพื่อความชัดเจนทางการศึกษา
148- เพิ่มคอมเมนต์อธิบายแนวคิดสำหรับผู้เรียน
149- ฟอร์แมตโดยใช้ Prettier เมื่อมีการตั้งค่า
150 
151### HTML/CSS
152 
153- ใช้องค์ประกอบ HTML5 ตามความหมาย
154- หลักการออกแบบตอบสนอง (Responsive)
155- กฎการตั้งชื่อตัวแปรคลาสที่ชัดเจน
156- คอมเมนต์อธิบายเทคนิค CSS สำหรับผู้เรียน
157 
158### Python
159 
160- ปฏิบัติตามแนวทางสไตล์ PEP 8
161- ตัวอย่างโค้ดที่ชัดเจนและเน้นการศึกษา
162- ใช้ type hint เมื่อช่วยให้เรียนรู้ได้ดีขึ้น
163 
164### เอกสาร Markdown
165 
166- ลำดับหัวข้อชัดเจน
167- บล็อกโค้ดพร้อมระบุภาษา
168- ลิงก์ไปยังแหล่งข้อมูลเพิ่มเติม
169- ภาพหน้าจอและรูปภาพในโฟลเดอร์ `images/`
170- ข้อความ alt ของภาพเพื่อการเข้าถึง
171 
172### การจัดระเบียบไฟล์
173 
174- บทเรียนเรียงหมายเลข (1-getting-started-lessons, 2-js-basics, เป็นต้น)
175- โครงการแต่ละอันมีไดเรกทอรี `solution/` และมักมี `start/` หรือ `your-work/`
176- รูปภาพเก็บในโฟลเดอร์ `images/` ที่เฉพาะเจาะจงกับบทเรียน
177- การแปลอยู่ในโครงสร้าง `translations/{language-code}/`
178 
179## การสร้างและปรับใช้
180 
181### การปรับใช้ Quiz App (Azure Static Web Apps)
182 
183quiz-app ถูกตั้งค่าสำหรับการปรับใช้กับ Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # สร้างโฟลเดอร์ dist/
188# ดีพลอยผ่าน workflow ของ GitHub Actions เมื่อ push ไปที่ main
189```
190 
191การตั้งค่า Azure Static Web Apps:
192- **ตำแหน่งแอป**: `/quiz-app`
193- **ตำแหน่งผลลัพธ์**: `dist`
194- **เวิร์กโฟลว์**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### การสร้างไฟล์เอกสาร PDF
197 
198```bash
199npm install                    # ติดตั้ง docsify-to-pdf
200npm run convert               # สร้าง PDF จาก docs
201```
202 
203### เอกสาร Docsify
204 
205```bash
206npm install -g docsify-cli    # ติดตั้ง Docsify ทั่วระบบ
207docsify serve                 # ให้บริการที่ localhost:3000
208```
209 
210### การสร้างเฉพาะโครงการ
211 
212แต่ละไดเรกทอรีโครงการอาจมีขั้นตอนการสร้างของตัวเอง:
213- โครงการ Vue: `npm run build` สร้าง bundle สำหรับโปรดักชัน
214- โครงการสแตติก: ไม่มีขั้นตอนการสร้าง ให้บริการไฟล์โดยตรง
215 
216## แนวทางในการส่ง Pull Request
217 
218### รูปแบบชื่อเรื่อง
219 
220ใช้ชื่อเรื่องที่ชัดเจนและบอกบริเวณการเปลี่ยนแปลง:
221- `[Quiz-app] เพิ่มแบบทดสอบใหม่สำหรับบทเรียน X`
222- `[Lesson-3] แก้ไขคำผิดในโครงการ terrarium`
223- `[Translation] เพิ่มการแปลภาษาสเปนสำหรับบทเรียน 5`
224- `[Docs] ปรับปรุงคำแนะนำการตั้งค่า`
225 
226### การตรวจสอบที่จำเป็น
227 
228ก่อนส่ง PR:
229 
2301. **คุณภาพโค้ด**:
231   - รัน `npm run lint` ในไดเรกทอรีโครงการที่ได้รับผลกระทบ
232   - แก้ไขข้อผิดพลาดและคำเตือนทั้งหมด
233 
2342. **ตรวจสอบการสร้าง**:
235   - รัน `npm run build` ถ้ามี
236   - ตรวจสอบว่าไม่มีข้อผิดพลาดจากการสร้าง
237 
2383. **ตรวจสอบลิงก์**:
239   - ทดสอบลิงก์ markdown ทั้งหมด
240   - ตรวจสอบการอ้างอิงภาพว่าใช้งานได้
241 
2424. **ตรวจสอบเนื้อหา**:
243   - ตรวจทานคำสะกดและไวยากรณ์
244   - ตรวจสอบตัวอย่างโค้ดว่าถูกต้องและเหมาะสมสำหรับการศึกษา
245   - ตรวจสอบว่าแปลถูกต้องและรักษาความหมายต้นฉบับ
246 
247### ข้อกำหนดการมีส่วนร่วม
248 
249- ยอมรับ Microsoft CLA (ตรวจสอบอัตโนมัติใน PR แรก)
250- ปฏิบัติตาม [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- ดู [CONTRIBUTING.md](./CONTRIBUTING.md) สำหรับแนวทางรายละเอียด
252- อ้างถึงหมายเลข issue ในคำอธิบาย PR หากเกี่ยวข้อง
253 
254### กระบวนการตรวจสอบ
255 
256- PR ถูกตรวจสอบโดยผู้ดูแลและชุมชน
257- เน้นความชัดเจนทางการศึกษาเป็นสำคัญ
258- ตัวอย่างโค้ดควรเป็นไปตามแนวปฏิบัติที่ดีที่สุดปัจจุบัน
259- การแปลต้องได้รับการตรวจสอบว่าถูกต้องและเหมาะสมทางวัฒนธรรม
260 
261## ระบบแปลภาษา
262 
263### การแปลอัตโนมัติ
264 
265- ใช้ GitHub Actions กับเวิร์กโฟลว์ co-op-translator
266- แปลอัตโนมัติเป็นกว่า 50 ภาษา
267- ไฟล์ต้นทางในไดเรกทอรีหลัก
268- ไฟล์แปลในโครงสร้าง `translations/{language-code}/`
269 
270### การเพิ่มคุณภาพการแปลด้วยตนเอง
271 
2721. ค้นหาไฟล์ใน `translations/{language-code}/`
2732. ปรับปรุงโดยรักษาโครงสร้างเดิม
2743. ตรวจสอบว่าตัวอย่างโค้ดยังทำงานได้
2754. ทดสอบเนื้อหาแบบทดสอบในท้องถิ่น
276 
277### เมตาดาต้าแปลภาษา
278 
279ไฟล์แปลจะมีส่วนหัว 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## การดีบักและแก้ปัญหา
293 
294### ปัญหาทั่วไป
295 
296**แอปแบบทดสอบไม่เริ่มทำงาน**:
297- ตรวจสอบเวอร์ชัน Node.js (แนะนำ v14+)
298- ลบ `node_modules` และ `package-lock.json` แล้วรัน `npm install` ใหม่
299- ตรวจสอบพอร์ตว่าง (ค่าเริ่มต้น: Vite ใช้พอร์ต 5173)
300 
301**เซิร์ฟเวอร์ API ไม่เริ่มทำงาน**:
302- ตรวจสอบเวอร์ชัน Node.js ให้เป็นไปตามขั้นต่ำ (node >=10)
303- ตรวจสอบว่าพอร์ทยังว่างอยู่
304- ติดตั้ง dependencies ทั้งหมดด้วย `npm install`
305 
306**ส่วนขยายเบราว์เซอร์ไม่โหลด**:
307- ตรวจสอบว่า manifest.json ถูกฟอร์แมตอย่างถูกต้อง
308- ดูข้อผิดพลาดในคอนโซลเบราว์เซอร์
309- ปฏิบัติตามคำแนะนำการติดตั้งของเบราว์เซอร์แต่ละตัว
310 
311**ปัญหาโครงการแชท Python**:
312- ตรวจสอบว่าติดตั้งแพ็กเกจ OpenAI แล้ว: `pip install openai`
313- ตรวจสอบว่าตัวแปรสภาพแวดล้อม GITHUB_TOKEN ถูกตั้งค่าแล้ว
314- ตรวจสอบสิทธิ์การเข้าถึงโมเดล GitHub
315 
316**Docsify ไม่ให้บริการเอกสาร**:
317- ติดตั้ง docsify-cli ทั่วไป: `npm install -g docsify-cli`
318- รันจากไดเรกทอรีรากของที่เก็บนี้
319- ตรวจสอบว่าไฟล์ `docs/_sidebar.md` มีอยู่
320 
321### เคล็ดลับสภาพแวดล้อมการพัฒนา
322 
323- ใช้ VS Code กับส่วนขยาย Live Server สำหรับโครงการ HTML
324- ติดตั้งส่วนขยาย ESLint และ Prettier สำหรับการฟอร์แมตที่สอดคล้อง
325- ใช้ DevTools ของเบราว์เซอร์สำหรับดีบัก JavaScript
326- สำหรับโปรเจ็กต์ Vue ให้ติดตั้งส่วนขยาย Vue DevTools บนเบราว์เซอร์
327 
328### การพิจารณาด้านประสิทธิภาพ
329 
330- จำนวนไฟล์แปลมาก (50+ ภาษา) ทำให้การโคลนครบถ้วนมีขนาดใหญ่
331- ใช้ shallow clone หากทำงานแค่เนื้อหา: `git clone --depth 1`
332- งดการค้นหาในโฟลเดอร์แปลภาษาเมื่อทำงานกับเนื้อหาอังกฤษ
333- ขั้นตอนการสร้างอาจช้าในครั้งแรก (npm install, สร้าง Vite)
334 
335## การพิจารณาด้านความปลอดภัย
336 
337### ตัวแปรสภาพแวดล้อม
338 
339- ห้ามคีย์ API ถูกคอมมิตในที่เก็บ
340- ใช้ไฟล์ `.env` (มีใน `.gitignore` แล้ว)
341- อธิบายตัวแปรสภาพแวดล้อมที่ต้องใช้ใน README ของแต่ละโครงการ
342 
343### โครงการ Python
344 
345- ใช้สภาพแวดล้อมเสมือน: `python -m venv venv`
346- อัปเดต dependencies อย่างสม่ำเสมอ
347- โทเค็น GitHub ควรมีสิทธิ์ขั้นต่ำที่จำเป็น
348 
349### การเข้าถึงโมเดล GitHub
350 
351- ต้องใช้ Personal Access Tokens (PAT) สำหรับโมเดล GitHub
352- โทเค็นควรเก็บเป็นตัวแปรสภาพแวดล้อม
353- ห้ามคอมมิตโทเค็นหรือข้อมูลประจำตัว
354 
355## หมายเหตุเพิ่มเติม
356 
357### กลุ่มเป้าหมาย
358 
359- ผู้เริ่มต้นเรียนรู้การพัฒนาเว็บอย่างสมบูรณ์
360- นักเรียนและผู้เรียนด้วยตนเอง
361- ครูผู้ใช้หลักสูตรในห้องเรียน
362- เนื้อหาออกแบบเพื่อการเข้าถึงและสร้างทักษะทีละขั้น
363 
364### ปรัชญาการศึกษา
365 
366- วิธีการเรียนรู้แบบโครงการ
367- มีการทดสอบความรู้บ่อยครั้ง (แบบทดสอบ)
368- แบบฝึกหัดโค้ดแบบลงมือทำ
369- ตัวอย่างการใช้งานจริง
370- เน้นพื้นฐานก่อนใช้เฟรมเวิร์ก
371 
372### การดูแลรักษาที่เก็บ
373 
374- ชุมชนผู้เรียนและผู้ร่วมมือที่แอคทีฟ
375- อัปเดต dependencies และเนื้อหาอย่างสม่ำเสมอ
376- มีผู้ดูแลคอยติดตามปัญหาและการสนทนา
377- การอัปเดตการแปลอัตโนมัติผ่าน GitHub Actions
378 
379### ทรัพยากรที่เกี่ยวข้อง
380 
381- [โมดูล Microsoft Learn](https://docs.microsoft.com/learn/)
382- [ทรัพยากร Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- แนะนำ [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) สำหรับผู้เรียน
384- หลักสูตรเพิ่มเติม: AI สร้างสรรค์, วิทยาศาสตร์ข้อมูล, ML, หลักสูตร IoT
385 
386### การทำงานกับโครงการเฉพาะ
387 
388สำหรับคำแนะนำเฉพาะเจาะจงของแต่ละโครงการ ดูไฟล์ README ใน:
389- `quiz-app/README.md` - แอปแบบทดสอบด้วย Vue 3
390- `7-bank-project/README.md` - แอปธนาคารพร้อมระบบยืนยันตัวตน
391- `5-browser-extension/README.md` - การพัฒนาส่วนขยายเบราว์เซอร์
392- `6-space-game/README.md` - การพัฒนาเกมด้วย Canvas
393- `9-chat-project/README.md` - โครงการผู้ช่วยแชท AI
394 
395### โครงสร้าง Monorepo
396 
397แม้จะไม่ใช่ monorepo แบบดั้งเดิม แต่ที่เก็บนี้ประกอบด้วยโครงการอิสระหลายชุด:
398- แต่ละบทเรียนเป็นอิสระ
399- โครงการไม่แชร์ dependencies ร่วมกัน
400- ทำงานกับโครงการแต่ละอันโดยไม่กระทบโครงการอื่น
401- โคลนที่เก็บทั้งหมดเพื่อประสบการณ์หลักสูตรเต็มรูปแบบ
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**ข้อจำกัดความรับผิดชอบ**:
407เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้เราจะพยายามให้ความถูกต้องสูงสุด โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลสำคัญ แนะนำให้ใช้การแปลโดยมนุษย์ผู้เชี่ยวชาญ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดใด ๆ ที่เกิดจากการใช้การแปลนี้
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->