CH3-002 · מכונת מצבים דטרמיניסטית ל-Trade

היום Trade.status הוא enum שטוח [pending, approved, executed, rejected]. המעברים מפוזרים ומרומזים בלבד — ב-runAgentScan, executeTrade, refreshPortfolioPrices וב-UI הידני. אין מצבים ל"ממתין לתנאי", "פג תוקף", "הועבר לבדיקה". תוצאה: עסקאות pending ישנות שנותרות תלויות, TTL אישור אינו מיוצג כמצב, ואין מקור אמת אחד למעברים החוקיים.

מכונת מצבים אחת, דטרמיניסטית, אטומית, אידמפוטנטית וניתנת לשחזור מלא, שכל שינוי סטטוס במערכת חייב לעבור דרכה. פונקציית מעבר אחת, טבלת מעברים אחת, רשומת Audit אחת לכל מעבר (כולל יצירה ואישור מחדש).

CH3-002 נוגע למישור 2 (Trade.status) בלבד. מישור 3 (execution_state) שייך ל-CH3-003 — מצב "ממתין למילוי" לאחר שליחת פקודה אינו מיוצג ב-wait.

transitionTradeStatus(tradeId, expectedFrom, expectedVersion, to, actorContext, reasonCode, idempotencyKey) היא הדרך היחידה לשנות status של Trade קיים. אף קוד אינו רשאי לכתוב Trade.update({ status }) ישירות (אכיפת grep).

rejected = החלטה שלילית מפורשת (ידנית או דטרמיניסטית של Risk Gate). תפוגה / סטיית מחיר / שוק סגור / נתונים ישנים / תקלה → expired.

wait מייצג Trade שכבר אושר אך ביצועו חסום זמנית — נכנס רק מ-approved. wait → approved אינו אישור חדש, אלא החזרת אישור קיים לאחר אימות TTL + Trade Validity + Risk Gate מחדש. ל-wait משמעות אחת בלבד.

Risk Gate אינו מעניק אישור עסקי — הוא רק מרשה המשך / דוחה / מסלים. אישור ראשוני pending→approved מבוצע רק על ידי Approval או משתמש מורשה; החזרת אישור קיים wait→approved מותרת ל-EXECUTION_GATE לאחר TTL, Trade Validity ו-Risk Gate. (תיקון 0.31)

approved → executed מותר רק לאחר אישור סופי מ-CH3-003 בהתאם למדיניות המילוי. שליחה לבד ≠ executed; Timeout ≠ executed; Partial Fill אינו עובר אוטומטית; RECONCILIATION_REQUIRED אינו משנה Trade.status.

approved נשאר בתוקף גם לאחר שליחת פקודה — execution_state מנהל את הפקודה עצמה (CH3-003).

אידמפוטנטיות: Retry של אותה בקשה משתמש באותו idempotency_key ומחזיר את אותה תוצאה — ללא מעבר או Audit נוסף. פעולה עסקית חדשה / אישור מחדש / Trade חדש מקבלים מפתח חדש. (תיקון 0.3)

transition_id ו-idempotency_key הם שני ערכים שונים — אסור לאחד אותם לשדה אחד. transition_id מזהה מעבר ספציפי; idempotency_key מאפשר Retry בטוח. (תיקון 0.3)

expectedFrom הוא פרמטר קריאה (חלק מהסכם ה-CAS), לא שדה שמור ב-Trade. ב-Trade נשמרים רק: status, status_version ושדות התפוגה הנדרשים. (תיקון 0.3)

Actor נגזר מהקשר משתמש מאומת או משירות פנימי מורשה — אסור לקרא לשלוח actor="APPROVAL" באופן חופשי ולהעניק לעצמו סמכות. טבלת הרשאות Actor לכל מעבר; reason_code קנוני לבדיקות ודוחות; טקסט חופשי רק כהסבר נוסף. (תיקון 0.3)

שחזור: Trade ללא Audit אינה ניתנת לשחזור בוודאות. נדרשת אחת משתי הכרעות — Transaction אטומי של Trade+Message, או Transition Journal/Outbox שנכתב לפני/יחד עם שינוי הסטטוס. "סריקה מתקנת" בלבד אינה עומדת בדרישת Message כמקור אמת. (תיקון 0.3)

גבול TTL מדויק ב-UTC: now < approval_expires_at → אישור תקף; now >= approval_expires_at → פג. pending משתמש ב-Proposal TTL נפרד מ-Approval TTL של approved/wait. (תיקון 0.3)

דטרמיניסטי לחלוטין — אף LLM אינו מעורב במכונה. כל הסטטוסים lowercase.

חסימת שינוי לאחר שליחה: כאשר execution_state != NOT_SENT, Trade Validity, Risk Gate, Global Freeze ושאר בדיקות טרום-שליחה אינן רשאיות לשנות את Trade.status. לאחר השליחה, רק אירוע סופי ומאומת מ-CH3-003 (חוזה הסיום) רשאי לבצע מעבר שהוגדר בחוזה הסיום. אחרת refreshPortfolioPrices עלול להפוך ל-expired עסקה שכבר נמצאת אצל הברוקר. (תיקון 0.31)

