# DATA_STRUCTURE - Структуры данных и схемы

## JSON Schema: Instance Response

### Структура инстанса из API

```json
{
  "instance": {
    "instanceUid": "0fcbae6c-6a36-4ce8-877d-58733f7c2fef",
    "displayName": "naeel-wheel",
    "svc": 1,
    "code": "S3",
    "explainedStatus": "running",
    "resourceRealm": "ceph.tst.nubes.ru",
    
    "state": {
      "params": {
        "resourceCPU": 100,
        "resourceMemory": 128,
        "s3UserUid": "abc123...",
        "displayName": "naeel-wheel",
        // ... ещё 68 полей
      },
      "out": {
        "bucket_name": "naeel-wheel",
        "api_endpoint": "https://ceph.tst.nubes.ru",
        // ... ещё 21 поле
      }
    },
    
    "dependencies": [
      {
        "instanceUid": "dep-uid-1",
        "displayName": "dep-name",
        "relationType": "PROVISIONING_DEPENDENCY"
      }
    ],
    "dependentInstances": [
      {
        "instanceUid": "dep-uid-2",
        "displayName": "dep-name-2",
        "relationType": "DEPLOYMENT_DEPENDENCY"
      }
    ],
    
    "createdAt": "2024-03-15T10:30:52Z",
    "modifiedAt": "2024-03-20T14:22:01Z"
  }
}
```

### Типы данных

| Поле | Тип | Примеры | Известные значения |
|------|-----|---------|-------------------|
| `instanceUid` | UUID | `0fcbae6c-6a36-4ce8-877d-58733f7c2fef` | UUID v4 |
| `displayName` | string | `naeel-wheel`, `iot-k8s-cluster` | 2-50 символов |
| `svc` | number (enum) | 1, 2, 3, ... | Зависит от сервиса |
| `code` | string (enum) | S3, PostgreSQL, Redis, ... | 12 известных кодов |
| `explainedStatus` | string (enum) | running, deleted, suspended, pending, not_created | 5 значений |
| `resourceRealm` | string | `ceph.tst.nubes.ru`, `"N/A"` | Адрес платформы или N/A |
| `createdAt` | ISO8601 | `2024-03-15T10:30:52Z` | RFC3339 timestamp |

---

## Массивы параметров: Input Parameters (state.params)

### Категория 1: Infrastructure
```json
{
  "resourceCPU": 100,
  "resourceMemory": 128,
  "resourceStorage": 1024,
  "resourceNetwork": "1GbE",
  "resourceDisk": 50
}
```

### Категория 2: Storage References
```json
{
  "s3UserUid": "uuid",
  "s3Uid": "uuid",
  "s3BucketName": "mybucket",
  "s3Endpoint": "https://ceph.tst.nubes.ru"
}
```

### Категория 3: Network References
```json
{
  "vdcUid": "uuid",
  "organizationUid": "uuid",
  "edgeUid": "uuid",
  "networkUid": "uuid",
  "ipUuid": "uuid"
}
```

### Категория 4: Configuration
```json
{
  "displayName": "service-name",
  "description": "Service description",
  "tags": ["tag1", "tag2"],
  "labels": {"key": "value"},
  "environment": "test"
}
```

### Категория 5: Integration
```json
{
  "postgresHost": "host.domain",
  "postgresPort": 5432,
  "postgresDatabase": "dbname",
  "redisHost": "host",
  "rabbitmqHost": "host",
  "rabbitmqPort": 5672
}
```

**Полный список всех 72 input параметров**: см. `/doc/api/PARAMETERS_REFERENCE.md`

---

## Массивы параметров: Output Parameters (state.out)

### Категория 1: Service Endpoints
```json
{
  "api_endpoint": "https://api.example.com",
  "dns_name": "service.domain.com",
  "external_ip": "1.2.3.4",
  "internal_ip": "10.0.0.x",
  "port": 443
}
```

### Категория 2: Credentials
```json
{
  "username": "admin",
  "password": "***",
  "access_key": "AKIAXXXXXXX",
  "secret_key": "***",
  "auth_token": "token_string"
}
```

### Категория 3: Connection Strings
```json
{
  "connection_string": "postgresql://...",
  "db_uri": "postgresql://host:5432/db",
  "client_url": "redis://host:6379"
}
```

### Категория 4: Resource Identifiers
```json
{
  "bucket_name": "mybucket",
  "cluster_id": "k8s-cluster-id",
  "namespace": "default",
  "service_id": "svc-123"
}
```

### Категория 5: Metadata
```json
{
  "version": "1.0.0",
  "status": "ready",
  "health": "healthy",
  "capacity": "100GB"
}
```

**Полный список всех 23 output параметров**: см. `/doc/api/PARAMETERS_REFERENCE.md`

---

## Dependencies: Структура связей

### API Dependencies (явные)
```json
{
  "dependencies": [
    {
      "instanceUid": "dep-uid",
      "displayName": "dependency-name",
      "relationType": "PROVISIONING_DEPENDENCY"
    }
  ],
  "dependentInstances": [
    {
      "instanceUid": "client-uid",
      "displayName": "client-name",
      "relationType": "DEPLOYMENT_DEPENDENCY"
    }
  ]
}
```

### Parametric Dependencies (вычисленные)
```json
[
  {
    "from": "naeel-k8s-cluster",
    "from_uid": "k8s-uid",
    "to": "naeel-vdc",
    "to_uid": "vdc-uid",
    "param": "vdcUid",
    "category": "Orchestration"
  },
  {
    "from": "dnsA-record",
    "from_uid": "dns-uid",
    "to": "naeel-rabbit",
    "to_uid": "rabbit-uid",
    "param": "recordName",
    "category": "DNS Routing"
  }
]
```

**Полный список 12 parametric dependencies**: см. `/tmp/links.json`

---

## Service Type Catalogue

### 1. S3 Object Storage
```json
{
  "code": "S3",
  "svc": 1,
  "instances": ["naeel-s3"],
  "role": "Central storage provider",
  "input_params": ["resourceCPU", "resourceMemory", "s3UserUid"],
  "output_params": ["api_endpoint", "bucket_name"],
  "platforms": ["ceph.tst.nubes.ru"]
}
```

### 2. S3 Bucket
```json
{
  "code": "S3BUCKET",
  "svc": 2,
  "instances": 5,
  "role": "Data storage",
  "parents": ["naeel-s3"],
  "inputs": ["s3Uid", "s3BucketName"]
}
```

### 3. PostgreSQL Database
```json
{
  "code": "PostgreSQL",
  "svc": 3,
  "instances": ["naeel-postgres"],
  "role": "Relational database",
  "outputs": ["connection_string", "postgres_host"]
}
```

### 4. Redis Cache
```json
{
  "code": "Redis",
  "svc": 4,
  "instances": ["naeel-redis"],
  "role": "In-memory cache"
}
```

### 5. RabbitMQ Message Broker
```json
{
  "code": "RabbitMQ",
  "svc": 5,
  "instances": ["naeel-rabbit"],
  "role": "Message queue"
}
```

### 6. Kubernetes Cluster
```json
{
  "code": "Kubernetes",
  "svc": 6,
  "instances": ["naeel-k8s-cluster"],
  "role": "Container orchestration",
  "depends_on": ["vdc", "edge"]
}
```

//... остальные 6 типов сервисов

**Всего 12 типов сервисов**: см. `/doc/api/PARAMETERS_REFERENCE.md#Service-Types`

---

## Platform Realms Distribution

```
ceph.tst.nubes.ru:
  - naeel-s3 (S3 storage hub)
  - naeel-s3-1 (bucket)
  - naeel-s3-2 (bucket)
  - naeel-s3-3 (bucket)
  - naeel-s3-4 (bucket)
  - naeel-s3-5 (bucket)
  Total: 6 instances

iot-naeel:
  - mqtt-bridge (MQTT integration)
  - iot-service (IoT gateway)
  Total: 2 instances

naeel-test-3:
  - naeel-sqs (SQS queue)
  - naeel-k8s-cluster (Kubernetes)
  Total: 2 instances

sandbox.nubes.ru:
  - naeel-vdc (Virtual Data Center)
  - naeel-edge (NSX-T Edge)
  - naeel-postgres (PostgreSQL)
  - naeel-redis (Redis)
  - naeel-rabbit (RabbitMQ)
  - naeel-organization (Organization)
  Total: 6 instances

grafana.ngcloud.ru:
  - grafana-monitoring (Grafana)
  Total: 1 instance

N/A (No specific platform):
  - public-ips-pool
  - dnsA-records
  Total: 2 instances
```

---

## Request/Response Examples

### List Instances Request
```bash
GET /api/v1/index.cfm/instances?page=1&size=100
Authorization: Bearer eyJhbGc...
Content-Type: application/json
```

### List Instances Response (200 OK)
```json
{
  "results": [
    {
      "instanceUid": "0fcbae6c-...",
      "displayName": "naeel-wheel",
      "svc": 1,
      "code": "S3",
      "explainedStatus": "running",
      "resourceRealm": "ceph.tst.nubes.ru"
    },
    // ... до 100 инстансов
  ],
  "page": 1,
  "size": 100,
  "total": 136
}
```

