Web-Dev-For-Beginners/translations/th/AGENTS.md

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

คำสั่งติดตั้ง

รีโพสิตอรีนี้เน้นสำหรับการบริโภคเนื้อหาการศึกษาหลัก หากต้องการทำงานกับโครงการเฉพาะ:

การตั้งค่าหลักของรีโพสิตอรี

git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners

การตั้งค่า Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # เริ่มต้นเซิร์ฟเวอร์สำหรับพัฒนา
npm run build      # สร้างสำหรับการผลิต
npm run lint       # รัน ESLint

API โครงการธนาคาร (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # เริ่มเซิร์ฟเวอร์ API
npm run lint       # รัน ESLint
npm run format     # จัดรูปแบบด้วย Prettier

โครงการส่วนขยายเบราว์เซอร์

cd 5-browser-extension/solution
npm install
# ทำตามคำแนะนำการโหลดส่วนขยายเฉพาะของเบราว์เซอร์

โครงการเกมอวกาศ

cd 6-space-game/solution
npm install
# เปิดไฟล์ index.html ในเบราว์เซอร์หรือใช้ Live Server

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

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

cd quiz-app
npm run lint       # ตรวจสอบปัญหาสไตล์โค้ด
npm run build      # ยืนยันการสร้างสำเร็จ

การทดสอบ Bank API

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:

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

npm install                    # ติดตั้ง docsify-to-pdf
npm run convert               # สร้าง PDF จาก docs

เอกสาร Docsify

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
• ดู CONTRIBUTING.md สำหรับแนวทางรายละเอียด
• อ้างถึงหมายเลข issue ในคำอธิบาย PR หากเกี่ยวข้อง

กระบวนการตรวจสอบ

• PR ถูกตรวจโดยผู้ดูแลและชุมชน
• ให้ความสำคัญกับความชัดเจนด้านการศึกษา
• ตัวอย่างโค้ดควรตามแนวปฏิบัติที่ดีที่สุดปัจจุบัน
• การแปลตรวจสอบความถูกต้องและเหมาะสมทางวัฒนธรรม

ระบบแปลภาษา

การแปลอัตโนมัติ

• ใช้ GitHub Actions กับเวิร์กโฟลว์ co-op-translator
• แปลเป็น 50+ ภาษาโดยอัตโนมัติ
• ไฟล์ต้นทางในไดเรกทอรีหลัก
• ไฟล์แปลในโครงสร้าง translations/{language-code}/

การเพิ่มความสมบูรณ์ของการแปลด้วยตนเอง

1. หาไฟล์ใน translations/{language-code}/
2. ปรับปรุงโดยเก็บโครงสร้างเดิม
3. ตรวจสอบให้ตัวอย่างโค้ดยังคงทำงานได้
4. ทดสอบเนื้อหาแบบทดสอบแปลท้องถิ่น

ข้อมูลเมตาของการแปล

ไฟล์แปลมีส่วนหัวข้อมูลเมตา:

<!--
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
• แหล่งข้อมูล Student Hub
• แนะนำให้ใช้ 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 กัน
• ทำงานกับโครงการแต่ละอันโดยไม่กระทบกัน
• โคลนรีโพสิตอรีทั้งชุดเพื่อประสบการณ์หลักสูตรเต็มรูปแบบ

---

ข้อจำกัดความรับผิดชอบ:
เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI Co-op Translator แม้ว่าเราจะพยายามรักษาความถูกต้อง แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อนได้ เอกสารต้นฉบับในภาษาดั้งเดิมถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้การแปลโดยมืออาชีพที่เป็นมนุษย์ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดใด ๆ ที่เกิดขึ้นจากการใช้การแปลนี้