docs: describe unified capture inbox flow

2026-06-05 07:51:08 +08:00 · 2026-06-05 07:51:08 +08:00 · db47d31183
parent 4755d3199d
commit db47d31183
4 changed files with 127 additions and 19 deletions
--- a/docs/01_Product_Spec.md
+++ b/docs/01_Product_Spec.md
@ -68,6 +68,12 @@ Markdown-файл внутри vault. Резервная копия при пе

 Любой файл, привязанный к делу. Открывается системным приложением.

+### Ссылка
+
+Отдельный артефакт дела, а не заметка. Хранит URL, название,
+hostname, заметку и дату добавления. Открывается во внешнем браузере
+и показывается во вкладке "Ссылки" конкретного дела.
+
 ### Действие

 Кнопка запуска: URL, файл, папка, команда. Опасные — с подтверждением.
@ -81,6 +87,21 @@ Markdown-файл внутри vault. Резервная копия при пе
 Следы работы: открыт файл, изменена заметка, запущено действие.
 Используется для восстановления времени.

+### Неразобранное
+
+Единый входящий поток. Любой внешний материал — файл, папка,
+изображение, URL или текст из drag-and-drop, Ctrl+V или кнопки
+"Вставить из буфера" — сначала создаётся как unresolved artifact.
+Верстак хранит контекст захвата по `node_id` или системному разделу,
+показывает материал в глобальном "Неразобранном" и, если захват был
+внутри дела, в локальной вкладке "Неразобранное" этого дела.
+
+При разборе artifact маршрутизируется по типу:
+
+- файл / папка / изображение → "Файлы" выбранного дела;
+- текст → "Заметки" выбранного дела;
+- URL → "Ссылки" выбранного дела.
+
 ## 5. Примеры дерева (универсальные)

 ```text
--- a/docs/03_Data_Model_Storage.md
+++ b/docs/03_Data_Model_Storage.md
@ -11,6 +11,7 @@
    config.yml
    device_token.json
    blobs/
+    inbox/
    plugins/
    trash/
    history/
@ -107,6 +108,26 @@ CREATE TABLE notes (
 );
 ```

+### links
+
+Resolved URL artifacts. Unresolved captured URLs live as inbox artifacts
+with capture metadata until the user assigns them to a target node.
+
+```sql
+CREATE TABLE links (
+    id TEXT PRIMARY KEY,
+    node_id TEXT NOT NULL REFERENCES nodes(id),
+    title TEXT NOT NULL,
+    url TEXT NOT NULL,
+    hostname TEXT NOT NULL DEFAULT '',
+    note TEXT NOT NULL DEFAULT '',
+    source TEXT NOT NULL DEFAULT '',
+    captured_at TEXT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+```
+
 ### actions

 ```sql
@ -215,6 +236,31 @@ CREATE TABLE sync_state (

 ## 3. Правила хранения

+### Capture / Inbox
+
+Внешний захват материала не создаёт сразу обычную заметку, файл или
+ссылку внутри дела. Сначала создаётся root-level inbox artifact с
+metadata в `node_meta`:
+
+```text
+capture.inbox = true
+capture.status = unresolved | resolved
+capture.context_type = node | section | global
+capture.context_node_id = <node_id>
+capture.context_section = today | journal | settings | inbox | root | ...
+capture.suggested_target_node_id = <node_id>
+capture.source_kind = file | folder | url | text | image
+capture.source = drop | paste | clipboard_button
+capture.created_at = RFC3339
+```
+
+Контекст дела хранится только по `node_id`, не по названию.
+
+Файлы, папки и изображения до разбора лежат в `.verstak/inbox/...`.
+После "Оставить здесь" или "Разложить" они физически перемещаются в
+нормальную vault-иерархию выбранного дела через существующую логику
+`MoveNode`.
+
 ### Заметки

 - physical `.md` file;
@ -227,6 +273,13 @@ CREATE TABLE sync_state (
 - open with system app;
 - metadata in SQLite.

+### Ссылки
+
+- unresolved URL хранится как inbox artifact типа `link` с URL metadata;
+- после разбора создаётся запись в `links`;
+- вкладка "Ссылки" показывает только resolved links текущего node;
+- URL открывается системным браузером.
+
 ### Secret notes

 - encrypted file, e.g. `access.secret.md.enc`;
--- a/docs/05_UI_UX.md
+++ b/docs/05_UI_UX.md
@ -82,7 +82,7 @@
 2026-05-12 — чистка кеша и проверка формы — 40м

 Вкладки:
-Обзор | Заметки | Файлы | Документы | Скрипты | Действия | Журнал | Активность
+Обзор | Заметки | Файлы | Неразобранное | Ссылки | Действия | Журнал | Активность
 ```

 ## 5. Заметки
