docs re-org

docs/20-API/WRITER-ENDPOINTS.md

@@ -0,0 +1,68 @@
+# Writer Endpoints
+
+## Purpose
+Document writer API endpoints for tasks, content, images, and taxonomies, including bulk actions and AI content generation triggers.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/writer/urls.py`
+- Views: `backend/igny8_core/modules/writer/views.py`
+- Serializers: `backend/igny8_core/modules/writer/serializers.py`
+- Services: `backend/igny8_core/business/content/services/content_generation_service.py`
+
+## High-Level Responsibilities
+- CRUD for writer entities scoped by account/site/sector.
+- Provide bulk operations and AI content generation for tasks.
+- Manage images and taxonomy terms linked to content/tasks.
+
+## Detailed Behavior
+- Base path: `/api/v1/writer/`
+- Viewsets (inherit `SiteSectorModelViewSet`, throttled `writer`, paginated):
+  - `TasksViewSet` (`/tasks/`):
+    - Filters: status, cluster_id, content_type, content_structure; search title/keywords; ordering by title/created_at/status.
+    - Bulk: `bulk_delete`, `bulk_update` (status).
+    - `auto_generate_content`: accepts task IDs (max 10), requires account, enforces credit checks via `ContentGenerationService`, returns async task_id or synchronous result; 402 on insufficient credits.
+    - Create requires site_id/sector_id; validates site/sector alignment; sets account/site/sector explicitly.
+  - `ImagesViewSet` (`/images/`):
+    - Filters: task_id, content_id, image_type, status; ordering by created_at/position/id.
+    - perform_create enforces site/sector presence (from request or defaults), sets account/site/sector; serves local files via `file` action with existence checks.
+  - `ContentViewSet` (`/content/`):
+    - Filters/order/search defined in viewset (titles, status, etc.); manages taxonomy relationships; exposes status, SEO fields, cluster link, external IDs/URLs.
+  - `ContentTaxonomyViewSet` (`/taxonomies/`):
+    - CRUD for taxonomy terms (category/tag) scoped to site/sector.
+- Serializers enforce required fields on create (e.g., cluster/content_type/content_structure for tasks; site/sector for content) and expose read-only derived fields (cluster/sector names, image/taxonomy info).
+- Error handling: unified responses; validation errors return 400; missing resources return 404; `auto_generate_content` can return 402/500 on credits/other errors.
+
+## Data Structures / Models Involved (no code)
+- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, and related domain models; `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filtering (account/site/sector) → serializer validation → model save → unified response; bulk/AI actions invoke services.
+
+## Cross-Module Interactions
+- Planner clusters/ideas feed tasks; automation stages 3–6 operate on writer data; publishing/integration uses content/taxonomies/images.
+- Billing credits enforced during AI content generation via `ContentGenerationService`.
+
+## State Transitions
+- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`.
+
+## Error Handling
+- Standard unified responses; credit errors mapped to 402 in `auto_generate_content`; file serving returns 404 for missing images.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector; base viewset and permissions enforce access; admin/developer/system may bypass filtering but records retain tenant/site/sector fields.
+
+## Billing Rules
+- AI generation actions check/deduct credits via billing services; other CRUD does not alter credits.
+
+## Background Tasks / Schedulers
+- `auto_generate_content` may enqueue Celery AI tasks when returning task_id; automation uses writer endpoints indirectly via services.
+
+## Key Design Considerations
+- Strict site/sector validation on create; max 10 tasks per auto_generate_content to manage load/credits.
+- Image file serving is permissive but guarded by existence checks.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes.
+- When extending AI flows, keep credit checks and account/site scoping intact.
+- Reuse existing viewsets/serializers for new fields; ensure filters/throttles stay aligned with module scope.
+