Скрипт звіту report.sh: агрегація даних і дашборд

Що робимо сьогодні

У ~/data/leads.jsonl уже лежать справжні заявки з твоєї форми. Сьогодні вони перетворюються на дашборд — і головна робота не в тому, щоб порахувати, а в тому, щоб порахувати й нічого не винести назовні.

Чого навчишся за цей урок

• рахувати заявки просто в терміналі: скільки всього і скільки з кожного класу;
• написати скрипт, який збирає ці числа у файл report.json;
• прибирати зі звіту імена й адреси, щоб назовні пішли самі цифри;
• ховати надто малі групи, щоб «четверо з 10C» не стало конкретним прізвищем;
• роздати файлам права так, щоб звіт бачили всі, а вихідні дані — тільки ти.

Слова «агрегація», «атомарний запис» та «ідемпотентність» поки нічого не означають. Розберемо їх по черзі, кожне на своєму місці.

З теми 2 у тебе вже є приймач. Він дописує рядок у ~/data/leads.jsonl щоразу, коли хтось заповнює форму. Файл лежить поза ~/www/. Саме тому за посиланням його ніхто не відкриє.

Сьогодні ти вперше береш дані з приватної частини й кладеш результат у публічну. Межу між ними проводиш ти сам. Скрипт ~/bin/report.sh читає файл з іменами й адресами, а віддає report.json із самими числами.

Кожен зайвий ключ у цьому JSON бачить будь-хто у світі. Тому за кожне поле звіту доводиться відповідати окремо.

Що поїде на сервер

Хід уроку

Одна межа, яку сьогодні проводиш ти

Дані для звіту приватні. Сам звіт публічний. Між ними — рівно один файл, який ти пишеш власноруч

На уроці 3 ти вже клав leads.jsonl поза ~/www/. Тоді за все відповідав сервер: чого немає у веб-корені, того для браузера не існує.

Сьогодні захист інший — твій власний код. Скрипт має право читати приватний файл. Він же має право писати в публічну теку. Що саме перетече через нього, вирішує вже не сервер, а ти.

Запис і агрегат — різні речі

Уяви класний журнал. Один рядок у ньому — це одна людина: прізвище, оцінки, пропуски. А середній бал класу — уже не про людину. Він про всіх разом, і за ним нікого не впізнати.

З нашим файлом так само. Рядок leads.jsonl стосується однієї людини: там ім'я, адреса, текст повідомлення. Число "10A": 22 не стосується нікого окремо.

Перетворення записів на такі спільні числа зветься агрегацією. Саме тут і проходить межа між приватним і публічним.

Читаємо JSONL із bash: чотири інструменти

Кожен рядок файлу — окремий валідний JSON. Саме тому звіт можна порахувати командами, а не програмою

Формат JSON Lines зроблений так, щоб його можна було читати рядок за рядком і дописувати в кінець без переписування файлу. Одна заявка — один рядок, розділювач — \n. Ніяких ком між об'єктами і жодних квадратних дужок навколо.

{"ts":"2026-08-30T09:14:07+00:00","name":"Оля","email":"olia@example.com","class":"10A","message":"Хочу в гурток робототехніки"}
{"ts":"2026-08-30T09:16:31+00:00","name":"Тарас","email":"taras@example.com","class":"10B","message":""}
{"ts":"2026-08-30T09:22:04+00:00","name":"Ніна","email":"nina@example.com","class":"10A","message":"Чи потрібен свій ноутбук?"}

1. Скільки всього: wc -l і його пастка

wc -l рахує не рядки, а символи переводу рядка. Різниця вилазить на останньому записі. Приймач міг упасти на півдорозі й не дописати \n у кінці.

Тоді запис на диску є, а перевід рядка після нього — ні. Ти побачиш 46 замість 47 і нічого не запідозриш. Команда, яка рахує чесно:

Порожній шаблон '' збігається з будь-яким рядком, а grep рахує саме рядки, а не переводи. Різниця між двома командами — це і є твій зіпсований останній запис.

2. Дістати поле: jq

jq — це grep для JSON. Ключ -r віддає рядок без лапок, щоб його можна було передати далі по конвеєру.

