185 lines
4.9 KiB
Markdown
185 lines
4.9 KiB
Markdown
# Publisher Module
|
|
|
|
**Last Verified:** December 25, 2025
|
|
**Status:** ✅ Active
|
|
**Backend Path:** `backend/igny8_core/modules/publisher/` + `backend/igny8_core/business/publishing/`
|
|
**Frontend Path:** N/A (API-only module)
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| What | File | Key Items |
|
|
|------|------|-----------|
|
|
| Views | `modules/publisher/views.py` | `PublishingRecordViewSet`, `DeploymentViewSet`, `PublishContentViewSet` |
|
|
| Models | `business/publishing/models.py` | `PublishingRecord`, `DeploymentRecord` |
|
|
| Services | `business/publishing/services/*.py` | Publishing orchestration |
|
|
| URLs | `modules/publisher/urls.py` | Publisher endpoints |
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
The Publisher module manages:
|
|
- Content publishing pipeline
|
|
- Publishing record tracking
|
|
- Deployment management
|
|
- Multi-destination publishing
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
---
|
|
|
|
## 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 | 🔜 Planned | Future-date publishing |
|
|
| Republish detection | 🔜 Planned | Detect and handle updates |
|
|
| Publishing queue | 🔜 Planned | Batch publishing with queue |
|