22 KiB

Raw Permalink Blame History Unescape Escape

AGENTS.md

Επισκόπηση Έργου

Αυτό είναι ένα εκπαιδευτικό αποθετήριο προγράμματος σπουδών για τη διδασκαλία των βασικών της ανάπτυξης ιστοσελίδων σε αρχάριους. Το πρόγραμμα σπουδών είναι ένα ολοκληρωμένο 12 εβδομάδων μάθημα που αναπτύχθηκε από τους Microsoft Cloud Advocates, με 24 πρακτικά μαθήματα που καλύπτουν JavaScript, CSS και HTML.

Κύρια Στοιχεία

Εκπαιδευτικό Περιεχόμενο: 24 δομημένα μαθήματα οργανωμένα σε μονάδες βασισμένες σε έργα
Πρακτικά Έργα: Terrarium, Typing Game, Browser Extension, Space Game, Banking App, Code Editor και AI Chat Assistant
Διαδραστικά Κουίζ: 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

Ρύθμιση Quiz App (Vue 3 + Vite)

cd quiz-app
npm install
npm run dev        # Εκκίνηση διακομιστή ανάπτυξης
npm run build      # Δημιουργία για παραγωγή
npm run lint       # Εκτέλεση ESLint

API Έργου Τράπεζας (Node.js + Express)

cd 7-bank-project/api
npm install
npm start          # Ξεκινήστε τον διακομιστή API
npm run lint       # Εκτελέστε το ESLint
npm run format     # Μορφοποιήστε με το Prettier

Έργα Επέκτασης Περιηγητή

cd 5-browser-extension/solution
npm install
# Ακολουθήστε τις οδηγίες φόρτωσης επεκτάσεων ειδικές για το πρόγραμμα περιήγησης

Έργα Παιχνιδιού Διαστήματος

cd 6-space-game/solution
npm install
# Ανοίξτε το index.html σε πρόγραμμα περιήγησης ή χρησιμοποιήστε το Live Server

Έργο Chat (Backend Python)

cd 9-chat-project/solution/backend/python
pip install openai
# Ορίστε τη μεταβλητή περιβάλλοντος GITHUB_TOKEN
python api.py

Ροή Ανάπτυξης

Για Συνεργάτες Περιεχομένου

Φορκάρετε το αποθετήριο στον λογαριασμό σας στο GitHub
Κλωνοποιήστε το fork σας τοπικά
Δημιουργήστε νέο branch για τις αλλαγές σας
Κάντε αλλαγές στο περιεχόμενο των μαθημάτων ή στα παραδείγματα κώδικα
Δοκιμάστε τις αλλαγές κώδικα στους αντίστοιχους καταλόγους έργων
Υποβάλετε pull requests ακολουθώντας τις οδηγίες συνεισφοράς

Για Μαθητές

Φορκάρετε ή κλωνοποιήστε το αποθετήριο
Πλοηγηθείτε διαδοχικά στους καταλόγους των μαθημάτων
Διαβάστε τα αρχεία README για κάθε μάθημα
Ολοκληρώστε τα προ-μάθημα κουίζ στο https://ff-quizzes.netlify.app/web/
Εργαστείτε μέσα από τα παραδείγματα κώδικα στους φακέλους μαθημάτων
Ολοκληρώστε τις ασκήσεις και προκλήσεις
Κάντε τα μετα-μάθημα κουίζ

Ζωντανή Ανάπτυξη

Τεκμηρίωση: Εκτελέστε docsify serve στη ρίζα (θύρα 3000)
Quiz App: Εκτελέστε npm run dev στον κατάλογο quiz-app
Έργα: Χρησιμοποιήστε την επέκταση Live Server του VS Code για έργα 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     # Επαληθεύστε ότι ο διακομιστής ξεκινά χωρίς σφάλματα

Γενική Προσέγγιση Δοκιμών

