# Том 15. Интеграционная архитектура

## 15.1. Цель

Описать все интеграции между Digital Kazakhstan Experience / KazResource OS, промышленными объектами, гос. реестрами, финансовыми системами, SCADA, MES, ERP, GIS, AI, 3D и т.д. Каждая интеграция должна иметь паспорт, контракт, event-схему, fallback и тесты.

---

## 15.2. Категории интеграций

| Категория | Примеры систем | Режим | Протокол | Зона |
|-----------|----------------|-------|----------|------|
| Государственные реестры | KazSubsoil, ГКД, e-License, Minerals.gov.kz, Реестр недр | ETL, API, CDC | REST/GraphQL, SFTP | DMZ / Government Cloud |
| Геологические системы | GEO-INFORM, KazGeology, Seismic DB | ETL | S3/SFTP, WMS | DMZ |
| SCADA / АСУ ТП | KUT HMI/SCADA, WinCC, Ignition, Honeywell, Siemens S7 | Read-only polling | OPC-UA, MQTT, Modbus TCP | OT-DMZ (Level 3.5) |
| MES | АСУ предприятием, Wonderware MES | API/CDC | REST, OPC-UA | OT-DMZ |
| ERP | 1С, SAP, Oracle | API/CDC | REST, OData, EDI | IT-DMZ |
| EAM | IBM Maximo, Infor EAM | API | REST | IT |
| GIS | Cesium Ion, ArcGIS, QGIS, KazGPS | Tiles/Features | WMS/WFS/3DTiles | IT/DMZ |
| Экологический мониторинг | EcoMon, KazHydroMet, датчики | Streaming | MQTT, Kafka, REST | DMZ |
| Финансовые системы | NPC Digital Tenge, Halyk, Kaspi, BCC, Altyn, Eurasian, KUT Digital Bank | API | REST, gRPC, ISO 20022, CBDC testnet | Fintech Zone |
| Лаборатории | LIMS, Certificate DB | API/ETL | REST, HL7, FHIR | DMZ |
| Транспорт/Логистика | KazTransOil TMS, АСУ ЖД, портовые системы | API/Event | Kafka, REST, EDI | DMZ |
| Спутниковые источники | Sentinel, Landsat, SAR, погода | ETL/Stream | STAC API, S3, MQTT | External → DMZ |
| Документооборот | E-Office, EDS, МЧД, нотариус | API/Event | REST, AS2, blockchain notary | DMZ |
| AI/ML | LLM API, RAG, Vector DB, Whisper, TTS | API | REST/gRPC/Websocket | AI Zone |
| 3D/DT | Unreal Pixel Streaming, Cesium, Asset Registry | Stream/API | WebRTC, REST, gRPC | DMZ |

---

## 15.3. Паспорт интеграции

Для каждой интеграции обязателен паспорт:

| Поле | Описание |
|------|----------|
| INT-XXX | Уникальный ID интеграции |
| Название | Человекочитаемое название |
| Владелец | Domain owner |
| Цель | Зачем нужна |
| Источник | Система-источник, endpoint, credentials |
| Получатель | Сервис/модуль/БД |
| Протокол | OPC-UA, MQTT, REST, gRPC, Kafka, SFTP, и т.д. |
| Формат | JSON, Avro, Protobuf, XML, CSV, OPC UA JSON, 3DTiles |
| Частота | Real-time / 5s / 1min / 15min / hourly / daily |
| Объём | Сообщений/сек, МБ/день |
| Доступ | Service account, RBAC, mTLS, API key |
| Шифрование | TLS 1.3, mTLS, VPN, IPsec, data diode |
| Обработка ошибок | Retry, DLQ, circuit breaker, fallback |
| SLA | Доступность, latency, RPO/RTO |
| Fallback | Режим при недоступности источника |
| Тестирование | Contract tests, mock tests, chaos tests |

### Пример: INT-OT-001 — Телеметрия Узен (SCADA → Edge → Platform)

