feat(loyalty): pair POS terminal devices with one-time setup QR

Adds the backend half of the Android tablet rollout. Merchants can
pair tablets to specific stores from /merchants/loyalty/devices (or
admins can pair on behalf from the merchant detail page). Each
pairing issues a long-lived JWT shown ONCE in the response with a
server-rendered QR PNG containing {api_url, store_code, auth_token} —
the tablet scans it on first boot and persists the three fields.

The store API (/api/v1/store/loyalty/*) now accepts these device JWTs
alongside user JWTs. Revoking a device row immediately rejects its
token (401 TERMINAL_DEVICE_REVOKED). Tokens expire after 1 year;
re-pair to renew.

- Migration loyalty_010 + TerminalDevice model
- create_device_token / verify_device_token JWT helpers
- 5 endpoints x 2 portals (merchant + admin on-behalf)
- Bearer-auth wiring in app/api/deps.py
- Pages, shared list partial with one-time pairing-QR modal,
  Alpine.js factories
- Locale strings (en authoritative; fr/de/lb seeded with EN copy
  for translation)
- 6 integration tests covering pair, list, revoke, idempotency,
  cross-merchant rejection, store-API auth via device JWT

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/modules/loyalty/templates/loyalty/admin/merchant-devices.html

@@ -0,0 +1,27 @@
+{# app/modules/loyalty/templates/loyalty/admin/merchant-devices.html #}
+{% extends "admin/base.html" %}
+{% from 'shared/macros/headers.html' import detail_page_header, refresh_button %}
+{% from 'shared/macros/alerts.html' import loading_state, error_state %}
+
+{% block title %}{{ _('loyalty.terminal_devices.title') }}{% endblock %}
+{% block i18n_modules %}['loyalty']{% endblock %}
+{% block alpine_data %}adminMerchantDevices(){% endblock %}
+
+{% block content %}
+{% call detail_page_header("'" + _('loyalty.terminal_devices.title') + ": " + (merchant_name or '') + "'", '/admin/loyalty/merchants/' ~ merchant_id, subtitle_show='program') %}
+    {{ _('loyalty.terminal_devices.admin_subtitle') }}
+{% endcall %}
+
+{{ loading_state(_('loyalty.terminal_devices.loading')) }}
+{{ error_state(_('loyalty.terminal_devices.error_loading')) }}
+
+{% set devices_api_prefix = '/admin/loyalty/merchants/' + merchant_id|string %}
+{% set show_store_filter = true %}
+{% set show_crud = true %}
+{% include 'loyalty/shared/devices-list.html' %}
+{% endblock %}
+
+{% block extra_scripts %}
+<script defer src="{{ url_for('loyalty_static', path='shared/js/loyalty-devices-list.js') }}"></script>
+<script defer src="{{ url_for('loyalty_static', path='admin/js/loyalty-merchant-devices.js') }}"></script>
+{% endblock %}

app/modules/loyalty/templates/loyalty/merchant/devices.html

@@ -0,0 +1,36 @@
+{# app/modules/loyalty/templates/loyalty/merchant/devices.html #}
+{% extends "merchant/base.html" %}
+{% from 'shared/macros/headers.html' import page_header_flex, refresh_button %}
+{% from 'shared/macros/alerts.html' import loading_state, error_state %}
+
+{% block title %}{{ _('loyalty.terminal_devices.title') }}{% endblock %}
+
+{% block i18n_modules %}['loyalty']{% endblock %}
+
+{% block alpine_data %}merchantLoyaltyDevices(){% endblock %}
+
+{% block content %}
+{% call page_header_flex(title=_('loyalty.terminal_devices.title'), subtitle=_('loyalty.terminal_devices.subtitle')) %}
+    <div class="flex items-center gap-3">
+        {{ refresh_button(loading_var='loading', onclick='loadDevices()', variant='secondary') }}
+        <button @click="openPairModal()"
+                class="flex items-center px-4 py-2 text-sm font-medium text-white bg-purple-600 rounded-lg hover:bg-purple-700">
+            <span x-html="$icon('plus', 'w-4 h-4 mr-2')"></span>
+            {{ _('loyalty.terminal_devices.pair_device') }}
+        </button>
+    </div>
+{% endcall %}
+
+{{ loading_state(_('loyalty.terminal_devices.loading')) }}
+{{ error_state(_('loyalty.terminal_devices.error_loading')) }}
+
+{% set devices_api_prefix = '/merchants/loyalty' %}
+{% set show_store_filter = true %}
+{% set show_crud = true %}
+{% include 'loyalty/shared/devices-list.html' %}
+{% endblock %}
+
+{% block extra_scripts %}
+<script defer src="{{ url_for('loyalty_static', path='shared/js/loyalty-devices-list.js') }}"></script>
+<script defer src="{{ url_for('loyalty_static', path='merchant/js/loyalty-devices.js') }}"></script>
+{% endblock %}

app/modules/loyalty/templates/loyalty/shared/devices-list.html

@@ -0,0 +1,192 @@
+{# app/modules/loyalty/templates/loyalty/shared/devices-list.html #}
+{#
+  Shared terminal-devices list partial. Set these variables before including:
+    - devices_api_prefix (str): API base URL for device data
+    - show_store_filter (bool): Show store dropdown filter (true for merchant view)
+    - show_crud (bool): Show pair/revoke/delete actions (false for admin read-only)
+#}
+{% from 'shared/macros/alerts.html' import loading_state, error_state %}
+{% from 'shared/macros/tables.html' import table_wrapper, table_header %}
+{% from 'shared/macros/modals.html' import modal, confirm_modal_dynamic %}
+
+<!-- Filter Bar -->
+<div x-show="!loading" class="mb-6 p-4 bg-white rounded-lg shadow-xs dark:bg-gray-800">
+    <div class="flex flex-wrap items-center gap-4">
+        {% if show_store_filter %}
+        <select x-model="filters.store_id" @change="applyFilter()"
+                class="px-4 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg focus:border-purple-400 focus:outline-none dark:bg-gray-700 dark:text-gray-300">
+            <option value="">{{ _('loyalty.common.all_stores') }}</option>
+            <template x-for="loc in locations" :key="loc.store_id">
+                <option :value="loc.store_id" x-text="loc.store_name"></option>
+            </template>
+        </select>
+        {% endif %}
+        <label class="inline-flex items-center text-sm text-gray-700 dark:text-gray-300">
+            <input type="checkbox" x-model="filters.include_revoked" @change="applyFilter()"
+                   class="mr-2 rounded border-gray-300 text-purple-600 focus:ring-purple-500">
+            {{ _('loyalty.terminal_devices.show_revoked') }}
+        </label>
+    </div>
+</div>
+
+<!-- Devices Table -->
+<div x-show="!loading">
+    {% call table_wrapper() %}
+        {% if show_store_filter %}
+        {{ table_header([
+            _('loyalty.terminal_devices.col_label'),
+            _('loyalty.terminal_devices.col_store'),
+            _('loyalty.terminal_devices.col_status'),
+            _('loyalty.terminal_devices.col_last_seen'),
+            _('loyalty.terminal_devices.col_expires'),
+            _('loyalty.terminal_devices.col_actions'),
+        ]) }}
+        {% else %}
+        {{ table_header([
+            _('loyalty.terminal_devices.col_label'),
+            _('loyalty.terminal_devices.col_status'),
+            _('loyalty.terminal_devices.col_last_seen'),
+            _('loyalty.terminal_devices.col_expires'),
+            _('loyalty.terminal_devices.col_actions'),
+        ]) }}
+        {% endif %}
+        <tbody class="bg-white divide-y dark:divide-gray-700 dark:bg-gray-800">
+            <template x-if="devices.length === 0">
+                <tr>
+                    <td :colspan="'{{ '6' if show_store_filter else '5' }}'" class="px-4 py-8 text-center text-gray-600 dark:text-gray-400">
+                        <div class="flex flex-col items-center">
+                            <span x-html="$icon('device-tablet', 'w-12 h-12 mb-2 text-gray-300')"></span>
+                            <p class="font-medium">{{ _('loyalty.terminal_devices.no_devices') }}</p>
+                        </div>
+                    </td>
+                </tr>
+            </template>
+            <template x-for="device in devices" :key="device.id">
+                <tr class="text-gray-700 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-700">
+                    <td class="px-4 py-3 text-sm font-semibold" x-text="device.label"></td>
+                    {% if show_store_filter %}
+                    <td class="px-4 py-3 text-sm" x-text="device.store_name || '-'"></td>
+                    {% endif %}
+                    <td class="px-4 py-3 text-xs">
+                        <span class="px-2 py-1 font-semibold leading-tight rounded-full"
+                              :class="{
+                                  'text-green-700 bg-green-100 dark:bg-green-700 dark:text-green-100': device.status === 'active',
+                                  'text-red-700 bg-red-100 dark:bg-red-700 dark:text-red-100': device.status === 'revoked',
+                                  'text-yellow-700 bg-yellow-100 dark:bg-yellow-700 dark:text-yellow-100': device.status === 'expired'
+                              }"
+                              x-text="$t('loyalty.terminal_devices.status_' + device.status)"></span>
+                    </td>
+                    <td class="px-4 py-3 text-sm" x-text="device.last_seen_at ? formatDate(device.last_seen_at) : '-'"></td>
+                    <td class="px-4 py-3 text-sm" x-text="formatDate(device.expires_at)"></td>
+                    <td class="px-4 py-3">
+                        {% if show_crud %}
+                        <div class="flex items-center gap-2">
+                            <button x-show="device.status === 'active'" @click="confirmRevoke(device)" type="button"
+                                    aria-label="{{ _('loyalty.terminal_devices.revoke') }}"
+                                    class="text-orange-600 hover:text-orange-700 dark:text-orange-400 text-sm">
+                                <span x-html="$icon('lock-closed', 'w-4 h-4')"></span>
+                            </button>
+                            <button @click="confirmDelete(device)" type="button"
+                                    aria-label="{{ _('loyalty.common.delete') }}"
+                                    class="text-red-600 hover:text-red-700 dark:text-red-400 text-sm">
+                                <span x-html="$icon('trash', 'w-4 h-4')"></span>
+                            </button>
+                        </div>
+                        {% else %}
+                        <span class="text-sm text-gray-400">-</span>
+                        {% endif %}
+                    </td>
+                </tr>
+            </template>
+        </tbody>
+    {% endcall %}
+</div>
+
+{% if show_crud %}
+<!-- Pair Device Modal -->
+{% call modal('pairDeviceModal', _('loyalty.terminal_devices.pair_device'), 'showPairModal', size='md', show_footer=false) %}
+    <form @submit.prevent="pairDevice()">
+        <div class="space-y-4">
+            <div>
+                <label class="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">{{ _('loyalty.terminal_devices.label_field') }}</label>
+                <input type="text" x-model="pairForm.label" required minlength="1" maxlength="100"
+                       class="w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg focus:border-purple-400 focus:outline-none dark:bg-gray-700 dark:text-gray-300"
+                       placeholder="{{ _('loyalty.terminal_devices.label_placeholder') }}">
+            </div>
+            {% if show_store_filter %}
+            <div>
+                <label class="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">{{ _('loyalty.terminal_devices.store_field') }}</label>
+                <select x-model="pairForm.store_id" required
+                        class="w-full px-3 py-2 text-sm border border-gray-300 dark:border-gray-600 rounded-lg focus:border-purple-400 focus:outline-none dark:bg-gray-700 dark:text-gray-300">
+                    <option value="">{{ _('loyalty.terminal_devices.select_store') }}</option>
+                    <template x-for="loc in locations" :key="loc.store_id">
+                        <option :value="loc.store_id" x-text="loc.store_name"></option>
+                    </template>
+                </select>
+            </div>
+            {% endif %}
+            <p class="text-xs text-gray-500 dark:text-gray-400">{{ _('loyalty.terminal_devices.pair_hint') }}</p>
+        </div>
+        <div class="flex items-center justify-end gap-3 mt-6">
+            <button type="button" @click="showPairModal = false"
+                    class="px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-300 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-600 transition-colors">
+                {{ _('loyalty.common.cancel') }}
+            </button>
+            <button type="submit" :disabled="pairing"
+                    class="flex items-center px-4 py-2 text-sm font-medium text-white bg-purple-600 rounded-lg hover:bg-purple-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
+                <span x-show="pairing" x-html="$icon('spinner', 'w-4 h-4 mr-2')"></span>
+                <span x-text="pairing ? $t('loyalty.common.saving') : $t('loyalty.terminal_devices.pair_device')"></span>
+            </button>
+        </div>
+    </form>
+{% endcall %}
+
+<!-- QR Code Modal (one-time pairing reveal) -->
+{% call modal('pairingQrModal', _('loyalty.terminal_devices.pairing_qr'), 'showQrModal', size='md', show_footer=false, close_on_backdrop=false) %}
+    <div class="space-y-4">
+        <div class="rounded-md bg-yellow-50 dark:bg-yellow-900/30 border border-yellow-200 dark:border-yellow-800 p-3">
+            <p class="text-sm text-yellow-800 dark:text-yellow-200">
+                <strong>{{ _('loyalty.terminal_devices.qr_warning_title') }}</strong>
+                {{ _('loyalty.terminal_devices.qr_warning_body') }}
+            </p>
+        </div>
+        <div class="flex items-center justify-center bg-white p-4 rounded-lg" x-show="pairingResult">
+            <img :src="pairingResult.qr_png_base64" alt="Pairing QR code" class="w-64 h-64">
+        </div>
+        <details class="text-sm" x-show="pairingResult">
+            <summary class="cursor-pointer text-gray-600 dark:text-gray-400">{{ _('loyalty.terminal_devices.show_payload') }}</summary>
+            <pre class="mt-2 p-3 text-xs bg-gray-50 dark:bg-gray-900 rounded overflow-x-auto" x-text="JSON.stringify(pairingResult.setup_payload, null, 2)"></pre>
+        </details>
+        <div class="flex items-center justify-end">
+            <button @click="closeQrModal()" type="button"
+                    class="px-4 py-2 text-sm font-medium text-white bg-purple-600 rounded-lg hover:bg-purple-700">
+                {{ _('loyalty.terminal_devices.qr_done') }}
+            </button>
+        </div>
+    </div>
+{% endcall %}
+
+<!-- Revoke Confirm -->
+{{ confirm_modal_dynamic(
+    'revokeDeviceModal',
+    _('loyalty.terminal_devices.revoke_title'),
+    'revokeConfirmMessage',
+    'revokeDevice()',
+    'showRevokeModal',
+    confirm_text=_('loyalty.terminal_devices.revoke'),
+    cancel_text=_('loyalty.common.cancel'),
+    variant='warning'
+) }}
+
+<!-- Delete Confirm -->
+{{ confirm_modal_dynamic(
+    'deleteDeviceModal',
+    _('loyalty.terminal_devices.delete_title'),
+    'deleteConfirmMessage',
+    'deleteDevice()',
+    'showDeleteModal',
+    confirm_text=_('loyalty.common.delete'),
+    cancel_text=_('loyalty.common.cancel'),
+    variant='danger'
+) }}
+{% endif %}