Αυτό είναι εκπαιδευτικό αποθετήριο χωρίς πλήρεις αυτοματοποιημένες δοκιμές
Οι χειροκίνητες δοκιμές εστιάζουν σε:
- Παράδειγματα κώδικα να εκτελούνται χωρίς σφάλματα
- Οι σύνδεσμοι στην τεκμηρίωση να λειτουργούν σωστά
- Ολοκληρωμένα επιτυχημένα builds έργων
- Παραδείγματα να ακολουθούν καλές πρακτικές

Έλεγχοι Πριν την Υποβολή

Εκτελέστε npm run lint σε καταλόγους με package.json
Ελέγξτε την εγκυρότητα των συνδέσμων markdown
Δοκιμάστε παραδείγματα κώδικα σε browser ή Node.js
Επιβεβαιώστε ότι οι μεταφράσεις διατηρούν τη σωστή δομή

Οδηγίες Στυλ Κώδικα

JavaScript

Χρήση μοντέρνας σύνταξης ES6+
Ακολουθήστε τις προεπιλεγμένες ρυθμίσεις ESLint των έργων
Χρησιμοποιήστε περιγραφικά ονόματα μεταβλητών και συναρτήσεων για εκπαιδευτική σαφήνεια
Προσθέστε σχόλια που εξηγούν έννοιες για τους μαθητές
Μορφοποίηση με Prettier όπου είναι ρυθμισμένο

HTML/CSS

Σημασιολογικά στοιχεία HTML5
Αρχές σχεδίασης responsive
Καθαρούς κανόνες ονοματοδοσίας κλάσεων
Σχόλια που εξηγούν τεχνικές CSS για τους μαθητές

Python

Οδηγίες στυλ PEP 8
Καθαρά, εκπαιδευτικά παραδείγματα κώδικα
Τύποι όπου βοηθούν στην εκμάθηση

Τεκμηρίωση Markdown

Καθαρή ιεραρχία κεφαλίδων
Μπλοκ κώδικα με καθορισμένη γλώσσα
Σύνδεσμοι σε επιπλέον πόρους
Στιγμιότυπα και εικόνες στους φακέλους 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

Builds Ανά Έργο

Κάθε φάκελος έργου μπορεί να έχει δική του διαδικασία build:

Vue έργα: npm run build δημιουργεί bundles παραγωγής
Στατικά έργα: Δεν υπάρχει βήμα build, σερβίρετε τα αρχεία απευθείας

Οδηγίες Pull Request

Μορφή Τίτλου

Χρησιμοποιήστε σαφείς, περιγραφικούς τίτλους που υποδεικνύουν το κομμάτι αλλαγής:

[Quiz-app] Προσθήκη νέου κουίζ για το μάθημα X
[Lesson-3] Διόρθωση ορθογραφικού λάθους στο έργο terrarium
[Translation] Προσθήκη ισπανικής μετάφρασης για το μάθημα 5
[Docs] Ενημέρωση οδηγιών ρύθμισης

Απαραίτητοι Έλεγχοι

Πριν υποβάλετε PR:

Ποιότητα Κώδικα:
- Εκτελέστε npm run lint στους επηρεαζόμενους καταλόγους έργων
- Διορθώστε όλα τα λάθη και προειδοποιήσεις lint
Επαλήθευση Build:
- Εκτελέστε npm run build όπου εφαρμόζεται
- Βεβαιωθείτε ότι δεν υπάρχουν σφάλματα build
Επικύρωση Συνδέσμων:
- Δοκιμάστε όλους τους συνδέσμους markdown
- Επιβεβαιώστε ότι οι εικόνες φορτώνουν σωστά
Ανασκόπηση Περιεχομένου:
- Διορθώστε ορθογραφία και γραμματική
- Βεβαιωθείτε ότι τα παραδείγματα κώδικα είναι σωστά και εκπαιδευτικά
- Επιβεβαιώστε ότι οι μεταφράσεις διατηρούν το αρχικό νόημα

