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`.

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

```bash
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`](docs/CODE-REFERENCE.md).

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