crm.clientright.ru/crm_extensions/file_storage/S3_MONITORING_GUIDE.md

# 🔍 Руководство по мониторингу S3

## Проблема
Тебе нужно ловить **любые** изменения файлов в S3 bucket, даже если они загружены:
- Вручную через S3 Browser / Cyberduck
- Из внешних скриптов
- Не через CRM или Nextcloud

## ❌ Почему не Event Notifications?
TWC Storage **не поддерживает** S3 Event Notifications официально (не документировано).

## ✅ РЕШЕНИЕ: n8n Workflow с Polling

### Как работает:
```
n8n каждые 30 сек → Список файлов в S3 → Сравнение с предыдущим состоянием → 
→ Обнаружены изменения → Публикация в Redis → Твои обработчики
```

---

## 📋 Пошаговая инструкция

### Шаг 1: Импортируй workflow в n8n

1. Открой n8n: https://n8n.clientright.pro
2. Создай новый workflow
3. Нажми **Import from File**
4. Загрузи файл: `n8n_s3_monitor_workflow.json`

### Шаг 2: Настрой S3 Credentials

В n8n создай credentials:

**Тип:** AWS S3  
**Имя:** `TWC S3`

**Параметры:**
```
Access Key ID: [твой S3 ключ из Nextcloud]
Secret Access Key: [твой S3 секрет из Nextcloud]
Region: ru-1

Custom Endpoints: ✅ (включить!)
S3 Endpoint: https://s3.twcstorage.ru
Force Path Style: ✅ (включить!)
```

**Как получить ключи:**
```bash
docker exec nextcloud-fresh php occ files_external:list --output=json | jq -r '.[0].configuration | "Key: \(.key)\nSecret: \(.secret)\nBucket: \(.bucket)"'
```

### Шаг 3: Настрой Redis Credentials

**Тип:** Redis  
**Имя:** `CRM Redis`

**Параметры:**
```
Host: 147.45.146.17
Port: 6379
Password: CRM_Redis_Pass_2025_Secure!
Database: 0
```

### Шаг 4: Настрой Environment Variables (если нужно)

В n8n Settings → Environment Variables:
```
S3_BUCKET=f9825c87-18698658-c378-4aa7-91cc-0c131bebccda
WEBHOOK_URL=https://твой-эндпоинт.com/webhook (опционально)
```

### Шаг 5: Настрой Bucket и Prefix

В ноде **List S3 Files**:
- `Bucket Name`: укажи свой bucket (или используй `{{$env.S3_BUCKET}}`)
- `Prefix`: укажи папку для мониторинга (например `nextcloud/data/admin/files/`)
- Оставь пустым для мониторинга всего bucket

### Шаг 6: Активируй Workflow

1. Нажми **Active** (включи workflow)
2. Первый запуск создаст начальное состояние файлов
3. Последующие запуски будут сравнивать с предыдущим состоянием

---

## 🧪 Тестирование

### 1. Загрузи тестовый файл в S3

Через S3 Browser, Cyberduck или aws-cli:
```bash
echo "test" > test.txt
aws s3 cp test.txt s3://твой-bucket/test.txt \
  --endpoint-url https://s3.twcstorage.ru
```

### 2. Подожди 30 секунд (интервал polling)

### 3. Проверь Redis

```bash
redis-cli -h 147.45.146.17 -p 6379 -a 'CRM_Redis_Pass_2025_Secure!' \
  SUBSCRIBE crm:file:events
```

Должно прийти:
```json
{
  "type": "file_created",
  "source": "s3_monitor",
  "timestamp": "2025-10-30T12:34:56Z",
  "path": "test.txt",
  "filename": "test.txt",
  "size": 5,
  "etag": "\"098f6bcd4621d373cade4e832627b4f6\"",
  "last_modified": "2025-10-30T12:34:50Z"
}
```

---

## ⚙️ Настройка интервала

Измени интервал проверки в ноде **"Каждые 30 секунд"**:

- **10 секунд** - почти реал-тайм, но больше нагрузка на S3 API
- **30 секунд** - оптимальный баланс (рекомендуется)
- **60 секунд** - экономия API запросов

**Важно:** TWC может лимитировать количество API запросов!

---

## 📊 Типы событий

Workflow генерирует 3 типа событий:

1. **`file_created`** - новый файл появился в bucket
2. **`file_modified`** - файл изменился (другой ETag)
3. **`file_deleted`** - файл удалён из bucket

---

## 🔄 Обработка событий в других workflows

Создай новый workflow в n8n:

### Trigger: Redis (Subscribe)
```
Host: 147.45.146.17
Port: 6379
Password: CRM_Redis_Pass_2025_Secure!
Channel: crm:file:events
```

### Filter: По типу события
```javascript
// Обрабатываем только создание файлов
return $json.type === 'file_created';
```

### Switch: По расширению файла
```javascript
const ext = $json.filename.split('.').pop().toLowerCase();

switch(ext) {
  case 'pdf':
    return [0]; // Обработка PDF
  case 'jpg':
  case 'png':
    return [1]; // Обработка изображений
  case 'xlsx':
  case 'csv':
    return [2]; // Обработка таблиц
  default:
    return [3]; // Остальные файлы
}
```

---

## 🎯 Пример: Автоматическая обработка ERV файлов

```
Redis Subscribe (crm:file:events) → 
→ Filter (filename contains "erv") → 
→ Download from S3 → 
→ Process ERV → 
→ Upload to CRM → 
→ Notify user
```

---

## 📝 Мониторинг нескольких buckets

Если тебе нужно мониторить несколько buckets:

1. **Вариант 1:** Создай отдельный workflow для каждого bucket
2. **Вариант 2:** Используй Loop в workflow для перебора buckets

---

## 🚨 Важные замечания

1. **State сохраняется в Static Data** - не удаляй workflow без экспорта!
2. **Первый запуск не генерирует события** - только создаёт начальное состояние
3. **ETag используется для определения изменений** - если файл перезаписан с тем же содержимым, событие не сработает
4. **Polling = задержка** - событие придёт через 0-30 секунд после реального изменения

---

## 🔧 Troubleshooting

### Проблема: Не приходят события
- Проверь что workflow **Active** (зелёная галочка)
- Проверь логи workflow (Execute → View executions)
- Проверь credentials (S3 и Redis)

### Проблема: Слишком много событий
- Уменьши область мониторинга через `Prefix`
- Увеличь интервал polling до 60-120 секунд

### Проблема: Пропускаются изменения
- Уменьши интервал до 10-15 секунд
- Проверь что State сохраняется (Static Data)

---

## 📚 Дополнительные материалы

- [n8n AWS S3 Node](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.awss3/)
- [n8n Redis Node](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.redis/)
- [n8n Code Node](https://docs.n8n.io/code-examples/methods-variables-reference/)

---

## 🎉 Готово!

Теперь у тебя есть полноценный мониторинг S3 bucket в реальном времени!

Все изменения файлов будут автоматически публиковаться в Redis канал `crm:file:events`, 
откуда их могут подхватить другие твои системы (CRM, другие n8n workflows, и т.д.)