173 lines
6.5 KiB
Markdown
173 lines
6.5 KiB
Markdown
# 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.
|