| Поле | Значение |
|------|----------|
| ID | INT-OT-001 |
| Название | Узен DNS/ЦПСН → Edge → Platform telemetry |
| Владелец | OT Lead |
| Источник | KUT HMI/SCADA / OPC-UA сервер DN-104/DN-105 |
| Получатель | `telemetry-ingestion-service` → TimescaleDB + Kafka |
| Протокол | OPC-UA (read-only), MQTT pub to edge broker |
| Формат | OPC UA JSON, normalized tag: `{asset_id, tag_code, ts, value, unit, quality, provenance}` |
| Частота | 1–5 сек (real-time class), 1 мин (operational class) |
| Объём | ~5 000 тегов × 1 Hz = 18M точек/час |
| Доступ | mTLS-сертификат Edge Gateway, service account `svc_ot_uzen` |
| Шифрование | mTLS, VPN по OT-DMZ, one-way data diode опционально |
| Ошибки | DLQ, replay buffer 24h, fallback to synthetic demo data |
| SLA | 99.9% доступность, latency ≤ 5 s, RPO 1 мин, RTO 30 мин |
| Тесты | Contract test, tag mapping validation, replay test |

### Пример: INT-FIN-001 — Цифровой тенге NPC (testnet)

| Поле | Значение |
|------|----------|
| ID | INT-FIN-001 |
| Название | NPC Digital Tenge testnet → KUT Digital Bank bridge |
| Источник | NPC CBDC testnet node (Corda/R3 или собственная сеть) |
| Получатель | `cbdc-adapter` → `digital-tenge-wallet-service` |
| Протокол | REST/gRPC, ISO 20022-style messages |
| Формат | `{tx_id, from_wallet, to_wallet, amount, currency=KZT, status, timestamp, memo}` |
| Частота | On-demand, batch |
| Объём | до 100 000 TPS проектно, в демо ≤ 10 TPS |
| Доступ | API key + HMAC + mTLS |
| Шифрование | TLS 1.3 |
| Ошибки | DLQ, idempotency key, reconciliation report |
| SLA | P95 latency ≤ 3 s, 99.95% |

---

## 15.4. Event Catalog

Каталог событий NEB (National Event Bus) / IEL (Industrial Event Ledger):

| Событие | Топик | Payload | Частота | Подписчики |
|---------|-------|---------|---------|------------|
| AssetRegistered | `assets.registry.v1` | `{asset_id, type, lat, lon, owner, ts}` | Ad-hoc | Graph DB, 3D registry, AI |
| LicenseUpdated | `subsoil.license.v1` | `{license_id, asset_id, status, area_km2, ts}` | Ad-hoc | Investment, Legal, National Map |
| ProductionMeasured | `production.measurement.v1` | `{asset_id, product, volume, unit, ts, source}` | 1–15 min | Analytics, 3D UI, Financial AI |
| EquipmentAlarmRaised | `ot.alarm.v1` | `{asset_id, tag, severity, value, threshold, ts}` | Real-time | SOC, AI, Unreal scene, mobile push |
| MaintenanceCompleted | `maintenance.completed.v1` | `{asset_id, work_order, result, ts}` | Hourly | EAM, Knowledge graph |
| EnvironmentalLimitExceeded | `environment.limit.v1` | `{asset_id, parameter, value, limit, ts}` | Real-time | Ecologist AI, Regulator |
| InvestmentProjectUpdated | `investment.project.v1` | `{project_id, npv, irr, risk, ts}` | Daily/On-change | Investor cabinet, National dashboard |
| DocumentApproved | `documents.approved.v1` | `{doc_id, asset_id, approver, hash, ts}` | Ad-hoc | Audit trail, Graph |
| RiskLevelChanged | `risk.level.v1` | `{risk_id, level, asset_id, ts}` | Ad-hoc | Situation Center, AI |
| CBDCTransferSettled | `cbdc.settled.v1` | `{tx_id, amount, wallets, status, ts}` | On-demand | Financial AI, investor wallet |
| AIRecommendationIssued | `ai.recommendation.v1` | `{rec_id, agent, asset_id, options, confidence, ts}` | On-demand | UI, audit, human decision log |
| TwinStateUpdated | `twin.state.v1` | `{asset_id, 7d_state, ts}` | 1–5 s | 3D engine, analytics |

