upload-platform/README.md

Upload Platform

Переиспользуемый browser-only file-picker версии 0.1.13. Он выбирает файлы, папки и ZIP, строит дерево и возвращает интегрирующему приложению browser File objects. Содержимое файлов остаётся в браузере: текущий проект не загружает его на VM, в Flask или в другое хранилище.

Карта файлов

Корень проекта

Путь	Назначение	Статус
package.json	Версия пакета и команда npm run build.	Используется
package-lock.json	Зафиксированные npm-зависимости.	Используется
build.mjs	esbuild-сборка ESM и IIFE bundle.	Используется
requirements.txt	Python-зависимости demo-сервера.	Используется demo
config.json	Конфигурация demo: разрешённые расширения.	Используется demo
dist/file-picker.esm.js	Готовый ESM bundle для интеграции.	Используется
dist/file-picker.iife.js	Готовый IIFE bundle FilePicker.	Используется
upload/	Исходники переиспользуемого picker-модуля.	Используется
site/	Flask demo, который раздаёт страницу и bundle.	Используется только demo
docs/	Справочная и историческая документация.	См. раздел LEGACY
HISTORY/	Архив решений, ревью и результатов проверок.	Только история

upload/ — исходники picker-а

Путь	Назначение
upload/README.md	Краткая инструкция интеграции готового bundle.
upload/config.example.json	Пример конфигурации разрешённых расширений.
upload/frontend/index.js	Единственная актуальная точка входа initFilePicker(config), DOM, lifecycle API.
upload/frontend/table/add_file_with_dedup.js	Дедупликация файлов и слияние одинаковых корней.
upload/frontend/table/esc.js	HTML-экранирование имён, путей и атрибутов.
upload/frontend/table/fs.js	Форматирование размеров файлов.
upload/frontend/table/on_files_change.js	Выбор файлов, фильтрация, ZIP-разбор и fallback ошибок.
upload/frontend/table/on_folder_change.js	Выбор папки через webkitdirectory и построение дерева.
upload/frontend/table/rebase_tree.js	Добавление префикса пути без изменения базового File.name.
upload/frontend/table/render.js	Рендер дерева, счётчик, поиск узлов и flattenFiles().
upload/frontend/zip/list_zip_files.js	Безопасный рекурсивный разбор ZIP через встроенный fflate.

site/ — demo-обёртка

Путь	Назначение
site/app.py	Flask entrypoint, /, /health, раздача bundle и совместимый маршрут исходников.
site/templates/index.html	Demo-страница и вызов FilePicker.initFilePicker().
site/static/style.css	Стили demo-страницы.
site/routes/	Текущий каталог маршрутов; прикладного upload backend в нём нет.

docs/

Путь	Назначение	Статус
docs/CODE-REFERENCE.md	Справочник актуального picker-кода и API.	Использовать
docs/PLAN-componentization.md	Исторический план перехода к bundle API.	LEGACY, не использовать как план
docs/sonnet-architecture-review-prompt.md	Исторический prompt ревью старой архитектуры.	LEGACY, не использовать
docs/*-architecture-review-response.md	Ответы на исторические ревью.	История, не спецификация

HISTORY/

Файлы HISTORY/ фиксируют состояние проекта на даты ревью, тестов и решений. Они могут описывать удалённые файлы, VM-upload или старые версии. Это архив, а не инструкция: при расхождении с кодом руководствоваться только исходниками, README.md, upload/README.md и docs/CODE-REFERENCE.md.

Локальный запуск

pip install -r requirements.txt
npm install
npm run build
python site/app.py
# → http://127.0.0.1:5000/

Для запуска уже собранного demo достаточно иметь зависимости Python и содержимое dist/. npm run build требуется после изменения исходников upload/frontend/.

Деплой на Nubes

• Точка входа: site/app.py (платформа запускает python site/app.py).
• app.run(host="0.0.0.0", port=5000, debug=False).
• Маршрут /health → 200 (иначе liveness-проба платформы убивает под).
• Без site/__init__.py и factory pattern.

Как интегрировать picker в другой проект

1. Скопировать dist/file-picker.iife.js или dist/file-picker.esm.js в свой проект.
2. Подключить IIFE через <script> и вызвать FilePicker.initFilePicker, либо импортировать ESM-бандл.
3. Передать mount, allowedExt, а при необходимости labels, layout, limits и onChange.
4. Получить выбранные leaf-файлы через picker.getFiles(); каждый элемент содержит path, name, size и исходный file.
5. После удаления компонента вызвать picker.destroy().

Исходники upload/frontend/ нужны только для разработки и пересборки bundle; встроенная библиотека fflate уже включена в готовые bundle.

Разрешённые расширения демо: .pdf, .doc, .docx, .txt, .md. ZIP-файлы используются как контейнеры и раскрываются в браузере; сам ZIP не возвращается как leaf-файл. По умолчанию действуют ограничения: 1000 entries, 100 MiB суммарно, 50 MiB на entry и глубина 20.

Legacy

Удалено и не должно восстанавливаться

• upload/backend/ — старый backend VM-upload, sessions и pull API;
• upload/frontend/table/init_upload_table.js — старый entry point с готовыми DOM-узлами;
• upload/frontend/table/set_status.js — неиспользуемый legacy helper;
• upload/frontend/upload/ — старый frontend VM-upload layer.

Эти части не входят в сборку build.mjs, не импортируются текущим picker-ом и не являются частью API. Не добавлять их обратно при интеграции.

Исторические документы

PLAN.md, docs/PLAN-componentization.md, review prompts и записи HISTORY/ могут содержать описания старой VM/backend-архитектуры. Они нужны для аудита решений, но не являются актуальной спецификацией и не должны использоваться как план разработки.

Актуальная инструкция интеграции находится в upload/README.md.

Полный справочник функций, состояния, DOM-контрактов и ограничений находится в docs/CODE-REFERENCE.md.

История решений и проверок находится в HISTORY/.