# Database Search & Update — User Guide

A fullscreen touchscreen application for querying and updating article/box weight (mass) records stored in a MariaDB database.

---

## UI Layout (top to bottom)

```
┌─────────────────────────────────────┬────────┐
│  Database Search & Update           │  Exit  │
├──────┬──────────────────────────────┴────────┤
│  ID: │  [scan / type here]                   │
│ Mass:│  [current mass]  Last update: ...     │
├──────┴───────────────────────────────────────┤
│  Article type detected: PRODUCT  [Override]  │
├───────────────┬──────────────┬───────────────┤
│  Add/Update   │ Reset Values │   Settings    │
├───────────────┴──────────────┴───────────────┤
│  Update Values                               │
│  ID:   [read-only — original barcode]        │
│  Mass: [editable]                            │
│  [Confirm Add/Update]        [Delete]        │
├──────────────────────────────────────────────┤
│  Status bar                                  │
├──────────────────────────────────────────────┤
│  [ 1 ]  [ 2 ]  [ 3 ]                        │
│  [ 4 ]  [ 5 ]  [ 6 ]    Numeric keypad      │
│  [ 7 ]  [ 8 ]  [ 9 ]                        │
│  [ . ]  [ 0 ]  [ ⌫ ]                        │
│  [           Enter           ]               │
└──────────────────────────────────────────────┘
```

---

## Article / Box Auto-Detection

When a barcode is entered in the **ID** field the app automatically classifies it:

| Rule | Type | DB key used |
|---|---|---|
| Exactly 8 digits | **BOX** | Leading zeros stripped — e.g. `00000003` → `3` |
| Anything else | **PRODUCT** | Used as-is |

The detected type is shown in the **mode bar** (blue = PRODUCT, amber = BOX).

### Manual Override
Press **Override type** to flip the detected type between BOX and PRODUCT.  
The mode bar shows `[Manual]` while an override is active.  
Typing a new ID resets the override back to auto-detection.

---

## Typical Workflow

### 1 — Search
1. Scan or type the article/box code into the **ID** field.
2. Press **Enter** on the keypad or the physical Enter key.
3. The app queries the database and fills:
   - **Mass** — current stored weight
   - **Last update** — date and time of the last mass change

   If the article is not in the database yet, Mass stays empty and the status bar shows "not found".

### 2 — Add / Update
1. After a search (found or not found), press **Add/Update**.
2. The **Update Values** frame activates:
   - **ID** (read-only) — shows the original barcode as scanned
   - **Mass** — pre-filled with the current value, fully editable; keyboard focus moves here automatically
3. Clear the Mass field and type the new weight using the numeric keypad or a physical keyboard.
4. Press **Confirm Add/Update**.
   - If the record exists → `UPDATE mass, t_update WHERE id = ?`
   - If the record is new → `INSERT` with the current timestamp
5. On success all fields are cleared and focus returns to the **ID** field.

### 3 — Delete
1. After a search (found), press **Add/Update** to load the record into the Update Values frame.
2. Press **Delete** → a confirmation popup appears.
3. Confirm to permanently remove the record from the database.

### 4 — Reset Values
Clears all fields (ID, Mass, Update Values frame) and returns focus to the **ID** field without touching the database.

---

## Numeric Keypad

| Key | Action |
|---|---|
| `0`–`9` | Append digit to the active field |
| `.` | Append decimal point |
| `⌫` | Delete last character |
| **Enter** | Trigger database search (when ID field is active) |

The keypad always targets the currently focused field (ID or Mass).

---

## Settings

Press **Settings** to change the database server address.

| Field | Default |
|---|---|
| Server IP / hostname | `localhost` (loaded from `config.json`) |

**Test Connection** checks connectivity before saving.  
**Save** persists the new address to `config.json` next to the executable.

---

## Log Files

Both files are created next to `config.json` (same folder as the `.exe` when running the built binary, or the project root when running from source).

### `app_actions.log`
One line per database action:

```
2026-04-09 15:30:45 | SEARCH_FOUND      | id=4                    | mass=3446.0, t_update=None
2026-04-09 15:31:02 | UPDATE            | id=4                    | mass=3440.0
2026-04-09 15:45:10 | INSERT            | id=12345                | mass=1200.0
2026-04-09 16:00:00 | DELETE            | id=7                    | rows_deleted=1
```

| Action | Description |
|---|---|
| `APP_START` | Application launched |
| `SEARCH_FOUND` | ID found in database |
| `SEARCH_NOT_FOUND` | ID not in database |
| `UPDATE` | Mass updated on existing record |
| `INSERT` | New record created |
| `DELETE` | Record removed |
| `DELETE_NOT_FOUND` | Delete attempted on non-existent ID |
| `LOG_PURGE` | Old log entries removed at startup |
| `*_ERROR` | Any database exception |

Lines older than **30 days** are automatically removed each time the app starts.

### `db_debug.log`
Verbose internal debug log (SQL statements, connection events, row counts) for troubleshooting.

---

## Database

| Detail | Value |
|---|---|
| Engine | MariaDB / MySQL |
| Database | `cantare_injectie` |
| Table | `offsystemsCounting` |
| Columns | `id VARCHAR(20)` · `mass REAL` · `t_update DATETIME` |

The table and the `t_update` column are created automatically on first run if they do not exist.

---

## Running from Source

```powershell
cd "C:\Users\Dell\Desktop\db_interface"
.\venv\Scripts\python.exe main.py
```

## Running the Built Binary

```
dist\DatabaseApp.exe
```

Copy your existing `config.json` next to the `.exe` to keep the saved server IP, or set it via **Settings** on first launch.