phase-4: N8N workflows README — step-by-step for first BIT.RA pull (employees)

n8n/workflows/README.md

@@ -0,0 +1,123 @@
+# N8N Workflows — pull из источников в `raw_*` схемы
+
+## Подготовка credentials (один раз)
+
+Открой http://localhost:5678 → **Credentials** (левая панель) → **Add credential**.
+
+### Credential A: PostgreSQL для нашего хранилища
+
+| Поле | Значение |
+|---|---|
+| Type | **Postgres** |
+| Name | `bit_flight_deck PG` |
+| Host | `pipeline_postgres` |
+| Port | `5432` |
+| Database | `bit_flight_deck` |
+| User | `bit_flight_deck_user` |
+| Password | (значение `PG_PASSWORD` из `~/projects/bit-flight-deck/.env`) |
+| SSL | Disable |
+
+Save → должен быть зелёный «Connection tested successfully».
+
+### Credential B: HTTP Basic Auth для BIT.RA API
+
+| Поле | Значение |
+|---|---|
+| Type | **HTTP Basic Auth** |
+| Name | `BIT.RA API` |
+| User | `Админ Рома` (временно, пока bfd_api_user не настроен в БСП) |
+| Password | `FoxsuXHiS~` |
+
+Save.
+
+---
+
+## Workflow #1 — pull-bitra-employees
+
+Это **образец**. По нему клонируются остальные. Создавать в UI:
+
+1. **Workflows → Add Workflow**. Имя: `pull-bitra-employees`.
+
+2. Добавить ноду **Schedule Trigger**:
+   - Trigger Times: Cron expression `0 */6 * * *` (раз в 6 часов).
+
+3. Добавить ноду **HTTP Request** (соединить от Schedule Trigger):
+   - Method: **GET**
+   - URL: `http://188.93.213.204/LURV/hs/bfd-api/v1/employees`
+   - Authentication: **Generic Credential Type** → **HTTP Basic Auth** → выбрать credential `BIT.RA API`.
+   - Response Format: **JSON**
+
+4. Добавить ноду **Postgres** (соединить от HTTP Request):
+   - Credential: `bit_flight_deck PG`
+   - Operation: **Execute Query**
+   - Query:
+     ```sql
+     INSERT INTO raw_bitra.employees (bitra_id, payload, synced_at)
+     SELECT
+         elem->>'id'   AS bitra_id,
+         elem          AS payload,
+         now()         AS synced_at
+     FROM jsonb_array_elements($1::jsonb) AS elem
+     ON CONFLICT (bitra_id) DO UPDATE SET
+         payload = EXCLUDED.payload,
+         synced_at = now();
+
+     INSERT INTO public.sync_log (source, entity, last_sync_ts, records_count, status)
+     VALUES ('bitra', 'employees', now(), jsonb_array_length($1::jsonb), 'ok');
+     ```
+   - **Query Parameters**: добавить параметр **$1** со значением `={{ JSON.stringify($json) }}`.
+
+5. **Save** workflow.
+
+6. **Execute Workflow** (правый верх) — тестовый запуск.
+   - В каждой ноде должны быть зелёные галки и виден output.
+   - HTTP Request: массив объектов сотрудников.
+   - Postgres: ответ с количеством обновлённых строк.
+
+7. **Verify в БД:**
+   ```bash
+   docker exec -e PGPASSWORD=<PG_PASSWORD> -i pipeline_postgres psql -h localhost -U bit_flight_deck_user -d bit_flight_deck -c "SELECT count(*) FROM raw_bitra.employees;"
+   ```
+   Ожидаемо: > 0.
+
+8. **Activate** (тумблер вверху) — workflow начнёт выполняться по расписанию.
+
+9. **Export** → правый клик на workflow в списке → Download → положить JSON в `n8n/workflows/01-pull-bitra-employees.json`.
+
+---
+
+## Дальше — клонирование на остальные эндпоинты
+
+Когда `pull-bitra-employees` отлажен — для каждого следующего эндпоинта:
+1. **Duplicate workflow** (правый клик на workflow → Duplicate).
+2. Переименовать.
+3. Изменить только: URL в HTTP Request, Query в Postgres (другая таблица + другой entity в sync_log).
+4. Возможно — расписание Schedule (для works — каждые 30 мин, для словарей — раз в сутки).
+5. Save, Activate, Export.
+
+## Список workflows для MVP-1
+
+| # | Имя | URL endpoint | Расписание | Postgres таблица |
+|---|---|---|---|---|
+| 1 | pull-bitra-employees | `/v1/employees` | `0 */6 * * *` | `raw_bitra.employees` |
+| 2 | pull-bitra-works | `/v1/works?modified_since={{last_sync}}` | `*/30 * * * *` | `raw_bitra.works` |
+| 3 | pull-bitra-projects | `/v1/projects` | `0 */6 * * *` | `raw_bitra.projects` |
+| 4 | pull-bitra-stages | `/v1/stages` | `0 */6 * * *` | `raw_bitra.dictionaries` (kind='stage') |
+| 5 | pull-bitra-work-types | `/v1/work_types` | `0 4 * * *` (daily 04:00) | `raw_bitra.work_types` |
+| 6 | pull-bitra-dictionaries | `/v1/dictionaries` | `0 4 * * *` | `raw_bitra.dictionaries` |
+| 7 | pull-bitra-dept-history | `/v1/dept_history?modified_since={{last_sync}}` | `0 */6 * * *` | `raw_bitra.dept_history` |
+| 8 | pull-eva-incremental | EVA CmfAudit | `*/30 * * * *` | `raw_eva.*` |
+| 9 | pull-eva-nightly-full | EVA `.list` на все модели | `0 2 * * *` | `raw_eva.*` |
+| 10 | pull-bitrix-deals | Bitrix `crm.deal.list?filter[CATEGORY_ID]=16` | `*/15 * * * *` | `raw_bitrix.deals` |
+| 11 | pull-bitrix-users | Bitrix `user.get` | `0 5 * * *` | `raw_bitrix.users` |
+
+Детальные SQL для каждой таблицы — см. SQL views/procs в `sql/views/` и `sql/procedures/` (будут сгенерированы после успешного запуска первого pull).
+
+---
+
+## Когда первый workflow отработает
+
+Скажи мне — я:
+1. Подготовлю остальные workflows (через duplicate-pattern).
+2. Напишу SQL для `stg_bitra.*` views, `core.merge_*` procedures, `mart.*` views.
+3. Подготовлю Metabase dashboard.