From 7d652485bd66a2eceb35cf9f5039855d52051319 Mon Sep 17 00:00:00 2001
From: FazziCLAY <fazziclay@gmail.com>
Date: Wed, 15 Oct 2025 15:08:33 +0300
Subject: [PATCH] add scheme doc

---
 vstu_parser_result_scheme.json | 81 ++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 vstu_parser_result_scheme.json

diff --git a/vstu_parser_result_scheme.json b/vstu_parser_result_scheme.json
new file mode 100644
index 0000000..3db3d63
--- /dev/null
+++ b/vstu_parser_result_scheme.json
@@ -0,0 +1,81 @@
+{
+	"actual_at": "0", // unix seconds когда было распарсено это расписание
+	"notice": "LEGAL INFORMATION HERE", // legal information
+	"stat": {
+		"total_parsing_time": 100.11 // сколько занял процесс парсинга от запуска программы (сек)
+	},
+	"version": "1", // версия = 1
+	"excels": [ // список всех эксель файлов которые были обработаны.
+		{
+			"filename": "эксель как на сайте.xls",
+			"url": "https://internet./path/to/эксель как на сайте.xls", // откуда парсер скачал
+			"download_place": "excels/temp.xls", // куда парсер скачал
+			"group_names_parsed": [""], // список названий групп которые удалось достать с этого файла
+			"facultet": "mag", // english name of facultet к которому относится этот эксель документ
+			"stat": {
+                "download": 0.314, // сколько скачивалось (сек)
+                "create_reader": 0.03, // сколько создавался Reader (сек), обычно у .xlsx это от нескольких секунд до минуты, а у .xls десятые доли секунды.
+                "parse": 0.00, // сколько парсился (сек)
+                "cycles": 2 // сколько парсер сделал циклов: по факту - сколько страниц в эксель файле
+			},
+			
+			// дальше optional
+			"parser_error_cycle_1": "string desk from Parser", // _1 номер цикла. не больше stat.cycles
+			"error": {"...":"..."} // исключение в коде
+		}
+	],
+	
+	"groups": { // список групп с данными о них
+		"имя-группы": {
+            "name": "имя-группы",
+            "position_human": "G6:J6", // range ячейки-заголовка группы в эксель таблице.
+            "slots": { // слоты - расписание этой группы на 2 недели
+			
+				// важно если у группы нету например занятий в первый понидельник то и ключа не будет. => если у группы нету занятий вообще то slots = {} (пустому словарю)
+			
+				// день определённой недели
+				// ключ - имя дня недели + (_1 OR _2 в зависимости от недели). Не полагайтесь на этот ключ, т.к. в каждой паре есть weekday (1-7) и weeknum (1-2).
+				// значение - список пар на этот день
+                "ПОНЕДЕЛЬНИК_1": { 
+                    "1-2": { // ключ - название времени пары (1-2, 2-3, 3-4 etc...), значение - информация о паре (о дисциплине в это время)
+                        "excel_pos": "G7", // позиция в экселе
+                        "discipline_name": "Великое знание российское", // название дисциплины (не всегда корректное)
+                        "locations": [ // список локаций (не всегда корректный)
+                            "В 1204"
+                        ],
+                        "leads": [ // список лидеров (спикеров, вообщем преподователей) (не всегда корректный)
+                            "Бадикова П.В."
+                        ],
+                        "is_solid": true, // единая ли верхняя ячейка (т.е. ширина 4 колонки и она объединена в одну)
+                        "time_coeff": 2, // по сути сколько пар длится пара. Тоесть если >1 то длится больше одной пары. Почти всегда 1, иногда 2. В редких случаях (химия) 3 :dead: соболезную трудящимся
+                        "is_flow": false, // потоковая? определяется если ширина объединённой ячейки больше 4 (а 4 это размер колонки группы). 
+                        "lefttopmerged": { // частично отладочная информация, как раз о объединённой ячейке взятой как тык пальцем в верхнюю левую ячейку.
+                            "width": 4,
+                            "height": 2,
+                            "excel_range": "G7:J8" // её range в экселе
+                        },
+                        "raw": [ // сырые данные. Содержание всех не пустых ячеек этой записи о паре.  (SET data structure)
+                            "Великое знание российское",
+                            "В 1204б,лунатутможетбытьчтоугодно",
+							"даты и т.д. всё что там есть будет тут",
+                            "практ. 4 час.",
+                            "Преподов П.П."
+                        ],
+                        "weekday": 1, // день недели 1- понидельник, 7 - воскр..
+                        "weeknum": 1, // номер недели 1- первая 2-вторая.
+						
+						// дальше optional
+						"pair_num_empty": {"..": "...", "restored": true}, // составители расписания лучшие и в макете забыли сбоку добавить [1-2] номер пары. Если restored=true то это недоразумение удалось исправить опираясь на предыдущую пару.
+						"to_many_parsing_time_coeff": true // если при попытке определить time_coeff, а он определяется по границам (borders) в эксель таблице, произошла ошибка (подавленный infinity loop)
+						
+					}
+				}
+			},
+			"facultet": "mag", // факультет группы
+			"data_source": "эксельтаблица.xls" // название таблицы откуда были получены данные о этой группе
+		}
+	}
+	
+	// безусловно перечислено не всё, но многое излишне.
+	// 		~ Stanislav Mironov
+}
\ No newline at end of file