feat: two-step staging upload + multi-page PDF person inheritance

- Add stage/process-staged/remove-staged endpoints for batch upload workflow
- Add staging gallery UI with thumbnail previews and per-image removal
- Inherit person info & doc fields from page 1 for multi-page PDFs
- Auto-link page 2+ to same person on confirmation
- Show info banner on review page for multi-page documents
- Exclude staged docs from stats counters

routers/documents.py

@@ -39,7 +39,7 @@ async def document_queue(request: Request, status: str = "", uploaded: int = 0):
                SUM(CASE WHEN status='extracted' THEN 1 ELSE 0 END) AS pending_review,
                SUM(CASE WHEN status='pending' THEN 1 ELSE 0 END) AS processing,
                SUM(CASE WHEN status='error' THEN 1 ELSE 0 END) AS errors
-            FROM documents"""
+            FROM documents WHERE status != 'staged'"""
         ).fetchone()
 
     return templates.TemplateResponse(

routers/review.py

@@ -42,6 +42,47 @@ def _get_document(doc_id: int) -> dict | None:
         else:
             doc["person"] = {}
 
+        # For multi-page PDFs (page 2+), inherit person info & doc fields from page 1
+        doc["inherited_from_page1"] = False
+        if doc.get("pdf_group_id") and (doc.get("page_number") or 0) > 1:
+            page1 = conn.execute(
+                """SELECT * FROM documents
+                   WHERE pdf_group_id=? AND page_number=1""",
+                (doc["pdf_group_id"],),
+            ).fetchone()
+            if page1:
+                page1 = dict(page1)
+                # Inherit person data if current page has no name
+                current_first = (doc["person"].get("first_name") or "").strip()
+                if not current_first:
+                    if page1.get("person_id"):
+                        person = conn.execute(
+                            "SELECT * FROM persons WHERE id=?", (page1["person_id"],)
+                        ).fetchone()
+                        if person:
+                            doc["person"] = dict(person)
+                            doc["inherited_from_page1"] = True
+                            doc["page1_person_id"] = page1["person_id"]
+                    elif page1.get("raw_extraction_json"):
+                        try:
+                            p1_extracted = json.loads(page1["raw_extraction_json"])
+                            p1_person = p1_extracted.get("person", {})
+                            if (p1_person.get("first_name") or "").strip():
+                                doc["person"] = p1_person
+                                doc["inherited_from_page1"] = True
+                        except Exception:
+                            pass
+
+                # Inherit document-level fields if missing
+                inherit_fields = [
+                    "request_number", "request_date", "search_scope",
+                    "request_purpose", "data_valid_until", "registry_office",
+                    "applicant_name_raw",
+                ]
+                for field in inherit_fields:
+                    if not (doc.get(field) or "").strip() and (page1.get(field) or "").strip():
+                        doc[field] = page1[field]
+
     return doc
 
 
@@ -304,6 +345,17 @@ async def confirm_document(doc_id: int, request: Request):
 
         person_id = None
 
+        # For multi-page PDFs (page 2+), auto-link to page 1's person
+        page1_person_id = None
+        if current_doc.get("pdf_group_id") and (current_doc.get("page_number") or 0) > 1:
+            page1 = conn.execute(
+                """SELECT person_id FROM documents
+                   WHERE pdf_group_id=? AND page_number=1 AND person_id IS NOT NULL""",
+                (current_doc["pdf_group_id"],),
+            ).fetchone()
+            if page1:
+                page1_person_id = page1["person_id"]
+
         # Option 1: User explicitly chose to merge with an existing person
         if merge_person_id:
             try:
@@ -388,6 +440,10 @@ async def confirm_document(doc_id: int, request: Request):
                     ),
                 )
 
+        # Option 2b: Auto-link to page 1's person for multi-page PDFs
+        if not person_id and page1_person_id:
+            person_id = page1_person_id
+
         # Option 3: Create new person
         if not person_id:
             existing_person = None

routers/upload.py

@@ -108,7 +108,7 @@ async def upload_page(request: Request):
                SUM(CASE WHEN status='confirmed' THEN 1 ELSE 0 END) AS confirmed,
                SUM(CASE WHEN status='extracted' THEN 1 ELSE 0 END) AS pending_review,
                SUM(CASE WHEN status='error' THEN 1 ELSE 0 END) AS errors
