feat: implement reminder preferences and withdrawal (Stories 6.3, 6.2)

Implement Phase 3 participant self-management features:

Story 6.3 - Reminder Preferences:
- Add ReminderPreferenceForm to participant forms
- Add update_preferences route for preference updates
- Update dashboard template with reminder preference toggle
- Participants can enable/disable reminder emails at any time

Story 6.2 - Withdrawal from Exchange:
- Add can_withdraw utility function for state validation
- Create WithdrawalService to handle withdrawal process
- Add WithdrawForm with explicit confirmation requirement
- Add withdraw route with GET (confirmation) and POST (process)
- Add withdrawal confirmation email template
- Update dashboard to show withdraw link when allowed
- Withdrawal only allowed before registration closes
- Session cleared after withdrawal, user redirected to registration

All acceptance criteria met for both stories.
Test coverage: 90.02% (156 tests passing)
Linting and type checking: passed

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/app.py

@@ -145,6 +145,8 @@ def register_setup_check(app: Flask) -> None:
             "participant.dashboard",
             "participant.logout",
             "participant.profile_edit",
+            "participant.update_preferences",
+            "participant.withdraw",
         ]:
             return
 

src/forms/participant.py

@@ -1,7 +1,7 @@
 """Forms for participant registration and management."""
 
 from flask_wtf import FlaskForm
-from wtforms import BooleanField, EmailField, StringField, TextAreaField
+from wtforms import BooleanField, EmailField, StringField, SubmitField, TextAreaField
 from wtforms.validators import DataRequired, Email, Length
 
 
@@ -70,3 +70,26 @@ class ProfileUpdateForm(FlaskForm):
         description="Optional wishlist or gift preferences for your Secret Santa",
         render_kw={"rows": 6, "maxlength": 10000},
     )
+
+
+class ReminderPreferenceForm(FlaskForm):
+    """Form for updating reminder email preferences."""
+
+    reminder_enabled = BooleanField(
+        "Send me reminder emails before the exchange date",
+        description="You can change this at any time",
+    )
+
+
+class WithdrawForm(FlaskForm):
+    """Form for confirming withdrawal from exchange.
+
+    Requires explicit confirmation to prevent accidental withdrawals.
+    """
+
+    confirm = BooleanField(
+        "I understand this cannot be undone and I will need to re-register to rejoin",
+        validators=[DataRequired(message="You must confirm to withdraw")],
+    )
+
+    submit = SubmitField("Withdraw from Exchange")

src/routes/participant.py

@@ -21,6 +21,8 @@ from src.forms.participant import (
     MagicLinkRequestForm,
     ParticipantRegistrationForm,
     ProfileUpdateForm,
+    ReminderPreferenceForm,
+    WithdrawForm,
 )
 from src.models.exchange import Exchange
 from src.models.magic_token import MagicToken
@@ -346,10 +348,20 @@ def dashboard(id: int):  # noqa: A002
         abort(404)
 
     # Get list of active participants
-    from src.utils.participant import can_update_profile, get_active_participants
+    from src.utils.participant import (
+        can_update_profile,
+        can_withdraw,
+        get_active_participants,
+    )
 
     participants = get_active_participants(exchange.id)
     can_edit = can_update_profile(participant)
+    can_leave = can_withdraw(participant)
+
+    # Create reminder preference form
+    reminder_form = ReminderPreferenceForm(
+        reminder_enabled=participant.reminder_enabled
+    )
 
     return render_template(
         "participant/dashboard.html",
@@ -358,6 +370,8 @@ def dashboard(id: int):  # noqa: A002
         participants=participants,
         participant_count=len(participants),
         can_edit_profile=can_edit,
+        can_withdraw=can_leave,
+        reminder_form=reminder_form,
     )
 
 
@@ -420,6 +434,114 @@ def profile_edit():
     )
 
 
