flight-alloc 0.0.1__py3-none-any.whl

src/web/__init__.py

@@ -0,0 +1,47 @@
+"""Local web UI for the Flight Allocation system.
+
+Served from stdlib http.server — no FastAPI / Flask / external deps, so
+it fits IT allow-list constraints and ships in the same PyInstaller
+bundle as the engine.
+
+The dashboard is the only input surface: the operator uploads the day's
+three files there, runs Plan / Allocate, reviews the result, and
+downloads an .xlsx if they need one to send on.
+
+Tabs:
+    Dashboard     Inputs, run status, headline stats, roster, charts
+    Allocations   Per-flight rows with shift / INTL / redistribution cues
+    Unallocated   What didn't fit, with per-flight recommendations
+    Workload      Per-staff load against the preferred / cap bands
+    Pairs         Pair map per boundary
+    Warnings      Severity-badged engine warnings
+    Override      Slide-out drawer, reachable from any tab
+
+Entry point: ``python -m src.web`` (binds 127.0.0.1:8765 by default).
+
+Layout
+------
+Server::
+
+    server.py     the request loop and the launcher — no endpoint logic
+    core/         transport: Response, the Router, static file serving
+    api/          one module per concern, each exposing register(router)
+    readback/     state -> the JSON shapes the UI reads
+    overrides/    the drawer's mutations, incl. config.yml write-through
+    runner.py     runs a stage on a worker thread
+
+Front end (``static/``)::
+
+    index.html    a shell with three mount points; views bring their markup
+    js/core/      dom, api, store (held payloads), shared constants
+    js/ui/        tab registry, layout mounting, the modals
+    js/views/     one module per tab, registered in views/index.js
+    js/charts/    one module per dashboard chart
+    js/panels/    dashboard blocks with their own load cycle
+    js/drawer/    the Override drawer and its sections
+    css/          partials, listed in styles.css
+
+Adding an endpoint is a handler in the ``api`` module that owns the
+concern. Adding a tab is a module in ``js/views/`` plus a line in its
+registry. Neither ``server.py`` nor ``index.html`` needs to change.
+"""