Απαιτήσεις Συνεισφοράς

Αποδοχή του Microsoft CLA (αυτόματος έλεγχος στην πρώτη PR)
Ακολουθήστε τον Κώδικα Συμπεριφοράς Ανοιχτού Κώδικα Microsoft
Δείτε το CONTRIBUTING.md για λεπτομερείς οδηγίες
Αναφέρετε αριθμούς issue στην περιγραφή PR αν ισχύει

Διαδικασία Ανασκόπησης

Οι PR ελέγχονται από διαχειριστές και κοινότητα
Η εκπαιδευτική σαφήνεια είναι προτεραιότητα
Τα παραδείγματα κώδικα πρέπει να ακολουθούν τις τρέχουσες βέλτιστες πρακτικές
Οι μεταφράσεις ελέγχονται για ακρίβεια και πολιτισμική καταλληλότητα

Σύστημα Μετάφρασης

Αυτόματη Μετάφραση

Χρησιμοποιεί GitHub Actions με ροή εργασίας co-op-translator
Μεταφράζει σε 50+ γλώσσες αυτόματα
Αρχεία προέλευσης στους κύριους καταλόγους
Μεταφρασμένα αρχεία στους φακέλους translations/{language-code}/

Προσθήκη Βελτιώσεων Χειροκίνητης Μετάφρασης

Βρείτε το αρχείο σε translations/{language-code}/
Κάντε βελτιώσεις διατηρώντας τη δομή
Βεβαιωθείτε ότι τα παραδείγματα κώδικα παραμένουν λειτουργικά
Δοκιμάστε τυχόν τοπικά κουίζ που έχουν εντοπιστεί

Μεταδεδομένα Μετάφρασης

Τα μεταφρασμένα αρχεία περιέχουν κεφαλίδα μεταδεδομένων:

<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->

Αποσφαλμάτωση και Επίλυση Προβλημάτων

Συχνά Προβλήματα

Το quiz app δεν ξεκινάει:

Ελέγξτε την έκδοση Node.js (συνιστάται v14+)
Διαγράψτε node_modules και package-lock.json, τρέξτε ξανά npm install
Ελέγξτε για συγκρούσεις θυρών (προεπιλεγμένη: Vite χρησιμοποιεί θύρα 5173)

Ο διακομιστής API δεν ξεκινά:

Ελέγξτε ότι η έκδοση Node.js είναι >=10
Ελέγξτε αν η θύρα χρησιμοποιείται ήδη
Βεβαιωθείτε ότι έχουν εγκατασταθεί όλες οι εξαρτήσεις με npm install

Η επέκταση περιηγητή δεν φορτώνει:

Επιβεβαιώστε ότι το manifest.json είναι σωστά διαμορφωμένο
Ελέγξτε την κονσόλα του browser για σφάλματα
Ακολουθήστε τις οδηγίες εγκατάστασης της επέκτασης για τον αντίστοιχο browser

Προβλήματα έργου chat Python:

Βεβαιωθείτε ότι το πακέτο OpenAI είναι εγκατεστημένο: pip install openai
Ελέγξτε ότι η μεταβλητή περιβάλλοντος GITHUB_TOKEN είναι ορισμένη
Ελέγξτε τα δικαιώματα πρόσβασης στα GitHub Models

Docsify δεν σερβίρει τεκμηρίωση:

Εγκαταστήστε docsify-cli παγκοσμίως: npm install -g docsify-cli
Τρέξτε από το ριζικό κατάλογο του αποθετηρίου
Βεβαιωθείτε ότι το docs/_sidebar.md υπάρχει

Συμβουλές Περιβάλλοντος Ανάπτυξης

Χρησιμοποιήστε VS Code με την επέκταση Live Server για έργα HTML
Εγκαταστήστε τις επεκτάσεις ESLint και Prettier για συνεπή μορφοποίηση
Χρησιμοποιήστε τα DevTools του browser για αποσφαλμάτωση JavaScript
Για έργα Vue, εγκαταστήστε την επέκταση Vue DevTools του browser

