webapp.sticky_notes_api module

Sticky Notes API for Markdown preview - Stores user-specific notes per file in MongoDB - Endpoints: list, create, update, delete

webapp.sticky_notes_api.emit_event(event, severity='info', **fields)[מקור]
פרמטרים:
webapp.sticky_notes_api.get_db()[מקור]
webapp.sticky_notes_api.reset_index_state_for_tests()[מקור]

מחזיר את מצב ”האינדקסים מוכנים“ למצב של תהליך שזה עתה עלה. לטסטים בלבד.

_ensure_indexes זוכר את מה שגילה בגלובלים של המודול, והם חיים כל עוד התהליך חי: _INDEX_READY, _TITLE_INDEX_OK ו-_REPO_TITLE_INDEX_OK, מועד הניסיון הבא _INDEX_RETRY_AFTER, החלון _INDEX_CACHE_LAST_CHECK של קריאת הדגל המשותף, ו-_WARMUP_TRIGGERED של חימום העלייה. בפרודקשן זו כל הכוונה. בטסטים תהליך אחד מריץ בדיקות רבות ברצף, ובדיקה שהריצה את הבנייה מול stub שאינו מאמת את אינדקס השם משאירה את _INDEX_RETRY_AFTER פתוח למשך _INDEX_RETRY_SECONDS — ובדיקה שבאה אחריה באותו תהליך מקבלת מ- _ensure_indexes יציאה מוקדמת, בלי שאף אינדקס נבנה.

רשימה אחת, ליד המצב. עד כאן כל קובץ טסט החזיק רשימה משלו של מה לאפס, והרשימות נסחפו: indexed_db ב-tests/test_note_boards_mongo.py איפס את השומרים שהכיר, ולא את _INDEX_RETRY_AFTER. מי שמוסיף כאן מצב מוסיף אותו גם לפונקציה הזו, ו-tests/test_sticky_notes_index_state.py נופל אם לא. בקוד הייצור אין לה קורא; בין בדיקות קורא לה הפיקסצ’ר האוטומטי ב- conftest.py שבשורש הריפו, לפני כל בדיקה ואחריה.

הדגל המשותף נמחק, ונקרא בחזרה — מהלקוח עצמו. _cache_flag_ready קורא אותו מהקאש של המודול (_shared_cache) — Redis, או קאש מדומה של בדיקה — ולכן איפוס של הזיכרון לבדו אינו מספיק. המחיקה והקריאה החוזרת אינן עוברות דרך CacheManager: get שלו מחזיר None גם כשאין מפתח וגם כש-Redis לא ענה, ו-delete מחזיר False גם כשהמפתח לא היה וגם כשהמחיקה נכשלה, ולכן אף אחד מהם אינו עדות. הלקוח שמאחוריו (redis_client) מחזיר None רק על מפתח שאינו קיים, וזורק כשהוא אינו עונה — לפי קוד המקור של redis-py 7.0.0: ה-docstring של get ב-redis/commands/core.py, ו-raise error בסוף Retry.call_with_retry ב-redis/retry.py.

ערוץ הכשל הוא חריגה. דגל ששרד את המחיקה זורק RuntimeError, ושגיאה של הלקוח עולה כמו שהיא: איפוס שנכשל וממשיך בשקט היה מחזיר בדיוק את מה שהוא בא לתקן — בנייה שיוצאת מוקדם, ובדיקות שנופלות על מסד ריק מסיבה שאין לה קשר לקוד שהן בודקות.

עבודה שהתחילה לפני האיפוס אינה כותבת אחריו. האיפוס מקדם את _INDEX_STATE_GENERATION תחת _INDEX_READY_LOCK. בנייה שכבר בתוך הנעילה מסתיימת קודם — כולל הקביעה של _INDEX_RETRY_AFTER כשהיא נכשלת — והאיפוס מנקה את מה שהיא פרסמה. קריאה שהתחילה לפני האיפוס ומגיעה לנעילה אחריו — בקשה שהמתינה לה, או חימום של kickoff_index_warmup שתוזמן ועוד ישן — יוצאת בלי לבנות ובלי לכתוב.