### Get Instance Details Request
```bash
GET /api/v1/index.cfm/instances/{instanceUid}
Authorization: Bearer eyJhbGc...
```

### Get Instance Details Response (200 OK)
```json
{
  "instance": {
    "instanceUid": "0fcbae6c-...",
    "displayName": "naeel-wheel",
    "state": {
      "params": { /* 72 параметров */ },
      "out": { /* 23 параметра */ }
    },
    "dependencies": [ /* API-based */ ],
    "dependentInstances": [ /* API-based */ ]
  }
}
```

### Error Response (401 Unauthorized)
```json
{
  "message": "invalid token format: JWT must consist of exactly three parts separated by dots",
  "requestId": "4c86f7321aaa4ed509b9205ece64e2d3",
  "statusCode": 401
}
```

---

## Data Files Reference

### `/tmp/all_instances.json` (Full list)
- 136 инстансов (all states)
- Fields: instanceUid, displayName, svc, code, explainedStatus, resourceRealm
- ~280 KB
- Updated: при каждом запуске скрипта

### `/tmp/all_params.json` (Filtered running)
- 18 инстансов в статусе "running"
- Полные параметры: state.params + state.out
- 72 input + 23 output параметров
- ~420 KB
- Updated: при каждом запуске скрипта

### `/tmp/links.json` (Dependencies)
- 12 parametric dependency links
- Fields: from, from_uid, to, to_uid, param, category
- ~8 KB
- Updated: при каждом запуске скрипта

### `/doc/api/all_instances_params.json` (Backup)
- Копия `/tmp/all_params.json` для длительного хранения
- Same structure
- ~420 KB
- Manual backup

---

## Типы данных в разрезе по сервисам

### S3 Hub (naeel-s3)
```
Input Params (Example):
  - resourceCPU: 100
  - resourceMemory: 128
  - s3UserUid: xxxxx

Output Params (Example):
  - api_endpoint: https://ceph.tst.nubes.ru
  - bucket_name_prefix: naeel-s3
```

### PostgreSQL (naeel-postgres)
```
Input Params (Example):
  - resourceCPU: 500
  - resourceMemory: 1024
  - resourceStorage: 50000
  - postgresDatabase: "sless_prod"

Output Params (Example):
  - connection_string: postgresql://admin:***@host:5432/sless_prod
  - postgresHost: postgres.naeel.svc
  - postgresPort: 5432
```

### Kubernetes (naeel-k8s-cluster)
```
Input Params (Example):
  - resourceCPU: 4000
  - resourceMemory: 8192
  - vdcUid: vdc-uuid
  - edgeUid: edge-uuid

Output Params (Example):
  - cluster_id: k8s-test-3
  - kubeconfig: base64-encoded
  - api_endpoint: https://k8s-api:6443
```

---

## Critical Data Points

### Single Points of Failure
1. **naeel-s3** (S3 Hub)
   - Если упадёт → 5 bucket'ов станут недоступны
   - Impact: HIGH
   
2. **naeel-vdc** (Virtual DC)
   - Если упадёт → 1 edge + 1 k8s станут недоступны
   - Impact: HIGH

3. **naeel-postgres** (Database)
   - Если упадёт → 6+ сервисов потеряют данные
   - Impact: CRITICAL

4. **naeel-k8s-cluster** (Container Orchestration)
   - Если упадёт → IoT сервисы остановятся
   - Impact: HIGH

### Параметры, требующие синхронизации
```json
{
  "sync_required": [
    {
      "param": "vdcUid",
      "who_has": ["naeel-k8s-cluster", "naeel-edge"],
      "what_references": "naeel-vdc",
      "risk": "Несинхронизированность → broken links in cluster"
    },
    {
      "param": "s3Uid",
      "who_has": ["все 5 buckets"],
      "what_references": "naeel-s3",
      "risk": "Orphaned buckets if s3 params changed"
    }
  ]
}
```

---

## Статистика данных

- **Total Instances**: 136
- **Running Instances**: 18
- **Input Parameters per Instance**: ~4 (среднее)
- **Output Parameters per Instance**: ~1.3 (среднее)
- **Total Unique Input Key Names**: 72
- **Total Unique Output Key Names**: 23
- **Parametric Dependencies**: 12
- **API Dependencies**: ~4 (average)
- **Average Response Time**: 150ms
- **Max Response Time**: 5000ms (PostgreSQL)
- **Service Types**: 12
- **Deployment Platforms**: 6
- **Instances with Unknown Platform**: 2