Phase 8: Project Management, find bar, presence and motion

The Project Management screen (/pm, view only) with Overview, Projects & units, Bottlenecks & aging, Hours vs target,
Quality & issues and Find jobs, the period picker, health per unit and per project, drill down, Excel (CSV) per table
and for all, and the PESCO production status report PDF with the controlled-copy stamp; every export logged as
"report exported". The find bar on every home screen: the full search set, the dropdowns, quick flags with Mine, the
flag kinds, Board and List with sorts, filters saved per browser; every filter applied by the server on the list and
the boards, with facets. Presence in packets with role, lock and revoke drop; the motion switch with reduced motion
honoured, card glides, glow and count-up; Back restores the scroll spot; sheet placement and the iPad layout pass. The
data book compared page by page with the old build and six layout differences fixed. Tests for the PM aggregates,
search, filters, presence and exports; Playwright scenarios for the PM screen, the find bar and presence at desktop and
iPad viewports. Docs updated; PLAN.md questions 38 to 42.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

server/packetstation/api/auth.py

@@ -7,7 +7,7 @@ from typing import Any
 from fastapi import APIRouter, Depends, Request, Response
 from pydantic import BaseModel, Field
 
-from .. import audit
+from .. import audit, events
 from ..auth import devices, signin, stepup
 from ..auth import directory as userdir
 from ..auth import pin as pins
@@ -186,6 +186,7 @@ def _lock(d: Db, p: Principal, source: str) -> None:
                 detail={"source": source},
                 ip=p.ip,
             )
+            events.publish(conn, {"event": "session", "session_id": str(p.session_id), "action": "locked"})
 
 
 @router.post("/lock", status_code=204)
@@ -240,5 +241,6 @@ def unlock(
                 detail={"factor": body.factor},
                 ip=p.ip,
             )
+            events.publish(conn, {"event": "session", "session_id": str(p.session_id), "action": "unlocked"})
         p.session["locked_since"] = None
     return me_payload(conn, p)

server/packetstation/api/deps.py

@@ -14,7 +14,7 @@ from typing import Any
 from fastapi import Depends, Request, Response
 from psycopg.types.json import Jsonb
 
-from .. import audit, db
+from .. import audit, db, events
 from ..auth import devices, sessions
 from ..auth import directory as userdir
 from ..auth import groups as groupmap
