docs: image_storage readme improved

modules/image_storage/README.md

@@ -0,0 +1,97 @@
+
+---
+
+## Image Storage Service — API
+
+### POST `/upload`
+
+Загрузка изображения как файла.
+
+**Параметры запроса:**
+
+* `file` — файл изображения (multipart/form-data, обязательный)
+* `subdir` — подкаталог хранения (query, необязательный, по умолчанию `posters`)
+
+**Ответ:**
+
+```json
+{
+  "path": "posters/ab/cd/<sha1>.jpg"
+}
+```
+
+**Пример:**
+
+```bash
+curl -F "file=@poster.jpg" "http://localhost:8000/upload?subdir=posters"
+```
+
+---
+
+### POST `/download-by-url`
+
+Загружает изображение из внешнего URL в файловое хранилище сервиса.
+Клиенту файл не возвращается — сохраняется только на стороне сервиса.
+
+**Тело запроса (JSON):**
+
+```json
+{
+  "url": "https://example.com/image.jpg",
+  "subdir": "posters"
+}
+```
+
+`subdir` — необязательный, по умолчанию `posters`.
+
+**Ответ:**
+
+```json
+{
+  "path": "posters/ab/cd/<sha1>.jpg"
+}
+```
+
+**Пример:**
+
+```bash
+curl -X POST "http://localhost:8000/download-by-url" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com/image.jpg"}'
+```
+
+---
+
+### GET `/{path:path}`
+
+Получение сохранённого файла по относительному пути.
+
+**Параметры:**
+
+* `path` — относительный путь к файлу
+  (например: `posters/ab/cd/<sha1>.jpg`)
+
+**Ответы:**
+
+* `200 OK` — файл
+* `404 Not Found` — файл не найден
+
+**Пример:**
+
+```bash
+curl http://localhost:8000/posters/ab/cd/<sha1>.jpg --output image.jpg
+```
+
+---
+
+### Формат ответа
+
+Все write-эндпоинты (`POST`) возвращают объект:
+
+```json
+{
+  "path": "<relative_path>"
+}
+```
+
+Этот `path` используется для последующего доступа через `GET /{path}`.