Add README and implementation plan

2026-09-05 08:09:05 +03:00
parent 39953c7c59
commit 82d9ca9136
2 changed files with 340 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Upload Platform
+
+Переиспользуемый сервис загрузки файлов через ВМ-буфер. Выносит два слоя —
+**выбор файлов** (фронт) и **закачку через ВМ** (фронт + бэк) — в отдельный
+проект, который копируется в любой другой проект.
+
+Паттерн: браузер → `PUT` на ВМ-буфер → Flask `POST /api/upload_refs` (egress pull) → сессия.
+
+## Слои
+
+| Слой | Ответственность |
+|---|---|
+| 0. Конфиг | `vmUploadUrl`, `allowedExt`, лимиты, ретраи |
+| 1. Выбор файлов | таблица, дедуп, раскрытие ZIP, рекурсивный обход папки |
+| 2. Закачка через ВМ | PUT на ВМ → pull в сессию |
+| 3. Логика приложения | здесь — стаб-заглушка (в каждом проекте своя) |
+
+## Структура
+
+```
+upload-platform/
+├── requirements.txt
+├── config.json               # слой 0 (рабочий конфиг этого демо)
+├── upload/                   # ← переиспользуемый модуль (копируется в любой проект)
+│   ├── README.md             # инструкция интеграции
+│   ├── config.example.json
+│   ├── frontend/             # слои 1+2 (vanilla JS, ES-модули)
+│   │   ├── zip/
+│   │   ├── table/
+│   │   └── upload/
+│   └── backend/              # слой 2 (Python)
+│       ├── upload_refs/
+│       └── session/
+└── site/                     # демо-обёртка (не переиспользуется)
+    ├── app.py
+    ├── routes/
+    ├── templates/
+    └── static/
+```
+
+## Локальный запуск
+
+```bash
+pip install -r requirements.txt
+python site/app.py
+# → http://127.0.0.1:5000/
+```
+
+## Деплой на 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.
+
+## Как интегрировать слои в другой проект
+
+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 (обработка файлов) — свой; сюда приходит список файлов сессии после закачки.
+
+Подробнее — `PLAN.md`.