docs: add product feedback feature plan

This commit is contained in:
2026-04-30 03:30:48 -04:00
parent 2e4c16621d
commit f9960b4fc9
10 changed files with 754 additions and 1 deletions

View File

@@ -1,4 +1,7 @@
# PROMPT TEMPLATES
I need you to help me write a feature. First, we need to define it, so you will ask me questions one-by-one to make sure we have a shared understanding of the scope
and expectating. - The feature we want is a way for your clients to report bugs/suggestions/requests from within our app. It should not be intrusive. It should allow
them to take a screen capture, put annotation, describe their request and/or issue. Then, as a dev, i will want to collect and review them.
## Purpose
This document standardizes how we interact with AI coding agents (Codex, Claude, etc).
@@ -324,4 +327,4 @@ scripts/ai-task review docs/tasks/TASK-XXX.md
---
End of document.
End of document.

View File

@@ -0,0 +1,256 @@
# Feature: Product Feedback
## Status
Draft
## Goal
Allow authenticated users to report bugs, suggestions, and requests from inside the app without interrupting their workflow, and give developers a lightweight place to review, discuss, and resolve that feedback.
This is product-level support data for the SaaS operator. It may capture workspace and page context for debugging, but it is not workspace-owned workflow data.
## User Stories
- As an authenticated user, I want to submit feedback from any app page so that I can report a bug, suggestion, or request when I notice it.
- As an authenticated user, I want to optionally capture and annotate the current app viewport so that I can explain visual issues clearly.
- As an authenticated user, I want a global My Feedback page so that I can track my submitted feedback across all workspaces.
- As a developer, I want a global feedback review page so that I can see all submitted product feedback.
- As a developer, I want to comment, update status/type, and add tags so that feedback can be reviewed without turning the app into a ticketing system.
- As a reporter, I want notifications when a developer comments or changes status so that I know when feedback needs my attention.
- As a developer, I want notifications for new reports and reporter replies so that feedback does not stall silently.
## Frontend Areas
- Global authenticated app shell floating Feedback button
- Feedback submission dialog
- Screenshot capture and annotation editor
- `/app/my-feedback`
- `/app/my-feedback/:id`
- `/app/feedback`
- `/app/feedback/:id`
- Existing notification bell
- `frontend/src/features/feedback/`
## Backend Modules
- Identity
- Notifications
- Feedback
- Infrastructure blob storage
## Access Rules
- Only authenticated users can submit feedback.
- Any authenticated user can submit feedback from any authenticated app page.
- A new `Developer` role can access the global developer feedback review pages and APIs.
- Developers can view every feedback report across the SaaS.
- Reporters can view only feedback they submitted.
- Feedback detail access is limited to the reporter and users with the `Developer` role.
- Feedback screenshot access must be authenticated and must follow the same reporter/developer access rules as the report.
- Feedback does not have public or shared links in v1.
## Submission Rules
- The global Feedback button appears on every authenticated app page.
- Submitting feedback is intentionally user-initiated and non-intrusive.
- Feedback type is required and must be one of:
- `Bug`
- `Suggestion`
- `Request`
- Description is required and plain text.
- Screenshot capture is optional.
- Users explicitly click `Capture screen`; opening feedback does not automatically capture the page.
- Capture is limited to the app viewport.
- If capture fails, the user can still submit text-only feedback.
- If a user closes a dirty feedback dialog, the app warns that unsent feedback will be discarded.
- Draft persistence is out of scope for v1.
- Reporters cannot edit or delete submitted feedback in v1.
- Reporters can add follow-up comments.
## Screenshot And Annotation Rules
- Screenshots are uploaded through the blob storage abstraction, not embedded in feedback database rows.
- Feedback screenshots should use a dedicated storage area or prefix.
- Annotated captures are exported as compressed image files.
- Backend upload size and content type validation must be enforced.
- The UI must show a friendly error when an image is too large or invalid.
- Annotation tools should support:
- crop
- arrows
- circles or ellipses
- lines
- freehand marks
- text labels
- undo
- clear/reset
- Frontend implementation may use established capture and annotation libraries rather than custom screenshot tooling.
- Developers can preview and download/open the annotated screenshot.
- Reporters can preview the annotated screenshot.
- If feedback deletion is added in the future, associated screenshot blobs must be deleted with the report.
- Feedback reports and screenshots are retained indefinitely until a future retention/deletion feature exists.
## Captured Metadata
Each report should capture useful debugging context automatically when available:
- reporter user id
- reporter name and email
- current app URL/path
- active workspace id/name
- active client id/name
- active project id/name
- active content item id/title
- browser user agent
- viewport size
- app version, if available
- created timestamp
## Status Model
Feedback status is deliberately lightweight:
- `New`
- `Planned`
- `Resolved`
- `Won't Do`
- `Cancelled`
Status rules:
- New reports start as `New`.
- Developers can move reports to `Planned`, `Resolved`, or `Won't Do`.
- Developers can change a report type.
- Developers can add, remove, and update free-form tags.
- Tags are visible to reporters.
- Tag entry should suggest previously used tags.
- Reporters can cancel their own report with an optional plain-text reason.
- `Cancelled` is final in v1.
- Reporters cannot reopen resolved or cancelled feedback; they can add comments where comments remain allowed.
- Developer reason/comment on `Won't Do` is optional.
- No severity, priority, assignment, duplicate linking, or Jira-style workflow is included in v1.
## Comments And Activity
- Feedback comments are visible to both the reporter and developers.
- Internal/private developer comments are out of scope for v1.
- Status/type/tag changes should be stored as activity history.
- Feedback detail should show a simple mixed timeline of comments and activity.
- Reporters can comment on their own feedback.
- Developers can comment on any feedback report.
## Notifications
- New feedback report: notify all users with the `Developer` role.
- Developer comment: notify the reporter.
- Developer status change: notify the reporter.
- Developer type/tag changes do not notify the reporter.
- Reporter comment: notify developers who have previously commented on that report.
- Feedback notifications use the existing in-app notification system.
- The existing notification bell should show feedback notifications and open the relevant feedback detail page.
- Email notifications are out of scope for v1.
- My Feedback should show an unread indicator for reports with unread developer comments or status changes.
## Developer Review Page
The developer review area is global, not workspace-scoped.
`/app/feedback` should support:
- list all reports by default, including final statuses
- filter by type
- filter by status
- filter by tag
- filter by reporter
- filter by workspace context
- filter by date range
- text search
- sort by newest
- sort by oldest
- sort by last activity
`/app/feedback/:id` should support:
- report details and captured metadata
- reporter identity details
- current URL/path link
- screenshot preview and developer download/open-original action
- comments
- activity timeline
- status updates
- type updates
- tag management with suggestions
## Reporter Pages
`/app/my-feedback` is global across workspaces and should default to active reports:
- `New`
- `Planned`
The page should support:
- list own reports only
- filter by status
- filter by type
- sort by newest
- sort by last activity
- unread indicators
- open feedback detail
- view visible tags
`/app/my-feedback/:id` should support:
- report details
- current URL/path link
- screenshot preview
- visible tags
- comments
- activity timeline
- cancel with optional reason when status is not final
## Localization
- User-facing feedback UI must be available in English and French.
- New strings belong in the existing locale files.
## API And Data Expectations
- Backend code should follow the FastEndpoints module pattern under `backend/src/Socialize.Api/Modules/Feedback`.
- Feedback entities should be added to `AppDbContext` with explicit model configuration.
- The `Developer` role should be seeded with the existing identity role setup.
- Screenshot storage should use the existing `IBlobStorage` abstraction.
- Protected screenshot access may require a feedback-specific download endpoint instead of public static blob URLs.
- Backend contract changes require OpenAPI regeneration while the backend is running.
## Out Of Scope For V1
- Public or unauthenticated feedback submission
- Shared feedback links
- Email notifications
- Draft saving
- Feedback deletion UI
- Automatic retention cleanup
- Severity or priority fields
- Assignment/owner workflow
- Duplicate linking
- Internal/private comments
- Workspace-owned exports or audit reports
## Done When
- [ ] Authenticated users can open a global Feedback dialog from every app page.
- [ ] Users can submit feedback with required type and description.
- [ ] Users can optionally capture, annotate, and upload an app viewport screenshot.
- [ ] Feedback records capture debugging metadata when available.
- [ ] Reporters can view their own global My Feedback list and details.
- [ ] Developers with the `Developer` role can view all feedback in `/app/feedback`.
- [ ] Developers can update type, status, and tags.
- [ ] Reporters and developers can comment on feedback.
- [ ] Feedback activity history is shown with comments.
- [ ] Feedback notifications appear in the existing in-app notification system.
- [ ] Feedback screenshot access is authenticated and scoped to reporter/developer access.
- [ ] English and French UI strings are present.
- [ ] Backend build and tests pass.
- [ ] Frontend build passes.
- [ ] OpenAPI is updated after backend contracts are implemented.

