db_interface/README.md

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

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.