079-reports.rst (4003B)
1 DD 79: Reports 2 ############## 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Christian Grothoff 8 :First published: 2025-12-22 9 :Last substantive change: 2025-12-26 10 :Implementation evidence: ``merchant`` (2025-12-26; 2025-12-28; 2026-01-07) 11 :Normative references: ``core/merchant/post-private-reports.rst``, ``core/merchant/get-config.rst``, and ``manpages/taler-merchant.conf.5.rst`` 12 13 Summary 14 ======= 15 16 Provide a way for merchants to be periodically sent 17 reports about payments without requiring them to open 18 the merchant backend in a browser. 19 20 Motivation 21 ========== 22 23 * We had merchants say that receiving e-mails with 24 transaction statistics is a "MUST" requirement for them 25 (see #10803). 26 * We had banks say that sending merchants reports on 27 transaction amounts and especially transaction fees is 28 a legal requirement for them to be able to say that the 29 merchant accepted the fees (see #9361). 30 31 Requirements 32 ============ 33 34 * Frequencies differ, daily, weekly, monthly, quarterly, yearly 35 are all frequencies we have already been told as desirable. 36 * In some cases, an offset is desired, like every day at 3am 37 to ensure business concluded around midnight is included in the 38 "daily" report received in the morning. 39 * The reports should include statistics grouped by "category". 40 We are right now interpreting "category" as "tax classes", and 41 thus should report the statistics with the sale amounts in 42 each tax category and the respective amount of taxes due in 43 each category, and the payment fees that were charged --- 44 and the total number of transactions made. 45 * We want this to be reasonably generic, so probably best to 46 immediately plan for E-mail, SMS and other transmission mechanisms. 47 So we should use a helper-program for the actual transmission. 48 * The target e-mail may not be the public e-mail address associated 49 with the instance. 50 * Multiple alerts at different frequencies and different content 51 may apply to the same instance. 52 53 54 Proposed Solution 55 ================= 56 57 * Do a "GET" request to some endpoint of the 58 instance to generate the PDF/CSV/TEXT/HTML and then pass that 59 on to the helper program instead of re-implementing the main 60 reporting logic. This way, the configuration would just 61 pick the endpoint (and content-type), which is quite flexible. 62 * Add new "reports" or "alerts" table with 63 (0) serial, (1) instance, (2) name, (3) frequency, 64 (4) time offset, (5) address type, (6) address, 65 (7) mime-type of the data to send, (7) URL 66 path (below /instance/$ID) to request the data from, 67 (8) next-transmission timestamp, (9) last error (EC), 68 (10) last error detail (text). 69 * Define helper programs in the configuration for each supported 70 address type that deal with the transmission of the report. 71 * Expose supported report address types in /config. 72 * Add CRUD API to manipulate report list. 73 * Implement helper program that scans the reports table, 74 requests the data and invokes the helper program for 75 transmission and possibly stores/clears errors. 76 77 Test Plan 78 ========= 79 80 * Shell-script based tests for the new CRUD API. 81 * Shell-script based tests for reports using 82 a "cat"-based helper that writes to a local file. 83 * Manual tests for SPA. 84 * Manual tests for PDF/CSV/etc. generation. 85 86 87 Definition of Done 88 ================== 89 90 * [x] Specification updated 91 * [x] Database updated 92 * [x] Merchant backend updated: 93 94 * CRUD API for report definitions 95 * INI-based configuration for reporting helper programs 96 * New background process for creating reports 97 * New endpoints for generating reports (#9361) 98 99 * [x] Merchant backend SPA updated with CRUD for report definitions 100 * [ ] Statistics page with links to GET pages that generate PDF/CSV reports 101 (#10487) verified and manually tested 102 103 104 Alternatives 105 ============ 106 107 None. 108 109 Drawbacks 110 ========= 111 112 Discussion / Q&A 113 ================ 114 115 (This should be filled in with results from discussions on mailing lists / personal communication.)