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

408 lines
24 KiB

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