Merge pull request #9 from ConductionNL/wip/build-tile-analytics-2026-07-23

feat(tile-usage-analytics): per-tile click analytics + archive

Author: rubenvdlinde

appinfo/routes.php

@@ -86,6 +86,21 @@
 		// dashboard does not exist.
 		['name' => 'dashboardApi#viewEvent', 'url' => '/api/dashboards/{uuid}/view-event', 'verb' => 'POST',
 		 'requirements' => ['uuid' => '[A-Za-z0-9\-]+']],
+
+		// REQ-TANLT-002: record a tile click. Authed users only; the
+		// controller short-circuits silently when the user has opted out
+		// or analytics is globally disabled (same reused REQ-ANLT-003/004/005
+		// gates as the dashboard view-event route above). Returns HTTP 204
+		// on success, 404 when the placement does not exist. `placementId`
+		// is constrained to digits so the router never confuses it with a
+		// literal segment.
+		['name' => 'tileAnalytics#recordClick', 'url' => '/api/tile-click/{placementId}', 'verb' => 'POST',
+		 'requirements' => ['placementId' => '\d+']],
+		// REQ-TANLT-003: lets the frontend hook know whether tracking is
+		// currently active for the calling user, so it can suppress the
+		// record call without re-implementing the gate logic client-side.
+		['name' => 'tileAnalytics#config', 'url' => '/api/tile-analytics/config', 'verb' => 'GET'],
+
 		// REQ-DASH-026: nested dashboard tree.
 		['name' => 'dashboardApi#tree', 'url' => '/api/dashboards/tree', 'verb' => 'GET'],
 		// REQ-DASH-027: slug-chain path resolution. The {path} placeholder
@@ -458,6 +473,18 @@
 		['name' => 'analytics#dashboardDetail', 'url' => '/api/admin/analytics/dashboards/{uuid}', 'verb' => 'GET',
 		 'requirements' => ['uuid' => '[A-Za-z0-9\-]+']],
 
+		// Tile usage-analytics admin endpoints (REQ-TANLT-004..005) — a
+		// strict downward extension of the dashboard view-analytics admin
+		// endpoints above. All admin-only via ADR-023 action authorization
+		// inside the controller. The literal `top` and `export` segments
+		// and the `by-dashboard` prefix precede any wildcard so the router
+		// never confuses them.
+		['name' => 'tileAnalytics#topTiles', 'url' => '/api/admin/analytics/tiles/top', 'verb' => 'GET'],
+		['name' => 'tileAnalytics#exportCsv', 'url' => '/api/admin/analytics/tiles/export', 'verb' => 'GET'],
+		['name' => 'tileAnalytics#dashboardBreakdown',
+		 'url' => '/api/admin/analytics/tiles/by-dashboard/{uuid}', 'verb' => 'GET',
+		 'requirements' => ['uuid' => '[A-Za-z0-9\-]+']],
+
 		// Background feed-refresh trigger (REQ-FRJ-010). Admin-only via
 		// runtime `IGroupManager::isAdmin` check inside the controller.
 		['name' => 'admin#refreshFeedsNow', 'url' => '/api/admin/feeds/refresh-now', 'verb' => 'POST'],

docs/features/tiles.md

@@ -20,6 +20,42 @@ Custom tiles are user-created shortcut cards that provide quick access to Nextcl
 | DELETE | `/api/tiles/{id}` | Delete tile |
 | POST | `/api/dashboard/{id}/tile` | Place tile on dashboard |
 
+## Usage analytics
+
+Tile usage analytics is a strict, downward **extension** of the
+[dashboard view-analytics](../../openspec/specs/dashboard-view-analytics/spec.md)
+capability at the tile/widget-placement grain — it does not introduce
+any new privacy machinery, only a finer-grained aggregate table.
+
+- Aggregate-only counts stored in `oc_launchpad_tile_clicks`, one row
+  per `(placementUuid, clickBucket)` per UTC day. No per-event rows
+  are ever persisted.
+- Unique-actor dedup reuses the SAME salted-daily-hash mechanism
+  (`sha256(userId || dailySalt)`, cached in `ICache` only) and the
+  SAME `SaltRotationJob` as dashboard views — no second salt or
+  rotation job.
+- Reuses the SAME `launchpad.analytics_enabled` (global) and
+  `launchpad.analytics_optout` (per-user) settings. There is no
+  separate tile-analytics opt-out.
+- The existing analytics retention-purge job is extended to also
+  purge `oc_launchpad_tile_clicks` rows older than
+  `launchpad.analytics_retention_days` in the same run — no second
+  purge job.
+- The frontend fires a fire-and-forget `POST /api/tile-click/{id}` on
+  tile activation (click or keyboard Enter), gated by
+  `GET /api/tile-analytics/config` so tracking is suppressed
+  client-side when analytics is disabled or the user opted out.
+
+### API Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| POST | `/api/tile-click/{placementId}` | Any authed user | Record a click (always 204; no-op when disabled/opted out) |
+| GET | `/api/tile-analytics/config` | Any authed user | Whether tracking is active for the caller |
+| GET | `/api/admin/analytics/tiles/top` | Admin | Top-N tiles by click count for a period |
+| GET | `/api/admin/analytics/tiles/by-dashboard/{uuid}` | Admin | Per-dashboard tile breakdown |
+| GET | `/api/admin/analytics/tiles/export` | Admin | CSV export |
+
 ## Screenshot
 
 ![Dashboard with Tiles](/screenshots/launchpad-dashboard-overview.png)

