# AGENTS.md

## ภาพรวมโครงการ

นี่คือรีโพสิตอรีหลักสูตรการศึกษาสำหรับสอนพื้นฐานการพัฒนาเว็บแก่ผู้เริ่มต้น หลักสูตรเป็นคอร์สครอบคลุม 12 สัปดาห์ที่พัฒนาโดย Microsoft Cloud Advocates มีบทเรียน 24 บทเรียนนำเสนอโครงการเชิงปฏิบัติที่ครอบคลุม JavaScript, CSS และ HTML

### ส่วนสำคัญ

- **เนื้อหาการศึกษา**: 24 บทเรียนที่จัดโครงสร้างในรูปแบบโมดูลโปรเจค
- **โครงการเชิงปฏิบัติ**: Terrarium, เกมพิมพ์ดีด, ส่วนขยายเบราว์เซอร์, เกมอวกาศ, แอปธนาคาร, โปรแกรมแก้ไขโค้ด, และผู้ช่วยแชท AI
- **แบบทดสอบเชิงโต้ตอบ**: แบบทดสอบ 48 ชุด แต่ละชุดมี 3 คำถาม (ประเมินก่อน/หลังบทเรียน)
- **รองรับหลายภาษา**: แปลโดยอัตโนมัติสำหรับ 50+ ภาษา โดยใช้ GitHub Actions
- **เทคโนโลยี**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (สำหรับโครงการ AI)

### สถาปัตยกรรม

- รีโพสิตอรีการศึกษาที่มีโครงสร้างตามบทเรียน
- แต่ละโฟลเดอร์บทเรียนประกอบด้วย README, ตัวอย่างโค้ด และวิธีแก้ไข
- โครงการเดี่ยวแยกอยู่ในไดเรกทอรีต่างหาก (quiz-app, โครงการบทเรียนต่างๆ)
- ระบบแปลโดยใช้ GitHub Actions (co-op-translator)
- เอกสารให้บริการผ่าน Docsify และมีในรูปแบบ PDF

## คำสั่งติดตั้ง

รีโพสิตอรีนี้เน้นสำหรับการบริโภคเนื้อหาการศึกษาหลัก หากต้องการทำงานกับโครงการเฉพาะ:

### การตั้งค่าหลักของรีโพสิตอรี

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### การตั้งค่า Quiz App (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # เริ่มต้นเซิร์ฟเวอร์สำหรับพัฒนา
npm run build      # สร้างสำหรับการผลิต
npm run lint       # รัน ESLint
```

### API โครงการธนาคาร (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # เริ่มเซิร์ฟเวอร์ API
npm run lint       # รัน ESLint
npm run format     # จัดรูปแบบด้วย Prettier
```

### โครงการส่วนขยายเบราว์เซอร์

```bash
cd 5-browser-extension/solution
npm install
# ทำตามคำแนะนำการโหลดส่วนขยายเฉพาะของเบราว์เซอร์
```

### โครงการเกมอวกาศ

```bash
cd 6-space-game/solution
npm install
# เปิดไฟล์ index.html ในเบราว์เซอร์หรือใช้ Live Server
```