+@participant_bp.route("/participant/preferences", methods=["POST"])
+@participant_required
+def update_preferences():
+    """Update participant reminder email preferences.
+
+    Returns:
+        Redirect to dashboard
+    """
+    from flask import current_app
+
+    participant = db.session.query(Participant).filter_by(id=session["user_id"]).first()
+    if not participant:
+        abort(404)
+
+    form = ReminderPreferenceForm()
+
+    if form.validate_on_submit():
+        try:
+            participant.reminder_enabled = form.reminder_enabled.data
+            db.session.commit()
+
+            if form.reminder_enabled.data:
+                flash("Reminder emails enabled.", "success")
+            else:
+                flash("Reminder emails disabled.", "success")
+
+        except Exception as e:
+            db.session.rollback()
+            current_app.logger.error(f"Failed to update preferences: {e}")
+            flash("Failed to update preferences. Please try again.", "error")
+    else:
+        flash("Invalid request.", "error")
+
+    return redirect(url_for("participant.dashboard", id=participant.exchange_id))
+
+
+@participant_bp.route("/participant/withdraw", methods=["GET", "POST"])
+@participant_required
+def withdraw():
+    """Withdraw from exchange (soft delete).
+
+    GET: Show confirmation page with warnings
+    POST: Process withdrawal, log out, redirect to public page
+
+    Returns:
+        GET: Withdrawal confirmation page
+        POST: Redirect to exchange registration page
+    """
+    from flask import current_app
+
+    participant = db.session.query(Participant).filter_by(id=session["user_id"]).first()
+    if not participant:
+        abort(404)
+
+    exchange = participant.exchange
+
+    # Check if withdrawal is allowed
+    from src.utils.participant import can_withdraw, is_withdrawn
+
+    if is_withdrawn(participant):
+        flash("You have already withdrawn from this exchange.", "info")
+        return redirect(url_for("participant.register", slug=exchange.slug))
+
+    if not can_withdraw(participant):
+        if exchange.state == "registration_closed":
+            message = "Registration has closed. Please contact the admin to withdraw."
+        else:
+            message = "Withdrawal is no longer available. Please contact the admin."
+        flash(message, "error")
+        return redirect(url_for("participant.dashboard", id=exchange.id))
+
+    # Create withdrawal confirmation form
+    form = WithdrawForm()
+
+    if form.validate_on_submit():
+        try:
+            # Perform withdrawal
+            from src.services.withdrawal import WithdrawalError, withdraw_participant
+
+            withdraw_participant(participant)
+
+            # Log out participant
+            session.clear()
+
+            flash(
+                "You have been withdrawn from the exchange. "
+                "A confirmation email has been sent.",
+                "success",
+            )
+            return redirect(url_for("participant.register", slug=exchange.slug))
+
+        except WithdrawalError as e:
+            flash(str(e), "error")
+            return redirect(url_for("participant.dashboard", id=exchange.id))
+
+        except Exception as e:
+            current_app.logger.error(f"Unexpected error during withdrawal: {e}")
+            flash("An unexpected error occurred. Please try again.", "error")
+
+    # GET request: show confirmation page
+    return render_template(
+        "participant/withdraw.html",
+        form=form,
+        participant=participant,
+        exchange=exchange,
+    )
+
+
 @participant_bp.route("/participant/logout", methods=["POST"])
 def logout():
     """Participant logout.

src/services/email.py

@@ -174,3 +174,53 @@ class EmailService:
         """
 
         return self.send_email(to=to, subject=subject, html_body=html_body)
+
+    def send_withdrawal_confirmation(self, participant: Any) -> Any:
+        """Send withdrawal confirmation email to participant.
+
+        Args:
+            participant: The participant who withdrew
+
+        Returns:
+            Response from email service
+        """
+        exchange = participant.exchange
+
+        subject = f"Withdrawal Confirmed - {exchange.name}"
+        html_body = f"""
+        <html>
+            <body>
+                <h2>Withdrawal Confirmed</h2>
+                <p>Hello {participant.name},</p>
+                <p>
+                    This email confirms that you have withdrawn from the
+                    Secret Santa exchange <strong>{exchange.name}</strong>.
+                </p>
+                <div style="background-color: #f8f9fa;
+                    border-left: 4px solid #e74c3c;
+                    padding: 15px; margin: 20px 0;">
+                    <p style="margin: 0;"><strong>What happens now:</strong></p>
+                    <ul style="margin: 10px 0;">
+                        <li>You have been removed from the participant list</li>
+                        <li>Your profile information has been archived</li>
+                        <li>
+                            You will not receive further emails about this exchange
+                        </li>
+                    </ul>
+                </div>
+                <p>
+                    If you withdrew by mistake, you can re-register using a
+                    different email address while registration is still open.
+                </p>
+                <hr style="border: none; border-top: 1px solid #ddd;
+                    margin: 30px 0;">
+                <p style="font-size: 12px; color: #666;">
+                    This is an automated message from Sneaky Klaus.
+                </p>
+            </body>
+        </html>
+        """
+
+        return self.send_email(
+            to=participant.email, subject=subject, html_body=html_body
+        )

src/services/withdrawal.py

