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