# Файлы

> Хранилище файлов проекта для фото, видео и PDF: загрузка, адреса, удаление и лимиты.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

У каждого проекта есть хранилище для фото, видео, PDF и больших картинок. Файлы переживают
любую сборку, их адреса не меняются. Код приложения ограничен 10 МБ архива и 15 МБ
распакованной сборки, поэтому тяжёлое в код не кладут:

| Где лежит | Что |
|---|---|
| в коде приложения | иконки, шрифты, небольшие картинки |
| в хранилище проекта | фото, видео, PDF, большие иллюстрации |
| в самой [странице](https://docs.getxflow.com/platform/pages.md) | всё, что она показывает: хранилище страницам не служит |

Файлы приложения кладёт агент командой `xflow storage push`. Файлы от пользователей приложения
идут через [функцию](https://docs.getxflow.com/platform/functions.md): её код решает, можно ли посетителю загружать.

## Загрузка

```bash
xflow storage push ./media --to media
```

Заливает папку или файл, сохраняя структуру папок.

| Флаг | Что делает |
|---|---|
| `--to <папка>` | в какую папку хранилища положить |
| `--replace` | заменить файл с другим размером, адрес сохраняется |
| `--json` | вывод одним JSON |

Заливается только недостающее: файл с тем же путём и размером пропускается, поэтому после
обрыва команду повторяют. Файл с другим размером без `--replace` остаётся как был. Скрытые
файлы (имя с точки) не уезжают.

`xflow storage ls [папка]` печатает путь, размер и адрес каждого файла, `--json` отдаёт список
целиком. Команды скачать файлы в папку нет.

## Адреса файлов

`push` и `ls` печатают относительный адрес `/_files/<id>`, его отдаёт адрес самого приложения:

```html
<img src="/_files/8c1f…" alt="Товар">
```

- Файл открывает тот, кто может открыть приложение. У приложения «Любой по ссылке» это любой
  посетитель без входа.
- Адрес постоянный, `--replace` его не меняет: ссылки в коде и в таблицах базы остаются рабочими.
- В интерфейсе платформы файлы открывает тот, у кого есть доступ к проекту.

Файлы от пользователей приложения: функция просит у платформы одноразовую ссылку, браузер
отправляет файл по ней в хранилище,
функция подтверждает загрузку и получает адрес. Списка загруженного платформа не отдаёт: адрес
нужно сразу записать в свою таблицу. Подробности агент знает из инструкции о платформе.

## Удаление

```bash
xflow storage rm /_files/8c1f…
xflow storage rm --folder media --yes
```

Удаление необратимо. Без `--yes` удаление папки называет число файлов и ничего не делает.

Агенту нужно право «Удалять файлы»: по умолчанию выключено (в тех же папках файлы
пользователей), включает человек в разделе «AI агент», без него команда отвечает отказом. В
интерфейсе удаляет уровень «Редактирование».

## Лимиты и типы

До 200 МБ на файл. Общий объём у организации задаёт [тариф](https://docs.getxflow.com/platform/billing.md), его можно
докупить. Занятое и лимит показывает `xflow whoami`.

| Вид | Расширения |
|---|---|
| изображения | `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`, `ico`, `bmp`, `tif`, `tiff`, `heic`, `heif` |
| документы | `pdf`, `txt`, `md`, `rtf`, `csv`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `odt`, `ods`, `odp` |
| данные | `json`, `xml`, `yaml`, `yml`, `geojson`, `vtt`, `srt`, `dat` |
| аудио | `mp3`, `wav`, `ogg`, `oga`, `m4a`, `aac`, `flac`, `opus`, `weba` |
| видео | `mp4`, `webm`, `mov`, `m4v`, `mpg`, `mpeg`, `avi`, `mkv` |
| шрифты | `woff`, `woff2`, `ttf`, `otf` |
| архивы | `zip`, `gz`, `tgz`, `tar`, `7z`, `rar` |

Страницы, скрипты и программы (`html`, `js`, `exe` и подобные) не принимаются: код приложения
уезжает через деплой.

| Код отказа | Что значит |
|---|---|
| `invalid_name` | пустое или слишком длинное имя, `/` в имени файла |
| `file_too_large` | файл больше 200 МБ |
| `quota_exceeded` | место организации кончилось |
| `forbidden_type` | такой тип файла не принимается |
| `duplicate_name` | файл с таким именем уже есть в папке |
| `not_found` | файла или папки нет |

В интерфейсе файлы в блоке «Хранилище» на главной проекта: папки, занятое место, загрузка,
предпросмотр, скачивание и удаление.