You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Web-Dev-For-Beginners/translations/th/AGENTS.md

415 lines
25 KiB

<!--
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) แม้ว่าเราจะพยายามให้การแปลมีความถูกต้อง แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาดั้งเดิมควรถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้บริการแปลภาษามนุษย์ที่เป็นมืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดจากการใช้การแปลนี้