ומה שאינו מכוסה, בכוונה: בדיקת המוכנוּת של _ensure_indexes — הדגל בזיכרון והדגל המשותף — רצה לפני הנעילה, כדי שבקשה רגילה תצא בלי לגעת בה (docs/performance-sticky-notes.rst). _cache_flag_ready שרץ באותו רגע עצמו בחוט אחר יכול עדיין לכתוב אחרי האיפוס: לאמץ דגל משותף שקרא לפני המחיקה ולהדליק את מה שכובה, או לקדם את _INDEX_CACHE_LAST_CHECK; וכך גם הבדיקה וההדלקה של _WARMUP_TRIGGERED ב-kickoff_index_warmup. בין בדיקות, זה דורש חוט שעדיין רץ אחרי שהבדיקה שלו הסתיימה, ושנמצא בתוך הקטע הזה בדיוק ברגע האיפוס.

Return type:

None

webapp.sticky_notes_api.kickoff_index_warmup(*, background=True, delay_seconds=0.0)[מקור]

Run index warmup once during startup so requests won’t block on it.

Return type:

None

פרמטרים:
webapp.sticky_notes_api.require_auth(f)[מקור]
webapp.sticky_notes_api.notes_rate_limit(key, max_per_minute)[מקור]
פרמטרים:
  • key (str)

  • max_per_minute (int)

webapp.sticky_notes_api.list_notes(file_id)

List all sticky notes for current user and file.

פרמטרים:

file_id (str)

webapp.sticky_notes_api.get_note_reminder(note_id)
פרמטרים:

note_id (str)

webapp.sticky_notes_api.set_note_reminder(note_id)
פרמטרים:

note_id (str)

webapp.sticky_notes_api.delete_note_reminder(note_id)
פרמטרים:

note_id (str)

webapp.sticky_notes_api.snooze_note_reminder(note_id)
פרמטרים:

note_id (str)

webapp.sticky_notes_api.BADGE_REFRESH_SECONDS = 300

כשיש בועה על המסך השרת מבקש מהלקוח לחזור לכל היותר בעוד חמש דקות — המרווח הקבוע שהיה כאן לפני הדגימה לפי השרת, וזה שריענן גם ניקוי ממכשיר אחר וגם מונה שהשתנה. הערך יושב בשרת ולא בלקוח כדי שללקוח יישאר כלל אחד: ”ישן כמה שהשרת אמר, בין הרצפה לתקרה“. תזכורת נוספת שמבשילה מוקדם יותר גוברת עליו.

webapp.sticky_notes_api.reminders_summary()

Return minimal summary for persistent UI badge.

Response:

{ ok, has_due: bool, count_due: int, next_in_seconds: int | null }

``next_in_seconds`` הוא מה שמחליף את הדגימה הקבועה. עד כאן הלקוח דגם כל חמש דקות בלי קשר למצב, כי ”כן/לא“ היה כל מה שקיבל — 954 קריאות ביממה שכולן החזירו ”אין“. השרת הוא היחיד שיודע גם מתי התזכורת הבאה, ולכן הוא זה שאומר ללקוח מתי לחזור — גם כשיש בועה: אז התשובה היא לכל היותר BADGE_REFRESH_SECONDS, כדי שבועה שנוקתה ממכשיר אחר ומונה שהשתנה ייראו תוך דקות ולא אחרי חצי שעה. אין תזכורת עתידית ואין בועה ← None, והלקוח נרדם עד התקרה שלו (חצי שעה) — לא לנצח, כדי שתזכורת שתיקבע ממכשיר אחר עדיין תתגלה.