View File

@@ -0,0 +1,69 @@
# Task: Backend feedback foundation
## Goal
Add the backend foundation for product feedback reports.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add a new `Developer` identity role and seed it with the existing role setup.
- Add a new FastEndpoints module under `backend/src/Socialize.Api/Modules/Feedback`.
- Add feedback report data entities and EF Core model configuration.
- Add feedback enum/value support for:
- type: `Bug`, `Suggestion`, `Request`
- status: `New`, `Planned`, `Resolved`, `Won't Do`, `Cancelled`
- Add `DbSet` entries and module configuration to `AppDbContext`.
- Capture reporter id, reporter display fields, submitted route, browser metadata, viewport size, app version if available, and optional workspace/client/project/content context.
- Add API endpoints for:
- submit feedback
- list current user's feedback
- get current user's feedback detail
- list all feedback for `Developer`
- get feedback detail for `Developer`
- update feedback type/status/tags for `Developer`
- cancel own feedback with optional reason
- list previously used tags for `Developer`
- Enforce access rules:
- authenticated users can submit feedback
- reporters can view only their own feedback
- developers can view all feedback
- only developers can update type/status/tags
- reporters can only move their own non-final report to `Cancelled`
- Keep assignment, priority, severity, duplicate linking, and deletion out of scope.
## Likely Files
- `backend/src/Socialize.Api/Modules/Identity/Contracts/KnownRoles.cs`
- `backend/src/Socialize.Api/Modules/Identity/DependencyInjection.cs`
- `backend/src/Socialize.Api/Data/AppDbContext.cs`
- `backend/src/Socialize.Api/Modules/Feedback/**`
- `backend/tests/Socialize.Tests/**`
## Notes
- Use FastEndpoints handlers and keep request/response records near their handlers unless local module patterns suggest otherwise.
- Use FluentValidation for non-trivial inputs.
- Treat feedback as global SaaS operator data, not workspace-owned workflow data.
- Tags are free-form but should be normalized enough to support search/filter suggestions later.
## Validation
```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
```
## Done When
- [ ] `Developer` role exists and is seeded.
- [ ] Feedback reports can be submitted by authenticated users.
- [ ] Reporters can list and view only their own feedback.
- [ ] Developers can list and view all feedback.
- [ ] Developers can update type, status, and tags.
- [ ] Reporters can cancel their own feedback with an optional reason.
- [ ] Backend validation rejects invalid type/status transitions and missing descriptions.
- [ ] Backend tests cover access rules and core transitions.

