feat: ingest HTTP 201/409 for event_id idempotency

- Validate UUID format; log created/duplicate/rejected - Tests for 201, 409, 422; update agent-integration and work-plan - Docs: neutral IDE wording (no product-specific editor names)
2026-05-28 09:13:12 +10:00
parent 5cf76f492c
commit 2b76ae8497
11 changed files with 210 additions and 26 deletions
@@ -15,7 +15,7 @@
 | [ssl-certificate.md](ssl-certificate.md) | Wildcard TLS: формат, scp, пути `/etc/ssl/sac/` |
 | [deployment.md](deployment.md) | Эксплуатация, backup, TLS, `sac-deploy.sh` |
 | [operations-prod-status.md](operations-prod-status.md) | **Статус prod** и следующие шаги |
-| [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root |
+| [workspace-three-repos.md](workspace-three-repos.md) | Multi-root workspace (три репо) |

 ## Порядок чтения

@@ -44,7 +44,7 @@
 | 2 | `RDP-login-monitor` | Агент на Windows Server |
 | 3 | `security-alert-center` | Центральный сервер (этот проект) |

-Совместная разработка в Cursor: multi-root workspace — см. [workspace-three-repos.md](workspace-three-repos.md).
+Совместная разработка в multi-root workspace — см. [workspace-three-repos.md](workspace-three-repos.md).

 ---

@@ -44,7 +44,7 @@ $SacSpoolDir = "D:\Soft\Logs\sac-spool"

 - `UseSAC=off` — без изменений: хотя бы один канал `NOTIFY_CHAIN` (как сейчас).
 - `UseSAC≠off` — обязательны `SAC_URL`, `SAC_API_KEY`; HTTP `GET {base}/health` OK.
- `--check-sac` / `Test-SacConnection` — отправка `agent.test`, ожидание `202`.
+- `--check-sac` / `Test-SacConnection` — отправка `agent.test`, ожидание **HTTP 201** (повтор с тем же `event_id` — **409**, тоже успех для spool).

 ---

@@ -64,20 +64,31 @@ Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
 ### 2.2. Ответ

 | HTTP | Значение | `status` в теле | `created` |
+|------|----------|-----------------|-----------|
+| **201** | Событие записано впервые | `created` | `true` |
+| **409** | Тот же `event_id` уже есть (идемпотентность) | `duplicate` | `false` |
+| **422** | Ошибка JSON Schema | — | — |
+
+Пример **201**:
+
+```json
 {
  "status": "created",
-  "event_id": "550e8400-e29b-41d4-a716-446655440000",
+  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "created": true,
-  "problem_id": null
+  "sac_event_url": "https://sac.kalinamall.ru/api/v1/events/12345",
+  "problem_id": null
 }
 ```

 `event_id` — обязательный **UUID** (RFC 4122), уникален глобально; в БД индекс `UNIQUE (event_id)`.
+
+### 2.3. Spool при ошибке

 1. Записать JSON в `SAC_SPOOL_DIR/{event_id}.json`.
 2. **ssh-monitor:** каждую итерацию цикла вызывается `sac_flush_spool` (до 20 файлов).
 3. После успеха (**HTTP 201** или **409**) — удалить файл из spool.
-4. Лимит размера spool (например 500 MB) — логировать WARN, не удалять без алерта.
+4. Лимит размера spool (например 500 MB) — логировать WARN, не удалять без алерта.

 ---

@@ -1,11 +1,11 @@
 # Диаграмма потоков данных (рис. 1 к ТЗ)

 Используется в [TZ.md](../TZ.md), раздел 3.  
-В GitLab/GitHub и в VS Code/Cursor с поддержкой Mermaid диаграмма рендерится автоматически.
+В GitLab/GitHub и в VS Code с поддержкой Mermaid диаграмма рендерится автоматически.

 ## Экспорт в PNG/SVG

-1. Открыть этот файл в Cursor preview или на https://mermaid.live
+1. Открыть этот файл в preview редактора или на https://mermaid.live
 2. Экспортировать как изображение для презентаций

 ```mermaid
@@ -81,7 +81,7 @@

 ### День 1

- [ ] `d1-1` Ingest: `event_id` UUID обязателен, UNIQUE индекс, коды duplicate, логи, docs/schema
+- [x] `d1-1` Ingest: `event_id` UUID обязателен, UNIQUE индекс, коды duplicate, логи, docs/schema
 - [ ] `d1-2` MVP Problems: модель, корреляция `host+type+окно`, API `GET/ack/resolve`
 - [ ] `d1-3` Правила v1: `brute-force burst`, `privilege spike`, `host silence`

@@ -106,9 +106,9 @@

 #### День 1

- [ ] `09:00–10:00` миграция `event_id` + UNIQUE, валидация ingest
- [ ] `10:00–11:00` поведение duplicate (`201/409`) и логирование reject
- [ ] `11:00–12:00` обновить `event-schema-v1.json` и `agent-integration.md` (в т.ч. `host.display_name` для агентов)
+- [x] `09:00–10:00` миграция `event_id` + UNIQUE, валидация ingest
+- [x] `10:00–11:00` поведение duplicate (`201/409`) и логирование reject
+- [x] `11:00–12:00` обновить `event-schema-v1.json` и `agent-integration.md` (в т.ч. `host.display_name` для агентов)
 - [ ] `13:00–14:30` модель Problems + миграция
 - [ ] `14:30–16:00` корреляция при ingest (`fingerprint`, `count`, `last_seen`)
 - [ ] `16:00–17:30` API `GET /problems`, `ack`, `resolve` + smoke
@@ -1,6 +1,6 @@
 # Multi-root workspace: три репозитория

-Как работать в Cursor над **ssh-monitor**, **RDP-login-monitor** и **security-alert-center** одновременно.
+Как работать в одном multi-root workspace над **ssh-monitor**, **RDP-login-monitor** и **security-alert-center** одновременно (VS Code или совместимый редактор).

 ---