<!-- @coderabbitai ignore --> ## Summary - **Admin feedback page** at `/admin/feedback` — browse all user feedback submissions with star ratings, text fields, search, pagination, and aggregate stats - **Email notification** to admin@nomadkaraoke.com whenever a user submits new feedback (configurable via `ADMIN_NOTIFICATION_EMAIL` env var) - **Admin API endpoint** `GET /api/admin/feedback` with pagination, search, test-data filtering, and average ratings ## Context User feedback was stored in Firestore (`user_feedback` collection) but completely invisible to the admin — the admin panel only showed a boolean "Feedback Submitted: Yes/No" badge per user. This PR closes that gap. ## Changes **Backend:** - `GET /api/admin/feedback` endpoint with pagination, search, `exclude_test` filter, aggregate rating averages - `send_feedback_notification()` method on `EmailService` — sends HTML email with star ratings, all text fields, link to admin page - Wired into `submit_user_feedback` as fire-and-forget (won't block user response) **Frontend:** - New admin page with aggregate stat cards, searchable/paginated table, visual star ratings, expandable rows for text detail - "Feedback" sidebar nav item with MessageSquare icon - `adminApi.listFeedback()` client method + TypeScript types **Tests:** 14 tests covering endpoint (pagination, search, filtering, aggregates, empty state, datetime edge cases), email (content, subject, custom admin, failure), and caller-callee contract integration ## Test plan - [x] `make test` — 712 tests pass (39 suites) - [x] 14 new tests in `test_admin_feedback.py` - [ ] Manual: verify admin page renders at `/admin/feedback` after deploy - [ ] Manual: submit feedback → verify email arrives at admin@nomadkaraoke.com 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5.5 KiB
Plan: Admin Feedback Visibility
Created: 2026-03-23 Branch: feat/sess-20260323-1454-feedback-email-debug Status: Draft
Overview
User feedback submissions are stored in Firestore (user_feedback collection) but are completely invisible to the admin. The admin panel only shows a boolean "Feedback Submitted: Yes/No" badge per user. This plan adds:
- Admin UI page to browse and review all submitted feedback
- Email notification to admin@nomadkaraoke.com on each new submission
Requirements
- Admin page at
/admin/feedbacklisting all feedback with ratings, text, timestamps, and user info - Sortable by date (newest first by default) and filterable by search (email)
- Star ratings rendered visually (not just numbers)
- Email sent to admin@nomadkaraoke.com immediately when feedback is submitted
- Email includes all feedback content (ratings, text fields, user email)
- Test data filtering works (exclude_test toggle)
- Sidebar navigation includes new "Feedback" item
Technical Approach
Admin API Endpoint
Add GET /api/admin/feedback to backend/api/routes/admin.py. Follows the standard admin endpoint pattern: require_admin dependency, pagination with limit/offset/search/exclude_test, returns Pydantic response model. Queries user_feedback Firestore collection.
Admin UI Page
New page at frontend/app/admin/feedback/page.tsx. Follows existing admin page patterns (Card, Table, Badge, pagination, search input, loading states). Uses adminApi.listFeedback() to fetch data.
Email Notification
Add a new method to EmailService (or call send_email directly) from the submit_user_feedback endpoint in users.py. Uses the existing SendGrid infrastructure — no new template service templates needed since this is an internal admin notification (simple HTML table with the feedback data).
Implementation Steps
Step 1: Backend — Admin feedback list endpoint
- Add
AdminFeedbackItemandAdminFeedbackListResponsePydantic models toadmin.py - Add
GET /api/admin/feedbackendpoint with:- Pagination:
limit=50,offset=0 - Search by user email
exclude_testfilter (reuseis_test_email)- Sort by
created_atdescending - Return: items, total, offset, limit, has_more
- Pagination:
- Add aggregate stats in response: average ratings, total count
Step 2: Backend — Email notification on submission
- Add
send_feedback_notificationmethod toEmailServicethat sends an HTML email toadmin@nomadkaraoke.comcontaining:- User email
- All 4 star ratings
- All text fields
- Would recommend / would use again
- Submitted timestamp
- Link to admin feedback page
- Call
send_feedback_notificationfromsubmit_user_feedbackinusers.py(fire-and-forget, don't block the user response on email success)
Step 3: Frontend — Admin API client
- Add
listFeedbackmethod toadminApiinfrontend/lib/api.ts - Add TypeScript types for
AdminFeedbackItemandAdminFeedbackListResponse
Step 4: Frontend — Admin feedback page
- Create
frontend/app/admin/feedback/page.tsxwith:- Table: user email, date, overall rating (stars), ease of use, lyrics accuracy, correction experience, would recommend, would use again
- Expandable rows or click-to-detail for text fields (what went well, what could improve, additional comments)
- Search by email
- Pagination (50 per page)
- Refresh button
- Test data toggle (via
useAdminSettings)
- Add "Feedback" item to admin sidebar in
frontend/components/admin/admin-sidebar.tsxwithMessageSquareicon
Step 5: Testing
- Backend unit test for
GET /api/admin/feedbackendpoint (pagination, search, exclude_test) - Backend unit test for
send_feedback_notificationemail method - Frontend component test for feedback page (render, empty state)
Files to Create/Modify
| File | Action | Description |
|---|---|---|
backend/api/routes/admin.py |
Modify | Add feedback list endpoint + response models |
backend/api/routes/users.py |
Modify | Add email notification call in submit_user_feedback |
backend/services/email_service.py |
Modify | Add send_feedback_notification method |
frontend/lib/api.ts |
Modify | Add adminApi.listFeedback() method + types |
frontend/app/admin/feedback/page.tsx |
Create | Admin feedback review page |
frontend/components/admin/admin-sidebar.tsx |
Modify | Add "Feedback" nav item |
backend/tests/test_admin_feedback.py |
Create | Tests for admin feedback endpoint |
backend/tests/test_feedback_email.py |
Create | Tests for feedback email notification |
Testing Strategy
- Unit tests: Admin endpoint (pagination, filtering, sorting), email method (content formatting, send call)
- Integration: Submit feedback → verify email service called
- Manual verification: Check email arrives in admin@nomadkaraoke.com inbox after submission
Open Questions
- Should the admin page show feedback from the old
beta_feedbackcollection too, or justuser_feedback? (Recommendation: justuser_feedback— the beta collection is legacy) - Should there be any spam/quality detection flagging? (Some submissions appear to game the system for credits)
Rollback Plan
- Backend: Remove endpoint from admin.py, revert email call in users.py
- Frontend: Delete feedback page, remove sidebar item
- No data migration needed — Firestore collection unchanged