| @@ -10,18 +10,13 @@ | ||
| 10 | 10 | |
| 11 | 11 | defined('ABSPATH') || exit; |
| 12 | 12 | |
| 13 | 13 | /** |
| 14 | - * One aggregation tool where the 34-tool draft had four. | |
| 14 | + * One aggregation tool: "group by X, measure Y" covers stats, trends, top | |
| 15 | + * events and host utilization with a single schema. | |
| 15 | 16 | * |
| 16 | - * `get-booking-stats`, `get-booking-trend`, `get-top-events` and | |
| 17 | - * `get-host-utilization` are all the same query with a different GROUP BY, and | |
| 18 | - * shipping them separately would have cost four schemas of resident context to | |
| 19 | - * express one idea. A model that understands "group by X, measure Y" can | |
| 20 | - * produce all four and the ones nobody thought to name. | |
| 21 | - * | |
| 22 | - * The response is aggregates only. It never returns booking rows — an agent | |
| 23 | - * that wants rows has list-bookings, which is paginated and masks PII. | |
| 17 | + * Returns aggregates only, never booking rows. Rows come from list-bookings, | |
| 18 | + * which paginates and masks PII. | |
| 24 | 19 | */ |
| 25 | 20 | class ReportTools |
| 26 | 21 | { |
| 27 | 22 | public static function definitions() |
| @@ -146,10 +141,9 @@ | ||
| 146 | 141 | $result['limit'] |
| 147 | 142 | ); |
| 148 | 143 | } |
| 149 | 144 | |
| 150 | - // Time buckets were shifted by a fixed offset, so say which one. An | |
| 151 | - // agent reporting "most bookings at 9am" needs to know whose 9am. | |
| 145 | + // Time buckets are shifted by a fixed offset, so report which one. | |
| 152 | 146 | if (self::hasTimeDimension($result['group_by'])) { |
| 153 | 147 | $offset = BookingReportService::offsetSeconds($timezone, $result['range']['from']); |
| 154 | 148 | $meta['bucket_offset'] = sprintf('%s%02d:%02d', $offset < 0 ? '-' : '+', abs($offset) / 3600, (abs($offset) % 3600) / 60); |
| 155 | 149 | $meta['bucket_note'] = __('Day, weekday and hour buckets use one fixed offset for the whole range. A range crossing a daylight-saving change can place bookings on the far side an hour out.', 'fluent-booking'); |
| @@ -165,20 +159,12 @@ | ||
| 165 | 159 | ); |
| 166 | 160 | } |
| 167 | 161 | |
| 168 | 162 | /** |
| 169 | - * Ids are not answers. A report grouped by host or event type resolves them | |
| 170 | - * to names here, in one query per dimension, so the agent does not have to | |
| 171 | - * spend a round-trip per row working out what "event 7" is. | |
| 163 | + * Human names for the grouped dimensions, for table headers. | |
| 172 | 164 | * |
| 173 | 165 | * @return array |
| 174 | 166 | */ |
| 175 | - /** | |
| 176 | - * Human names for the dimensions grouped on, so an agent rendering a table | |
| 177 | - * does not have to invent a header for `event_type`. | |
| 178 | - * | |
| 179 | - * @return array | |
| 180 | - */ | |
| 181 | 167 | private static function dimensionLabels($groupBy) |
| 182 | 168 | { |
| 183 | 169 | $dimensions = BookingReportService::dimensions(); |
| 184 | 170 | $labels = []; |
| @@ -191,8 +177,13 @@ | ||
| 191 | 177 | |
| 192 | 178 | return $labels; |
| 193 | 179 | } |
| 194 | 180 | |
| 181 | + /** | |
| 182 | + * Resolve host and event ids to names, one query per dimension. | |
| 183 | + * | |
| 184 | + * @return array | |
| 185 | + */ | |
| 195 | 186 | private static function labelRows($rows, $groupBy) |
| 196 | 187 | { |
| 197 | 188 | if (!$rows) { |
| 198 | 189 | return $rows; |
| @@ -252,12 +243,10 @@ | ||
| 252 | 243 | return $rows; |
| 253 | 244 | } |
| 254 | 245 | |
| 255 | 246 | /** |
| 256 | - * Column totals, so an agent does not have to sum the rows itself and get | |
| 257 | - * it wrong. Rates are omitted: averaging per-group rates is not the rate | |
| 258 | - * over the whole set, and computing the real one would need the numerators | |
| 259 | - * this response does not carry. | |
| 247 | + * Column totals. Rates are omitted: averaging per-group rates isn't the | |
| 248 | + * overall rate, and the numerators aren't in the response. | |
| 260 | 249 | * |
| 261 | 250 | * @return array |
| 262 | 251 | */ |
| 263 | 252 | private static function totals($rows, $metrics) |
| @@ -269,10 +258,9 @@ | ||
| 269 | 258 | $totals[$metric] = array_sum(array_column($rows, $metric)); |
| 270 | 259 | } |
| 271 | 260 | } |
| 272 | 261 | |
| 273 | - // distinct_attendees cannot be summed across groups without | |
| 274 | - // double-counting anyone who appears in two of them. | |
| 262 | + // distinct_attendees can't be summed without double-counting. | |
| 275 | 263 | if (isset($totals['distinct_attendees'])) { |
| 276 | 264 | $totals['distinct_attendees_note'] = __('Summed across groups, so an attendee in two groups is counted twice.', 'fluent-booking'); |
| 277 | 265 | } |
| 278 | 266 | |
