1174 lines
36 KiB
Markdown
1174 lines
36 KiB
Markdown
# Implementation Audit & Action Plan
|
||
**Pre-Launch Items 1 & 4: Status Modules + Page Flow UX**
|
||
|
||
**Date:** December 15, 2025
|
||
**Status:** Complete System Audit
|
||
**Purpose:** Identify current implementation state and define exact changes needed
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [UX Components Audit](#ux-components-audit)
|
||
2. [Page Structure Audit](#page-structure-audit)
|
||
3. [Module-by-Module Implementation Status](#module-by-module-implementation-status)
|
||
|
||
---
|
||
|
||
|
||
## UX Components Audit
|
||
|
||
### Components Required by ITEM-4 but Missing
|
||
|
||
| Component | Status | Purpose | Priority |
|
||
|-----------|--------|---------|----------|
|
||
| **StepBanner** | 🔴 Missing | Show workflow step progress (Step 2/5) | High |
|
||
| **HelperNotification** | 🔴 Missing | Contextual guidance messages | High |
|
||
| **InlineGuidance** | 🔴 Missing | Help text under form fields | Medium |
|
||
| **Breadcrumbs** | 🔴 Missing | Navigation breadcrumb trail | Medium |
|
||
| **MetricsPanel** | 🔴 Missing | Collapsible bottom metrics panel | High |
|
||
| **NotificationDropdown** | 🔴 Missing | Bell icon notifications | Medium |
|
||
|
||
### Existing Components (Good)
|
||
|
||
| Component | Status | Location | Notes |
|
||
|-----------|--------|----------|-------|
|
||
| **PageHeader** | ✅ Exists | `frontend/src/components/common/PageHeader.tsx` | Well-implemented, standardized |
|
||
| **ModuleNavigationTabs** | ✅ Exists | `frontend/src/components/navigation/ModuleNavigationTabs.tsx` | Works well, needs tooltips |
|
||
| **Tooltip** | ✅ Exists | `frontend/src/components/ui/tooltip/Tooltip.tsx` | Basic implementation, needs enhancement |
|
||
| **ProgressModal** | ✅ Exists | `frontend/src/components/common/ProgressModal.tsx` | Needs refactoring |
|
||
|
||
---
|
||
|
||
### New Components to Create
|
||
|
||
#### 1. StepBanner Component
|
||
|
||
**Purpose:** Display workflow step progress (e.g., "Step 2 of 5: Cluster Keywords")
|
||
|
||
**Location:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface StepBannerProps {
|
||
currentStep: number;
|
||
totalSteps: number;
|
||
steps: Array<{
|
||
label: string;
|
||
href: string;
|
||
completed: boolean;
|
||
}>;
|
||
onStepClick?: (stepIndex: number) => void;
|
||
}
|
||
```
|
||
|
||
**Visual:**
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
Step 2 of 5: Organize into Clusters
|
||
|
||
1. Extract Keywords ✓ → 2. Cluster Keywords ● → 3. Generate Ideas → 4. Create Content → 5. Publish
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
```
|
||
|
||
**Usage:**
|
||
```tsx
|
||
<StepBanner
|
||
currentStep={2}
|
||
totalSteps={5}
|
||
steps={[
|
||
{ label: 'Extract Keywords', href: '/planner/keywords', completed: true },
|
||
{ label: 'Cluster Keywords', href: '/planner/clusters', completed: false },
|
||
// ...
|
||
]}
|
||
/>
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. HelperNotification Component
|
||
|
||
**Purpose:** Show contextual guidance (welcome, tips, warnings)
|
||
|
||
**Location:** `frontend/src/components/helper/HelperNotification.tsx` (NEW)
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface HelperNotificationProps {
|
||
type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
|
||
title: string;
|
||
message: string;
|
||
actions?: Array<{
|
||
label: string;
|
||
href?: string;
|
||
onClick?: () => void;
|
||
}>;
|
||
dismissible?: boolean;
|
||
onDismiss?: () => void;
|
||
}
|
||
```
|
||
|
||
**Visual:**
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 💡 Welcome to Keywords │
|
||
│ │
|
||
│ Extract and manage SEO keywords. Start by │
|
||
│ adding keywords manually or importing CSV. │
|
||
│ │
|
||
│ [Import CSV] [Learn More] [Got it] [×] │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Persistence:** Store dismissed state in localStorage per page
|
||
|
||
---
|
||
|
||
#### 3. InlineGuidance Component
|
||
|
||
**Purpose:** Small help text under form fields
|
||
|
||
**Location:** `frontend/src/components/helper/InlineGuidance.tsx` (NEW)
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface InlineGuidanceProps {
|
||
text: string;
|
||
type?: 'info' | 'warning' | 'error';
|
||
icon?: ReactNode;
|
||
}
|
||
```
|
||
|
||
**Visual:**
|
||
```
|
||
[Input Field: Enter keyword]
|
||
ℹ️ Use lowercase, no special characters. Separate with commas.
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. Breadcrumbs Component
|
||
|
||
**Purpose:** Navigation breadcrumb trail
|
||
|
||
**Location:** `frontend/src/components/navigation/Breadcrumbs.tsx` (NEW)
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface BreadcrumbsProps {
|
||
items: Array<{
|
||
label: string;
|
||
href?: string; // No href = current page
|
||
}>;
|
||
}
|
||
```
|
||
|
||
**Visual:**
|
||
```
|
||
Home > Setup > Sites > Site Settings
|
||
```
|
||
|
||
---
|
||
|
||
#### 5. MetricsPanel Component
|
||
|
||
**Purpose:** Collapsible metrics panel at page bottom
|
||
|
||
**Location:** `frontend/src/components/dashboard/MetricsPanel.tsx` (NEW)
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface MetricsPanelProps {
|
||
title: string;
|
||
metrics: Array<{
|
||
label: string;
|
||
value: string | number;
|
||
subtitle?: string;
|
||
icon?: ReactNode;
|
||
tooltip?: string;
|
||
onClick?: () => void;
|
||
}>;
|
||
collapsible?: boolean;
|
||
defaultCollapsed?: boolean;
|
||
}
|
||
```
|
||
|
||
**Visual (Expanded):**
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ▼ Keyword Metrics [Collapse] × │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Total: 450 │ New: 120 │ Mapped: 330 │ Vol: 125K │
|
||
│ ℹ️ All saved │ ℹ️ Unmapped │ ℹ️ In cluster │ ℹ️ Search │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. NotificationDropdown Component
|
||
|
||
**Purpose:** Bell icon with notification list
|
||
|
||
**Location:** `frontend/src/components/notifications/NotificationDropdown.tsx` (NEW)
|
||
|
||
**Backend Required:** `Notification` model with account FK
|
||
|
||
**Props:**
|
||
```typescript
|
||
interface NotificationDropdownProps {
|
||
notifications: Notification[];
|
||
unreadCount: number;
|
||
onMarkRead: (id: number) => void;
|
||
onClearAll: () => void;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Tooltip Component Enhancement
|
||
|
||
**Current Location:** `frontend/src/components/ui/tooltip/Tooltip.tsx`
|
||
|
||
**Current Implementation:** Basic hover tooltip with portal rendering
|
||
|
||
**Required Enhancements:**
|
||
|
||
| Enhancement | Current | Required |
|
||
|-------------|---------|----------|
|
||
| Keyboard accessibility | ❌ No ESC handler | ✅ ESC to close, tab navigation |
|
||
| Hover delay | ❌ Immediate show | ✅ 300ms delay before show |
|
||
| Max width | ❌ Whitespace nowrap | ✅ Max-width with wrapping |
|
||
| Rich content | ❌ Text only | ✅ Support ReactNode content |
|
||
| Arrow positioning | ✅ Has arrow | ✅ Keep current (good) |
|
||
|
||
**Example Usage (Enhanced):**
|
||
```tsx
|
||
<Tooltip content={
|
||
<div>
|
||
<strong>Clustering</strong>
|
||
<p>Groups keywords by semantic similarity</p>
|
||
<a href="/help">Learn more →</a>
|
||
</div>
|
||
}>
|
||
<InfoIcon />
|
||
</Tooltip>
|
||
```
|
||
|
||
---
|
||
|
||
## Page Structure Audit
|
||
|
||
### Current Page Structure (Planner/Writer Pages)
|
||
|
||
**Example: Keywords.tsx**
|
||
|
||
```tsx
|
||
<div>
|
||
<PageHeader
|
||
title="Keywords"
|
||
badge={{ icon: <KeyIcon />, color: 'blue' }}
|
||
navigation={<ModuleNavigationTabs tabs={tabs} />}
|
||
/>
|
||
|
||
{/* Actions bar */}
|
||
<div className="actions">
|
||
<Button>Import</Button>
|
||
<Button>Add</Button>
|
||
</div>
|
||
|
||
{/* Main content - table */}
|
||
<Table data={keywords} />
|
||
|
||
{/* No metrics panel */}
|
||
</div>
|
||
```
|
||
|
||
### Required Page Structure (Standardized)
|
||
|
||
**All workflow pages should follow:**
|
||
|
||
```tsx
|
||
<div className="page-container">
|
||
{/* 1. Page Header (EXISTS) */}
|
||
<PageHeader
|
||
title="Page Title"
|
||
badge={badge}
|
||
navigation={<ModuleNavigationTabs tabs={tabs} />}
|
||
/>
|
||
|
||
{/* 2. Step Banner (MISSING - needs creation) */}
|
||
{isWorkflowPage && <StepBanner currentStep={2} totalSteps={5} />}
|
||
|
||
{/* 3. Helper Notification (MISSING - needs creation) */}
|
||
{showHelper && <HelperNotification type="welcome" message="..." />}
|
||
|
||
{/* 4. Breadcrumbs (MISSING - needs creation) */}
|
||
{showBreadcrumbs && <Breadcrumbs items={breadcrumbs} />}
|
||
|
||
{/* 5. Page Actions Bar (EXISTS, needs standardization) */}
|
||
<PageActionsBar
|
||
primaryAction={primaryAction}
|
||
secondaryActions={secondaryActions}
|
||
filters={filters}
|
||
/>
|
||
|
||
{/* 6. Main Content (EXISTS) */}
|
||
<MainContent>
|
||
{/* Tables, forms, cards */}
|
||
</MainContent>
|
||
|
||
{/* 7. Metrics Panel (MISSING - needs creation) */}
|
||
<MetricsPanel metrics={metrics} collapsible={true} />
|
||
</div>
|
||
```
|
||
|
||
### Page Header Usage Analysis
|
||
|
||
**Current Status:** ✅ PageHeader is used on all major pages
|
||
|
||
| Module | Page | Has PageHeader | Has Navigation | Missing Elements |
|
||
|--------|------|----------------|----------------|------------------|
|
||
| **Planner** | Keywords | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| Planner | Clusters | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| Planner | Ideas | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| **Writer** | Tasks | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| Writer | Content | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| Writer | Images | ✅ Yes | ✅ Yes | StepBanner, Helper, Metrics |
|
||
| **Automation** | Automation | ✅ Yes | ❌ No tabs | Helper, stage progress fixes |
|
||
|
||
---
|
||
|
||
## Module-by-Module Implementation Status
|
||
|
||
### PLANNER MODULE
|
||
|
||
#### Keywords Page
|
||
|
||
**Location:** `frontend/src/pages/Planner/Keywords.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 1/3: Extract Keywords" | Add component |
|
||
| Helper | ❌ | None | "Import keywords or add manually" | Add welcome message |
|
||
| Progress Modal | ✅ | useProgressModal for clustering | Fix message counts | Update backend tracker |
|
||
| Metrics Panel | ❌ | None | Total, New, Mapped, Avg Volume | Add component |
|
||
| Tooltips | ❌ | None | "Cluster" button, import icon | Add tooltips |
|
||
| Next Step Button | ❌ | None | "Cluster Keywords →" | Add button to actions |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 1/3 in Planner workflow
|
||
2. Add HelperNotification on first visit: "Import keywords or add manually to start"
|
||
3. Add Tooltip on "Cluster" button: "Group keywords by semantic similarity"
|
||
4. Add MetricsPanel at bottom with: Total keywords, New (unmapped), Mapped, Avg volume
|
||
5. Add "Next Step" button: "Cluster Keywords →" navigating to /planner/clusters
|
||
6. Backend: Update clustering progress to include keyword counts in details
|
||
|
||
---
|
||
|
||
#### Clusters Page
|
||
|
||
**Location:** `frontend/src/pages/Planner/Clusters.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 2/3: Organize Clusters" | Add component |
|
||
| Helper | ❌ | None | "Clusters organize keywords into topic groups" | Add welcome message |
|
||
| Progress Modal | ❌ | No generation function | N/A (future feature) | None |
|
||
| Metrics Panel | ❌ | None | Total clusters, Avg size, Total volume | Add component |
|
||
| Tooltips | ❌ | None | Cluster cards, action buttons | Add tooltips |
|
||
| Next Step Button | ❌ | None | "Generate Ideas →" | Add button to actions |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 2/3 in Planner workflow
|
||
2. Add HelperNotification: "Clusters organize keywords into topic groups"
|
||
3. Add Tooltip on cluster cards showing keyword count and volume
|
||
4. Add MetricsPanel: Total clusters, Avg cluster size, Total volume
|
||
5. Add "Next Step" button: "Generate Ideas →" to /planner/ideas
|
||
|
||
---
|
||
|
||
#### Ideas Page
|
||
|
||
**Location:** `frontend/src/pages/Planner/Ideas.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 3/3: Generate Ideas" | Add component |
|
||
| Helper | ❌ | None | "Content ideas generated from clusters" | Add welcome message |
|
||
| Progress Modal | ✅ | useProgressModal for ideas | Fix generic "preparing clusters" | Update backend messages |
|
||
| Metrics Panel | ❌ | None | Ideas, Cluster hubs, Word count estimates | Add component |
|
||
| Content Structure Badge | ✅ | Shows badge | Add tooltip to badge | Add tooltip |
|
||
| Next Step Button | ❌ | None | "Create Tasks →" | Add button |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 3/3 in Planner workflow
|
||
2. Add HelperNotification: "Content ideas are generated from your clusters"
|
||
3. Add Tooltip on content structure badge explaining structure type
|
||
4. Add MetricsPanel: Total ideas, Cluster hubs, Est. word count
|
||
5. Add "Next Step" button: "Create Tasks →" to convert ideas to tasks
|
||
6. Backend: Update idea generation to include cluster names in details
|
||
|
||
---
|
||
|
||
### WRITER MODULE
|
||
|
||
#### Tasks Page
|
||
|
||
**Location:** `frontend/src/pages/Writer/Tasks.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 1/3: Queue Tasks" | Add component |
|
||
| Helper | ❌ | None | "Tasks are content generation jobs" | Add welcome message |
|
||
| Progress Modal | ✅ | useProgressModal for content | Fix generic "writing article" | Update backend with title & word count |
|
||
| Metrics Panel | ❌ | None | Total, Queued, Completed, Total words | Add component |
|
||
| Status Badges | ✅ | Shows status | Add tooltips to badges | Add tooltips |
|
||
| Next Step Button | ❌ | None | "Generate Content →" | Add button |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 1/3 in Writer workflow
|
||
2. Add HelperNotification: "Tasks are content generation jobs queued for AI"
|
||
3. Add Tooltip on status badges explaining each status
|
||
4. Add MetricsPanel: Total tasks, Queued, Completed, Total words
|
||
5. Add "Next Step" button: "Generate Content →" trigger bulk generation
|
||
6. Backend: Include task title and target word count in progress details
|
||
|
||
---
|
||
|
||
#### Content Page
|
||
|
||
**Location:** `frontend/src/pages/Writer/Content.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 2/3: Review Content" | Add component |
|
||
| Helper | ❌ | None | "Review and edit AI-generated content" | Add welcome message |
|
||
| Progress Modal | ✅ | For image prompts | Fix prompt count extraction | Update backend to return counts |
|
||
| Metrics Panel | ❌ | None | Total, Drafts, Published, Total words | Add component |
|
||
| Status Badges | ✅ | Shows status | Add tooltips | Add tooltips |
|
||
| Next Step Button | ❌ | None | "Generate Images →" | Add button |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 2/3 in Writer workflow
|
||
2. Add HelperNotification: "Review and edit AI-generated content before publishing"
|
||
3. Add Tooltip on status badges (draft/review/published)
|
||
4. Add MetricsPanel: Total content, Drafts, Published, Total words
|
||
5. Add "Next Step" button: "Generate Images →" to /writer/images
|
||
6. Backend: Return structured prompt counts in result
|
||
|
||
---
|
||
|
||
#### Images Page
|
||
|
||
**Location:** `frontend/src/pages/Writer/Images.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge, tabs | ✅ Good | None |
|
||
| StepBanner | ❌ | None | Show "Step 3/3: Generate Images" | Add component |
|
||
| Helper | ❌ | None | "Generate images from AI prompts" | Add welcome message |
|
||
| Progress Modal | ✅ | ImageQueueModal | Harmonize with ProgressModal | Consider refactor |
|
||
| Metrics Panel | ❌ | None | Total images, Generated, Published | Add component |
|
||
| Image Preview | ✅ | Hover preview | Add tooltip | None needed |
|
||
| Next Step Button | ❌ | None | "Publish to WordPress →" | Add button |
|
||
|
||
**Required Changes:**
|
||
1. Add StepBanner showing step 3/3 in Writer workflow
|
||
2. Add HelperNotification: "Generate images for your content from AI prompts"
|
||
3. Add MetricsPanel: Total images, Generated, Published
|
||
4. Add "Next Step" button: "Publish to WordPress →" to publish flow
|
||
5. Consider harmonizing ImageQueueModal with ProgressModal pattern
|
||
|
||
---
|
||
|
||
### AUTOMATION MODULE
|
||
|
||
#### Automation Page
|
||
|
||
**Location:** `frontend/src/pages/Automation/AutomationPage.tsx`
|
||
|
||
| Feature | Status | Current | Required | Action |
|
||
|---------|--------|---------|----------|--------|
|
||
| PageHeader | ✅ | Has title, badge | No tabs (not needed) | None |
|
||
| StepBanner | ❌ | Shows stage cards instead | Keep current approach | None |
|
||
| Helper | ❌ | None | "Automation runs workflow automatically" | Add helper |
|
||
| Stage Progress | 🔴 | Broken | Fix queue items, counts | Critical fix needed |
|
||
| Progress Bar | 🔴 | Inaccurate | Fix calculation | Fix |
|
||
| Real-time Updates | 🟡 | Partial | Optimize polling | Improve |
|
||
| Metrics Display | ✅ | Stage cards show metrics | Fix accuracy | Update logic |
|
||
|
||
**Critical Issues:**
|
||
|
||
| Issue | Impact | Location | Fix Required |
|
||
|-------|--------|----------|--------------|
|
||
| Wrong queue items displayed | Users see incorrect tasks in queue | Stage cards | Fix stage result parsing |
|
||
| Missing queue items | Some items don't appear | Stage cards | Fix API response structure |
|
||
| Progress bar doesn't progress | Users can't see actual progress | Progress bar component | Fix percentage calculation |
|
||
| Total/processed counts buggy | Metrics don't add up | Stage cards | Fix backend stage_X_result JSON |
|
||
|
||
**Required Changes:**
|
||
1. Add HelperNotification: "Automation runs the entire workflow automatically"
|
||
2. Fix stage progress cards to show accurate queue items:
|
||
- Parse `stage_X_result` JSON correctly
|
||
- Show pending, processing, completed, failed lists
|
||
3. Fix progress bar calculation:
|
||
- Formula: `(completed_stages * 100 / 7) + (current_stage_progress / 7)`
|
||
4. Fix stage metrics to show accurate counts:
|
||
- Keywords processed → clusters created
|
||
- Clusters processed → ideas created
|
||
- Ideas → tasks → content → images
|
||
5. Add real-time stage updates without excessive polling
|
||
6. Display estimated completion time
|
||
7. Show credit consumption per stage
|
||
|
||
---
|
||
|
||
**End of Audit Document**
|
||
|
||
|
||
**File:** `backend/igny8_core/common/status_enums.py` (NEW)
|
||
|
||
```python
|
||
GENERATION_STATUS_CHOICES = [
|
||
('pending', 'Pending'),
|
||
('queued', 'Queued'),
|
||
('processing', 'Processing'),
|
||
('completed', 'Completed'),
|
||
('failed', 'Failed'),
|
||
('cancelled', 'Cancelled'),
|
||
]
|
||
|
||
CONTENT_STATUS_CHOICES = [
|
||
('draft', 'Draft'),
|
||
('review', 'Review'),
|
||
('published', 'Published'),
|
||
('archived', 'Archived'),
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
#### 1.2 Add generation_status Fields
|
||
|
||
**Migrations Required:**
|
||
|
||
| Model | Field | Default | Migration File |
|
||
|-------|-------|---------|----------------|
|
||
| Keywords | `generation_status` | `'pending'` | `0014_add_keywords_generation_status.py` |
|
||
| Clusters | `generation_status` | `'pending'` | `0015_add_clusters_generation_status.py` |
|
||
| Content | `generation_status` | `'pending'` | `0016_add_content_generation_status.py` |
|
||
|
||
**Update Status Choices:**
|
||
|
||
| Model | Action | Migration File |
|
||
|-------|--------|----------------|
|
||
| ContentIdeas | Add `processing`, `failed`, `cancelled` | `0017_update_ideas_status_choices.py` |
|
||
| Tasks | Add `processing`, `failed`, `cancelled` | `0018_update_tasks_status_choices.py` |
|
||
|
||
---
|
||
|
||
#### 1.3 Enhance ProgressTracker
|
||
|
||
**File:** `backend/igny8_core/ai/tracker.py`
|
||
|
||
**Changes:**
|
||
|
||
```python
|
||
class ProgressTracker:
|
||
def update(
|
||
self,
|
||
phase: str,
|
||
percentage: int,
|
||
message: str,
|
||
details: Dict = None # NEW
|
||
):
|
||
"""
|
||
details = {
|
||
'items_total': int,
|
||
'items_processed': int,
|
||
'current_item': str,
|
||
'current_item_name': str,
|
||
'estimated_seconds_remaining': int,
|
||
}
|
||
"""
|
||
if self.task:
|
||
self.task.update_state(
|
||
state='PROGRESS',
|
||
meta={
|
||
'phase': phase,
|
||
'percentage': percentage,
|
||
'message': message,
|
||
'details': details or {}, # Include details
|
||
'current': self.current,
|
||
'total': self.total,
|
||
}
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
#### 1.4 Update AI Function Progress Messages
|
||
|
||
**Files to Update:**
|
||
|
||
1. **auto_cluster.py:**
|
||
```python
|
||
# PREP phase
|
||
tracker.update(
|
||
phase='PREP',
|
||
percentage=10,
|
||
message=f"Loading {len(keywords)} keywords for clustering",
|
||
details={
|
||
'items_total': len(keywords),
|
||
'items_processed': 0,
|
||
}
|
||
)
|
||
|
||
# AI_CALL phase (in loop)
|
||
tracker.update(
|
||
phase='AI_CALL',
|
||
percentage=20 + (processed * 60 / total),
|
||
message=f"Analyzing keyword relationships ({processed}/{total})",
|
||
details={
|
||
'items_total': total,
|
||
'items_processed': processed,
|
||
'current_item': 'keyword',
|
||
'current_item_name': current_keyword.keyword,
|
||
}
|
||
)
|
||
|
||
# SAVE phase
|
||
tracker.update(
|
||
phase='SAVE',
|
||
percentage=90,
|
||
message=f"Creating {len(clusters)} clusters",
|
||
details={
|
||
'items_total': len(clusters),
|
||
}
|
||
)
|
||
```
|
||
|
||
2. **generate_ideas.py:**
|
||
```python
|
||
# PREP phase
|
||
tracker.update(
|
||
phase='PREP',
|
||
percentage=10,
|
||
message=f"Preparing {len(clusters)} cluster(s) for idea generation",
|
||
details={'items_total': len(clusters)}
|
||
)
|
||
|
||
# AI_CALL phase (per cluster)
|
||
tracker.update(
|
||
phase='AI_CALL',
|
||
percentage=20 + (idx * 60 / total),
|
||
message=f"Generating ideas for cluster: {cluster.name}",
|
||
details={
|
||
'items_total': total,
|
||
'items_processed': idx,
|
||
'current_item_name': cluster.name,
|
||
}
|
||
)
|
||
```
|
||
|
||
3. **generate_content.py:**
|
||
```python
|
||
# PREP phase
|
||
tracker.update(
|
||
phase='PREP',
|
||
percentage=10,
|
||
message=f"Preparing task: {task.title}",
|
||
details={'current_item_name': task.title}
|
||
)
|
||
|
||
# AI_CALL phase
|
||
tracker.update(
|
||
phase='AI_CALL',
|
||
percentage=50,
|
||
message=f"Writing {task.word_count}-word article: {task.title}",
|
||
details={
|
||
'current_item_name': task.title,
|
||
'word_count': task.word_count,
|
||
}
|
||
)
|
||
```
|
||
|
||
4. **generate_image_prompts.py:**
|
||
```python
|
||
# PARSE phase
|
||
tracker.update(
|
||
phase='PARSE',
|
||
percentage=70,
|
||
message=f"Writing {len(in_article_prompts)} in-article image prompts",
|
||
details={'prompt_count': len(in_article_prompts)}
|
||
)
|
||
```
|
||
|
||
5. **generate_images.py:**
|
||
```python
|
||
# AI_CALL phase (in loop)
|
||
tracker.update(
|
||
phase='AI_CALL',
|
||
percentage=20 + (idx * 70 / total),
|
||
message=f"Generating image {idx + 1}/{total}: {prompt[:50]}...",
|
||
details={
|
||
'items_total': total,
|
||
'items_processed': idx,
|
||
'current_item_name': prompt[:100],
|
||
}
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
#### 1.5 Return Structured Completion Data
|
||
|
||
**Update Celery task return values:**
|
||
|
||
```python
|
||
# In each AI function, return structured summary
|
||
return {
|
||
'status': 'completed',
|
||
'summary': {
|
||
'message': 'Clustering complete',
|
||
'details': f"{keywords_processed} keywords mapped into {clusters_created} clusters",
|
||
'counts': {
|
||
'keywords_processed': keywords_processed,
|
||
'clusters_created': clusters_created,
|
||
}
|
||
},
|
||
'results': [...],
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 2: Frontend Progress Refactor (Week 1-2)
|
||
|
||
#### 2.1 Simplify useProgressModal Hook
|
||
|
||
**File:** `frontend/src/hooks/useProgressModal.ts`
|
||
|
||
**Changes:**
|
||
|
||
1. **Remove regex extraction logic** (Lines 90-120, ~100 lines)
|
||
2. **Simplify getStepInfo():**
|
||
```typescript
|
||
const getStepInfo = (state: any): ProgressDisplay => {
|
||
const details = state.meta?.details || {};
|
||
|
||
return {
|
||
percentage: state.meta?.percentage || 0,
|
||
message: state.meta?.message || 'Processing...',
|
||
itemProgress: details.items_total
|
||
? `${details.items_processed || 0}/${details.items_total}`
|
||
: null,
|
||
currentItem: details.current_item_name || null,
|
||
};
|
||
};
|
||
```
|
||
|
||
3. **Update polling to use backend details directly**
|
||
|
||
---
|
||
|
||
#### 2.2 Simplify ProgressModal Component
|
||
|
||
**File:** `frontend/src/components/common/ProgressModal.tsx`
|
||
|
||
**Changes:**
|
||
|
||
1. **Replace getSuccessMessage() with simple backend lookup:**
|
||
```typescript
|
||
const getSuccessMessage = (taskResult: any): string => {
|
||
return taskResult?.summary?.details || 'Task completed successfully';
|
||
};
|
||
```
|
||
|
||
2. **Remove all regex extraction** (Lines 30-130)
|
||
|
||
3. **Use backend step definitions** instead of hardcoded function checks
|
||
|
||
---
|
||
|
||
#### 2.3 Add Real-Time Status Updates to Tables
|
||
|
||
**Files:** All page components with tables
|
||
|
||
**Changes:**
|
||
|
||
1. Add `status` column to tables showing badge
|
||
2. Update row status in real-time during processing
|
||
3. Show animated spinner for "processing" status
|
||
4. Auto-reload row data on completion
|
||
|
||
**Example:**
|
||
```tsx
|
||
// In Keywords table
|
||
<td>
|
||
{keyword.generation_status === 'processing' && (
|
||
<Badge color="blue" icon={<SpinnerIcon className="animate-spin" />}>
|
||
Processing
|
||
</Badge>
|
||
)}
|
||
{keyword.generation_status === 'completed' && (
|
||
<Badge color="green">Completed</Badge>
|
||
)}
|
||
</td>
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 3: Create New UX Components (Week 2)
|
||
|
||
#### 3.1 StepBanner Component
|
||
|
||
**File:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)
|
||
|
||
**Implementation:**
|
||
```tsx
|
||
import React from 'react';
|
||
import { Link } from 'react-router-dom';
|
||
|
||
interface Step {
|
||
label: string;
|
||
href: string;
|
||
completed: boolean;
|
||
}
|
||
|
||
interface StepBannerProps {
|
||
currentStep: number;
|
||
totalSteps: number;
|
||
steps: Step[];
|
||
}
|
||
|
||
export default function StepBanner({ currentStep, totalSteps, steps }: StepBannerProps) {
|
||
return (
|
||
<div className="bg-gradient-to-r from-brand-50 to-brand-100 dark:from-brand-900/20 dark:to-brand-800/20 border border-brand-200 dark:border-brand-700 rounded-lg p-4 mb-6">
|
||
<p className="text-sm font-semibold text-brand-700 dark:text-brand-300 mb-2">
|
||
Step {currentStep} of {totalSteps}: {steps[currentStep - 1]?.label}
|
||
</p>
|
||
<div className="flex items-center gap-2">
|
||
{steps.map((step, idx) => (
|
||
<React.Fragment key={idx}>
|
||
{step.completed ? (
|
||
<Link
|
||
to={step.href}
|
||
className="flex items-center gap-1 text-sm text-green-600 dark:text-green-400 hover:underline"
|
||
>
|
||
<span>✓</span> {idx + 1}. {step.label}
|
||
</Link>
|
||
) : idx === currentStep - 1 ? (
|
||
<span className="flex items-center gap-1 text-sm font-medium text-brand-600 dark:text-brand-400">
|
||
<span>●</span> {idx + 1}. {step.label}
|
||
</span>
|
||
) : (
|
||
<span className="flex items-center gap-1 text-sm text-gray-400 dark:text-gray-600">
|
||
{idx + 1}. {step.label}
|
||
</span>
|
||
)}
|
||
{idx < steps.length - 1 && (
|
||
<span className="text-gray-400">→</span>
|
||
)}
|
||
</React.Fragment>
|
||
))}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.2 HelperNotification Component
|
||
|
||
**File:** `frontend/src/components/helper/HelperNotification.tsx` (NEW)
|
||
|
||
**Implementation:**
|
||
```tsx
|
||
import React, { useState, useEffect } from 'react';
|
||
import Button from '../ui/button/Button';
|
||
|
||
interface HelperAction {
|
||
label: string;
|
||
href?: string;
|
||
onClick?: () => void;
|
||
}
|
||
|
||
interface HelperNotificationProps {
|
||
type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
|
||
title: string;
|
||
message: string;
|
||
actions?: HelperAction[];
|
||
dismissible?: boolean;
|
||
pageKey: string; // Used for localStorage persistence
|
||
}
|
||
|
||
export default function HelperNotification({
|
||
type,
|
||
title,
|
||
message,
|
||
actions,
|
||
dismissible = true,
|
||
pageKey,
|
||
}: HelperNotificationProps) {
|
||
const storageKey = `helper_dismissed_${pageKey}`;
|
||
const [isDismissed, setIsDismissed] = useState(false);
|
||
|
||
useEffect(() => {
|
||
const dismissed = localStorage.getItem(storageKey);
|
||
if (dismissed === 'true') {
|
||
setIsDismissed(true);
|
||
}
|
||
}, [storageKey]);
|
||
|
||
const handleDismiss = () => {
|
||
localStorage.setItem(storageKey, 'true');
|
||
setIsDismissed(true);
|
||
};
|
||
|
||
if (isDismissed) return null;
|
||
|
||
const colors = {
|
||
welcome: 'bg-blue-50 border-blue-200 text-blue-900 dark:bg-blue-900/20 dark:border-blue-700 dark:text-blue-100',
|
||
info: 'bg-gray-50 border-gray-200 text-gray-900 dark:bg-gray-800/50 dark:border-gray-700 dark:text-gray-100',
|
||
tip: 'bg-green-50 border-green-200 text-green-900 dark:bg-green-900/20 dark:border-green-700 dark:text-green-100',
|
||
warning: 'bg-orange-50 border-orange-200 text-orange-900 dark:bg-orange-900/20 dark:border-orange-700 dark:text-orange-100',
|
||
success: 'bg-emerald-50 border-emerald-200 text-emerald-900 dark:bg-emerald-900/20 dark:border-emerald-700 dark:text-emerald-100',
|
||
};
|
||
|
||
const icons = {
|
||
welcome: '💡',
|
||
info: 'ℹ️',
|
||
tip: '✨',
|
||
warning: '⚠️',
|
||
success: '✅',
|
||
};
|
||
|
||
return (
|
||
<div className={`rounded-lg border p-4 mb-6 ${colors[type]}`}>
|
||
<div className="flex items-start gap-3">
|
||
<span className="text-2xl">{icons[type]}</span>
|
||
<div className="flex-1">
|
||
<h4 className="font-semibold mb-1">{title}</h4>
|
||
<p className="text-sm mb-3">{message}</p>
|
||
{actions && actions.length > 0 && (
|
||
<div className="flex gap-2">
|
||
{actions.map((action, idx) => (
|
||
<Button
|
||
key={idx}
|
||
variant="secondary"
|
||
size="sm"
|
||
onClick={action.onClick}
|
||
>
|
||
{action.label}
|
||
</Button>
|
||
))}
|
||
</div>
|
||
)}
|
||
</div>
|
||
{dismissible && (
|
||
<button
|
||
onClick={handleDismiss}
|
||
className="text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-300"
|
||
>
|
||
×
|
||
</button>
|
||
)}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.3 Other Components
|
||
|
||
**Create these components following similar patterns:**
|
||
|
||
1. **InlineGuidance.tsx** - Simple text with icon
|
||
2. **Breadcrumbs.tsx** - Navigation trail with links
|
||
3. **MetricsPanel.tsx** - Collapsible metrics display
|
||
4. **NotificationDropdown.tsx** - Bell icon with dropdown list
|
||
|
||
---
|
||
|
||
### Phase 4: Update All Pages (Week 3)
|
||
|
||
#### 4.1 Planner Pages
|
||
|
||
**Apply to:** Keywords.tsx, Clusters.tsx, Ideas.tsx
|
||
|
||
**Changes per page:**
|
||
1. Import new components
|
||
2. Add StepBanner at top
|
||
3. Add HelperNotification below StepBanner
|
||
4. Add Tooltips to icons and buttons
|
||
5. Add MetricsPanel at bottom
|
||
6. Add "Next Step" button to actions bar
|
||
|
||
---
|
||
|
||
#### 4.2 Writer Pages
|
||
|
||
**Apply to:** Tasks.tsx, Content.tsx, Images.tsx
|
||
|
||
**Changes per page:**
|
||
1. Import new components
|
||
2. Add StepBanner at top
|
||
3. Add HelperNotification below StepBanner
|
||
4. Add Tooltips to status badges
|
||
5. Add MetricsPanel at bottom
|
||
6. Add "Next Step" button to actions bar
|
||
|
||
---
|
||
|
||
#### 4.3 Automation Page
|
||
|
||
**File:** `frontend/src/pages/Automation/AutomationPage.tsx`
|
||
|
||
**Critical Fixes:**
|
||
1. Fix stage progress card data parsing
|
||
2. Fix queue item display (pending/processing/completed/failed)
|
||
3. Fix progress bar calculation
|
||
4. Add real-time stage updates
|
||
5. Add HelperNotification
|
||
|
||
---
|
||
|
||
### Phase 5: Testing & QA (Week 3)
|
||
|
||
#### 5.1 Manual AI Function Tests
|
||
|
||
| Test | Page | Action | Expected Result |
|
||
|------|------|--------|-----------------|
|
||
| Clustering | Keywords | Select 50 keywords, run clustering | Modal shows accurate counts, creates clusters |
|
||
| Ideas | Ideas | Select 3 clusters, generate ideas | Modal shows cluster names, creates ideas |
|
||
| Content | Tasks | Select 1 task, generate | Modal shows task title & word count |
|
||
| Image Prompts | Content | Generate prompts | Modal shows "1 Featured + X In-article prompts" |
|
||
| Images | Images | Generate images | Shows each image with accurate progress |
|
||
|
||
---
|
||
|
||
#### 5.2 Automation Wizard Tests
|
||
|
||
| Test | Expected Result |
|
||
|------|-----------------|
|
||
| Stage 1: Clustering | Shows accurate keyword → cluster counts |
|
||
| Stage 2: Ideas | Shows cluster → idea counts |
|
||
| Stage 3: Tasks | Shows idea → task conversion |
|
||
| Stage 4: Content | Shows task → content generation |
|
||
| Pause/Resume | Continues from pause point |
|
||
| Cancel | Stops and shows cancelled state |
|
||
| Queue Display | Shows correct pending/processing/completed items per stage |
|
||
|
||
---
|
||
|
||
#### 5.3 UX Component Tests
|
||
|
||
| Component | Test | Expected |
|
||
|-----------|------|----------|
|
||
| StepBanner | Click completed step | Navigates to that page |
|
||
| HelperNotification | Dismiss | Persists dismissal in localStorage |
|
||
| Tooltip | Hover | Shows after 300ms delay |
|
||
| MetricsPanel | Collapse | Collapses and shows summary |
|
||
| Breadcrumbs | Click | Navigates to parent pages |
|
||
|
||
---
|
||
|
||
## Summary of Required Changes
|
||
|
||
### Backend Changes
|
||
|
||
| Priority | Change | Files | Effort |
|
||
|----------|--------|-------|--------|
|
||
| P0 | Create unified status enums | `common/status_enums.py` (NEW) | 2h |
|
||
| P0 | Add migrations for generation_status | 4 migration files | 4h |
|
||
| P0 | Enhance ProgressTracker with details | `ai/tracker.py` | 3h |
|
||
| P0 | Update AI function messages | 5 AI function files | 8h |
|
||
| P1 | Return structured completion data | All AI functions | 4h |
|
||
|
||
**Total Backend Effort:** ~21 hours
|
||
|
||
---
|
||
|
||
### Frontend Changes
|
||
|
||
| Priority | Change | Files | Effort |
|
||
|----------|--------|-------|--------|
|
||
| P0 | Simplify useProgressModal | `hooks/useProgressModal.ts` | 4h |
|
||
| P0 | Simplify ProgressModal | `components/common/ProgressModal.tsx` | 3h |
|
||
| P0 | Create StepBanner | `components/workflow/StepBanner.tsx` (NEW) | 4h |
|
||
| P0 | Create HelperNotification | `components/helper/HelperNotification.tsx` (NEW) | 4h |
|
||
| P1 | Create MetricsPanel | `components/dashboard/MetricsPanel.tsx` (NEW) | 6h |
|
||
| P1 | Create Breadcrumbs | `components/navigation/Breadcrumbs.tsx` (NEW) | 3h |
|
||
| P2 | Create InlineGuidance | `components/helper/InlineGuidance.tsx` (NEW) | 2h |
|
||
| P2 | Enhance Tooltip | `components/ui/tooltip/Tooltip.tsx` | 3h |
|
||
| P0 | Fix Automation stage progress | `pages/Automation/AutomationPage.tsx` | 8h |
|
||
| P0 | Update Keywords page | `pages/Planner/Keywords.tsx` | 4h |
|
||
| P0 | Update Clusters page | `pages/Planner/Clusters.tsx` | 3h |
|
||
| P0 | Update Ideas page | `pages/Planner/Ideas.tsx` | 3h |
|
||
| P0 | Update Tasks page | `pages/Writer/Tasks.tsx` | 4h |
|
||
| P0 | Update Content page | `pages/Writer/Content.tsx` | 3h |
|
||
| P0 | Update Images page | `pages/Writer/Images.tsx` | 3h |
|
||
|
||
**Total Frontend Effort:** ~57 hours
|
||
|
||
---
|
||
|
||
### Total Project Effort
|
||
|
||
| Phase | Effort | Duration |
|
||
|-------|--------|----------|
|
||
| Backend Foundation | 21h | Week 1 |
|
||
| Frontend Refactor | 20h | Week 1-2 |
|
||
| New Components | 22h | Week 2 |
|
||
| Page Updates | 20h | Week 3 |
|
||
| Testing & QA | 15h | Week 3 |
|
||
| **TOTAL** | **98h** | **3 weeks** |
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
### Backend
|
||
- ✅ All models have proper status fields with full choices
|
||
- ✅ All AI functions emit detailed progress with item counts
|
||
- ✅ All AI functions return structured completion data
|
||
- ✅ Progress messages are specific and accurate
|
||
|
||
### Frontend
|
||
- ✅ Progress modal shows accurate counts without regex parsing
|
||
- ✅ All 5 new UX components created and working
|
||
- ✅ All Planner/Writer pages have StepBanner, Helper, Metrics
|
||
- ✅ Automation stage progress is accurate
|
||
- ✅ All tooltips working with keyboard accessibility
|
||
|
||
### UX
|
||
- ✅ Users understand current workflow step (StepBanner)
|
||
- ✅ Users get contextual help (HelperNotification)
|
||
- ✅ Users see real-time metrics (MetricsPanel)
|
||
- ✅ Progress messages are clear and accurate
|
||
- ✅ Automation progress is transparent and accurate
|
||
|
||
---
|
||
|
||
## Implementation Notes
|
||
|
||
1. **Backwards Compatibility:** New `generation_status` fields should not break existing queries
|
||
2. **Migration Strategy:** Run migrations in dev → staging → production with testing at each stage
|
||
3. **localStorage Cleanup:** Consider adding "Reset all helpers" option in settings
|
||
4. **Performance:** MetricsPanel should not cause extra API calls (use existing data)
|
||
5. **Accessibility:** All new components must support keyboard navigation
|
||
6. **Dark Mode:** All new components must have proper dark mode styles
|
||
|
||
---
|
||
|
||
**End of Audit Document**
|