From 8df4d22cfb6eda4de89ccfb8e0d3c300130a4f05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sat, 5 Sep 2026 12:58:47 +0300
Subject: [PATCH] Update picker documentation

---
 README.md        | 44 +++++++++++++++++++++++---------------------
 upload/README.md | 27 +++++++++++++++++++++------
 2 files changed, 44 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 8889c99..4434561 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,17 @@
 # Upload Platform
 
-Переиспользуемый сервис загрузки файлов через ВМ-буфер. Выносит два слоя —
-**выбор файлов** (фронт) и **закачку через ВМ** (фронт + бэк) — в отдельный
-проект, который копируется в любой другой проект.
-
-Паттерн: браузер → `PUT` на ВМ-буфер → Flask `POST /api/upload_refs` (egress pull) → сессия.
+Переиспользуемый browser-only file-picker. Модуль выбирает отдельные файлы,
+папки и ZIP, строит сворачиваемое дерево и возвращает исходные browser `File`
+objects с полными путями. Файлы не отправляются на VM и не загружаются через
+backend.
 
 ## Слои
 
 | Слой | Ответственность |
 |---|---|
-| 0. Конфиг | `vmUploadUrl`, `allowedExt`, лимиты, ретраи |
-| 1. Выбор файлов | таблица, дедуп, раскрытие ZIP, рекурсивный обход папки |
-| 2. Закачка через ВМ | PUT на ВМ → pull в сессию |
-| 3. Логика приложения | здесь — стаб-заглушка (в каждом проекте своя) |
+| Конфиг | `allowedExt` |
+| Picker | таблица, дедупликация, ZIP, рекурсивный обход папки |
+| Интегрирующее приложение | получает leaf-файлы через `getFiles()` |
 
 ## Структура
 
@@ -24,13 +22,10 @@ upload-platform/
 ├── upload/                   # ← переиспользуемый модуль (копируется в любой проект)
 │   ├── README.md             # инструкция интеграции
 │   ├── config.example.json
-│   ├── frontend/             # слои 1+2 (vanilla JS, ES-модули)
+│   ├── frontend/             # picker (vanilla JS, ES-модули)
 │   │   ├── zip/
 │   │   ├── table/
-│   │   └── upload/
-│   └── backend/              # слой 2 (Python)
-│       ├── upload_refs/
-│       └── session/
+│   └── backend/              # LEGACY: VM upload/session remnants
 └── site/                     # демо-обёртка (не переиспользуется)
     ├── app.py
     ├── routes/
@@ -53,15 +48,22 @@ python site/app.py
 - Маршрут `/health` → `200` (иначе liveness-проба платформы убивает под).
 - Без `site/__init__.py` и factory pattern.
 
-## Как интегрировать слои в другой проект
+## Как интегрировать picker в другой проект
 
 1. Скопировать папку `upload/` в свой проект.
-2. Задать свой конфиг (по образцу `upload/config.example.json`).
-3. Фронт: подключить ES-модули из `upload/frontend/` через `<script type="module">`,
-   вызвать `initUploadTable(cfg)` и `uploadViaVM(...)`.
-4. Бэк: зарегистрировать `create_upload_refs_blueprint(cfg)`, импортировать `upload.backend.session`.
-5. Слой 3 (обработка файлов) — свой; сюда приходит список файлов сессии после закачки.
+2. Задать конфиг по образцу `upload/config.example.json`.
+3. Подключить локальный `fflate` до picker-модуля.
+4. Вызвать `initUploadTable({ ...cfg, fileInputEl, folderInputEl, tableBodyEl, countEl })`.
+5. Получить выбранные leaf-файлы через `table.getFiles()`; каждый элемент содержит
+    `path`, `name`, `size` и исходный `file`.
 
-Подробнее — `PLAN.md`.
+Разрешённые расширения по умолчанию: `.pdf`, `.doc`, `.docx`, `.txt`, `.md`.
+ZIP-файлы используются как контейнеры и раскрываются в браузере; сам ZIP не
+возвращается как leaf-файл. Ограничения размера и количества файлов не заданы.
 
+## Legacy
+
+`upload/backend/` и старые VM-upload упоминания сохранены только для истории и
+совместимости с предыдущими этапами проекта. Текущая picker-only интеграция их
+не импортирует и не требует Flask API для обработки файлов.
 Переиспользуемая инструкция находится в `upload/README.md`.
diff --git a/upload/README.md b/upload/README.md
index e6b4999..05f1064 100644
--- a/upload/README.md
+++ b/upload/README.md
@@ -1,13 +1,28 @@
 # Upload module
 
-Скопируйте каталог `upload/` в проект и подключите:
+Скопируйте каталог `upload/` в проект и подключите picker:
 
-- `create_upload_refs_blueprint(config)` к Flask-приложению;
 - `initUploadTable(config)` из `frontend/table/init_upload_table.js`;
-- `uploadViaVM(files, vmUploadUrl)` из `frontend/upload/upload_via_vm.js`.
+- локальный `fflate` до загрузки picker-модуля.
 
-В конфигурации задаются URL ВМ-буфера, допустимые расширения, лимиты и параметры
-повторных попыток pull. Backend-модуль хранит файлы сессии в памяти; обработка
-файлов остаётся ответственностью приложения, которое интегрирует этот модуль.
+`config` должен содержать `allowedExt`, а также ссылки на DOM-элементы
+`fileInputEl`, `folderInputEl`, `tableBodyEl` и `countEl`.
+
+Публичный API таблицы:
+
+- `pickFiles()` и `pickFolder()` — открыть системный выбор;
+- `getFiles()` — получить leaf-файлы с `path`, `name`, `size` и `file`;
+- `addFiles(files)` — добавить файлы программно;
+- `remove(id)` и `clear()` — удалить узел или очистить дерево.
+
+Picker поддерживает разрешённые документы, папки и вложенные ZIP, хранит
+исходные browser `File` objects и выполняет дедупликацию по пути и размеру.
+Загрузка на VM, backend sessions и upload API не используются.
+
+## Legacy
+
+Каталоги `backend/` и старые ссылки на `uploadViaVM`/VM-буфер относятся к
+предыдущей архитектуре и сохранены как legacy-остатки. Для текущей picker-only
+интеграции они не нужны.
 
 Для ZIP перед ES-модулями загрузите локальный `fflate` из `site/static/vendor/`.
\ No newline at end of file