# AGENTS.md

## ទិដ្ឋភាពគម្រោង

Data Science for Beginners គឺជាកម្មវិធីបណ្តុះបណ្តាលរយៈពេល ១០ សប្តាហ៍ និង ២០ មេរៀន ដែលបានបង្កើតឡើងដោយអ្នកអភិវឌ្ឍន៍ Microsoft Azure Cloud Advocates។​ ឃ្លាំងកូដនេះជាធនធានការសិក្សាដែលបង្រៀនគំនិតមូលដ្ឋានវិទ្យាសាស្ត្រទិន្នន័យតាមរយៈមេរៀនផ្អែកលើគម្រោង រួមទាំងសៀវភៅចំណាំ Jupyter, ប្រលងអន្ដរកម្ម និងភារកិច្ចអនុវត្តដោយដៃ។

**បច្ចេកវិទ្យាសំខាន់ៗ៖**
- **សៀវភៅចំណាំ Jupyter**: ប្រព័ន្ធសិក្សាចម្បងដោយប្រើ Python 3
- **បណ្ណាល័យ Python**: pandas, numpy, matplotlib សម្រាប់វិភាគ និងតំណាងទិន្នន័យ
- **Vue.js 2**: កម្មវិធីប្រលង (ថតឌីរ quiz-app)
- **Docsify**: រក្សាទុកគេហទំព័រអត្ថបទអាចប្រើបានក្រៅបណ្តាញ
- **Node.js/npm**: គ្រប់គ្រងកញ្ចប់ផ្នែកកម្មវិធី JavaScript
- **Markdown**: អត្ថបទមេរៀន និងឯកសារ

**រចនាសម្ព័ន្ធ៖**
- ឃ្លាំងកូដសិក្សាបណ្ដាញភាសាច្រើនជាមួយការបញ្ចូលភាសាច្រើន
- រៀបចំជាម៉ូឌុលមេរៀន (១-បើកកម្មវិធី ដល់ ៦-វិទ្យាសាស្ត្រទិន្នន័យក្នុងធម្មជាតិ)
- មេរៀនមួយៗមាន README, សៀវភៅចំណាំ, ភារកិច្ច និងប្រលង
- កម្មវិធី Vue.js ប្រលងឯករাজ្យសម្រាប់វាស់វែងមុននិងក្រោយមេរៀន
- គាំទ្រដំណើរការជាមួយ GitHub Codespaces និង VS Code dev containers

## ពាក្យបញ្ជាសំណុំត្រា

### ការតំឡើងឃ្លាំងកូដ
```bash
# ចម្លងគម្រោងនេះ (ប្រសិនបើមិនបានចម្លងរួច)
git clone https://github.com/microsoft/Data-Science-For-Beginners.git
cd Data-Science-For-Beginners
```

### ការតំឡើងបរិស្ថាន Python
```bash
# បង្កើតបរិស្ថានវើចួអាល់ (ត្រូវបានណែនាំ)
python -m venv venv
source venv/bin/activate  # លើ Windows: venv\Scripts\activate

# ធ្វើការដំឡើងបណ្ណាល័យវិទ្យាសាស្ត្រទិន្នន័យទូទៅ (មិនមាន requirements.txt)
pip install jupyter pandas numpy matplotlib seaborn scikit-learn
```

### ការតំឡើងកម្មវិធីប្រលង
```bash
# បញ្ជាទៅកម្មវិធីសំណួរ
cd quiz-app

# តំឡើងផ្នែកផ្គត់ផ្គង់
npm install

# ចាប់ផ្តើមម៉ាស៊ីនមេអភិវឌ្ឍន៍
npm run serve

# សង់សម្រាប់ផលិតកម្ម
npm run build

# ពិនិត្យ និងកែប្រែឯកសារ
npm run lint
```

### ម៉ាស៊ីនបម្រើឯកសារ Docsify
```bash
# តំឡើង Docsify ជាទូទៅ
npm install -g docsify-cli

# បម្រើឯកសារជាផ្ទាល់ក្នុងម៉ាស៊ីន
docsify serve

# ឯកសារនឹងមានស្រាប់នៅ localhost:3000
```

### ការតំឡើងគម្រោងតំណាងទិន្នន័យ
សម្រាប់គម្រោងដូចជា meaningful-visualizations (មេរៀនលេខ ១៣):
```bash
# ធ្វើដំណើរទៅថតស្តាតឬដំណោះស្រាយ
cd 3-Data-Visualization/13-meaningful-visualizations/starter

# តំឡើងការពឹងផ្អែក
npm install

# ចាប់ផ្តើមម៉ាស៊ីនបម្រើអភិវឌ្ឍន៍
npm run serve

# បង្កើតសម្រាប់ផលិតកម្ម
npm run build

# ពិនិត្យឯកសារ
npm run lint
```

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