והערך יחסי, לא חותמת. remind_at שנקרא מהמסד הוא מודע-אזור רק כל עוד הלקוח נבנה עם tz_aware — ומחרוזת ISO בלי offset נקראת ב-JavaScript כזמן מקומי, כלומר שלוש שעות סטייה בלי שגיאה. מספר שניות אין לו אזור זמן, והוא גם חסין לשעון לקוח שסוטה.

webapp.sticky_notes_api.reminders_list()

Return a list of due sticky‑note reminders for the current user.

Response:

{
  "ok": true,
  "items": [
    { "note_id": "...", "file_id": "...", "preview": "...", "anchor_id": "h2-intro", "anchor_text": "Intro",
      "remind_at": "2026-09-20T09:00:00+00:00" }
  ],
  "count": 1
}

remind_at הוא המועד שהפריט הזה נורה עליו; החלונית מחזירה אותו ב-ack, כדי שהאישור ייקשר למועד הזה ולא ל“איזו שהיא“ תזכורת של הפתק.

preview הוא השם שבו החלונית מציגה את הפתק — sticky_notes_target.note_label, אותה פונקציה שממלאת את התראת הפוש (push_api._reminder_label) ואת הדשבורד: שם הפתק, ובלעדיו השורה הראשונה שלו. שם השדה נשאר preview מהתקופה שלפני שמות, כדי לא לשבור את החוזה עם הדף.

webapp.sticky_notes_api.reminders_ack()

Mark current due reminder as acknowledged (user opened it).

סוגר את שני שדות המצב יחד. עד כאן נכתב ack_at בלבד, ו-status נשאר pending לנצח — כך שכרטיס הדשבורד, שסופר לפי status, דיווח תזכורות ”בהמתנה“ שאיש לא המתין להן. השדות מגיעים מ- note_reminder_state.acknowledge_fields(), שמחזירה את שניהם או אף אחד, ומונגו מחילה אותם ב-$set יחיד.

ונקשר למועד שההתראה נשאה. בלי remind_at בגוף, האישור סגר ”איזו שהיא“ תזכורת של הפתק; וכשהפתק נדרך מחדש אחרי שההתראה נורתה — בדיוק מה שעושים כשתזכורת מגיעה ברגע לא נוח — התראה ישנה במגש סגרה את התזכורת של מחר, כי set_note_reminder עושה upsert על אותו מסמך ויש תמיד שורה אחת לפגוע בה. עם המועד, הפילטר תופס רק את המסמך שעדיין נושא אותו: מסמך שנדרך מחדש או נדחה מאז עונה 404, ונשאר פעיל. לקוח שאינו שולח מועד (SW ישן במטמון, התראה שהוצגה לפני השדה) מאשר בלי קשירה — ההתנהגות של קודם.

webapp.sticky_notes_api.create_note(file_id)

Create a new sticky note for a file.

פרמטרים:

file_id (str)

webapp.sticky_notes_api.get_note(note_id)

פתק אחד, מלא, עם תקצירי השרשורים שלו — מה שהלקוח מושך כשצריך את המצב הטרי של פתק.

שלושה צרכנים ב-sticky-notes.js: הרענון בכניסה לעריכה, משיכת פתק שהדגימה (?versions=1) מצאה שהשתנה או שנוסף, ובדיקה ישירה של פתק שנעלם מהדגימה — לפני שהוא יורד מהמסך. בלי מסנן משטח: הלקוח מחליט אם הפתק עדיין שלו לפי השדות שבו (archived_at, board_id, הנעיצה), ולכן כל פתק של המשתמש מוחזר, ופתק שנמחק או של משתמש אחר עונה 404 note_not_found. הזרימה — _one_note_in_scope, כמו הפתק הבודד בארכיון ובעמוד הקבצים.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.update_note(note_id)

Update existing note; only owner can update.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.delete_note(note_id)

Delete a note; only owner can delete.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.batch_update_notes()

Batch update multiple notes in one request.

Body format (JSON):

