# 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

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

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

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

### Banking Project API (Node.js + Express)

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

### គម្រោង Browser Extension

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

### គម្រោង Space Game

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

### គម្រោង Chat (Python Backend)

```bash
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

```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 មានន័យសំខាន់
- គោលការណ៍រចនាបែបឆ្លាតវៃ
- ឈ្មោះថ្នាក់ដែលច្បាស់លាស់
- កំណត់ចំណាំបង្ហាញបច្ចេកទេស 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:

```bash
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

```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` បង្កើតកញ្ចប់ផលិតកម្ម
- គម្រោងជារបស់ស្ថិតិ៖ មិនមានដំណើរការបង្កើត ធ្វើសេវាទៅឯកសារផ្ទាល់ចុះ

## ការណែនាំសម្រាប់ 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](./CONTRIBUTING.md) សម្រាប់គោលការណ៍ពិសេស
- យោងលេខបញ្ហានៅក្នុងការពិពណ៌នារបស់ PR ប្រសិនបើមាន

### ដំណើរការពិនិត្យ

- PR ត្រូវបានពិនិត្យដោយអ្នកថែទាំ និងសហគមន៍
- ផ្តោតលើភាពច្បាស់ថ្លា និងការអប់រំ
- ឧទាហរណ៍កូដត្រូវតែគោរពតាមអនុវិធីល្អបំផុត
- បកប្រែត្រូវតែពិនិត្យភាពត្រឹមត្រូវ និងរចនាបថវប្បធម៌

## ប្រព័ន្ធបកប្រែ

### បកប្រែដោយស្វ័យប្រវត្តិ

- ប្រើ GitHub Actions និង co-op-translator workflow
- បកប្រែជាង ៥០ ភាសា ដោយស្វ័យប្រវត្តិ
- ឯកសារដើមនៅក្នុងថតមេ
- ឯកសារបកប្រែក្នុង `translations/{language-code}/`

### ការកែលម្អបកប្រែ ដោយដៃ

1. រកឃើញឯកសារ​នៅក្នុង `translations/{language-code}/`
2. បញ្ចូលការកែលម្អ បើក្សនាផ្លូវរចនាសម្ព័ន្ធ
3. ធានាឲ្យឧទាហរណ៍កូដនៅស្ថិតក្នុងសភាពដើម
4. សាកល្បងមាតិកាវិញ្ញាសា​ដែលបានបកប្រែ

### បញ្ជីមេតាអំពីបកប្រែ

ឯកសារបកប្រែរួមបញ្ចូលក្បាលទិន្នន័យមេតា៖
```markdown
<!--
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](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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
- អាចធ្វើការងារជាមួយគម្រោងឯកត្តដោយមិនប៉ះពាល់គ្នា
- ចម្លងឃ្លាំងទាំងមូលសម្រាប់បទពិសោធទាំងមូលនៃកម្មវិធីសិក្សា

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ការបដិសេធ**៖  
ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះបីយើងខំប្រឹងសម្រាប់ភាពត្រឹមត្រូវ ក៏សូមយល់ថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាដែលវាត្រូវបានគេប្រើជាភាសាមូលដ្ឋានគួរត្រូវបានគេចាត់ទុកជាធាតុយោងដែលមានសុពលភាព។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយអ្នកជំនាញមនុស្សគឺល្អជាង។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកប្រែខុសពីការប្រើប្រាស់បកប្រែនេះឡើយ។
<!-- CO-OP TRANSLATOR DISCLAIMER END -->