@@ -268,9 +268,13 @@ def resolve(request: Request, d: Db, *, allow_locked: bool, token: str | None =
         conn.execute("UPDATE sessions SET hidden_since = NULL WHERE id = %s", (row["id"],))
     if lock_source is not None:
         with conn.transaction():
-            conn.execute(
-                "UPDATE sessions SET locked_since = %s WHERE id = %s AND locked_since IS NULL", (now, row["id"])
-            )
+            locked = conn.execute(
+                "UPDATE sessions SET locked_since = %s WHERE id = %s AND locked_since IS NULL RETURNING id",
+                (now, row["id"]),
+            ).fetchone()
+            if locked is not None:
+                # Presence drops a locked session at once (events.EventHub handles the event).
+                events.publish(conn, {"event": "session", "session_id": str(row["id"]), "action": "locked"})
             snap = row.get("roles_snapshot") or {}
             audit.append(
                 conn,

server/packetstation/api/events.py

@@ -6,7 +6,7 @@ from fastapi import APIRouter, Query, Request
 from fastapi.responses import StreamingResponse
 from starlette.concurrency import run_in_threadpool
 
-from ..auth.groups import SCREENS
+from ..auth.groups import SCREEN_LABELS, SCREENS, role_label
 from ..events import EventHub, stream
 from .deps import resolve_standalone, settings_of
 
@@ -22,16 +22,21 @@ async def events(
     packet_id: int | None = Query(None, ge=1, le=2**62),
 ) -> StreamingResponse:
     """The event stream. `packet_id` is the packet the page has open; presence carries it, so the packet page can
-    show who else is looking at the same packet. The client reopens the stream when the open packet changes."""
+    show who else is looking at the same packet. The client reopens the stream when the open packet changes.
+    Presence names the person with the label of the screen they have open (a screen their roles allow), else their
+    primary role. A locked session is left out of presence until it unlocks."""
     # The session check runs on its own pooled connection, returned before the stream starts
     p = await run_in_threadpool(resolve_standalone, request)
     hub: EventHub = request.app.state.events
+    open_screen = screen if screen in SCREENS and screen in p.screens else None
     sub = hub.subscribe(
         session_id=p.session_id,
         user_id=p.user_id,
         display_name=p.user["display_name"],
-        screen=screen if screen in SCREENS and screen in p.screens else None,
+        screen=open_screen,
         packet_id=packet_id,
+        role=SCREEN_LABELS[open_screen] if open_screen else role_label(p.roles),
+        locked=p.locked,
     )
     hello = {"session_id": str(p.session_id), "build": settings_of(request).ps_build}
     return StreamingResponse(

server/packetstation/api/packets.py

@@ -8,8 +8,10 @@ Every mutating answer is the full read model.
 from __future__ import annotations
 
 import uuid
+from datetime import UTC, date, datetime
 from decimal import Decimal
 from typing import Any, Literal
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from fastapi import APIRouter, Depends, Query, Request
 from psycopg.types.json import Jsonb
@@ -18,7 +20,7 @@ from pydantic import BaseModel, Field
 from .. import audit, events, policy
 from ..domain import assets as asset_store
 from ..domain import ncr as ncrs
-from ..domain import packets, shop
+from ..domain import packets, search, shop
 from ..domain import qc as qc_dom
 from ..domain.pipeline import (
     Expect,
@@ -294,32 +296,69 @@ def _pp(d: Db, p: Principal) -> policy.Principal:
 # ---------------------------------------------------------------- list and read
 
 
-@router.get("")
-def list_packets(
-    p: Principal = Depends(current_principal),  # noqa: B008
-    d: Db = Depends(get_db),  # noqa: B008
+def site_today(request: Request) -> date:
+    """Today in the site time zone (settings.site_tz), once per request."""
+    try:
+        tz: Any = ZoneInfo(settings_of(request).site_tz)
+    except (ZoneInfoNotFoundError, ValueError):
+        tz = UTC
+    return datetime.now(tz).date()
+
+
+def find_query(
+    q: str = Query("", max_length=200),
     status: str = Query("", max_length=200),
     dept: str = Query("", max_length=10),
+    station_id: int | None = Query(None, ge=1, le=2**62),
+    welder_id: str = Query("", max_length=40),
+    flags: str = Query("", max_length=100),
+    flag: str = Query("", max_length=20),
+    sort: str = Query("", max_length=20),
+    mine_screen: str = Query("", max_length=20),
+    mine_station_id: int | None = Query(None, ge=1, le=2**62),
+) -> dict[str, Any]:
+    """The find bar's query values, shared by GET /api/packets, the boards and the PM reports."""
+    return {
+        "q": q,
+        "status": status,
+        "dept": dept,
+        "station_id": station_id,
+        "welder_id": welder_id,
+        "flags": flags,
+        "flag": flag,
+        "sort": sort,
+        "mine_screen": mine_screen,
+        "mine_station_id": mine_station_id,
+    }
+
+
+FIND = Depends(find_query)
+
+
+@router.get("")
+def list_packets(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
     unit_id: int | None = Query(None),
     project_id: int | None = Query(None),
-    q: str = Query("", max_length=200),
-    flag: str = Query("", max_length=20),
     co: str = Query("", max_length=20),
+    facets: int = Query(0, ge=0, le=1),
     limit: int = Query(500, ge=1, le=2000),
     removed: int = Query(0, ge=0, le=1),
 ) -> dict[str, Any]:
-    filters = {
-        "status": status,
-        "dept": dept.strip() or None,
-        "unit_id": unit_id,
-        "project_id": project_id,
-        "q": clean_text(q, 200),
-        "flag": flag,
-        "co": co.strip().lower() or None,
-        "limit": limit,
-        "removed": bool(removed) and p.is_admin,
-    }
-    return {"packets": packets.list_cards(d.conn, _pp(d, p), filters)}
+    """The cards for a list. The find bar's filters are applied here; `facets=1` adds the stations and workers
+    among the packets in the project and unit scope."""
+    pp = _pp(d, p)
+    filters = search.parse_filters(
+        {**find, "unit_id": unit_id, "project_id": project_id}, pp, screen=None, today=site_today(request)
+    )
+    filters.update({"co": co.strip().lower() or None, "limit": limit, "removed": bool(removed) and p.is_admin})
+    out: dict[str, Any] = {"packets": packets.list_cards(d.conn, pp, filters)}
+    if facets:
+        out["facets"] = search.facets(d.conn, project_id=project_id, unit_id=unit_id)
+    return out
 
 
 @router.post("", status_code=201, dependencies=WRITE)

server/packetstation/api/pm.py

@@ -0,0 +1,229 @@
+"""Project Management: the read-only reports, the CSV exports and the production status PDF.
+
+Any signed-in session reads (every role may open every packet, PM included). Nothing here writes a packet; an export
+writes one print_log row and one audit row (`report exported`). Every endpoint takes the find bar's scope: the
+project and unit pick, dept, status, station_id, welder_id, flags, flag, q, and the history period (30, 90, 365 or
+all days; default 90). Mine is ignored here. The reports read PostgreSQL only.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query, Request
+from fastapi.responses import Response
+
+from ..domain import packets, pm, prints
+from ..pdf import pmreport
+from ..pdf.tracecsv import to_csv
+from .deps import Db, Principal, current_principal, get_db, settings_of
+from .errors import ApiError
+from .packets import FIND
+
+router = APIRouter(prefix="/api/pm", tags=["pm"])
+
+PERIOD = Query(pm.DEFAULT_PERIOD, pattern="^(30|90|365|all)$")
+
+
+def _report(
+    request: Request,
+    d: Db,
+    p: Principal,
+    find: dict[str, Any],
+    project_id: int | None,
+    unit_id: int | None,
+    period: str,
+    expand: str | None = None,
+) -> pm.Report:
+    conn = d.conn
+    pp = packets.policy_principal_for(conn, p)
+    s = settings_of(request)
+    return pm.load(
+        conn,
+        pp,
+        {**find, "project_id": project_id, "unit_id": unit_id},
+        now=datetime.now(UTC),
+        tz=s.site_tz,
+        period=period,
+        expand=expand,
+    )
+
+
+@router.get("/overview")
+def overview(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+) -> dict[str, Any]:
+    """The KPIs, the plain-words summary, the pipeline and the units late or at risk."""
+    return pm.overview(_report(request, d, p, find, project_id, unit_id, period))
+
+
+@router.get("/projects")
+def projects(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+    expand: str = Query("", max_length=2000),
+) -> dict[str, Any]:
+    """The projects table. Without `expand` only the picked project shows its units; `expand=all` opens every
+    project, a comma list of project ids opens those."""
+    rep = _report(request, d, p, find, project_id, unit_id, period, expand=expand)
+    return {"scope": rep.scope(), "tables": [pm.projects_table(rep)]}
+
+
+@router.get("/aging")
+def aging(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+) -> dict[str, Any]:
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    pipe = pm.pipeline(rep)
+    return {"scope": rep.scope(), "pipeline": pipe, "tables": pm.aging_tables(rep, pipe)}
+
+
+@router.get("/hours")
+def hours(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+) -> dict[str, Any]:
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    return {"scope": rep.scope(), "tables": pm.hours_tables(rep)}
+
+
+@router.get("/quality")
+def quality(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+) -> dict[str, Any]:
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    return {"scope": rep.scope(), "tables": pm.quality_tables(rep)}
+
+
+@router.get("/find")
+def find_jobs(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+) -> dict[str, Any]:
+    """The cards in scope, in the find bar's sort (default last updated)."""
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    if (find.get("sort") or "updated") != "project":
+        f = {**rep.filters, "sort": find.get("sort") or "updated", "limit": pm.CARD_LIMIT, "lite": True}
+        cards = packets.list_cards(d.conn, packets.policy_principal_for(d.conn, p), f)
+    else:
+        cards = rep.cards
+    return {"scope": rep.scope(), "packets": cards}
+
+
+@router.get("/export.csv")
+def export_csv(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+    table: str = Query("all", max_length=40),
+) -> Response:
+    """One table (by key), the jobs (`jobs`) or every report (`all`) as CSV for Excel: a BOM, CRLF lines and the
+    formula guard on every cell. Logged as `report exported`."""
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    found = pm.tables_for(rep, table.strip().lower())
+    if found is None:
+        raise ApiError(404, "not_found", "No such report table.")
+    name, tables = found
+    who = str(p.user.get("display_name") or p.user.get("sam_account") or "")
+    body = "\ufeff" + to_csv(pm.csv_rows(rep, name, tables, who)) + "\r\n"
+    day = rep.now.astimezone(pm.zone(rep.tz)).date().isoformat()
+    filename = f"PacketStation_{pm.file_stem(name)}_{day}.csv"
+    label = rep.scope_label()
+    prints.record(
+        d.conn,
+        p,
+        action="report exported",
+        kind="report-csv",
+        what=f"{name} · CSV · {label}",
+        pages=None,
+        detail={"name": name, "format": "csv", "scope": label, "period": rep.period},
+    )
+    return Response(
+        content=body.encode("utf-8"),
+        media_type="text/csv; charset=utf-8",
+        headers={"Content-Disposition": prints.disposition(filename, download=True), "Cache-Control": "no-store"},
+    )
+
+
+@router.get("/report.pdf")
+def report_pdf(
+    request: Request,
+    p: Principal = Depends(current_principal),  # noqa: B008
+    d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
+    project_id: int | None = Query(None),
+    unit_id: int | None = Query(None),
+    period: str = PERIOD,
+    download: int = Query(0, ge=0, le=1),
+) -> Response:
+    """The PESCO production status report (dark format), stamped as a controlled copy on every page. Inline unless
+    `download=1`. Logged as `report exported` with the page count."""
+    rep = _report(request, d, p, find, project_id, unit_id, period)
+    who = prints.who_of(p)
+    built = pmreport.build(
+        d.conn,
+        settings_of(request),
+        scope_params={**find, "project_id": project_id, "unit_id": unit_id, "period": period},
+        who=who,
+        now=rep.now,
+        report=rep,
+    )
+    label = rep.scope_label()
+    prints.record(
+        d.conn,
+        p,
+        action="report exported",
+        kind="report-pdf",
+        what=f"Production status report · PDF · {label}",
+        pages=built.pages,
+        stamp=built.stamp,
+        stamp_sig=built.stamp_sig,
+        detail={"name": "Production status report", "format": "pdf", "scope": label, "period": rep.period},
+    )
+    day = rep.now.astimezone(pm.zone(rep.tz)).date().isoformat()
+    return Response(
+        content=built.pdf,
+        media_type="application/pdf",
+        headers={
+            "Content-Disposition": prints.disposition(f"PESCO_Production_Status_{day}.pdf", download=bool(download)),
+            "Cache-Control": "no-store",
+        },
+    )

server/packetstation/api/qc.py

@@ -10,18 +10,18 @@ from __future__ import annotations
 import uuid
 from typing import Any
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Query, Request
 from pydantic import BaseModel, Field
 
 from .. import audit, events, policy
 from ..domain import assets as asset_store
 from ..domain import itp as itp_dom
-from ..domain import packets, qcdocs
+from ..domain import packets, qcdocs, search
 from ..domain import qc as dom
 from ..text import clean_opt, clean_text
 from .deps import Db, Principal, current_principal, get_db
 from .errors import ApiError
-from .packets import WRITE
+from .packets import FIND, WRITE, site_today
 
 router = APIRouter(prefix="/api/qc", tags=["qc"])
 
@@ -42,13 +42,21 @@ class QcDocBody(BaseModel):
 
 @router.get("/home")
 def home(
+    request: Request,
     p: Principal = Depends(current_principal),  # noqa: B008
     d: Db = Depends(get_db),  # noqa: B008
+    find: dict[str, Any] = FIND,
     project_id: int | None = Query(None),
     unit_id: int | None = Query(None),
 ) -> dict[str, Any]:
+    """The Q.C. home. The find bar values narrow the cards of the three boards; the KPIs follow the project and
+    unit only."""
     conn = d.conn
-    return dom.home(conn, packets.policy_principal_for(conn, p), project_id=project_id, unit_id=unit_id)
+    pp = packets.policy_principal_for(conn, p)
+    filters = search.parse_filters(
+        {**find, "project_id": project_id, "unit_id": unit_id}, pp, screen="qc", today=site_today(request)
+    )
+    return dom.home(conn, pp, project_id=project_id, unit_id=unit_id, filters=filters)
 
 
 @router.get("/folders")

server/packetstation/api/shop.py

@@ -8,26 +8,37 @@ from __future__ import annotations
 
 from typing import Any
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Query, Request
 
-from ..domain import packets, shop
+from ..domain import packets, search, shop
 from ..text import clean_text
 from .deps import Db, Principal, current_principal, get_db
+from .packets import FIND, site_today
 
 router = APIRouter(prefix="/api/shop", tags=["shop"])
 
 
 @router.get("/board")
 def board(
+    request: Request,
     p: Principal = Depends(current_principal),  # noqa: B008
     d: Db = Depends(get_db),  # noqa: B008
-    dept: str = Query("", max_length=10),
+    find: dict[str, Any] = FIND,
     project_id: int | None = Query(None),
     unit_id: int | None = Query(None),
 ) -> dict[str, Any]:
+    """The supervisor board. `dept` picks one of the departments the person leads (it scopes the board and its
+    KPIs); the other find bar values narrow the cards."""
     conn = d.conn
     pp = packets.policy_principal_for(conn, p)
-    return shop.board(conn, pp, dept=clean_text(dept, 10) or None, project_id=project_id, unit_id=unit_id)
+    dept = clean_text(find.get("dept") or "", 10) or None
+    filters = search.parse_filters(
+        {**find, "dept": None, "project_id": project_id, "unit_id": unit_id},
+        pp,
+        screen="supervisor",
+        today=site_today(request),
+    )
+    return shop.board(conn, pp, dept=dept, project_id=project_id, unit_id=unit_id, filters=filters)
 
 
 @router.get("/stations")
@@ -41,9 +52,16 @@ def stations(
 
 @router.get("/stall")
 def stall(
+    request: Request,
     p: Principal = Depends(current_principal),  # noqa: B008
     d: Db = Depends(get_db),  # noqa: B008
     station_id: int = Query(ge=1),
+    find: dict[str, Any] = FIND,
 ) -> dict[str, Any]:
+    """The cards at one station. The find bar values narrow them; `station_id` here is the stall's station, so the
+    Station filter does not apply. Mine is the station's own work."""
     conn = d.conn
-    return shop.stall(conn, packets.policy_principal_for(conn, p), station_id)
+    pp = packets.policy_principal_for(conn, p)
+    raw = {**find, "station_id": None, "mine_station_id": find.get("mine_station_id") or station_id}
+    filters = search.parse_filters(raw, pp, screen="stall", today=site_today(request))
+    return shop.stall(conn, pp, station_id, filters)

server/packetstation/api/warehouse.py

@@ -12,9 +12,9 @@ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from fastapi import APIRouter, Depends, Query, Request
 
-from ..domain import packets
-from ..text import clean_text
+from ..domain import packets, search
 from .deps import Db, Principal, current_principal, get_db, settings_of
+from .packets import FIND
 
 router = APIRouter(prefix="/api/warehouse", tags=["warehouse"])
 
@@ -141,21 +141,22 @@ def board(
     request: Request,
     p: Principal = Depends(current_principal),  # noqa: B008
     d: Db = Depends(get_db),  # noqa: B008
-    q: str = Query("", max_length=200),
+    find: dict[str, Any] = FIND,
     project_id: int | None = Query(None),
     unit_id: int | None = Query(None),
-    dept: str = Query("", max_length=10),
 ) -> dict[str, Any]:
+    """The warehouse board. The find bar values narrow the cards of every column and the shorts list; the KPIs
+    follow the project and unit only."""
     conn = d.conn
     pp = packets.policy_principal_for(conn, p)
     tz = _tz(request)
-    filters: dict[str, Any] = {
-        "q": clean_text(q, 200),
-        "project_id": project_id,
-        "unit_id": unit_id,
-        "dept": dept.strip() or None,
-        "limit": BOARD_LIMIT,
-    }
+    parsed = search.parse_filters(
+        {**find, "project_id": project_id, "unit_id": unit_id},
+        pp,
+        screen="warehouse",
+        today=datetime.now(tz).date(),
+    )
+    filters: dict[str, Any] = {**search.board_filters(parsed), "limit": BOARD_LIMIT}
 
     columns: dict[str, list[dict[str, Any]]] = {st: [] for st in (*STAGES, "released")}
     for card in packets.list_cards(conn, pp, {**filters, "status": "warehouse"}):
@@ -182,4 +183,9 @@ def board(
             for sr in packets.rows(conn, SHORTS_SQL, (list(by_id),)):
                 shorts.append(_short_row(sr, by_id[int(sr["packet_id"])], today, now))
 
-    return {"kpis": _kpis(conn, filters), "columns": columns, "shorts": shorts}
+    return {
+        "kpis": _kpis(conn, filters),
+        "columns": columns,
+        "shorts": shorts,
+        "facets": search.facets(conn, project_id=project_id, unit_id=unit_id),
+    }