View File

@@ -0,0 +1,54 @@
# Task: Protected feedback screenshots
## Goal
Store feedback screenshots through blob storage and expose them only through authenticated, feedback-scoped access.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add screenshot metadata to feedback reports or a related feedback screenshot entity.
- Store uploaded annotated screenshots with the existing `IBlobStorage` abstraction.
- Use a dedicated feedback storage container/prefix.
- Validate content type and maximum upload size on the backend.
- Add API support for attaching a screenshot when creating feedback or immediately after creation.
- Add a protected screenshot download/preview endpoint.
- Enforce screenshot access:
- reporter can access screenshots for their own reports
- developers can access all feedback screenshots
- no public/static blob URL access for feedback screenshots
- Return enough screenshot metadata for frontend preview/download flows without exposing unauthenticated blob URLs.
- Document that future feedback deletion must remove associated screenshot blobs.
## Likely Files
- `backend/src/Socialize.Api/Infrastructure/BlobStorage/Contracts/*`
- `backend/src/Socialize.Api/Infrastructure/BlobStorage/Services/*`
- `backend/src/Socialize.Api/Modules/Feedback/**`
- `backend/src/Socialize.Api/Data/AppDbContext.cs`
- `backend/tests/Socialize.Tests/**`
## Notes
- Existing portrait/logo blob behavior may expose static URLs; feedback screenshots must not rely on that public URL pattern.
- Prefer an endpoint that streams the blob after checking feedback access.
- Annotated screenshots are expected to be compressed PNG or JPEG files.
## Validation
```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
```
## Done When
- [ ] Feedback screenshots are stored via `IBlobStorage`.
- [ ] Feedback screenshots use a dedicated storage area/prefix.
- [ ] Invalid or oversized screenshots are rejected with clear API errors.
- [ ] Screenshot access requires authentication.
- [ ] Reporter/developer access rules are enforced for downloads/previews.
- [ ] Backend tests cover authorized and unauthorized screenshot access.

