US05-04: Verify, Retry, and Resolve Uncertain Uploads (#74)

photo_pipeline/models/uploads.py

@@ -69,6 +69,11 @@ class UploadBatch(Base):
     outcome_counts: Mapped[str | None] = mapped_column(String)  # JSON, from the items
     report_counts: Mapped[str | None] = mapped_column(String)  # JSON, uploader's own
 
+    # Verification (US05-04). ``stale_bytes`` means at least one uploaded file has
+    # been edited since: the batch carries a visible warning and cannot be re-run.
+    verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    stale_bytes: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
     error_code: Mapped[str | None] = mapped_column(String)
     error_message: Mapped[str | None] = mapped_column(String)
 
@@ -102,6 +107,45 @@ class UploadItem(Base):
     outcome: Mapped[str | None] = mapped_column(String)
     evidence: Mapped[str | None] = mapped_column(String)  # the bounded report line
     outcome_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    # Verification against the server (US05-04): present | absent | inconclusive |
+    # manual. NULL until the item has been verified; ``inconclusive`` whenever the
+    # server could not answer — which is never treated as success.
+    verification: Mapped[str | None] = mapped_column(String)
+    verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    # The bytes on disk at verification time, and whether they still are the bytes
+    # this batch uploaded.
+    observed_sha256: Mapped[str | None] = mapped_column(String)
+    changed_after_upload: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
     updated_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now(), onupdate=func.now()
     )
+
+
+class UploadVerification(Base):
+    """Append-only evidence for every verification and manual resolution (US05-04).
+
+    The item row is a projection of the latest answer; this table is the history
+    that answers "who decided this, on what evidence, and when?". Rows are never
+    updated or deleted, so a manual resolution can always be told apart from
+    server evidence.
+    """
+
+    __tablename__ = "upload_verifications"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    batch_id: Mapped[str] = mapped_column(
+        ForeignKey("upload_batches.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    asset_id: Mapped[str] = mapped_column(String, nullable=False)
+    action: Mapped[str] = mapped_column(String, nullable=False)  # verify | resolve
+    source: Mapped[str] = mapped_column(String, nullable=False)  # immich_api | operator
+    # present | absent | inconclusive for a verify; the recorded outcome for a resolve.
+    result: Mapped[str] = mapped_column(String, nullable=False)
+    outcome: Mapped[str | None] = mapped_column(String)
+    evidence: Mapped[str] = mapped_column(String, nullable=False)
+    actor: Mapped[str | None] = mapped_column(String)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )