932927b9df
Move completed plan docs to docs/plans/archive/. Add survey migration 046 and reference HTML/plan files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
4.9 KiB
Feedback Form — Design Document
Date: 2026-02-18 Revised: 2026-02-18 — added DB persistence, feedback type helper text, confirmation email, future TODO notes
Overview
A feedback form page where logged-in users can submit bug reports, feature requests, and general feedback. Submissions are persisted to a feedback database table and emailed to a configurable address via the existing Resend infrastructure. A confirmation email is sent back to the submitter.
Feedback Types
| Type | Helper Text |
|---|---|
| Bug Report | Something is broken or not working as expected |
| Feature Request | An idea for something new you'd like to see |
| Usability Issue | Something works but is confusing or hard to use |
| Documentation | Feedback on help docs, tooltips, or in-app guidance |
| General Feedback | Anything else — thoughts, impressions, suggestions |
Email Format
Admin Notification Email
Subject:
[ResolutionFlow Feedback] Bug Report — 2026-02-18 — ACC-7X3K
Where ACC-7X3K is the user's account display code.
Body:
Feedback Type: Bug Report
Submitted By: engineer@example.com
Account: Contoso IT Services (ACC-7X3K)
Date: February 18, 2026
---
User's written feedback text goes here...
Reply-to is set to the submitter's email for direct replies.
Confirmation Email (to submitter)
Subject: Thanks for your feedback — ResolutionFlow
Body: Brief thank you, echoes back the feedback type and a preview of their message (first ~100 chars). Dark-themed HTML matching existing email templates.
Fire-and-forget: if this email fails, it's logged but doesn't affect the user's submission response.
Database
feedback table
| Column | Type | Notes |
|---|---|---|
id |
UUID | PK |
account_id |
UUID | FK to accounts, nullable, SET NULL on delete |
user_id |
UUID | FK to users, SET NULL on delete |
email |
String(255) | The reply-to email submitted |
feedback_type |
String(50) | Enum value |
message |
Text | Full feedback text |
created_at |
DateTime(tz) | Timestamp |
Indexes on account_id, user_id, created_at.
No admin view or API read endpoints — queryable directly in the DB when needed.
Important: DB write happens before email sending. Email failure does NOT prevent the feedback from being saved.
Frontend
Page
FeedbackPage.tsx — form page inside the app shell.
Access Points
- Sidebar nav item (icon + "Feedback" label) — visible to all roles
- Link card on
AccountSettingsPage
Route
/feedback — top-level app shell route (not nested under /account).
Form Fields
| Field | Details |
|---|---|
| Auto-filled from logged-in user, editable | |
| Feedback Type | Custom dropdown with description text per option |
| Message | Textarea, required, min 10 chars |
| Submit | bg-gradient-brand, disabled while submitting |
UX Flow
- Form loads with email pre-filled
- User opens feedback type dropdown — sees label + helper description for each option
- User selects type, writes message, submits
- Button shows loading state during submission
- On success: success message with confirmation email note, form resets
- On error: inline error, form stays populated for retry
Styling
Standard page layout — container mx-auto, bg-card border border-border rounded-xl form card, max-w-2xl width.
API Client
feedbackApi.submit() in a new api/feedback.ts module.
Backend
Endpoint
POST /feedback in endpoints/feedback.py
Schema
FeedbackSubmission in schemas/feedback.py:
email: EmailStr— validated as emailfeedback_type: FeedbackType— enum-validated against the 5 typesmessage: str— min 10 chars, max 5000 chars
Auth
Requires get_current_active_user. Account display code pulled from user's account relationship server-side.
Config
FEEDBACK_EMAIL: Optional[str] = None in config.py. Endpoint returns 503 if not configured.
Email Service
Two new static methods on EmailService:
send_feedback_email()— admin notification with reply-tosend_feedback_confirmation_email()— thank-you to submitter (fire-and-forget)
Both use existing Resend client and dark-themed HTML matching existing email templates.
Rate Limiting
One submission per minute per user.
Future Consideration
Post-session contextual feedback prompt — do NOT build now. TODO comments in FeedbackPage.tsx and endpoints/feedback.py serve as breadcrumbs. Concept: after completing a troubleshooting session, show a subtle inline prompt that opens a lightweight version of the feedback form pre-tagged with tree/session context. The feedback infrastructure (DB table, email service, API endpoint) built here should be directly reusable.
Not Included (YAGNI)
- No admin view for feedback
- No file attachments
- No public (unauthenticated) access