3. Порахувати повторення: sort | uniq -c

uniq склеює тільки сусідні однакові рядки. Без sort перед ним ти отримаєш той самий клас у кількох групах.

Це та сама команда, якою ти звіряєш звіт руками. У скрипт іде інша — та, що одразу дає готовий JSON:

Ця команда робить чотири кроки поспіль. Ключ -s (від slurp, «сьорбнути») читає весь файл одразу й складає рядки в один масив. Без нього jq обробляв би кожен рядок окремо й не зміг би їх порівняти.

Далі group_by розкладає масив на купки за значенням поля. Усі заявки з 10A — в одну купку, з 10B — в іншу. Порахувати їх поки ніхто не просив.

Потім map({(.[0].class): length}) проходить по кожній купці й лишає від неї два значення: назву класу і length — скільки в ній заявок. Самі заявки на цьому кроці зникають.

Нарешті add зсипає ці дрібні об'єкти в один. Саме він і поїде у звіт.

4. Порахувати число: awk

Коли потрібна сума або середнє, а не кількість, рахує awk. Він читає потік рядок за рядком, накопичує в змінних і друкує підсумок у блоці END.

Зверни увагу: жоден символ самого повідомлення сюди не потрапив. Лишилася тільки його довжина. Ось як виглядає агрегація на практиці: текст стає числом якнайраніше, ще всередині конвеєра.

set -euo pipefail: три літери проти тихих поломок

За замовчуванням bash не зупиняється на помилці. Він іде далі й доводить справу до кінця — навіть якщо всі числа вже нулі

Скрипт без цього рядка поводиться так. Команда впала, він написав щось у stderr і перейшов до наступної. Так само з другою, третьою і п'ятою.

На виході ти маєш report.json, де все на місці, крім змісту. Дашборд покаже нулі. А ти шукатимеш помилку в дашборді — і не знайдеш, бо він ні до чого.

Скрипт по блоках

Каркас, який ти дописуєш під свої дані

Цей код можна згенерувати з Antigravity — але вчитель попросить пояснити будь-які три рядки. Тому читай зараз, а не на перевірці.

#!/usr/bin/env bash
# ~/bin/report.sh — рахує числа з приватних даних і кладе їх у публічну теку
set -euo pipefail

# 1. шляхи тільки абсолютні: з cron поточна тека буде іншою
SRC="$HOME/data/leads.jsonl"
OUT_DIR="$HOME/www/dash"
OUT="$OUT_DIR/report.json"

# 2. перевірки до першого підрахунку, кожна зі своїм кодом виходу
command -v jq >/dev/null || { echo "report.sh: немає jq" >&2; exit 3; }
[ -r "$SRC" ]            || { echo "report.sh: не читається $SRC" >&2; exit 4; }
mkdir -p "$OUT_DIR"

# 3. агрегація: у змінних лише числа, жодного імені й жодної адреси
total=$(grep -c '' "$SRC" || true)
unique_people=$(jq -r '.email' "$SRC" | sort -u | wc -l)
with_message=$(jq -s '[.[] | select((.message // "") != "")] | length' "$SRC")
avg_msg_len=$(jq -r '.message | length' "$SRC" \
              | awk '{s+=$1; n++} END {printf "%.1f", (n ? s/n : 0)}')
