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

Bank Project 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

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

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 ตามความหมาย
• หลักการออกแบบตอบสนอง (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:

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

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

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

ระบบแปลภาษา

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

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

การเพิ่มคุณภาพการแปลด้วยตนเอง

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

เมตาดาต้าแปลภาษา

ไฟล์แปลจะมีส่วนหัว metadata:

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

---

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