View File

@@ -0,0 +1,58 @@
# Task: Feedback comments, activity, and notifications
## Goal
Add the conversation, activity timeline, and in-app notification behavior for feedback.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add feedback comments visible to both reporters and developers.
- Add feedback activity entries for status/type/tag changes and cancellation.
- Return a mixed timeline of comments and activity from feedback detail endpoints.
- Add API endpoints for:
- reporter adds comment to own feedback
- developer adds comment to any feedback
- detail timeline retrieval if not included in existing detail endpoints
- Use the existing Notifications module for:
- new feedback report: notify all `Developer` users
- developer comment: notify reporter
- developer status change: notify reporter
- reporter comment: notify developers who have previously commented on that report
- Do not notify for developer type/tag changes.
- Extend notification payloads so feedback notifications can open feedback detail pages.
- Add read/unread support needed for My Feedback unread indicators, or expose enough data for the frontend to derive unread state from notifications.
## Likely Files
- `backend/src/Socialize.Api/Modules/Feedback/**`
- `backend/src/Socialize.Api/Modules/Notifications/**`
- `backend/src/Socialize.Api/Data/AppDbContext.cs`
- `backend/tests/Socialize.Tests/**`
## Notes
- Internal/private comments are out of scope.
- Email notifications are out of scope.
- Avoid adding assignment/owner workflow.
## Validation
```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
```
## Done When
- [ ] Reporters and developers can comment according to access rules.
- [ ] Status/type/tag/cancel actions create activity entries.
- [ ] Feedback detail includes a mixed comment/activity timeline.
- [ ] New reports notify all developers.
- [ ] Developer comments and status changes notify the reporter.
- [ ] Reporter comments notify participating developers.
- [ ] Feedback notifications include route-target data for frontend navigation.
- [ ] Backend tests cover comment access and notification side effects.

View File