### ការប្រើប្រាស់សៀវភៅចំណាំ Jupyter
១. ចាប់ផ្តើម Jupyter នៅចំណុចគោលឃ្លាំងកូដ: `jupyter notebook`  
២. ទៅកាន់ថតមេរៀនដែលចង់ធ្វើការ  
៣. បើកឯកសារ `.ipynb` ដើម្បីអនុវត្តកិច្ចការផ្សេងៗ  
៤. សៀវភៅចំណាំមានការពន្យល់និងក្រឡាចត្រង្គកូដដោយខ្លួនឯង  
៥. សៀវភៅចំណាំភាគច្រើនប្រើ pandas, numpy និង matplotlib - ត្រូវប្រាកដថាតំឡើងរួច

### រចនាសម្ព័ន្ធមេរៀន
មេរៀនមួយៗទូទៅមាន៖
- `README.md` - អត្ថបទមេរៀនសំខាន់ ទ្រង់ទ្រាយ ទ្រឹស្តី និងឧទាហរណ៍  
- `notebook.ipynb` - កិច្ចការអនុវត្តជាមួយ Jupyter notebook  
- `assignment.ipynb` ឬ `assignment.md` - ភារកិច្ចសម្រួល  
- ថត `solution/` - សៀវភៅចំណាំនិងកូដដោះស្រាយ  
- ថត `images/` - រូបភាពគាំទ្រ

### ការអភិវឌ្ឍកម្មវិធីប្រលង
- កម្មវិធី Vue.js 2 មានប្រព័ន្ធបញ្ចូលកូដបន្ត ដែលអាចកែបានភ្លាមៗពេលអភិវឌ្ឍ  
- ប្រលងផ្ទុកនៅក្នុងថត `quiz-app/src/assets/translations/`  
- ភាសាផ្សេងៗមានថតបកប្រែផ្ទាល់ខ្លួន (en, fr, es, ល។)  
- លេខប្រលងចាប់ពី ០ ដល់ ៣៩ (មាន ៤០ ប្រលងសរុប)

### ការបញ្ចូលការបកប្រែ
- ការបកប្រែស្ថិតនៅក្នុងថត `translations/` នៅក្បែរគោលឃ្លាំងកូដ  
- ភាសាផ្សេងគ្នាគឺមានរចនាសម្ព័ន្ធមេរៀនពេញលេញជាs តាមរយៈ English ដែលបានចំលង  
- ការបកប្រែធ្វើដោយម៉ាស៊ីនតាម GitHub Actions (co-op-translator.yml)

## ការណែនាំសម្រាប់ធ្វើតេស្ត

### ការធ្វើតេស្តកម្មវិធីប្រលង
```bash
cd quiz-app

# បញ្ជា​លីន​ជ្រើស​រើស
npm run lint

# ពិនិត្យ​ដំណើរការសាងសង់
npm run build

# ការប្រឡងដោយដៃ: ចាប់ផ្តើមម៉ាស៊ីនបម្រើ dev និងផ្ទៀងផ្ទាត់មុខងារប្រលង
npm run serve
```

### ការធ្វើតេស្តសៀវភៅចំណាំ
- គ្មានស៊ុមតេស្តស្វ័យប្រវត្តសម្រាប់សៀវភៅចំណាំទេ  
- តេស្តដោយដៃ៖ បើកក្រឡាចត្រង្គគ្រប់ផ្នែក ដើម្បីប្រាកដថាគ្មានកំហុស  
- ពិនិត្យឯកសារទិន្នន័យអាចចូលប្រើបាន និងលទ្ធផលបានបង្កើតត្រឹមត្រូវ  
- ពិនិត្យការតំណាងទិន្នន័យសមរម្យ

### ការធ្វើតេស្តឯកសារ
```bash
# បញ្ជាក់ថា Docsify បង្ហាញបានត្រឹមត្រូវ
docsify serve

# ពិនិត្យមើលតំណខូចដោយដៃតាមរយៈការស្វែងរកក្នុងមាតិកា
# បញ្ជាក់ថាតំណមេរៀនទាំងអស់ដំណើរការជាលម្អិតក្នុងឯកសារដែលបានបង្ហាញ
```

