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