# Справочник кода Upload Platform

Документ описывает актуальную picker-only реализацию. VM upload, backend sessions
и API загрузки являются legacy и в текущем коде не используются.

## Архитектура

```text
site/app.py
  -> site/templates/index.html
      -> dist/file-picker.iife.js
          -> upload/frontend/index.js
          -> table/on_files_change.js
          -> table/on_folder_change.js
          -> table/add_file_with_dedup.js
          -> table/render.js
          -> zip/list_zip_files.js
```

Flask отдаёт страницу и ES-модули. Все выбранные файлы остаются в памяти браузера;
сервер не принимает содержимое файлов.

## Модель данных

Каждый узел дерева имеет поля:

| Поле | Тип | Назначение |
|---|---|---|
| `id` | `string` | Уникальный идентификатор для DOM-кнопок и поиска. |
| `kind` | `file`, `folder`, `zip` | Тип узла. `file` является leaf. |
| `name` | `string` | Имя отображения в дереве. |
| `path` | `string` | Полный логический путь внутри выбора/архива. |
| `file` | `File \| null` | Исходный или созданный из ZIP browser File для leaf. |
| `children` | `Array` | Дочерние узлы группы. |
| `expanded` | `boolean` | Видимость дочерних строк в таблице. |

Внутреннее состояние picker-а:

| Поле | Назначение |
|---|---|
| `nodes` | Корневые узлы дерева. |
| `fileKeys` | Set ключей `path + NUL + size` для дедупликации. |
| `busy` | Защита от параллельной обработки async change-событий. |

## `upload/frontend/table`

### `add_file_with_dedup.js`

| Функция | Вход | Выход | Побочные эффекты |
|---|---|---|---|
| `addFileWithDedup(state, fileNode)` | state и корневой file/folder/zip-узел | `boolean` | Фильтрует дубли и пустые группы, добавляет узел и ключи в state. |

Дедупликация выполняется рекурсивно. Один и тот же путь с другим размером не
считается дублем.

### `esc.js`

| Функция | Вход | Выход |
|---|---|---|
| `esc(value)` | Любое значение | HTML-экранированная строка |

Используется перед `innerHTML`, `data-path`, `aria-label` и текстом имени.

### `fs.js`

| Функция | Вход | Выход |
|---|---|---|
| `fs(bytes)` | Размер в байтах | Строка в `B`, `KB` или `MB` |

### `rebase_tree.js`

| Функция | Вход | Выход | Побочные эффекты |
|---|---|---|---|
| `rebaseTree(root, prefix)` | Дерево и префикс папки | То же дерево | Рекурсивно меняет `path`; для leaf создаёт File с новым именем. |

Модуль является единственной реализацией rebasing для ZIP внутри выбранной папки
и для nested ZIP.

### `on_files_change.js`

| Функция | Вход | Выход | Назначение |
|---|---|---|---|
| `addFiles(state, cfg, files, elements)` | state, `allowedExt`, FileList/Array, DOM | `Promise<void>` | Фильтрует обычные файлы, раскрывает ZIP, вызывает render. |
| `onFilesChange(state, cfg, elements)` | state, config, DOM | async callback | Блокирует повторные события через `busy` и вызывает `addFiles`. |

Ошибка отдельного ZIP пропускается и передаётся в `cfg.onError(error, file)`, если
callback задан. `finally` обязательно освобождает `busy`.

### `on_folder_change.js`

| Функция | Вход | Выход | Назначение |
|---|---|---|---|
| `onFolderChange(state, cfg, elements)` | state, `allowedExt`, folder input и DOM | async callback | Строит дерево по `webkitRelativePath`, раскрывает ZIP и рендерит. |

Корень пути становится folder-узлом. Вложенные папки создаются по сегментам
пути, затем корень проходит общую дедупликацию.

### `render.js`

| Функция | Вход | Выход | Назначение |
|---|---|---|---|
| `renderNode(node, depth)` | Узел и глубина | HTML | Рекурсивно создаёт строки дерева. Внутренняя функция. |
| `render(state, elements)` | state и DOM | `void` | Перерисовывает таблицу и счётчик. |
| `findNode(nodes, id)` | Массив узлов и id | `{node, nodes}` или `null` | Ищет узел и его родительский массив. |
| `flattenFiles(nodes, result)` | Дерево и аккумулятор | Массив leaf-файлов | Преобразует дерево для API приложения. |

