# Feedback & Change Request System - Design Document

**Date**: 2026-02-27
**Status**: Approved

## Overview

In-app feedback system that allows users to submit bugs, change requests, improvements, and feature requests with AI-powered report generation. The system captures page context, allows element targeting, screenshot annotation, and uses AI (DeepSeek/ChatGPT) to generate structured specifications.

## Architecture

### Components

```
src/app/features/feedback/
├── feedback-button/              ← Floating Action Button (FAB)
├── feedback-modal/               ← Main modal with stepper
├── element-selector/             ← Click-to-select inspector overlay
├── screenshot-editor/            ← html2canvas capture + canvas annotation tools
├── ai-report-viewer/             ← Formatted AI report display
├── feedback-history/             ← localStorage saved reports list
└── services/
    ├── feedback.service.ts       ← State management & localStorage
    ├── element-inspector.service.ts ← DOM inspection & highlight
    ├── screenshot.service.ts     ← html2canvas + annotation canvas
    └── ai-report.service.ts      ← DeepSeek/ChatGPT API calls
```

### Dependencies (new)
- `html2canvas` - Automatic screenshot capture

## Feature Details

### 1. Floating Action Button (FAB)

- Fixed position: bottom-left (RTL layout)
- Gold (#ffc107) color matching theme
- Click opens main feedback modal
- Badge shows saved reports count from localStorage
- Visible on all authenticated pages (added in main-layout)

### 2. Feedback Modal - Stepper Flow

**Step 1: Type Selection**
| Type | Icon | Description |
|------|------|-------------|
| Bug | pi-bug | Report error or problem |
| Change Request | pi-pencil | Modify existing functionality |
| Improvement | pi-chart-line | Enhance performance or UX |
| Feature Request | pi-plus-circle | Add new functionality |

**Step 2: Auto-captured Context**
- `page_url` - Current browser URL (auto)
- `screen_name` - From Angular Router (auto)
- `module` - Extracted from route path (auto)

**Step 3: Type-specific Fields**

**Bug:**
- Steps to reproduce (textarea)
- Expected result (textarea)
- Actual result (textarea)
- Screenshot + Element select (optional)

**Change Request:**
- Change type dropdown: design change, show element, hide element, add field, remove field, reorder fields, change permissions, change validation, change label, change flow
- As-Is: Current state (textarea, required)
- To-Be: Desired state (textarea, required)
- Why: Business reason (textarea, required)
- Target Element (click-to-select)
- Screenshot + Annotations

**Improvement:**
- Description (textarea)
- Priority: high/medium/low
- Screenshot + Annotations (optional)
- Drawing on page or template selection

**Feature Request:**
- Description (textarea)
- Priority: high/medium/low
- Drawing on page and/or template selection (button, table, form, report)
- Screenshot + Annotations (optional)

**Step 4: Visual Attachments (shared)**
- Auto screenshot via html2canvas
- Manual image upload
- Annotation tools on either

**Step 5: AI Report Preview**
- Generated report display
- Copy / Download / Save options

### 3. Element Inspector (Click-to-Select)

1. User clicks "Select Element" button in modal
2. Modal hides temporarily
3. Semi-transparent overlay appears on page
4. Hovering highlights elements with blue border
5. Clicking captures element data:
   - `tag`, `id`, `classes`, `innerText` (truncated)
   - CSS selector path
   - Bounding rect (position/size)
6. Modal reopens with element info displayed
7. Can select multiple elements

### 4. Screenshot + Annotation Editor

**Capture methods:**
- Auto: html2canvas captures visible page
- Manual: File upload input

**Annotation tools (Canvas-based):**
- Arrow
- Rectangle
- Circle
- Free text
- Freehand drawing
- Color picker (red, green, blue, yellow)
- Undo/Redo stack

### 5. AI Report Generation

**Providers:**
- DeepSeek: `https://api.deepseek.com/v1/chat/completions` (model: deepseek-chat)
- ChatGPT: `https://api.openai.com/v1/chat/completions` (model: gpt-4o-mini)
- User selects preferred provider in settings
- Automatic fallback to other provider on failure

**Report templates by type:**

- **Bug** → Steps + Expected/Actual + Severity + Suggested Fix
- **Change Request** → Specification + Acceptance Criteria + Impact Analysis
- **Improvement** → Current State + Proposed Enhancement + Business Value
- **Feature Request** → Feature Spec + User Stories + Acceptance Criteria

**Screenshot handling:**
- Sent as base64 in vision message content
- AI analyzes visual context + annotations

### 6. Feedback History (localStorage)

- List view of all saved reports
- Filter by type and date
- View full report details
- Delete old reports
- Max storage: ~50 reports (with cleanup of oldest)

### 7. Data Model

```typescript
interface FeedbackReport {
  id: string;
  type: 'bug' | 'change_request' | 'improvement' | 'feature_request';
  status: 'draft' | 'submitted';

  // Auto-captured
  page_url: string;
  screen_name: string;
  module: string;

  // Type-specific
  change_type?: string;
  description: string;
  as_is?: string;
  to_be?: string;
  why?: string;
  steps_to_reproduce?: string;
  expected_result?: string;
  actual_result?: string;
  priority?: 'high' | 'medium' | 'low';
  template_type?: string;

  // Target elements
  target_elements: TargetElement[];

  // Visual
  screenshots: Screenshot[];

  // AI
  ai_report?: string;
  ai_provider?: 'deepseek' | 'chatgpt';

  // Meta
  created_at: string;
  user_name?: string;
}

interface TargetElement {
  tag: string;
  id?: string;
  classes: string[];
  text: string;
  css_path: string;
  rect: { x: number; y: number; width: number; height: number };
}

interface Screenshot {
  data_url: string;  // base64
  annotations?: string;  // annotated version base64
  source: 'auto' | 'upload';
}
```

## Non-Goals (for this phase)
- No database persistence
- No backend API integration
- No admin workflow (New → Accepted → Planned → Done)
- No email notifications
- No cost estimates or version targeting