{
  "updates": [
    {
      "id": "...",
      "content": "...",
      "position": {"x": 120, "y": 240},
      "size": {"width": 260, "height": 200},
      "color": "yellow_light",
      "is_minimized": false,
      "line_start": 10,
      "line_end": null,
      "anchor_id": "h2-intro",
      "anchor_text": "Intro",
      "mode": "surface",
      "prev_updated_at": "2024-01-01T00:00:00+00:00"
    }
  ]
}

Response JSON contains results with per-item status, e.g. 200/409.

webapp.sticky_notes_api.archive_note(note_id)

מעביר פתק לארכיון — מכל יעד, ובלי דרך חזרה ליעד הקודם.

גוף אופציונלי: {"title": "..."} — השם שהמשתמש אישר בחלון. בלעדיו נשאר השם הקיים, ופתק בלי שם אינו עובר (resolve_archive_title): הארכיון מנווט לפי שם.

הסדר, וכל שלב בו מגן על משהו:

  1. הפתק קיים ושייך למשתמש — אחרת 404 note_not_found.

  2. כבר בארכיון ← 200 עם already_archived, בלי כתיבה. לחיצה כפולה, או מכשיר שני שעוד מציג את הפתק על הלוח, אינם שגיאה.

  3. השם, ואחריו תקרת הארכיון (MAX_ARCHIVED_NOTES_PER_USER, אדמין פטור). ספירה שנכשלה נדחית (check_note_quota), כמו בכל תקרה אחרת.

  4. כתיבה אחת מותנית (CAS): find_one_and_update שהפילטר שלו דורש שהפתק עדיין אינו בארכיון (active_notes_filter). שתי העברות מקבילות — רק אחת כותבת. None מהמסד אינו הצלחה (K11): קוראים שוב ומסווגים — נמחק בינתיים, או הועבר בבקשה המקבילה.

  5. השרשורים הפתוחים נסגרים רק אחרי שההעברה נכתבה (nt.resolve_open_threads). כשל שם אינו מבטל את ההעברה, שכבר קרתה: threads_resolved: null אומר ללקוח שהשרשורים לא נסגרו, והכשל נרשם בלוג. התזכורת אינה נוגעת: היא נשארת פעילה.

התשובה נבנית מהמסמך שהכתיבה הזו השאירה (ReturnDocument.AFTER), לא ממה שביקשו.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.list_archived_notes()

כרטיסי עמוד הארכיון — מהחדש לישן לפי זמן ההעברה, בלי גוף הפתקים.

max הוא התקרה שחלה על המשתמש, או null לאדמין, שפטור ממנה. שאילתה שנכשלה עונה 500 ולא רשימה ריקה: העמוד אומר ”לא הצלחתי לטעון“, ולא ”הארכיון ריק“.

בלי ``limit``: התשובה היא הרשת כולה, ו-limit בלי דפדוף היה מסתיר מאדמין (שפטור מהתקרה) את הפתקים הישנים בלי שום סימן. העבודה פרופורציונלית לתשובה בדרך אחרת: שלושה שדות בלבד, בסדר של האינדקס ובלי מיון בזיכרון (נמדד ב-explain, tests/test_note_archive_mongo.py), ולמשתמש שאינו אדמין התקרה חוסמת את הרשימה — כמו ברשימות הלוח, שגם בהן אדמין פטור.

לא ``GET /<file_id>``. הקטע archive סטטי, ו-Werkzeug בודק קטע סטטי לפני קטע עם משתנה — וממילא מזהה קובץ הוא ObjectId, ולכן archive אינו יכול להיות אחד.

webapp.sticky_notes_api.get_archived_note(note_id)

פתק אחד מהארכיון, מלא, עם תקצירי השרשורים שלו — כשפותחים כרטיס.

רק פתק שבארכיון ושייך למשתמש; כל פתק אחר עונה 404 note_not_found. כשל בקריאת השרשורים אינו מפיל את התשובה: threads_unavailable, כמו ברשימות של שאר היעדים.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.pin_note_to_files_page(note_id)

