# Анализ ширины колонок таблиц документации

> Методика определения оптимальных ширин колонок на основе реальных данных из YAML-спек.

---

## Методика

### Источник данных

Все параметры ресурсов генерируются из YAML-спек в `generated/<stand>/resources_yaml/*.yaml`.
Скрипт анализа собирает ВСЕ параметры из всех YAML-файлов (только операции `create` и `modify`, включая вложенные `sub_params`).

### Что измеряется

Для каждого параметра извлекаются 5 групп значений:

| Группа | Поля YAML | Назначение в таблице |
|---|---|---|
| Code | `code` | Название параметра |
| Type | `data_type`, `type` | Тип данных |
| Default | `default` | Значение по умолчанию |
| Description | `descr`, `man` | Описание |
| Constraints | `min_value`, `max_value`, `regex`, `value_list`, `max_length`, `min_length`, `func`, `ref_svc_id`, `unique` | Ограничения |

Для каждой группы вычисляется:
- MAX длина строки (символов)
- AVERAGE длина
- % значений длиннее 30/50/100/200/500 символов

### Код анализа

```python
import os, yaml

YAML_DIR = 'generated/test/resources_yaml'
all_params = []
nested_count = 0

def extract_params(svc, op, params_list, depth=0):
    global nested_count
    for p in params_list:
        if not isinstance(p, dict): continue
        all_params.append((svc, op, p, depth))
        sub = p.get('sub_params', [])
        if sub:
            nested_count += len(sub)
            extract_params(svc, op, sub, depth + 1)

for fname in sorted(os.listdir(YAML_DIR)):
    if not fname.endswith('.yaml'): continue
    with open(os.path.join(YAML_DIR, fname)) as f:
        data = yaml.safe_load(f)
    svc = data.get('name', fname)
    for op in data.get('operations', []):
        if op.get('action') not in ('create', 'modify'): continue
        extract_params(svc, op.get('name','?'), op.get('params', []))

# ... (статистика по 5 группам, см. ниже)
```

### Когда перезапускать анализ

- После добавления новых сервисов
- После изменения структуры параметров в API
- При смене стенда (test/dev/prod)

Запуск:
```bash
python3 analyze_column_widths.py
```

---

## Результаты (стенд test, 2026-07-18)

**Объём данных:** 49 YAML-файлов, 775 параметров, 339 вложенных sub_params

| Колонка | Count | MAX (симв.) | AVG (симв.) | >50 | >100 | >200 |
|---|---|---|---|---|---|---|
| **Code** | 775 | 29 | 11 | 0% | 0% | 0% |
| **Type** | 775 | 15 | 9 | 0% | 0% | 0% |
| **Default** | 497 | 48 | 4 | 0% | 0% | 0% |
| **Description** | 488 | 635 | 69 | **55%** | **25%** | **3%** |
| **Constraints** | 247 | 199 | 46 | 27% | 6% | 0% |

### Выводы

1. **Code, Type, Default** — всегда короткие (макс 48 символов, обычно < 15). Им не нужно много места.
2. **Description** — основная колонка. 55% значений > 50 символов, 25% > 100. Ей нужна бОльшая часть ширины.
3. **Constraints** — есть только у 32% параметров (247 из 775). Длинные regex (> 100 символов) — исключение (у mariadb, clickhouse, postgres). Не нужно раздувать колонку ради 6% случаев — хватит `word-break: break-all`.
4. **Default** — есть у 64% параметров, всегда короткий (AVG 4 символа).

---

## Оптимальные ширины колонок

Используется `table-layout: fixed` — браузер жёстко соблюдает проценты.

### Основная таблица (`.resource-table:not(.resource-table-nested)`)

5 или 6 колонок: ID | Code | Type | (Default) | Description | Constraints

| Колонка | CSS-селектор | Ширина | Примечание |
|---|---|---|---|---|
| ID | `nth-child(1)` | 3% | |
| Code | `nth-child(2)` | 15% | |
| Type | `nth-child(3)` | 7% | |
| Default | авто | авто | только если есть (6 колонок) |
| Description | `nth-last-child(2)` | 48% | **главная колонка** |
| Constraints | `nth-last-child(1)` | 27% | `word-break: break-all` |

### Nested-таблица (`.resource-table-nested`)

7 колонок: ID | Code | Type | Required | Default | Description | Constraints

| Колонка | CSS-селектор | Ширина | Примечание |
|---|---|---|---|---|
| ID | `nth-child(1)` | 3% | |
| Code | `nth-child(2)` | 12% | |
| Type | `nth-child(3)` | 7% | |
| Required | `nth-child(4)` | 5% | |
| Default | `nth-child(5)` | 7% | |
| Description | `nth-child(6)` | 38% | **главная колонка** |
| Constraints | `nth-child(7)` | 28% | `word-break: break-all` |

---

## Принцип

> Если поле широкое только в 5% случаев — не надо рисовать его широким для всех.
> Description — всегда широкий. Constraints — редко широкий, пусть ломается.