### JSON-схема события (production)

```json
{
  "specversion": "1.0",
  "type": "kz.digital.resource.production.measurement.v1",
  "source": "ot://uzen/dn-104/scada",
  "id": "uuid",
  "time": "2026-07-29T09:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "asset_id": "kut-ozen-well-1542",
    "license_id": "lic-0215-uyen",
    "product": "crude_oil",
    "volume_m3": 12.45,
    "unit": "m3/h",
    "ts": "2026-07-29T09:00:00Z",
    "source": "SCADA",
    "quality": "good",
    "provenance": "operational"
  }
}
```

---

## 15.5. Интеграционная шина

### 15.5.1. Компоненты

- **API Gateway** — Kong/NGINX/Wso2; маршрутизация, rate limiting, auth, audit.
- **Message Broker** — Apache Kafka / NATS JetStream; event bus NEB/IEL.
- **Streaming** — Kafka Streams / Flink для windowed-аналитики.
- **ETL/ELT** — Apache Airflow / dbt / Dagster для гос. реестров и исторических данных.
- **CDC** — Debezium для PostgreSQL/TimescaleDB.
- **File Exchange** — SFTP/S3 с landed zone, антивирус, структурная проверка.
- **Integration Adapters** — для каждой системы по паспорту.

### 15.5.2. Паттерны

- **Anti-corruption layer** — между OT и IT.
- **Strangler Fig** — постепенная миграция legacy.
- **Saga / Outbox** — распределённые транзакции цифрового актива/тенге.
- **CQRS** — разделение команд и запросов для 3D/AI/Finance.
- **Adapter + Normalizer** — все теги приводятся к канонической модели (см. Том 4).

---

## 15.6. Требования к интеграционным API

1. OpenAPI 3.0+ или gRPC/GraphQL schema.
2. Версионирование URL (`/v1/`, `/v2/`) + заголовок `Accept-Version`.
3. OAuth 2.0 / OIDC + mTLS для machine-to-machine.
4. Rate limiting: business APIs — до 10 000 req/min; OT APIs — до 1 000 req/min.
5. Идемпотентность для финансовых и write-операций (`Idempotency-Key`).
6. Корреляционный ID `X-Correlation-ID` через всю цепочку.
7. Трассировка OpenTelemetry, логи JSON.
8. SLA и SLO на latency, availability, error rate.
9. Правила deprecation: минимум 6 месяцев notice, dual-version.

---

## 15.7. Государственные интеграции для демо

| Система | Что получаем | Как в демо |
|---------|--------------|------------|
| KazSubsoil / ГКД | Лицензии, участки, запасы, отчёты | Sandbox-реплика, анонимизированные полигоны |
| e-License | Статусы лицензий, сроки | Mock-сервис |
| Minerals.gov.kz | Кадастр недр | Кэшированная выгрузка |
| KazTransOil | Маршруты, NPS, объёмы | Historical open data + synthetic |
| NPC Digital Tenge | Testnet CBDC | Testnet или emulated ledger |
| Halyk / Kaspi / BCC / Altyn / Eurasian | Wallet / mock settlement | Sandbox APIs или mock-адаптеры |
| ЕНПФ / ФСМС / ГКД | Социальные и пенсионные распределения | Reference formulas, test accounts |

---

## 15.8. Безопасность интеграций

- Сегментация сети: OT, OT-DMZ, IT, IT-DMZ, Fintech, AI, Public.
- mTLS на всех machine-to-machine соединениях.
- API Gateway с WAF, DDoS, bot protection.
- Secret management: HashiCorp Vault, ротация ключей.
- Data minimization: только разрешённые поля, tokenization PAN/счетов.
- One-way data diode для read-only OT.
- Audit log всех интеграционных вызовов.

---

## 15.9. Приёмка интеграций

- Contract tests для каждого API-контракта.
- Integration tests на staging.
- Chaos tests: отключение источника, DLQ, fallback.
- Performance tests: peak load, sustained load.
- Security tests: penetration test интеграционных endpoint, SAST/DAST.
- Data reconciliation: сверка источника → bus → consumer.