נועץ פתק לוח לראש עמוד הקבצים.

גוף אופציונלי: {"device_limit": N} — כמה כרטיסים נכנסים בשורה בעמוד הקבצים במסך שממנו נועצים. הוא רק מוריד את התקרה (files_page_pin_limit), כדי שמכשיר שנכנסים בו שני כרטיסים לא ינעץ שלישי שיוצג אצלו רק כ-”+N“.

הסדר, וכל שלב בו מגן על משהו:

  1. הפתק קיים ושייך למשתמש — אחרת 404 note_not_found. פתק בארכיון — 409 note_archived; פתק שאינו פתק לוח — 400 not_a_board_note.

  2. כבר נעוץ ← 200 עם already_pinned, בלי כתיבה. לחיצה כפולה, או מכשיר שני שעוד מציג את הפתק כלא-נעוץ, אינם שגיאה.

  3. התקרה — MAX_FILES_PAGE_PINNED_NOTES, או פחות לפי המכשיר. תקרה של צורת-תוכן, ולכן is_admin=False תמיד; ספירה שנכשלה נדחית (note_quota_unknown), ולא נחשבת אפס. מלא ← 409 files_page_pins_full, והפתק הישן אינו יורד אוטומטית.

  4. כתיבה אחת מותנית (CAS): find_one_and_update שהפילטר שלו דורש פתק לוח פעיל שעוד אינו נעוץ. None מהמסד אינו הצלחה (K11): קוראים שוב ומסווגים — נמחק בינתיים, ננעץ בבקשה מקבילה, או הועבר לארכיון.

התשובה נבנית מהמסמך שהכתיבה הזו השאירה (ReturnDocument.AFTER). הספירה והכתיבה אינן אטומיות — אותה מגבלה ידועה של כל התקרות (docs/dev/sticky_notes_extending_backend.rst).

פרמטרים:

note_id (str)

webapp.sticky_notes_api.unpin_note_from_files_page(note_id)

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

כתיבה מותנית אחת: $unset רק על פתק שהשדה קיים בו — כל ערך, גם פגום, כדי שהסרה תמיד תנקה. None מהמסד מסווג בקריאה חוזרת: פתק שאינו קיים ← 404; פתק שאינו נעוץ ← 200 עם already_unpinned (לחיצה כפולה או מכשיר שני אינם שגיאה).

פרמטרים:

note_id (str)

webapp.sticky_notes_api.list_files_page_notes()

הכרטיסים לראש עמוד הקבצים — הפתקים הנעוצים, מהראשון שננעץ לאחרון.

בלי ``limit``, ובכוונה: הספירה והכתיבה של הנעיצה אינן אטומיות, ושתי נעיצות מקבילות יכולות להשאיר אחד מעל התקרה. limit היה מסתיר אותו בלי שום סימן, וממנו גם את הדרך להסיר אותו מעמוד הקבצים. שאילתה שנכשלה עונה 500 ולא רשימה ריקה: העמוד אומר ”לא הצלחתי לטעון“, ולא מציג עמוד בלי פתקים כאילו אין נעוצים.

webapp.sticky_notes_api.get_files_page_note(note_id)

פתק נעוץ אחד, מלא, עם תקצירי השרשורים שלו — כשפותחים כרטיס בעמוד הקבצים.

רק פתק נעוץ ופעיל של המשתמש (files_page_pinned_filter); כל פתק אחר — נמחק, הוסר מהנעיצה או הועבר לארכיון ממכשיר אחר — עונה 404 note_not_found, והעמוד מוריד את הכרטיס. כשל בקריאת השרשורים אינו מפיל את התשובה: threads_unavailable, כמו בשאר הרשימות.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.list_board_notes(board_id)

פתקי לוח. שאילתה ישירה, בלי $or ובלי מעבר ב-code_snippets.