### ការត្រួតពិនិត្យគុណភាពកូដ
```bash
# គម្រោង Vue.js (កម្មវិធីសំណួរនិងគម្រោង Visualization)
cd quiz-app  # ឬថតគម្រោង Visualization
npm run lint

# សៀវភៅកំណត់ត្រា Python - សូមផ្ដល់អនុសាសន៍ការត្រួតពិនិត្យដោយដៃ
# ធានាថាការនាំចូលដំណើរការត្រឹមត្រូវ និងកោសិកាធ្វើការបញ្ចប់ដោយគ្មានកំហុស
```

## ទ្រឹស្តីលីហ្គិសម្រាប់កូដ

### Python (សៀវភៅចំណាំ Jupyter)
- បន្តតាមមាត្រដ្ឋាន PEP 8 សម្រាប់កូដ Python  
- ប្រើឈ្មោះអថេរល្អ ឱ្យប្រាប់ពីទិន្នន័យដែលកំពុងវិភាគ  
- រួមបញ្ចូលte ផ្នែក markdown ដោយមានការពន្យល់មុនកុងតោងកូដ  
- កូដនៅក្នុងក្រឡាចត្រង្គមានមនោសញ្ចេតនាតែមួយ  
- ប្រើ pandas សម្រាប់កែប្រែទិន្នន័យ, matplotlib សម្រាប់គំនូស  
- រូបមន្តនាំចូលទូទៅ៖  
  ```python
  import pandas as pd
  import numpy as np
  import matplotlib.pyplot as plt
  ```

### JavaScript/Vue.js
- បន្តតាមមគ្គុទេសក៍ Vue.js 2 និងអនុវត្តល្អ  
- កំណត់ប្រែ ESLint នៅក្នុង `quiz-app/package.json`  
- ប្រើផ្សេង Vue ឯកសារតែមួយ (.vue)  
- រក្សារចនាសម្ព័ន្ធមូលដ្ឋានតាមបែបតំបន់  
- រត់ `npm run lint` មុនបញ្ចូលកូដ