@@ -0,0 +1,73 @@
+"""Participant withdrawal service."""
+
+from datetime import UTC, datetime
+
+from flask import current_app
+
+from src.app import db
+from src.models.participant import Participant
+from src.services.email import EmailService
+from src.utils.participant import can_withdraw
+
+
+class WithdrawalError(Exception):
+    """Raised when withdrawal operation fails."""
+
+    pass
+
+
+def withdraw_participant(participant: Participant) -> None:
+    """Withdraw a participant from their exchange.
+
+    This performs a soft delete by setting withdrawn_at timestamp.
+    Participant record is retained for audit trail.
+
+    Args:
+        participant: The participant to withdraw
+
+    Raises:
+        WithdrawalError: If withdrawal is not allowed
+
+    Side effects:
+        - Sets participant.withdrawn_at to current UTC time
+        - Commits database transaction
+        - Sends withdrawal confirmation email
+    """
+    # Validate withdrawal is allowed
+    if not can_withdraw(participant):
+        if participant.withdrawn_at is not None:
+            raise WithdrawalError("You have already withdrawn from this exchange.")
+
+        exchange = participant.exchange
+        if exchange.state == "registration_closed":
+            raise WithdrawalError(
+                "Registration has closed. Please contact the admin to withdraw."
+            )
+        elif exchange.state in ["matched", "completed"]:
+            raise WithdrawalError(
+                "Matching has already occurred. Please contact the admin."
+            )
+        else:
+            raise WithdrawalError("Withdrawal is not allowed at this time.")
+
+    # Perform withdrawal
+    participant.withdrawn_at = datetime.now(UTC)
+
+    try:
+        db.session.commit()
+        current_app.logger.info(
+            f"Participant {participant.id} withdrawn from "
+            f"exchange {participant.exchange_id}"
+        )
+    except Exception as e:
+        db.session.rollback()
+        current_app.logger.error(f"Failed to withdraw participant: {e}")
+        raise WithdrawalError("Failed to process withdrawal. Please try again.") from e
+
+    # Send confirmation email
+    try:
+        email_service = EmailService()
+        email_service.send_withdrawal_confirmation(participant)
+    except Exception as e:
+        current_app.logger.error(f"Failed to send withdrawal email: {e}")
+        # Don't raise - withdrawal already committed

src/templates/participant/dashboard.html

@@ -61,6 +61,34 @@
         {% endif %}
     </section>
 
+    <section>
+        <h2>Email Reminders</h2>
+        <form method="POST" action="{{ url_for('participant.update_preferences') }}">
+            {{ reminder_form.hidden_tag() }}
+            <div>
+                {{ reminder_form.reminder_enabled() }}
+                {{ reminder_form.reminder_enabled.label }}
+            </div>
+            {% if reminder_form.reminder_enabled.description %}
+            <small>{{ reminder_form.reminder_enabled.description }}</small>
+            {% endif %}
+            <button type="submit">Update Preferences</button>
+        </form>
+    </section>
+
+    {% if can_withdraw %}
+    <section>
+        <h2>Withdraw from Exchange</h2>
+        <p>
+            If you can no longer participate, you can withdraw from this exchange.
+            This cannot be undone.
+        </p>
+        <a href="{{ url_for('participant.withdraw') }}" role="button" class="secondary">
+            Withdraw from Exchange
+        </a>
+    </section>
+    {% endif %}
+
     <section>
         <form method="POST" action="{{ url_for('participant.logout') }}">
             <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">

src/templates/participant/withdraw.html

@@ -0,0 +1,47 @@
+{% extends "layouts/base.html" %}
+
+{% block title %}Withdraw from {{ exchange.name }}{% endblock %}
+
+{% block content %}
+<article>
+    <header>
+        <h1>Withdraw from Exchange</h1>
+    </header>
+
+    <div role="alert" style="background-color: #fff3cd; border-left: 4px solid #ffc107; padding: 1rem; margin: 1rem 0;">
+        <h2 style="margin-top: 0;">⚠️ Are you sure?</h2>
+        <p>Withdrawing from this exchange means:</p>
+        <ul>
+            <li>Your registration will be cancelled</li>
+            <li>You will be removed from the participant list</li>
+            <li>You cannot undo this action</li>
+            <li>You will need to re-register with a different email to rejoin</li>
+        </ul>
+    </div>
+
+    <form method="POST" action="{{ url_for('participant.withdraw') }}">
+        {{ form.hidden_tag() }}
+
+        <div>
+            <label>
+                {{ form.confirm() }}
+                {{ form.confirm.label.text }}
+            </label>
+            {% if form.confirm.errors %}
+            <ul style="color: #dc3545; list-style: none; padding: 0;">
+                {% for error in form.confirm.errors %}
+                <li>{{ error }}</li>
+                {% endfor %}
+            </ul>
+            {% endif %}
+        </div>
+
+        <div>
+            {{ form.submit(class="contrast") }}
+            <a href="{{ url_for('participant.dashboard', id=exchange.id) }}" role="button" class="secondary">
+                Cancel
+            </a>
+        </div>
+    </form>
+</article>
+{% endblock %}

src/utils/participant.py

@@ -53,3 +53,24 @@ def can_update_profile(participant: "Participant") -> bool:
     exchange = participant.exchange
     allowed_states = ["draft", "registration_open", "registration_closed"]
     return exchange.state in allowed_states
+
+
+def can_withdraw(participant: "Participant") -> bool:
+    """Check if participant can withdraw from the exchange.
+
+    Withdrawals are only allowed before registration closes.
+    After that, admin intervention is required.
+
+    Args:
+        participant: The participant to check
+
+    Returns:
+        True if withdrawal is allowed, False otherwise
+    """
+    # Already withdrawn
+    if participant.withdrawn_at is not None:
+        return False
+
+    exchange = participant.exchange
+    allowed_states = ["draft", "registration_open"]
+    return exchange.state in allowed_states