פרמטרים:

board_id (str)

webapp.sticky_notes_api.create_board_note(board_id)

פתק חדש על לוח.

פרמטרים:

board_id (str)

webapp.sticky_notes_api.list_repo_notes(repo_name, repo_path)

פתקים על קובץ בריפו ממורר.

סימון היתומים נעשה בקריאה, ולא בכתיבה. אין סריקה תקופתית ואין update_many על מסלול קריאה — זה הלקח מסריקת היתומים של הלוחות. הפתק ממשיך להיות מוחזר עם הנתיב האחרון הידוע, ורק נושא דגל.

פרמטרים:
  • repo_name (str)

  • repo_path (str)

webapp.sticky_notes_api.create_repo_note(repo_name, repo_path)

פתק חדש על קובץ בריפו ממורר.

פרמטרים:
  • repo_name (str)

  • repo_path (str)

webapp.sticky_notes_api.list_repo_orphans(repo_name)

קומה ראשונה: פתקים בריפו הזה שהקובץ שלהם כבר אינו בעץ.

”מיותם“ נגזר מהמראה, לא מ-GitHub. דפדפן הריפו מציג עותק מסונכרן, ולכן קובץ שנמחק ב-GitHub לפני שעתיים עדיין קיים כאן והפתק עליו ייראה תקין עד הסנכרון הבא. לכן מוחזר גם last_sync_time — זה לא באג אם כתוב, וכן באג אם לא.

פרמטרים:

repo_name (str)

webapp.sticky_notes_api.list_orphan_repos()

קומה שנייה: ריפואים שיש להם פתקים ואינם ממוררים עוד.

בלי הקומה הזו פתקים של ריפו שהוסר לא מופיעים בשום תצוגה — לא בעץ שלו, כי אין עץ, ולא ברשימת היתומים, כי היא פר-ריפו. זה בדיוק ”המצב שנעלם בשקט“.

webapp.sticky_notes_api.toggle_note_task(note_id)

מסמן או מבטל צ’קבוקס בתוך פתק.

הראוט הזה קיים כדי שאפשר יהיה לאמת את הכתיבה. האלטרנטיבה — לשלוח את התוכן המלא ב-PUT /note/<id> — הופכת כל קליק לדריסת last-writer-wins של עריכות מקבילות, ובעיקר הופכת אימות לבלתי אפשרי: אפשר לאמת רק שכתבנו את מה ששלחנו. הבקשה כאן נושאת כוונה (מספר סידורי + מצב רצוי), וזה הדבר היחיד שניתן לאמת מול המסד.

הסדר, וכל שלב בו מגן על משהו:

  1. הפתק קיים ושייך למשתמש — אחרת 404.

  2. prev_updated_at — אחרת 409, בדיוק כמו ב-update_note.

  3. סידורי שאינו קיים ⇒ 409, לא 200. התצוגה של הלקוח מיושנת.

  4. כבר במצב המבוקש ⇒ 200 בלי כתיבה. אידמפוטנטי.

  5. Compare-and-swap: הפילטר כולל את התוכן הקודם, כך שכותב מקביל אינו נדרס.

  6. קריאה חוזרת מהמסד ובדיקה שהתו אכן השתנה. לא modified_count, לא ok: true — אלה מדווחים על הקריאה, לא על המצב.

בכל מסלול התשובה נושאת את התוכן הסמכותי, כדי שהלקוח יסתנכרן בלי סיבוב נוסף — וגם במסלול הכשל, שם זה מה שמאפשר לו להחזיר את התצוגה למה שבאמת שמור.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.list_note_threads(note_id)

תקצירי השרשורים של פתק, בלי התגובות — לרענון הבועות.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.get_note_thread(note_id, thread_id)

שרשור אחד עם כל התגובות שלו — מה שהחלונית מציגה.