### ឯកសារអត្ថបទ Markdown
- ប្រើកម្រិតមុខងារច្បាស់ (# ## ###)  
- រួមបញ្ចូលកូដនៅក្នុងប្លុកជាមួយនិយមន័យភាសា  
- បន្ថែមអត្ថបទជំនួសរូបភាព  
- តំណភ្ជាប់ទៅមេរៀន និងធនធានទាក់ទង  
- រក្សារវាងបន្ទាត់អាចអានបាន

### ការរៀបចំឯកសារ
- អត្ថបទមេរៀននៅក្នុងថតលេខ (01-defining-data-science ល។)  
- ដោះស្រាយនៅក្នុងថត `solution/` ផ្ទាល់ខ្លួន  
- បកប្រែតាមរចនាសម្ព័ន្ធ English នៅថត `translations/`  
- រក្សា​ឯកសារទិន្នន័យ​នៅ​ក្នុងថត `data/` ឬថតមេរៀន

## ការសាងសង់ និងចែកចាយ

### ការចែកចាយកម្មវិធីប្រលង
```bash
cd quiz-app

# បង្កើតកំណែផលិតកម្ម
npm run build

# លទ្ធផលត្រូវបានរក្សាទុកនៅក្នុងថត dist/
# ការដាក់ឯកសារ dist/ ទៅកាន់ម៉ាស៊ីនផ្ទុកស្ថាបត្យកម្ម (Azure Static Web Apps, Netlify, ល។)
```

### ការចែកចាយក្នុង Azure Static Web Apps
កម្មវិធីប្រលងអាចចែកចាយទៅ Azure Static Web Apps៖  
១. បង្កើតធនធាន Azure Static Web App  
២. ភ្ជាប់ជាមួយឃ្លាំងកូដ GitHub  
៣. រៀបចំការកំណត់សាងសង់៖  
   - ទីតាំងកម្មវិធី៖ `quiz-app`  
   - ទីតាំងលទ្ធផល៖ `dist`  
៤. GitHub Actions នឹងធ្វើដំណើរចែកចាយដោយស្វ័យប្រវត្តិពេលឈ្នះ push

### គេហទំព័រឯកសារ
```bash
# សាងសង់ PDF ពី Docsify (ជាជម្រើស)
npm run convert

# ឯកសារ Docsify ត្រូវបានបម្រើដោយផ្ទាល់ពីឯកសារ markdown
# មិនត្រូវការជំហានសាងសង់សម្រាប់ការដាក់បង្ហាញ
# ដាក់បង្ហាញឃ្លាំងទៅបណ្តាញផ្តាំថេរជាមួយ Docsify
```

### GitHub Codespaces
- ឃ្លាំងកូដមានការកំណត់ dev container  
- Codespaces រៀបចំពីលើ Python និង Node.js ដោយស្វ័យប្រវត្តិ  
- បើកឃ្លាំងកូដក្នុង Codespace តាម UI GitHub  
- ឯកតា dependencies ទាំងអស់ត្រូវបានដំឡើងដោយស្វ័យប្រវត្តិ

## ទ្រឹស្តីសម្រាប់ដាក់ស្នើ Pull Request

### មុនដាក់ស្នើ
```bash
# សម្រាប់ការផ្លាស់ប្តូរនៅក្នុង Vue.js ក្នុងកម្មវិធីប្រឡង
cd quiz-app
npm run lint
npm run build

# សាកល្បងការផ្លាស់ប្តូរប្រក្បុងក្រោម
npm run serve
```

### ទ្រង់ទ្រាយចំណងជើង PR
- ប្រើចំណងជើងច្បាស់ សង្ខេប  
- ទ្រង់ទ្រាយ៖ `[Component] សង្ខេបខ្លី`  
- ឧទាហរណ៍ៈ  
  - `[Lesson 7] ដោះស្រាយកំហុសនាំចូលសៀវភៅ Python`  
  - `[Quiz App] បន្ថែមការបកប្រែភាសាអាឡឺម៉ង់`  
  - `[Docs] បរិច្ចាគ README ជាមួយលក្ខណៈជាមុន`

### ការត្រួតពិនិត្យចាំបាច់
- ធ្វើការ Run កូដគ្រប់ខុសត្រូវ  
- ប្រាកដថាសៀវភៅចំណាំរត់បានគ្រប់  
- រត់កំណត់ Vue.js បានដោយជោគជ័យ  
- ពិនិត្យតំណរ ឯកសារ ងាយស្រួលចូលប្រើ  
- ប្រាកដថាកម្មវិធីប្រលងបញ្ចូលបញ្ហាឫក្រេប  
- អះអាងថាការបកប្រែមានរចនាសម្ព័ន្ធខ្ពស់

### ទ្រឹស្តីចូលរួម
- អនុវត្តលីហ្គិចកូដ និងតម្រូវការគោលបំណង  
- បន្ថែមមតិពន្យល់លម្អិតសម្រាប់លក្ខណៈស្មុគស្មាញ  
- បន្ថែមឯកសារតម្រូវទាក់ព័ន្ធ  
- ពិនិត្យការផ្លាស់ប្តូរនៅមេរៀនផ្សេងៗ  
- បរិចារណាឯកសារ CONTRIBUTING.md

## របៀបលម្អិតបន្ថែម

### បណ្ណាល័យដែលប្រើឥតខ្ចោះ
- **pandas**: ការបំលែង និងវិភាគទិន្នន័យ  
- **numpy**: គណនាលេខ  
- **matplotlib**: ការតំណាងទិន្នន័យ និងគំនូស  
- **seaborn**: ការតំណាងទិន្នន័យស្ថិតិ (មេរៀនខ្លះ)  
- **scikit-learn**: មេរៀនម៉ាស៊ីនរៀន (កម្រិតខ្ពស់)

### ការប្រើប្រាស់ឯកសារទិន្នន័យ
- ឯកសារទិន្នន័យមាននៅក្នុងថត `data/` ឬថតរបស់មេរៀន  
- សៀវភៅចំណាំភាគច្រើនរំពឹងឯកសារទិន្នន័យជាភាពទាក់ទង  
- ឯកសារ CSV ជាទ្រង់ទ្រាយទិន្នន័យចម្បង  
- មេរៀនខ្លះប្រើ JSON សម្រាប់ឧទាហរណ៍ទិន្នន័យអ្វីដែលមិនស្មើ

### ការគាំទ្រភាសាច្រើន
- បកប្រែជាង ៤០ ភាសាតាមរយៈ GitHub Actions  
- ដំណើរការបកប្រែក្នុង `.github/workflows/co-op-translator.yml`  
- ឃ្លាំង `translations/` មានកូដភាសា  
- បកប្រែប្រលងនៅ `quiz-app/src/assets/translations/`

### ជម្រើសបរិស្ថានអភិវឌ្ឍន៍
១. **អភិវឌ្ឍន៍ក្នុងស្រុក**៖ តំឡើង Python, Jupyter, Node.js នៅក្នុងម៉ាស៊ីន  
២. **GitHub Codespaces**៖ បរិស្ថានអភិវឌ្ឍន៍គ្រឿងប្រព័ន្ធម៉ោនពពក  
៣. **VS Code Dev Containers**៖ បរិស្ថានអភិវឌ្ឍន៍ក្នុងកុងតឺន័រ  
៤. **Binder**៖ បើកសៀវភៅចំណាំក្នុងពពក (បើបានកំណត់)

### ទ្រឹស្តីមេរៀន
- មេរៀនមួយៗឯករាជ្យ ប៉ុន្តែបង្កើតលើគំនិតមុន  
- ប្រលងមុនមេរៀនវាស់វែងចំណេះដឹងមុន  
- ប្រលងក្រោយមេរៀនពង្រឹងការសិក្សា  
- ភារកិច្ចផ្តល់ការអនុវត្ត  
- សេចក្ដីសង្ខេបជារូបតំណាង

### ដោះស្រាយបញ្ហាទូទៅ

**បញ្ហា Kernel Jupyter:**
```bash
# ប្រាកដថាម៉ាស៊ីនចំណុចស្នូលត្រូវបានដំឡើងត្រឹមត្រូវ
python -m ipykernel install --user --name=datascience
```

**កំហុស npm Install:**
```bash
# សម្អាតប្រអប់ផ្ទុករបស់ npm ហើយសាកល្បងម្តងទៀត
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

**កំហុសនាំចូលក្នុងសៀវភៅចំណាំ:**
- ត្រួតពិនិត្យបណ្ណាល័យទាំងអស់បានដំឡើង  
- ពិនិត្យកំណែ Python (Python 3.7+ និយាយល្អ)  
- ប្រាកដថាបរិស្ថាន virtual បានបើក

**Docsify មិនផ្ទុក:**
- ប្រាកដថាកំពុងបម្រើពីគោលឃ្លាំងកូដ  
- ពិនិត្យឯកសារ `index.html` មាន  
- ប្រាកដថាប្រើបណ្តាញត្រឹមត្រូវ (ច្រក 3000)

### ការពិចារណាអំពីប្រសិទ្ធភាព
- ទិន្នន័យធំអាចយឺតក្នុងការផ្ទុកនៅសៀវភៅចំណាំ  
- ការតំណាងអាចយឺតសម្រាប់គំនូសស្មុគស្មាញ  
- Vue.js dev server កសាងប្រព័ន្ធបញ្ចូលកូដភ្លាមៗ  
- ការសាងសង់ផលិតកម្មបានបំពេញល្អ និងកាត់បន្ថយទំហំ

### សម្គាល់សុវត្ថិភាព
- មិនមានទិន្នន័យនីមួយៗឬ លេខសម្ងាត់ បញ្ចូលលើកូដ  
- ប្រើអថេរបរិស្ថានសម្រាប់កូនសោ API នៅមេរៀនពពក  
- មេរៀន Azure ត្រូវការគណនី Azure  
- អាប់ដេត dependencies តែងតែរក្សាសុវត្ថិភាព

## របៀបចូលរួមបកប្រែ
- បកប្រែដោយម៉ាស៊ីនគ្រប់គ្រងតាម GitHub Actions  
- ត្រួតពិនិត្យដោយដៃសម្រាប់ភាពត្រឹមត្រូវការបកប្រែ  
- បន្តការដាក់ថតបកប្រែដូចបែបតម្លើង  
- បន្ថែមតំណភ្ជាប់ប្រលងភាសា: `?loc=fr`  
- តេស្តមេរៀនបកប្រែឱ្យបង្ហាញត្រឹមត្រូវ

## ធនធានដែលទាក់ទង
- កម្មវិធីសិក្សាចម្បង: https://aka.ms/datascience-beginners  
- សិក្សាជាមួយ Microsoft Learn: https://docs.microsoft.com/learn/  
- មជ្ឈមណ្ឌលសិស្ស: https://docs.microsoft.com/learn/student-hub  
- វេទិកាចែករំលែកគំនិត: https://github.com/microsoft/Data-Science-For-Beginners/discussions  
- កម្មវិធី Microsoft ផ្សេងៗ: ML for Beginners, AI for Beginners, Web Dev for Beginners

## ការថែរក្សាគម្រោង
- ធ្វើអាប់ដេតទៀងទាត់ដើម្បីរក្សាសម័យ  
- ស្វាគមន៍ការចូលរួមពីសហគមន៍  
- ការតាមដានបញ្ហាក្នុង GitHub  
- ពិនិត្យ PR ដោយអ្នកថែរក្សាគម្រោង  
- សម្រេចការត្រួតពិនិត្យ និងធ្វើអាប់ដេតប្រចាំខែ

---

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