docs: record final Layer 2 checkpoint

2026-09-06 12:03:21 +03:00
parent 112c84f11a
commit 8768fd96ec
1 changed files with 52 additions and 0 deletions
@@ -0,0 +1,52 @@
+# 2026-09-06: Финальная фиксация состояния Слоя 2
+
+## Репозиторий
+
+- Проект: `upload-platform`.
+- Основная ветка: `master`.
+- Рабочее дерево на момент фиксации чистое.
+- Основной коммит реализации: `112c84f`.
+- Изменения отправлены в `origin/master`.
+- Контрольное состояние сохранено в ветке `checkpoint-layer2-complete`, опубликованной в origin.
+
+## Реализованное состояние
+
+В `upload-platform` реализованы и изолированы два API-слоя:
+
+1. **Слой 1: File Picker**
+   - Выбор файлов и папок.
+   - Клиентская распаковка ZIP и вложенных архивов.
+   - Дедупликация, фильтрация и лимиты.
+   - Контракт: `picker.getFiles()` возвращает плоский список объектов `{ path, name, size, file }`.
+
+2. **Слой 2: Per-file Transit**
+   - Для каждого файла выполняется последовательность `PUT` в буфер ВМ -> `POST /api/upload_refs` -> исходящий потоковый `GET` в RAM сессии -> `DELETE` из буфера ВМ.
+   - Следующий файл начинает передаваться только после завершения текущего.
+   - В буфере ВМ одновременно находится не более одного файла.
+   - Файлы сессии хранятся только в оперативной памяти.
+   - URL буфера задаются конфигурацией через `vmUploadUrl` и `vmUploadPrefix`; боевые домены не зашиваются в интеграционный код.
+   - Входящие URL проходят SSRF-проверку, имена файлов санитизируются.
+   - Для будущего Слоя 3 предусмотрен callback `onFileReceived(sid, name, content)`.
+
+## Автономный тестовый стенд
+
+`site/app.py` содержит RAM-only mock WebDAV с операциями `PUT`, `GET`, `DELETE` и маршрутом статуса. Это позволяет тестировать полный транзит без внешней ВМ:
+
+`browser -> mock buffer -> upload_refs -> RAM session -> Layer 3 callback`.
+
+## Проверка
+
+- `npm run build`: успешно.
+- `npm test`: 9 тестов пройдены.
+- `pytest tests/ -v`: 10 тестов пройдены.
+- Итого: 19 тестов, все пройдены.
+- Приложение `site/app.py` импортируется и регистрирует 11 маршрутов.
+
+## Версия и документация
+
+- Версия платформы: `0.2.0`.
+- Обновлены `README.md` и `upload/README.md`.
+- Техническое задание: `LAYER2-RESUME.md`.
+- Подробный отчёт реализации: `HISTORY/2026-09-06-layer2-implementation-and-tests.md`.
+
+Слой 3 в текущую реализацию не входит; он подключается потребляющим сервисом через API сессии и callback-контракт.