# Refactoring Plan: API CRUD V3

**Goal:** Modularize `app/routers/api_crud_v3.py` to improve maintainability, readability, and reusability. The file currently mixes route definitions, security enforcement, data sanitization, and helper utilities.

## Phase 1: Extract Helpers & Core Logic (Safest) - COMPLETED
**Objective:** Move pure functions and business logic out of the router file.

1.  **Create `app/lib_api_crud_v3.py`**: DONE
2.  **Update `app/routers/api_crud_v3.py`**: DONE (All endpoints now use `sanitize_payload`).

## Phase 2: Separate Child/Nested Routes - COMPLETED
**Objective:** Reduce file size by splitting standard CRUD from relational CRUD.

1.  **Create `app/routers/api_crud_v3_nested.py`**: DONE
2.  **Update `app/routers/api_crud_v3.py`**: DONE (Included via `router.include_router`)

## Phase 3: Schema Introspection - COMPLETED
**Objective:** Isolate database introspection logic.

1.  **Create `app/lib_schema_v3.py`**: DONE
2.  **Update `app/routers/api_crud_v3.py`**: DONE

## Refactoring Summary
The V3 CRUD system is now modularized into:
- `app/routers/api_crud_v3.py`: Top-level object routes.
- `app/routers/api_crud_v3_nested.py`: Relational/child object routes.
- `app/lib_api_crud_v3.py`: Shared security, filtering, and sanitization logic.
- `app/lib_schema_v3.py`: Database and model introspection logic.

## New DX Features

### 1. Error Bubbling
Database and Validation errors are no longer swallowed. 
- **Validation Errors**: Specific Pydantic validation failures are returned in `meta.details`.
- **Database Errors**: MariaDB constraint violations (e.g., Duplicate Entry, Not Null) are captured and cleaned up via `format_db_error()` and returned in `meta.details`.

### 2. Validation Endpoint
**Route**: `POST /v3/crud/{obj_type}/validate`
- **Purpose**: Dry-run validation of a payload against the Pydantic model.
- **Behavior**: Returns `data: true` if valid, or a 400 error with specific details if invalid. No database operations are performed.