296 lines
8.9 KiB
Markdown
296 lines
8.9 KiB
Markdown
# Publisher Module
|
|
|
|
**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:** `frontend/src/pages/Publisher/`
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| What | File | Key Items |
|
|
|------|------|-----------|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
The Publisher module manages:
|
|
- Content publishing pipeline
|
|
- **Publishing scheduler (automated publishing)**
|
|
- Publishing record tracking
|
|
- Deployment management
|
|
- Multi-destination publishing
|
|
- **Content calendar visualization**
|
|
|
|
---
|
|
|
|
## Data Models
|
|
|
|
### PublishingRecord
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| account | FK | Owner account |
|
|
| site | FK | Parent site |
|
|
| content | FK | Source content |
|
|
| destination | CharField | wordpress/ghost/webflow |
|
|
| external_id | CharField | ID on destination platform |
|
|
| external_url | URLField | Published URL |
|
|
| status | CharField | pending/published/failed/retracted |
|
|
| published_at | DateTime | Publication time |
|
|
| metadata | JSON | Additional data |
|
|
| created_at | DateTime | Record creation |
|
|
|
|
### DeploymentRecord
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| account | FK | Owner account |
|
|
| site | FK | Target site |
|
|
| deployment_type | CharField | full/incremental |
|
|
| status | CharField | pending/deploying/completed/failed |
|
|
| items_deployed | Integer | Number of items |
|
|
| started_at | DateTime | Start time |
|
|
| completed_at | DateTime | Completion time |
|
|
| 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
|
|
|
|
| Method | Path | Handler | Purpose |
|
|
|--------|------|---------|---------|
|
|
| GET | `/api/v1/publisher/records/` | `PublishingRecordViewSet.list` | List publishing records |
|
|
| POST | `/api/v1/publisher/records/` | `PublishingRecordViewSet.create` | Create record |
|
|
| GET | `/api/v1/publisher/deployments/` | `DeploymentViewSet.list` | List deployments |
|
|
| 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
|
|
|
|
---
|
|
|
|
## Publishing Flow
|
|
|
|
### Single Content Publish
|
|
|
|
**Trigger:** User clicks "Publish" or API call
|
|
**Flow:**
|
|
1. Validate content is in publishable state
|
|
2. Get site integration credentials
|
|
3. Transform content for destination:
|
|
- Format HTML for platform
|
|
- Process images
|
|
- Map taxonomies
|
|
4. Push to destination API
|
|
5. Create `PublishingRecord` with external ID
|
|
6. Update Content status to `published`
|
|
|
|
### Batch Deployment
|
|
|
|
**Trigger:** Deployment action
|
|
**Flow:**
|
|
1. Create `DeploymentRecord`
|
|
2. Gather all pending content
|
|
3. Process each item:
|
|
- Publish to destination
|
|
- Create publishing record
|
|
- Update content status
|
|
4. Update deployment status
|
|
5. Log any errors
|
|
|
|
---
|
|
|
|
## Destination Adapters
|
|
|
|
### WordPress Adapter
|
|
|
|
- Uses WordPress REST API
|
|
- Supports posts, pages, custom post types
|
|
- Handles media upload
|
|
- Maps categories/tags
|
|
|
|
### Ghost Adapter (Planned)
|
|
|
|
- Ghost Admin API integration
|
|
- Post publishing
|
|
- Image handling
|
|
|
|
### Webflow Adapter (Planned)
|
|
|
|
- Webflow CMS API
|
|
- Collection item publishing
|
|
- Asset management
|
|
|
|
---
|
|
|
|
## Publishing States
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| pending | Ready to publish |
|
|
| published | Successfully published |
|
|
| failed | Publishing failed |
|
|
| retracted | Unpublished/removed |
|
|
|
|
---
|
|
|
|
## Site Definition Endpoint
|
|
|
|
**Purpose:** Public endpoint for headless CMS use cases
|
|
|
|
Returns site structure for external consumption:
|
|
- Site metadata
|
|
- Available taxonomies
|
|
- Content types
|
|
- URL structure
|
|
|
|
---
|
|
|
|
## Integration Points
|
|
|
|
| From | To | Trigger |
|
|
|------|----|---------|
|
|
| Writer | Publisher | Publish action |
|
|
| Automation Stage 7 | Publisher | Auto-publish (future) |
|
|
| Publisher | Integrations | Destination APIs |
|
|
| Publisher | Content | Status updates |
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
| Issue | Cause | Fix |
|
|
|-------|-------|-----|
|
|
| Publish failed | Invalid credentials | Check integration settings |
|
|
| Duplicate posts | Published twice | Check existing publishing record |
|
|
| Images missing | Upload failed | Check media library access |
|
|
| Wrong category | Mapping issue | Verify taxonomy sync |
|
|
|
|
---
|
|
|
|
## Planned Changes
|
|
|
|
| Feature | Status | Description |
|
|
|---------|--------|-------------|
|
|
| Ghost integration | 🔜 Planned | Ghost CMS publishing |
|
|
| Webflow integration | 🔜 Planned | Webflow publishing |
|
|
| ~~Scheduled publishing~~ | ✅ Implemented (v1.3.2) | Future-date publishing |
|
|
| Republish detection | 🔜 Planned | Detect and handle updates |
|
|
| ~~Publishing queue~~ | ✅ Implemented (v1.3.2) | Batch publishing with queue |
|
|
| Drag-and-drop calendar | 🔜 Planned | Reschedule via drag-and-drop |
|