### โครงการแชท (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# ตั้งค่าตัวแปรสภาพแวดล้อม GITHUB_TOKEN
python api.py
```

## กระบวนการพัฒนา

### สำหรับผู้ร่วมเนื้อหา

1. **Fork รีโพสิตอรี** ไปยังบัญชี GitHub ของคุณ
2. **โคลน fork** ลงในเครื่องของคุณ
3. **สร้างสาขาใหม่** สำหรับการเปลี่ยนแปลงของคุณ
4. แก้ไขเนื้อหาบทเรียนหรือตัวอย่างโค้ด
5. ทดสอบการเปลี่ยนแปลงโค้ดในไดเรกทอรีโครงการที่เกี่ยวข้อง
6. ส่ง pull request ตามแนวทางการมีส่วนร่วม

### สำหรับผู้เรียน

1. Fork หรือโคลนรีโพสิตอรี
2. ไปที่ไดเรกทอรีบทเรียนเรียงตามลำดับ
3. อ่านไฟล์ README สำหรับแต่ละบทเรียน
4. ทำแบบทดสอบก่อนบทเรียนที่ https://ff-quizzes.netlify.app/web/
5. ทำตัวอย่างโค้ดในโฟลเดอร์บทเรียน
6. ทำการบ้านและความท้าทาย
7. ทำแบบทดสอบหลังบทเรียน

### การพัฒนาแบบสด

- **เอกสาร**: รัน `docsify serve` ในโฟลเดอร์หลัก (พอร์ต 3000)
- **Quiz App**: รัน `npm run dev` ในไดเรกทอรี quiz-app
- **โครงการ**: ใช้ส่วนขยาย VS Code Live Server สำหรับโครงการ HTML
- **โครงการ API**: รัน `npm start` ในไดเรกทอรี API ที่เกี่ยวข้อง

## คำแนะนำการทดสอบ

### การทดสอบ Quiz App

```bash
cd quiz-app
npm run lint       # ตรวจสอบปัญหาสไตล์โค้ด
npm run build      # ยืนยันการสร้างสำเร็จ
```

### การทดสอบ Bank API

```bash
cd 7-bank-project/api
npm run lint       # ตรวจสอบปัญหาสไตล์โค้ด
node server.js     # ตรวจสอบว่าเซิร์ฟเวอร์เริ่มต้นโดยไม่มีข้อผิดพลาด
```

### แนวทางการทดสอบทั่วไป

- นี่คือรีโพสิตอรีการศึกษาที่ไม่มีการทดสอบอัตโนมัติครบถ้วน
- การทดสอบด้วยตนเองเน้นที่:
  - ตัวอย่างโค้ดทำงานโดยไม่มีข้อผิดพลาด
  - ลิงก์ในเอกสารทำงานถูกต้อง
  - การสร้างโครงการสมบูรณ์สำเร็จ
  - ตัวอย่างตามแนวทางปฏิบัติที่ดีที่สุด

### การตรวจสอบก่อนส่ง

- รัน `npm run lint` ในไดเรกทอรีที่มี package.json
- ตรวจสอบลิงก์ Markdown ให้ถูกต้อง
- ทดสอบตัวอย่างโค้ดในเบราว์เซอร์หรือ Node.js
- ตรวจสอบว่าสิ่งแปลคงโครงสร้างเดิม

## แนวทางการเขียนโค้ด

### JavaScript

- ใช้ไวยากรณ์ ES6+ สมัยใหม่
- ตามการตั้งค่า ESLint มาตรฐานที่ให้มาในโครงการ
- ใช้ชื่อตัวแปรและฟังก์ชันที่มีความหมายเพื่อความชัดเจนในการศึกษา
- เพิ่มคอมเมนต์อธิบายแนวคิดสำหรับผู้เรียน
- จัดรูปแบบโดยใช้ Prettier เมื่อกำหนดไว้

### HTML/CSS

- ใช้องค์ประกอบ HTML5 เชิงความหมาย
- หลักการออกแบบตอบสนอง
- การตั้งชื่อคลาสที่ชัดเจน
- คอมเมนต์อธิบายเทคนิค CSS สำหรับผู้เรียน

### Python

- แนวทางสไตล์ PEP 8
- ตัวอย่างโค้ดชัดเจนและเหมาะสำหรับการศึกษา
- ใส่ type hints เมื่อต้องการช่วยการเรียนรู้

### เอกสาร Markdown

- โครงสร้างหัวข้อที่ชัดเจน
- บล็อกโค้ดพร้อมการระบุภาษา
- ลิงก์ไปยังแหล่งข้อมูลเพิ่มเติม
- รูปภาพและสกรีนช็อตในโฟลเดอร์ `images/`
- ข้อความ alt สำหรับรูปภาพเพื่อการเข้าถึง

### การจัดการไฟล์

- บทเรียนเรียงลำดับหมายเลข (1-getting-started-lessons, 2-js-basics, เป็นต้น)
- โครงการแต่ละอันมีโฟลเดอร์ `solution/` และมักจะมี `start/` หรือ `your-work/`
- รูปภาพเก็บในโฟลเดอร์ `images/` เฉพาะบทเรียน
- การแปลอยู่ในโครงสร้าง `translations/{language-code}/`

## การสร้างและปรับใช้

### การปรับใช้ Quiz App (Azure Static Web Apps)

quiz-app ถูกตั้งค่าสำหรับการปรับใช้บน Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # สร้างโฟลเดอร์ dist/
# นำส่งผ่าน workflow ของ GitHub Actions เมื่อมีการ push ไปยัง main
```

