ITD Transport Tracking – пълно ръководство

Приложение за проследяване на транспортни средства (камиони) по постове: четене на QR карта, регистрация на преминаване през постове, генериране на карти и администрация на картите. Работи с база данни SQL Server и може да се ползва като Python скрипт или като преносимо EXE.

---

1. Какво прави приложението

• Регистрация по пост – при четене на QR код на карта се записва преминаване през следващия пост (1→2→3→4→5).
• Пет поста: Портал (паркинг) → Вход в завода → Рампа начало товарене → Рампа край товарене → Напускане.
• Таблица с цикли – показва всички цикли с време за всеки пост и изход; поддържа филтър по номер на карта.
• Служебно затваряне на цикъл – ако липсва регистрация на последен пост, цикълът може да се затвори ръчно със „Служебен изход“ (и после отмяна на служебния изход).
• Модул „Карти“ – списък на карти, корекция на текст (име + № кола), активиране/деактивиране, генериране на QR карта, отпечатване на карта като PNG.

Иконата на приложението е ITD.ico (квадратна, без допълнително преобразуване).

---

2. Изисквания

• Python 3.8+ (при ползване като скрипт).
• SQL Server – база данни с таблиците ITD_Cards и ITD_Cycles (схемата се прилага автоматично при първо стартиране от schema.sql).
• ODBC Driver 17 for SQL Server (или съвместим) на машината.
• За изграждане на EXE: PyInstaller (pip install pyinstaller).

---

3. Първоначална настройка

3.1 Файлове в папката на проекта

Файл	Описание
main.py	Основно приложение (екран с регистрация, цикли, бутони).
db.py	Връзка към БД и операции с карти/цикли.
db_check.py	Проверка за достъп до БД и прилагане на schema.sql.
schema.sql	SQL схема – таблици ITD_Cards, ITD_Cycles.
appsettings.json	Задължителен – connection string към SQL Server (не се комитва в Git).
appsettings.example.json	Пример; копирайте като appsettings.json и попълнете данните.
ITD.ico	Икона на приложението (прозорец и EXE).
start.bat	Стартиране в режим разработка (проверка БД + main.py).
build.bat	Изграждане на преносимо EXE.
requirements.txt	Python зависимости: pyodbc, qrcode[pil].

3.2 Настройка на връзката към базата данни

1. Копирайте appsettings.example.json като appsettings.json в същата папка.
2. Отворете appsettings.json и попълнете connection string:

{
  "ConnectionStrings": {
    "SqlServer": "Server=ВАШИЯ_СЪРВЪР;Database=ITD;User Id=ПОТРЕБИТЕЛ;Password=ПАРОЛА;TrustServerCertificate=true"
  }
}

• Server – име или адрес на SQL Server инстанцията.
• Database – име на базата (напр. ITD).
• User Id / Password – потребител с права за създаване на таблици и четене/запис.
• TrustServerCertificate=true – обикновено нужен при самоподписан сертификат.

Алтернативно можете да използвате Odbc ключ в ConnectionStrings с пълен ODBC connection string, ако не ползвате SqlServer формата.

3.3 База данни и таблици

При първо стартиране (или при изпълнение на db_check.py) приложението търси schema.sql и изпълнява скрипта. Така се създават:

• ITD_Cards – карти (код, текст за показ, активна/неактивна, дати).
• ITD_Cycles – цикли за всяка карта с дата/час за пост 1…5 и служебно затваряне.

Ако таблиците вече съществуват, схемата не променя данните (използва се IF NOT EXISTS).

---

4. Стартиране (режим разработка)

1. Отворете папката на проекта в командния ред.
2. Стартирайте:

start.bat

Скриптът:

• проверява за наличие на appsettings.json;
• инсталира зависимости от requirements.txt (ако липсват);
• пуска db_check.py – проверка за достъп до БД и прилагане на схемата;
• при успех пуска main.py.

Ако няма appsettings.json или връзката към БД не успее, програмата спира с подходящо съобщение.

