Enhance Paperless integration with custom fields, storage paths, bulk sync

- Add custom fields support (Expense Amount, Reimbursed Amount, Claim Number,
  Status, Account Type, Family Member) for better organization in Paperless
- Add storage paths matching HSA Tracker's folder structure
  (HSA-Tracker/{category}/{year}/receipts for receipts, HSA-Tracker/benefit_plans/{year}
  for policy documents)
- Add bulk sync feature in settings to sync all unsynced documents at once
- Add "View in Paperless" link on synced items - clicking the green checkmark
  opens the document directly in Paperless
- Auto-update Paperless metadata when expense is edited (status, amounts, etc.)
- Wait for Paperless document processing to complete before applying metadata

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: JavaDogWebDesign

app/app.py

@@ -125,20 +125,27 @@ def inject_user_preferences():
         currency_symbol = get_currency_symbol(currency)
         user_date_format = get_user_date_format(user_id)
 
-        # Check if user has completed onboarding
+        # Check if user has completed onboarding and get Paperless config
         conn = get_db_connection()
-        user = conn.execute('SELECT onboarding_completed FROM users WHERE id = ?', (user_id,)).fetchone()
+        user = conn.execute('''SELECT onboarding_completed, paperless_url, paperless_enabled
+                              FROM users WHERE id = ?''', (user_id,)).fetchone()
         conn.close()
 
         is_first_login = False
         if user and not user['onboarding_completed']:
             is_first_login = True
 