การตั้งค่า Azure Static Web Apps:
- **ที่ตั้งแอป**: `/quiz-app`
- **โฟลเดอร์เอาต์พุต**: `dist`
- **เวิร์กโฟลว์**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### การสร้างเอกสาร PDF

```bash
npm install                    # ติดตั้ง docsify-to-pdf
npm run convert               # สร้าง PDF จาก docs
```

### เอกสาร Docsify

```bash
npm install -g docsify-cli    # ติดตั้ง Docsify ทั่วโลก
docsify serve                 # ให้บริการบน localhost:3000
```

### การสร้างเฉพาะโครงการ

ไดเรกทอรีโครงการแต่ละอันอาจมีขั้นตอนการสร้างของตัวเอง:
- โครงการ Vue: รัน `npm run build` เพื่อสร้างบันเดิลสำหรับผลิต
- โครงการสแตติก: ไม่มีขั้นตอนการสร้าง เสิร์ฟไฟล์โดยตรง

## แนวทางการส่ง Pull Request

### รูปแบบชื่อหัวข้อ

ใช้หัวข้อชัดเจน บอกขอบเขตของการเปลี่ยนแปลง:
- `[Quiz-app] เพิ่มแบบทดสอบใหม่สำหรับบทเรียน X`
- `[Lesson-3] แก้ไขคำผิดในโครงการ terrarium`
- `[Translation] เพิ่มคำแปลภาษาสเปนสำหรับบทเรียน 5`
- `[Docs] อัปเดตคำแนะนำการตั้งค่า`

### การตรวจสอบที่จำเป็น

ก่อนส่ง PR:

1. **คุณภาพโค้ด**:
   - รัน `npm run lint` ในไดเรกทอรีโครงการที่ได้รับผลกระทบ
   - แก้ไขข้อผิดพลาดและคำเตือน lint ทั้งหมด

2. **ตรวจสอบการสร้าง**:
   - รัน `npm run build` หากมี
   - ตรวจสอบไม่มีข้อผิดพลาดการสร้าง

3. **ตรวจสอบลิงก์**:
   - ทดสอบลิงก์ Markdown ทั้งหมด
   - ตรวจสอบอ้างอิงรูปภาพใช้งานได้

4. **ตรวจสอบเนื้อหา**:
   - พิสูจน์อักษรเรื่องการสะกดและไวยากรณ์
   - ตรวจสอบตัวอย่างโค้ดถูกต้องและเหมาะสมสำหรับการศึกษา
   - ตรวจสอบการแปลรักษาความหมายต้นฉบับ

### ข้อกำหนดการร่วม