@@ -0,0 +1,67 @@
# Task: Frontend feedback submission flow
## Goal
Add the global authenticated Feedback button, submission dialog, viewport capture, and annotation flow.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add feature-owned frontend code under `frontend/src/features/feedback/`.
- Add a small floating Feedback button to the authenticated app shell on every `/app/*` page.
- Keep the button visible on feedback-related pages too.
- Add a feedback submission dialog with:
- required type: `Bug`, `Suggestion`, `Request`
- required plain-text description
- optional capture flow
- dirty-close warning that discards unsent feedback if confirmed
- Capture only the current app viewport when the user explicitly clicks `Capture screen`.
- Add screenshot annotation support:
- crop
- arrows
- circles or ellipses
- lines
- freehand marks
- text labels
- undo
- clear/reset
- Export annotated screenshots as compressed PNG or JPEG.
- Submit feedback metadata, route context, browser metadata, viewport size, and optional screenshot to the backend.
- If capture fails, show a friendly error and allow text-only submission.
- Use established libraries for capture/annotation rather than custom screenshot infrastructure.
- Add English and French locale strings for the submission flow.
## Likely Files
- `frontend/package.json`
- `frontend/src/layouts/**`
- `frontend/src/features/feedback/**`
- `frontend/src/plugins/api.js`
- `frontend/src/locales/en.json`
- `frontend/src/locales/fr.json`
## Notes
- Runtime configuration must continue to flow through `frontend/src/config.js` if new configuration is needed.
- Keep the flow non-intrusive and app-shell scoped.
- Avoid landing-page or marketing-style UI.
## Validation
```bash
cd frontend
npm run build
```
## Done When
- [ ] Authenticated users see a floating Feedback button on every app page.
- [ ] Users can submit required type and description.
- [ ] Users can optionally capture and annotate the app viewport.
- [ ] Capture failures do not block text-only feedback.
- [ ] Dirty dialog close warns before discarding unsent feedback.
- [ ] UI strings exist in English and French.
- [ ] Frontend build passes.

View File

@@ -0,0 +1,71 @@
# Task: Frontend My Feedback pages
## Goal
Add reporter-facing pages for tracking submitted feedback.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add routes:
- `/app/my-feedback`
- `/app/my-feedback/:id`
- Add feature-owned views/stores/components under `frontend/src/features/feedback/`.
- The list page is global across workspaces and shows only the authenticated user's own reports.
- Default the list to active reports:
- `New`
- `Planned`
- Support list filtering by:
- status
- type
- Support sorting by:
- newest
- last activity
- Show unread indicators for reports with unread developer comments or status changes.
- Show visible tags.
- Detail page should show:
- report details
- current URL/path link
- screenshot preview
- tags
- comments
- activity timeline
- cancellation action with optional reason when the report is not final
- Allow reporters to add follow-up comments.
- Extend navigation/sidebar/user menu as appropriate so users can find My Feedback.
- Add English and French locale strings.
## Likely Files
- `frontend/src/router/router.js`
- `frontend/src/layouts/main/**`
- `frontend/src/features/feedback/**`
- `frontend/src/locales/en.json`
- `frontend/src/locales/fr.json`
## Notes
- Reporters cannot edit or delete submitted feedback in v1.
- Reporters cannot change status except cancelling their own non-final report.
- `Cancelled` is final.
## Validation
```bash
cd frontend
npm run build
```
## Done When
- [ ] Authenticated users can open My Feedback.
- [ ] My Feedback defaults to active reports.
- [ ] Users can filter and sort their feedback.
- [ ] Unread indicators are visible where applicable.
- [ ] Users can open details, preview screenshots, read timeline, and comment.
- [ ] Users can cancel their own non-final report with an optional reason.
- [ ] UI strings exist in English and French.
- [ ] Frontend build passes.

View File

