f7cloud_mobile/docs/app-map/notes.md

Карта: Заметки

Приложение «Заметки» (/apps/notes/) на forbion.f7cloud.ru. Структура кнопок/меню снята из кода (метод mail/078): апстрим nextcloud/notes v5.0.0 (src/**/*.vue — точная версия с forbion, канон README) + мобильная тема forbion (design-reference/forbion-theme/css/pages/pages-mobile/_mobile-notes.css, css/pages/app-notes/). Живой мобильный web (Browser 1, cloude, mail/079) — только для визуальной сверки «как выглядит/порядок»; строго read-only (mail/073): ничего не создаётся/не меняется/не удаляется. Приватность: реальные заголовки/тексты заметок не фиксируются — только структура UI и дерево переходов.

Статус визуальной сверки на живом forbion (Browser 1 c9284989, cloude, mail/079, техника same-origin iframe 390px): выполнена частично, 2026-07-12. Мобильная вёрстка подтверждена (header__mobile, header__mobile-bottom). Подтверждено на живом сервере: пустое состояние Welcome (тексты 1:1 с кодом), кнопка «Новая заметка», поле поиска, «Создайте образец заметки с помощью Markdown», навигация «Все заметки» (со счётчиком) / капшен «Категории» / «Новая категория», «Меню настроек» (модалка открывается, секция «Мобильные приложения» — Android / iPhone and iPad). НЕ наблюдаемо read-only: список строк-заметок, меню заметки (⋮), редактор (rich/plain/preview), диалог конфликта, детальные секции настроек «Общее» — у cloude заметок НЕТ, а создание/открытие = запись (запрещено mail/073). Эти узлы остаются из кода (v5.0.0) — помечены код-only ниже. NB: при первом входе поверх приложения всплывает глобальный онбординг-попап «Добро пожаловать в F7cloud!» (не notes-специфичный, не закрывал — dismiss может писать флаг на сервер).

Компоненты-источники (nextcloud/notes v5.0.0)

App.vue (шелл: навигация категорий + настройки) · NotesView.vue (список + поиск + «Новая заметка») · NotesList.vue/NoteItem.vue (строка заметки + меню действий) · CategoriesList.vue (навигация: Все заметки / Категории) · Note.vue→NoteRich.vue (rich-редактор @nextcloud/text) / NotePlain.vue (простой/preview) · AppSettings.vue (модалка настроек) · Welcome.vue (пустое состояние) · ConflictSolution.vue (конфликт версий) · NoteShareSidebar.vue (шаринг).

Вход

Шторка приложений (по «трём полоскам») → «Заметки», или прямой URL /apps/notes/. Оболочку (нижняя панель, шторка, бургер) описывает shell.md (зона лида) — здесь только специфика приложения. На мобильном (узкий вьюпорт) сначала показывается список заметок; выбор заметки открывает редактор поверх (NcAppContent show-details), возврат — «назад».

Экран: Список заметок (главный)

Шапка списка (content-list__search) — ✔ кнопка и поле подтверждены на forbion:

• Кнопка «Новая заметка» (primary, иконка +) → создаёт заметку и открывает редактор (write — на forbion НЕ нажимаю).
• Поле «Искать заметки» (Search for notes) → фильтрация списка по заголовку по мере ввода; крестик (trailing) очищает поиск.

Тело: список строк-заметок, сгруппированный. Группировка (NotesView groupedNotes):

• если выбраны «Все заметки» и настроен режим — по временным слотам (заголовки-капшены через NotesCaption: сегодня/недавние/… — таймслоты) и/или по категориям;
• избранные сортируются выше (favorite → вверх), затем по дате изменения.

Строка заметки (NoteItem = NcListItem):

• Тап по строке → открыть заметку в редакторе.
• Индикатор «расшарена» (значок ShareVariant, если у заметки есть шаринг).
• Кнопка «действия» (⋮, меню строки) → см. «Меню заметки».

