Making long running operations asynchronous

.claude/settings.local.json

@@ -13,7 +13,28 @@
       "Bash(docker build *)",
       "Bash(git status *)",
       "Bash(git -C /home/iroddis/dev/armament/fitguide status --short)",
-      "Bash(git -C /home/iroddis/dev/armament/fitguide log --oneline -10)"
+      "Bash(git -C /home/iroddis/dev/armament/fitguide log --oneline -10)",
+      "Bash(node --check /Users/roddis/dev/armament/fitguide/app/static/js/sortable-tables.js)",
+      "Bash(sqlite3 /Users/roddis/dev/armament/fitguide/app.db \"select count\\(*\\) from users;\")",
+      "Bash(sqlite3 /Users/roddis/dev/armament/fitguide/app.db \"select count\\(*\\) from part_colours;\")",
+      "Bash(sqlite3 /Users/roddis/dev/armament/fitguide/app.db \"select count\\(*\\) from manufacturers;\")",
+      "Bash(curl -s -c /tmp/fg_cookies.txt -o /dev/null -w \"login:%{http_code}\\\\n\" -d \"email=admin@armament.com&password=changethis\" http://localhost:8000/login)",
+      "Bash(curl -s -b /tmp/fg_cookies.txt http://localhost:8000/admin/manufacturers)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code} %{content_type}\\\\n\" http://localhost:8000/static/js/sortable-tables.js)",
+      "Bash(curl -s -b /tmp/fg_cookies.txt \"http://localhost:8000/admin/augmented-parts\")",
+      "Bash(curl -s -b /tmp/fg_cookies.txt \"http://localhost:8000/admin/augmented-parts/filter?sort=colour&dir=desc\")",
+      "Bash(curl -s -b /tmp/fg_cookies.txt \"http://localhost:8000/admin/roles\")",
+      "Bash(curl -s http://localhost:8000/scopes)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\\\\n\" http://localhost:8000/scopes)",
+      "Bash(curl -s -b /tmp/fg_cookies.txt http://localhost:8000/scopes)",
+      "Bash(lsof -ti:8000 -sTCP:LISTEN)",
+      "Bash(xargs -r kill)",
+      "Bash(rm -f /tmp/fg_cookies.txt /private/tmp/claude-501/-Users-roddis-dev-armament-fitguide/7873fd9c-2f2b-4583-877e-72fc88718f24/scratchpad/smoke_sort.py)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\\\\n\" http://localhost:8000/login)",
+      "Bash(curl -s -b /tmp/fg_cookies.txt http://localhost:8000__TRACKED_VAR__)",
+      "Bash(sqlite3 app.db \"PRAGMA foreign_keys=ON; SELECT scope_model_id FROM augmented_parts WHERE id=1862;\")",
+      "Bash(sqlite3 app.db \"SELECT id, name FROM scope_models WHERE name='Viper';\")",
+      "Bash(sqlite3 app.db \"SELECT COUNT\\(*\\) FROM augmented_parts WHERE scope_model_id=\\(SELECT id FROM scope_models WHERE name='Viper'\\);\")"
     ]
   }
 }

alembic/versions/8012c00b0c04_add_augmented_part_notes_table.py

@@ -0,0 +1,43 @@
+"""add_augmented_part_notes_table
+
+Revision ID: 8012c00b0c04
+Revises: d1e2f3a4b5c6
+Create Date: 2026-07-31 09:07:06.137175
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "8012c00b0c04"
+down_revision: Union[str, None] = "d1e2f3a4b5c6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "augmented_part_notes",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("augmented_part_id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("username", sa.String(length=255), nullable=False),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["augmented_part_id"], ["augmented_parts.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("augmented_part_notes")

app/api/augmented_parts.py

@@ -4,10 +4,13 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.database import get_db
 from app.crud import audit as audit_crud
 from app.crud import augmented_part as augmented_part_crud
+from app.crud import augmented_part_note as augmented_part_note_crud
 from app.deps import require_permission
 from app.models.user import User
 from app.schemas.augmented_part import (
     AugmentedPartCreate,
+    AugmentedPartNoteCreate,
+    AugmentedPartNoteRead,
     AugmentedPartRead,
     AugmentedPartSyncResult,
     AugmentedPartUpdate,
@@ -132,3 +135,22 @@ async def delete_augmented_part(
             "AugmentedPart", augmented_part_id, label
         ),
     )
+
+
+@router.post(
+    "/{augmented_part_id}/notes",
+    response_model=AugmentedPartNoteRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_augmented_part_note(
+    augmented_part_id: int,
+    payload: AugmentedPartNoteCreate,
+    db: AsyncSession = Depends(get_db),
+    actor: User = Depends(require_permission("augmented_parts:write")),
+):
+    ap = await augmented_part_crud.get(db, augmented_part_id)
+    if ap is None:
+        raise HTTPException(status_code=404, detail="Augmented part not found")
+    return await augmented_part_note_crud.create(
+        db, augmented_part=ap, author=actor, body=payload.body
+    )

app/crud/augmented_part.py

@@ -4,9 +4,47 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.associations import augmented_part_imported_parts
 from app.models.augmented_part import AugmentedPart
 from app.models.imported_part import ImportedPart
+from app.models.manufacturer import Manufacturer
+from app.models.part_colour import PartColour
+from app.models.part_type import PartType
+from app.models.scope_model import ScopeModel
+from app.models.sub_part_type import SubPartType
 
 _RELATIONSHIPS = ["colour", "manufacturer", "scope_model", "part_type", "sub_part_type"]
 
+# Sortable columns for the admin list, keyed by the query-string "sort" value.
+# Columns backed by a related table's name require an outer join (the FK may be
+# nullable, e.g. scope_model_id) so unrelated rows still appear, ordered last.
+SORT_COLUMNS = {
+    "id": (AugmentedPart.id, None),
+    "sku": (AugmentedPart.sku, None),
+    "description": (AugmentedPart.description, None),
+    "colour": (PartColour.name, (PartColour, AugmentedPart.colour_id == PartColour.id)),
+    "manufacturer": (
+        Manufacturer.name,
+        (Manufacturer, AugmentedPart.manufacturer_id == Manufacturer.id),
+    ),
+    "scope_model": (
+        ScopeModel.name,
+        (ScopeModel, AugmentedPart.scope_model_id == ScopeModel.id),
+    ),
+    "part_type": (PartType.name, (PartType, AugmentedPart.part_type_id == PartType.id)),
+    "sub_part_type": (
+        SubPartType.name,
+        (SubPartType, AugmentedPart.sub_part_type_id == SubPartType.id),
+    ),
+}
+
+
+def _apply_sort(q, sort: str, direction: str):
+    column, join = SORT_COLUMNS.get(sort, SORT_COLUMNS["description"])
+    if join is not None:
+        table, cond = join
+        q = q.outerjoin(table, cond)
+    order = column.desc() if direction == "desc" else column.asc()
+    # AugmentedPart.id as a tiebreaker keeps paginated ordering stable.
+    return q.order_by(order, AugmentedPart.id)
+
 
 async def get(db: AsyncSession, augmented_part_id: int) -> AugmentedPart | None:
     return await db.get(AugmentedPart, augmented_part_id)
@@ -35,9 +73,7 @@ async def get_many(db: AsyncSession, ids: list[int]) -> list[AugmentedPart]:
     """Fetch augmented parts by id in one query (selectin relationships loaded)."""
     if not ids:
         return []
-    result = await db.execute(
-        select(AugmentedPart).where(AugmentedPart.id.in_(ids))
-    )
+    result = await db.execute(select(AugmentedPart).where(AugmentedPart.id.in_(ids)))
     return list(result.scalars().all())
 
 
@@ -49,6 +85,8 @@ async def list_filtered(
     scope_model_id: int | None = None,
     part_type_id: int | None = None,
     sub_part_type_id: int | None = None,
+    sort: str = "description",
+    direction: str = "asc",
     skip: int = 0,
     limit: int = 100,
 ) -> list[AugmentedPart]:
@@ -65,9 +103,8 @@ async def list_filtered(
         q = q.where(AugmentedPart.part_type_id == part_type_id)
     if sub_part_type_id is not None:
         q = q.where(AugmentedPart.sub_part_type_id == sub_part_type_id)
-    result = await db.execute(
-        q.order_by(AugmentedPart.description).offset(skip).limit(limit)
-    )
+    q = _apply_sort(q, sort, direction)
+    result = await db.execute(q.offset(skip).limit(limit))
     return list(result.scalars().all())
 
 

app/crud/augmented_part_note.py

@@ -0,0 +1,19 @@
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.augmented_part import AugmentedPart, AugmentedPartNote
+from app.models.user import User
+
+
+async def create(
+    db: AsyncSession, *, augmented_part: AugmentedPart, author: User, body: str
+) -> AugmentedPartNote:
+    note = AugmentedPartNote(
+        augmented_part_id=augmented_part.id,
+        user_id=author.id,
+        username=author.full_name or author.email,
+        body=body,
+    )
+    db.add(note)
+    await db.commit()
+    await db.refresh(note)
+    return note

app/crud/imported_part.py

@@ -16,14 +16,37 @@ _FIELDS = frozenset(
     }
 )
 
+# Sortable columns for the admin list, keyed by the query-string "sort" value.
+SORT_COLUMNS = {
+    "InventoryID": ImportedPart.InventoryID,
+    "Description": ImportedPart.Description,
+    "TBXColour": ImportedPart.TBXColour,
+    "ProductMaxThreadDepthmm": ImportedPart.ProductMaxThreadDepthmm,
+    "ProductMaxThreadDepthin": ImportedPart.ProductMaxThreadDepthin,
+    "ProductODmm": ImportedPart.ProductODmm,
+    "ProductODin": ImportedPart.ProductODin,
+    "TBXThreadAttribute": ImportedPart.TBXThreadAttribute,
+}
+
+
+def _apply_sort(q, sort: str, direction: str):
+    column = SORT_COLUMNS.get(sort, ImportedPart.InventoryID)
+    order = column.desc() if direction == "desc" else column.asc()
+    return q.order_by(order, ImportedPart.InventoryID)
+
 
 async def get(db: AsyncSession, inventory_id: str) -> ImportedPart | None:
     return await db.get(ImportedPart, inventory_id)
 
 
-async def list_all(db: AsyncSession, skip: int = 0, limit: int = 500) -> list[ImportedPart]:
+async def list_all(
+    db: AsyncSession, skip: int = 0, limit: int = 500
+) -> list[ImportedPart]:
     result = await db.execute(
-        select(ImportedPart).order_by(ImportedPart.InventoryID).offset(skip).limit(limit)
+        select(ImportedPart)
+        .order_by(ImportedPart.InventoryID)
+        .offset(skip)
+        .limit(limit)
     )
     return list(result.scalars().all())
 
@@ -31,13 +54,16 @@ async def list_all(db: AsyncSession, skip: int = 0, limit: int = 500) -> list[Im
 async def list_filtered(
     db: AsyncSession,
     description: str = "",
+    sort: str = "InventoryID",
+    direction: str = "asc",
     skip: int = 0,
     limit: int = 500,
 ) -> list[ImportedPart]:
     q = select(ImportedPart)
     if description.strip():
         q = q.where(ImportedPart.Description.ilike(f"%{description.strip()}%"))
-    result = await db.execute(q.order_by(ImportedPart.InventoryID).offset(skip).limit(limit))
+    q = _apply_sort(q, sort, direction)
+    result = await db.execute(q.offset(skip).limit(limit))
     return list(result.scalars().all())
 
 
@@ -78,7 +104,11 @@ async def upsert_bulk(db: AsyncSession, records: list[dict]) -> tuple[int, int]:
         return 0, 0
 
     clean = [
-        {k: str(v).strip() if v is not None else None for k, v in r.items() if k in _FIELDS}
+        {
+            k: str(v).strip() if v is not None else None
+            for k, v in r.items()
+            if k in _FIELDS
+        }
         for r in records
         if r.get("InventoryID")
     ]
@@ -88,7 +118,9 @@ async def upsert_bulk(db: AsyncSession, records: list[dict]) -> tuple[int, int]:
     incoming_ids = {r["InventoryID"] for r in clean}
 
     result = await db.execute(
-        select(ImportedPart.InventoryID).where(ImportedPart.InventoryID.in_(incoming_ids))
+        select(ImportedPart.InventoryID).where(
+            ImportedPart.InventoryID.in_(incoming_ids)
+        )
     )
     existing_ids = {row[0] for row in result.all()}
 
@@ -103,7 +135,9 @@ async def upsert_bulk(db: AsyncSession, records: list[dict]) -> tuple[int, int]:
         vals = {k: v for k, v in record.items() if k != "InventoryID"}
         if vals:
             await db.execute(
-                update(ImportedPart).where(ImportedPart.InventoryID == inv_id).values(vals)
+                update(ImportedPart)
+                .where(ImportedPart.InventoryID == inv_id)
+                .values(vals)
             )
 
     await db.commit()

app/models/__init__.py

@@ -8,7 +8,7 @@ from app.models.associations import (
 from app.models.attachment_point import AttachmentPoint
 from app.models.attachment_point_name import AttachmentPointName
 from app.models.audit_log import AuditLog
-from app.models.augmented_part import AugmentedPart
+from app.models.augmented_part import AugmentedPart, AugmentedPartNote
 from app.models.clamp_connection import ClampConnection
 from app.models.fit import Fit, FitLabel, FitNote
 from app.models.imported_part import ImportedPart
@@ -32,6 +32,7 @@ __all__ = [
     "AttachmentPointName",
     "AuditLog",
     "AugmentedPart",
+    "AugmentedPartNote",
     "ClampConnection",
     "Fit",
     "FitLabel",

app/models/augmented_part.py

@@ -1,4 +1,6 @@
-from sqlalchemy import ForeignKey, String
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, Text, func
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.core.database import Base
@@ -45,3 +47,30 @@ class AugmentedPart(Base):
     scope_model: Mapped[ScopeModel | None] = relationship(lazy="selectin")
     part_type: Mapped[PartType] = relationship(lazy="selectin")
     sub_part_type: Mapped[SubPartType | None] = relationship(lazy="selectin")
+    notes: Mapped[list["AugmentedPartNote"]] = relationship(
+        back_populates="augmented_part",
+        lazy="selectin",
+        order_by="AugmentedPartNote.created_at",
+        cascade="all, delete-orphan",
+    )
+
+
+class AugmentedPartNote(Base):
+    __tablename__ = "augmented_part_notes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    augmented_part_id: Mapped[int] = mapped_column(
+        ForeignKey("augmented_parts.id", ondelete="CASCADE"), nullable=False
+    )
+    user_id: Mapped[int | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    # Denormalized snapshot of who wrote the note (mirrors FitNote.username), so
+    # the note stays attributable even if the user is later deleted.
+    username: Mapped[str] = mapped_column(String(255), nullable=False)
+    body: Mapped[str] = mapped_column(Text, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+    augmented_part: Mapped[AugmentedPart] = relationship(back_populates="notes")

app/schemas/augmented_part.py

@@ -1,4 +1,6 @@
-from pydantic import BaseModel, ConfigDict
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, field_validator
 
 from app.schemas.manufacturer import ManufacturerRead
 from app.schemas.part_colour import PartColourRead
@@ -7,6 +9,28 @@ from app.schemas.scope_model import ScopeModelRead
 from app.schemas.sub_part_type import SubPartTypeRead
 
 
+class AugmentedPartNoteCreate(BaseModel):
+    body: str
+
+    @field_validator("body")
+    @classmethod
+    def validate_body(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("body must not be blank")
+        return v.strip()
+
+
+class AugmentedPartNoteRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    augmented_part_id: int
+    user_id: int | None
+    username: str
+    body: str
+    created_at: datetime
+
+
 class AugmentedPartBase(BaseModel):
     sku: str | None = None
     description: str
@@ -46,3 +70,4 @@ class AugmentedPartRead(AugmentedPartBase):
     scope_model: ScopeModelRead | None
     part_type: PartTypeRead
     sub_part_type: SubPartTypeRead | None
+    notes: list[AugmentedPartNoteRead] = []

app/services/jobs.py

@@ -0,0 +1,74 @@
+"""Lightweight in-process tracking for long-running admin operations.
+
+Jobs live in a module-level dict, so this only works correctly for a single
+OS process (the app's current deployment: one uvicorn worker, no multi-process
+or multi-replica setup — see ``entrypoint.sh`` / ``docker-compose.yml``). If
+the app is ever scaled to multiple workers/replicas, this needs to move to
+shared storage (a DB table, Redis) so a poll request landing on a different
+process can still see the job.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+_MAX_FINISHED_AGE_SECONDS = 3600
+
+
+@dataclass
+class Job:
+    id: str
+    kind: str
+    status: str = "running"  # running | done | error
+    message: str = "Working…"
+    result: object | None = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    finished_at: datetime | None = None
+
+
+_jobs: dict[str, Job] = {}
+
+
+def get(job_id: str) -> Job | None:
+    return _jobs.get(job_id)
+
+
+def _evict_stale() -> None:
+    now = datetime.now(UTC)
+    stale = [
+        job_id
+        for job_id, job in _jobs.items()
+        if job.finished_at
+        and (now - job.finished_at).total_seconds() > _MAX_FINISHED_AGE_SECONDS
+    ]
+    for job_id in stale:
+        del _jobs[job_id]
+
+
+def start(kind: str, run: Callable[[Job], Awaitable[None]]) -> Job:
+    """Create a job, launch ``run(job)`` in the background, and return it immediately.
+
+    ``run`` is responsible for updating ``job.status``/``job.message``/``job.result``
+    to reflect the outcome, including catching its own errors. Any exception that
+    escapes anyway is caught here as a last resort so the job doesn't hang forever
+    in "running" state.
+    """
+    _evict_stale()
+    job = Job(id=uuid.uuid4().hex, kind=kind)
+    _jobs[job.id] = job
+
+    async def _runner() -> None:
+        try:
+            await run(job)
+        except Exception as exc:
+            job.status = "error"
+            job.message = f"{kind} failed: {exc}"
+        finally:
+            job.finished_at = datetime.now(UTC)
+
+    asyncio.create_task(_runner())
+    return job

app/static/css/style.css

@@ -247,6 +247,37 @@ h2 {
   gap: 0.4rem;
 }
 
