בירור | קובץ הוראות לצורת עבודה נכונה בjs

[עידו300]

לאור המסקנות מהשרשור הקודם, בקשתי מAI שינסח לי כללים לעבודה נכונה + הוראות לAI.

מאחר ואני לא סומך על AI כזה או אחר הייתי שמח אם מישהו יוכל לעבור על זה לראות שכל תקין ונכון, וכמובן אם יש הערות.

מעולה.
הנה ערכת כללים מותאמת במיוחד לפרויקט שלך (Node.js + MySQL + API + מערכת טלפונית).
לא דוגמטית, לא בירוקרטית — אבל מקצועית, נקייה ובטוחה.

---

ערכת כללים לפרויקט API (Node + MySQL)

---

1️⃣ ארכיטקטורה (חובה)

שכבות קבועות

Route → Controller → Service → Repository → DB

אסור:

• SQL בתוך Controller
• לוגיקה עסקית בתוך Route
• בדיקות ולידציה בתוך Repository

---

אחריות כל שכבה

Route

• ניתוב בלבד
• חיבור middleware

Controller

• request / response
• קודי סטטוס
• העברת נתונים ל-Service

Service

• כל הלוגיקה העסקית
• בדיקות תנאים
• חוקים מורכבים
• שילוב כמה repositories

Repository

• שאילתות בלבד
• אין if עסקי
• אין החלטות

---

2️⃣ ולידציה (קריטי)

כלל ברזל:

כל קלט חיצוני עובר ולידציה לפני שהוא מגיע ל-Service.

חובה:

• שימוש בסכמה (Zod / Joi)
• בדיקה של ערכים ריקים
• בדיקת טיפוסים
• בדיקת טווחים
• בדיקת פורמט (טלפון, זמן וכו')

אסור:

• לבדוק טיפוס בתוך Service
• לסמוך על הלקוח

---

3️⃣ עבודה עם SQL

חובה:

Prepared Statements בלבד
שימוש ב־? placeholders
אין שרשור מחרוזות ל-SQL
אין הכנסת ערכים ישירות ל-ORDER BY

אסור:

const sql = "SELECT * FROM ads WHERE phone = " + phone;

---

כלל חשוב נוסף

אם שאילתה חוזרת על עצמה ביותר ממקום אחד →
להוציא אותה ל-Repository פונקציה ייעודית.

---

4️⃣ שגיאות (Error Handling)

סוגי שגיאות

Business Error

• משתמש חרג ממגבלה
• ערך לא חוקי לפי כללי מערכת
• פעולה כפולה

→ מחזירים 400 עם הודעה ברורה

---

System Error

• DB לא עונה
• קריסה לא צפויה
• בעיית קישוריות

→ לוג ERROR
→ מחזירים 500 כללי

---

כלל ברזל:

לא לבלוע שגיאות.

אסור:

catch (e) {}

---

5️⃣ לוגים

רמות:

• INFO → אירועים עסקיים תקינים
• WARN → חריגה לא קריטית
• ERROR → תקלה מערכתית

אסור:

• console.log בפרודקשן
• לוגים מפוצצים בלי צורך

---

6️⃣ מבנה פונקציות

כללים פשוטים:

פונקציה עושה דבר אחד
שם מסביר למה היא קיימת
עדיף פחות מ-30 שורות
יותר מ-3 פרמטרים? שקול להעביר אובייקט

---

7️⃣ שמות

אסור:

• data
• temp
• info
• manager
• handler

כן:

• createAdIfAllowed
• validateRingModeForPublisher
• findAdsByPhone

שם צריך להסביר כוונה.

---

8️⃣ Hard Coding

אסור:

• ערכי DB בקוד
• URL בקוד
• מפתחות API בקוד
• מספרי קסם (magic numbers)

כן:

• משתני סביבה
• קובץ config מרכזי

---

9️⃣ בדיקות (בצורה ריאלית)

לא צריך 3 רמות לכל פונקציה.

כן צריך:

בדיקות לפונקציות לוגיקה מורכבות
בדיקות למקרים חריגים
בדיקה לפחות ל-happy path

---

ביצועים וניקיון

לא לבצע שאילתות מיותרות
לא לטעון הכל לזיכרון אם לא צריך
לא לבצע לולאות על תוצאות DB בלי סיבה
להשתמש ב-LIMIT כשאפשר

---

1️⃣1️⃣ אבטחה (קריטי למערכת טלפונית)

כל קלט מסונן
אין echo של שגיאת DB
אין חשיפת stack trace
Rate limit ל-API אם רלוונטי
לא לסמוך על client-side validation

---

1️⃣2️⃣ עקרון הזהב

אם אתה שואל את עצמך:

"איפה לשים את הקוד הזה?"

שאל:

• האם זו החלטה עסקית? → Service
• האם זו שאילתת DB? → Repository
• האם זו בדיקת קלט? → Validator
• האם זו תגובת HTTP? → Controller

---

גרסה מקוצרת במיוחד (לשים מול העיניים)

1. אין SQL מחוץ ל-Repository
2. אין לוגיקה מחוץ ל-Service
3. אין קלט בלי ולידציה
4. אין שרשור SQL
5. אין בליעת שגיאות
6. אין Hard Coding
7. פונקציות ברורות וקצרות
8. לוגים ברמות נכונות

---

או באנגליתAI_RULES.md

תודה

[צדיק תמים]

בגדול נכון
את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לשאילתות תשתמש בספריה מוכנה של query builder, לדוגמה https://github.com/knex/knex, ולפרויקט עתידי כדאי לשקול ORM

[A0533057932]

@צדיק-תמים את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לא מדוייק
זה סגנון עבודה שתמיד כדאי לעשות
להתחיל בצורה מסודרת מאפשר לך להחליף חלקים בצורה קלה בלי לפגוע במבנה כלל
או בדוגמה בפייתון
להחליף בין fastAPI לפלאסק לכל מנגנון אחר בלי להשפיע על כל המערכת
לשנות לוגיקה בלי לגעת בראוטים או בDB
להחליף DB בלי לשנות לוגיקה של התוכנה
וכן הלאה

במיוחד שעובדים עם AI אים שום סיבה לא לנהל את הפרוייקט בצורה מלאה ותקינה לא משנה מה גודל הפרוייקט

[צדיק תמים]

@A0533057932 להחליף פריימוורק זה לא בשכבת ה Service או ה Repository
להחליף DB זה לא צורך נפוץ, בפרויקט קטן זה לא שווה את המורכבות של לעטוף הכל במעין ORM במימוש עצמי
להפריד לסרוויס כן יותר נפוץ, אבל להפריד ריפוזיטורי זה שימושי בעיקר אם אתה עושה טסטים מלאים עם DI אחרת זה סתם שכבה מיותרת שמפריעה להבנה של הקוד