פרויקט צוותי: תכנון — Repo, Issues ו-Interface Contracts

מה זה?#

זהו הפרויקט הצוותי הראשון של הקורס: מערכת “מודיעין עסקי” (Intelligence System) עם ארבעה שירותים — Collector, Analyzer, Alert, Dashboard — כל אחד בבעלות חבר צוות אחר, לפי כל מה שנלמד ביחידת המיקרוסרביסים (Bounded Context, sync/async). לפני שכותבים קוד, צריך תכנון: מי אחראי על מה, ובעיקר — מה בדיוק כל שירות שולח/מצפה לקבל משכניו, כדי ששני אנשים שכותבים קוד במקביל לא “יתנגשו” כשמחברים הכל בסוף.

מילות מפתח שחשוב לזכור#

• Interface Contract (חוזה ממשק) — הסכם מפורש על מבנה הנתונים בין שירותים (JSON schema, Topic names) — נכתב לפני קוד, לא מגלים אותו תוך כדי אינטגרציה

• Issue — משימה בודדת מתועדת (ב-GitHub/Jira) שאפשר להקצות, לעקוב אחריה ולסגור

• Milestone — קבוצת Issues שמסמנת יעד ביניים משותף (למשל “כל שירות שולח/מקבל הודעה בסיסית”)

• Repo Setup — מבנה ריפוזיטורי הגיוני לפרויקט מרובה-שירותים (תיקייה נפרדת לכל שירות, או ריפואים נפרדים)

# Interface Contract — written and agreed on before code, e.g. as a shared README/document

Topic: "event-collected"
Producer: Collector Service
Consumers: Analyzer Service

Message Schema (JSON):
{
  "eventId": "string (UUID)",
  "eventType": "string",
  "value": "number",
  "timestamp": "string (ISO 8601)",
  "source": "string"
}

