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.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:
- 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.
- webapp.sticky_notes_api.list_notes(file_id)
List all sticky notes for current user and file.
- פרמטרים:
file_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
resultswith per-item status, e.g. 200/409.
- webapp.sticky_notes_api.archive_note(note_id)
מעביר פתק לארכיון — מכל יעד, ובלי דרך חזרה ליעד הקודם.
גוף אופציונלי:
{"title": "..."}— השם שהמשתמש אישר בחלון. בלעדיו נשאר השם הקיים, ופתק בלי שם אינו עובר (resolve_archive_title): הארכיון מנווט לפי שם.הסדר, וכל שלב בו מגן על משהו:
הפתק קיים ושייך למשתמש — אחרת
404 note_not_found.כבר בארכיון ←
200עםalready_archived, בלי כתיבה. לחיצה כפולה, או מכשיר שני שעוד מציג את הפתק על הלוח, אינם שגיאה.השם, ואחריו תקרת הארכיון (
MAX_ARCHIVED_NOTES_PER_USER, אדמין פטור). ספירה שנכשלה נדחית (check_note_quota), כמו בכל תקרה אחרת.כתיבה אחת מותנית (CAS):
find_one_and_updateשהפילטר שלו דורש שהפתק עדיין אינו בארכיון (active_notes_filter). שתי העברות מקבילות — רק אחת כותבת.Noneמהמסד אינו הצלחה (K11): קוראים שוב ומסווגים — נמחק בינתיים, או הועבר בבקשה המקבילה.השרשורים הפתוחים נסגרים רק אחרי שההעברה נכתבה (
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“.הסדר, וכל שלב בו מגן על משהו:
הפתק קיים ושייך למשתמש — אחרת
404 note_not_found. פתק בארכיון —409 note_archived; פתק שאינו פתק לוח —400 not_a_board_note.כבר נעוץ ←
200עםalready_pinned, בלי כתיבה. לחיצה כפולה, או מכשיר שני שעוד מציג את הפתק כלא-נעוץ, אינם שגיאה.התקרה —
MAX_FILES_PAGE_PINNED_NOTES, או פחות לפי המכשיר. תקרה של צורת-תוכן, ולכןis_admin=Falseתמיד; ספירה שנכשלה נדחית (note_quota_unknown), ולא נחשבת אפס. מלא ←409 files_page_pins_full, והפתק הישן אינו יורד אוטומטית.כתיבה אחת מותנית (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.list_repo_notes(repo_name, repo_path)
פתקים על קובץ בריפו ממורר.
סימון היתומים נעשה בקריאה, ולא בכתיבה. אין סריקה תקופתית ואין
update_manyעל מסלול קריאה — זה הלקח מסריקת היתומים של הלוחות. הפתק ממשיך להיות מוחזר עם הנתיב האחרון הידוע, ורק נושא דגל.
- webapp.sticky_notes_api.create_repo_note(repo_name, repo_path)
פתק חדש על קובץ בריפו ממורר.
- 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 של עריכות מקבילות, ובעיקר הופכת אימות לבלתי אפשרי: אפשר לאמת רק שכתבנו את מה ששלחנו. הבקשה כאן נושאת כוונה (מספר סידורי + מצב רצוי), וזה הדבר היחיד שניתן לאמת מול המסד.הסדר, וכל שלב בו מגן על משהו:
הפתק קיים ושייך למשתמש — אחרת 404.
prev_updated_at— אחרת 409, בדיוק כמו ב-update_note.סידורי שאינו קיים ⇒ 409, לא 200. התצוגה של הלקוח מיושנת.
כבר במצב המבוקש ⇒ 200 בלי כתיבה. אידמפוטנטי.
Compare-and-swap: הפילטר כולל את התוכן הקודם, כך שכותב מקביל אינו נדרס.
קריאה חוזרת מהמסד ובדיקה שהתו אכן השתנה. לא
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, ומספר השרשורים על פתק אינו מוגבל. התקצירים של כולם (בלי תגובות) חוזרים יחד איתו, בשביל המספור והבועות.
- 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שאינו בוליאני ← 400invalid_reopen: אחרת"false"כמחרוזת היה נקרא כאמת ופותח שרשור.
- webapp.sticky_notes_api.resolve_note_thread(note_id, thread_id)
סגירת שרשור. גוף:
{}, או{"body": "..."}— משפט סיכום שנשמר כתגובה אחרונה באותה כתיבה (כפתור ”✓ נפתר“ כשיש טקסט בתיבה, כמוresolveעםbodyב-MCP).
- webapp.sticky_notes_api.reopen_note_thread(note_id, thread_id)
פתיחה מחדש של שרשור שנפתר, בלי תגובה — הכפתור ”פתיחה מחדש“.
- 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)[מקור]
הצינור שמחפש פתקים — בנוי כאן, ונבדק כפי שנשלח.
סדר השלבים אינו קוסמטי, ושלושה מהם קיימים בגלל תקלות שכבר קרו בריפו הזה:
$match— הפילטר המשותף עם ה-MCP (note_search_filter()). אותה פונקציה ולא העתק: שני חיפושי פתקים שמתאימים אחרת הם שני מוצרים שמתחזים לאחד. גם הסתרת הארכיון (include_archived) קורית שם.$addFields— הדירוג והתצוגה המקדימה, שניהם לפני שהגוף יורד, כי שניהם נגזרים ממנו.$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.$sort— כותרת לפני גוף, ובתוך כל קבוצה לפי עדכון אחרון. ``false < true`` בסדר ה-BSON, ולכן-1מעלה את פגיעות הכותרת.$limitעם שורת סנטינל (limit + 1), כמו ב-MCP: שורה נוספת שחזרה היא ראיה שיש עוד, ולא ניחוש מתוך ספירה ששווה לתקרה.$unset— שדה העזר של הדירוג אינו חלק מהתשובה.
``$substrCP`` ו-``$strLenCP``, ולעולם לא הגרסאות ב-Bytes. אות עברית היא שני בייטים, וחיתוך בבייטים על מספר שנספר בתווים נוחת באמצע תו ומפיל את השאילתה (
Location28657). זהamir-bug-patternsH6, והאירוע עצמו קרה כאן.הדירוג פשוט בכוונה. אין כאן משקלות מכוילים:
_calculate_relevance_scoreשהתיעוד מזכיר אינה קיימת בקוד כלל, וניקוד שאיש אינו יכול להסביר הוא ניקוד שאיש לא יתחזק. פתק הוא נושא שלם, ולכן השאלה היא איזה פתק — ומופע בשם הוא עדות חזקה יותר ממופע בגוף.
- 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.