docs: дизайн таблиц, ответы Соннета, CSS, правила без ВМ

2026-07-18 08:37:19 +03:00
parent 6beac52e92
commit ea3e53849d
7 changed files with 555 additions and 77 deletions
@@ -0,0 +1,132 @@
+# Анализ ширины колонок таблиц документации
+
+> Методика определения оптимальных ширин колонок на основе реальных данных из 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 — редко широкий, пусть ломается.