@@ -0,0 +1,75 @@
# Task: Frontend developer feedback review
## Goal
Add the developer-facing global feedback review area.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Add routes restricted to the `Developer` role:
- `/app/feedback`
- `/app/feedback/:id`
- Add feature-owned views/stores/components under `frontend/src/features/feedback/`.
- Add a discoverable navigation entry for users with the `Developer` role.
- The list page is global and shows all reports by default, including final statuses.
- Support list filters:
- type
- status
- tag
- reporter
- workspace context
- date range
- text search
- Support sorting by:
- newest
- oldest
- last activity
- Detail page should show:
- report details and captured metadata
- reporter name/email
- current URL/path link
- screenshot preview
- developer download/open-original screenshot action
- comments
- activity timeline
- status updates
- type updates
- tag management with suggestions from previously used tags
- Allow developers to comment on any feedback report.
- Add English and French locale strings.
## Likely Files
- `frontend/src/router/router.js`
- `frontend/src/layouts/main/**`
- `frontend/src/features/feedback/**`
- `frontend/src/locales/en.json`
- `frontend/src/locales/fr.json`
## Notes
- Do not add assignment, priority, severity, duplicate linking, or private comments.
- Keep the review page operational and dense, not a Jira-style board.
## Validation
```bash
cd frontend
npm run build
```
## Done When
- [ ] Only users with the `Developer` role can access `/app/feedback`.
- [ ] Developers can list all feedback with required filters and sorting.
- [ ] Developers can open details and inspect metadata.
- [ ] Developers can preview and download/open screenshots.
- [ ] Developers can update type, status, and tags.
- [ ] Tag suggestions use previously used tags.
- [ ] Developers can comment.
- [ ] UI strings exist in English and French.
- [ ] Frontend build passes.

View File

@@ -0,0 +1,50 @@
# Task: Feedback notification UI integration
## Goal
Integrate feedback notifications into the existing notification bell and route navigation.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Extend frontend notification display to support feedback event types.
- Clicking a feedback notification should open:
- `/app/my-feedback/:id` for reporters
- `/app/feedback/:id` for developers when appropriate
- Mark feedback notifications as read using existing notification behavior.
- Ensure feedback notification labels are localized in English and French.
- Ensure My Feedback unread indicators stay consistent with notification read state or the backend unread model.
- Preserve existing content/comment/approval notification behavior.
## Likely Files
- `frontend/src/layouts/main/AppSidebar.vue`
- `frontend/src/features/notifications/**`
- `frontend/src/features/feedback/**`
- `frontend/src/locales/en.json`
- `frontend/src/locales/fr.json`
## Notes
- This task depends on backend feedback notification payloads from `003-feedback-comments-activity-notifications.md`.
- Do not introduce email notification behavior.
## Validation
```bash
cd frontend
npm run build
```
## Done When
- [ ] Feedback notifications appear in the existing notification bell.
- [ ] Feedback notification clicks navigate to the correct detail page.
- [ ] Feedback notifications can be marked read.
- [ ] My Feedback unread indicators reflect unread feedback activity.
- [ ] Existing notification flows still work.
- [ ] UI strings exist in English and French.
- [ ] Frontend build passes.

View File

@@ -0,0 +1,50 @@
# Task: OpenAPI sync and end-to-end feedback polish
## Goal
Finalize contract sync, validation, and end-to-end behavior after the feedback backend and frontend tasks are implemented.
## Feature Spec
- `docs/FEATURES/product-feedback.md`
## Scope
- Run the backend and regenerate OpenAPI after feedback API contracts are complete.
- Update generated frontend API types.
- Resolve frontend build issues caused by contract changes.
- Verify reporter and developer access flows manually.
- Verify protected screenshot preview/download behavior.
- Verify feedback notifications open the expected pages.
- Verify English/French feedback UI coverage.
- Review `docs/FEATURES/product-feedback.md` and update it if implementation intentionally changed behavior.
- Add or update follow-up task files for deferred work discovered during implementation.
## Likely Files
- `shared/openapi/openapi.json`
- `frontend/src/api/schema.d.ts`
- `docs/FEATURES/product-feedback.md`
- `docs/TASKS/product-feedback/**`
## Validation
```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
./scripts/update-openapi.sh
cd frontend
npm run build
```
## Done When
- [ ] OpenAPI snapshot is updated.
- [ ] Generated frontend schema is updated.
- [ ] Backend build passes.
- [ ] Backend tests pass.
- [ ] Frontend build passes.
- [ ] Reporter can submit, view, comment, and cancel feedback.
- [ ] Developer can review, filter, comment, update status/type/tags, and access screenshots.
- [ ] Feedback notifications work from the notification bell.
- [ ] Feature spec still matches implemented behavior.