eeac98b17a
Adds DB persistence, feedback type helper text, confirmation email, and future post-session prompt notes. Removes "No DB persistence" from YAGNI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 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 |
|
|
|-------|---------|
|
|
| Email | 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
|
|
|
|
1. Form loads with email pre-filled
|
|
2. User opens feedback type dropdown — sees label + helper description for each option
|
|
3. User selects type, writes message, submits
|
|
4. Button shows loading state during submission
|
|
5. On success: success message with confirmation email note, form resets
|
|
6. 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 email
|
|
- `feedback_type: FeedbackType` — enum-validated against the 5 types
|
|
- `message: 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-to
|
|
- `send_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
|