Пустое состояние (нет заметок / Welcome.vue) — ✔ подтверждено на forbion (cloude, route /apps/notes/welcome): заголовок «Заметки» + «Начните писать заметку, нажав «Новая заметка».» + кнопка «Новая заметка»; подсказки: «Записывайте свои мысли, ни на что не отвлекаясь.», «Поддержка языка разметки Markdown для оформления текста;», кнопка «Создайте образец заметки с помощью Markdown» (CreateSampleButton — write, не нажимаю), «Поддержка категорий;».

Состояние загрузки: «Загрузка …» (Loading …). Пустой поиск в категории: кнопка «Найти во всех категориях» (сбрасывает выбранную категорию).

Меню заметки (⋮ в строке — NoteItem #actions) — код-only

(У cloude заметок нет → строку и её меню на forbion read-only не наблюдал; из кода v5.0.0.) Порядок пунктов:

• «Добавить в избранное» / «Удалить из избранного» (тумблер, звезда) → PUT /favorite.
• «Поделиться» (Share) → открывает сайдбар шаринга (NoteShareSidebar, стандартный NC-шэринг). (состав панели — общий NC sharing; детально не раскрывал — визуал(?))
• «<Категория>» / «Изменить категорию» → инлайн-выбор категории (мультиселект с возможностью ввести новую, taggable) → PUT /category.
• «Переименовать» → инлайн-поле ввода нового заголовка → PUT /title.
• —— разделитель ——
• «Удалить заметку» (если не read-only) → удаление (DELETE) с возможностью отмены (POST /notes/undo). (write — не выполняю на forbion.)

Экран: Редактор заметки — код-only

(Открытие/создание заметки = запись → на forbion read-only не наблюдал; из кода v5.0.0.) Открывается тапом по заметке или «Новая заметка». Режим определяется настройкой Display (rich / plain / preview, см. Настройки).

Заголовок: формируется автоматически из первой строки (autotitle, PUT /autotitle); пустая заметка → «Новая заметка».

Rich-режим (NoteRich → редактор @nextcloud/text):

• Панель форматирования (.text-menubar — в теме _mobile-notes.css она переносится на мобильном: flex-wrap: wrap). Инструменты (из списка горячих клавиш AppSettings): жирный, курсив, цитата, моноширинный, очистить стиль, список, нумерованный список, заголовок / крупный заголовок, вставить ссылку. (точный набор иконок на узком экране — визуал(?))
• Тело — редактируемый markdown-контент; автосохранение (debounce) → PUT /notes/{id} с заголовком If-Match: "<etag>".

Plain-режим (NotePlain) — меню действий редактора (NcActions):

• «Просмотр» / «Правка» (тумблер preview⇄edit, подсказка «CTRL + /»).
• «Полный экран» / «Выйти из полноэкранного режима» (тумблер).
• Плейсхолдер пустого тела: «Write …» (или «Empty note» в preview).

Read-only заметка: пункт-индикатор «Заметка только для чтения. Вы не можете её изменить.» (PencilOffOutline), редактирование заблокировано.

Ошибка сохранения: пункт «Сохранение не удалось. Нажмите, чтобы повторить.» (onManualSave) — ручной повтор PUT.

Диалог: Конфликт версий (ConflictSolution) — код-only

Возникает, если заметка изменена в другой сессии (сервер вернул конфликт на If-Match):

• Текст: «Заметка была изменена в другой сессии. Выберите, какую версию сохранить.»
• Кнопка «Использовать версию с сервера».
• Кнопка «Использовать текущую версию».

Прямое подтверждение моего плана (mail/071 п.2): конфликт разрешается ЯВНЫМ выбором, а не молчаливой перезаписью. Нативный NoteEditorScreen обязан воспроизвести этот диалог.

Навигация: Категории (левая шторка — App.vue + CategoriesList)

На мобильном — за «бургером»/шторкой навигации приложения (не нижняя панель оболочки). ✔ На forbion подтверждены: «Все заметки» (со счётчиком 0), капшен «Категории», «Новая категория», кнопка «Меню настроек». Список конкретных категорий пуст (у cloude нет заметок).

• «Новая категория» (NcAppNavigationNew, иконка папка+) → создание категории (drag-n-drop заметки на неё тоже вешает категорию). (write — не выполняю.)
• «Все заметки» + счётчик (bubble) → сброс фильтра категории, весь список.
• Капшен «Категории», далее список категорий:
  • «Без категории» (uncategorized) + счётчик.
  • Каждая категория: название (иконка папки, в теме заменена на серую folder-gray.svg) + счётчик; действия: «Переименовать категорию» (инлайн-правка), «Удалить категорию» → подтверждение (диалог «Удалить категорию» / «Удалить» / «Отмена»). (write — не выполняю.)
• Подкатегории: имя вида parent/child разворачивается вложенно.
• Внизу навигации: «Настройки заметок» (шестерёнка) → модалка настроек.

Модалка: Настройки заметок (AppSettings)

На мобильном тема раскрывает её на весь экран (_mobile-notes.css: modal-container height 100%, скрыт заголовок modal-header). ✔ На forbion открыл модалку read-only и подтвердил секцию «Мобильные приложения» (подписи «Android», «iPhone and iPad» = HelpMobile.vue). Секции «Общее»/«Комбинации клавиш» детально не раскрывал (код-only, из v5.0.0). Секции:

• Общее (General):
  • «Отображение» (Display): «Форматированный текст» (rich) / «Простой текст» (plain) / «Просмотр» (preview).
  • «Расширение файла» (для новых заметок): «.md» / «.txt» / «Свой» (+ поле «Своё расширение файла»).
  • «Файлы» → «Папка заметок» (NcFormBoxButton) → выбор папки хранения заметок (WebDAV picker). (write-настройка — не меняю.)
• Мобильные приложения (Mobile apps) — ссылки/подсказки на приложения (в теме секция клавиш-шорткатов и это скрыты частично — визуал(?)).
• Комбинации клавиш (Shortcuts) — справочный список (см. панель форматирования выше). В теме forbion секция keyboard-shortcuts скрыта (display:none) — на forbion её, вероятно, не видно. визуал(?)

API-контур (для нативного модуля — подтверждает mail/071)

Базовый путь apps/notes/api/v1 (в вебе — apps/notes/...):

• GET /notes?pruneBefore=<ts> — список (инкрементальный синк по времени; в нашем клиенте — exclude=content для лёгкого списка + ETag-коллекция).
• GET /notes/{id} — заметка; POST /notes — создать; PUT /notes/{id} (тело content, заголовок If-Match: "<etag>") — сохранить; DELETE /notes/{id}; POST /notes/undo.
• PUT /notes/{id}/favorite, /category, /title, /autotitle; PATCH /notes/category (переименовать), DELETE /notes/category (удалить категорию).
• Поля модели: id, title, category, content, favorite, modified, etag, readonly.

Расхождения с нативным клиентом

Модуль feature/notes ещё не создан (скелет заводит лид по mail/071) — поэтому полный список расхождений = весь функционал выше как первичный бэклог. Ключевые пункты к паритету при реализации плана 1→2→3 (mail/071):

• Список: поиск по заголовку, группировка (таймслоты + категории), сортировка «избранное вверх», индикатор шаринга, пустое/загрузочное состояния.
• Меню заметки: избранное, категория (с созданием новой), переименование, удаление с undo, шаринг.
• Редактор: rich (панель форматирования) ↔ plain ↔ preview, полноэкранный режим, автосейв с If-Match, автозаголовок, read-only состояние.
• Диалог конфликта версий (обязателен — не молчаливая перезапись).
• Категории: навигация «Все/Без категории/по категориям» со счётчиками, CRUD категорий, вложенность parent/child.
• Настройки: режим отображения, расширение файла, папка заметок.