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

AGENTS.md

ពិភាក្សាពីគម្រោង

នេះជាឃ្លាំងមេរៀនសិក្សាសម្រាប់បង្រៀនមូលដ្ឋាននៃការអភិវឌ្ឍវែបដល់អ្នកចាប់ផ្តើម។ មេរៀននេះជាកម្មវិធីសិក្សាពេញលេញរយៈពេល ១២ សប្តាហ៍ ដែលបានបង្កើតឡើងដោយអ្នករៀបចំកម្មវិធី Microsoft Cloud Advocates មានមេរៀនទាំងស្រុង ២៤ នៅក្នុងគម្រោងអនុវត្តន៍ដែលគ្របដណ្តប់លើ JavaScript, CSS និង HTML។

ផ្នែកសំខាន់ៗ

• មាតិកាសិក្សា៖ មេរៀន ២៤ ដែលមានរចនាសម្ព័ន្ធ ក្នុងម៉ូឌុលមូលដ្ឋានគម្រោង
• គម្រោងអនុវត្តន៍៖ Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor និង AI Chat Assistant
• វិញ្ញាសាបែបមានអន្តរកម្ម៖ វិញ្ញាសា ៤៨ ដែលមាន ៣ សំណួរក្នុងមួយវិញ្ញាសា (ប៉ុន្មានមុន / បន្ទាប់មេរៀន)
• គាំទ្រភាសាច្រើន៖ បកប្រែដោយស្វ័យប្រវត្តិជាង ៥០ ភាសា តាមរយៈ GitHub Actions
• បច្ចេកវិទ្យា៖ HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (សម្រាប់គម្រោង AI)

វិស្វកម្ម

• ឃ្លាំងសម្រាប់ការសិក្សា ជារចនាសម្ព័ន្ធមេរៀន
• តំបន់មេរៀននីមួយៗមាន README, ឧទាហរណ៍កូដ និងដំណោះស្រាយ
• គម្រោងឯកាពេញខុសគ្នា (quiz-app, គម្រោងមេរៀនផ្សេងៗ)
• ប្រព័ន្ធបកប្រែដោយ GitHub Actions (co-op-translator)
• ឯកសារបង្ហាញតាម Docsify និងមានជាទម្រង់ PDF

ពាក្យបញ្ជា Setup

ឃ្លាំងនេះសំរាប់ការប្រើប្រាស់មាតិកាសិក្សាសម្រាប់សិស្ស។ សម្រាប់ធ្វើការអនុវត្តន៍ជាមួយគម្រោងពិសេស៖

ការតំឡើងឃ្លាំងមេ

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

