# 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

The production Docker stack runs the app with PostgreSQL and retains its database in a named
Docker volume. See `README-Docker.md` for the initial SQLite import, startup, and backup steps.

## 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)
  data/
    telco.db                    <- legacy SQLite file, used for the first import only
```

## 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.

The portal is available at `http://localhost:8092/` by default and requires a configured user
login.

## 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 the legacy SQLite database. 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

The production database is PostgreSQL. Use the `pg_dump` command documented in
`README-Docker.md` to create a portable backup.