architect/_archive/2026-04-11/standards-old/data/data-session-standard.md

DataSession — стандарт обработки данных

Стандарт описывает механизм воспроизводимой обработки данных:
как открыть сессию, записывать шаги, откатываться и повторять обработку.

Суть

DataSession — компонент платформы для обработки данных.

Каждый раз когда начинается обработка данных (загрузка, трансформация, экспорт) — открывается сессия. Сессия:
- создаёт рабочую папку
- ведёт журнал шагов (journal.yaml)
- сохраняет состояние после каждого шага
- позволяет откатиться на любой шаг
- позволяет повторить обработку по журналу (replay)

Структура сессии

sessions/
  {project}-{YYYY-MM-DD}-{NNN}/
    session.yaml     ← метаданные: проект, режим, статус, шаги
    journal.yaml     ← последовательность: action / params / result
    source/          ← исходные данные как пришли (CSV, XML, JSON)
    export/          ← результат (feed.xml, CATALOG.csv, ...)
    data.db          ← рабочий SQLite (всегда текущее состояние)
    data.sql         ← только в режиме git (SQL-дамп, в git ✅)
    data_01.db       ← только в режиме files (снепшот шага 1)
    data_02.db       ← только в режиме files (снепшот шага 2)
    ...

Папка сессии находится внутри проекта: projects/org/{project}/sessions/

Два режима хранения шагов

При старте сессии выбирается режим:

Режим git

Один файл data.sql — перезаписывается после каждого шага. История хранится в git-коммитах.

data.db     ← рабочий SQLite (в .gitignore)
data.sql    ← SQL-дамп (в git ✅)

После каждого шага:

sqlite3 data.db .dump > data.sql
git add data.sql journal.yaml session.yaml
git commit -m "step_NN: {action} — {result}"

Откат на шаг 2:

git checkout step_02 -- data.sql
sqlite3 data.db < data.sql

Когда использовать: данные до ~100k строк, важен читаемый diff в git.

Режим files

Отдельный .db файл на каждый шаг. Можно открыть любой шаг в GUI (DBeaver, TablePlus).

data.db       ← рабочий SQLite (текущее состояние)
data_01.db    ← снепшот после шага 1
data_02.db    ← снепшот после шага 2
data_03.db    ← снепшот после шага 3

После каждого шага:

cp data.db data_{NN}.db

Откат на шаг 2:

cp data_02.db data.db

Когда использовать: нужно визуально смотреть данные на каждом шаге в GUI.

Формат шага в journal.yaml

steps:
  - id: 01
    action: load_source
    params:
      file: source/CATALOG.csv
      encoding: utf-8
    result:
      rows: 18304
      tables: [parts, models]
    status: done
    timestamp: "2026-04-05T04:00:01"

  - id: 02
    action: filter_duplicates
    params:
      key: oem
    result:
      removed: 142
      rows: 18162
    status: done
    timestamp: "2026-04-05T04:00:05"

  - id: 03
    action: translate
    params:
      dictionary: parts-dictionary
    result:
      translated: 9212
      unknown: 0
    status: done
    timestamp: "2026-04-05T04:00:18"

Формат session.yaml

id: lideravto-2026-04-05-001
project: lideravto-new
mode: git          # git | files
status: done       # open | running | done | failed
started: "2026-04-05T04:00:00"
finished: "2026-04-05T04:01:42"
steps_total: 4
steps_done: 4
export:
  - export/CATALOG_OEM.csv
  - export/feed.xml

Replay — повтор обработки

Берём journal.yaml из прошлой сессии → запускаем на новых исходных данных:

python session.py replay \
  --journal=sessions/lideravto-2026-04-05-001/journal.yaml \
  --source=source/CATALOG_new.csv

Компонент прогоняет те же шаги с теми же параметрами → новая сессия с новыми данными.

Расположение в платформе

architect/standards/data/
  data-session-standard.md     ← этот файл (стандарт)

library/
  @data.session/               ← реализация компонента
    session.py                 ← открыть / закрыть / статус
    journal.py                 ← записать шаг
    git_backend.py             ← dump → commit → rollback (режим git)
    files_backend.py           ← cp snapshot (режим files)
    replay.py                  ← повтор по journal.yaml
    CLI                        ← python session.py start|step|rollback|replay

Gitignore для сессий

# DataSession — рабочие файлы не в git
sessions/**/data.db
sessions/**/data_*.db

# DataSession — в git только для режима git
# sessions/**/data.sql  ← НЕ игнорировать

Версия

Версия Дата Изменение
1.0 2026-04-05 Первая версия — два режима git/files