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