-            FROM documents"""
+            FROM documents WHERE status != 'staged'"""
         ).fetchone()
     return templates.TemplateResponse(
         request, "index.html", {
@@ -171,3 +171,102 @@ async def upload_files(
     if len(doc_ids) == 1:
         return RedirectResponse(f"/review/{doc_ids[0][0]}?wait=1", status_code=303)
     return RedirectResponse("/documents?uploaded=1", status_code=303)
+
+
+# ─── Two-step workflow: stage images, then process ─────────────
+
+@router.post("/upload/stage")
+async def stage_file(
+    request: Request,
+    files: list[UploadFile] = File(...),
+):
+    """Save uploaded images without triggering AI extraction."""
+    staged = []
+    for upload in files:
+        suffix = Path(upload.filename).suffix.lower()
+        if suffix not in ALLOWED_EXTENSIONS:
+            continue
+
+        file_bytes = await upload.read()
+
+        if suffix in ALLOWED_PDF_EXTS:
+            pages = pdf_to_images(file_bytes, upload.filename)
+            for page_info in pages:
+                with get_db() as conn:
+                    cursor = conn.execute(
+                        """INSERT INTO documents
+                           (image_path, status, pdf_group_id, page_number)
+                           VALUES (?, 'staged', ?, ?)""",
+                        (
+                            page_info["image_path"],
+                            page_info["pdf_group_id"],
+                            page_info["page_number"],
+                        ),
+                    )
+                    staged.append({
+                        "id": cursor.lastrowid,
+                        "image_path": page_info["image_path"],
+                        "name": f"{upload.filename} (p{page_info['page_number']})",
+                    })
+        else:
+            rel_path = _save_image(file_bytes, upload.filename)
+            with get_db() as conn:
+                cursor = conn.execute(
+                    "INSERT INTO documents (image_path, status) VALUES (?, 'staged')",
+                    (rel_path,),
+                )
+                staged.append({
+                    "id": cursor.lastrowid,
+                    "image_path": rel_path,
+                    "name": upload.filename,
+                })
+
+    from fastapi.responses import JSONResponse
+    return JSONResponse({"staged": staged})
+
+
+@router.post("/upload/process-staged")
+async def process_staged(
+    request: Request,
+    doc_ids: str = Form(...),
+    provider: str = Form(""),
+):
+    """Trigger AI extraction for previously staged documents."""
+    if not provider:
+        provider = get_default_provider()
+
+    ids = [int(x) for x in doc_ids.split(",") if x.strip().isdigit()]
+
+    with get_db() as conn:
+        rows = conn.execute(
+            f"SELECT id, image_path FROM documents WHERE id IN ({','.join('?' * len(ids))}) AND status='staged'",
+            ids,
+        ).fetchall()
+        for row in rows:
+            conn.execute(
+                "UPDATE documents SET status='pending', provider=?, updated_at=CURRENT_TIMESTAMP WHERE id=?",
+                (provider, row["id"]),
+            )
+
+    for row in rows:
+        asyncio.create_task(_extract_and_save(row["id"], row["image_path"], provider))
+
+    if len(rows) == 1:
+        return RedirectResponse(f"/review/{rows[0]['id']}?wait=1", status_code=303)
+    return RedirectResponse("/documents?uploaded=1", status_code=303)
+
+
+@router.delete("/upload/staged/{doc_id}")
+async def remove_staged(doc_id: int):
+    """Remove a single staged document before processing."""
+    from fastapi.responses import JSONResponse
+    with get_db() as conn:
+        row = conn.execute("SELECT image_path FROM documents WHERE id=? AND status='staged'", (doc_id,)).fetchone()
+        if row:
+            # Delete the file
+            file_path = Path(UPLOAD_DIR) / row["image_path"]
+            if file_path.exists():
+                file_path.unlink()
+            conn.execute("DELETE FROM documents WHERE id=?", (doc_id,))
+            return JSONResponse({"ok": True})
+    return JSONResponse({"ok": False}, status_code=404)

static/css/main.css

@@ -355,6 +355,20 @@ a.stat.active { border-color: rgba(15,118,110,.24); background: var(--primary-so
   margin-bottom: 1rem;
   color: var(--success);
 }
+.info-banner {
+  background: linear-gradient(135deg, rgba(239,246,255,.95), rgba(255,255,255,.82));
+  border: 1px solid #bfdbfe;
+  border-radius: calc(var(--radius) - 4px);
+  padding: .85rem 1rem;
+  margin-bottom: 1rem;
+  color: #1d4ed8;
+  display: flex;
+  align-items: center;
+  gap: .6rem;
+  font-size: .92rem;
+  line-height: 1.5;
+}
+.info-banner svg { flex-shrink: 0; stroke: #3b82f6; }
 
 /* ============================
    Upload Card
@@ -1450,3 +1464,107 @@ a.stat.active { border-color: rgba(15,118,110,.24); background: var(--primary-so
     font-size: .68rem;
   }
 }
+
+/* ============================
+   Staging Gallery (two-step upload)
+   ============================ */
+.stage-controls {
+  display: flex;
+  gap: .75rem;
+  flex-wrap: wrap;
+  margin-bottom: 1rem;
+}
+.stage-capture-btn svg { vertical-align: -.15em; margin-inline-end: .3rem; }
+
+.staging-gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(130px, 1fr));
+  gap: .75rem;
+  margin-bottom: 1rem;
+}
+.staging-thumb {
+  position: relative;
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  background: var(--surface-tint);
+  border: 2px solid var(--border);
+  aspect-ratio: 3/4;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  transition: var(--transition);
+}
+.staging-thumb.loading {
+  opacity: .6;
+}
+.staging-thumb.removing {
+  opacity: 0;
+  transform: scale(.9);
+}
+.staging-thumb img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.staging-thumb-name {
+  font-size: .72rem;
+  color: var(--text-muted);
+  padding: .25rem .4rem;
+  text-align: center;
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  background: rgba(255,255,255,.85);
+  backdrop-filter: blur(4px);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.staging-remove {
+  position: absolute;
+  top: 4px;
+  left: 4px;
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  border: none;
+  background: rgba(220,38,38,.85);
+  color: #fff;
+  font-size: 1.1rem;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  transition: opacity .15s;
+}
+.staging-thumb:hover .staging-remove { opacity: 1; }
+@media (pointer: coarse) { .staging-remove { opacity: 1; } }
+
+.staging-thumb-spinner {
+  width: 28px;
+  height: 28px;
+  border: 3px solid var(--border);
+  border-top-color: var(--primary);
+  border-radius: 50%;
+  animation: spin .7s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.staging-count {
+  text-align: center;
+  font-weight: 600;
+  color: var(--primary-dark);
+  margin-bottom: .75rem;
+  font-size: 1rem;
+}
+
+.stage-action-buttons {
+  display: flex;
+  gap: .5rem;
+  justify-content: center;
+  margin-top: .75rem;
+}

templates/index.html

@@ -74,6 +74,57 @@
   </form>
 </div>
 
+<!-- ─── Two-step: Stage pictures then process ─── -->
+<div class="upload-card" id="stagingCard">
+  <div class="card-heading">
+    <div>
+      <h2>التقاط صور ثم معالجة دفعة واحدة</h2>
+      <p>التقط أو أضف صوراً واحدة تلو الأخرى، ثم اضغط على «معالجة الكل» عند الانتهاء.</p>
+    </div>
+  </div>
+
+  <div class="stage-controls">
+    <input type="file" id="stageFileInput" accept=".jpg,.jpeg,.png,.webp,.pdf" capture="environment" class="file-input">
+    <label for="stageFileInput" class="btn btn-secondary btn-large stage-capture-btn">
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z"/><circle cx="12" cy="13" r="4"/></svg>
+      التقط صورة / أضف ملف
+    </label>
+    <input type="file" id="stageMultiInput" multiple accept=".jpg,.jpeg,.png,.webp,.pdf" class="file-input">
+    <label for="stageMultiInput" class="btn btn-secondary btn-large">
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+      اختر عدة ملفات
+    </label>
+  </div>
+
+  <div id="stagingGallery" class="staging-gallery hidden"></div>
+  <div id="stagingCount" class="staging-count hidden"></div>
+
+  <div id="stagingActions" class="upload-actions hidden">
+    <div class="provider-section">
+      <label class="provider-label">محرك الاستخراج:</label>
+      <div class="provider-options">
+        {% for p in providers %}
+        <label class="provider-option">
+          <input type="radio" name="stage_provider" value="{{ p.id }}"
+                 {{ 'checked' if p.id == default_provider else '' }}>
+          <span class="provider-card {{ 'provider-free' if p.id == 'easyocr' else 'provider-ai' }}">
+            <span class="provider-name">{{ p.name }}</span>
+            <span class="provider-model">{{ p.model }}</span>
+          </span>
+        </label>
+        {% endfor %}
+      </div>
+    </div>
+    <div class="stage-action-buttons">
+      <button type="button" class="btn btn-primary btn-large" id="processAllBtn" onclick="processStaged()">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polygon points="5 3 19 12 5 21 5 3"/></svg>
+        معالجة الكل
+      </button>
+      <button type="button" class="btn btn-secondary" onclick="clearStaged()">مسح الكل</button>
+    </div>
+  </div>
+</div>
+
 <div class="quick-links">
   <a href="/search" class="quick-link-card">
     <span class="ql-icon">
@@ -141,5 +192,113 @@ document.getElementById('uploadForm').addEventListener('submit', function() {
   document.querySelector('.btn-primary').textContent = 'جارٍ الرفع...';
   document.querySelector('.btn-primary').disabled = true;
 });
+
+// ─── Staging workflow ─────────────────────────────────────────
+const stagedItems = []; // {id, image_path, name}
+
+async function stageFiles(fileInputEl) {
+  const files = fileInputEl.files;
+  if (!files.length) return;
+
+  for (const file of files) {
+    const formData = new FormData();
+    formData.append('files', file);
+
+    const thumb = addStagingPlaceholder(file.name);
+
+    try {
+      const res = await fetch('/upload/stage', { method: 'POST', body: formData });
+      const data = await res.json();
+      for (const item of data.staged) {
+        stagedItems.push(item);
+        updateStagingThumb(thumb, item);
+      }
+    } catch (e) {
+      thumb.remove();
+      alert('خطأ في رفع الملف: ' + file.name);
+    }
+  }
+
+  fileInputEl.value = '';
+  refreshStagingUI();
+}
+
+function addStagingPlaceholder(name) {
+  const gallery = document.getElementById('stagingGallery');
+  gallery.classList.remove('hidden');
+  const div = document.createElement('div');
+  div.className = 'staging-thumb loading';
+  div.innerHTML = `<div class="staging-thumb-spinner"></div><span class="staging-thumb-name">${name}</span>`;
+  gallery.appendChild(div);
+  return div;
+}
+
+function updateStagingThumb(thumb, item) {
+  thumb.classList.remove('loading');
+  thumb.dataset.id = item.id;
+  thumb.innerHTML = `
+    <img src="/uploads/${item.image_path}" alt="${item.name}">
+    <span class="staging-thumb-name">${item.name}</span>
+    <button type="button" class="staging-remove" onclick="removeStagedItem(${item.id}, this)" title="إزالة">&times;</button>
+  `;
+}
+
+async function removeStagedItem(id, btn) {
+  const thumb = btn.closest('.staging-thumb');
+  thumb.classList.add('removing');
+  try {
+    await fetch('/upload/staged/' + id, { method: 'DELETE' });
+  } catch (e) { /* ignore */ }
+  const idx = stagedItems.findIndex(s => s.id === id);
+  if (idx !== -1) stagedItems.splice(idx, 1);
+  thumb.remove();
+  refreshStagingUI();
+}
+
+function refreshStagingUI() {
+  const count = stagedItems.length;
+  const countEl = document.getElementById('stagingCount');
+  const actionsEl = document.getElementById('stagingActions');
+  const gallery = document.getElementById('stagingGallery');
+
+  if (count > 0) {
+    countEl.textContent = `${count} صورة جاهزة للمعالجة`;
+    countEl.classList.remove('hidden');
+    actionsEl.classList.remove('hidden');
+  } else {
+    countEl.classList.add('hidden');
+    actionsEl.classList.add('hidden');
+    gallery.classList.add('hidden');
+  }
+}
+
+async function processStaged() {
+  if (!stagedItems.length) return;
+  const ids = stagedItems.map(s => s.id).join(',');
+  const provider = document.querySelector('input[name="stage_provider"]:checked')?.value || '';
+
+  const btn = document.getElementById('processAllBtn');
+  btn.textContent = 'جارٍ المعالجة...';
+  btn.disabled = true;
+
+  const form = document.createElement('form');
+  form.method = 'POST';
+  form.action = '/upload/process-staged';
+  form.innerHTML = `<input type="hidden" name="doc_ids" value="${ids}"><input type="hidden" name="provider" value="${provider}">`;
+  document.body.appendChild(form);
+  form.submit();
+}
+
+async function clearStaged() {
+  for (const item of [...stagedItems]) {
+    try { await fetch('/upload/staged/' + item.id, { method: 'DELETE' }); } catch(e) {}
+  }
+  stagedItems.length = 0;
+  document.getElementById('stagingGallery').innerHTML = '';
+  refreshStagingUI();
+}
+
+document.getElementById('stageFileInput').addEventListener('change', function() { stageFiles(this); });
+document.getElementById('stageMultiInput').addEventListener('change', function() { stageFiles(this); });
 </script>
 {% endblock %}

templates/review.html

@@ -54,6 +54,18 @@
   <div class="form-panel">
     <form id="reviewForm">
 
+      {% if doc.get('pdf_group_id') and (doc.get('page_number') or 0) > 1 %}
+      <div class="info-banner page-group-banner">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
+        هذه الصفحة {{ doc.page_number }} من مستند متعدد الصفحات.
+        {% if doc.get('inherited_from_page1') %}
+        بيانات الشخص مستوردة تلقائياً من الصفحة الأولى.
+        {% else %}
+        يرجى التأكد من بيانات الشخص يدوياً.
+        {% endif %}
+      </div>
+      {% endif %}
+
       <!-- Person Info -->
       <section class="form-section">
         <h3>بيانات الشخص</h3>