Θέματα Απόδοσης

Μεγάλος αριθμός μεταφρασμένων αρχείων (50+ γλώσσες) σημαίνει μεγάλα ολοκληρωτικά κλώνους
Χρησιμοποιήστε ρηχό κλώνο αν εργάζεστε μόνο με περιεχόμενο: git clone --depth 1
Αποκλείστε τις μεταφράσεις από τις αναζητήσεις όταν εργάζεστε με αγγλικό περιεχόμενο
Οι διαδικασίες build μπορεί να είναι αργές στην πρώτη εκτέλεση (npm install, Vite build)

Θέματα Ασφαλείας

Μεταβλητές Περιβάλλοντος

Τα κλειδιά API δεν πρέπει ποτέ να δεσμεύονται στο αποθετήριο
Χρησιμοποιήστε αρχεία .env (ήδη στο .gitignore)
Τεκμηριώστε τις απαιτούμενες μεταβλητές περιβάλλοντος στα README των έργων

Έργα Python

Χρησιμοποιήστε εικονικά περιβάλλοντα: python -m venv venv
Κρατήστε ενημερωμένες τις εξαρτήσεις
Τα tokens GitHub πρέπει να έχουν ελάχιστα απαιτούμενα δικαιώματα

Πρόσβαση σε GitHub Models

Απαιτούνται Personal Access Tokens (PAT) για GitHub Models
Τα tokens να αποθηκεύονται ως μεταβλητές περιβάλλοντος
Ποτέ μη δεσμεύετε tokens ή διαπιστευτήρια στον κώδικα

Πρόσθετες Σημειώσεις

Στόχος Κοινού

Απόλυτα αρχάριοι στην ανάπτυξη ιστοσελίδων
Μαθητές και αυτοδίδακτοι
Καθηγητές που χρησιμοποιούν το πρόγραμμα σε τάξεις
Το περιεχόμενο σχεδιάστηκε για προσβασιμότητα και σταδιακή ανάπτυξη δεξιοτήτων

Εκπαιδευτική Φιλοσοφία

Προσέγγιση μάθησης βασισμένη σε έργα
Συχνές επαληθεύσεις γνώσης (κουίζ)
Πρακτικές ασκήσεις κώδικα
Παραδείγματα εφαρμογών πραγματικού κόσμου
Εστίαση στα θεμελιώδη πριν τα πλαίσια εργασίας

Συντήρηση Αποθετηρίου

Ενεργή κοινότητα μαθητών και συνεργατών
Τακτικές ενημερώσεις εξαρτήσεων και περιεχομένου
Παρακολούθηση ζητημάτων και συζητήσεων από διαχειριστές
Αυτόματες ενημερώσεις μεταφράσεων μέσω 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 - Ανάπτυξη παιχνιδιού καμβά
9-chat-project/README.md - Έργο βοηθού συνομιλίας AI

Δομή Μονό-αποθετηρίου (Monorepo)

Παρότι δεν είναι παραδοσιακό monorepo, αυτό το αποθετήριο περιέχει πολλαπλά ανεξάρτητα έργα:

Κάθε μάθημα είναι αυτόνομο
Τα έργα δεν μοιράζονται εξαρτήσεις
Εργαστείτε σε μεμονωμένα έργα χωρίς να επηρεάζετε άλλα
Κλωνοποιήστε ολόκληρο το αποθετήριο για την πλήρη εμπειρία προγράμματος σπουδών

Αποποίηση ευθύνης:
Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης AI Co-op Translator. Παρόλο που καταβάλλουμε προσπάθεια για ακρίβεια, παρακαλούμε λάβετε υπόψη ότι οι αυτόματες μεταφράσεις μπορεί να περιέχουν σφάλματα ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η έγκυρη πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για οποιεσδήποτε παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.

22 KiB Raw Permalink Blame History Unescape Escape