Admin System

Admin System

Admin photo review: approve, edit tags, delete. Quality gate between user submissions and public data.

Key Files

Backend — Photo Review (Phase 1–2)

• app/Http/Controllers/AdminController.php — 4 methods: verify, destroy, updateDelete, getCountriesWithPhotos
• app/Http/Controllers/Admin/AdminQueueController.php — Paginated queue endpoint with filters + tag transform (GET /api/admin/photos)
• app/Http/Controllers/Admin/AdminResetTagsController.php — Reset tags on a photo: reverse metrics, delete PhotoTags, reset state to unverified
• app/Http/Middleware/IsAdmin.php — checks hasRole('admin') or hasRole('superadmin') on web guard
• app/Events/TagsVerifiedByAdmin.php — event with full constructor (photo_id, user_id, country_id, state_id, city_id, team_id)
• app/Actions/Tags/AddTagsToPhotoAction.php — v5 tag pipeline (creates PhotoTags, summary, XP)
• app/Services/Metrics/MetricsService.php — deletePhoto() for metric reversal before soft delete
• app/Helpers/helpers.php — rewardXpToAdmin(), logAdminAction()

Backend — User Management, Stats, Username Moderation (Phase 3)

• app/Http/Controllers/Admin/AdminStatsController.php — Dashboard stats (cached 60s): queue totals, by-verification, by-country, user counts, flagged usernames
• app/Http/Controllers/Admin/AdminUsersController.php — 4 methods: index (list/search/filter), trust (toggle), approveAll (bulk), updateUsername (moderation)
• app/Http/Requests/Admin/UpdateUsernameRequest.php — Validation: 3–30 chars, alphanumeric + hyphens, unique. Superadmin auth gate.
• app/Mail/SchoolManagerInvite.php — Queued email sent when school_manager role is granted via toggleSchoolManager()

Frontend

• resources/js/stores/admin.js — Pinia store: fetchPhotos, fetchCountries, approvePhoto, deletePhoto, updateTagsAndApprove, fetchUsers, fetchStats, toggleTrust, approveAllForUser, updateUsername
• resources/js/views/Admin/AdminQueue.vue — Photo review page (three-panel: filters | photo | tags)
• resources/js/views/Admin/AdminUsers.vue — User management page (stats cards, search, filters, table)
• resources/js/views/Admin/components/AdminQueueHeader.vue — Header bar with pending count, navigation, action buttons
• resources/js/views/Admin/components/AdminQueueFilters.vue — Filter sidebar (country, photo ID, user ID, date range)
• resources/js/views/Admin/components/UserRow.vue — Table row: trust toggle, approve all, username editor (superadmin gated)

Tests (49 tests total)

• tests/Feature/Admin/AdminVerificationTest.php — 8 tests (approve, delete, edit+approve, retag, idempotency, auth, school exclusion)
• tests/Feature/Admin/AdminQueueTest.php — 12 tests (queue endpoint: filters, pagination, exclusions, auth)
• tests/Feature/Admin/AdminResetTagsTest.php — 4 tests (reset clears state, metrics reversal, skip approved, non-admin rejected)
• tests/Feature/Admin/AdminStatsTest.php — 5 tests (cache, counts, by-verification, by-country, auth)
• tests/Feature/Admin/AdminUsersTest.php — 9 tests (list, search, sort, trust filter, flagged filter, pagination, auth, school manager invite email on grant, no email on revoke)
• tests/Feature/Admin/AdminTrustTest.php — 10 tests (trust toggle, approve-all, superadmin-only, school exclusion, idempotency)
• tests/Feature/Admin/AdminUsernameModerationTest.php — 13 tests (username edit, flagging lifecycle, validation rules, auth)
• readme/Admin.md — full spec (Phase 1–3 complete)

Invariants

1. Approve requires non-null summary. If photo.summary is null → 422. No tags = nothing to approve.
2. Approve is atomic and idempotent. WHERE is_public = true AND verified < ADMIN_APPROVED. Second approve matches 0 rows, no event fires, no XP awarded.
3. School photos excluded. is_public = false photos never enter admin queue. The WHERE is_public = true condition enforces this.
4. MetricsService before soft delete. deletePhoto() runs BEFORE $photo->delete(). If it throws, delete is aborted.
5. Soft delete only. $photo->delete() uses SoftDeletes trait. No hard deletes.
6. Full event constructor. TagsVerifiedByAdmin needs all 6 args: photo_id, user_id, country_id, state_id, city_id, team_id.
7. No S3 deletion on approve. Photos remain viewable after approval. S3 cleanup is deferred (Phase 2).
8. Admin XP is conditional. rewardXpToAdmin() only called when an action actually changed state (row updated).
9. Tag edits use DB::transaction. Delete existing PhotoTags + AddTagsToPhotoAction::run() + approve, all atomic.
10. Admin middleware uses web guard. Auth::user() (default = web). Tests use actingAs($user) with no guard arg.

