From a8f642a1c9242d36f2ec1b2246a98361a9a17a25 Mon Sep 17 00:00:00 2001 From: ske087 Date: Thu, 9 Apr 2026 11:05:43 +0300 Subject: [PATCH] docs: add README with full UI and workflow documentation --- README.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d50d5d --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ +# 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.