074-merchant-backend-simplification.rst (10914B)
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 * Host should not contain http(s):// 254 * Owner's name 255 * Readiness (show emoji, text on hover) 256 257 * ✅ Ok 258 * ⚠️ Action Required 259 * ❌ Not working 260 * "Wire transfers" button => takes use to wire transfers page, with account selected 261 * "Edit" button 262 * "Delete" button 263 264 On click of a row with a bank account: Expand to show details 265 266 Details of an expanded row: 267 * list of exchanges that require an action 268 * Button "Show all exchanges" 269 270 * Pop ups a table with all exchanges, their status and limits 271 272 * Grouped by "supported / "unavailable" exchanges for this account 273 in collapsible sections, with the "unavailable" collapsed by default? 274 * The "unavailable" section both has exchanges that are not reachable (network issues etc.) 275 and ones that are incompatible w.r.t. currency or supported wire methods. 276 277 * Columns for "supported": 278 279 * Exchange URL 280 * Status ("ok", "action required", "limit reached") 281 * Limits (e.g. "Deposit: 50 CHF / month, 1500 CHF / year") 282 283 * Columns for "unavailable": 284 285 * Exchange URL 286 * Reason ("currency mismatch", "wire method mismatch", "exchange is offline") 287 288 289 ----- 290 291 Wire transfers page: 292 293 Tab "Incoming": 294 295 * Expected amount 296 * Expected time 297 * Exchange URL 298 * Wire transfer ID (= expected subject?) 299 * Button "Confirm" 300 * If there's an error: Show "⚠️"-Element, 301 when the row is clicked, it expands to show the error message 302 303 Tab "Confirmed": 304 * amount 305 * time 306 * Exchange URL 307 * Wire transfer ID (= expected subject?) 308 * Button "Undo confirmation" 309 310 311 Simplication of OTP devices 312 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 313 314 ``OTP devices`` are only used in combination with templates. They are not 315 used for logins etc., which might make it confusing to always show them. 316 317 As a simplification, we could make the OTP devices *only* available via the 318 ``Templates`` screen. So the ``Templates`` screen would basically have two 319 tables (and ``+``-buttons), one for ``Templates`` and a second below 320 for ``OTP devices``. 321 322 323 Settings Structure 324 ^^^^^^^^^^^^^^^^^^ 325 326 Currently we have: 327 328 * ``Settings``: Contains five different types of settings: 329 330 * payment-technical settings: transaction fee, payment delay default 331 * contact information shown to the user 332 * instance deletion 333 * authentication-related settings (email / phone is used for auth) 334 335 * Interface: Contains user interface settings. 336 * Password: Change password 337 338 We should also separate the phone number and email shown to the user and 339 the one used for 2FA. 340 341 Suggested restructuring: 342 343 * ``Settings`` (with each sub-item as a collapsible section): 344 345 * ``Personalization`` (was: Interface, only UI settings, *maybe* link to other settings) 346 347 * ``Payment options`` 348 349 * default payment time 350 * refund time 351 * wire transfer time 352 * auto-refund time (?) 353 * STEFAN / payment fee options 354 355 * ``Public profile`` (Contact settings as seen by the wallet users via contract terms) 356 357 * We should add e-mail and phone number under the merchant ``address`` 358 in the contract terms (after all, they are contact addresses for the 359 merchant). Many advantages, starting with no change required in the 360 backend. 361 * Jurisdiction => We need more info on how merchants use this in practice 362 363 * ``Security`` (both password and 2FA-related fields) 364 365 * Password 366 * Phone number and e-mail address used for 2FA 367 * Access tokens 368 369 * Also show copyable base URL (#10657) 370 * Later: QR code for PoS setup (#9791) 371 372 * ``Integrations`` 373 374 * Webhooks 375 * Future: Connected devices and services 376 377 * For PoS access tokens 378 * For turnstile, wordpress, etc. 379 380 * ``About`` 381 382 * Version of UI 383 * Version of merchant backend 384 * backend base URL 385 386 387 Sidebar Simplification 388 ^^^^^^^^^^^^^^^^^^^^^^ 389 390 * Remove Wire transfers section (now redundant) 391 * Remove KYC Status section (now redundant) 392 * Remove OTP (now under Templates) 393 * Remove Webhooks (now under settings) 394 * Remove Passwords (now under settings) 395 * Remove Access Tokens (now under settings) 396 * Remove Personalization (now under settings) 397 * Remove merchant backoffice domain (now under settings->about) 398 * Move user login name at the top (instead of version) 399 * Remove version number (now under settings->about) 400 * Remove labels "Configuration" / "Connection" 401 402 Definition of Done 403 ================== 404 405 TBD. 406 407 Alternatives 408 ============ 409 410 TBD. 411 412 Drawbacks 413 ========= 414 415 TBD. 416 417 Discussion / Q&A 418 ================ 419 420 * Can the persona be changed while being logged in? 421 422 * Yes, under ``Personalization``, just like the language and date format. 423 424 * Can the user choose a person at login or instance creation? 425 426 * No, we want to avoid too many input fields / choices. 427 428 * Is the chosen persona persistent? 429 430 * Not for now, it's stored per local-storage.