From 521831be5ec7a9246e9e72838e3b75a6a5fd1301 Mon Sep 17 00:00:00 2001
From: AI Assistant <ai@clientright.ru>
Date: Tue, 25 Nov 2025 16:42:28 +0300
Subject: [PATCH] docs: Add n8n workflow documentation for form approval

Added documentation for n8n workflow setup:
- Redis channel subscription (clientright:webform:approve)
- Data structure description
- SQL script usage for marking forms as approved
- Verification steps

Files:
- docs/N8N_FORM_APPROVAL_WORKFLOW.md
---
 docs/N8N_FORM_APPROVAL_WORKFLOW.md | 120 +++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 docs/N8N_FORM_APPROVAL_WORKFLOW.md

diff --git a/docs/N8N_FORM_APPROVAL_WORKFLOW.md b/docs/N8N_FORM_APPROVAL_WORKFLOW.md
new file mode 100644
index 0000000..f671374
--- /dev/null
+++ b/docs/N8N_FORM_APPROVAL_WORKFLOW.md
@@ -0,0 +1,120 @@
+# Настройка n8n Workflow для обработки подтвержденных форм
+
+## Описание
+
+После того, как пользователь подтвердил форму и прошел SMS-верификацию, данные публикуются в Redis канал `clientright:webform:approve`. n8n workflow должен:
+
+1. Подписаться на Redis канал `clientright:webform:approve`
+2. Обработать данные формы
+3. Отметить форму как подтвержденную в PostgreSQL (чтобы она больше не показывалась в черновиках)
+
+## Структура данных в Redis канале
+
+```json
+{
+  "event_type": "form_approve",
+  "status": "approved",
+  "message": "Форма подтверждена после SMS-верификации",
+  "claim_id": "0eb051ec-23a6-4e06-8b98-f02d20d35f68",
+  "session_token": "sess_xxx",
+  "unified_id": "usr_xxx",
+  "phone": "79262306381",
+  "sms_code": "123456",
+  "sms_verified": true,
+  "idempotency_key": "claim_id_timestamp_user_id",
+  "timestamp": "2025-11-25T12:30:36.262855",
+  "form_data": { /* данные формы */ },
+  "user": { /* данные пользователя */ },
+  "project": { /* данные проекта */ },
+  "offenders": [ /* нарушители */ ],
+  "meta": { /* метаданные */ }
+}
+```
+
+## Настройка n8n Workflow
+
+### Шаг 1: Redis Subscribe Node
+
+1. Добавьте **Redis Subscribe** node
+2. Настройте подключение к Redis:
+   - Host: `crm.clientright.ru` (или IP вашего Redis)
+   - Port: `6379`
+   - Password: `CRM_Redis_Pass_2025_Secure!`
+3. Channel: `clientright:webform:approve`
+4. Output: `JSON`
+
+### Шаг 2: Обработка данных
+
+После получения данных из Redis канала:
+
+1. **Parse JSON** (если нужно)
+2. **Обработайте данные формы** (сохранение в CRM, отправка уведомлений и т.д.)
+3. **Отметьте форму как подтвержденную** (см. Шаг 3)
+
+### Шаг 3: Отметка формы как подтвержденной
+
+Используйте **PostgreSQL** node с SQL скриптом из `SQL_MARK_FORM_APPROVED.sql`:
+
+```sql
+-- Используйте claim_id из данных Redis события
+WITH claim_lookup AS (
+  SELECT 
+    c.id,
+    c.payload,
+    c.status_code,
+    c.is_confirmed
+  FROM clpr_claims c
+  WHERE c.id::text = '{{ $json.claim_id }}'::text
+     OR c.payload->>'claim_id' = '{{ $json.claim_id }}'::text
+  ORDER BY 
+    CASE WHEN c.id::text = '{{ $json.claim_id }}'::text THEN 1 ELSE 2 END,
+    c.updated_at DESC
+  LIMIT 1
+)
+UPDATE clpr_claims c
+SET 
+  status_code = 'approved',
+  is_confirmed = true,
+  updated_at = now()
+FROM claim_lookup cl
+WHERE c.id = cl.id
+RETURNING 
+  c.id,
+  c.payload->>'claim_id' AS claim_id,
+  c.status_code,
+  c.is_confirmed,
+  c.updated_at;
+```
+
+**Параметры:**
+- `{{ $json.claim_id }}` - claim_id из данных Redis события
+
+**Результат:**
+- Форма помечается как `status_code = 'approved'`
+- Устанавливается `is_confirmed = true`
+- Форма больше не будет показываться в списке черновиков (`/api/v1/claims/drafts/list`)
+
+## Проверка работы
+
+После обработки события в n8n:
+
+1. Проверьте, что запись в `clpr_claims` обновлена:
+   ```sql
+   SELECT id, status_code, is_confirmed, updated_at 
+   FROM clpr_claims 
+   WHERE payload->>'claim_id' = 'YOUR_CLAIM_ID';
+   ```
+
+2. Проверьте, что форма не показывается в черновиках:
+   ```bash
+   curl "http://localhost:8200/api/v1/claims/drafts/list?unified_id=YOUR_UNIFIED_ID"
+   ```
+
+## Важные поля из Redis события
+
+- `claim_id` - ID заявки (используется для обновления статуса)
+- `sms_code` - SMS код, использованный для верификации (для аудита)
+- `form_data` - данные формы подтверждения
+- `user`, `project`, `offenders` - структурированные данные формы
+- `idempotency_key` - ключ для защиты от дублей (для будущей интеграции с RabbitMQ)
+