VErsion 1.3.2

docs/10-MODULES/PUBLISHER.md

@@ -1,9 +1,10 @@
 # Publisher Module
 
-**Last Verified:** December 25, 2025  
+**Last Verified:** January 3, 2026  
 **Status:** ✅ Active  
+**Version:** 1.3.2
 **Backend Path:** `backend/igny8_core/modules/publisher/` + `backend/igny8_core/business/publishing/`  
-**Frontend Path:** N/A (API-only module)
+**Frontend Path:** `frontend/src/pages/Publisher/`
 
 ---
 
@@ -13,8 +14,11 @@
 |------|------|-----------|
 | Views | `modules/publisher/views.py` | `PublishingRecordViewSet`, `DeploymentViewSet`, `PublishContentViewSet` |
 | Models | `business/publishing/models.py` | `PublishingRecord`, `DeploymentRecord` |
+| Integration Models | `modules/integration/models.py` | `PublishingSettings` |
 | Services | `business/publishing/services/*.py` | Publishing orchestration |
+| Scheduler Tasks | `igny8_core/tasks/publishing_scheduler.py` | Celery beat tasks |
 | URLs | `modules/publisher/urls.py` | Publisher endpoints |
+| Frontend | `pages/Publisher/ContentCalendar.tsx` | Content calendar view |
 
 ---
 
@@ -22,9 +26,11 @@
 
 The Publisher module manages:
 - Content publishing pipeline
+- **Publishing scheduler (automated publishing)**
 - Publishing record tracking
 - Deployment management
 - Multi-destination publishing
+- **Content calendar visualization**
 
 ---
 
@@ -59,6 +65,31 @@ The Publisher module manages:
 | error_log | TextField | Errors encountered |
 | metadata | JSON | Deployment details |
 
+### PublishingSettings (v1.3.2)
+
+Site-level publishing configuration:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| site | OneToOne | Parent site (unique) |
+| auto_approval_enabled | Boolean | Auto-approve content |
+| auto_publish_enabled | Boolean | Auto-publish approved content |
+| daily_publish_limit | Integer | Max publications per day |
+| weekly_publish_limit | Integer | Max publications per week |
+| monthly_publish_limit | Integer | Max publications per month |
+| publish_days | JSON | Days of week for publishing ["mon","wed","fri"] |
+| publish_time_slots | JSON | Time slots for publishing [{"start":"09:00","end":"17:00"}] |
+
+### Content Site Status Fields (v1.3.2)
+
+Added to Content model for scheduling:
+
+| Field | Type | Values |
+|-------|------|--------|
+| site_status | CharField | not_published, scheduled, publishing, published, failed |
+| scheduled_publish_at | DateTime | Future publication time (nullable) |
+| site_status_updated_at | DateTime | Last status change timestamp |
+
 ---
 
 ## API Endpoints
@@ -71,6 +102,85 @@ The Publisher module manages:
 | POST | `/api/v1/publisher/publish/` | `PublishContentViewSet.publish` | Publish content |
 | GET | `/api/v1/publisher/publish/status/` | `PublishContentViewSet.status` | Get publishing status |
 | GET | `/api/v1/publisher/site-definition/` | `SiteDefinitionViewSet.list` | Public site definitions |
+| **POST** | `/api/v1/content/{id}/schedule/` | Schedule content | Schedule content for future publish |
+| **POST** | `/api/v1/content/{id}/unschedule/` | Unschedule content | Remove from publishing schedule |
+| **GET** | `/api/v1/sites/{site_id}/publishing-settings/` | `PublishingSettingsViewSet` | Get site publishing settings |
+| **PUT** | `/api/v1/sites/{site_id}/publishing-settings/` | `PublishingSettingsViewSet` | Update publishing settings |
+
+---
+
+## Publishing Scheduler (v1.3.2)
+
+### Celery Beat Tasks
+
+Located in `igny8_core/tasks/publishing_scheduler.py`:
+
+| Task | Schedule | Purpose |
+|------|----------|---------|
+| `schedule_approved_content` | Every 15 minutes | Assigns publish times to approved content |
+| `process_scheduled_publications` | Every 5 minutes | Publishes content when scheduled time arrives |
+| `cleanup_failed_publications` | Daily at midnight | Retries or cleans up failed publications |
+
+### Scheduling Flow
+
+```
+Approved Content → schedule_approved_content (every 15 min)
+                        ↓
+            Check PublishingSettings
+                        ↓
+            Assign scheduled_publish_at based on:
+            - publish_days configuration
+            - publish_time_slots configuration  
+            - daily/weekly/monthly limits
+                        ↓
+            Set site_status = "scheduled"
+                        ↓
+process_scheduled_publications (every 5 min)
+                        ↓
+            If scheduled_publish_at <= now:
+            - Set site_status = "publishing"
+            - Execute publication
+            - Set site_status = "published" or "failed"
+```
+
+### Site Status State Machine
+
+```
+not_published → scheduled → publishing → published
+                    ↓              ↓
+                    ↓         → failed
+                    ↓
+              not_published (if unscheduled)
+```
+
+---
+
+## Frontend Pages (v1.3.2)
+
+### Content Calendar (`/publisher/content-calendar`)
+
+**Purpose:** Visualize and manage scheduled content
+
+**Features:**
+- Calendar view of scheduled publications
+- List view alternative
+- Filter by site
+- Schedule/unschedule actions
+- Drag-and-drop rescheduling (planned)
+
+**Components:**
+- `ContentCalendar.tsx` - Main page component
+- `CalendarItemTooltip` - Hover details for calendar items
+- `SiteInfoBar` - Site context header
+
+### Publishing Queue (`/publisher/publishing-queue`)
+
+**Purpose:** Review upcoming publications
+
+**Features:**
+- List of content pending publication
+- Status indicators (scheduled, publishing, failed)
+- Publish now / unschedule actions
 
 ---
 
@@ -179,6 +289,7 @@ Returns site structure for external consumption:
 |---------|--------|-------------|
 | Ghost integration | 🔜 Planned | Ghost CMS publishing |
 | Webflow integration | 🔜 Planned | Webflow publishing |
-| Scheduled publishing | 🔜 Planned | Future-date publishing |
+| ~~Scheduled publishing~~ | ✅ Implemented (v1.3.2) | Future-date publishing |
 | Republish detection | 🔜 Planned | Detect and handle updates |
-| Publishing queue | 🔜 Planned | Batch publishing with queue |
+| ~~Publishing queue~~ | ✅ Implemented (v1.3.2) | Batch publishing with queue |
+| Drag-and-drop calendar | 🔜 Planned | Reschedule via drag-and-drop |