Initial commit: Queensway Europe Telco Portal (Flask + SQLite, Docker deploy)

2026-09-11 07:23:40 +00:00
commit 919df2220e
42 changed files with 2206 additions and 0 deletions
@@ -0,0 +1,80 @@
+# Queensway Europe Telco Portal
+
+Management web portal for:
+
+- The mobile phone repository (phone numbers, plan, contract expiration, replacement
+  eligibility, current owner, venue)
+- Internet connectivity at each restaurant venue
+
+Same deployment approach as TostaSklad/TostaPortal: a Docker container you run locally on this
+PC with Docker Desktop, with all data kept in a bind-mounted folder outside the container. See
+`README-Docker.md` for how to start/stop it.
+
+## Folder layout
+
+```
+QWE Telco/
+  docker-compose.yml
+  README-Docker.md              <- Docker instructions (start here)
+  TelcoPortal-README.md         <- this file
+  TelcoPortal-source/           <- Flask app source (rebuilt into the Docker image)
+  TelcoPortal-data/
+    telco.db                    <- the SQLite database (both tables live in this one file)
+```
+
+## Data model
+
+**Mobile Phones** (`phones` table): Phone Number, Plan, Contract Expiration, Eligibility for
+Replacement, Current Owner, Venue.
+
+**Internet Connectivity** (`internet_connections` table): Venue, ISP Provider, Plan, Contract
+Expiration, Notes. This table starts empty - the source Excel file only had mobile phone data -
+add rows with the "+ Add Connection" button on the Internet Connectivity page as you go.
+
+There is no login. Anyone who can reach the URL (`http://localhost:8092/` by default) can view
+and edit both tables.
+
+## How the mobile phone data was loaded
+
+The one-off migration script `TelcoPortal-source/import_excel.py` reads the source Excel file
+(`Mobilne telefony 20260901.xlsx`) and loads it into `TelcoPortal-data/telco.db`. This has
+**already been run once** to populate the database - the Excel file is not needed by the running
+app and can be archived/deleted.
+
+Column mapping from the Excel file:
+
+| Excel column (Slovak)      | Portal field                |
+|-----------------------------|------------------------------|
+| T.Č.                         | Phone Number (re-prefixed with the leading 0 Excel drops from numeric cells) |
+| Užívateľský balík            | Plan                          |
+| Viazanosť do:                 | Contract Expiration           |
+| Možnost výmeny od:             | Eligibility for Replacement (blank/`---` in the source means "eligible now", not "unknown") |
+| Meno užívatela                | **not auto-split** - see note below |
+
+### Current Owner / Venue
+
+The source `Meno užívatela` column mixes two things: a handful of rows have a
+`"<number> - <person or venue>"` pattern, but most rows just repeat the company name
+("Queensway Restaurants Slovakia, s.r.o.") with nothing usable as a venue. There was no reliable
+way to auto-split this into separate Owner and Venue fields, so on import:
+
+- **Current Owner** was set to the raw `Meno užívatela` text for each row (nothing was thrown
+  away)
+- **Venue** was left blank
+
+To fix this up in bulk instead of editing 70+ rows by hand one at a time, re-run the import with
+a mapping file:
+
+```
+python import_excel.py "Mobilne telefony 20260901.xlsx" --mapping owner_venue_mapping.csv
+```
+
+where `owner_venue_mapping.csv` has three columns: `phone_number,current_owner,venue` (phone
+number in the same format shown in the portal, e.g. `0905988240`). Rows are matched by phone
+number, and only the rows present in the mapping file are updated - existing Plan/Contract
+Expiration/Eligibility data is left as-is either way. You can also just fix individual rows with
+the Edit button in the portal itself.
+
+## Backups
+
+Copy or zip `TelcoPortal-data/telco.db` any time - that single file is the entire database.