grzctl db tui: add --quarter/--year selection for “Detailed QC by LE” overview (closes #502) (#541)

## Summary

Adds optional `--quarter` and `--year` flags to `grzctl db tui` to
control which quarter/year is used for the **“Detailed QC by LE”**
overview panel.

## Behavior

- If `--quarter/--year` are **provided**: the “Detailed QC by LE” panel
shows the counts/ratio for that selected quarter/year.
- If **omitted**: the panel defaults to the current quarter/year (as
before).
- The other overview panels (**Submission count by state**, **Submission
count by consent**) remain **all-time totals** (unchanged).

## Why

Makes it easier to inspect detailed QC coverage for a specific reporting
quarter directly in the TUI, without changing the existing default
overview behavior.

Closes #502.

Author: jblesch

packages/grzctl/src/grzctl/commands/db/cli.py

@@ -326,7 +326,19 @@ def list_change_requests(ctx: click.Context, output_json: bool = False):
 
 @db.command("tui")
 @click.pass_context
-def tui(ctx: click.Context):
+@click.option(
+    "--quarter",
+    type=click.IntRange(min=1, max=4),
+    default=None,
+    help="Quarter (1-4) for the 'Detailed QC by LE' overview panel (default: current quarter).",
+)
+@click.option(
+    "--year",
+    type=click.IntRange(min=2024, max=9999),
+    default=None,
+    help="Year for the selected --quarter in the 'Detailed QC by LE' overview panel (default: current year).",
+)
+def tui(ctx: click.Context, quarter: int | None, year: int | None):
     """Starts the interactive terminal user interface to the database."""
     db_url = ctx.obj["db_url"]
     public_keys = ctx.obj["public_keys"]
@@ -344,7 +356,7 @@ def tui(ctx: click.Context):
     textual_handler.setFormatter(logging.Formatter(fmt=LOGGING_FORMAT, datefmt=LOGGING_DATEFMT))
     root_logger.addHandler(textual_handler)
 
-    app = DatabaseBrowser(database=database, public_keys=public_keys)
+    app = DatabaseBrowser(database=database, public_keys=public_keys, quarter=quarter, year=year)
     app.run()
 
 

packages/grzctl/src/grzctl/commands/db/tui.py

@@ -1,4 +1,3 @@
-import calendar
 import datetime
 import itertools
 import logging
@@ -11,6 +10,7 @@
 import textual
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 from grz_db.models.submission import Submission, SubmissionDb, SubmissionStateLog
+from grz_pydantic_models.dates import date_to_quarter_year, quarter_date_bounds
 from grz_pydantic_models.submission.metadata import SubmissionType
 from sqlalchemy import func as sqlfn
 from sqlalchemy.orm import selectinload
@@ -27,6 +27,13 @@
 _DEFAULT_SEARCH_LIMIT = 20
 
 
+def _resolve_quarter_year(today: datetime.date, quarter: int | None, year: int | None) -> tuple[int, int]:
+    default_quarter, default_year = date_to_quarter_year(today)
+    resolved_quarter = quarter if quarter is not None else default_quarter
+    resolved_year = year if year is not None else default_year
+    return resolved_quarter, resolved_year
+
+
 class SubmissionCountByStateTable(Static):
     def on_mount(self) -> None:
         self.loading = True
@@ -108,7 +115,7 @@ def on_mount(self) -> None:
         self.styles.border = ("round", self.app.theme_variables["foreground"])
 
     @textual.work
-    async def load(self, database: SubmissionDb) -> None:
+    async def load(self, database: SubmissionDb, quarter: int | None = None, year: int | None = None) -> None:
         self.loading = True
         with database._get_session() as session:
             statement = (
@@ -121,13 +128,8 @@ async def load(self, database: SubmissionDb) -> None:
             submission_qc_states = session.exec(statement).all()
 
         today = datetime.date.today()
-        quarter = ((today.month - 1) // 3) + 1
-        quarter_start_date = datetime.date(year=today.year, month=((quarter - 1) * 3) + 1, day=1)
-        quarter_end_month = quarter_start_date.month + 2
-        _quarter_end_month_first_weekday, days_in_quarter_end_month = calendar.monthrange(
-            quarter_start_date.year, quarter_end_month
-        )
-        quarter_end_date = quarter_start_date.replace(month=quarter_end_month, day=days_in_quarter_end_month)
+        resolved_quarter, resolved_year = _resolve_quarter_year(today, quarter, year)
+        quarter_start_date, quarter_end_date = quarter_date_bounds(year=resolved_year, quarter=resolved_quarter)
         logger.debug("Quarter: %s to %s", quarter_start_date, quarter_end_date)
         rows = []
         for submitter_id, group in itertools.groupby(
@@ -142,10 +144,10 @@ async def load(self, database: SubmissionDb) -> None:
             for _, submission_date, detailed_qc_passed in group:
                 if detailed_qc_passed is not None:
                     qced += 1
-                # current quarter
+                # resolved quarter
                 if (
                     (submission_date is not None)
-                    and (submission_date.year == today.year)
+                    and (submission_date.year == resolved_year)
                     and (quarter_start_date <= submission_date <= quarter_end_date)
                 ):
                     if detailed_qc_passed is not None:
@@ -162,7 +164,7 @@ async def load(self, database: SubmissionDb) -> None:
         table = rich.table.Table(
             rich.table.Column(header="Submitter", justify="center"),
             rich.table.Column(header="Total", justify="center"),
-            rich.table.Column(header=f"Q{quarter} {today.year}", justify="center"),
+            rich.table.Column(header=f"Q{resolved_quarter} {resolved_year}", justify="center"),
             rich.table.Column(header=today.strftime("%B"), justify="center"),
         )
         for submitter_id, qced, total, qced_quarter, total_quarter, qced_month, total_month in rows:
@@ -265,10 +267,19 @@ class DatabaseBrowser(App):
     ]
     CSS_PATH = "tui.css"
 
-    def __init__(self, database: SubmissionDb, public_keys: dict[str, Ed25519PublicKey], **kwargs) -> None:
+    def __init__(
+        self,
+        database: SubmissionDb,
+        public_keys: dict[str, Ed25519PublicKey],
+        quarter: int | None = None,
+        year: int | None = None,
+        **kwargs,
+    ) -> None:
         super().__init__(**kwargs)
         self._database = database
         self._public_keys = public_keys
+        self._quarter = quarter
+        self._year = year
 
     def compose(self) -> ComposeResult:
         with TabbedContent():
@@ -320,7 +331,9 @@ def on_mount(self) -> None:
     async def _refresh_overview(self) -> None:
         self.query_exactly_one(SubmissionCountByStateTable).load(self._database)
         self.query_exactly_one(SubmissionCountByConsentTable).load(self._database)
-        self.query_exactly_one(SubmissionCountByDetailedQCByLETable).load(self._database)
+        self.query_exactly_one(SubmissionCountByDetailedQCByLETable).load(
+            self._database, quarter=self._quarter, year=self._year
+        )
         table_states_latest = self.query_exactly_one("#table-states-latest", DataTable)
         table_states_latest.loading = True
         with self._database._get_session() as session:

packages/grzctl/tests/cli/test_db_tui.py

@@ -0,0 +1,107 @@
+import datetime
+import logging
+
+import click.testing
+import grzctl.cli
+import grzctl.commands.db.tui as db_tui
+import pytest
+
+
+@pytest.fixture
+def captured_browser_args(monkeypatch):
+    captured: dict[str, object] = {}
+
+    class DummyBrowser:
+        def __init__(self, *, database, public_keys, quarter=None, year=None, **kwargs):
+            captured["quarter"] = quarter
+            captured["year"] = year
+
+        def run(self):
+            captured["ran"] = True
+
+    import grzctl.commands.db.cli as db_cli
+
+    monkeypatch.setattr(db_cli, "DatabaseBrowser", DummyBrowser)
+    return captured
+
+
+def test_db_tui_passes_quarter_year(captured_browser_args, blank_database_config_path):
+    root_logger = logging.getLogger()
+    old_handlers = list(root_logger.handlers)
+    try:
+        runner = click.testing.CliRunner(catch_exceptions=False)
+        cli = grzctl.cli.build_cli()
+        result = runner.invoke(
+            cli,
+            [
+                "db",
+                "--config-file",
+                str(blank_database_config_path),
+                "tui",
+                "--quarter",
+                "2",
+                "--year",
+                "2025",
+            ],
+        )
+        assert result.exit_code == 0, result.stderr
+        assert captured_browser_args["quarter"] == 2
+        assert captured_browser_args["year"] == 2025
+        assert captured_browser_args.get("ran") is True
+    finally:
+        root_logger.handlers[:] = old_handlers
+
+
+def test_db_tui_passes_none_when_quarter_year_omitted(captured_browser_args, blank_database_config_path):
+    root_logger = logging.getLogger()
+    old_handlers = list(root_logger.handlers)
+    try:
+        runner = click.testing.CliRunner(catch_exceptions=False)
+        cli = grzctl.cli.build_cli()
+        result = runner.invoke(
+            cli,
+            [
+                "db",
+                "--config-file",
+                str(blank_database_config_path),
+                "tui",
+            ],
+        )
+        assert result.exit_code == 0, result.stderr
+        assert captured_browser_args["quarter"] is None
+        assert captured_browser_args["year"] is None
+        assert captured_browser_args.get("ran") is True
+    finally:
+        root_logger.handlers[:] = old_handlers
+
+
+def test_resolve_quarter_year_defaults_to_current_when_omitted(monkeypatch):
+    def fake_date_to_quarter_year(_today):
+        return (3, 2026)
+
+    monkeypatch.setattr(db_tui, "date_to_quarter_year", fake_date_to_quarter_year)
+
+    resolved_quarter, resolved_year = db_tui._resolve_quarter_year(
+        datetime.date(2026, 8, 12),
+        quarter=None,
+        year=None,
+    )
+
+    assert resolved_quarter == 3
+    assert resolved_year == 2026
+
+
+def test_resolve_quarter_year_prefers_explicit_values(monkeypatch):
+    def fake_date_to_quarter_year(_today):
+        return (3, 2026)
+
+    monkeypatch.setattr(db_tui, "date_to_quarter_year", fake_date_to_quarter_year)
+
+    resolved_quarter, resolved_year = db_tui._resolve_quarter_year(
+        datetime.date(2026, 8, 12),
+        quarter=2,
+        year=2025,
+    )
+
+    assert resolved_quarter == 2
+    assert resolved_year == 2025