null → pending אינו ניתן למימוש דרך transitionTradeStatus(tradeId) — זה מניח שהרשומה כבר קיימת, אך בשלב היצירה היא עדיין לא קיימת. (תיקון 0.3)

פעולת יצירה ייעודית ואטומית createTradeWithAudit(...) יוצרת יחד: Trade חדש ב-pending, status_version התחלתי, רשומת Message Audit ראשונה, transition_id ו-idempotency_key.

היא משתמשת באותו מנגנון Audit כמו transitionTradeStatus — שרשרת ההיסטוריה מתחילה בראשית, לא באמצע.

approved → executed מותר רק לאחר אישור סופי מ-CH3-003 בהתאם למדיניות המילוי שתיקבע שם. (תיקון 0.3)

שליחה לבד ≠ executed. Timeout ≠ executed. Partial Fill אינו עובר אוטומטית ל-executed.

RECONCILIATION_REQUIRED (CH3-003) אינו משנה את Trade.status.

approved נשאר בתוקף לאחר שליחת פקודה — execution_state מנהל את הפקודה; Trade.status ממתין לאישור הסופי.

כל הזמנים נשמרים ומושווים ב-UTC. (תיקון 0.3)

now < approval_expires_at → האישור תקף. now >= approval_expires_at → האישור פג.

pending משתמש ב-Proposal TTL נפרד (proposal_expires_at) מ-Approval TTL של approved/wait (approval_expires_at). שני השעונים מוגדרים במפורש. proposal_expires_at נוסף לסכמת Trade ו-proposal_ttl_hours ל-SystemSettings; createTradeWithAudit מאתחל ומדיניות Migration מטפלת ב-pending קיימות. (תיקון 0.31)

אישור מחדש של רשומה שפגה (expired) יוצר Trade חדש עם idempotency_key חדש — וגם כותב Message ייעודי המקשר ביניהן. (תיקון 0.3)

ה-Message כולל לפחות: expired_trade_id, new_trade_id, סיבת האישור מחדש, והמשתמש/הרכיב שיזם אותו.

כך ניתן לשחזר את שרשרת ההיסטוריה המלאה גם כשהצעה נפתחת מחדש.

אסור שהקרא יוכל לשלוח actor="APPROVAL" באופן חופשי ולהעניק לעצמו סמכות. Actor נגזר מהקשר משתמש מאומת או משירות פנימי מורשה. טבלת הרשאות Actor לכל מעבר נאכפת; reason_code קנוני לבדיקות ודוחות; טקסט חופשי רק כהסבר נוסף.

לא לשנות רשומות rejected על סמך תאריך approval_expires_at בלבד — Trade שנדחתה ידנית לפני חודש תיפגה כיום בתנאי אף שלא נדחתה בגלל TTL.

להמיר rejected → expired רק כאשר קיימת ראיית Audit מפורשת שהסיבה הייתה TTL או סטיית מחיר.

ללא ראיה חד-משמעית — להשאיר rejected.

שדות תפוגה חייבים להיות ריקים כאשר status אינו expired; להסיר expiration_reason="pending_manual_review" מרשומות שנשארות rejected.

חד-פעני, הפיך — סקריפט rollback מוכן לפני הרצה. מפתח Migration: trade.id בלבד.

רשומות קיימות עם pending/approved/executed נשארות כשתפקידן — תוספתי בלבד.

אישור מחדש של expired → יצירת Trade חדש עם idempotency_key חדש (לא פתיחת הישנה) + כתיבת Message קישור (expired_trade_id, new_trade_id, סיבה, מזמים).

גבול TTL מדויק ב-UTC: now < approval_expires_at → תקף; now >= → פג. pending משתמש ב-Proposal TTL נפרד.

Global Freeze: חל על קנייה חדשה בלבד. מכירה / צמצום / יציאה מותרות גם בהקפאה — אינן חסומות במעבר ל-executed.

Partial Fill / Reconciliation: אינם משנים Trade.status. מטופלים ב-execution_state (CH3-003) בלבד.

Retry: אותה בקשה חוזרת עם אותו idempotency_key ומחזירה אותה תוצאה — ללא מעבר/Audit נוסף.

base44/entities/Trade.jsonc — enum + status_version + last_transition_id/last_idempotency_key (Cache) + proposal_expires_at + approval_expires_at + שדות תפוגה (⚠ דורש אישור Architect). expectedFrom אינו נשמר. (תיקון 0.31)

base44/entities/SystemSettings.jsonc — הוספת proposal_ttl_hours (תיקון 0.31).

base44/shared/stateMachine.ts (חדש) — transitionTradeStatus() + createTradeWithAudit() + assertTransitionAllowed() + CAS (status_version) + Outbox (Transition Journal) נבחר + Audit קנוני + טבלת הרשאויות Actor + חסימת טרום-שליחה (תיקון 0.31)

base44/shared/tradeExecution.ts — כל שינוי status דרך המכונה; approved→executed רק לאחר אישור סופי מ-CH3-003

