docs: add README with full UI and workflow documentation

2026-04-09 11:05:43 +03:00
parent 704e01669f
commit a8f642a1c9
1 changed files with 172 additions and 0 deletions
--- a/README.md
+++ 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.