# 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
```

### Bank Project 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
```

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

```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 ตามความหมาย
- หลักการออกแบบตอบสนอง (Responsive)
- กฎการตั้งชื่อตัวแปรคลาสที่ชัดเจน
- คอมเมนต์อธิบายเทคนิค CSS สำหรับผู้เรียน

### Python

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

### เอกสาร 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` สร้าง bundle สำหรับโปรดักชัน
- โครงการสแตติก: ไม่มีขั้นตอนการสร้าง ให้บริการไฟล์โดยตรง

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

### รูปแบบชื่อเรื่อง

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

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

ก่อนส่ง PR:

1. **คุณภาพโค้ด**:
   - รัน `npm run 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. ทดสอบเนื้อหาแบบทดสอบในท้องถิ่น

### เมตาดาต้าแปลภาษา

ไฟล์แปลจะมีส่วนหัว metadata:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

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

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

**แอปแบบทดสอบไม่เริ่มทำงาน**:
- ตรวจสอบเวอร์ชัน 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`
- ตรวจสอบว่าตัวแปรสภาพแวดล้อม GITHUB_TOKEN ถูกตั้งค่าแล้ว
- ตรวจสอบสิทธิ์การเข้าถึงโมเดล GitHub

**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)

## การพิจารณาด้านความปลอดภัย

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

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

### โครงการ Python

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

### การเข้าถึงโมเดล GitHub

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

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

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

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

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

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

### การดูแลรักษาที่เก็บ

- ชุมชนผู้เรียนและผู้ร่วมมือที่แอคทีฟ
- อัปเดต 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) สำหรับผู้เรียน
- หลักสูตรเพิ่มเติม: AI สร้างสรรค์, วิทยาศาสตร์ข้อมูล, 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

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

---

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