base44/functions/refreshPortfolioPrices/entry.ts — תפוגה/סטיית מחיר → expired (UTC); Risk Gate אינו מאשר

base44/functions/runAgentScan/entry.ts — יצירת הצעה דרך createTradeWithAudit

base44/functions/executeTrade/entry.ts — wait→approved (החזרת אישור); approved→executed רק לאחר אישור סופי; איסור wait→executed, pending→wait

src/pages/Trades.jsx + src/components/invest/Badges.jsx — תצוגת wait / expired / escalated_for_review

מעבר לא-חוקי (pending→wait, pending→executed, wait→executed) נדחה בשגיאה ומתועד.

wait נכנס רק מ-approved; wait→approved אינו אישור חדש אלא החזרת אישור קיים לאחר TTL+Validity+Risk Gate מחדש.

approved→executed מתרחש רק לאחר אישור סופי מ-CH3-003; שליחה/Timeout/Partial Fill אינם executed; RECONCILIATION_REQUIRED אינו משנה status.

Risk Gate אינו מבצע מעבר ל-approved (רק APPROVAL / ידני).

createTradeWithAudit יוצר Trade+status_version+Audit+transition_id+idempotency_key יחד (null→pending מתועד).

Retry עם אותו idempotency_key מחזיר אותה תוצאה ללא מעבר/Audit נוסף; פעולה חדשה → מפתח חדש.

transition_id ו-idempotency_key שמורים בשני שדות נפרדים.

expectedFrom/expectedVersion אינם נשמרים ב-Trade (פרמטרי קריאה בלבד).

מרוץ מקבילי נבלם: שתי בקשות על pending → רק אחת מצליחה (CAS / status_version).

שחזור: Transition Journal/Outbox נבחר מאפשר התאוששות מלאה (מי/מה קדם/סיבה/idempotency_key). transition_id ו-idempotency_key נשמרים בנפרד ב-Outbox; ב-Trade נשמרים רק last_transition_id ו-last_idempotency_key כ-Cache.

Actor נגזר מהקשר מאומת; טבלת הרשאות Actor לכל מעבר נאכפת; reason_code קנוני.

גבול TTL ב-UTC: now < approval_expires_at → תקף; now >= → פג; pending משתמש ב-Proposal TTL נפרד.

אישור מחדש של expired → Trade חדש + Message קישור (expired_trade_id, new_trade_id, סיבה, מזמים).

Migration מומש רק עם ראיית Audit מפורשת; ללא ראיה — rejected; שדות תפוגה ריקים כשאינו expired.

grep בקוד מאפס Trade.update({ status }) מחוץ ל-stateMachine.

כל מעבר מתועד ב-Message עם from→to, actor, reason_code, trade_id, transition_id, idempotency_key.

מעבר לאותו סטטוס נוכחי = no-op שקט. כל הסטטוסים lowercase.

כאשר execution_state != NOT_SENT — Trade Validity/Risk Gate/Global Freeze אינן משנות Trade.status; רק חוזה הסיום מ-CH3-003. (תיקון 0.31)

מקור האמת ל-idempotency הוא ה-Outbox/Journal (תוצאה מקורית שאינה נדרסת); ב-Trade רק Cache (last_transition_id, last_idempotency_key). Retry ישן מחזיר את התוצאה המקורית גם לאחר מעברים נוספים. (תיקון 0.31)

proposal_expires_at קיים ב-Trade; proposal_ttl_hours ב-SystemSettings; createTradeWithAudit מאתחל; Migration ל-pending קיימות; קבלה now >= proposal_expires_at. (תיקון 0.31)

Actor קנוני: pending→approved = Approval/משתמש; approved↔wait = EXECUTION_GATE; approved→executed = EXECUTION(CH3-003). טבלת הרשאויות Actor ורשימת reason_code מצורפות. (תיקון 0.31)

1. base44/shared/stateMachine.ts: transitionTradeStatus() + createTradeWithAudit() + assertTransitionAllowed() + CAS (status_version) + Transition Journal/Outbox + Audit קנוני + טבלת הרשאות Actor.

2. base44/entities/Trade.jsonc + SystemSettings.jsonc: enum + status_version + last_transition_id/last_idempotency_key (Cache) + proposal_expires_at + approval_expires_at + שדות תפוגה; SystemSettings: proposal_ttl_hours (עם אישור Architect). expectedFrom אינו נשמר. (תיקון 0.31)

3. רפקטור כל כתיבת status ב-tradeExecution / refreshPortfolioPrices / runAgentScan / executeTrade למכונה; יצירה דרך createTradeWithAudit.

4. מדיניות מילוי: approved→executed רק לאחר אישור סופי מ-CH3-003; שליחה/Timeout/Partial Fill אינם executed.

5. Migration בטוח (ראיית Audit בלבד) + rollback; סריקת UTC ל-TTL.

6. Message קישור אישור מחדש (expired_trade_id/new_trade_id).

7. עדכון UI: Trades.jsx + Badges.jsx — תצוגת wait/expired/escalated_for_review.

8. בדיקת קבלה מתועדת + דוח ביצוע (Ch3ExecutionReport002).