Patterns

Approve flow

// Precondition
if ($photo->summary === null) return 422;

// Atomic update
$affected = Photo::where('id', $photo->id)
    ->where('is_public', true)
    ->where('verified', '<', VerificationStatus::ADMIN_APPROVED->value)
    ->update(['verified' => VerificationStatus::ADMIN_APPROVED->value]);

// Only if row was updated
if ($affected > 0) {
    event(new TagsVerifiedByAdmin($photo->id, $photo->user_id, ...));
    rewardXpToAdmin();
}

Delete flow

if ($photo->processed_at !== null) {
    $this->metricsService->deletePhoto($photo); // Reverses metrics
}
// Littercoin detachment...
$photo->delete(); // Soft delete
rewardXpToAdmin();

Edit + approve flow

DB::transaction(function () use ($request, $photo) {
    PhotoTag::where('photo_id', $photo->id)->delete();
    $this->addTagsAction->run($photo->user_id, $photo->id, $request->tags);
});
$photo->refresh();
// Then same atomic approve as verify()

Countries queue query (v5)

Photo::query()
    ->where('verified', '<', VerificationStatus::ADMIN_APPROVED->value)
    ->where('is_public', true)
    ->whereNotNull('summary')
    ->groupBy('country_id');

Queue endpoint pattern

// GET /api/admin/photos — AdminQueueController
Photo::query()
    ->where('is_public', true)
    ->where('verified', '<', VerificationStatus::ADMIN_APPROVED->value)
    ->whereNotNull('summary')
    ->with(['user:id,name', 'countryRelation:id,country,shortcode',
            'photoTags.category', 'photoTags.object',
            'photoTags.primaryCustomTag', 'photoTags.extraTags.extraTag'])
    ->when($request->country_id, fn ($q) => $q->where('country_id', $request->country_id))
    ->when($request->user_id, fn ($q) => $q->where('user_id', $request->user_id))
    ->when($request->photo_id, fn ($q) => $q->where('id', $request->photo_id))
    ->when($request->date_from, fn ($q) => $q->where('created_at', '>=', $request->date_from))
    ->when($request->date_to, fn ($q) => $q->where('created_at', '<=', $request->date_to))
    ->orderBy('created_at', 'asc')
    ->paginate($perPage);
// Response manually built (avoids Location accessor crash on null updated_at)
// Includes new_tags[] with hydrated PhotoTag data for frontend tag editing

Stats endpoint pattern

// GET /api/admin/stats — AdminStatsController (cached 60s)
Cache::remember('admin:dashboard:stats', 60, function () {
    // queue_total: is_public=true, verified=VERIFIED, summary NOT NULL
    // queue_today: same + created_at >= today
    // by_verification: grouped by VerificationStatus enum labels
    // by_country: top 20 countries with pending photos
    // total_users, users_today, flagged_usernames
});

User list endpoint pattern

// GET /api/admin/users — AdminUsersController@index
User::query()
    ->withCount('photos')
    ->with('roles:id,name')
    ->when($search, fn ($q) => $q->where(function ($q) use ($search) {
        $q->where('name', 'LIKE', "%{$search}%")
          ->orWhere('username', 'LIKE', "%{$search}%")
          ->orWhere('email', 'LIKE', "%{$search}%");
    }))
    ->when($trustFilter === 'trusted', fn ($q) => $q->where('verification_required', false))
    ->when($trustFilter === 'untrusted', fn ($q) => $q->where('verification_required', true))
    ->when($flagged, fn ($q) => $q->where('username_flagged', true))
    ->orderBy($sortBy, $sortDir)
    ->paginate($perPage);
// Response includes pending_photos count per user (is_public=true, verified < ADMIN_APPROVED)

Trust toggle pattern

// POST /api/admin/users/{user}/trust — superadmin only
// Sets verification_required = !trusted
// Does NOT retroactively approve existing photos
// No logAdminAction() — schema needs target_type for user-target actions

Approve-all pattern

// POST /api/admin/users/{user}/approve-all — superadmin only, max 500
// Same atomic WHERE as verify(): is_public=true AND verified < ADMIN_APPROVED
// Fires TagsVerifiedByAdmin per photo + rewardXpToAdmin()

Username moderation pattern

// PATCH /api/admin/users/{user}/username — superadmin only
// UpdateUsernameRequest: 3-30 chars, alphanumeric + hyphens, unique
// Clears username_flagged after edit
// username_flagged set to true when user self-changes username (in ApiSettingsController)

Routes

All under /api/admin/ prefix with admin middleware:

Photo review (admin + superadmin)

Dashboard stats (admin + superadmin)

User management

Deprecated routes (return 410 Gone)

Frontend routes

Roles (Spatie, web guard)