שרשור אחד בכל פעם, ולא כל שרשורי הפתק: שרשור יכול להגיע ל- nt.MAX_THREAD_BODY_BYTES, ומספר השרשורים על פתק אינו מוגבל. התקצירים של כולם (בלי תגובות) חוזרים יחד איתו, בשביל המספור והבועות.

פרמטרים:
  • note_id (str)

  • thread_id (str)

webapp.sticky_notes_api.create_note_thread(note_id)

שרשור חדש על פתק, עם התגובה הראשונה שלו. גוף: {"body": "..."}.

השרשור נוצר רק עם תגובה — ”השרשור נשמר עם שליחת התגובה הראשונה“ (העיצוב). 201.

פרמטרים:

note_id (str)

webapp.sticky_notes_api.reply_note_thread(note_id, thread_id)

תשובה בשרשור. גוף: {"body": "...", "reopen": true|false}.

reopen (ברירת מחדל true) — תשובה על שרשור שנפתר פותחת אותו באותה כתיבה; false עונה ומשאיר אותו נפתר (”שליחה בלי פתיחה“, לפי ההחלטה שבפתק על האפיון). reopen שאינו בוליאני ← 400 invalid_reopen: אחרת "false" כמחרוזת היה נקרא כאמת ופותח שרשור.

פרמטרים:
  • note_id (str)

  • thread_id (str)

webapp.sticky_notes_api.resolve_note_thread(note_id, thread_id)

סגירת שרשור. גוף: {}, או {"body": "..."} — משפט סיכום שנשמר כתגובה אחרונה באותה כתיבה (כפתור ”✓ נפתר“ כשיש טקסט בתיבה, כמו resolve עם body ב-MCP).

פרמטרים:
  • note_id (str)

  • thread_id (str)

webapp.sticky_notes_api.reopen_note_thread(note_id, thread_id)

פתיחה מחדש של שרשור שנפתר, בלי תגובה — הכפתור ”פתיחה מחדש“.

פרמטרים:
  • note_id (str)

  • thread_id (str)

webapp.sticky_notes_api.NOTE_SEARCH_DEFAULT_LIMIT = 30

כמה תוצאות מוחזרות כשלא נתבקש אחרת, וכמה הכי הרבה אפשר לבקש.

התקרה אינה קוסמטית. limit מגיע מה-URL, כלומר מחוץ לתהליך, ובלי חסם עליון בקשה אחת יכולה לגרור את כל מכסת המשתמש (MAX_NOTES_PER_USER) לתוך המיון ולתוך התשובה. חמישים תוצאות הן יותר ממה שמישהו סורק בעין; מי שצריך יותר מצמצם את החיפוש.

webapp.sticky_notes_api.NOTE_SEARCH_MAX_NEEDLE = 200

אורך מרבי למחט החיפוש עצמה.

קבוע נפרד מ-NOTE_SEARCH_PREVIEW_CHARS אף ששניהם 200 היום: זה חוסם קלט שנכנס לרג’קס, וזה קובע כמה מהגוף מוצג. מספר משותף לשני דברים שאינם אותו דבר הוא מספר שמישהו ישנה בשביל האחד וישבור את השני.

webapp.sticky_notes_api.build_note_search_pipeline(user_id, needle, *, color_id, limit, include_archived=False)[מקור]

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