src/web/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m src.web`` entry point."""
+from __future__ import annotations
+
+import sys
+
+from .server import main
+
+if __name__ == "__main__":
+    sys.exit(main())

src/web/api/__init__.py

@@ -0,0 +1,56 @@
+"""The console's HTTP API, one module per concern.
+
+    readbacks       GET endpoints that only serialise state
+    inputs          upload / list / remove the three source files
+    runs            start Plan / Allocate / Reset, poll what's running
+    override_rows   the drawer's rows and staged add/remove forms
+    recommender     turn a suggested fix into an override row
+    settings        shift bands, airport codes, extraction filters
+    zc              the per-date Zone Controller list
+    export          the .xlsx download
+    pages           index.html and the static/ tree
+
+Each module exposes ``register(router)``. To add an endpoint, add a
+handler to the module that owns the concern — or add a module here and
+list it in ``BLUEPRINTS``. Nothing else needs to change.
+"""
+
+from __future__ import annotations
+
+from ..core.router import Router
+from . import (
+    export,
+    inputs,
+    override_rows,
+    pages,
+    readbacks,
+    recommender,
+    runs,
+    settings,
+    zc,
+)
+
+#: Registered in order. Literal routes are a dict lookup, so order only
+#: matters for the parameterised ones — keep the most specific first.
+BLUEPRINTS = (
+    readbacks,
+    inputs,
+    runs,
+    override_rows,
+    recommender,
+    settings,
+    zc,
+    export,
+    pages,
+)
+
+
+def build_router() -> Router:
+    """Assemble the full route table. Called once at start-up."""
+    router = Router()
+    for blueprint in BLUEPRINTS:
+        blueprint.register(router)
+    return router
+
+
+__all__ = ["BLUEPRINTS", "build_router"]

src/web/api/export.py

@@ -0,0 +1,37 @@
+"""Rendering the current state as an .xlsx download."""
+
+from __future__ import annotations
+
+from ...state import STATE
+from ..core.responses import (
+    XLSX_CONTENT_TYPE,
+    XML_CONTENT_TYPE,
+    Response,
+    attachment,
+    server_error,
+)
+from ..core.router import Request, Router
+
+
+def register(router: Router) -> None:
+
+    @router.get("/api/export.xlsx")
+    def export(_req: Request) -> Response:
+        from ...io.export import build_workbook, filename_for
+        try:
+            data = build_workbook(STATE)
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="export failed")
+        return attachment(data, XLSX_CONTENT_TYPE, filename_for(STATE))
+
+    @router.get("/api/export/allocations.xml")
+    def export_allocations_xml(_req: Request) -> Response:
+        from ...io.export_xml import build_allocations_xml, filename_for_xml
+        try:
+            data = build_allocations_xml(STATE)
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="allocations xml export failed")
+        return attachment(data, XML_CONTENT_TYPE, filename_for_xml(STATE))
+
+
+__all__ = ["register"]

src/web/api/inputs.py

@@ -0,0 +1,122 @@
+"""The three input files: upload, list, remove.
+
+The daily flight schedule is held in the server's memory for the
+session. The two period rosters are also kept on disk (``roster_store``)
+and reloaded at start-up: they are uploaded about once a month, several
+can be held at once, and the one covering the allocation date is used.
+Nothing is ever written back to the source workbooks.
+
+Which slot a file appears in is decided by its cadence, not by this
+module: the daily flight schedule sits on the dashboard and the two
+period rosters sit in the Setup sidebar. See ``INPUT_CADENCE`` in
+``state.py``. Every endpoint here answers with the same shape as
+``GET /api/inputs`` so the UI has one payload to render from.
+"""
+
+from __future__ import annotations
+
+import logging
+import urllib.parse
+from datetime import date as date_t
+
+from ...config import load_config
+from ...io.roster_library import roster_dates
+from ...state import INPUT_KINDS, SETUP_INPUT_KINDS, STATE
+from .. import readback
+from ..readback.common import CONFIG_PATH
+from ..core.responses import Response, bad_request, json_response
+from ..core.router import Request, Router
+
+logger = logging.getLogger("src.web")
+
+
+def register(router: Router) -> None:
+
+    @router.post("/api/inputs/{kind}")
+    def upload(req: Request) -> Response:
+        kind = req.params["kind"]
+        if kind not in INPUT_KINDS:
+            return bad_request(
+                f"unknown input {kind!r}; expected one of {list(INPUT_KINDS)}"
+            )
+        data = req.body
+        if not data:
+            return bad_request("empty upload")
+        # An .xlsx is a zip; anything else would blow up deep inside
+        # openpyxl on the next run, so reject it at the door.
+        if not data.startswith(b"PK"):
+            return bad_request(
+                "that doesn't look like an .xlsx file — re-save it as "
+                "Excel Workbook (.xlsx) and upload again"
+            )
+        filename = urllib.parse.unquote(
+            req.header("X-Filename") or f"{kind}.xlsx"
+        )
+        if kind in SETUP_INPUT_KINDS:
+            return _upload_roster(kind, filename, data)
+        up = STATE.set_input(kind, filename, data)
+        logger.info("[upload] %s: %s (%.0f KB)", kind, up.filename, len(data) / 1024)
+        return json_response({
+            "uploaded": up.as_json(),
+            **readback.read_inputs(STATE),
+        })
+
+    @router.delete("/api/inputs/{kind}")
+    def remove(req: Request) -> Response:
+        STATE.clear_input(req.params["kind"])
+        return json_response(readback.read_inputs(STATE))
+
+    @router.delete("/api/inputs/{kind}/{file_id}")
+    def remove_one(req: Request) -> Response:
+        """Drop one stored roster, keeping the others."""
+        kind = req.params["kind"]
+        if kind not in SETUP_INPUT_KINDS:
+            return bad_request(f"{kind!r} does not hold multiple files")
+        if not STATE.remove_roster(kind, req.params["file_id"]):
+            return bad_request("no such roster")
+        logger.info("[roster] removed %s %s", kind, req.params["file_id"])
+        return json_response(readback.read_inputs(STATE))
+
+    @router.get("/api/rosters/coverage")
+    def coverage(req: Request) -> Response:
+        """Does the stored roster set cover ``?date=`` (default: the
+        session's run date, else the server's today) and the day after?"""
+        raw = (req.query.get("date") or [""])[0]
+        try:
+            day = date_t.fromisoformat(raw) if raw else (
+                STATE.run_date or date_t.today()
+            )
+        except ValueError:
+            return bad_request(f"bad date {raw!r}; expected YYYY-MM-DD")
+        return json_response(STATE.roster_coverage(day))
+
+
+def _upload_roster(kind: str, filename: str, data: bytes) -> Response:
+    """Validate a period roster at the door, then keep it.
+
+    Parsing here means a wrong file (no ID column, duplicate ids, no
+    date columns) is refused with the reader's own message right away,
+    instead of surfacing as a failed Plan days later. The dates it
+    covers are what later picks it for an allocation date.
+    """
+    try:
+        dates = roster_dates(kind, data, load_config(CONFIG_PATH))
+    except Exception as exc:  # noqa: BLE001 — reader errors are user-facing
+        return bad_request(f"could not read {filename}: {exc}")
+    if not dates:
+        return bad_request(
+            f"{filename} has no date columns (expected headers like "
+            "'Mon,31Aug'). Is this the right file?"
+        )
+    rf = STATE.add_roster(kind, filename, data, dates)
+    logger.info(
+        "[upload] %s: %s (%d days, %s to %s)",
+        kind, rf.filename, len(rf.dates), rf.start, rf.end,
+    )
+    return json_response({
+        "uploaded": {"kind": kind, **rf.as_json()},
+        **readback.read_inputs(STATE),
+    })
+
+
+__all__ = ["register"]

src/web/api/override_rows.py

@@ -0,0 +1,138 @@
+"""The Override drawer's write surface: the row table, the staged
+add/remove forms, and the apply pass that materialises staged rows onto
+the data sheets.
+
+Every mutation here is session-scoped — rows live in ``STATE`` until
+the server restarts. Reset keeps them on purpose, so an assigner can
+re-run without retyping.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ...state import STATE
+from .. import overrides as override_ops
+from ..core.responses import (
+    Response,
+    bad_request,
+    json_response,
+    server_error,
+)
+from ..core.router import Request, Router
+from .runs import parse_date
+
+logger = logging.getLogger("src.web")
+
+
+def _row_index(req: Request) -> int | None:
+    """The ``{index}`` path param as an int, or None if it isn't one."""
+    try:
+        return int(req.params["index"])
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def register(router: Router) -> None:
+
+    @router.post("/api/overrides")
+    def add_row(req: Request) -> Response:
+        values = req.json().get("values")
+        if not isinstance(values, list):
+            return bad_request("body.values must be a list of strings")
+        index = override_ops.add_override(STATE, [str(v) for v in values])
+        return json_response({"index": index})
+
+    @router.put("/api/overrides/{index}")
+    def update_row(req: Request) -> Response:
+        row_index = _row_index(req)
+        if row_index is None:
+            return bad_request(f"row index must be an integer, got {req.params['index']!r}")
+        body = req.json()
+        values = body.get("values")
+        if not isinstance(values, list):
+            return bad_request("body.values must be a list of strings")
+        try:
+            override_ops.update_override(
+                STATE, row_index, [str(v) for v in values],
+            )
+        except IndexError as exc:
+            return bad_request(str(exc))
+
+        # Re-apply staged rows after an edit so add_flight / remove_flight
+        # / add_staff / remove_staff / change_role / sick take effect on
+        # the data immediately; the dashboard refresh then shows it.
+        applied: dict[str, int] = {}
+        d_day = parse_date(body.get("date"))
+        if d_day is not None:
+            from ... import staged_overrides as _so
+            applied = _so.apply_staged_overrides(STATE, d_day)
+        return json_response({"updated": True, "applied": applied})
+
+    @router.delete("/api/overrides/{index}")
+    def delete_row(req: Request) -> Response:
+        row_index = _row_index(req)
+        if row_index is None:
+            return bad_request(f"row index must be an integer, got {req.params['index']!r}")
+        try:
+            override_ops.delete_override(STATE, row_index)
+        except IndexError as exc:
+            return bad_request(str(exc))
+        return json_response({"deleted": True})
+
+    @router.post("/api/overrides/apply_staged")
+    def apply_staged(req: Request) -> Response:
+        d_day = parse_date(req.json().get("date"))
+        if d_day is None:
+            return bad_request("body.date required (YYYY-MM-DD)")
+        from ... import staged_overrides as _so
+        try:
+            counts = _so.apply_staged_overrides(STATE, d_day)
+        except Exception as exc:  # noqa: BLE001
+            return server_error(exc, context="apply_staged failed")
+        return json_response({"applied": counts})
+
+    @router.post("/api/staged_form/{op}")
+    def staged_form(req: Request) -> Response:
+        """Drawer forms: add_flight / remove_flight / add_staff /
+        remove_staff. Writes the override row AND applies it immediately
+        so the dashboard reflects the projected state on next refresh.
+
+        ``ops_date`` is the day being planned and must be ISO. It is
+        kept separate from the row's own ``date`` column, which a
+        remove_flight row carries as MM/DD — overloading one key for
+        both meant the MM/DD value was parsed as the ops date and every
+        remove_flight submission was rejected. ``date`` is still read as
+        a fallback so an older client keeps working.
+        """
+        from ...schemas import STAGED_FORM_OVERRIDE_TYPES
+        op_type = req.params["op"]
+        valid = {t.value for t in STAGED_FORM_OVERRIDE_TYPES}
+        if op_type not in valid:
+            return bad_request(
+                f"unknown staged form op: {op_type!r}. valid: {sorted(valid)}"
+            )
+        body = req.json()
+        d_day = parse_date(body.get("ops_date")) or parse_date(body.get("date"))
+        if d_day is None:
+            return bad_request("body.ops_date required (YYYY-MM-DD)")
+        payload = {
+            k: str(v).strip() for k, v in body.items()
+            if k != "ops_date" and isinstance(v, (str, int, float)) and str(v).strip()
+        }
+        try:
+            index = override_ops.write_staged_override(STATE, op_type, payload)
+            from ... import staged_overrides as _so
+            applied = _so.apply_staged_overrides(STATE, d_day)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("staged form %s failed", op_type)
+            return server_error(exc, context=f"{op_type} failed")
+        logger.info(
+            "[staged-form] %s: row %s written, applied=%s", op_type, index, applied,
+        )
+        return json_response({
+            "ok": True, "index": index, "op": op_type, "applied": applied,
+        })
+
+
+__all__ = ["register"]