by_class=$(jq -s 'group_by(.class)
                  | map({(.[0].class // "не вказано"): length}) | add' "$SRC")
by_day=$(jq -s 'map(.ts[0:10]) | group_by(.)
                | map({(.[0]): length}) | add' "$SRC")

# 4. збираємо JSON у тимчасовий файл ПОРУЧ із робочим
TMP=$(mktemp "$OUT_DIR/.report.XXXXXX")
trap 'rm -f "$TMP"' EXIT

jq -n \
  --arg     generated_at  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson total         "$total" \
  --argjson unique_people "$unique_people" \
  --argjson with_message  "$with_message" \
  --argjson avg_msg_len   "$avg_msg_len" \
  --argjson by_class      "$by_class" \
  --argjson by_day        "$by_day" \
  '{generated_at:$generated_at, total:$total, unique_people:$unique_people,
    with_message:$with_message, avg_msg_len:$avg_msg_len,
    by_class:$by_class, by_day:$by_day}' > "$TMP"

# 5. права ДО підміни, інакше сторінка секунду віддає 403
chmod 644 "$TMP"
mv "$TMP" "$OUT"
trap - EXIT

echo "report.sh: $total записів → $OUT"

Мінімізація: у звіт іде тільки те, без чого звіту немає

Правило перевірки одне: чи не соромно вивести цей рядок report.json на проєктор перед усією школою

Це не фігура мови. report.json лежить у веб-корені з правами 644. Його адресу відкриє з телефона будь-хто, хто її знає.

А знати її неважко: посилання на файл стоїть прямо в коді дашборду. Тож публічний звіт і публічний проєктор — це буквально одне й те саме.

Агрегація — дорога в один бік

Поріг: від скількох людей можна показувати групу

Магічної цифри тут немає. Статистичні служби публікують таблиці про людей щодня. Клітинку, у якій менше 5 або 10 спостережень, вони зазвичай не показують.

Замість неї ставлять зведений рядок або прочерк. Логіка проста: чим менша група, тим легше вгадати, хто саме в ній.

У нашому випадку «додаткові знання» — це вся школа. Якщо в звіті написано "10C": 1, то будь-хто з 10C, хто чув розмову на перерві, знає прізвище. Тому в скрипті ставлять поріг:

# групи від 5 осіб показуємо як є, решту зводимо в «інші»
by_class=$(jq -s --argjson min 5 '
  group_by(.class)
  | (map(select(length >= $min) | {(.[0].class): length}) | add // {}) as $big
  | (map(select(length <  $min) | length) | add // 0)              as $small
  | $big + (if $small > 0 then {"інші": $small} else {} end)
' "$SRC")

На нашому наборі {"10A":22,"10B":21,"10C":4} стає {"10A":22,"10B":21,"інші":4}. Сума не змінилася: 47 лишається 47. Зник тільки рядок, який називав чотирьох людей з маленького класу.

Оператор // у коді страхує від порожнечі. Якщо великих груп немає взагалі, add поверне null. Тоді // {} підставить порожній об'єкт, і скрипт не впаде.

Конструктор звіту

Обираєш показники — сторінка пише за тебе bash і одразу показує, який report.json із цього вийде і що з нього побачить сторонній

Набір даних тут демонстраційний і зашитий у сторінку: 47 заявок, 43 різні адреси, класи 10A / 10B / 10C. Код, який видає конструктор, — справжній: його можна вставити у свій report.sh і замінити назви полів на свої.

Чому report.sh — це 700

У скрипті немає паролів. У ньому є дещо цінніше — карта: де лежать дані, як вони називаються і що в них усередині

Твій сервер не належить тобі одному. Це гуртожиток: у теці /home/ лежать десятки чужих домашніх тек. Усі ці люди залогінені на ту саму машину, що й ти.

Права 755 означають одне: кожен із них прочитає твій файл. Не через інтернет, а просто командою cat, не встаючи зі свого місця.

Ставимо й перевіряємо

Аудит прав: що зламається і що витече

Нижче — шість файлів твого проєкту в тому стані, у якому їх зазвичай лишає FTP-клієнт. Постав кожному права й дивись на наслідок

Помилки тут бувають двох протилежних сортів. Занадто суворі права ламають те, що мало працювати: веб-сервер не читає звіт, cron не запускає скрипт.

Занадто вільні віддають чужим те, що мало лишитися твоїм. Тому правильний набір — не «якнайменше», а «рівно стільки, скільки потрібно кожному учаснику».

Атомарний запис: тимчасовий файл і mv

Поки твій скрипт пише звіт, дашборд може його читати. Це не гіпотеза — це кожен запуск

Уяви, що стираєш дошку й пишеш на ній нове оголошення. Хвилину дошка напівпорожня. Хто зайде саме тоді, прочитає половину фрази й піде.

Команда jq … > report.json робить рівно те саме. Оболонка спершу обнуляє файл, а потім наповнює його по частинах. Між цими двома моментами на диску лежить обрізаний JSON.

Хто відкриє дашборд у цю мить, отримає помилку розбору. Виглядає це як випадковий глюк, а насправді трапляється при кожному запуску.

Чому mv — це одна дія

Тому оголошення пишуть на аркуші за столом, а на дошку вішають уже готовим. Обмін займає секунду, і напівпорожньої дошки ніхто не бачить. Це і зветься атомарним записом: дія або сталася повністю, або не сталася зовсім.

Перейменування файлу в межах однієї файлової системи — це системний виклик rename(). Ядро гарантує ось що. У будь-яку мить ім'я report.json веде або на старий файл цілком, або на новий цілком. Стану «наполовину» не існує в принципі.

Ідемпотентність: два запуски — один результат

Запусти скрипт двічі, нічого не міняючи в даних. Звіт має вийти той самий, до останнього числа. Якщо так — скрипт ідемпотентний.

Найчастіші причини, чому цього не стається:

• >> замість > — числа не замінюються, а дописуються, і файл швидко перестає бути валідним JSON;
• скрипт читає старий report.json і додає до нього — метрики ростуть при кожному запуску без жодних нових заявок;
• скрипт дописує рядок у leads.jsonl «для перевірки» — джерело даних скрипт звіту не змінює ніколи.

Перевірка займає три команди. Поле generated_at міняється завжди — його з порівняння прибирають:

jq -S сортує ключі, щоб diff не спрацював на різному порядку полів. Порожній вивід diff і слово «ідемпотентно» — це і є критерій idempotent.

Дашборд: сторінка, яка нічого не рахує

Уся арифметика вже сталася на сервері. Сторінці лишається прочитати шість чисел і намалювати з них картинку

Це і є розподіл праці, заради якого існує report.sh. Сторінка не має доступу до leads.jsonl — і не потребує його. Вона тягне report.json вагою в кілька сотень байтів, тому відкривається миттєво навіть із телефона на поганому зв'язку.

fetch('report.json', {cache: 'no-store'})
  .then(r => r.ok ? r.json() : Promise.reject('HTTP ' + r.status))
  .then(d => {
    document.getElementById('total').textContent = d.total;
    document.getElementById('uniq').textContent  = d.unique_people;
    // час беремо зі звіту, а не з годинника відвідувача
    document.getElementById('upd').textContent =
      new Date(d.generated_at).toLocaleString('uk-UA');
    drawBars(d.by_class);          // твій SVG, як на уроці 6
  })
  .catch(e => {
    document.getElementById('err').textContent = 'звіт недоступний: ' + e;
  });

Практика: пишемо report.sh

Кроки 1—9 робиш у себе на комп'ютері й у терміналі, кроки 10—15 — на сервері. Галочки зберігаються

Автоперевірка

Чекер запускає твій скрипт двічі, порівнює звіти, дивиться на права й шукає в публічному JSON те, чого там не має бути. Спроби не обмежені

Демонстраційний режим: результат згенеровано для показу. На сервері ця кнопка викликає POST /api/check, який запускає /opt/lessons/09/check.sh від імені учня.

Що вчитель дивиться на твоєму екрані

• ти запускаєш bash -x ~/bin/report.sh і пояснюєш своїми словами будь-які три рядки з тих, що вивів трасувальник — включно з тими, які згенерував Antigravity;
• називаєш число з дашборду й тут же показуєш команду, яка дає це саме число з leads.jsonl;
• відкриваєш report.json і пояснюєш, чому там немає жодного поля з leads.jsonl у первісному вигляді;
• показуєш stat -c %a на скрипті, даних і звіті — і кажеш, чому саме такі цифри;
• кажеш, який поріг малих груп у тебе стоїть і чому саме такий.

Шкала виконання

Це те, що бачить учитель, коли виставляє оцінку.

П'ять речень, які варто запам'ятати

• межу між приватним і публічним тримає не сервер, а твій скрипт — сервер лише виконує те, що ти написав;
• агрегація незворотна: з числа 22 не дістати 22 імені, і саме тому публікують числа, а не записи;
• маленька група — це знову людина, тому в звіті стоїть поріг;
• mv у межах однієї файлової системи — одна дія ядра, і тільки тому дашборд ніколи не бачить недописаного файлу;
• права 700 на скрипт ховають не пароль, а карту: де дані, як називаються поля, коли все це запускається.

Де найчастіше помиляються

• скрипт дописує в старий report.json замість перезапису — числа ростуть при кожному запуску;
• шлях записаний відносно (data/leads.jsonl) — з cron скрипт не знайде файл;
• забутий chmod 644 на тимчасовому файлі — після mv звіт лишається 600, і дашборд отримує 403;
• у звіт «на секунду» додали масив імен і забули прибрати;
• AI-коментар суперечить цифрам, бо його згенеровано до перерахунку;
• report.json залито по FTP руками — числа на сторінці живуть окремим життям від даних;
• скрипт залито по FTP одразу в ~/bin/, права лишилися від FTP-клієнта — критерій script_perms червоний.

Домашнє завдання

Додай до дашборду четверту метрику — таку, якої в каркасі ще немає. Поясни її в README.md двома абзацами. Перший: що вона показує і чим корисна саме тобі.

Другий абзац — чому вона нікого не називає. Він обов'язковий. Якщо пояснити не виходить, це сигнал: метрика небезпечна.

Потім перевір поріг. Постав його на 3, на 5 і на 10. Подивись, як щоразу міняється твій by_class, і запиши в README.md, яке число ти обрав і чому.

Звідки взяті твердження й команди

Кожну команду з цієї сторінки можна перевірити в документації, а більшість — просто набрати в терміналі

• Формат JSON Lines — один валідний JSON на рядок, розділювач \n, кодування UTF-8. jsonlines.org
• jq: group_by, --arg і --argjson, ключ -s, оператор //, -n, -S — офіційний посібник. jqlang.github.io/jq/manual
• set -e, set -u, set -o pipefail — розділ «The Set Builtin» посібника GNU Bash. gnu.org/software/bash
• Чому set -e не завжди робить те, чого від нього чекають — розбір випадків, зокрема команд, для яких ненульовий код нормальний. mywiki.wooledge.org/BashFAQ/105
• Код виходу grep: 0 — знайдено, 1 — не знайдено, 2 — помилка. Саме тому grep -c на порожньому файлі валить скрипт із set -e. gnu.org/software/grep
• Атомарність перейменування — rename(2): «If newpath already exists, it will be atomically replaced». Гарантія діє в межах однієї файлової системи. man7.org · rename(2)
• mktemp — створення тимчасового файлу за шаблоном з XXXXXX; файл створюється з правами 600. man7.org · mktemp(1)
• trap на EXIT — прибирання за собою незалежно від того, чим скінчився скрипт. gnu.org/software/bash · Signals
• Права доступу у вісімковому вигляді — chmod, stat; на macOS stat -f %A замість stat -c %a. man7.org · chmod(1), man7.org · stat(1)
• Мінімізація даних — принцип «адекватні, доречні та обмежені тим, що необхідно»: GDPR, ст. 5(1)(c). В українському праві той самий принцип — ст. 6 Закону «Про захист персональних даних». gdpr-info.eu/art-5-gdpr, zakon.rada.gov.ua · 2297-17
• Придушення малих клітинок у публічних таблицях — практика статистичного контролю розкриття: клітинки з малим числом спостережень не публікують окремо. Eurostat · Statistical Disclosure Control
• k-анонімність — L. Sweeney, «k-Anonymity: A Model for Protecting Privacy», 2002: запис має бути невідрізненний щонайменше від k−1 інших. dataprivacylab.org
• fetch і параметр cache — чому no-store обов'язковий для файлу, який перезаписується під тим самим іменем. MDN · Request.cache
• Googlebot виконує JavaScript — сторінка рендериться, і запити, які робить її код, теж стають відомими сканеру. Тому «на цей файл ніде немає посилання» не є захистом. developers.google.com/search
• Безпека через незрозумілість — чому прихована адреса не є механізмом захисту. OWASP · Secure Product Design
• date -u +%Y-%m-%dT%H:%M:%SZ і формат ISO 8601 / RFC 3339 — час у звіті записується в UTC. datatracker.ietf.org · RFC 3339

Повний список із поясненнями, що звідки взято, — у файлі urok-09-джерела.md поруч із цією сторінкою.