Banking Project API (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # ចាប់ផ្តើមម៉ាស៊ីនបម្រើ API
npm run lint       # ដំណើរការ ESLint
npm run format     # ទ្រង់ទ្រាយជាមួយ Prettier

គម្រោង Browser Extension

cd 5-browser-extension/solution
npm install
# អនុវត្តតាមការណែនាំការផ្ទុកបន្ថែមដែលជាក់លាក់ទ្វារទស្សនា

គម្រោង Space Game

cd 6-space-game/solution
npm install
# បើក index.html នៅក្នុងកម្មវិធីរុករក ឬប្រើ Live Server

គម្រោង Chat (Python Backend)

cd 9-chat-project/solution/backend/python
pip install openai
# កំណត់អថេរបរិបទ GITHUB_TOKEN
python api.py

ដំណើរការអភិវឌ្ឍ

សម្រាប់អ្នកចូលរួមដាក់ទិន្នន័យ

1. ចម្លងឃ្លាំងនេះ ទៅទៅគណនី GitHub របស់អ្នក
2. ចម្លងបង្កើតទីតាំងក្នុងម៉ាស៊ីនប័ណ្ណ របស់អ្នក
3. បង្កើតសាខាថ្មី សម្រាប់ការផ្លាស់ប្តូររបស់អ្នក
4. បង្កើតកំណែប្រែខ្លះៗលើមាតិកាមេរៀន ឬឧទាហរណ៍កូដ
5. សាកល្បងកូដនៅក្នុងថតគម្រោងពាក់ព័ន្ធ
6. បញ្ចូន pull requests ទៅតាមកម្រិតការចូលរួម

សម្រាប់អ្នករៀន

1. ចម្រាស់ឬចម្លងឃ្លាំងនេះ
2. ចូលទៅថតមេរៀនដោយជាប់លំដាប់
3. អានឯកសារ README នីមួយៗ
4. បញ្ចប់វិញ្ញាសាមុនមេរៀន នៅ https://ff-quizzes.netlify.app/web/
5. អនុវត្តឧទាហរណ៍កូដនៅថតមេរៀន
6. បញ្ចប់ការងារនិងសំណួរប្រកួតប្រជែង
7. ធ្វើវិញ្ញាសាបន្ទាប់មេរៀន

អភិវឌ្ឍបន្តផ្ទាល់

• ឯកសារ៖ រត់ docsify serve នៅថតឫស (port 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
• ឧទាហរណ៍កូដច្បាស់លាស់ និងផ្តោតលើការអប់រំ
• ចំណាំប្រភេទនៅកន្លែងមានប្រយោជន៍សម្រាប់ការសិក្សា

ឯកសារម៉ាគដោន

• រចនាសម្ព័ន្ធក្បាលច្បាស់លាស់
• ប្លុកកូដមានកំណត់ភាសា
• តំណទៅកាន់ធនធានបន្ថែម
• រូបភាព និងផ្ទាំងរូបនៅថត images/
• ចំណងជើងរូបភាពសម្រាប់ការចូលដល់អត្តសញ្ញាណ

រៀបចំឯកសារ

• មេរៀនត្រូវបានលេខរៀងជាលំដាប់ (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/
# ចាក់ផ្សាយតាមរយៈដំណើរការងារប្រតិបត្តិ GitHub Actions នៅពេលបញ្ចូនទៅ 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 នៅថតគម្រោងដែលពាក់ព័ន្ធ
   • ជួសជុលកំហុស និងសញ្ញាព្រមានទាំងអស់

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 workflow
• បកប្រែជាង ៥០ ភាសា ដោយស្វ័យប្រវត្តិ
• ឯកសារដើមនៅក្នុងថតមេ
• ឯកសារបកប្រែក្នុង 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 ម្ដងទៀត
• ពិនិត្យការប្រឈមមុខនឹងតំណរភ្ជាប់ port (លំនាំដើម៖ Vite ប្រើ port 5173)

API សេវាកម្មមិនចាប់ផ្តើម៖

• ពិនិត្យកំណែ Node.js >= 10
• ពិនិត្យថាតំណ port មិនត្រូវបានប្រើរួចហើយ
• ធានាថា dependencies ទាំងអស់បានដំឡើង npm install

Browser extension មិនត្រូវផ្ទុកទេ៖

• ពិនិត្យ manifest.json មានទ្រង់ទ្រាយត្រឹមត្រូវ
• ពិនិត្យកុងសូលរុករកសម្រាប់កំហុស
• អនុវត្ដតាមការណែនាំដំឡើង extension ក្រៅបណ្ដាញ

បញ្ហាគម្រោង Python chat៖

• ធានាបញ្ចូលកញ្ចប់ OpenAI៖ pip install openai
• ពិនិត្យថា GITHUB_TOKEN បានកំណត់ជាផ្លាកបរិស្ថាន
• ពិនិត្យសិទ្ធិចូលប្រើម៉ូដែល GitHub

Docsify មិនបង្ហាញឯកសារទេ៖

• ដំឡើង docsify-cli ទូទាំងប្រព័ន្ធ៖ npm install -g docsify-cli
• រត់ពីថតឫស repositories
• ពិនិត្យឯកសារ docs/_sidebar.md មានស្រាប់

អ្នកអភិវឌ្ឍផ្នែកបរិយាកាស

• ប្រើ VS Code ជាមួយ Live Server extension សម្រាប់គម្រោង HTML
• ដំឡើង ESLint និង Prettier extension សម្រាប់លំអរយក
• ប្រើ DevTools រុករកសម្រាប់ដោះស្រាយជំហាន JavaScript
• សម្រាប់គម្រោង Vue, ដំឡើង Vue DevTools extension រុករក

ចំណាំសមត្ថភាព

• ចំនួនឯកសារបកប្រែច្រើន (ជាង ៥០ ភាសា) មានទំហំធំ
• ប្រើ shallow clone ប្រសិនបើគ្រាន់តែធ្វើការងារជាមួយមាតិកា៖ git clone --depth 1
• មិនស្វែងរកក្នុងបកប្រែពេលធ្វើការជាមួយមាតិកាអង់គ្លេស
• ដំណើរការប្រមូលផលអាចប្រហែលយឺតនៅលើការដំណើរការដំបូង (npm install, របៀប build Vite)

ចំណុចសុវត្ថិភាព

ផ្លាកបរិស្ថាន

• កូនសោ API មិនគួរត្រូវបានបញ្ចូលក្នុងឃ្លាំង
• ប្រើឯកសារ .env (មានរួចក្នុង .gitignore)
• រៀបរាប់ប្រាប់ពីផ្លាកបរិស្ថានចាំបាច់ក្នុង README គម្រោង

គម្រោង Python

• ប្រើបរិយាកាសវេរ៉ែល (virtual environments): python -m venv venv
• រក្សាអាប់ដេត dependencies ជានិច្ច
• ស្លាក GitHub token ត្រូវមានសិទ្ធិចូលតិចតួចបំផុត

សិទ្ធិចូលម៉ូដែល GitHub

• ត្រូវការបាន Personal Access Tokens (PAT) សម្រាប់ពេលប្រើម៉ូដែល GitHub
• ត្រូវរក្សាគោលបំណងស្លាកជា environment variable
• មិនគួរបញ្ចូលលេខសម្ងាត់ឬកូនសោឡើយ

កំណត់សម្គាល់បន្ថែម

គោលដៅអ្នកប្រើប្រាស់

• អ្នកចាប់ផ្តើមបំពេញក្នុងការអភិវឌ្ឍវែប
• សិស្ស និងអ្នករៀនដោយខ្លួនឯង
• គ្រូបង្រៀនដែលប្រើមេរៀននៅថ្នាក់សិក្សា
• មាតិកាផ្ដោតលើភាពងាយស្រួល និងការកែលម្អជារបៀបជាប់ជាលំដាប់

ទស្សនវិជ្ជាអប់រំ

• វិធីសាស្ត្រសិក្សាជាគម្រោង
• ការត្រួតពិនិត្យចំណេះដឹងជាប្រចាំ (វិញ្ញាសា)
• អនុវត្តន៍​កូដ​ដោយដៃ
• ឧទាហរណ៍នៃកម្មវិធីពិតប្រាកដ
• ព្រមទាំងផ្ដោតលើមូលដ្ឋាន មុនចូលទៅ framework

ការថែទាំឃ្លាំង

• សហគមន៍សកម្មនៃអ្នករៀន និងអ្នកចូលរួម
• បន្តពិនិត្យ និងធ្វើបច្ចុប្បន្នភាពលើ dependencies និងមាតិកា
• ចំណុចបញ្ហា និងការពិភាក្សាត្រូវបានគ្រប់គ្រងដោយអ្នកថែទាំ
• ការអាប់ដេតបកប្រែធ្វើដោយស្វ័យប្រវត្តិតាម GitHub Actions

ធនធានដែលពាក់ព័ន្ធ

• Microsoft Learn modules
• Student Hub resources
• GitHub Copilot ផ្ដល់អនុសាសន៍សម្រាប់អ្នករៀន
• គរូបិសេសផ្សេងៗ: Generative AI, Data Science, ML, IoT បណ្ដុះបណ្ដាលមាន

ធ្វើការជាមួយគម្រោងពិសេស

សម្រាប់ការណែនាំលម្អិតនៃគម្រោងជាក់លាក់សូមមើលឯកសារ README នៅក្នុង៖

• quiz-app/README.md - កម្មវិធី quiz Vue 3
• 7-bank-project/README.md - កម្មវិធីធនាគារជាមួយការផ្ទៀងផ្ទាត់
• 5-browser-extension/README.md - ការអភិវឌ្ឍ browser extension
• 6-space-game/README.md - ការបង្កើតហ្គេមប្លុក canvas
• 9-chat-project/README.md - គម្រោងជំនួយការជជែក AI

រចនាសម្ព័ន្ធ Monorepo

ទោះបីមិនមែនជាការប្រមូលគ្នារូបមន្តចម្រុះនោះ ក៏ឃ្លាំងនេះមានគម្រោងឯករាជ្យច្រើន៖

• មេរៀននីមួយៗមានជាពិសេស
• គម្រោងមិនចែករំលែក dependencies
• អាចធ្វើការងារជាមួយគម្រោងឯកត្តដោយមិនប៉ះពាល់គ្នា
• ចម្លងឃ្លាំងទាំងមូលសម្រាប់បទពិសោធទាំងមូលនៃកម្មវិធីសិក្សា

---

ការបដិសេធ៖
ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែ AI Co-op Translator។ ទោះបីយើងខំប្រឹងសម្រាប់ភាពត្រឹមត្រូវ ក៏សូមយល់ថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាដែលវាត្រូវបានគេប្រើជាភាសាមូលដ្ឋានគួរត្រូវបានគេចាត់ទុកជាធាតុយោងដែលមានសុពលភាព។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយអ្នកជំនាញមនុស្សគឺល្អជាង។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកប្រែខុសពីការប្រើប្រាស់បកប្រែនេះឡើយ។