- ยอมรับ Microsoft CLA (มีการตรวจสอบอัตโนมัติใน PR แรก)
- ปฏิบัติตาม [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
- ดู [CONTRIBUTING.md](./CONTRIBUTING.md) สำหรับแนวทางรายละเอียด
- อ้างถึงหมายเลข issue ในคำอธิบาย PR หากเกี่ยวข้อง

### กระบวนการตรวจสอบ

- PR ถูกตรวจโดยผู้ดูแลและชุมชน
- ให้ความสำคัญกับความชัดเจนด้านการศึกษา
- ตัวอย่างโค้ดควรตามแนวปฏิบัติที่ดีที่สุดปัจจุบัน
- การแปลตรวจสอบความถูกต้องและเหมาะสมทางวัฒนธรรม

## ระบบแปลภาษา

### การแปลอัตโนมัติ

- ใช้ GitHub Actions กับเวิร์กโฟลว์ co-op-translator
- แปลเป็น 50+ ภาษาโดยอัตโนมัติ
- ไฟล์ต้นทางในไดเรกทอรีหลัก
- ไฟล์แปลในโครงสร้าง `translations/{language-code}/`

### การเพิ่มความสมบูรณ์ของการแปลด้วยตนเอง

1. หาไฟล์ใน `translations/{language-code}/`
2. ปรับปรุงโดยเก็บโครงสร้างเดิม
3. ตรวจสอบให้ตัวอย่างโค้ดยังคงทำงานได้
4. ทดสอบเนื้อหาแบบทดสอบแปลท้องถิ่น

### ข้อมูลเมตาของการแปล

ไฟล์แปลมีส่วนหัวข้อมูลเมตา:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## การดีบักและแก้ไขปัญหา

### ปัญหาทั่วไป

**Quiz app เริ่มต้นไม่ขึ้น**:
- ตรวจสอบเวอร์ชัน Node.js (แนะนำ v14+)
- ลบ `node_modules` และ `package-lock.json` แล้วรัน `npm install` ใหม่
- ตรวจสอบปัญหาพอร์ตซ้ำซ้อน (โดยปกติ Vite ใช้พอร์ต 5173)

**เซิร์ฟเวอร์ API เริ่มต้นไม่ขึ้น**:
- ตรวจสอบเวอร์ชัน Node.js ว่าตรงตามขั้นต่ำ (node >=10)
- ตรวจสอบว่าพอร์ตไม่ถูกใช้งานแล้ว
- แน่ใจว่าติดตั้ง dependencies ทั้งหมดด้วย `npm install`

**ส่วนขยายเบราว์เซอร์ไม่โหลด**:
- ตรวจสอบว่า manifest.json ฟอร์แมตถูกต้อง
- ตรวจดูคอนโซลเบราว์เซอร์หาข้อผิดพลาด
- ทำตามคำแนะนำการติดตั้งส่วนขยายที่เจาะจงเบราว์เซอร์

**ปัญหาโครงการแชท Python**:
- ติดตั้งแพ็กเกจ OpenAI: `pip install openai`
- ตรวจสอบว่า environment variable GITHUB_TOKEN ถูกตั้งค่า
- ตรวจสอบสิทธิ์การเข้าถึง GitHub Models

**Docsify ไม่ให้บริการเอกสาร**:
- ติดตั้ง docsify-cli ทั่วโลก: `npm install -g docsify-cli`
- รันจากโฟลเดอร์หลักของรีโพสิตอรี
- ตรวจว่า `docs/_sidebar.md` มีอยู่

### คำแนะนำสภาพแวดล้อมพัฒนา

- ใช้ VS Code พร้อมส่วนขยาย Live Server สำหรับโครงการ HTML
- ติดตั้งส่วนขยาย ESLint และ Prettier เพื่อรูปแบบโค้ดสม่ำเสมอ
- ใช้ DevTools ของเบราว์เซอร์ในการดีบัก JavaScript
- สำหรับโครงการ Vue ติดตั้งส่วนขยาย Vue DevTools ในเบราว์เซอร์

### ข้อควรพิจารณาด้านประสิทธิภาพ

- จำนวนไฟล์แปลมาก (50+ ภาษา) ทำให้การโคลนเต็มมีขนาดใหญ่
- ใช้ shallow clone หากทำงานกับเนื้อหาอย่างเดียว: `git clone --depth 1`
- ยกเว้นการค้นหาในโฟลเดอร์แปลเมื่อทำงานกับเนื้อหาอังกฤษ
- กระบวนการสร้างอาจช้าในรอบแรก (npm install, การสร้าง Vite)

## ข้อควรระวังด้านความปลอดภัย

### ตัวแปรสภาพแวดล้อม

- ไม่ควร commit คีย์ API ลงในรีโพสิตอรี
- ใช้ไฟล์ `.env` (ที่มีใน `.gitignore` แล้ว)
- แจ้งตัวแปรสภาพแวดล้อมที่จำเป็นใน README ของโครงการ

### โครงการ Python

- ใช้สภาพแวดล้อมเสมือน: `python -m venv venv`
- อัปเดต dependencies อยู่เสมอ
- โทเค็น GitHub ควรมีสิทธิ์จำกัดตามจำเป็น

### การเข้าถึง GitHub Models

- ต้องใช้ Personal Access Tokens (PAT) เพื่อ GitHub Models
- โทเค็นควรเก็บเป็นตัวแปรสภาพแวดล้อม
- ห้าม commit โทเค็นหรือข้อมูลรับรอง

## หมายเหตุเพิ่มเติม

### กลุ่มเป้าหมาย

- ผู้เริ่มต้นใหม่ทั้งหมดในการพัฒนาเว็บ
- นักเรียนและผู้เรียนด้วยตนเอง
- ครูผู้ใช้หลักสูตรในห้องเรียน
- เนื้อหาออกแบบเพื่อการเข้าถึงและสร้างทักษะทีละขั้น

### ปรัชญาการศึกษา

- วิธีการเรียนรู้โดยโครงการ
- การตรวจสอบความรู้เป็นระยะ (แบบทดสอบ)
- แบบฝึกหัดเขียนโค้ดจริง
- ตัวอย่างการใช้งานโลกจริง
- เน้นพื้นฐานก่อนเฟรมเวิร์ก

### การบำรุงรักษารีโพสิตอรี

- ชุมชนผู้เรียนและผู้ร่วมพัฒนาอย่างแข็งขัน
- อัปเดต dependencies และเนื้อหาเป็นประจำ
- ติดตามปัญหาและการสนทนาโดยผู้ดูแล
- อัปเดตการแปลโดยอัตโนมัติผ่าน GitHub Actions

### แหล่งข้อมูลที่เกี่ยวข้อง

- [โมดูล Microsoft Learn](https://docs.microsoft.com/learn/)
- [แหล่งข้อมูล Student Hub](https://docs.microsoft.com/learn/student-hub/)
- แนะนำให้ใช้ [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) สำหรับผู้เรียน
- คอร์สเพิ่มเติม: Generative AI, Data Science, ML, หลักสูตร IoT พร้อมใช้งาน

### การทำงานกับโครงการเฉพาะ

สำหรับคำแนะนำโดยละเอียดของแต่ละโครงการ ดูไฟล์ README ที่:
- `quiz-app/README.md` - แอปแบบทดสอบ Vue 3
- `7-bank-project/README.md` - แอปธนาคารพร้อมระบบยืนยันตัวตน
- `5-browser-extension/README.md` - การพัฒนาส่วนขยายเบราว์เซอร์
- `6-space-game/README.md` - การพัฒนาเกมด้วย Canvas
- `9-chat-project/README.md` - โครงการผู้ช่วยแชท AI

### โครงสร้างมอนอรีโพ (Monorepo)

แม้จะไม่ใช่มอนอรีโพแบบดั้งเดิม แต่รีโพสิตอรีนี้มีหลายโครงการอิสระ:
- บทเรียนแต่ละอันแยกตัวเอง
- โครงการไม่แชร์ dependencies กัน
- ทำงานกับโครงการแต่ละอันโดยไม่กระทบกัน
- โคลนรีโพสิตอรีทั้งชุดเพื่อประสบการณ์หลักสูตรเต็มรูปแบบ

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ข้อจำกัดความรับผิดชอบ**:  
เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้ว่าเราจะพยายามรักษาความถูกต้อง แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อนได้ เอกสารต้นฉบับในภาษาดั้งเดิมถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้การแปลโดยมืออาชีพที่เป็นมนุษย์ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดใด ๆ ที่เกิดขึ้นจากการใช้การแปลนี้
<!-- CO-OP TRANSLATOR DISCLAIMER END -->