arm-ka-fixtures/synthgen/README.md

synthgen — настраиваемый генератор синтетической ГСК

Строит вымышленный набор для АРМ КА: состав группы (ЕЦП), ОСВ по счетам, ББ и ОФР по компаниям и периодам. Все числа выведены из одной двойной записи на компанию (книга проводок), поэтому ББ, ОФР и ОСВ согласованы между собой. Назначение — объём и демо (десятки компаний, до 150 внешних контрагентов в ОСВ); это не оракул: ожидаемых итогов консолидации генератор не даёт. Проект: docs/superpowers/specs/2026-11-12-synthgen-design.md.

Запуск

uv run --with openpyxl==3.1.5 --with pyyaml==6.0.2 python -m synthgen \
    --config synthgen/examples/default.yaml --set group_size=12 --set prefix=DEMO2 --out /tmp/demo2

Из корня репозитория fixtures. Без --out результат — ./out/<prefix>. Непустой каталог без --force — код 3; --force очищает его содержимое целиком. Код 2 — ошибка настроек. Тесты: python -m pytest synthgen/tests -q (-m parser — приёмка парсером, нужен TP_WT; -m slow — крупный прогон).

Настройки

Любой ключ переопределяется --set ключ=значение; неизвестный ключ или значение вне диапазона — ошибка.

Ключ	Смысл	По умолчанию	Диапазон
group_size	число компаний в ГК (все входят в ГСК)	5	2–40
prefix	префикс ГК: в названиях и диапазон ИНН	SYN	2–12 букв/цифр
periods	число отчётных периодов	4	1–12
start	первый период	2025-Q1	2020-Q1 … 2030-Q4
osv_counterparties_mean	среднее число внешних контрагентов в одной ОСВ	60	0–150
no_inn_companies	сколько компаний выгружают ОСВ без ИНН	1	0–group_size
vgo_mismatch_share	доля пар ВГО с расхождением	0.1	0–1
seed	зерно случайности	1	целое
out	каталог результата	./out/<prefix>	—

Одинаковые настройки и seed дают побайтно одинаковые файлы (путь результата в файлы не попадает).

Что получается

<out>/
  README.md                       журнал прогона: настройки, состав группы, пары ВГО с расхождениями, контрагенты
  config.yaml                     фактические настройки
  directories/ecp-<prefix>.xlsx   выгрузка ЕЦП: состав ГК
  osv/<КОД>/<период>/сч NN_….xlsx ОСВ по счетам 01, 58, 60, 62, 66, 67, 76, 80, 90
  statements/<КОД>/<период>/      ББ_….xlsx и ОФР_….xlsx (форма 66н, тыс. руб.)

<КОД> — C01…Cnn, головная — C01; периоды — нарастающим итогом с 1 января (2025-Q1, 2025-Q2, 2025-Q3, 2025-FY). Набор сам в git не коммитится (out/ в .gitignore).

Как загрузить на стенд

1. Импорт ЕЦП: directories/ecp-<prefix>.xlsx (справочник групп и юрлиц).
2. Документы по компаниям: ОСВ, затем ББ и ОФР из osv/<КОД>/… и statements/<КОД>/…. Компании без ИНН в ОСВ и пары ВГО с расхождениями перечислены в README набора.

Ограничения

• Не оракул; только форма 66н (ФСБУ 4/2023 не покрыта).
• Среднее число контрагентов ограничено словарём (≤ 150): при потолке README набора пишет «среднее ограничено словарём».
• ИНН компаний группы берутся из диапазона по хешу префикса; два префикса могут столкнуться (малая вероятность).
• Выручка 90.01 в ОСВ без аналитики по контрагентам; счёт 80 головной без аналитики; подпись «За 3 месяца» в ОФР не сверена с реальной выгрузкой первого квартала; внешние 58.03 и 76.05 только по Кт не проверялись на ядре.
• Побайтная воспроизводимость — в пределах одной платформы (float в весах и масштабах).
• Как ядро увидит расхождения (торговля и заём выше 5 % — нераспределённые строки MULTIPLE_RULES, до 5 % — автоматически), какие особенности у данных и как прочитать пары — в README каждого прогона.
• --force чистит только каталог, который узнаёт как набор synthgen (config.yaml и README с заголовком набора), и отказывает при .git в каталоге.

Как пересобрать словарь и шаблоны

• Словарь организаций: python -m synthgen.dictionary.build → synthgen/dictionary/companies.csv (коммитится).
• Стиль ОСВ: python synthgen/templates/build_osv_style.py → osv_style.json; шаблоны ББ/ОФР: python synthgen/templates/build_forms_templates.py → bb_1c.xlsx, ofr_1c.xlsx. Образцы — из этого же репозитория (osv/rb/2024-Q1, statements-xlsx/mezheninovskaya/2025-Q3), путь можно передать аргументом; реквизитов образца в шаблонах нет.