OLM v5: Tagging v2, Achievements, Vue3, Tailwind & more

.ai/skills/location-system/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: location-system
+description: Countries, states, cities, ResolveLocationAction, Location base model, LocationType enum, geocoding, and location-level Redis data.
+---
+
+# Location System
+
+Location tables store identity only (name, shortcode, FKs). All aggregates live in the `metrics` table and Redis. The `Location` base model computes all stats from Redis on access via `$appends`.
+
+## Key Files
+
+- `app/Models/Location/Location.php` — Abstract base model with Redis-backed computed attributes
+- `app/Models/Location/Country.php` — Route key: `shortcode` (ISO 3166-1 alpha-2)
+- `app/Models/Location/State.php` — Belongs to Country
+- `app/Models/Location/City.php` — Belongs to Country + State
+- `app/Actions/Locations/ResolveLocationAction.php` — Lat/lon -> Country/State/City via geocoding
+- `app/Actions/Locations/ReverseGeocodeLocationAction.php` — LocationIQ API wrapper
+- `app/Actions/Locations/LocationResult.php` — DTO returned by ResolveLocationAction
+- `app/Enums/LocationType.php` — Global(0), Country(1), State(2), City(3)
+- `app/Enums/Timescale.php` — AllTime(0), Daily(1), Weekly(2), Monthly(3), Yearly(4)
+
+## Invariants
+
+1. **Location tables store identity only.** No `total_*` counters, no `manual_verify`, no aggregates. All stats come from Redis or the `metrics` table.
+2. **Photo table uses FK columns only:** `country_id`, `state_id`, `city_id`. Deprecated string columns (`country`, `county`, `city`, `display_name`, `location`, `road`) are dropped.
+3. **Redis is a derived cache.** All Redis location data is rebuildable from the `metrics` table.
+4. **HyperLogLog for contributor counts.** `PFCOUNT` gives ~0.81% error, O(1) space, append-only (cannot decrement).
+5. **Country uses `shortcode` as route key**, not `id`. Routes: `/countries/{shortcode}`.
+
+## Patterns
+
+### ResolveLocationAction
+
+```php
+// app/Actions/Locations/ResolveLocationAction.php
+public function run(float $lat, float $lon): LocationResult
+{
+    $address = $this->reverseGeocode->run($lat, $lon);
+
+    $country = $this->resolveCountry($address);  // firstOrCreate by country_code
+    $state   = $this->resolveState($country, $address);
+    $city    = $this->resolveCity($country, $state, $address);
+
+    return new LocationResult($country, $state, $city, $address, $displayName);
+}
+```
+
+**Lookup strategy for city:** Searches keys in order: `city`, `town`, `city_district`, `village`, `hamlet`, `locality`, `county`.
+
+### LocationResult DTO
+
+```php
+readonly class LocationResult
+{
+    public function __construct(
+        public Country $country,
+        public State   $state,
+        public City    $city,
+        public array   $addressArray,
+        public string  $displayName,
+    ) {}
+}
+```
+
+### LocationType enum
+
+```php
+enum LocationType: int
+{
+    case Global  = 0;   // dbColumn: null,       scopePrefix: {g}
+    case Country = 1;   // dbColumn: country_id, scopePrefix: {c:$id}
+    case State   = 2;   // dbColumn: state_id,   scopePrefix: {s:$id}
+    case City    = 3;   // dbColumn: city_id,     scopePrefix: {ci:$id}
+
+    public function dbColumn(): ?string
+    public function scopePrefix(int $id = 0): string
+    public function modelClass(): ?string
+    public function parentType(): ?self
+}
+```
+
+### Location model computed attributes (from Redis)
+
+```php
+// All appended attributes on Country/State/City models:
+$country->total_litter_redis      // HGET {c:$id}:stats litter
+$country->total_photos_redis      // HGET {c:$id}:stats uploads
+$country->total_contributors_redis // PFCOUNT {c:$id}:hll
+$country->total_xp               // HGET {c:$id}:stats xp
+$country->litter_data             // HGETALL {c:$id}:cat  (resolved to names)
+$country->objects_data            // top 20 from {c:$id}:obj
+$country->materials_data          // HGETALL {c:$id}:mat
+$country->brands_data             // HGETALL {c:$id}:brands
+$country->ppm                     // Cached time-series from metrics table (15min TTL)
+$country->recent_activity         // Last 7 days daily counts (5min TTL)
+```
+
+### Location hierarchy rankings
+
+```php
+RedisKeys::globalCountryLitterRanking()           // {g}:rank:c:litter (ZSET)
+RedisKeys::globalCountryPhotosRanking()           // {g}:rank:c:photos
+RedisKeys::countryStateRanking($countryId, $metric)  // {c:$id}:rank:s:$metric
+RedisKeys::stateCityRanking($stateId, $metric)       // {s:$id}:rank:ci:$metric
+```
+
+### Database schema (identity only)
+
+```sql
+countries (id, country, shortcode UNIQUE, created_by, timestamps)
+states    (id, state, country_id, created_by, timestamps, UNIQUE(country_id, state))
+cities    (id, city, country_id, state_id, created_by, timestamps, UNIQUE(country_id, state_id, city))
+```
+
+## LocationController API (v1)
+
+`app/Http/Controllers/Location/LocationController.php` serves the locations browsing UI.
+
+### Endpoints
+- `GET /api/v1/locations` — Global view: list of countries with stats
+- `GET /api/v1/locations/{type}/{id}` — Drill into country/state/city
+
+### Response keys
+```json
+{
+    "stats": { "countries": 120, "states": 450, "cities": 1200, ... },
+    "locations": [ ... ],
+    "location_type": "country",
+    "breadcrumbs": [ ... ],
+    "activity": [ ... ]
+}
+```
+
+**Key naming:** Response uses `locations` (not `children`) and `location_type` (not `children_type`). The Pinia store `useLocationsStore` reads these exact keys.
+
+### Time filtering
+Supports `?period=today|yesterday|this_month|last_month|this_year` and `?year=2024` query params. Mutually exclusive — year clears period and vice versa.
+
+## Common Mistakes
+
+- **Adding aggregate columns to location tables.** Aggregates live in `metrics` table and Redis. Location tables are identity only.
+- **Using deprecated photo string columns.** `country`, `county`, `city`, `display_name`, `location`, `road` are dropped. Use `country_id`, `state_id`, `city_id` FKs.
+- **Routing countries by ID instead of shortcode.** Country model has `getRouteKeyName(): 'shortcode'`.
+- **Treating Redis location stats as authoritative.** They're derived caches. The `metrics` table is source of truth.
+- **Decrementing HyperLogLog.** PFCOUNT is append-only. You cannot remove a contributor from HLL.
+- **Forgetting `GeocodingException`.** `ResolveLocationAction::run()` throws `GeocodingException` when geocoding fails. Always handle this.
+- **Using `children` or `children_type` in API responses.** The correct keys are `locations` and `location_type`.
+- **Filtering locations by `manual_verify`.** This deprecated column is no longer used. Don't scope queries with it.