# Suggested repo structure — a monorepo with a folder for each service
intelligence-system/
├── collector-service/     (C# — owner: team member A)
├── analyzer-service/      (Python — owner: team member B)
├── alert-service/         (C# — owner: team member C)
├── dashboard-service/     (Python — owner: team member D)
├── docker-compose.yml     (runs everything together — the integration lesson)
└── CONTRACTS.md           (all interface contracts in one place)

הסבר עיקרי#

Interface Contract הוא ה-DDD בפעולה — זוכרים Bounded Context ו-Ubiquitous Language מיחידת המיקרוסרביסים? Interface Contract הוא איך זה נראה בפועל: לפני שחבר הצוות שכותב Collector וחבר הצוות שכותב Analyzer כותבים קוד, הם מסכימים בכתב על מבנה ה-JSON שעובר ביניהם דרך Kafka (מיחידת NoSQL). בלי זה, כל אחד “מנחש” את המבנה, וגילוי אי-ההתאמה קורה רק באינטגרציה — מאוחר ויקר.

Issues/Milestones הם ניהול פרויקט אמיתי, לא רק “רשימת מטלות” — Milestone (“כל שירות שולח הודעה בסיסית”) נותן יעד ביניים משותף וניתן-לבדיקה — לא “כל אחד עובד בבועה שלו עד הסוף”. Issues בודדים בתוך Milestone (כמו “Collector: endpoint לקליטת אירוע”, “Analyzer: קריאת הודעה מ-Kafka”) מאפשרים לעקוב מי עובד על מה, ולזהות מוקדם אם מישהו נתקע.

מבנה Repo — Monorepo מול ריפואים נפרדים — Monorepo (הצעה בדוגמה) שם את כל השירותים תחת ריפו אחד, בתיקיות נפרדות — נוח לראות את כל הפרויקט יחד, במיוחד בקורס עם docker-compose משותף. הגישה החלופית (ריפו נפרד לכל שירות) מדמה סביבת עבודה אמיתית יותר, אך מוסיפה מורכבות ניהולית לפרויקט לימודי בהיקף כזה.

יתרונות#

תכנון מוקדם עם Interface Contracts מונע גילוי אי-התאמות מאוחר ויקר; Issues/Milestones נותנים נראות לכל הצוות על התקדמות ותלויות; חלוקת בעלות ברורה (חבר אחד = שירות אחד) מונעת “כולם נוגעים בהכל” שיוצר קונפליקטים.

חסרונות#

תכנון-יתר לפני שיש הבנה מעשית של הבעיה עלול לבזבז זמן על חוזים שישתנו בכל מקרה; חלוקת בעלות קשיחה מדי עלולה ליצור “צווארי בקבוק” אם חבר צוות אחד נתקע ואחרים לא יכולים לעזור בלי הקשר.

נקודות חשובות#

• Interface Contract נכתב לפני קוד — מונע גילוי אי-התאמות רק באינטגרציה

• Milestone = יעד ביניים משותף; Issue = משימה בודדת ניתנת-להקצאה

• תכנון פרויקט מיקרוסרביסים אמיתי דורש גם ידע טכני וגם תיאום צוותי מפורש

• זהו יישום מעשי ישיר של Bounded Context ו-Ubiquitous Language מהיחידה הקודמת

טעויות נפוצות#

• להתחיל לכתוב קוד בלי חוזה ממשק מוסכם, ולגלות אי-התאמות רק באינטגרציה

• Issues מעורפלים מדי (“לעבוד על Analyzer”) במקום ספציפיים וניתנים-לבדיקה (“Analyzer: לקרוא הודעה מ-Kafka ולהדפיס אותה”)

• לתכנן יותר מדי מראש, לפני שיש הבנה בסיסית של איך המערכת בכלל אמורה לעבוד

סיכום#

תכנון פרויקט מיקרוסרביסים צוותי מתחיל ב-Interface Contracts (מבנה ה-JSON/Topics המוסכם בין שירותים, לפני קוד), חלוקת בעלות ברורה לכל חבר צוות, ו-Issues/Milestones שנותנים מבנה ומעקב. זהו יישום ישיר ומעשי של Bounded Context ו-Ubiquitous Language מיחידת המיקרוסרביסים — לא תיאוריה, אלא איך עובדים בפועל כשכמה אנשים בונים שירותים נפרדים שצריכים “לדבר” ביחד בסוף.

דוקומנטציה רשמית#

GitHub — About issues

GitHub — About milestones

תרגילים#

תרגיל 1 — כתיבת Interface Contract#

המשימה: כתבו Interface Contract (כמו בדוגמה) עבור Topic anomaly-detected — מה Analyzer שולח, ומה Alert Service מצפה לקבל.

בדיקה: החוזה כולל שם Topic, Producer/Consumer, וסכימת JSON מלאה עם כל השדות.

תרגיל 2 — פירוק ל-Issues#

המשימה: פרקו את המשימה “Collector Service שולח אירועים ל-Kafka” ל-4 Issues קונקרטיים וניתנים-לבדיקה.

בדיקה: כל Issue הוא יחידת עבודה ברורה, לא “לעבוד על X” כללי.

פרויקט מסכם#

המשימה: הצוות (4 חברים) יגדיר את כל תשתית התכנון לפרויקט “מערכת מודיעין” לפני כתיבת קוד.

דרישות:

1. חלוקת בעלות: מי אחראי על Collector/Analyzer/Alert/Dashboard
2. Interface Contracts מלאים לכל תקשורת בין שירותים (לפחות 3 חוזים: Collector→Analyzer, Analyzer→Alert, כולם→Dashboard)
3. Repo (Monorepo מוצע) עם מבנה תיקיות מוסכם, ו-CONTRACTS.md עם כל החוזים
4. Milestone ראשון מוגדר עם Issues קונקרטיים לכל חבר צוות

בדיקה: כל חבר צוות יודע בדיוק על מה הוא אחראי ומה הוא מצפה לקבל/לשלוח לשירותים אחרים, לפני שכתבו שורת קוד אחת.

מה בפרק הבא#

בפרק הבא — Collector Service: השירות הראשון בפרויקט — קולט אירועים דרך REST API ומפרסם אותם ל-Kafka, ב-C#.