סדר השלבים אינו קוסמטי, ושלושה מהם קיימים בגלל תקלות שכבר קרו בריפו הזה:

  1. $match — הפילטר המשותף עם ה-MCP (note_search_filter()). אותה פונקציה ולא העתק: שני חיפושי פתקים שמתאימים אחרת הם שני מוצרים שמתחזים לאחד. גם הסתרת הארכיון (include_archived) קורית שם.

  2. $addFields — הדירוג והתצוגה המקדימה, שניהם לפני שהגוף יורד, כי שניהם נגזרים ממנו.

  3. $project בהכללה (_SEARCH_HIT_PROJECTION) — רק מה שהתשובה צריכה ממשיך ל-$sort. בסדר ההפוך — מיון ואז היטלה — מונגו החזירה בפרודקשן שגיאה 292 (QueryExceededMemoryLimitNoDiskUseAllowed) והקוד נפל למסלול איטי; allowDiskUse אינו מציל כי Atlas מתעלם ממנו ב-Flex. מתועד ב-tests/test_files_pipelines_drop_heavy_fields_early.py.

    ולמה הכללה ולא ``{”content“: 0}``, שהיה כאן עד אוקטובר 2026. החרגה שבאה אחרי $addFields לא הורידה את הגוף מהמיון: explain מול מונגו 8 הראה totalDataSizeSortedBytesEstimate של 1,792,484 בייטים על 200 פתקים ארוכים (תקרה 50), ו-57,260 עם הכללה — אותה תוצאה. זה amir-bug-patterns, BY-STACK/mongodb.md דפוס 5, שנותן את הפונקציה הזו כדוגמה. נעול ב-tests/test_note_archive_mongo.py.

  4. $sort — כותרת לפני גוף, ובתוך כל קבוצה לפי עדכון אחרון. ‏``false < true`` בסדר ה-BSON, ולכן -1 מעלה את פגיעות הכותרת.

  5. $limit עם שורת סנטינל (limit + 1), כמו ב-MCP: שורה נוספת שחזרה היא ראיה שיש עוד, ולא ניחוש מתוך ספירה ששווה לתקרה.

  6. $unset — שדה העזר של הדירוג אינו חלק מהתשובה.

‏``$substrCP`` ו-``$strLenCP``, ולעולם לא הגרסאות ב-Bytes. אות עברית היא שני בייטים, וחיתוך בבייטים על מספר שנספר בתווים נוחת באמצע תו ומפיל את השאילתה (Location28657). זה amir-bug-patterns H6, והאירוע עצמו קרה כאן.

הדירוג פשוט בכוונה. אין כאן משקלות מכוילים: _calculate_relevance_score שהתיעוד מזכיר אינה קיימת בקוד כלל, וניקוד שאיש אינו יכול להסביר הוא ניקוד שאיש לא יתחזק. פתק הוא נושא שלם, ולכן השאלה היא איזה פתק — ומופע בשם הוא עדות חזקה יותר ממופע בגוף.

Return type:

List[Dict[str, Any]]

פרמטרים:
  • user_id (int)

  • needle (str)

  • color_id (str | None)

  • limit (int)

  • include_archived (bool)

webapp.sticky_notes_api.search_notes()

חיפוש בפתקים של המשתמש — בשם ובגוף, חוצה את שלושת היעדים.

אותה התאמה כמו ב-MCP. שניהם עוברים דרך note_search_filter(), ולכן חיפוש של אותה מילה בעמוד ובסוכן מחזיר את אותה קבוצת פתקים. מה שנבדל הוא רק מה שכל צרכן מציג: ה-MCP מחזיר הפניות בלבד, והעמוד מוסיף תצוגה מקדימה.

הרשאות: הפתקים של המשתמש, כל שלושת הסוגים — בדיוק כמו codekeeper_search_notes, שאינו מגודר לאדמין (הגידור שם חל על list_repo_notes/create_repo_note בלבד). גם /api/sticky-notes/repo/… בוובאפ נושא @require_auth בלבד, כלומר גייט אדמין כאן היה מסתיר מהמשתמש פתקים שהוא כבר מושך בקריאה אחרת — גייט שאינו מגן על דבר.

פתקי הארכיון — רק כשביקשו. include_archived=1 מחזיר אותם, וזו התיבה ”כלול ארכיון“ בעמוד; בלעדיו הם מוסתרים בפילטר המשותף, כמו ב- codekeeper_search_notes בלי הפרמטר באותו שם. התשובה מחזירה את include_archived שהוחל, כמו color_id.