src/web/api/pages.py

@@ -0,0 +1,30 @@
+"""The page itself: index.html and everything under ``static/``.
+
+Registered last, and the wildcard is scoped to ``/static/`` rather than
+``/``, so an unmatched ``/api/...`` path still returns a JSON 404
+instead of being answered with HTML.
+"""
+
+from __future__ import annotations
+
+from ..core import static_files
+from ..core.responses import Response
+from ..core.router import Request, Router
+
+
+def register(router: Router) -> None:
+
+    @router.get("/")
+    def index(_req: Request) -> Response:
+        return static_files.serve(static_files.INDEX)
+
+    @router.get("/index.html")
+    def index_html(_req: Request) -> Response:
+        return static_files.serve(static_files.INDEX)
+
+    @router.get("/static/{path*}")
+    def asset(req: Request) -> Response:
+        return static_files.serve(req.params["path"])
+
+
+__all__ = ["register"]

src/web/api/readbacks.py

@@ -0,0 +1,72 @@
+"""GET endpoints that only serialise state — no mutation, no side
+effects.
+
+The bulk of them are a straight ``path -> readback function`` mapping,
+so they're registered from a table: a new tab needs a readback function
+and one line here, not a new handler.
+"""
+
+from __future__ import annotations
+
+from ...state import STATE
+from .. import readback
+from ..core.responses import Response, json_response
+from ..core.router import Request, Router
+
+#: Endpoints whose handler is exactly ``fn(STATE)``.
+STATE_READBACKS = {
+    "/api/inputs":             readback.read_inputs,
+    "/api/server_date":        readback.read_server_date,
+    "/api/dashboard":          readback.read_dashboard,
+    "/api/allocations":        readback.read_allocations,
+    "/api/workload":           readback.read_workload,
+    "/api/pairs":              readback.read_pairs,
+    "/api/warnings":           readback.read_warnings,
+    "/api/unallocated":        readback.read_unallocated,
+    "/api/recommendations":    readback.read_recommendations,
+    "/api/overrides":          readback.read_overrides,
+    "/api/plan":               readback.read_plan_summary,
+    "/api/handlers":           readback.read_handlers,
+    "/api/staffing":           readback.read_staffing,
+    "/api/staff_names":        readback.read_staff_names,
+    "/api/roster_full":        readback.read_roster_full,
+    "/api/sv_portal/columns":  readback.read_sv_portal_columns,
+}
+
+
+def register(router: Router) -> None:
+    for path, fn in STATE_READBACKS.items():
+        router.add("GET", path, _state_handler(fn))
+
+    @router.get("/api/shift_limits")
+    def shift_limits(_req: Request) -> Response:
+        return json_response(readback.read_shift_limits())
+
+    @router.get("/api/override_types")
+    def override_types(_req: Request) -> Response:
+        """The canonical list of user-facing override types plus the
+        per-type relevant columns, so the drawer always matches the
+        backend enum and renders only the cells a row type cares about.
+        Single source of truth lives in schemas."""
+        from ...schemas import (
+            OVERRIDE_TYPE_RELEVANT_COLS,
+            OVERRIDE_TYPES_FOR_UI,
+            OverrideType,
+        )
+        return json_response({
+            "types": [t.value for t in OVERRIDE_TYPES_FOR_UI],
+            "relevant_cols": {
+                t.value: list(OVERRIDE_TYPE_RELEVANT_COLS[t])
+                for t in OverrideType
+            },
+        })
+
+
+def _state_handler(fn):
+    def handler(_req: Request) -> Response:
+        return json_response(fn(STATE))
+    handler.__name__ = getattr(fn, "__name__", "readback")
+    return handler
+
+
+__all__ = ["STATE_READBACKS", "register"]