lib/BackgroundJob/PurgeViewsJob.php

@@ -8,6 +8,11 @@
  * window is 365 days; admin override via
  * `launchpad.analytics_retention_days` is clamped to `[30, 3650]`.
  *
+ * Extended by the tile usage-analytics capability (REQ-TANLT-005) to
+ * also purge `oc_launchpad_tile_clicks` rows older than the SAME
+ * cutoff in the same run — no second purge job is introduced, per the
+ * "reuse, don't reinvent" contract for that capability.
+ *
  * Logging is intentionally aggregate-only: row count + cutoff date
  * — never any user-attributable identifiers (REQ-ANLT-009 scenario
  * "Purge logs execution"). The job is registered via
@@ -30,6 +35,7 @@
 namespace OCA\LaunchPad\BackgroundJob;
 
 use OCA\LaunchPad\Db\DashboardViewMapper;
+use OCA\LaunchPad\Db\TileClickMapper;
 use OCA\LaunchPad\Service\AnalyticsService;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\BackgroundJob\TimedJob;
@@ -56,12 +62,18 @@ class PurgeViewsJob extends TimedJob
      *                                              context).
      * @param DashboardViewMapper $viewMapper       Aggregate-row
      *                                              mapper.
+     * @param TileClickMapper     $tileClickMapper  Tile-click
+     *                                              aggregate-row
+     *                                              mapper — reuses
+     *                                              the same cutoff
+     *                                              date (REQ-TANLT-005).
      * @param LoggerInterface     $logger           PSR logger.
      */
     public function __construct(
         ITimeFactory $time,
         private readonly AnalyticsService $analyticsService,
         private readonly DashboardViewMapper $viewMapper,
+        private readonly TileClickMapper $tileClickMapper,
         private readonly LoggerInterface $logger,
     ) {
         parent::__construct(time: $time);
@@ -70,25 +82,31 @@ public function __construct(
 
     /**
      * Run the job — delete every aggregate row strictly older than
-     * the cutoff date.
+     * the cutoff date, in BOTH the dashboard-views table and the
+     * tile-clicks table (REQ-TANLT-005 — same cutoff, same run, no
+     * second job).
      *
      * @param mixed $argument Required by the base class; unused.
      *
      * @return void
      *
      * @spec openspec/specs/dashboard-view-analytics/spec.md
+     * @spec openspec/specs/dashboard-view-analytics/spec.md
      */
     protected function run($argument): void
     {
-        $cutoff  = $this->analyticsService->getPurgeCutoffDate();
-        $deleted = $this->viewMapper->deleteOlderThan(beforeDate: $cutoff);
+        $cutoff        = $this->analyticsService->getPurgeCutoffDate();
+        $deletedViews  = $this->viewMapper->deleteOlderThan(beforeDate: $cutoff);
+        $deletedClicks = $this->tileClickMapper->deleteOlderThan(beforeDate: $cutoff);
 
         $this->logger->info(
-            message: 'launchpad analytics purge: deleted '.$deleted.' rows older than '.$cutoff,
+            message: 'launchpad analytics purge: deleted '.$deletedViews.' view rows and '
+                .$deletedClicks.' tile-click rows older than '.$cutoff,
             context: [
-                'rows'      => $deleted,
-                'cutoff'    => $cutoff,
-                'retention' => $this->analyticsService->getRetentionDays(),
+                'viewRows'   => $deletedViews,
+                'tileRows'   => $deletedClicks,
+                'cutoff'     => $cutoff,
+                'retention'  => $this->analyticsService->getRetentionDays(),
             ]
         );
     }//end run()