revamps docs complete

master-docs/20-api/ENDPOINTS/sites.md

@@ -0,0 +1,71 @@
+# Site Endpoints
+
+## Purpose
+Document site management endpoints under the auth module, including creation, listing, sector selection, and activation.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/auth/urls.py`
+- Views: `backend/igny8_core/auth/views.py` (`SiteViewSet`)
+- Serializers: `backend/igny8_core/auth/serializers.py` (`SiteSerializer`, `SectorSerializer`)
+
+## High-Level Responsibilities
+- CRUD for sites scoped to an account, with role-based access.
+- Allow public read by slug for active sites (renderer support).
+- Manage sector selection and activation per site.
+
+## Detailed Behavior
+- Base path: `/api/v1/auth/sites/`
+- Permissions:
+  - `list` with slug filter: `AllowAny` (public read by slug, active sites only).
+  - `create`: authenticated users (viewer+); sets site account from request/user.
+  - Other actions: `IsEditorOrAbove` with tenant access.
+- Queryset logic:
+  - Unauthenticated with `slug` query param: returns active site by slug.
+  - Authenticated admin/developer: all sites.
+  - Authenticated owner/admin: sites for user’s account.
+  - Other users: sites where they have `SiteUserAccess`.
+- Actions:
+  - `GET /sites/` list (with filters above).
+  - `POST /sites/` create site; account set from request/user.
+  - `GET /sites/{id}/sectors/` list active sectors for the site.
+  - `POST /sites/{id}/set_active/` marks site active (no deactivation of others).
+  - `POST /sites/{id}/select_sectors/` sets industry and sectors:
+    - Requires `industry_slug`; optional `sector_slugs` list.
+    - Validates industry exists/active; enforces plan sector limit (`get_max_sectors_limit`).
+    - Deactivates sectors not in provided list; ensures sectors belong to industry; creates missing site sectors as needed; returns site + sectors.
+- Create/update:
+  - `perform_create` sets account; no single-active constraint.
+  - `perform_update` retains account; no single-active constraint.
+
+## Data Structures / Models Involved (no code)
+- `Site`, `Sector`, `Industry`, `IndustrySector`, `Plan` (for sector limits), `SiteUserAccess`, `Account`.
+
+## Execution Flow
+- Requests → DRF auth (JWT/session) → permissions → queryset scoping → serializer validation → model ops → unified response. Public slug reads bypass account filtering.
+
+## Cross-Module Interactions
+- Sites link to planner/writer records via site/sector; integration uses `Site.wp_api_key`; plan sector limits referenced here.
+
+## State Transitions
+- Site activation via `set_active`; sector activation/deactivation via `select_sectors`; industry assignment updated on selection.
+
+## Error Handling
+- 400 for missing industry slug or exceeding sector limits; 404 for missing site/industry; 500 if site lacks account when selecting sectors.
+
+## Tenancy Rules
+- Account-scoped except public slug read; role-based overrides for admins/developers; SiteUserAccess governs non-admin access.
+
+## Billing Rules
+- Sector limit enforced from plan (`max_industries` via `get_max_sectors_limit`).
+
+## Background Tasks / Schedulers
+- None in site endpoints.
+
+## Key Design Considerations
+- Public slug access supports site renderer without auth.
+- Sector selection enforces industry/plan constraints and deactivates unselected sectors.
+
+## How Developers Should Work With This Module
+- Use `select_sectors` to set industry/sector with plan-aware limits.
+- When extending site data, keep public slug path safe and scoped to active sites; maintain role-based access controls.
+