AGENTS.md

1# AGENTS.md
2 
3## Επισκόπηση Έργου
4 
5Αυτό είναι ένα εκπαιδευτικό αποθετήριο προγράμματος σπουδών για τη διδασκαλία των βασικών της ανάπτυξης ιστοσελίδων σε αρχάριους. Το πρόγραμμα σπουδών είναι ένα ολοκληρωμένο μάθημα 12 εβδομάδων που αναπτύχθηκε από τους Microsoft Cloud Advocates, με 24 πρακτικά μαθήματα που καλύπτουν JavaScript, CSS και HTML.
6 
7### Κύρια Στοιχεία
8 
9- **Εκπαιδευτικό Περιεχόμενο**: 24 δομημένα μαθήματα οργανωμένα σε μονάδες βασισμένες σε έργα
10- **Πρακτικά Έργα**: Terrarium, Παιχνίδι Πληκτρολόγησης, Επέκταση Περιηγητή, Παιχνίδι Διαστήματος, Τραπεζική Εφαρμογή, Κώδικας Επεξεργαστή και Βοηθός Συνομιλίας με Τεχνητή Νοημοσύνη
11- **Διαδραστικά Κουίζ**: 48 κουίζ με 3 ερωτήσεις το καθένα (αξιολογήσεις πριν/μετά το μάθημα)
12- **Υποστήριξη Πολλαπλών Γλωσσών**: Αυτόματες μεταφράσεις για πάνω από 50 γλώσσες μέσω GitHub Actions
13- **Τεχνολογίες**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (για έργα ΤΝ)
14 
15### Αρχιτεκτονική
16 
17- Εκπαιδευτικό αποθετήριο με δομή βάσει μαθημάτων
18- Οφάκελοι κάθε μαθήματος περιέχουν README, παραδείγματα κώδικα και λύσεις
19- Αυτόνομα έργα σε ξεχωριστούς φακέλους (quiz-app, διάφορα έργα μαθημάτων)
20- Σύστημα μετάφρασης μέσω GitHub Actions (co-op-translator)
21- Τεκμηρίωση διατίθεται μέσω Docsify και ως PDF
22 
23## Εντολές Ρύθμισης
24 
25Αυτό το αποθετήριο προορίζεται κυρίως για κατανάλωση εκπαιδευτικού περιεχομένου. Για εργασία με συγκεκριμένα έργα:
26 
27### Ρύθμιση Κύριου Αποθετηρίου
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Ρύθμιση Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Εκκίνηση διακομιστή ανάπτυξης
40npm run build      # Δημιουργία για παραγωγή
41npm run lint       # Εκτέλεση ESLint
42```
43 
44### API Τραπεζικού Έργου (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Εκκίνηση διακομιστή API
50npm run lint       # Εκτέλεση ESLint
51npm run format     # Μορφοποίηση με Prettier
52```
53 
54### Έργα Επέκτασης Περιηγητή
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Ακολουθήστε τις οδηγίες φόρτωσης επεκτάσεων που είναι ειδικές για τον περιηγητή
60```
61 
62### Έργα Παιχνιδιού Διαστήματος
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Ανοίξτε το index.html σε πρόγραμμα περιήγησης ή χρησιμοποιήστε Live Server
68```
69 
70### Έργο Συνομιλίας (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Ορισμός μεταβλητής περιβάλλοντος GITHUB_TOKEN
76python api.py
77```
78 
79## Ροή Ανάπτυξης
80 
81### Για Συνεισφέροντες Περιεχομένου
82 
831. **Δημιουργήστε fork** του αποθετηρίου στον λογαριασμό σας στο GitHub
842. **Κλωνοποιήστε το fork** τοπικά
853. **Δημιουργήστε νέο κλαδί** για τις αλλαγές σας
864. Κάντε αλλαγές στο περιεχόμενο των μαθημάτων ή τα παραδείγματα κώδικα
875. Δοκιμάστε τις αλλαγές κώδικα στους αντίστοιχους φακέλους έργων
886. Υποβάλετε pull requests ακολουθώντας τις οδηγίες συνεισφοράς
89 
90### Για Μαθητές
91 
921. Κάντε fork ή κλωνοποιήστε το αποθετήριο
932. Πλοηγηθείτε διαδοχικά στους φακέλους των μαθημάτων
943. Διαβάστε τα αρχεία README κάθε μαθήματος
954. Ολοκληρώστε τα προ-μαθήματος κουίζ στο https://ff-quizzes.netlify.app/web/
965. Επεξεργαστείτε τα παραδείγματα κώδικα στους φακέλους μαθημάτων
976. Ολοκληρώστε εργασίες και προκλήσεις
987. Πραγματοποιήστε τα μετα-μαθήματος κουίζ
99 
100### Ζωντανή Ανάπτυξη
101 
102- **Τεκμηρίωση**: Εκτελέστε `docsify serve` από τη ρίζα (θύρα 3000)
103- **Quiz App**: Εκτελέστε `npm run dev` στον φάκελο quiz-app
104- **Έργα**: Χρησιμοποιήστε το Live Server extension του VS Code για έργα HTML
105- **API Έργα**: Εκτελέστε `npm start` στους αντίστοιχους φακέλους API
106 
107## Οδηγίες Δοκιμών
108 
109### Δοκιμές Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Έλεγχος για θέματα στυλ κώδικα
114npm run build      # Επαλήθευση επιτυχίας κατασκευής
115```
116 
117### Δοκιμές Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Έλεγχος για θέματα στυλ κώδικα
122node server.js     # Επιβεβαίωση ότι ο διακομιστής ξεκινά χωρίς σφάλματα
123```
124 
125### Γενική Προσέγγιση Δοκιμών
126 
127- Πρόκειται για εκπαιδευτικό αποθετήριο χωρίς ολοκληρωμένες αυτοματοποιημένες δοκιμές
128- Οι χειροκίνητες δοκιμές εστιάζουν σε:
129  - Εκτέλεση παραδειγμάτων κώδικα χωρίς σφάλματα
130  - Οι σύνδεσμοι στην τεκμηρίωση λειτουργούν σωστά
131  - Οι κατασκευές έργων ολοκληρώνονται επιτυχώς
132  - Τα παραδείγματα ακολουθούν τις βέλτιστες πρακτικές
133 
134### Έλεγχοι Πριν την Υποβολή
135 
136- Εκτελέστε `npm run lint` στους φακέλους με package.json
137- Επαληθεύστε ότι οι σύνδεσμοι markdown είναι έγκυροι
138- Δοκιμάστε παραδείγματα κώδικα στον περιηγητή ή Node.js
139- Ελέγξτε ότι οι μεταφράσεις διατηρούν τη σωστή δομή
140 
141## Οδηγίες Στυλ Κώδικα
142 
143### JavaScript
144 
145- Χρησιμοποιήστε τον σύγχρονο σύνταξη ES6+
146- Ακολουθήστε τις τυπικές ρυθμίσεις ESLint που παρέχονται στα έργα
147- Χρησιμοποιήστε ουσιαστικά ονόματα μεταβλητών και συναρτήσεων για εκπαιδευτική σαφήνεια
148- Προσθέστε σχόλια που εξηγούν έννοιες για τους μαθητές
149- Μορφοποιήστε με Prettier όπου είναι ρυθμισμένο
150 
151### HTML/CSS
152 
153- Σημαντικά στοιχεία HTML5
154- Αρχές σχεδιασμού προσαρμοστικής εμφάνισης (responsive)
155- Καθαρούς κανόνες ονοματολογίας κλάσεων
156- Σχόλια που εξηγούν τεχνικές CSS για μαθητές
157 
158### Python
159 
160- Χρήση οδηγιών στυλ PEP 8
161- Καθαρά, εκπαιδευτικά παραδείγματα κώδικα
162- Χρήση δηλώσεων τύπων όπου βοηθούν στην εκμάθηση
163 
164### Τεκμηρίωση σε Markdown
165 
166- Σαφή ιεραρχία επικεφαλίδων
167- Μπλοκ κώδικα με καθορισμένη γλώσσα
168- Σύνδεσμοι για επιπλέον πόρους
169- Στιγμιότυπα και εικόνες στους φακέλους `images/`
170- Εναλλακτικό κείμενο (alt text) για τις εικόνες για προσβασιμότητα
171 
172### Οργάνωση Αρχείων
173 
174- Μαθήματα με αριθμημένη ακολουθία (1-getting-started-lessons, 2-js-basics κ.ά.)
175- Κάθε έργο έχει φακέλους `solution/` και συχνά `start/` ή `your-work/`
176- Εικόνες φυλαγμένες σε φακέλους `images/` κάθε μαθήματος
177- Μεταφράσεις σε δομή `translations/{language-code}/`
178 
179## Κατασκευή και Ανάπτυξη
180 
181### Ανάπτυξη Quiz App (Azure Static Web Apps)
182 
183Το quiz-app είναι ρυθμισμένο για ανάπτυξη σε Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Δημιουργεί φάκελο dist/
188# Αναπτύσσει μέσω ροής εργασίας GitHub Actions κατά την ώθηση στο main
189```
190 
191Ρυθμίσεις Azure Static Web Apps:
192- **Τοποθεσία εφαρμογής**: `/quiz-app`
193- **Τοποθεσία εξόδου**: `dist`
194- **Ροή εργασίας**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Δημιουργία PDF Τεκμηρίωσης
197 
198```bash
199npm install                    # Εγκαταστήστε το docsify-to-pdf
200npm run convert               # Δημιουργία PDF από docs
201```
202 
203### Τεκμηρίωση Docsify
204 
205```bash
206npm install -g docsify-cli    # Εγκαταστήστε το Docsify παγκοσμίως
207docsify serve                 # Εκτελέστε στον localhost:3000
208```
209 
210### Κατασκευές ανά Έργο
211 
212Κάθε φάκελος έργου μπορεί να έχει δική του διαδικασία κατασκευής:
213- Έργα Vue: `npm run build` δημιουργεί παραγωγικά πακέτα
214- Στατικά έργα: Δεν απαιτείται βήμα κατασκευής, σερβίρονται απευθείας τα αρχεία
215 
216## Οδηγίες Pull Request
217 
218### Μορφή Τίτλου
219 
220Χρησιμοποιήστε σαφείς, περιγραφικούς τίτλους που υποδεικνύουν την περιοχή αλλαγής:
221- `[Quiz-app] Προσθήκη νέου κουίζ για μάθημα Χ`
222- `[Lesson-3] Διόρθωση τυπογραφικού λάθους στο έργο terrarium`
223- `[Translation] Προσθήκη ισπανικής μετάφρασης για το μάθημα 5`
224- `[Docs] Ενημέρωση οδηγιών ρύθμισης`
225 
226### Απαιτούμενοι Έλεγχοι
227 
228Πριν από την υποβολή PR:
229 
2301. **Ποιότητα Κώδικα**:
231   - Εκτελέστε `npm run lint` στους επηρεασμένους φακέλους έργων
232   - Διορθώστε όλα τα σφάλματα και προειδοποιήσεις linting
233 
2342. **Επαλήθευση Κατασκευής**:
235   - Εκτελέστε `npm run build` εάν ισχύει
236   - Βεβαιωθείτε ότι δεν υπάρχουν σφάλματα κατασκευής
237 
2383. **Επαλήθευση Συνδέσμων**:
239   - Δοκιμάστε όλους τους συνδέσμους markdown
240   - Επαληθεύστε ότι οι αναφορές εικόνων λειτουργούν
241 
2424. **Αναθεώρηση Περιεχομένου**:
243   - Διόρθωση ορθογραφίας και γραμματικής
244   - Επιβεβαίωση ότι τα παραδείγματα κώδικα είναι σωστά και εκπαιδευτικά
245   - Επαλήθευση σωστής διατήρησης νοήματος στις μεταφράσεις
246 
247### Απαιτήσεις Συνεισφοράς
248 
249- Αποδοχή του Microsoft CLA (αυτόματος έλεγχος στην πρώτη PR)
250- Ακολουθήστε τον [Κώδικα Συμπεριφοράς Ανοιχτού Κώδικα της Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Διαβάστε το [CONTRIBUTING.md](./CONTRIBUTING.md) για λεπτομερείς οδηγίες
252- Αναφέρετε αριθμούς ζητημάτων στην περιγραφή PR αν ισχύει
253 
254### Διαδικασία Αναθεώρησης
255 
256- Οι PR ελέγχονται από συντηρητές και την κοινότητα
257- Προτεραιότητα στην εκπαιδευτική σαφήνεια
258- Τα παραδείγματα κώδικα να ακολουθούν τις τρέχουσες βέλτιστες πρακτικές
259- Οι μεταφράσεις ελέγχονται για ακρίβεια και πολιτισμική καταλληλότητα
260 
261## Σύστημα Μετάφρασης
262 
263### Αυτόματη Μετάφραση
264 
265- Χρησιμοποιεί GitHub Actions με ροή εργασίας co-op-translator
266- Μεταφράζει σε πάνω από 50 γλώσσες αυτόματα
267- Αρχεία πηγής σε κύριους φακέλους
268- Τα μεταφρασμένα αρχεία βρίσκονται σε `translations/{language-code}/`
269 
270### Προσθήκη Χειροκίνητων Βελτιώσεων Μετάφρασης
271 
2721. Εντοπίστε το αρχείο σε `translations/{language-code}/`
2732. Κάντε βελτιώσεις διατηρώντας τη δομή
2743. Εξασφαλίστε ότι τα παραδείγματα κώδικα παραμένουν λειτουργικά
2754. Δοκιμάστε όλο το τοπικοποιημένο περιεχόμενο κουίζ
276 
277### Μεταδεδομένα Μετάφρασης
278 
279Τα μεταφρασμένα αρχεία περιλαμβάνουν κεφαλίδα μεταδεδομένων:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Αντιμετώπιση και Επίλυση Προβλημάτων
293 
294### Συνήθη Θέματα
295 
296**Η εφαρμογή Quiz δεν ξεκινά**:
297- Ελέγξτε την έκδοση Node.js (συνιστάται v14+)
298- Διαγράψτε `node_modules` και `package-lock.json`, εκτελέστε ξανά `npm install`
299- Ελέγξτε για σύγκρουση θυρών (προεπιλογή: Vite χρησιμοποιεί θύρα 5173)
300 
301**Ο διακομιστής API δεν ξεκινά**:
302- Επαληθεύστε ότι η έκδοση Node.js είναι ≥10
303- Ελέγξτε αν η θύρα είναι ήδη σε χρήση
304- Βεβαιωθείτε ότι όλες οι εξαρτήσεις είναι εγκατεστημένες με `npm install`
305 
306**Η επέκταση περιηγητή δεν φορτώνει**:
307- Επαληθεύστε ότι το manifest.json είναι σωστά μορφοποιημένο
308- Ελέγξτε τα σφάλματα στην κονσόλα περιηγητή
309- Ακολουθήστε τις οδηγίες εγκατάστασης για την επέκταση ανά περιηγητή
310 
311**Προβλήματα στο έργο συνομιλίας Python**:
312- Βεβαιωθείτε ότι το πακέτο OpenAI είναι εγκατεστημένο: `pip install openai`
313- Επαληθεύστε ότι το περιβάλλον GITHUB_TOKEN έχει οριστεί
314- Ελέγξτε τα δικαιώματα πρόσβασης στα GitHub Models
315 
316**Η Docsify δεν σερβίρει τεκμηρίωση**:
317- Εγκαταστήστε docsify-cli παγκοσμίως: `npm install -g docsify-cli`
318- Εκτελέστε από την ρίζα του αποθετηρίου
319- Ελέγξτε ότι υπάρχει το αρχείο `docs/_sidebar.md`
320 
321### Συμβουλές Περιβάλλοντος Ανάπτυξης
322 
323- Χρησιμοποιήστε VS Code με το Live Server extension για έργα HTML
324- Εγκαταστήστε τις επεκτάσεις ESLint και Prettier για ομοιόμορφη μορφοποίηση
325- Χρησιμοποιήστε τα DevTools του περιηγητή για αποσφαλμάτωση JavaScript
326- Για έργα Vue, εγκαταστήστε την επέκταση Vue DevTools για περιηγητές
327 
328### Θέματα Απόδοσης
329 
330- Ο μεγάλος αριθμός μεταφρασμένων αρχείων (50+ γλώσσες) κάνει τα πλήρη κλωνοποιημένα αρχεία μεγάλα
331- Χρησιμοποιήστε επιφανειακό κλώνο αν εργάζεστε μόνο με το περιεχόμενο: `git clone --depth 1`
332- Εξαιρέστε τις μεταφράσεις από αναζητήσεις όταν δουλεύετε σε αγγλικό περιεχόμενο
333- Οι διαδικασίες κατασκευής μπορεί να είναι αργές στην πρώτη εκτέλεση (npm install, κατασκευή Vite)
334 
335## Θέματα Ασφαλείας
336 
337### Μεταβλητές Περιβάλλοντος
338 
339- Τα κλειδιά API δεν πρέπει ποτέ να αποθηκεύονται στο αποθετήριο
340- Χρησιμοποιήστε αρχεία `.env` (ήδη στο `.gitignore`)
341- Καταγράψτε τις απαιτούμενες μεταβλητές περιβάλλοντος στα README των έργων
342 
343### Έργα Python
344 
345- Χρησιμοποιήστε εικονικά περιβάλλοντα: `python -m venv venv`
346- Διατηρήστε τις εξαρτήσεις ενημερωμένες
347- Τα GitHub tokens πρέπει να έχουν τα ελάχιστα απαιτούμενα δικαιώματα
348 
349### Πρόσβαση σε GitHub Models
350 
351- Απαιτούνται Personal Access Tokens (PAT) για GitHub Models
352- Τα tokens πρέπει να αποθηκεύονται ως μεταβλητές περιβάλλοντος
353- Ποτέ μην αποθηκεύετε tokens ή διαπιστευτήρια στο αποθετήριο
354 
355## Πρόσθετες Σημειώσεις
356 
357### Στόχος Κοινού
358 
359- Απόλυτα αρχάριοι στην ανάπτυξη ιστοσελίδων
360- Φοιτητές και αυτοδίδακτοι
361- Εκπαιδευτικοί που χρησιμοποιούν το πρόγραμμα στην τάξη
362- Το περιεχόμενο σχεδιάστηκε για προσβασιμότητα και σταδιακή ανάπτυξη δεξιοτήτων
363 
364### Εκπαιδευτική Φιλοσοφία
365 
366- Προσέγγιση μάθησης βασισμένη σε έργα
367- Συχνές αξιολογήσεις γνώσεων (κουίζ)
368- Πρακτικές ασκήσεις κωδικοποίησης
369- Παραδείγματα εφαρμογών πραγματικού κόσμου
370- Εστίαση στα βασικά πριν τα frameworks
371 
372### Διαχείριση Αποθετηρίου
373 
374- Ενεργή κοινότητα μαθητών και συνεισφερόντων
375- Τακτικές ενημερώσεις εξαρτήσεων και περιεχομένου
376- Παρακολούθηση ζητημάτων και συζητήσεων από συντηρητές
377- Αυτοματοποιημένες ενημερώσεις μεταφράσεων μέσω GitHub Actions
378 
379### Σχετικοί Πόροι
380 
381- [Μονάδες Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Πόροι Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) συνιστάται για μαθητές
384- Πρόσθετα μαθήματα: Γενετική ΤΝ, Επιστήμη Δεδομένων, ML, IoT διαθέσιμα
385 
386### Εργασία με Συγκεκριμένα Έργα
387 
388Για λεπτομερείς οδηγίες για κάθε έργο, ανατρέξτε στα README αρχεία:
389- `quiz-app/README.md` - Εφαρμογή quiz Vue 3
390- `7-bank-project/README.md` - Τραπεζική εφαρμογή με ταυτοποίηση
391- `5-browser-extension/README.md` - Ανάπτυξη επέκτασης περιηγητή
392- `6-space-game/README.md` - Ανάπτυξη παιχνιδιού με καμβά
393- `9-chat-project/README.md` - Έργο βοηθού συνομιλίας με ΤΝ
394 
395### Δομή Monorepo
396 
397Αν και δεν είναι παραδοσιακό monorepo, αυτό το αποθετήριο περιέχει πολλαπλά ανεξάρτητα έργα:
398- Κάθε μάθημα είναι αυτόνομο
399- Τα έργα δεν μοιράζονται εξαρτήσεις
400- Εργαστείτε σε μεμονωμένα έργα χωρίς να επηρεάζετε τα άλλα
401- Κλωνοποιήστε ολόκληρο το αποθετήριο για πλήρη εμπειρία προγράμματος σπουδών
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Αποποίηση ευθυνών**:  
407Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που προσπαθούμε για ακρίβεια, παρακαλούμε να γνωρίζετε ότι οι αυτοματοποιημένες μεταφράσεις μπορεί να περιέχουν σφάλματα ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για οποιεσδήποτε παρερμηνείες ή παρανοήσεις προκύψουν από τη χρήση αυτής της μετάφρασης.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->