# 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.