074-merchant-backend-simplification.rst (10923B)
1 DD 74: Merchant Backend Simplification 2 ###################################### 3 4 :Design status: Draft 5 :Implementation status: Not started 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold, Christian Grothoff, Sebastian 8 :First published: 2025-11-13 9 :Last substantive change: 2026-02-05 10 11 Summary 12 ======= 13 14 This design document proposes simplifications to the merchant backend user interface. 15 16 Motivation 17 ========== 18 19 The current merchant backend SPA provides a user interface tailored towards 20 expert users that know the underlying protocol concepts. 21 22 Requirements 23 ============ 24 25 * The merchant backend SPA should be usable by non-experts 26 * Different normal users will have different use-cases, requirements 27 and background, so one-size-fits-all does not apply. 28 * The merchant backend SPA should remain as a tool for expert users 29 * We do not want to maintain different versions of the merchant backend SPA 30 31 32 Proposed Solution (Iteration 1) 33 =============================== 34 35 Existing Pages 36 ^^^^^^^^^^^^^^ 37 38 What follows is a listing of the menu entries 39 in the merchant UI as of 2025-11-13. It serves as the 40 basis of further discussion in this document. 41 42 43 Top-Level (unnamed) 44 45 * Orders 46 * Inventory 47 * Categories 48 * Wire transfers 49 * Templates 50 * KYC Status 51 52 Configuration: 53 54 * Bank accounts 55 * OTP Devices 56 * Webhooks 57 * Settings 58 * Password 59 * Access tokens 60 61 Connection: 62 63 * Interface 64 65 Instances: 66 67 * New 68 * List 69 * Logout 70 71 72 Personas 73 ^^^^^^^^ 74 75 * Personas are a preset of feature flags and other settings 76 * The backend provides a default persona. After login, the UI for 77 this persona is chosen. It can be changed in the "Personalization" menu. 78 * We do not call it "profiles", because it clashes with the "profile" terminology 79 as it is typically used in UIs (contact info, profile picture, ...). 80 81 82 Persona Definitions 83 ^^^^^^^^^^^^^^^^^^^ 84 85 * ``Beta tester`` 86 87 * Every feature flag on 88 * Should come last in the drop-down 89 90 * ``Expert`` 91 92 * All basic features 93 * Second to last in dropdown 94 * No Age restriction 95 * No token families 96 * No product taxes 97 * No refreshable scopes 98 99 * ``Unattended in-person offline vending`` (minimal farm shop) showing: 100 101 * ``Orders``, but exclude ``+``-button for creating new orders manually, 102 that's already a power-user feature. 103 104 * ``Templates``, but exclude OTP devices, only useful for power-users. 105 106 * ``KYC status`` (but only if action required) 107 108 * ``Bank accounts``, including KYC status 109 110 * ``Settings`` 111 112 * ``Logout`` 113 114 115 * ``Unattended in-person offline vending with inventory``, 116 (this choice should only be enabled once we have the next 117 version of templates with inventory!) showing: 118 119 * Orders, but exclude ``+`` button for creating new orders manually, 120 that's already a power-user feature. 121 122 * ``Inventory`` (once supported by templates!) 123 124 * ``Categories`` (once supported by templates!) 125 126 * ``Templates``, but exclude OTP devices, again, HW doesn't exist yet, 127 and only useful for power-users. Without age restriction and paymentTimeout option. 128 129 * ``KYC status`` (if action required) 130 131 * ``Bank accounts`` 132 133 * ``Settings`` 134 135 * ``Logout`` 136 137 * ``In-person online point-of-sale with inventory`` showing: 138 139 * ``Orders``, but exclude ``+``-button for creating new orders manually, 140 that's already a power-user feature. 141 142 * ``Inventory`` 143 144 * ``Categories`` 145 146 * ``Access tokens`` 147 148 * ``KYC status`` (if action required) 149 150 * ``Bank accounts`` 151 152 * ``Settings`` 153 154 * ``Logout`` 155 156 * ``Digital publishing`` showing: 157 158 * ``Orders``, but exclude ``+``- button for creating new orders manually, 159 that's already a power-user feature. 160 161 * ``Subscriptions and Discounts`` (only after v1.6) 162 163 * ``Access tokens`` 164 165 * ``KYC status`` (if action required) 166 167 * ``Bank accounts`` 168 169 * ``Settings`` 170 171 * ``Logout`` 172 173 * ``E-commerce site`` showing: 174 175 * ``Orders``, but exclude ``+``-button for creating new orders manually, 176 that's already a power-user feature. 177 178 * ``Subscriptions and Discounts`` (only after v1.6) 179 180 * ``Webhooks`` 181 182 * ``Access tokens`` 183 184 * ``KYC status`` (if action required) 185 186 * ``Bank accounts`` 187 188 * ``Settings`` 189 190 * ``Logout`` 191 192 193 Proposed Solution (Iteration 2) 194 =============================== 195 196 .. warning:: 197 198 The proposed simplifications here 199 are still under discussion and will only 200 be implemented once iteration 2 is done. 201 202 203 Simplification of Resource Identifiers 204 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 205 206 Currently, the user has to choose the resource identifier for templates, 207 products, and so on. It's not clear to the typical user *why* they have to 208 choose this, so we should provide a reasonable default for the resource ID. 209 210 https://bugs.gnunet.org/view.php?id=10620 211 212 213 Simplication of Bank Account Settings 214 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 215 216 Currently we have three screens involving the bank account: 217 ``Bank accounts`` (under configuration), 218 ``KYC Status`` and ``Wire transfers``. 219 220 Since all of the activities done on this screen are related to the bank 221 account, we can simplify it into one ``Bank accounts`` page. 222 223 .. note:: 224 225 When adding a bank account, we should only show the simplified 226 dialog (IBAN, account owner information) and not the 227 WireGateway part *unless* in "show everything" and/or "beta tester" 228 mode. In terms of entering account owner information, we should 229 allow entering more data, like ZIP code, City name, etc. as these 230 are becoming more-and-more required. So not just "receiver-name". 231 (But everything but receiver-name can be optional for now.) 232 233 The wire transfers can be shown by clicking on the details page of a bank account. 234 235 .. note:: 236 237 This feature needs more testing, I think we should only show 238 it in ``Developer`` mode for now! 239 240 The KYC status can also be shown in the table of the bank accounts. 241 242 If KYC is required for a bank account, we can both highlight the bank account 243 *and* also add a ``KYC required`` highlighted menu item that directly goes to 244 the KYC status of a bank account that requires action. 245 246 247 Screens (in improved version): 248 249 * overview screen with list of bank accounts 250 251 * Wire method (iban / x-taler-bank 252 * Account ("<iban> · <name>" / "<account name> · <host>") 253 254 * Host should not contain http(s):// 255 * Owner's name 256 * Readiness (show emoji, text on hover) 257 258 * ✅ Ok 259 * ⚠️ Action Required 260 * ❌ Not working 261 * "Wire transfers" button => takes use to wire transfers page, with account selected 262 * "Edit" button 263 * "Delete" button 264 265 On click of a row with a bank account: Expand to show details 266 267 Details of an expanded row: 268 269 * list of exchanges that require an action 270 * Button "Show all exchanges" 271 272 * Pop ups a table with all exchanges, their status and limits 273 274 * Grouped by "supported / "unavailable" exchanges for this account 275 in collapsible sections, with the "unavailable" collapsed by default? 276 * The "unavailable" section both has exchanges that are not reachable (network issues etc.) 277 and ones that are incompatible w.r.t. currency or supported wire methods. 278 279 * Columns for "supported": 280 281 * Exchange URL 282 * Status ("ok", "action required", "limit reached") 283 * Limits (e.g. "Deposit: 50 CHF / month, 1500 CHF / year") 284 285 * Columns for "unavailable": 286 287 * Exchange URL 288 * Reason ("currency mismatch", "wire method mismatch", "exchange is offline") 289 290 291 ----- 292 293 Wire transfers page: 294 295 Tab "Incoming": 296 297 * Expected amount 298 * Expected time 299 * Exchange URL 300 * Wire transfer ID (= expected subject?) 301 * Button "Confirm" 302 * If there's an error: Show "⚠️"-Element, 303 when the row is clicked, it expands to show the error message 304 305 Tab "Confirmed": 306 * amount 307 * time 308 * Exchange URL 309 * Wire transfer ID (= expected subject?) 310 * Button "Undo confirmation" 311 312 313 Simplication of OTP devices 314 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 315 316 ``OTP devices`` are only used in combination with templates. They are not 317 used for logins etc., which might make it confusing to always show them. 318 319 As a simplification, we could make the OTP devices *only* available via the 320 ``Templates`` screen. So the ``Templates`` screen would basically have two 321 tables (and ``+``-buttons), one for ``Templates`` and a second below 322 for ``OTP devices``. 323 324 325 Settings Structure 326 ^^^^^^^^^^^^^^^^^^ 327 328 Currently we have: 329 330 * ``Settings``: Contains five different types of settings: 331 332 * payment-technical settings: transaction fee, payment delay default 333 * contact information shown to the user 334 * instance deletion 335 * authentication-related settings (email / phone is used for auth) 336 337 * Interface: Contains user interface settings. 338 * Password: Change password 339 340 We should also separate the phone number and email shown to the user and 341 the one used for 2FA. 342 343 Suggested restructuring: 344 345 * ``Settings`` (with each sub-item as a collapsible section): 346 347 * ``Personalization`` (was: Interface, only UI settings, *maybe* link to other settings) 348 349 * ``Payment options`` 350 351 * default payment time 352 * refund time 353 * wire transfer time 354 * auto-refund time (?) 355 * STEFAN / payment fee options 356 357 * ``Public profile`` (Contact settings as seen by the wallet users via contract terms) 358 359 * We should add e-mail and phone number under the merchant ``address`` 360 in the contract terms (after all, they are contact addresses for the 361 merchant). Many advantages, starting with no change required in the 362 backend. 363 * Jurisdiction => We need more info on how merchants use this in practice 364 365 * ``Security`` (both password and 2FA-related fields) 366 367 * Password 368 * Phone number and e-mail address used for 2FA 369 * Access tokens 370 371 * Also show copyable base URL (#10657) 372 * Later: QR code for PoS setup (#9791) 373 374 * ``Integrations`` 375 376 * Webhooks 377 * Future: Connected devices and services 378 379 * For PoS access tokens 380 * For turnstile, wordpress, etc. 381 382 * ``About`` 383 384 * Version of UI 385 * Version of merchant backend 386 * backend base URL 387 388 389 Sidebar Simplification 390 ^^^^^^^^^^^^^^^^^^^^^^ 391 392 * Remove Wire transfers section (now redundant) 393 * Remove KYC Status section (now redundant) 394 * Remove OTP (now under Templates) 395 * Remove Webhooks (now under settings) 396 * Remove Passwords (now under settings) 397 * Remove Access Tokens (now under settings) 398 * Remove Personalization (now under settings) 399 * Remove merchant backoffice domain (now under settings->about) 400 * Move user login name at the top (instead of version) 401 * Remove version number (now under settings->about) 402 * Remove labels "Configuration" / "Connection" 403 404 Definition of Done 405 ================== 406 407 TBD. 408 409 Alternatives 410 ============ 411 412 TBD. 413 414 Drawbacks 415 ========= 416 417 TBD. 418 419 Discussion / Q&A 420 ================ 421 422 * Can the persona be changed while being logged in? 423 424 * Yes, under ``Personalization``, just like the language and date format. 425 426 * Can the user choose a person at login or instance creation? 427 428 * No, we want to avoid too many input fields / choices. 429 430 * Is the chosen persona persistent? 431 432 * Not for now, it's stored per local-storage.