.ai/skills/metrics-pipeline/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: metrics-pipeline
+description: MetricsService, RedisMetricsCollector, ProcessPhotoMetrics, metrics table, Redis stats, leaderboards, XP processing, and photo processing state (processed_at/fp/tags/xp).
+---
+
+# Metrics Pipeline
+
+MetricsService is the **single writer** for all metrics — MySQL time-series and Redis aggregates. Nothing else touches metric counters. This is the golden rule.
+
+## Key Files
+
+- `app/Services/Metrics/MetricsService.php` — Single writer for MySQL + Redis
+- `app/Services/Redis/RedisMetricsCollector.php` — Redis operations (stats, HLL, rankings, tags)
+- `app/Services/Redis/RedisKeys.php` — All Redis key builders (single source of truth for naming)
+- `app/Listeners/Metrics/ProcessPhotoMetrics.php` — Queued listener on `TagsVerifiedByAdmin`
+- `app/Events/TagsVerifiedByAdmin.php` — Trigger event for metrics processing
+- `app/Enums/LocationType.php` — Global(0), Country(1), State(2), City(3) with scope prefixes
+
+## Invariants
+
+1. **Single writer rule.** Only `MetricsService` writes to the `metrics` table and Redis metric keys. No other code may increment/decrement counters.
+2. **Processing state is four columns:** `processed_at`, `processed_fp`, `processed_tags`, `processed_xp`. A photo with `processed_at = null` has never affected aggregates.
+3. **Fingerprint-based idempotency.** MetricsService diffs old `processed_tags` JSON against new summary and writes only non-zero deltas. Safe to call repeatedly on any photo.
+4. **Summary must exist before metrics fire.** `GeneratePhotoSummaryService::run()` MUST be called before `TagsVerifiedByAdmin` dispatches. MetricsService reads from `photo.summary`.
+5. **Redis is a derived cache.** Rebuildable from the `metrics` table. `RedisKeys::*` is single source of truth for key naming.
+6. **`processed_xp` must be INT UNSIGNED**, not TINYINT. Overflow bug documented in migration `2026_02_23_182605`.
+7. **Tags count excludes categories** to avoid double-counting: `tags_count = objects + materials + brands + custom_tags`.
+
+## Patterns
+
+### How MetricsService processes a photo
+
+```php
+// MetricsService::processPhoto() — called by ProcessPhotoMetrics listener
+DB::transaction(function () use ($photo) {
+    $photo = Photo::whereKey($photo->id)->lockForUpdate()->first();
+    $metrics = $this->extractMetricsFromPhoto($photo);  // reads photo.summary
+    $fingerprint = $this->computeFingerprint($metrics['tags']);
+
+    // Skip if nothing changed (fingerprint + XP both match)
+    if ($photo->processed_fp === $fingerprint &&
+        (int)$photo->processed_xp === (int)$metrics['xp']) {
+        return;
+    }
+
+    // Route to create (first time) or update (re-tag)
+    if ($photo->processed_at !== null) {
+        $this->doUpdate($photo, $metrics, $fingerprint);
+    } else {
+        $this->doCreate($photo, $metrics, $fingerprint);
+    }
+});
+```
+
+### MySQL upsert across timescales and locations
+
+Each photo writes up to **20 rows**: 5 timescales (all-time, daily, weekly, monthly, yearly) x 4 location scopes (global, country, state, city).
+
+```php
+DB::table('metrics')->upsert($rows,
+    ['timescale', 'location_type', 'location_id', 'user_id', 'year', 'month', 'week', 'bucket_date'],
+    [
+        'uploads' => DB::raw('GREATEST(uploads + VALUES(uploads), 0)'),
+        'tags'    => DB::raw('GREATEST(tags + VALUES(tags), 0)'),
+        // ... same for brands, materials, custom_tags, litter, xp
+    ]
+);
+```
+
+Uploads delta: `+1` for create, `0` for update, `-1` for delete. `GREATEST(..., 0)` prevents negative counters.
+
+### Redis operations happen after MySQL commit
+
+```php
+private function updateRedis(Photo $photo, array $payload, string $operation): void
+{
+    DB::afterCommit(function () use ($photo, $payload, $operation) {
+        RedisMetricsCollector::processPhoto($photo, $payload, $operation);
+    });
+}
+```
+
+### Redis key patterns (cluster-safe with hash tags)
+
+```php
+RedisKeys::global()           // {g}
+RedisKeys::country($id)       // {c:$id}
+RedisKeys::state($id)         // {s:$id}
+RedisKeys::city($id)          // {ci:$id}
+RedisKeys::user($userId)      // {u:$userId}
+
+RedisKeys::stats($scope)             // $scope:stats (HASH: uploads, tags, litter, xp, ...)
+RedisKeys::hll($scope)               // $scope:hll (HyperLogLog for contributor count)
+RedisKeys::objects($scope)            // $scope:obj (HASH: object_id => count)
+RedisKeys::ranking($scope, $dim)      // $scope:rank:$dim (ZSET)
+RedisKeys::userBitmap($userId)        // {u:$userId}:bitmap (activity bitmap)
+```
+
+### Where TagsVerifiedByAdmin fires
+
+1. **Trusted users tag a photo (web):** `AddTagsToPhotoAction::updateVerification()` — dispatches immediately after summary + XP.
+2. **Teacher approves school photos:** `TeamPhotosController::approve()` — dispatches per photo after atomic `is_public = true` update.
+3. **Trusted users tag a photo (mobile):** `ConvertV4TagsAction::run()` — dispatches after v4→v5 conversion + summary generation.
+
+### Delete flow (metrics reversal)
+
+```php
+// MetricsService::deletePhoto() — called synchronously in controllers before soft-delete
+// Reads processed_tags JSON, applies negative deltas, clears processed_* columns
+$photo->update([
+    'processed_at' => null,
+    'processed_fp' => null,
+    'processed_tags' => null,
+    'processed_xp' => null,
+]);
+```
+
+## Common Mistakes
+
+- **Writing metrics outside MetricsService.** Never `DB::table('metrics')->increment(...)` or `Redis::hincrby(...)` directly.
+- **Dispatching `TagsVerifiedByAdmin` before summary generation.** MetricsService reads `photo.summary` — null summary = zero metrics.
+- **Comparing `processed_xp` as TINYINT.** Values above 127 overflow. Column must be UNSIGNED INT.
+- **Forgetting row locking.** Always use `Photo::whereKey($id)->lockForUpdate()->first()` inside the transaction.
+- **Assuming Redis is source of truth.** Redis is a cache. The `metrics` table is authoritative.
+- **Including categories in `tags_count`.** Categories are groupings, not countable items. Only objects + materials + brands + custom_tags.