<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-03T11:28:21+00:00",
  "source_file": "AGENTS.md",
  "language_code": "th"
}
-->
# 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
```

### การตั้งค่าแอปแบบทดสอบ (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint
```

### API ของโปรเจกต์ธนาคาร (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier
```

### โปรเจกต์ส่วนขยายเบราว์เซอร์

```bash
cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions
```

### โปรเจกต์เกมอวกาศ

```bash
cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server
```

### โปรเจกต์แชท (Python Backend)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py
```

## เวิร์กโฟลว์การพัฒนา

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

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

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

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

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

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

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

### การทดสอบแอปแบบทดสอบ

```bash
cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds
```

### การทดสอบ API ของธนาคาร

```bash
cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors
```

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

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

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

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

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

### JavaScript

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

### HTML/CSS

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

### Python

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

### เอกสาร Markdown

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

### การจัดระเบียบไฟล์

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

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

### การปรับใช้แอปแบบทดสอบ (Azure Static Web Apps)

แอปแบบทดสอบถูกตั้งค่าสำหรับการปรับใช้ Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main
```

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

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

```bash
npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs
```

### เอกสาร Docsify

```bash
npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000
```

### การสร้างโปรเจกต์เฉพาะ

แต่ละไดเรกทอรีโปรเจกต์อาจมีขั้นตอนการสร้างของตัวเอง:
- โปรเจกต์ Vue: `npm run build` สร้างชุดโปรดักชัน
- โปรเจกต์ Static: ไม่มีขั้นตอนการสร้าง ให้บริการไฟล์โดยตรง

## แนวทางการส่ง 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) สำหรับแนวทางโดยละเอียด
- อ้างอิงหมายเลขปัญหาในคำอธิบาย 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": "..."
}
-->
```

## การแก้ไขข้อบกพร่องและการแก้ปัญหา

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

**แอปแบบทดสอบไม่เริ่มต้น**:
- ตรวจสอบเวอร์ชัน 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 Models

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

### เคล็ดลับสภาพแวดล้อมการพัฒนา

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

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

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

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

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

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

### โปรเจกต์ Python

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

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

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

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

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

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

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

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

### การดูแลคลัง

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

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

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](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

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

---

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