Можете да стартирате и директно:

python db_check.py
python main.py

Иконата на прозореца се зарежда от ITD.ico в същата папка.

---

5. Изграждане на преносимо EXE

1. Уверете се, че в папката има: main.py, schema.sql, ITD.ico, appsettings.json (за тест; за разпространение вижте по-долу).
2. Инсталирайте PyInstaller (еднократно):

pip install pyinstaller

3. Пуснете:

build.bat

При успех в подпапка dist се създава ITD_Transport.exe. В EXE е вградена и схемата schema.sql; иконата на изпълнимия файл е ITD.ico.

Ако няма ITD.ico, build-ът все пак минава, но EXE няма да има икона.

---

6. Преносимо ползване на друг компютър

За да ползвате приложението без инсталиран Python:

1. Копирайте в една папка на целевата машина:
   • ITD_Transport.exe (от dist\);
   • appsettings.json (с правилен connection string за тази мрежа/сървър);
   • ITD.ico (по желание – за икона на прозореца при нужда).
2. На целевата машина трябва да е инсталиран ODBC Driver 17 for SQL Server (или съвместим драйвер).
3. Стартирайте ITD_Transport.exe. Работната директория е папката на exe-то; от там се чете appsettings.json.

Не е нужно да инсталирате Python или PyInstaller на целевата машина.

---

7. Основни екрани и функции

7.1 Основен екран

• Постове – показват се петте поста с цветове.
• QR карта (код) – въвеждате или сканирате кода на картата и натискате Регистрирай. Записва се следващият пост за тази карта.
• Филтър по карта – показват се само циклите за въведения номер на карта; Всички премахва филтъра.
• Таблица с цикли – ред за всеки цикъл: карта, време за постове 1–5, изход (нормален или служебен). С клик се избира ред.
• Бутони:
  • Обнови – презарежда циклите;
  • Затвори цикъла – служебно затваряне на избрания цикъл (ако липсва регистрация на последен пост);
  • Отмени служебен изход – премахва служебното затваряне за избрания цикъл;
  • Карти – отваря модула за карти.

7.2 Модул „Карти“

• Таблица с всички карти: код, текст (име + № кола), активна, дати.
• Обнови – презарежда списъка.
• Коригирай – промяна на текста на избрана карта.
• Изтрий – изтриване на карта (и регистрациите по нея).
• Деактивирай / Активирай – картата спира/започва да участва в регистрации.
• Създай PNG – запазване на карта като PNG (QR + текст) за отпечатване.
• Генерирай QR карта – нова карта с текст; запис в БД и показване на QR за отпечатване.
• Затвори – затваряне на прозореца.

---

8. Git и синхронизация

За работа с няколко компютъра и GitHub вижте GIT_SETUP.md: инициализация на repo, push към GitHub, клониране на друг компютър и локално изграждане на EXE.

Важно: appsettings.json е в .gitignore – не се комитва. На всеки компютър копирайте appsettings.example.json като appsettings.json и попълнете connection string.

---

9. Помощни скриптове и файлове

• make_icon.py – не се използва от текущия build; иконата е директно ITD.ico.
• reset_manual_cycle_closes.sql – при нужда за нулиране на служебни затваряния (изпълнява се ръчно върху БД).
• centered_messagebox.py – помощни функции за центрирани диалози в приложението.

---

10. Обобщение – бърз старт

Действие	Команда / стъпка
Първа настройка	Копирайте appsettings.example.json → appsettings.json, попълнете connection string.
Стартиране	start.bat (или python db_check.py и python main.py).
Build на EXE	build.bat → exe в dist\ITD_Transport.exe.
Преносимо ползване	Копирайте exe + appsettings.json + при желание ITD.ico в папка на целевата машина; инсталиран ODBC драйвер за SQL Server.

Иконата на приложението е само ITD.ico – в папката на скрипта при разработка и в папката на exe при преносимо ползване.