@ -100,7 +100,8 @@
 Actions:

 - add file;
- drag & drop;
+- drag & drop в приложении создаёт unresolved artifact в Неразобранном;
+- явные кнопки добавления файла/папки импортируют в выбранный раздел файлов;
 - copy into vault;
 - link external;
 - open with system app;
@ -199,23 +200,50 @@ Search results:

 ## 11. Неразобранное

+Неразобранное — единый входящий лоток для внешнего материала.
+Пользователь может кинуть или вставить материал в любое место
+приложения; Верстак сначала сохраняет его как unresolved artifact,
+а не добавляет напрямую в дело.
+
 Туда попадают:

- будущие импортированные DokuWiki pages без уверенного назначения;
- будущие файлы без дела из scan work;
- будущие конфликты sync;
- activity suggestions без уверенного дела.
+- файлы и папки из drag-and-drop;
+- изображения из paste/drop, если webview отдаёт данные;
+- URL из браузера (`text/uri-list`, `text/x-moz-url`, `text/plain`);
+- обычный текст из Ctrl+V;
+- текст/URL из кнопки "Вставить из буфера" через backend clipboard bridge;
+- будущие импортированные материалы без уверенного назначения;
+- будущие конфликты sync.
+
+Глобальное "Неразобранное" показывает все unresolved artifacts.
+Локальная вкладка "Неразобранное" внутри дела показывает artifacts,
+захваченные в контексте этого `node_id` или предложенные для него.

 Actions:

- создать дело;
- привязать к делу;
- переместить;
- архивировать;
- игнорировать;
- удалить в trash.
+- "Оставить здесь" — если есть suggested target;
+- "Разложить" / "Переместить..." — выбрать target node;
+- удалить artifact и staged данные.

-## 12. TUI UX
+Маршрутизация при разборе:
+
+- файл / папка / изображение → вкладка "Файлы" target node;
+- текст → вкладка "Заметки" target node;
+- URL → вкладка "Ссылки" target node.
+
+## 12. Ссылки
+
+Вкладка "Ссылки" внутри дела показывает только resolved URL artifacts
+этого node. Ссылки не смешиваются с файлами, заметками и действиями.
+
+Минимальные действия:
+
+- открыть во внешнем браузере;
+- скопировать URL;
+- редактировать название, URL и заметку;
+- удалить ссылку.
+
+## 13. TUI UX

 TUI нужен для быстрого:

@ -232,7 +260,7 @@ TUI нужен для быстрого:
 - preview документов;
 - настройки sync.

-## 13. CLI UX
+## 14. CLI UX

 CLI команды:

--- a/docs/06_Roadmap.md
+++ b/docs/06_Roadmap.md
@ -135,14 +135,20 @@ Acceptance:

 ## Milestone 9 — Work folder intake

- scan folder;
- show unassigned folders/files;
- create case from folder;
- copy/move/link into vault.
+- unified Capture / Inbox pipeline for external drop, paste and clipboard button;
+- stage captured files/folders/images under `.verstak/inbox`;
+- store capture context by `node_id` or system section;
+- global Inbox view for all unresolved artifacts;
+- local Inbox tab inside a node;
+- resolve artifacts into Files / Notes / Links;
+- dedicated Links tab for resolved URL artifacts;
+- scanner for a whole work folder remains future work.

 Acceptance:

- можно постепенно разобрать папку `work`.
+- можно кинуть или вставить файл, папку, картинку, URL или текст в приложение;
+- материал не теряется и сначала виден в "Неразобранном";
+- после разбора он физически или логически оказывается в выбранном деле.

 ## Milestone 10 — Sync server/client MVP