+        # Build Paperless config for client-side use
+        paperless_config = None
+        if user and user['paperless_enabled'] and user['paperless_url']:
+            paperless_config = {'url': user['paperless_url'].rstrip('/')}
+
         return dict(
             user_currency=currency,
             currency_symbol=currency_symbol,
             user_date_format=user_date_format,
             is_first_login=is_first_login,
+            paperless_config=paperless_config,
             oidc_enabled=OIDC_ENABLED,
             oidc_allow_local_auth=ALLOW_LOCAL_AUTH,
             oidc_providers=get_oidc_providers_for_template()
@@ -148,6 +155,7 @@ def inject_user_preferences():
         currency_symbol='$',
         user_date_format=DEFAULT_DATE_FORMAT,
         is_first_login=False,
+        paperless_config=None,
         oidc_enabled=OIDC_ENABLED,
         oidc_allow_local_auth=ALLOW_LOCAL_AUTH,
         oidc_providers=get_oidc_providers_for_template()

app/assets/js/services/expenses.js

@@ -590,7 +590,7 @@ export function createEditReceiptItem(attachment, expenseId, allAttachments = nu
     const previewAttachments = allAttachments || [attachment];
 
     // Get sync status icon
-    const syncIcon = getSyncStatusIcon(attachment.paperless_sync_status);
+    const syncIcon = getSyncStatusIcon(attachment.paperless_sync_status, attachment.paperless_doc_id);
 
     if (fileType === 'pdf') {
         const iconDiv = document.createElement('div');
@@ -1045,11 +1045,24 @@ export function viewExpenseDetails(id) {
 }
 
 // Helper function to create sync status icon HTML
-function getSyncStatusIcon(syncStatus) {
+function getSyncStatusIcon(syncStatus, paperlessDocId = null) {
     if (!syncStatus) return ''; // Paperless not configured or not synced yet
 
+    // Get Paperless URL from global config (set by server)
+    const paperlessUrl = window.paperlessConfig?.url;
+
     switch (syncStatus) {
         case 'synced':
+            // If we have paperless URL and doc ID, make it a link
+            if (paperlessUrl && paperlessDocId) {
+                return `<a href="${paperlessUrl}/documents/${paperlessDocId}" target="_blank" rel="noopener"
+                          class="sync-status sync-synced" title="View in Paperless (opens in new tab)">
+                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
+                        <polyline points="22 4 12 14.01 9 11.01"/>
+                    </svg>
+                </a>`;
+            }
             return `<span class="sync-status sync-synced" title="Synced to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                     <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
@@ -1118,7 +1131,7 @@ function createAttachmentItem(attachment, expenseId, allAttachments = null, atta
     contentDiv.title = 'Click to preview';
 
     // Get sync status icon
-    const syncIcon = getSyncStatusIcon(attachment.paperless_sync_status);
+    const syncIcon = getSyncStatusIcon(attachment.paperless_sync_status, attachment.paperless_doc_id);
 
     if (fileType === 'pdf') {
         contentDiv.innerHTML = `

app/assets/js/services/policyYearDocuments.js

@@ -5,11 +5,24 @@ import { showAlert } from '../components/alerts.js';
 import { showConfirmModal } from '../components/confirmModal.js';
 
 // Helper function to create sync status icon HTML
-function getSyncStatusIcon(syncStatus) {
+function getSyncStatusIcon(syncStatus, paperlessDocId = null) {
     if (!syncStatus) return ''; // Paperless not configured or not synced yet
 
+    // Get Paperless URL from global config (set by server)
+    const paperlessUrl = window.paperlessConfig?.url;
+
     switch (syncStatus) {
         case 'synced':
+            // If we have paperless URL and doc ID, make it a link
+            if (paperlessUrl && paperlessDocId) {
+                return `<a href="${paperlessUrl}/documents/${paperlessDocId}" target="_blank" rel="noopener"
+                          class="sync-status sync-synced" title="View in Paperless (opens in new tab)">
+                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                        <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
+                        <polyline points="22 4 12 14.01 9 11.01"/>
+                    </svg>
+                </a>`;
+            }
             return `<span class="sync-status sync-synced" title="Synced to Paperless">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
                     <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/>
@@ -125,7 +138,7 @@ function createPolicyDocumentItem(doc) {
     const filePath = doc.file_path.replace(/^data\/\d+\//, '');
 
     // Get sync status icon
-    const syncIcon = getSyncStatusIcon(doc.paperless_sync_status);
+    const syncIcon = getSyncStatusIcon(doc.paperless_sync_status, doc.paperless_doc_id);
 
     // Check if it's an image type
     const isImage = ['jpg', 'jpeg', 'png'].includes(fileType);

app/routes/expenses.py

@@ -7,8 +7,9 @@
 from flask import Blueprint, request, jsonify, session
 from datetime import datetime
 import os
+import logging
 
-from database import get_db_connection
+from database import get_db_connection, db_readonly
 from utils.decorators import login_required
 from utils.helpers import get_user_receipts_folder, allowed_file, generate_attachment_filename, get_user_naming_patterns
 from services.expense_service import (
@@ -20,9 +21,59 @@
     CapacityResult,
 )
 
+logger = logging.getLogger(__name__)
 expenses_bp = Blueprint('expenses', __name__)
 
 
+def _update_paperless_for_expense(user_id: int, expense_id: int, expense_data: dict) -> None:
+    """Update Paperless documents for all synced attachments of an expense.
+
+    Args:
+        user_id: User ID
+        expense_id: Expense ID
+        expense_data: Dict with updated expense data (status, category, etc.)
+    """
+    try:
+        from services.paperless_service import update_document_in_paperless
+
+        # Get all synced attachments for this expense
+        with db_readonly() as conn:
+            attachments = conn.execute('''
+                SELECT a.paperless_doc_id, e.status, e.category, e.claim_number,
+                       e.amount_outflow, e.amount_inflow, f.name as family_member
+                FROM attachments a
+                JOIN expenses e ON a.expense_id = e.id
+                LEFT JOIN family_members f ON e.family_member_id = f.id
+                WHERE a.expense_id = ? AND a.paperless_sync_status = 'synced'
+                  AND a.paperless_doc_id IS NOT NULL
+            ''', (expense_id,)).fetchall()
+
+        # Update each synced attachment in Paperless
+        for attachment in attachments:
+            metadata = {
+                'status': expense_data.get('status', attachment['status']),
+                'category': expense_data.get('category', attachment['category']),
+                'claim_number': expense_data.get('claim_number', attachment['claim_number']),
+                'amount_outflow': expense_data.get('amount_outflow', attachment['amount_outflow']),
+                'amount_inflow': expense_data.get('amount_inflow', attachment['amount_inflow']),
+                'family_member': attachment['family_member'],
+                'doc_type': 'receipt'
+            }
+
+            success, message = update_document_in_paperless(
+                user_id=user_id,
+                paperless_doc_id=attachment['paperless_doc_id'],
+                metadata=metadata
+            )
+
+            if not success:
+                logger.warning(f"Failed to update Paperless document {attachment['paperless_doc_id']}: {message}")
+
+    except Exception as e:
+        # Don't fail the expense update if Paperless update fails
+        logger.error(f"Error updating Paperless for expense {expense_id}: {e}")
+
+
 @expenses_bp.route('/api/expenses', methods=['GET'])
 @login_required
 def get_expenses():
@@ -192,6 +243,9 @@ def update_expense(expense_id: int):
         # Fetch the updated expense to return full data for optimistic UI
         updated_expense = service.get_expense(expense_id, user_id)
 
+        # Update Paperless documents for this expense (non-blocking)
+        _update_paperless_for_expense(user_id, expense_id, updated_expense)
+
         # Build response
         response = {'success': True, 'expense': updated_expense}
 
@@ -264,6 +318,9 @@ def patch_expense(expense_id: int):
         # Fetch updated expense
         updated_expense = service.get_expense(expense_id, user_id)
 
+        # Update Paperless documents for this expense (non-blocking)
+        _update_paperless_for_expense(user_id, expense_id, updated_expense)
+
         # Build response
         response = {'success': True, 'expense': updated_expense}
 

app/routes/settings.py

@@ -601,3 +601,40 @@ def retry_paperless_sync():
         'success': success,
         'message': message
     })
+
+
+@settings_bp.route('/settings/paperless-unsynced-count', methods=['GET'])
+@login_required
+def paperless_unsynced_count():
+    """Get count of unsynced attachments and documents"""
+    from services.paperless_service import get_unsynced_count
+
+    user_id = session['user_id']
+    counts = get_unsynced_count(user_id)
+
+    return jsonify({
+        'success': True,
+        'counts': counts
+    })
+
+
+@settings_bp.route('/settings/paperless-bulk-sync', methods=['POST'])
+@login_required
+def paperless_bulk_sync():
+    """Sync all unsynced attachments and documents to Paperless"""
+    from services.paperless_service import bulk_sync_unsynced
+
+    user_id = session['user_id']
+    results = bulk_sync_unsynced(user_id)
+
+    if 'error' in results:
+        return jsonify({
+            'success': False,
+            'message': results['error']
+        }), 400
+
+    return jsonify({
+        'success': True,
+        'message': f"Synced {results['synced']} item(s). Failed: {results['failed']}. Skipped: {results['skipped']}.",
+        'results': results
+    })