`render` считает все leaf-файлы, включая свернутые группы. `renderNode` показывает
дочерние строки только при `expanded === true`.

### `init_upload_table.js` (legacy)

| Функция | Вход | Выход | Назначение |
|---|---|---|---|
| `removeFileMeta(state, node)` | state и удаляемое поддерево | `void` | Рекурсивно удаляет dedup-ключи. Внутренняя функция. |
| `removeNode(state, id)` | state и id | `void` | Удаляет узел из родительского массива. Внутренняя функция. |
| `initUploadTable(cfg)` | `allowedExt` и четыре DOM-элемента | API-объект | Создаёт state, события, render и публичные операции. |

Публичный API legacy-совместимости:

| Метод | Вход | Результат |
|---|---|---|
| `pickFiles()` | нет | Открывает обычный file input. |
| `pickFolder()` | нет | Открывает folder input. |
| `addFiles(files)` | FileList/Array | Добавляет файлы с фильтрацией и ZIP-разбором. |
| `getFiles()` | нет | `{path, name, size, file}[]` только для leaf. |
| `remove(id)` | id узла | Удаляет узел и его dedup-ключи. |
| `render()` | нет | Перерисовывает текущий state. |
| `clear()` | нет | Очищает дерево и dedup Set. |

## `upload/frontend/zip`

### `list_zip_files.js`

| Функция | Вход | Выход | Назначение |
|---|---|---|---|
| `extensionAllowed(name, allowedExt)` | Имя и расширения | boolean | Проверяет расширение. Внутренняя. |
| `makeFile(data, name)` | Байты и путь | `File` | Создаёт browser File. Внутренняя. |
| `safeEntryParts(entryName)` | Сырой ZIP-путь | сегменты или null | Отбрасывает traversal и опасные пути. Внутренняя. |
| `node(kind, name, path, children, file)` | Метаданные узла | node | Создаёт узел. Внутренняя. |
| `addPath(root, parts, fileNode)` | Дерево, сегменты, узел | `void` | Создаёт папки и вставляет узел. Внутренняя. |
| `listEntries(data, zipName, allowedExt, depth)` | ZIP bytes и контекст | `Promise<node|null>` | Рекурсивно обрабатывает ZIP. Внутренняя. |
| `listZipFiles(file, allowedExt, limits)` | browser File, расширения и limits | `Promise<node|null>` | Публичная точка входа ZIP-парсера. |

Безопасность: отклоняются абсолютные пути, backslash, пустые сегменты, `.` и
`..`; применяются лимиты `maxEntries`, `maxTotalBytes`, `maxEntryBytes` и
`maxDepth` с безопасными значениями по умолчанию. ZIP без разрешённых leaf-файлов
возвращает `null` и не создаёт пустую группу.

## `upload/frontend/index.js`

`initFilePicker({ mount, allowedExt, labels, layout, limits, onChange, onError })`
строит весь DOM внутри HTMLElement или CSS-селектора `mount`, подключает inputs,
таблицу и обработчики. Возвращаемый API: `pickFiles`, `pickFolder`, `addFiles`,
`getFiles`, `remove`, `clear`, `render`, `destroy`. `getFiles` и `onChange`
возвращают копии массива leaf-файлов. `destroy` снимает слушатели и очищает mount.

IIFE-бандл экспортирует этот API как `FilePicker.initFilePicker`; ESM-бандл
экспортирует функцию напрямую. `fflate` включён в оба bundle, поэтому глобальный
vendor script не требуется.

## Flask и HTML

### `site/app.py`

| Маршрут/объект | Вход | Выход |
|---|---|---|
| `CONFIG` | `config.json` | JSON-конфигурация picker |
| `VERSION` | константа | Версия страницы |
| `index()` / `/` | HTTP GET | HTML с version и config |
| `health()` / `/health` | HTTP GET | `ok`, HTTP 200 |
| `upload_frontend(filename)` | HTTP GET и относительный путь | Legacy-файл из `upload/frontend` |
| `file_picker_dist(filename)` | HTTP GET и имя bundle | Bundle из `dist` |

### `site/templates/index.html`

Шаблон создаёт mount, подключает IIFE bundle с query-параметром версии для
сброса browser cache и вызывает `FilePicker.initFilePicker`.

## Legacy

`upload/frontend/table/set_status.js` не импортируется актуальной страницей и
сохранён как legacy-заготовка. Vendor `site/static/vendor/fflate.min.js` не
документируется построчно: это внешняя библиотека, используемая как готовый
runtime dependency.