src/web/api/recommender.py

@@ -0,0 +1,72 @@
+"""Turning an unallocated flight's suggested fix into an override row.
+
+One at a time from the Unallocated tab's chips, or all of them at once
+when a bad day leaves a list too long to click through.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ...state import STATE
+from .. import overrides as override_ops
+from .. import readback
+from ..core.responses import Response, bad_request, json_response
+from ..core.router import Request, Router
+
+logger = logging.getLogger("src.web")
+
+#: How many per-flight failures to quote back in the apply_all response.
+MAX_SAMPLE_ERRORS = 5
+
+
+def register(router: Router) -> None:
+
+    @router.post("/api/recommender/apply")
+    def apply_one(req: Request) -> Response:
+        body = req.json()
+        kind = body.get("kind") if isinstance(body.get("kind"), str) else None
+        payload = body.get("payload")
+        if not kind or not isinstance(payload, dict):
+            return bad_request("body must have kind:str and payload:dict")
+        try:
+            index = override_ops.apply_phase_r_override(STATE, kind, payload)
+        except (ValueError, KeyError) as exc:
+            return bad_request(str(exc))
+        return json_response({"index": index, "kind": kind})
+
+    @router.post("/api/recommender/apply_all")
+    def apply_all(_req: Request) -> Response:
+        """For each unallocated flight, take the LEAST intrusive
+        suggestion and write it as an override — one click instead of
+        dozens when a bad day leaves a long unallocated list."""
+        recs = readback.read_recommendations(STATE).get("recommendations", [])
+        applied = failed = 0
+        errs: list[str] = []
+        for rec in recs:
+            suggestions = rec.get("suggestions") or []
+            if not suggestions:
+                continue
+            best = min(suggestions, key=lambda s: s.get("intrusiveness", 100))
+            kind = best.get("type")
+            payload = best.get("payload") or {}
+            if not kind or not isinstance(payload, dict):
+                failed += 1
+                continue
+            try:
+                override_ops.apply_phase_r_override(STATE, kind, payload)
+                applied += 1
+            except Exception as exc:  # noqa: BLE001 — one bad row shouldn't
+                failed += 1           # abandon the rest of the list
+                if len(errs) < MAX_SAMPLE_ERRORS:
+                    errs.append(f"{rec.get('flt', '?')}: {exc!r}")
+        logger.info(
+            "[apply-all] applied=%s failed=%s total=%s", applied, failed, len(recs),
+        )
+        return json_response({
+            "applied": applied, "failed": failed,
+            "total": len(recs), "sample_errors": errs,
+        })
+
+
+__all__ = ["MAX_SAMPLE_ERRORS", "register"]