drawings: on a rev mismatch, Clerical can keep the retired rev VISUAL calls (#41)

When VISUAL calls a rev that M-Files has retired, the draft is still
flagged rev_mismatch, but the drawing job now also copies the rev VISUAL
calls (MFilesKit 0.1.3 DrawingLookup.revision) into drawing_revisions and
visual.called. A Clerical Supervisor picks either rev on the packet:
"Use latest rev N" as before, or "Use rev V as VISUAL calls it"
(rev-approve with use=called), with a reason and a signature.

The kept rev holds while M-Files' Effective rev stays the one chosen
against: no flag, no change order. A newer Effective rev flags the
packet again; a new VISUAL rev clears the choice.

Migration 0009 adds drawing_revisions. Needs mfileskit 0.1.3.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

server/packetstation/drawings/decide.py

@@ -13,7 +13,10 @@ Rows, in the order they are tried:
  4. no released rev otherwise -> flag not_found.
  5. VISUAL rev not a number (and no approved rev equal to M-Files') -> flag bad_rev, not attached.
  6. revs differ (and no approved rev equal to M-Files') -> flag rev_mismatch. The job stages the M-Files copy
-    for Clerical Supervisor approval on drafts only.
+    for Clerical Supervisor approval on drafts only, and on a draft also copies the rev VISUAL calls when M-Files
+    still holds it (Retired, say), so Clerical can choose either.
+    Revs differ, but Clerical chose to keep the rev VISUAL calls while M-Files' Effective rev was this one ->
+    unchanged (no flag, no change order). A newer Effective rev flags the packet again.
  7. revs match, draft with a hand drawing -> unchanged (the feed already took the hand drawing off on a rev move).
  8. revs match, draft with this very file attached at this rev -> unchanged.
  9. revs match, draft -> attach ("sheet of drawing <base>" for an H sheet).
@@ -69,6 +72,8 @@ class Target:
     co_pending: bool = False
     co_staged_sha: bytes | None = None  # sha256 of the file the pending CO already stages
     rejected_sha: bytes | None = None  # sha256 staged on the last drawing-origin CO Clerical rejected
+    # Clerical chose the rev VISUAL calls (a Retired rev) over M-Files' Effective rev; this is that Effective rev.
+    kept_latest: str | None = None
 
 
 @dataclass(frozen=True)
@@ -79,11 +84,15 @@ class Decision:
     note: str
 
 
-def _int(v: object) -> int | None:
+def as_int(v: object) -> int | None:
+    """A rev as a number: "3" -> 3; "A", "" and None -> None."""
     s = "" if v is None else str(v).strip()
     return int(s) if s.isdigit() else None
 
 
+_int = as_int
+
+
 def draft_line(f: Found) -> str:
     """The old draftLine: "rev N <where>", or "in drafting, no released PDF yet", or ""."""
     if f.draft_rev is not None and f.draft_where:
@@ -102,13 +111,21 @@ def failed_note(f: Found) -> str:
     return f"{_FAILED_PREFIX}{detail or 'no detail'}"
 
 
+def kept_called(t: Target, f: Found) -> bool:
+    """Clerical kept the rev VISUAL calls, and M-Files' Effective rev is still the one they chose against."""
+    return f.ok and f.rev is not None and t.kept_latest is not None and str(t.kept_latest).strip() == str(f.rev)
+
+
 def rev_confirmed(t: Target, f: Found) -> bool:
-    """The old revConfirmed: M-Files' released rev is the rev VISUAL calls, or Clerical approved that rev."""
+    """The old revConfirmed: M-Files' released rev is the rev VISUAL calls, or Clerical approved that rev, or Clerical
+    kept the rev VISUAL calls over that rev."""
     if not f.ok or f.rev is None:
         return False
     v = _int(t.visual_rev)
     if v is not None and v == f.rev:
         return True
+    if kept_called(t, f):
+        return True
     return t.rev_ok is not None and str(t.rev_ok).strip() == str(f.rev)
 
 
@@ -156,6 +173,8 @@ def decide(t: Target, f: Found, *, same_file: bool, fetched_sha: bytes | None =
     approved = t.rev_ok is not None and str(t.rev_ok).strip() == str(f.rev)
     vrev = (t.visual_rev or "").strip()
     v = _int(vrev)
+    if not approved and kept_called(t, f):
+        return keep(UNCHANGED, f"Rev {vrev} kept by Clerical; M-Files has rev {f.rev}")
     if not approved:
         # 5
         if v is None: