Cap FSA/DCFSA reimbursements at election limit and fix HSA balance chart

FSA/DCFSA capacity capping:
- Replace rejection with automatic capping when reimbursement exceeds remaining election capacity
- Add get_fsa_remaining_capacity() and cap_amount_to_capacity() methods
- Fix DCFSA capacity calculation for combined plans (HSA+DCFSA, FSA+DCFSA)
- Update PATCH endpoint to use ExpenseService for proper validation
- Return capping_info in API responses when amount is capped

HSA balance chart fix:
- Calculate historical balances backwards from current balance
- Ensures upward trajectory when adding historical expenses with existing balance
- Starting balance derived as: current_balance - net_effect_of_all_transactions

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

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

Author: JavaDogWebDesign

app/routes/expenses.py

@@ -17,6 +17,7 @@
     ExpenseValidationError,
     CategoryConflictError,
     CapacityExceededError,
+    CapacityResult,
 )
 
 expenses_bp = Blueprint('expenses', __name__)
@@ -101,7 +102,7 @@ def create_expense():
         }
 
         # Create expense
-        expense_id = service.create_expense(user_id, expense_data)
+        expense_id, capacity_result = service.create_expense(user_id, expense_data)
 
         # Handle file uploads
         if 'receipts' in request.files:
@@ -127,7 +128,21 @@ def create_expense():
 
         # Fetch the created expense to return full data for optimistic UI
         created_expense = service.get_expense(expense_id, user_id)
-        return jsonify({'success': True, 'expense_id': expense_id, 'expense': created_expense})
+
+        # Build response
+        response = {'success': True, 'expense_id': expense_id, 'expense': created_expense}
+
+        # Add capping info if reimbursement was capped
+        if capacity_result and capacity_result.was_capped:
+            response['reimbursement_capped'] = True
+            response['capping_info'] = {
+                'original_amount': capacity_result.original_amount,
+                'capped_amount': capacity_result.capped_amount,
+                'remaining_capacity': capacity_result.remaining_capacity,
+                'message': f'Reimbursement was capped at ${capacity_result.capped_amount:.2f} (remaining {expense_data["category"]} election capacity)'
+            }
+
+        return jsonify(response)
 
     except CategoryConflictError as e:
         conn.rollback()
@@ -155,19 +170,30 @@ def update_expense(expense_id: int):
 
     try:
         service = ExpenseService(conn)
-        service.update_expense(expense_id, user_id, data)
+        _, capacity_result = service.update_expense(expense_id, user_id, data)
         conn.commit()
 
         # Fetch the updated expense to return full data for optimistic UI
         updated_expense = service.get_expense(expense_id, user_id)
-        return jsonify({'success': True, 'expense': updated_expense})
+
+        # Build response
+        response = {'success': True, 'expense': updated_expense}
+
+        # Add capping info if reimbursement was capped
+        if capacity_result and capacity_result.was_capped:
+            response['reimbursement_capped'] = True
+            response['capping_info'] = {
+                'original_amount': capacity_result.original_amount,
+                'capped_amount': capacity_result.capped_amount,
+                'remaining_capacity': capacity_result.remaining_capacity,
+                'message': f'Reimbursement was capped at ${capacity_result.capped_amount:.2f} (remaining election capacity)'
+            }
+
+        return jsonify(response)
 
     except CategoryConflictError as e:
         conn.rollback()
         return jsonify({'error': e.message}), 400
-    except CapacityExceededError as e:
-        conn.rollback()
-        return jsonify({'error': e.message}), 400
     except ExpenseValidationError as e:
         conn.rollback()
         if 'not found' in e.message.lower():
@@ -183,17 +209,19 @@ def update_expense(expense_id: int):
 @expenses_bp.route('/api/expenses/<int:expense_id>', methods=['PATCH'])
 @login_required
 def patch_expense(expense_id: int):
-    """API endpoint to partially update an expense (status, provider, amount_inflow)."""
+    """API endpoint to partially update an expense (status, provider, amount_inflow).
+
+    Uses the ExpenseService to ensure FSA/DCFSA capacity validation and HSA balance tracking.
+    """
     data = request.json
     user_id = session['user_id']
     conn = get_db_connection()
 
     try:
+        service = ExpenseService(conn)
+
         # Get current expense for smart reimbursement logic
-        expense = conn.execute(
-            'SELECT id, amount_outflow FROM expenses WHERE id = ? AND user_id = ?',
-            (expense_id, user_id)
-        ).fetchone()
+        expense = service.get_expense(expense_id, user_id)
 
         if not expense:
             return jsonify({'error': 'Expense not found'}), 404
@@ -213,19 +241,36 @@ def patch_expense(expense_id: int):
         if not filtered_data:
             return jsonify({'error': 'No valid fields to update'}), 400
 
-        # Build update query
-        fields = [f"{field} = ?" for field in filtered_data.keys()]
-        values = list(filtered_data.values())
-        fields.append("updated_at = ?")
-        values.append(datetime.now().isoformat())
-        values.extend([expense_id, user_id])
-
-        query = f"UPDATE expenses SET {', '.join(fields)} WHERE id = ? AND user_id = ?"
-        conn.execute(query, values)
+        # Use the service to update (handles FSA/DCFSA capacity capping and HSA balance)
+        _, capacity_result = service.update_expense(expense_id, user_id, filtered_data)
         conn.commit()
 
-        return jsonify({'success': True})
+        # Fetch updated expense
+        updated_expense = service.get_expense(expense_id, user_id)
+
+        # Build response
+        response = {'success': True, 'expense': updated_expense}
 
+        # Add capping info if reimbursement was capped
+        if capacity_result and capacity_result.was_capped:
+            response['reimbursement_capped'] = True
+            response['capping_info'] = {
+                'original_amount': capacity_result.original_amount,
+                'capped_amount': capacity_result.capped_amount,
+                'remaining_capacity': capacity_result.remaining_capacity,
+                'message': f'Reimbursement was capped at ${capacity_result.capped_amount:.2f} (remaining {expense["category"]} election capacity)'
+            }
+
+        return jsonify(response)
+
+    except CategoryConflictError as e:
+        conn.rollback()
+        return jsonify({'error': e.message}), 400
+    except ExpenseValidationError as e:
+        conn.rollback()
+        if 'not found' in e.message.lower():
+            return jsonify({'error': e.message}), 404
+        return jsonify({'error': e.message}), 400
     except Exception as e:
         conn.rollback()
         return jsonify({'error': str(e)}), 500