+/* Sortable table headers */
+table.sortable thead th:not([data-sort-off]) {
+  cursor: pointer;
+  user-select: none;
+}
+
+table.sortable thead th:not([data-sort-off]):hover {
+  color: var(--text);
+}
+
+table.sortable thead th[aria-sort]::after {
+  margin-left: 0.3rem;
+}
+
+table.sortable thead th[aria-sort="ascending"]::after {
+  content: "\25B2";
+}
+
+table.sortable thead th[aria-sort="descending"]::after {
+  content: "\25BC";
+}
+
+.sort-link {
+  color: inherit;
+  text-decoration: none;
+}
+
+.sort-link:hover {
+  text-decoration: underline;
+}
+
 /* Tags / definition lists */
 .tag {
   display: inline-block;

app/static/js/sortable-tables.js

@@ -0,0 +1,77 @@
+(function () {
+  "use strict";
+
+  function getCellText(row, index) {
+    var cell = row.children[index];
+    return cell ? cell.textContent.trim() : "";
+  }
+
+  function isEmptyValue(text) {
+    return text === "" || text === "—";
+  }
+
+  function isPureNumber(text) {
+    return /^-?\d+(\.\d+)?$/.test(text);
+  }
+
+  function columnIsNumeric(rows, index) {
+    var sawValue = false;
+    for (var i = 0; i < rows.length; i++) {
+      var text = getCellText(rows[i], index);
+      if (isEmptyValue(text)) continue;
+      sawValue = true;
+      if (!isPureNumber(text)) return false;
+    }
+    return sawValue;
+  }
+
+  function compareRows(a, b, index, numeric, dir) {
+    var textA = getCellText(a, index);
+    var textB = getCellText(b, index);
+    var emptyA = isEmptyValue(textA);
+    var emptyB = isEmptyValue(textB);
+    if (emptyA && emptyB) return 0;
+    if (emptyA) return 1;
+    if (emptyB) return -1;
+
+    var result = numeric
+      ? parseFloat(textA) - parseFloat(textB)
+      : textA.localeCompare(textB, undefined, { numeric: true, sensitivity: "base" });
+    return dir === "desc" ? -result : result;
+  }
+
+  function sortTable(table, th) {
+    var thead = table.tHead;
+    var tbody = table.tBodies[0];
+    if (!thead || !tbody) return;
+
+    var headerRow = thead.rows[0];
+    var index = Array.prototype.indexOf.call(headerRow.children, th);
+    if (index === -1) return;
+
+    var rows = Array.prototype.slice.call(tbody.rows);
+    if (rows.length < 2) return;
+
+    var nextDir = th.getAttribute("data-sort-dir") === "asc" ? "desc" : "asc";
+    Array.prototype.forEach.call(headerRow.children, function (cell) {
+      cell.removeAttribute("data-sort-dir");
+      cell.removeAttribute("aria-sort");
+    });
+    th.setAttribute("data-sort-dir", nextDir);
+    th.setAttribute("aria-sort", nextDir === "asc" ? "ascending" : "descending");
+
+    var numeric = columnIsNumeric(rows, index);
+    rows.sort(function (a, b) {
+      return compareRows(a, b, index, numeric, nextDir);
+    });
+    rows.forEach(function (row) {
+      tbody.appendChild(row);
+    });
+  }
+
+  document.addEventListener("click", function (event) {
+    var th = event.target.closest("table.sortable thead th");
+    if (!th || th.hasAttribute("data-sort-off") || th.textContent.trim() === "") return;
+    sortTable(th.closest("table"), th);
+  });
+})();

app/templates/_scopes_table_card.html

@@ -11,7 +11,7 @@
   {%- endif -%}
 {%- endmacro -%}
 <div id="scopes-table-card" class="card" style="overflow-x:auto">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>Scope</th>
@@ -21,7 +21,7 @@
         <th>Magnification</th>
         <th>Objective thread</th>
         {% for ct in column_types %}
-          <th>{{ ct.name }}</th>
+          <th data-sort-off>{{ ct.name }}</th>
         {% endfor %}
       </tr>
     </thead>

app/templates/admin/_attachment_point_names_table.html

@@ -1,5 +1,5 @@
 <div id="attachment-point-name-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th>

app/templates/admin/_attachment_point_row.html

@@ -20,7 +20,6 @@
 {% endif %}
 <tr id="attachment-point-{{ ap.id }}">
   <td>{{ ap.id }}</td>
-  <td>{{ ap.augmented_part.description | truncate(40) }}</td>
   <td>{{ ap.attachment_point_name.name }}</td>
   <td>{{ conn_type }}</td>
   <td><code>{{ conn_label }}</code></td>

app/templates/admin/_attachment_points_table.html

@@ -1,9 +1,8 @@
 <div id="attachment-point-list" class="card" style="overflow-x:auto">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th>
-        <th>Augmented Part</th>
         <th>Point Name</th>
         <th>Connection Type</th>
         <th>Connection</th>

app/templates/admin/_augmented_part_fits.html

@@ -45,6 +45,16 @@
       </select>
     </label>
     <div id="ap-{{ augmented_part_id }}-fit-other-points"></div>
+    <label>Fit type
+      <select name="label">
+        <option value="exact" selected>Exact</option>
+        <option value="possible">Possible</option>
+        <option value="none">None</option>
+      </select>
+    </label>
+    <label>Note (optional)
+      <input type="text" name="note" placeholder="Add a note…">
+    </label>
     <button type="submit" class="btn btn-primary">Add fit</button>
   </form>
   {% endif %}

app/templates/admin/_augmented_part_notes.html

@@ -0,0 +1,22 @@
+<div id="ap-{{ augmented_part_id }}-notes" class="ap-inline-section">
+  <h3>Notes</h3>
+
+  <div class="fit-notes">
+    {% for note in notes %}
+      <div class="fit-note">
+        <span class="fit-note-meta">{{ note.username }} · {{ note.created_at.strftime("%Y-%m-%d %H:%M") }}</span>
+        <p class="fit-note-body">{{ note.body }}</p>
+      </div>
+    {% else %}
+      <p class="muted" style="font-size:0.85rem;margin:0 0 0.5rem">No notes recorded yet.</p>
+    {% endfor %}
+    {% if can_write_notes %}
+    <form hx-post="/admin/augmented-parts/{{ augmented_part_id }}/notes"
+          hx-target="#ap-{{ augmented_part_id }}-notes" hx-swap="outerHTML"
+          class="inline-edit fit-note-form">
+      <input type="text" name="body" placeholder="Add a note…" required>
+      <button type="submit" class="btn btn-ghost">Add note</button>
+    </form>
+    {% endif %}
+  </div>
+</div>

app/templates/admin/_augmented_parts_table.html

@@ -10,6 +10,8 @@
         hx-target="#augmented-parts-table-card"
         hx-trigger="input delay:300ms, change"
         hx-swap="outerHTML">
+    <input type="hidden" name="sort" value="{{ sort }}">
+    <input type="hidden" name="dir" value="{{ dir }}">
     <input type="text" name="description" placeholder="Filter by description…" value="{{ filter_description or '' }}">
     <select name="colour_id">
       <option value="">All colours</option>

app/templates/admin/_augmented_parts_table_card.html

@@ -1,16 +1,17 @@
+{% from "admin/_sort_macros.html" import sort_th %}
 <div id="augmented-parts-table-card" class="card">
   {% include "admin/_pagination.html" %}
   <table class="table">
     <thead>
       <tr>
-        <th>ID</th>
-        <th>SKU</th>
-        <th>Description</th>
-        <th>Colour</th>
-        <th>Manufacturer</th>
-        <th>Model</th>
-        <th>Type</th>
-        <th>Sub Type</th>
+        {{ sort_th("id", "ID", sort_headers) }}
+        {{ sort_th("sku", "SKU", sort_headers) }}
+        {{ sort_th("description", "Description", sort_headers) }}
+        {{ sort_th("colour", "Colour", sort_headers) }}
+        {{ sort_th("manufacturer", "Manufacturer", sort_headers) }}
+        {{ sort_th("scope_model", "Model", sort_headers) }}
+        {{ sort_th("part_type", "Type", sort_headers) }}
+        {{ sort_th("sub_part_type", "Sub Type", sort_headers) }}
         <th></th>
       </tr>
     </thead>

app/templates/admin/_clamp_connections_table.html

@@ -1,5 +1,5 @@
 <div id="clamp-connection-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th>

app/templates/admin/_fit_other_points_select.html

@@ -1,6 +1,13 @@
+{% if points %}
 <select name="other_attachment_point_id" required>
   <option value="">— select —</option>
   {% for p in points %}
     <option value="{{ p.id }}">{{ p.attachment_point_name.name }}</option>
   {% endfor %}
 </select>
+{% else %}
+<input type="hidden" name="other_attachment_point_id" value="">
+<p class="muted" style="font-size:0.85rem;margin:0">
+  This part has no attachment points yet — one matching yours will be created automatically.
+</p>
+{% endif %}

app/templates/admin/_imported_parts_table.html

@@ -11,6 +11,8 @@
           hx-target="#imported-parts-table-card"
           hx-trigger="input delay:300ms, change"
           hx-swap="outerHTML">
+      <input type="hidden" name="sort" value="{{ sort }}">
+      <input type="hidden" name="dir" value="{{ dir }}">
       <input type="text" name="description" placeholder="Filter by description…" value="{{ filter_description or '' }}">
     </form>
   </div>

app/templates/admin/_imported_parts_table_card.html

@@ -1,16 +1,17 @@
+{% from "admin/_sort_macros.html" import sort_th %}
 <div id="imported-parts-table-card" class="card" style="overflow-x:auto">
   {% include "admin/_pagination.html" %}
   <table class="table">
     <thead>
       <tr>
-        <th>InventoryID</th>
-        <th>Description</th>
-        <th>TBX Colour</th>
-        <th>Max Thread Depth (mm)</th>
-        <th>Max Thread Depth (in)</th>
-        <th>OD (mm)</th>
-        <th>OD (in)</th>
-        <th>Thread Attribute</th>
+        {{ sort_th("InventoryID", "InventoryID", sort_headers) }}
+        {{ sort_th("Description", "Description", sort_headers) }}
+        {{ sort_th("TBXColour", "TBX Colour", sort_headers) }}
+        {{ sort_th("ProductMaxThreadDepthmm", "Max Thread Depth (mm)", sort_headers) }}
+        {{ sort_th("ProductMaxThreadDepthin", "Max Thread Depth (in)", sort_headers) }}
+        {{ sort_th("ProductODmm", "OD (mm)", sort_headers) }}
+        {{ sort_th("ProductODin", "OD (in)", sort_headers) }}
+        {{ sort_th("TBXThreadAttribute", "Thread Attribute", sort_headers) }}
       </tr>
     </thead>
     <tbody>

app/templates/admin/_job_progress.html

@@ -0,0 +1,7 @@
+<div id="{{ container_id }}"
+     hx-get="{{ poll_url }}"
+     hx-trigger="load delay:1s"
+     hx-swap="outerHTML"
+     class="{{ extra_class or '' }}">
+  <p class="muted">⏳ {{ job.message }}</p>
+</div>

app/templates/admin/_job_progress_inline.html

@@ -0,0 +1,5 @@
+<span id="{{ container_id }}"
+      hx-get="{{ poll_url }}"
+      hx-trigger="load delay:1s"
+      hx-swap="outerHTML"
+      class="muted">⏳ {{ job.message }}</span>

app/templates/admin/_manufacturers_table.html

@@ -1,8 +1,8 @@
 <div id="manufacturer-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
-        <th>ID</th><th>Name</th><th>Homepage</th><th>Logo</th><th></th>
+        <th>ID</th><th>Name</th><th>Homepage</th><th data-sort-off>Logo</th><th></th>
       </tr>
     </thead>
     <tbody>

app/templates/admin/_part_colours_table.html

@@ -1,5 +1,5 @@
 <div id="part-colour-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th>

app/templates/admin/_part_types_table.html

@@ -1,5 +1,5 @@
 <div id="part-type-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th><th>Name</th><th></th>

app/templates/admin/_roles_table.html

@@ -1,7 +1,7 @@
 <div id="role-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
-      <tr><th>ID</th><th>Name</th><th>Description</th><th>Permissions</th><th>Default</th><th></th></tr>
+      <tr><th>ID</th><th>Name</th><th>Description</th><th data-sort-off>Permissions</th><th data-sort-off>Default</th><th></th></tr>
     </thead>
     <tbody>
       {% for r in roles %}

app/templates/admin/_scope_import_result.html

@@ -1,3 +1,4 @@
+<div id="{{ container_id or 'scope-import-result-body' }}">
 {% if error %}
 <div class="card">
   <p style="color:var(--color-danger,#c00)">{{ error }}</p>
@@ -39,3 +40,4 @@
   {% endif %}
 </div>
 {% endif %}
+</div>

app/templates/admin/_scope_models_table.html

@@ -1,5 +1,5 @@
 <div id="scope-model-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th><th>Name</th><th>Manufacturer</th><th>Product Page</th><th></th>

app/templates/admin/_sort_macros.html

@@ -0,0 +1,13 @@
+{% macro sort_th(key, label, sort_headers) %}
+  {% if sort_headers and key in sort_headers %}
+    {% set h = sort_headers[key] %}
+    <th>
+      <a href="#" class="sort-link{{ ' active' if h.active else '' }}"
+         hx-get="{{ h.url }}"
+         hx-target="{{ h.target_id }}"
+         hx-swap="outerHTML">{{ label }}{% if h.active %}<span aria-hidden="true">{{ ' ▲' if h.dir == 'asc' else ' ▼' }}</span>{% endif %}</a>
+    </th>
+  {% else %}
+    <th>{{ label }}</th>
+  {% endif %}
+{% endmacro %}

app/templates/admin/_static_connections_table.html

@@ -1,5 +1,5 @@
 <div id="static-connection-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th>

app/templates/admin/_sub_part_types_table.html

@@ -1,5 +1,5 @@
 <div id="sub-part-type-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
         <th>ID</th><th>Name</th><th>Parent Type</th><th></th>

app/templates/admin/_users_table.html

@@ -1,8 +1,8 @@
 <div id="user-list" class="card">
-  <table class="table">
+  <table class="table sortable">
     <thead>
       <tr>
-        <th>ID</th><th>Email</th><th>Name</th><th>Active</th><th>Superuser</th><th>Roles</th><th></th>
+        <th>ID</th><th>Email</th><th>Name</th><th>Active</th><th>Superuser</th><th data-sort-off>Roles</th><th></th>
       </tr>
     </thead>
     <tbody>

app/templates/admin/audit_log.html

@@ -7,7 +7,7 @@
 
   <div class="card">
     {% if entries %}
-    <table class="table">
+    <table class="table sortable">
       <thead>
         <tr>
           <th>Time</th>

app/templates/admin/augmented_part_detail.html

@@ -61,5 +61,9 @@
     {% include "admin/_augmented_part_fits.html" %}
   </div>
   {% endif %}
+
+  <div class="card">
+    {% include "admin/_augmented_part_notes.html" %}
+  </div>
 </main>
 {% endblock %}

app/templates/base.html

@@ -4,10 +4,12 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>{% block title %}{{ app_name }}{% endblock %}</title>
+  <link rel="icon" href="/static/favicon.ico" sizes="any">
   <link rel="stylesheet" href="/static/css/style.css">
   <script src="https://unpkg.com/htmx.org@1.9.12"
           integrity="sha384-ujb1lZYygJmzgSwoxRggbCHcjc0rB2XoQrxeTUQyRjrOnlCoYta87iKBWq3EsdM2"
           crossorigin="anonymous"></script>
+  <script src="/static/js/sortable-tables.js" defer></script>
 </head>
 <body>
   {% block body %}{% endblock %}

app/web/admin.py

@@ -16,9 +16,10 @@ from fastapi import (
 from fastapi.responses import HTMLResponse, RedirectResponse, Response
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.database import get_db
+from app.core.database import AsyncSessionLocal, get_db
 from app.crud import audit as audit_crud
 from app.crud import augmented_part as augmented_part_crud
+from app.crud import augmented_part_note as augmented_part_note_crud
 from app.crud import imported_part as imported_part_crud
 from app.crud import imported_part_config as imported_part_config_crud
 from app.crud import iso_thread as iso_thread_crud
@@ -43,6 +44,7 @@ from app.models.unc_thread import UncSeries
 from app.models.user import User
 from app.services import augmented_part_sync as augmented_part_sync_service
 from app.services import fit_matching as fit_matching_service
+from app.services import jobs
 from app.services import odata as odata_service
 from app.services import scope_import as scope_import_service
 from app.web.templates import templates
@@ -52,6 +54,11 @@ router = APIRouter(prefix="/admin", include_in_schema=False)
 _PAGE_SIZE = 50
 
 
+def _query_url(base_path: str, params: dict) -> str:
+    clean = {k: v for k, v in params.items() if v not in (None, "", 0)}
+    return f"{base_path}?{urllib.parse.urlencode(clean)}"
+
+
 def _paginate(
     base_path: str,
     filter_params: dict,
@@ -65,10 +72,9 @@ def _paginate(
     skip = (page - 1) * page_size
 
     def _url(p: int) -> str:
-        params = {k: v for k, v in filter_params.items() if v not in (None, "", 0)}
-        params["page"] = p
-        params["page_size"] = page_size
-        return f"{base_path}?{urllib.parse.urlencode(params)}"
+        return _query_url(
+            base_path, {**filter_params, "page": p, "page_size": page_size}
+        )
 
     return {
         "page": page,
@@ -84,6 +90,33 @@ def _paginate(
     }
 
 
+def _sort_headers(
+    base_path: str,
+    filter_params: dict,
+    columns: list[str],
+    sort: str,
+    direction: str,
+    target_id: str,
+) -> dict:
+    """Per-column header link context for click-to-sort table headers.
+
+    ``filter_params`` should NOT include "sort"/"dir"/"page" — those are added here.
+    """
+    headers = {}
+    for key in columns:
+        next_dir = "desc" if sort == key and direction == "asc" else "asc"
+        headers[key] = {
+            "url": _query_url(
+                base_path,
+                {**filter_params, "sort": key, "dir": next_dir, "page": 1},
+            ),
+            "active": sort == key,
+            "dir": direction if sort == key else None,
+            "target_id": target_id,
+        }
+    return headers
+
+
 def web_require(*perms: str):
     """Web dependency: allow superusers or holders of all given permissions."""
 
@@ -1205,10 +1238,50 @@ async def delete_sub_part_type(
 
 # --- Imported Parts ----------------------------------------------------------
 
+_IMPORTED_PARTS_SORT_COLUMNS = [
+    "InventoryID",
+    "Description",
+    "TBXColour",
+    "ProductMaxThreadDepthmm",
+    "ProductMaxThreadDepthin",
+    "ProductODmm",
+    "ProductODin",
+    "TBXThreadAttribute",
+]
+
+
+async def _default_imported_parts_table_ctx(db: AsyncSession) -> dict:
+    """Table-card context (default sort, no filter, page 1) after a refresh."""
+    total = await imported_part_crud.count(db)
+    pagination = _paginate(
+        "/admin/imported-parts/filter",
+        {},
+        1,
+        _PAGE_SIZE,
+        total,
+        "#imported-parts-table-card",
+    )
+    return {
+        "parts": await imported_part_crud.list_filtered(db, limit=_PAGE_SIZE),
+        "pagination": pagination,
+        "sort_headers": _sort_headers(
+            "/admin/imported-parts/filter",
+            {},
+            _IMPORTED_PARTS_SORT_COLUMNS,
+            "InventoryID",
+            "asc",
+            "#imported-parts-table-card",
+        ),
+        "sort": "InventoryID",
+        "dir": "asc",
+    }
+
 
 @router.get("/imported-parts", response_class=HTMLResponse)
 async def imported_parts_page(
     request: Request,
+    sort: str = "InventoryID",
+    dir: str = "asc",
     db: AsyncSession = Depends(get_db),
     user: User = Depends(web_require("imported_parts:read")),
 ):
@@ -1219,19 +1292,37 @@ async def imported_parts_page(
         "has_password": bool(config and config.password),
     }
     total = await imported_part_crud.count(db)
-    parts = await imported_part_crud.list_filtered(db, limit=_PAGE_SIZE)
+    parts = await imported_part_crud.list_filtered(
+        db, sort=sort, direction=dir, limit=_PAGE_SIZE
+    )
     pagination = _paginate(
         "/admin/imported-parts/filter",
-        {},
+        {"sort": sort, "dir": dir},
         1,
         _PAGE_SIZE,
         total,
         "#imported-parts-table-card",
     )
+    sort_headers = _sort_headers(
+        "/admin/imported-parts/filter",
+        {},
+        _IMPORTED_PARTS_SORT_COLUMNS,
+        sort,
+        dir,
+        "#imported-parts-table-card",
+    )
     return templates.TemplateResponse(
         request,
         "admin/imported_parts.html",
-        {"user": user, "config": config_view, "parts": parts, "pagination": pagination},
+        {
+            "user": user,
+            "config": config_view,
+            "parts": parts,
+            "pagination": pagination,
+            "sort_headers": sort_headers,
+            "sort": sort,
+            "dir": dir,
+        },
     )
 
 
@@ -1273,19 +1364,8 @@ async def refresh_imported_parts(
     config = await imported_part_config_crud.get(db)
 
     async def _imported_table_ctx(sync_result=None, sync_error=None):
-        total = await imported_part_crud.count(db)
-        parts = await imported_part_crud.list_filtered(db, limit=_PAGE_SIZE)
-        pagination = _paginate(
-            "/admin/imported-parts/filter",
-            {},
-            1,
-            _PAGE_SIZE,
-            total,
-            "#imported-parts-table-card",
-        )
         return {
-            "parts": parts,
-            "pagination": pagination,
+            **await _default_imported_parts_table_ctx(db),
             "sync_result": sync_result,
             "sync_error": sync_error,
         }
@@ -1328,15 +1408,18 @@ async def refresh_imported_parts(
 async def filter_imported_parts(
     request: Request,
     description: str = "",
+    sort: str = "InventoryID",
+    dir: str = "asc",
     page: int = 1,
     page_size: int = _PAGE_SIZE,
     db: AsyncSession = Depends(get_db),
     _: User = Depends(web_require("imported_parts:read")),
 ):
     total = await imported_part_crud.count_filtered(db, description=description)
+    filter_params = {"description": description}
     pagination = _paginate(
         "/admin/imported-parts/filter",
-        {"description": description},
+        {**filter_params, "sort": sort, "dir": dir},
         page,
         page_size,
         total,
@@ -1345,13 +1428,29 @@ async def filter_imported_parts(
     parts = await imported_part_crud.list_filtered(
         db,
         description=description,
+        sort=sort,
+        direction=dir,
         skip=pagination["skip"],
         limit=page_size,
     )
+    sort_headers = _sort_headers(
+        "/admin/imported-parts/filter",
+        filter_params,
+        _IMPORTED_PARTS_SORT_COLUMNS,
+        sort,
+        dir,
+        "#imported-parts-table-card",
+    )
     return templates.TemplateResponse(
         request,
         "admin/_imported_parts_table_card.html",
-        {"parts": parts, "pagination": pagination},
+        {
+            "parts": parts,
+            "pagination": pagination,
+            "sort_headers": sort_headers,
+            "sort": sort,
+            "dir": dir,
+        },
     )
 
 
@@ -1371,11 +1470,21 @@ async def scope_import_page(
     )
 
 
+_SCOPE_IMPORT_STATUS_ID = "scope-import-status"
+
+
+def _scope_import_progress_ctx(job: jobs.Job) -> dict:
+    return {
+        "container_id": _SCOPE_IMPORT_STATUS_ID,
+        "poll_url": f"/admin/scope-import/jobs/{job.id}",
+        "job": job,
+    }
+
+
 @router.post("/scope-import", response_class=HTMLResponse)
 async def upload_scope_import(
     request: Request,
     file: UploadFile = File(...),
-    db: AsyncSession = Depends(get_db),
     actor: User = Depends(web_require("augmented_parts:write")),
 ):
     filename = file.filename or ""
@@ -1383,20 +1492,26 @@ async def upload_scope_import(
         return templates.TemplateResponse(
             request,
             "admin/_scope_import_result.html",
-            {"error": "Expected an .xlsx spreadsheet."},
+            {
+                "error": "Expected an .xlsx spreadsheet.",
+                "container_id": _SCOPE_IMPORT_STATUS_ID,
+            },
         )
     data = await file.read()
+    actor_id = actor.id
+
+    async def _run(job: jobs.Job) -> None:
+        async with AsyncSessionLocal() as db:
             try:
                 result = await scope_import_service.import_from_bytes(db, data)
             except Exception as exc:  # noqa: BLE001
-        return templates.TemplateResponse(
-            request,
-            "admin/_scope_import_result.html",
-            {"error": f"Could not read spreadsheet: {exc}"},
-        )
+                job.status = "error"
+                job.message = f"Could not read spreadsheet: {exc}"
+                return
+            actor_row = await user_crud.get(db, actor_id)
             await audit_crud.log(
                 db,
-        actor=actor,
+                actor=actor_row,
                 action="update",
                 resource_type="AugmentedPart",
                 resource_id=None,
@@ -1406,10 +1521,45 @@ async def upload_scope_import(
                     f"{result.errors} errors"
                 ),
             )
+            job.status = "done"
+            job.result = result
+
+    job = jobs.start("scope_import", _run)
+    return templates.TemplateResponse(
+        request, "admin/_job_progress.html", _scope_import_progress_ctx(job)
+    )
+
+
+@router.get("/scope-import/jobs/{job_id}", response_class=HTMLResponse)
+async def scope_import_job_status(
+    request: Request,
+    job_id: str,
+    _: User = Depends(web_require("augmented_parts:write")),
+):
+    job = jobs.get(job_id)
+    if job is None:
         return templates.TemplateResponse(
             request,
             "admin/_scope_import_result.html",
-        {"result": result},
+            {
+                "error": "Import job not found — it may have expired.",
+                "container_id": _SCOPE_IMPORT_STATUS_ID,
+            },
+        )
+    if job.status == "running":
+        return templates.TemplateResponse(
+            request, "admin/_job_progress.html", _scope_import_progress_ctx(job)
+        )
+    if job.status == "error":
+        return templates.TemplateResponse(
+            request,
+            "admin/_scope_import_result.html",
+            {"error": job.message, "container_id": _SCOPE_IMPORT_STATUS_ID},
+        )
+    return templates.TemplateResponse(
+        request,
+        "admin/_scope_import_result.html",
+        {"result": job.result, "container_id": _SCOPE_IMPORT_STATUS_ID},
     )
 
 
@@ -1430,18 +1580,22 @@ async def _augmented_part_form_ctx(db: AsyncSession) -> dict:
     }
 
 
-@router.get("/augmented-parts", response_class=HTMLResponse)
-async def augmented_parts_page(
-    request: Request,
-    db: AsyncSession = Depends(get_db),
-    user: User = Depends(web_require("augmented_parts:read")),
-):
-    ctx = await _augmented_part_form_ctx(db)
+_AUGMENTED_PARTS_SORT_COLUMNS = [
+    "id",
+    "sku",
+    "description",
+    "colour",
+    "manufacturer",
+    "scope_model",
+    "part_type",
+    "sub_part_type",
+]
+
+
+async def _default_augmented_parts_table_ctx(db: AsyncSession) -> dict:
+    """Table-card context (default sort, no filters, page 1) after create/sync actions."""
     total = await augmented_part_crud.count_filtered(db)
-    ctx["augmented_parts"] = await augmented_part_crud.list_filtered(
-        db, limit=_PAGE_SIZE
-    )
-    ctx["pagination"] = _paginate(
+    pagination = _paginate(
         "/admin/augmented-parts/filter",
         {},
         1,
@@ -1449,6 +1603,55 @@ async def augmented_parts_page(
         total,
         "#augmented-parts-table-card",
     )
+    return {
+        "augmented_parts": await augmented_part_crud.list_filtered(
+            db, limit=_PAGE_SIZE
+        ),
+        "pagination": pagination,
+        "sort_headers": _sort_headers(
+            "/admin/augmented-parts/filter",
+            {},
+            _AUGMENTED_PARTS_SORT_COLUMNS,
+            "description",
+            "asc",
+            "#augmented-parts-table-card",
+        ),
+        "sort": "description",
+        "dir": "asc",
+    }
+
+
+@router.get("/augmented-parts", response_class=HTMLResponse)
+async def augmented_parts_page(
+    request: Request,
+    sort: str = "description",
+    dir: str = "asc",
+    db: AsyncSession = Depends(get_db),
+    user: User = Depends(web_require("augmented_parts:read")),
+):
+    ctx = await _augmented_part_form_ctx(db)
+    total = await augmented_part_crud.count_filtered(db)
+    ctx["augmented_parts"] = await augmented_part_crud.list_filtered(
+        db, sort=sort, direction=dir, limit=_PAGE_SIZE
+    )
+    ctx["pagination"] = _paginate(
+        "/admin/augmented-parts/filter",
+        {"sort": sort, "dir": dir},
+        1,
+        _PAGE_SIZE,
+        total,
+        "#augmented-parts-table-card",
+    )
+    ctx["sort_headers"] = _sort_headers(
+        "/admin/augmented-parts/filter",
+        {},
+        _AUGMENTED_PARTS_SORT_COLUMNS,
+        sort,
+        dir,
+        "#augmented-parts-table-card",
+    )
+    ctx["sort"] = sort
+    ctx["dir"] = dir
     ctx["user"] = user
     return templates.TemplateResponse(request, "admin/augmented_parts.html", ctx)
 
@@ -1487,39 +1690,35 @@ async def create_augmented_part(
         ),
     )
     form_ctx = await _augmented_part_form_ctx(db)
-    total = await augmented_part_crud.count_filtered(db)
-    pagination = _paginate(
-        "/admin/augmented-parts/filter",
-        {},
-        1,
-        _PAGE_SIZE,
-        total,
-        "#augmented-parts-table-card",
-    )
     return templates.TemplateResponse(
         request,
         "admin/_augmented_parts_table.html",
-        {
-            **form_ctx,
-            "augmented_parts": await augmented_part_crud.list_filtered(
-                db, limit=_PAGE_SIZE
-            ),
-            "pagination": pagination,
-        },
+        {**form_ctx, **await _default_augmented_parts_table_ctx(db)},
     )
 
 
+_AUGMENTED_PARTS_SYNC_TARGET_ID = "augmented-part-list"
+
+
 @router.post("/augmented-parts/sync", response_class=HTMLResponse)
 async def sync_augmented_parts(
     request: Request,
-    db: AsyncSession = Depends(get_db),
     actor: User = Depends(web_require("augmented_parts:write")),
 ):
+    actor_id = actor.id
+
+    async def _run(job: jobs.Job) -> None:
+        async with AsyncSessionLocal() as db:
             try:
                 result = await augmented_part_sync_service.sync(db)
+            except Exception as exc:
+                job.status = "error"
+                job.message = f"Sync failed: {exc}"
+                return
+            actor_row = await user_crud.get(db, actor_id)
             await audit_crud.log(
                 db,
-            actor=actor,
+                actor=actor_row,
                 action="update",
                 resource_type="AugmentedPart",
                 resource_id=None,
@@ -1528,7 +1727,8 @@ async def sync_augmented_parts(
                     f"{result.skipped} skipped (no type match)"
                 ),
             )
-        sync_result = (
+            job.status = "done"
+            job.message = (
                 f"Sync complete: {result.created} created, {result.deleted} deleted"
                 + (
                     f", {result.skipped} skipped (type not recognised)"
@@ -1537,31 +1737,58 @@ async def sync_augmented_parts(
                 )
                 + "."
             )
-        sync_error = None
-    except Exception as exc:
-        sync_result = None
-        sync_error = f"Sync failed: {exc}"
-    form_ctx = await _augmented_part_form_ctx(db)
-    total = await augmented_part_crud.count_filtered(db)
-    pagination = _paginate(
-        "/admin/augmented-parts/filter",
-        {},
-        1,
-        _PAGE_SIZE,
-        total,
-        "#augmented-parts-table-card",
+
+    job = jobs.start("augmented_part_sync", _run)
+    return templates.TemplateResponse(
+        request,
+        "admin/_job_progress.html",
+        {
+            "container_id": _AUGMENTED_PARTS_SYNC_TARGET_ID,
+            "poll_url": f"/admin/augmented-parts/sync/jobs/{job.id}",
+            "job": job,
+        },
     )
+
+
+@router.get("/augmented-parts/sync/jobs/{job_id}", response_class=HTMLResponse)
+async def augmented_parts_sync_job_status(
+    request: Request,
+    job_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: User = Depends(web_require("augmented_parts:write")),
+):
+    job = jobs.get(job_id)
+    if job is None:
+        form_ctx = await _augmented_part_form_ctx(db)
         return templates.TemplateResponse(
             request,
             "admin/_augmented_parts_table.html",
             {
                 **form_ctx,
-            "augmented_parts": await augmented_part_crud.list_filtered(
-                db, limit=_PAGE_SIZE
-            ),
-            "pagination": pagination,
-            "sync_result": sync_result,
-            "sync_error": sync_error,
+                **await _default_augmented_parts_table_ctx(db),
+                "sync_result": None,
+                "sync_error": "Sync job not found — it may have expired.",
+            },
+        )
+    if job.status == "running":
+        return templates.TemplateResponse(
+            request,
+            "admin/_job_progress.html",
+            {
+                "container_id": _AUGMENTED_PARTS_SYNC_TARGET_ID,
+                "poll_url": f"/admin/augmented-parts/sync/jobs/{job_id}",
+                "job": job,
+            },
+        )
+    form_ctx = await _augmented_part_form_ctx(db)
+    return templates.TemplateResponse(
+        request,
+        "admin/_augmented_parts_table.html",
+        {
+            **form_ctx,
+            **await _default_augmented_parts_table_ctx(db),
+            "sync_result": job.message if job.status == "done" else None,
+            "sync_error": job.message if job.status == "error" else None,
         },
     )
 
@@ -1575,6 +1802,8 @@ async def filter_augmented_parts(
     scope_model_id: str = "",
     part_type_id: str = "",
     sub_part_type_id: str = "",
+    sort: str = "description",
+    dir: str = "asc",
     page: int = 1,
     page_size: int = _PAGE_SIZE,
     db: AsyncSession = Depends(get_db),
@@ -1604,7 +1833,7 @@ async def filter_augmented_parts(
     }
     pagination = _paginate(
         "/admin/augmented-parts/filter",
-        filter_params,
+        {**filter_params, "sort": sort, "dir": dir},
         page,
         page_size,
         total,
@@ -1618,13 +1847,29 @@ async def filter_augmented_parts(
         scope_model_id=scope_model_id_int,
         part_type_id=part_type_id_int,
         sub_part_type_id=sub_part_type_id_int,
+        sort=sort,
+        direction=dir,
         skip=pagination["skip"],
         limit=page_size,
     )
+    sort_headers = _sort_headers(
+        "/admin/augmented-parts/filter",
+        filter_params,
+        _AUGMENTED_PARTS_SORT_COLUMNS,
+        sort,
+        dir,
+        "#augmented-parts-table-card",
+    )
     return templates.TemplateResponse(
         request,
         "admin/_augmented_parts_table_card.html",
-        {"augmented_parts": parts, "pagination": pagination},
+        {
+            "augmented_parts": parts,
+            "pagination": pagination,
+            "sort_headers": sort_headers,
+            "sort": sort,
+            "dir": dir,
+        },
     )
 
 
@@ -1803,6 +2048,9 @@ async def augmented_part_detail(
         ),
         "can_read_fits": can_read_fits,
         "can_read_attachment_points": can_read_attachment_points,
+        "augmented_part_id": augmented_part_id,
+        "notes": ap.notes,
+        "can_write_notes": _can_write_augmented_part_notes(user),
     }
     if can_read_attachment_points:
         ctx.update(
@@ -2210,19 +2458,29 @@ async def augmented_part_fits(
     return templates.TemplateResponse(request, "admin/_augmented_part_fits.html", ctx)
 
 
+def _augmented_part_fits_target_id(augmented_part_id: int) -> str:
+    return f"ap-{augmented_part_id}-fits"
+
+
 @router.post(
     "/augmented-parts/{augmented_part_id}/fits/recompute", response_class=HTMLResponse
 )
 async def recompute_augmented_part_fits(
     request: Request,
     augmented_part_id: int,
-    db: AsyncSession = Depends(get_db),
     actor: User = Depends(web_require("fits:write")),
 ):
-    result = await fit_matching_service.recompute_for_part(db, augmented_part_id)
+    actor_id = actor.id
+
+    async def _run(job: jobs.Job) -> None:
+        async with AsyncSessionLocal() as db:
+            result = await fit_matching_service.recompute_for_part(
+                db, augmented_part_id
+            )
+            actor_row = await user_crud.get(db, actor_id)
             await audit_crud.log(
                 db,
-        actor=actor,
+                actor=actor_row,
                 action="update",
                 resource_type="Fit",
                 resource_id=augmented_part_id,
@@ -2231,11 +2489,63 @@ async def recompute_augmented_part_fits(
                     f"{result.created} created, {result.removed} removed"
                 ),
             )
+            job.status = "done"
+            job.message = f"{result.created} created, {result.removed} removed."
+
+    job = jobs.start("fit_recompute_part", _run)
+    return templates.TemplateResponse(
+        request,
+        "admin/_job_progress.html",
+        {
+            "container_id": _augmented_part_fits_target_id(augmented_part_id),
+            "poll_url": f"/admin/augmented-parts/{augmented_part_id}/fits/recompute/jobs/{job.id}",
+            "job": job,
+            "extra_class": "ap-inline-section",
+        },
+    )
+
+
+@router.get(
+    "/augmented-parts/{augmented_part_id}/fits/recompute/jobs/{job_id}",
+    response_class=HTMLResponse,
+)
+async def augmented_part_fits_recompute_job_status(
+    request: Request,
+    augmented_part_id: int,
+    job_id: str,
+    db: AsyncSession = Depends(get_db),
+    actor: User = Depends(web_require("fits:write")),
+):
+    job = jobs.get(job_id)
+    if job is None:
         ctx = await _augmented_part_fits_ctx(
             db,
             augmented_part_id,
             can_write=_can_write_fits(actor),
-        message=f"{result.created} created, {result.removed} removed.",
+            error="Recompute job not found — it may have expired.",
+        )
+        return templates.TemplateResponse(
+            request, "admin/_augmented_part_fits.html", ctx
+        )
+    if job.status == "running":
+        return templates.TemplateResponse(
+            request,
+            "admin/_job_progress.html",
+            {
+                "container_id": _augmented_part_fits_target_id(augmented_part_id),
+                "poll_url": (
+                    f"/admin/augmented-parts/{augmented_part_id}/fits/recompute/jobs/{job_id}"
+                ),
+                "job": job,
+                "extra_class": "ap-inline-section",
+            },
+        )
+    ctx = await _augmented_part_fits_ctx(
+        db,
+        augmented_part_id,
+        can_write=_can_write_fits(actor),
+        message=job.message if job.status == "done" else None,
+        error=job.message if job.status == "error" else None,
     )
     return templates.TemplateResponse(request, "admin/_augmented_part_fits.html", ctx)
 
@@ -2268,24 +2578,64 @@ async def create_augmented_part_fit(
     request: Request,
     augmented_part_id: int,
     own_attachment_point_id: int = Form(...),
+    other_augmented_part_id: str = Form(""),
     other_attachment_point_id: str = Form(""),
+    label: FitLabel = Form(FitLabel.EXACT),
+    note: str = Form(""),
     db: AsyncSession = Depends(get_db),
     actor: User = Depends(web_require("fits:write")),
 ):
     error = None
-    if not other_attachment_point_id:
+    auto_created_ap = None
+    ap_a = await attachment_point_crud.get(db, own_attachment_point_id)
+    ap_b = None
+    if ap_a is None:
+        error = "Attachment point not found."
+    elif other_attachment_point_id:
+        ap_b = await attachment_point_crud.get(db, int(other_attachment_point_id))
+        if ap_b is None:
+            error = "Attachment point not found."
+    elif other_augmented_part_id:
+        other_part = await augmented_part_crud.get(db, int(other_augmented_part_id))
+        if other_part is None:
+            error = "Part not found."
+        elif await attachment_point_crud.list_for_augmented_part(db, other_part.id):
             error = "Select the other part's attachment point."
         else:
-        ap_a = await attachment_point_crud.get(db, own_attachment_point_id)
-        ap_b = await attachment_point_crud.get(db, int(other_attachment_point_id))
-        if ap_a is None or ap_b is None:
-            error = "Attachment point not found."
-        elif ap_a.augmented_part_id == ap_b.augmented_part_id:
+            ap_b = await attachment_point_crud.create(
+                db,
+                augmented_part_id=other_part.id,
+                attachment_point_name_id=ap_a.attachment_point_name_id,
+                iso_thread_id=ap_a.iso_thread_id,
+                unc_thread_id=ap_a.unc_thread_id,
+                clamp_connection_id=ap_a.clamp_connection_id,
+                static_connection_id=ap_a.static_connection_id,
+            )
+            auto_created_ap = ap_b
+    else:
+        error = "Select the other part's attachment point."
+
+    if error is None and ap_b is not None:
+        if ap_a.augmented_part_id == ap_b.augmented_part_id:
             error = "A part cannot fit itself."
         elif await fit_crud.get_by_attachment_points(db, ap_a, ap_b) is not None:
             error = "That fit already exists."
         else:
-            fit = await fit_crud.create(db, ap_a=ap_a, ap_b=ap_b, label=FitLabel.EXACT)
+            if auto_created_ap is not None:
+                await audit_crud.log(
+                    db,
+                    actor=actor,
+                    action="create",
+                    resource_type="AttachmentPoint",
+                    resource_id=auto_created_ap.id,
+                    description=audit_crud.describe_create(
+                        "AttachmentPoint",
+                        auto_created_ap.id,
+                        f"auto-created on AugmentedPart #{auto_created_ap.augmented_part_id} "
+                        f"to match attachment point {ap_a.id}",
+                    ),
+                )
+            fit = await fit_crud.create(db, ap_a=ap_a, ap_b=ap_b, label=label)
             await audit_crud.log(
                 db,
                 actor=actor,
@@ -2293,9 +2643,14 @@ async def create_augmented_part_fit(
                 resource_type="Fit",
                 resource_id=fit.id,
                 description=audit_crud.describe_create(
-                    "Fit", fit.id, f"attachment points {ap_a.id}↔{ap_b.id}"
+                    "Fit",
+                    fit.id,
+                    f"attachment points {ap_a.id}↔{ap_b.id} ({label.value})",
                 ),
             )
+            if note.strip():
+                await fit_note_crud.create(db, fit=fit, author=actor, body=note.strip())
+                await db.refresh(fit, attribute_names=["notes"])
     ctx = await _augmented_part_fits_ctx(
         db, augmented_part_id, can_write=_can_write_fits(actor), error=error
     )
@@ -2398,16 +2753,23 @@ async def delete_augmented_part_fit(
     return templates.TemplateResponse(request, "admin/_augmented_part_fits.html", ctx)
 
 
+_ALL_FITS_RECOMPUTE_STATUS_ID = "fits-recompute-status"
+
+
 @router.post("/augmented-parts/fits/recompute", response_class=HTMLResponse)
 async def recompute_all_fits(
     request: Request,
-    db: AsyncSession = Depends(get_db),
     actor: User = Depends(web_require("fits:write")),
 ):
+    actor_id = actor.id
+
+    async def _run(job: jobs.Job) -> None:
+        async with AsyncSessionLocal() as db:
             result = await fit_matching_service.recompute_all(db)
+            actor_row = await user_crud.get(db, actor_id)
             await audit_crud.log(
                 db,
-        actor=actor,
+                actor=actor_row,
                 action="update",
                 resource_type="Fit",
                 resource_id=None,
@@ -2416,8 +2778,82 @@ async def recompute_all_fits(
                     f"{result.removed} removed"
                 ),
             )
-    return HTMLResponse(
-        f"Recompute complete: {result.created} created, {result.removed} removed."
+            job.status = "done"
+            job.message = (
+                f"Recompute complete: {result.created} created, "
+                f"{result.removed} removed."
+            )
+
+    job = jobs.start("fit_recompute_all", _run)
+    return templates.TemplateResponse(
+        request,
+        "admin/_job_progress_inline.html",
+        {
+            "container_id": _ALL_FITS_RECOMPUTE_STATUS_ID,
+            "poll_url": f"/admin/augmented-parts/fits/recompute/jobs/{job.id}",
+            "job": job,
+        },
+    )
+
+
+@router.get(
+    "/augmented-parts/fits/recompute/jobs/{job_id}", response_class=HTMLResponse
+)
+async def recompute_all_fits_job_status(
+    request: Request,
+    job_id: str,
+    _: User = Depends(web_require("fits:write")),
+):
+    job = jobs.get(job_id)
+    if job is None:
+        return HTMLResponse("Recompute job not found — it may have expired.")
+    if job.status == "running":
+        return templates.TemplateResponse(
+            request,
+            "admin/_job_progress_inline.html",
+            {
+                "container_id": _ALL_FITS_RECOMPUTE_STATUS_ID,
+                "poll_url": f"/admin/augmented-parts/fits/recompute/jobs/{job_id}",
+                "job": job,
+            },
+        )
+    return HTMLResponse(job.message)
+
+
+# --- Augmented Part Notes -------------------------------------------------
+
+
+def _can_write_augmented_part_notes(user: User) -> bool:
+    return user.is_superuser or "augmented_parts:write" in user.permissions
+
+
+@router.post(
+    "/augmented-parts/{augmented_part_id}/notes",
+    response_class=HTMLResponse,
+)
+async def create_augmented_part_note(
+    request: Request,
+    augmented_part_id: int,
+    body: str = Form(...),
+    db: AsyncSession = Depends(get_db),
+    actor: User = Depends(web_require("augmented_parts:write")),
+):
+    ap = await augmented_part_crud.get(db, augmented_part_id)
+    if ap is None:
+        raise HTTPException(status_code=404, detail="Augmented part not found")
+    if body.strip():
+        await augmented_part_note_crud.create(
+            db, augmented_part=ap, author=actor, body=body.strip()
+        )
+        await db.refresh(ap, attribute_names=["notes"])
+    return templates.TemplateResponse(
+        request,
+        "admin/_augmented_part_notes.html",
+        {
+            "augmented_part_id": augmented_part_id,
+            "notes": ap.notes,
+            "can_write_notes": _can_write_augmented_part_notes(actor),
+        },
     )
 
 

tests/test_admin_background_jobs.py

@@ -0,0 +1,156 @@
+import asyncio
+import re
+
+import pytest
+
+from app.crud import role as role_crud
+from app.models.attachment_point import AttachmentPoint
+from app.models.attachment_point_name import AttachmentPointName
+from app.models.augmented_part import AugmentedPart
+from app.models.part_type import PartType
+from tests.test_scope_import import _scope_row, _workbook
+
+_JOB_URL_RE = re.compile(r'hx-get="([^"]+/jobs/[^"]+)"')
+
+
+async def _web_login(client, email, password="secret123"):
+    resp = await client.post("/login", data={"email": email, "password": password})
+    assert resp.status_code == 303
+
+
+async def _poll_until_done(client, url, max_tries=50):
+    """Follow the same htmx polling loop a browser would, until no further
+    ``hx-get`` job-status link is present in the response."""
+    body = ""
+    for _ in range(max_tries):
+        resp = await client.get(url)
+        assert resp.status_code == 200
+        body = resp.text
+        match = _JOB_URL_RE.search(body)
+        if not match:
+            return body
+        url = match.group(1)
+        await asyncio.sleep(0.02)
+    raise AssertionError(f"job did not finish after {max_tries} polls: {body!r}")
+
+
+@pytest.mark.asyncio
+async def test_scope_import_runs_in_background(
+    client, seeded, make_user, db_sessionmaker, monkeypatch
+):
+    monkeypatch.setattr("app.web.admin.AsyncSessionLocal", db_sessionmaker)
+    async with db_sessionmaker() as db:
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db,
+            name="scope-import-editor",
+            permission_ids=[perms["augmented_parts:write"].id],
+        )
+        editor_id = editor.id
+    await make_user("importer@example.com", role_ids=[editor_id])
+    await _web_login(client, "importer@example.com")
+
+    data = _workbook([_scope_row(product_number="BG-SCOPE-1")])
+    resp = await client.post(
+        "/admin/scope-import",
+        files={"file": ("scopes.xlsx", data, "application/octet-stream")},
+    )
+    assert resp.status_code == 200
+    assert "scope-import-status" in resp.text
+    match = _JOB_URL_RE.search(resp.text)
+    assert match, resp.text
+
+    final_body = await _poll_until_done(client, match.group(1))
+    assert "1</strong> created" in final_body
+
+
+@pytest.mark.asyncio
+async def test_augmented_parts_sync_runs_in_background(
+    client, seeded, make_user, db_sessionmaker, monkeypatch
+):
+    monkeypatch.setattr("app.web.admin.AsyncSessionLocal", db_sessionmaker)
+    async with db_sessionmaker() as db:
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db, name="sync-editor", permission_ids=[perms["augmented_parts:write"].id]
+        )
+        editor_id = editor.id
+    await make_user("syncer@example.com", role_ids=[editor_id])
+    await _web_login(client, "syncer@example.com")
+
+    resp = await client.post("/admin/augmented-parts/sync")
+    assert resp.status_code == 200
+    assert 'id="augmented-part-list"' in resp.text
+    match = _JOB_URL_RE.search(resp.text)
+    assert match, resp.text
+
+    final_body = await _poll_until_done(client, match.group(1))
+    assert "Sync complete" in final_body
+
+
+@pytest.mark.asyncio
+async def test_fit_recompute_for_part_runs_in_background(
+    client, seeded, make_user, db_sessionmaker, monkeypatch
+):
+    monkeypatch.setattr("app.web.admin.AsyncSessionLocal", db_sessionmaker)
+    async with db_sessionmaker() as db:
+        apn = AttachmentPointName(name="Objective")
+        part_t = PartType(name="Scope")
+        db.add_all([apn, part_t])
+        await db.flush()
+        part = AugmentedPart(
+            description="Test scope",
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=part_t.id,
+        )
+        db.add(part)
+        await db.flush()
+        db.add(
+            AttachmentPoint(augmented_part_id=part.id, attachment_point_name_id=apn.id)
+        )
+        await db.commit()
+        part_id = part.id
+
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db,
+            name="fit-recompute-editor",
+            permission_ids=[perms["fits:write"].id, perms["augmented_parts:read"].id],
+        )
+        editor_id = editor.id
+    await make_user("recomputer@example.com", role_ids=[editor_id])
+    await _web_login(client, "recomputer@example.com")
+
+    resp = await client.post(f"/admin/augmented-parts/{part_id}/fits/recompute")
+    assert resp.status_code == 200
+    assert f'id="ap-{part_id}-fits"' in resp.text
+    match = _JOB_URL_RE.search(resp.text)
+    assert match, resp.text
+
+    final_body = await _poll_until_done(client, match.group(1))
+    assert "created" in final_body and "removed" in final_body
+
+
+@pytest.mark.asyncio
+async def test_fit_recompute_all_runs_in_background(
+    client, seeded, make_user, db_sessionmaker, monkeypatch
+):
+    monkeypatch.setattr("app.web.admin.AsyncSessionLocal", db_sessionmaker)
+    async with db_sessionmaker() as db:
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db, name="fit-recompute-all-editor", permission_ids=[perms["fits:write"].id]
+        )
+        editor_id = editor.id
+    await make_user("recomputerall@example.com", role_ids=[editor_id])
+    await _web_login(client, "recomputerall@example.com")
+
+    resp = await client.post("/admin/augmented-parts/fits/recompute")
+    assert resp.status_code == 200
+    assert "fits-recompute-status" in resp.text
+    match = _JOB_URL_RE.search(resp.text)
+    assert match, resp.text
+
+    final_body = await _poll_until_done(client, match.group(1))
+    assert "Recompute complete" in final_body

tests/test_admin_sorting.py

@@ -0,0 +1,148 @@
+import pytest
+
+from app.crud import augmented_part as augmented_part_crud
+from app.models.augmented_part import AugmentedPart
+from app.models.imported_part import ImportedPart
+from app.models.manufacturer import Manufacturer
+from app.models.part_colour import PartColour
+from app.models.part_type import PartType
+
+
+async def _web_login(client, email, password="secret123"):
+    resp = await client.post("/login", data={"email": email, "password": password})
+    assert resp.status_code == 303
+
+
+async def _seed_augmented_parts(db):
+    part_t = PartType(name="Scope")
+    db.add(part_t)
+    await db.flush()
+    parts = [
+        AugmentedPart(
+            description=desc,
+            sku=sku,
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=part_t.id,
+        )
+        for desc, sku in [
+            ("Alpha scope", "SKU-C"),
+            ("Bravo scope", "SKU-A"),
+            ("Charlie scope", "SKU-B"),
+        ]
+    ]
+    db.add_all(parts)
+    await db.commit()
+
+
+async def _seed_imported_parts(db):
+    db.add_all(
+        [
+            ImportedPart(InventoryID="INV-2", Description="Charlie widget"),
+            ImportedPart(InventoryID="INV-1", Description="Alpha widget"),
+            ImportedPart(InventoryID="INV-3", Description="Bravo widget"),
+        ]
+    )
+    await db.commit()
+
+
+def _order_of(body: str, needles: list[str]) -> list[str]:
+    positions = {n: body.find(n) for n in needles}
+    return sorted(positions, key=lambda n: positions[n])
+
+
+@pytest.mark.asyncio
+async def test_augmented_parts_page_sorts_by_description_desc(
+    client, seeded, make_user, db_sessionmaker
+):
+    async with db_sessionmaker() as db:
+        await _seed_augmented_parts(db)
+    await make_user("reader@example.com", role_ids=[seeded["roles"]["user"].id])
+    await _web_login(client, "reader@example.com")
+
+    resp = await client.get("/admin/augmented-parts?sort=description&dir=desc")
+    assert resp.status_code == 200
+    body = resp.text
+    assert _order_of(body, ["Charlie scope", "Bravo scope", "Alpha scope"]) == [
+        "Charlie scope",
+        "Bravo scope",
+        "Alpha scope",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_augmented_parts_filter_sorts_by_sku_asc(
+    client, seeded, make_user, db_sessionmaker
+):
+    async with db_sessionmaker() as db:
+        await _seed_augmented_parts(db)
+    await make_user("reader2@example.com", role_ids=[seeded["roles"]["user"].id])
+    await _web_login(client, "reader2@example.com")
+
+    resp = await client.get("/admin/augmented-parts/filter?sort=sku&dir=asc")
+    assert resp.status_code == 200
+    body = resp.text
+    # SKU-A (Bravo), SKU-B (Charlie), SKU-C (Alpha)
+    assert _order_of(body, ["Bravo scope", "Charlie scope", "Alpha scope"]) == [
+        "Bravo scope",
+        "Charlie scope",
+        "Alpha scope",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_imported_parts_page_sorts_by_description_desc(
+    client, seeded, make_user, db_sessionmaker
+):
+    async with db_sessionmaker() as db:
+        await _seed_imported_parts(db)
+    await make_user("reader3@example.com", role_ids=[seeded["roles"]["user"].id])
+    await _web_login(client, "reader3@example.com")
+
+    resp = await client.get("/admin/imported-parts?sort=Description&dir=desc")
+    assert resp.status_code == 200
+    body = resp.text
+    assert _order_of(body, ["Charlie widget", "Bravo widget", "Alpha widget"]) == [
+        "Charlie widget",
+        "Bravo widget",
+        "Alpha widget",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_list_filtered_sorts_by_joined_colour_name(db_sessionmaker):
+    async with db_sessionmaker() as db:
+        red = PartColour(name="Red")
+        blue = PartColour(name="Blue")
+        manufacturer = Manufacturer(name="Acme", url="https://acme.example")
+        part_t = PartType(name="Scope")
+        db.add_all([red, blue, manufacturer, part_t])
+        await db.flush()
+
+        db.add_all(
+            [
+                AugmentedPart(
+                    description="Red one",
+                    colour_id=red.id,
+                    manufacturer_id=manufacturer.id,
+                    part_type_id=part_t.id,
+                ),
+                AugmentedPart(
+                    description="Blue one",
+                    colour_id=blue.id,
+                    manufacturer_id=manufacturer.id,
+                    part_type_id=part_t.id,
+                ),
+            ]
+        )
+        await db.commit()
+
+        parts = await augmented_part_crud.list_filtered(
+            db, sort="colour", direction="asc"
+        )
+        assert [p.description for p in parts] == ["Blue one", "Red one"]
+
+        parts_desc = await augmented_part_crud.list_filtered(
+            db, sort="colour", direction="desc"
+        )
+        assert [p.description for p in parts_desc] == ["Red one", "Blue one"]

tests/test_augmented_part_detail.py

@@ -3,8 +3,9 @@ import pytest
 from app.crud import role as role_crud
 from app.models.attachment_point import AttachmentPoint
 from app.models.attachment_point_name import AttachmentPointName
-from app.models.augmented_part import AugmentedPart
-from app.models.fit import Fit, FitLabel
+from app.models.augmented_part import AugmentedPart, AugmentedPartNote
+from app.models.fit import Fit, FitLabel, FitNote
+from app.models.iso_thread import IsoThread
 from app.models.part_type import PartType
 from app.models.scope_info import ScopeInfo
 
@@ -40,12 +41,8 @@ async def _seed_part_with_fit(db):
             objective_thread_pitch="M52x0.75",
         )
     )
-    ap_s = AttachmentPoint(
-        augmented_part_id=scope.id, attachment_point_name_id=apn.id
-    )
-    ap_c = AttachmentPoint(
-        augmented_part_id=cover.id, attachment_point_name_id=apn.id
-    )
+    ap_s = AttachmentPoint(augmented_part_id=scope.id, attachment_point_name_id=apn.id)
+    ap_c = AttachmentPoint(augmented_part_id=cover.id, attachment_point_name_id=apn.id)
     db.add_all([ap_s, ap_c])
     await db.flush()
 
@@ -91,6 +88,7 @@ async def test_detail_shows_attributes_and_fits_readonly(
     assert "Add fit" not in body
     assert "Mark Exact" not in body
     assert "Recompute possible fits" not in body
+    assert "Add note" not in body
     # ...and attachment-point add/edit/delete controls are hidden too
     assert 'name="attachment_point_name_id"' not in body
     assert "Delete this attachment point?" not in body
@@ -151,6 +149,199 @@ async def test_detail_write_controls_for_fit_editor(
     assert "Recompute possible fits" in body
 
 
+@pytest.mark.asyncio
+async def test_create_fit_auto_creates_matching_attachment_point(
+    client, seeded, make_user, db_sessionmaker
+):
+    async with db_sessionmaker() as db:
+        apn = AttachmentPointName(name="Objective")
+        scope_t = PartType(name="Scope")
+        cover_t = PartType(name="Flip Cover")
+        db.add_all([apn, scope_t, cover_t])
+        await db.flush()
+
+        thread = IsoThread(diameter_mm=42.0, pitch_mm=0.75)
+        db.add(thread)
+        await db.flush()
+
+        scope = AugmentedPart(
+            description="Alpha 3-18x50",
+            sku="ALP-318",
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=scope_t.id,
+        )
+        cover = AugmentedPart(
+            description="Flip cover 50mm",
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=cover_t.id,
+        )
+        db.add_all([scope, cover])
+        await db.flush()
+
+        own_ap = AttachmentPoint(
+            augmented_part_id=scope.id,
+            attachment_point_name_id=apn.id,
+            iso_thread_id=thread.id,
+        )
+        db.add(own_ap)
+        await db.commit()
+
+        scope_id, cover_id, own_ap_id = scope.id, cover.id, own_ap.id
+
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db,
+            name="fit-editor2",
+            permission_ids=[
+                perms["augmented_parts:read"].id,
+                perms["fits:read"].id,
+                perms["fits:write"].id,
+            ],
+        )
+        editor_id = editor.id
+    await make_user("editor2@example.com", role_ids=[editor_id])
+    await _web_login(client, "editor2@example.com")
+
+    resp = await client.post(
+        f"/admin/augmented-parts/{scope_id}/fits",
+        data={
+            "own_attachment_point_id": own_ap_id,
+            "other_augmented_part_id": cover_id,
+            "other_attachment_point_id": "",
+            "label": "possible",
+        },
+    )
+    assert resp.status_code == 200
+    body = resp.text
+    assert "already exists" not in body
+    assert "not found" not in body
+
+    async with db_sessionmaker() as db:
+        cover_points = [
+            ap
+            for ap in (await db.execute(AttachmentPoint.__table__.select())).all()
+            if ap.augmented_part_id == cover_id
+        ]
+        assert len(cover_points) == 1
+        assert cover_points[0].iso_thread_id == thread.id
+        assert cover_points[0].attachment_point_name_id == apn.id
+
+        fits = (await db.execute(Fit.__table__.select())).all()
+        assert len(fits) == 1
+        assert fits[0].label == FitLabel.POSSIBLE
+
+
+@pytest.mark.asyncio
+async def test_create_fit_with_note_creates_fit_note(
+    client, seeded, make_user, db_sessionmaker
+):
+    async with db_sessionmaker() as db:
+        apn = AttachmentPointName(name="Objective")
+        scope_t = PartType(name="Scope")
+        cover_t = PartType(name="Flip Cover")
+        db.add_all([apn, scope_t, cover_t])
+        await db.flush()
+
+        scope = AugmentedPart(
+            description="Alpha 3-18x50",
+            sku="ALP-318",
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=scope_t.id,
+        )
+        cover = AugmentedPart(
+            description="Flip cover 50mm",
+            colour_id=1,
+            manufacturer_id=1,
+            part_type_id=cover_t.id,
+        )
+        db.add_all([scope, cover])
+        await db.flush()
+
+        own_ap = AttachmentPoint(
+            augmented_part_id=scope.id, attachment_point_name_id=apn.id
+        )
+        other_ap = AttachmentPoint(
+            augmented_part_id=cover.id, attachment_point_name_id=apn.id
+        )
+        db.add_all([own_ap, other_ap])
+        await db.commit()
+
+        scope_id, own_ap_id, other_ap_id = scope.id, own_ap.id, other_ap.id
+
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db,
+            name="fit-editor3",
+            permission_ids=[
+                perms["augmented_parts:read"].id,
+                perms["fits:read"].id,
+                perms["fits:write"].id,
+            ],
+        )
+        editor_id = editor.id
+    await make_user("editor3@example.com", role_ids=[editor_id])
+    await _web_login(client, "editor3@example.com")
+
+    resp = await client.post(
+        f"/admin/augmented-parts/{scope_id}/fits",
+        data={
+            "own_attachment_point_id": own_ap_id,
+            "other_attachment_point_id": other_ap_id,
+            "label": "exact",
+            "note": "Confirmed fit on the bench.",
+        },
+    )
+    assert resp.status_code == 200
+    body = resp.text
+    assert "Confirmed fit on the bench." in body
+
+    async with db_sessionmaker() as db:
+        fits = (await db.execute(Fit.__table__.select())).all()
+        assert len(fits) == 1
+        notes = (await db.execute(FitNote.__table__.select())).all()
+        assert len(notes) == 1
+        assert notes[0].fit_id == fits[0].id
+        assert notes[0].body == "Confirmed fit on the bench."
+
+
+@pytest.mark.asyncio
+async def test_create_augmented_part_note(client, seeded, make_user, db_sessionmaker):
+    async with db_sessionmaker() as db:
+        ids = await _seed_part_with_fit(db)
+        perms = seeded["perms"]
+        editor = await role_crud.create(
+            db,
+            name="ap-note-editor",
+            permission_ids=[
+                perms["augmented_parts:read"].id,
+                perms["augmented_parts:write"].id,
+            ],
+        )
+        editor_id = editor.id
+    await make_user("noteeditor@example.com", role_ids=[editor_id])
+    await _web_login(client, "noteeditor@example.com")
+
+    resp = await client.get(f"/admin/augmented-parts/{ids['scope_id']}")
+    assert resp.status_code == 200
+    assert "Add note" in resp.text
+
+    resp = await client.post(
+        f"/admin/augmented-parts/{ids['scope_id']}/notes",
+        data={"body": "Verified thread depth on the bench."},
+    )
+    assert resp.status_code == 200
+    assert "Verified thread depth on the bench." in resp.text
+
+    async with db_sessionmaker() as db:
+        notes = (await db.execute(AugmentedPartNote.__table__.select())).all()
+        assert len(notes) == 1
+        assert notes[0].augmented_part_id == ids["scope_id"]
+        assert notes[0].body == "Verified thread depth on the bench."
+
+
 @pytest.mark.asyncio
 async def test_detail_404_for_missing_part(client, seeded, make_user):
     await make_user("reader2@example.com", role_ids=[seeded["roles"]["user"].id])
@@ -160,7 +351,9 @@ async def test_detail_404_for_missing_part(client, seeded, make_user):
 
 
 @pytest.mark.asyncio
-async def test_detail_requires_read_permission(client, seeded, make_user, db_sessionmaker):
+async def test_detail_requires_read_permission(
+    client, seeded, make_user, db_sessionmaker
+):
     async with db_sessionmaker() as db:
         ids = await _seed_part_with_fit(db)
     await make_user("plain@example.com")  # no roles, not superuser