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

การตั้งค่าแอปแบบทดสอบ (Vue 3 + Vite)

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)

cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier

โปรเจกต์ส่วนขยายเบราว์เซอร์

cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions

โปรเจกต์เกมอวกาศ

cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server

โปรเจกต์แชท (Python Backend)

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 ที่เกี่ยวข้อง

คำแนะนำการทดสอบ

การทดสอบแอปแบบทดสอบ

cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds

การทดสอบ API ของธนาคาร

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:

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

npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs

เอกสาร Docsify

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
• ดู CONTRIBUTING.md สำหรับแนวทางโดยละเอียด
• อ้างอิงหมายเลขปัญหาในคำอธิบาย 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": "..."
}
-->

การแก้ไขข้อบกพร่องและการแก้ปัญหา

ปัญหาทั่วไป

แอปแบบทดสอบไม่เริ่มต้น:

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