ITD_track/README.md

# 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:

```json
{
  "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. Стартирайте:

```bat
start.bat
```

Скриптът:

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

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

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

```bat
python db_check.py
python main.py
```

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

---

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

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

```bat
pip install pyinstaller
```

3. Пуснете:

```bat
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 при преносимо ползване.