stage 4-1
This commit is contained in:
alorig
354
refactor-plan/STAGE4_IMPLEMENTATION_PLAN.md
Normal file
354
refactor-plan/STAGE4_IMPLEMENTATION_PLAN.md
Normal file
@@ -0,0 +1,354 @@
|
||||
# Stage 4 Implementation Plan - Publishing & Sync Integration
|
||||
|
||||
**Status:** Planning Phase
|
||||
**Last Updated:** 2025-01-27
|
||||
**Objective:** Achieve feature parity between IGNY8-hosted deployments and WordPress sites using the shared metadata model from Stages 1-3.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Codebase Audit Summary
|
||||
|
||||
### ✅ Existing Infrastructure (No Changes Needed)
|
||||
|
||||
#### Backend Models
|
||||
- ✅ `SiteIntegration` model exists with WordPress support
|
||||
- Location: `backend/igny8_core/business/integration/models.py`
|
||||
- Fields: `platform`, `credentials_json`, `sync_enabled`, `last_sync_at`, `sync_status`, `sync_error`
|
||||
- Supports: WordPress, Shopify, Custom API
|
||||
|
||||
- ✅ `SiteBlueprintTaxonomy` model (from Stage 1)
|
||||
- Location: `backend/igny8_core/business/site_building/models.py`
|
||||
- Has `external_reference` field for WordPress taxonomy IDs
|
||||
|
||||
- ✅ `ContentClusterMap`, `ContentTaxonomyMap`, `ContentAttributeMap` (from Stage 1)
|
||||
- Location: `backend/igny8_core/business/content/models.py`
|
||||
- Support metadata mapping for sync
|
||||
|
||||
#### Backend Services
|
||||
- ✅ `WordPressAdapter` - Basic publishing to WordPress
|
||||
- Location: `backend/igny8_core/business/publishing/services/adapters/wordpress_adapter.py`
|
||||
- Methods: `publish()`, `test_connection()`, `get_status()`
|
||||
- **Status:** Works for posts, needs taxonomy/product support
|
||||
|
||||
- ✅ `ContentSyncService` - Sync service skeleton
|
||||
- Location: `backend/igny8_core/business/integration/services/content_sync_service.py`
|
||||
- Methods: `sync_to_external()`, `sync_from_external()`
|
||||
- **Status:** WordPress sync methods exist but are incomplete (TODOs)
|
||||
|
||||
- ✅ `TaxonomyService` - Taxonomy CRUD (from Stage 1)
|
||||
- Location: `backend/igny8_core/business/site_building/services/taxonomy_service.py`
|
||||
- Method: `import_from_external()` - Ready for WordPress import
|
||||
|
||||
- ✅ `SitesRendererAdapter` - IGNY8 deployment
|
||||
- Location: `backend/igny8_core/business/publishing/services/adapters/sites_renderer_adapter.py`
|
||||
- **Status:** Works, needs Stage 3 metadata integration
|
||||
|
||||
- ✅ `WordPressClient` - WordPress REST API client
|
||||
- Location: `backend/igny8_core/utils/wordpress.py`
|
||||
- Methods: `test_connection()`, `create_post()`
|
||||
- **Status:** Basic functionality, needs taxonomy/product endpoints
|
||||
|
||||
#### Backend APIs
|
||||
- ✅ Integration endpoints exist
|
||||
- Location: `backend/igny8_core/modules/integration/views.py`
|
||||
- Endpoints: `/api/v1/integration/integrations/{id}/sync/`, `/api/v1/integration/integrations/{id}/sync_status/`
|
||||
- **Status:** Basic sync endpoints exist, need Stage 4 enhancements
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Implementation Tasks
|
||||
|
||||
### Phase 1: Backend - WordPress Taxonomy & Product Sync
|
||||
|
||||
#### Task 1.1: Enhance WordPressClient
|
||||
**File:** `backend/igny8_core/utils/wordpress.py`
|
||||
|
||||
**Add Methods:**
|
||||
```python
|
||||
def get_categories(self) -> List[Dict[str, Any]]
|
||||
def create_category(self, name: str, slug: str, parent_id: Optional[int] = None) -> Dict[str, Any]
|
||||
def get_tags(self) -> List[Dict[str, Any]]
|
||||
def create_tag(self, name: str, slug: str) -> Dict[str, Any]
|
||||
def get_products(self) -> List[Dict[str, Any]] # WooCommerce
|
||||
def create_product(self, product_data: Dict[str, Any]) -> Dict[str, Any]
|
||||
def get_product_attributes(self) -> List[Dict[str, Any]] # WooCommerce
|
||||
```
|
||||
|
||||
**Breaking Changes:** None - All new methods
|
||||
|
||||
#### Task 1.2: Enhance ContentSyncService for Taxonomies
|
||||
**File:** `backend/igny8_core/business/integration/services/content_sync_service.py`
|
||||
|
||||
**Enhance `_sync_from_wordpress()`:**
|
||||
- Fetch WordPress categories/tags via WordPressClient
|
||||
- Map to IGNY8 `SiteBlueprintTaxonomy` using `TaxonomyService.import_from_external()`
|
||||
- Store `external_reference` (WP taxonomy ID) in `SiteBlueprintTaxonomy.external_reference`
|
||||
- Auto-create missing clusters with `imported=True` flag
|
||||
|
||||
**Enhance `_sync_to_wordpress()`:**
|
||||
- Ensure taxonomies exist in WordPress before publishing content
|
||||
- Create missing categories/tags via WordPressClient
|
||||
- Update `external_reference` after creation
|
||||
- Push product attributes/tags before product content
|
||||
|
||||
**Breaking Changes:** None - Enhances existing methods
|
||||
|
||||
#### Task 1.3: Add Sync Health Service
|
||||
**New File:** `backend/igny8_core/business/integration/services/sync_health_service.py`
|
||||
|
||||
**Purpose:** Track sync health, mismatches, errors
|
||||
|
||||
**Methods:**
|
||||
```python
|
||||
class SyncHealthService:
|
||||
def get_sync_status(site_id: int, integration_id: Optional[int] = None) -> Dict[str, Any]
|
||||
def get_mismatches(site_id: int) -> Dict[str, Any]
|
||||
def get_sync_logs(site_id: int, limit: int = 100) -> List[Dict[str, Any]]
|
||||
def record_sync_run(integration_id: int, result: Dict[str, Any]) -> None
|
||||
```
|
||||
|
||||
**Breaking Changes:** None - New service
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Backend - Deployment Readiness
|
||||
|
||||
#### Task 2.1: Create Deployment Readiness Service
|
||||
**New File:** `backend/igny8_core/business/publishing/services/deployment_readiness_service.py`
|
||||
|
||||
**Purpose:** Check if site is ready for deployment
|
||||
|
||||
**Methods:**
|
||||
```python
|
||||
class DeploymentReadinessService:
|
||||
def check_readiness(site_blueprint_id: int) -> Dict[str, Any]
|
||||
# Returns:
|
||||
# {
|
||||
# 'ready': bool,
|
||||
# 'checks': {
|
||||
# 'cluster_coverage': bool,
|
||||
# 'content_validation': bool,
|
||||
# 'sync_status': bool,
|
||||
# 'taxonomy_completeness': bool
|
||||
# },
|
||||
# 'errors': List[str],
|
||||
# 'warnings': List[str]
|
||||
# }
|
||||
```
|
||||
|
||||
**Breaking Changes:** None - New service
|
||||
|
||||
#### Task 2.2: Enhance SitesRendererAdapter with Stage 3 Metadata
|
||||
**File:** `backend/igny8_core/business/publishing/services/adapters/sites_renderer_adapter.py`
|
||||
|
||||
**Enhance `_build_site_definition()`:**
|
||||
- Include cluster metadata in navigation
|
||||
- Include taxonomy metadata for breadcrumbs
|
||||
- Include internal links from `ContentClusterMap`
|
||||
|
||||
**Breaking Changes:** None - Adds optional metadata fields
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Backend - API Endpoints
|
||||
|
||||
#### Task 3.1: Add Sync Health Endpoints
|
||||
**File:** `backend/igny8_core/modules/integration/views.py`
|
||||
|
||||
**Add to IntegrationViewSet:**
|
||||
```python
|
||||
@action(detail=False, methods=['get'], url_path='sites/(?P<site_id>[^/.]+)/sync/status')
|
||||
def sync_status_by_site(self, request, site_id=None):
|
||||
"""GET /api/v1/integration/integrations/sites/{site_id}/sync/status/"""
|
||||
|
||||
@action(detail=False, methods=['post'], url_path='sites/(?P<site_id>[^/.]+)/sync/run')
|
||||
def run_sync(self, request, site_id=None):
|
||||
"""POST /api/v1/integration/integrations/sites/{site_id}/sync/run/"""
|
||||
```
|
||||
|
||||
**Breaking Changes:** None - New endpoints
|
||||
|
||||
#### Task 3.2: Add Deployment Readiness Endpoint
|
||||
**File:** `backend/igny8_core/modules/publisher/views.py` (or create new)
|
||||
|
||||
**New Endpoint:**
|
||||
```python
|
||||
@api_view(['GET'])
|
||||
def deployment_readiness(request, blueprint_id):
|
||||
"""GET /api/v1/publisher/blueprints/{blueprint_id}/readiness/"""
|
||||
```
|
||||
|
||||
**Breaking Changes:** None - New endpoint
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Frontend - Sync Dashboard
|
||||
|
||||
#### Task 4.1: Create Sync Dashboard Component
|
||||
**New File:** `frontend/src/pages/Sites/SyncDashboard.tsx`
|
||||
|
||||
**Features:**
|
||||
- Parity indicators (taxonomies, products, posts)
|
||||
- Manual sync button
|
||||
- Retry failed items
|
||||
- View logs with pagination
|
||||
- Detail drawer for mismatches
|
||||
|
||||
**API Integration:**
|
||||
- `GET /api/v1/integration/integrations/sites/{site_id}/sync/status/`
|
||||
- `POST /api/v1/integration/integrations/sites/{site_id}/sync/run/`
|
||||
|
||||
**Breaking Changes:** None - New page
|
||||
|
||||
#### Task 4.2: Add Sync Status to Site Dashboard
|
||||
**File:** `frontend/src/pages/Sites/Dashboard.tsx`
|
||||
|
||||
**Enhancement:**
|
||||
- Add sync status widget
|
||||
- Show last sync time
|
||||
- Show sync errors if any
|
||||
|
||||
**Breaking Changes:** None - Adds optional widget
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Frontend - Deployment Panel
|
||||
|
||||
#### Task 5.1: Create Deployment Panel Component
|
||||
**New File:** `frontend/src/components/sites/DeploymentPanel.tsx`
|
||||
|
||||
**Features:**
|
||||
- Readiness checklist
|
||||
- Deploy button (disabled if not ready)
|
||||
- Rollback button
|
||||
- Confirmation modals
|
||||
- Toast notifications
|
||||
|
||||
**API Integration:**
|
||||
- `GET /api/v1/publisher/blueprints/{blueprint_id}/readiness/`
|
||||
- `POST /api/v1/publisher/deploy/{blueprint_id}/` (existing)
|
||||
- `POST /api/v1/publisher/rollback/{deployment_id}/` (new)
|
||||
|
||||
**Breaking Changes:** None - New component
|
||||
|
||||
#### Task 5.2: Integrate Deployment Panel
|
||||
**File:** `frontend/src/pages/Sites/Dashboard.tsx`
|
||||
|
||||
**Enhancement:**
|
||||
- Add deployment panel section
|
||||
- Show readiness status
|
||||
- Link to deployment history
|
||||
|
||||
**Breaking Changes:** None - Adds optional section
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Frontend - WordPress Connection UI
|
||||
|
||||
#### Task 6.1: Enhance Integration Settings UI
|
||||
**File:** `frontend/src/pages/Settings/Integrations.tsx` (or create new)
|
||||
|
||||
**Features:**
|
||||
- Show WordPress integration status
|
||||
- Credential health check
|
||||
- Last sync time
|
||||
- Active site type detection
|
||||
- Troubleshooting helper text
|
||||
- Links to docs/runbook
|
||||
|
||||
**API Integration:**
|
||||
- `GET /api/v1/integration/integrations/{id}/sync_status/` (existing)
|
||||
- `POST /api/v1/integration/integrations/{id}/test_connection/` (existing)
|
||||
|
||||
**Breaking Changes:** None - Enhances existing UI
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Backward Compatibility Guarantees
|
||||
|
||||
### No Breaking Changes Policy
|
||||
|
||||
1. **All new endpoints are additive** - No existing endpoints modified
|
||||
2. **All new methods are optional** - Existing code continues to work
|
||||
3. **Database changes are additive** - New fields are nullable
|
||||
4. **Service enhancements are backward compatible** - Old behavior preserved
|
||||
|
||||
### Migration Strategy
|
||||
|
||||
1. **Feature Flag:** `USE_STAGE4_SYNC` (default: `False`)
|
||||
2. **Gradual Rollout:** Enable per site/integration
|
||||
3. **Fallback:** If Stage 4 features fail, fall back to existing behavior
|
||||
|
||||
---
|
||||
|
||||
## 📊 Implementation Checklist
|
||||
|
||||
### Backend
|
||||
- [ ] Task 1.1: Enhance WordPressClient with taxonomy/product methods
|
||||
- [ ] Task 1.2: Enhance ContentSyncService for taxonomies
|
||||
- [ ] Task 1.3: Create SyncHealthService
|
||||
- [ ] Task 2.1: Create DeploymentReadinessService
|
||||
- [ ] Task 2.2: Enhance SitesRendererAdapter with Stage 3 metadata
|
||||
- [ ] Task 3.1: Add sync health endpoints
|
||||
- [ ] Task 3.2: Add deployment readiness endpoint
|
||||
|
||||
### Frontend
|
||||
- [ ] Task 4.1: Create Sync Dashboard component
|
||||
- [ ] Task 4.2: Add sync status to Site Dashboard
|
||||
- [ ] Task 5.1: Create Deployment Panel component
|
||||
- [ ] Task 5.2: Integrate Deployment Panel
|
||||
- [ ] Task 6.1: Enhance WordPress Connection UI
|
||||
|
||||
### Testing
|
||||
- [ ] Unit tests for new services
|
||||
- [ ] Integration tests for sync flows
|
||||
- [ ] E2E tests for deployment panel
|
||||
- [ ] Manual testing with live WordPress instance
|
||||
|
||||
### Documentation
|
||||
- [ ] Update API documentation
|
||||
- [ ] Create operational runbooks
|
||||
- [ ] Update user documentation
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Risk Mitigation
|
||||
|
||||
### Risk 1: WordPress API Rate Limits
|
||||
**Mitigation:**
|
||||
- Implement backoff + batching in WordPressClient
|
||||
- Show rate limit status in dashboard
|
||||
- Queue sync operations
|
||||
|
||||
### Risk 2: Data Mismatches
|
||||
**Mitigation:**
|
||||
- Detailed diff view in dashboard
|
||||
- Retry actions for failed items
|
||||
- Documented runbook for manual fixes
|
||||
|
||||
### Risk 3: Deployment Failures
|
||||
**Mitigation:**
|
||||
- Preflight checks before deploy
|
||||
- Rollback button with confirmation
|
||||
- Structured logs for debugging
|
||||
|
||||
### Risk 4: Breaking Existing Functionality
|
||||
**Mitigation:**
|
||||
- Feature flag protection
|
||||
- Comprehensive testing
|
||||
- Gradual rollout plan
|
||||
|
||||
---
|
||||
|
||||
## 📝 Next Steps
|
||||
|
||||
1. **Review this plan** with team
|
||||
2. **Create feature branch:** `feature/stage4-sync-integration`
|
||||
3. **Start with Phase 1** (Backend WordPress sync)
|
||||
4. **Test incrementally** after each phase
|
||||
5. **Document as you go** - Update this plan with progress
|
||||
|
||||
---
|
||||
|
||||
*This plan ensures Stage 4 implementation without breaking existing functionality.*
|
||||
|
||||
Reference in New Issue
Block a user