backend-mcp/docs/modules/crud.md

Generador automático de backends con Node.js, Express, Prisma y módulos configurables. Servidor MCP compatible con npx para agentes IA. Soporta PostgreSQL, MySQL, MongoDB y SQLite.

# 📦 Módulo crud

**Versión:** 1.0.0  
**Categoría:** core  
**Descripción:** Módulo CRUD genérico para operaciones de base de datos

## 📊 Estado del Módulo

| Componente | Estado |
|------------|--------|
| Script de inicialización | ✅ Disponible |
| Templates | ✅ Disponible |
| Ejemplos | ❌ Faltante |

## 🔗 Dependencias

### Requeridas
- `database`

### Opcionales
- `auth`
- `logging`
- `cache`
- `validation`

## ✨ Características

- CRUD operations (Create, Read, Update, Delete)
- Pagination and filtering
- Sorting and searching
- Soft delete support
- Audit logging
- Input validation
- Error handling
- Swagger documentation
- Generic controllers
- DTO transformations
- Query optimization
- Bulk operations

## 📖 Documentación Completa

# CRUD Module

Generic CRUD operations generator for MCP Backend framework.

## Features

- ✅ Automatic CRUD endpoint generation
- ✅ Database-agnostic operations
- ✅ Built-in validation and sanitization
- ✅ Pagination and filtering
- ✅ Sorting and searching
- ✅ Soft delete support
- ✅ Bulk operations
- ✅ Relationship handling
- ✅ Custom field transformations
- ✅ Audit logging

## Installation

This module is automatically installed when using the MCP Backend Generator.

## Configuration

### Environment Variables

- `CRUD_ENABLED` (optional) - Enable/disable CRUD module (default: true)
- `CRUD_DEFAULT_PAGE_SIZE` (optional) - Default pagination size (default: 20)
- `CRUD_MAX_PAGE_SIZE` (optional) - Maximum pagination size (default: 100)
- `CRUD_SOFT_DELETE` (optional) - Enable soft delete by default (default: true)
- `CRUD_AUDIT_ENABLED` (optional) - Enable audit logging (default: true)

### Configuration File

```typescript
// src/config/crud.ts
export const crudConfig = {
  enabled: process.env.CRUD_ENABLED !== 'false',
  defaultPageSize: parseInt(process.env.CRUD_DEFAULT_PAGE_SIZE || '20'),
  maxPageSize: parseInt(process.env.CRUD_MAX_PAGE_SIZE || '100'),
  softDelete: process.env.CRUD_SOFT_DELETE !== 'false',
  auditEnabled: process.env.CRUD_AUDIT_ENABLED !== 'false'
};
```

## Usage

### Basic CRUD Service

```typescript
import { CrudService } from './services/crud';
import { User } from './types/user';

// Create CRUD service for User model
const userCrudService = new CrudService<User>({
  model: 'user',
  tableName: 'users',
  primaryKey: 'id',
  softDelete: true,
  searchFields: ['name', 'email'],
  sortableFields: ['name', 'email', 'createdAt'],
  filterableFields: ['role', 'status']
});

// Create
const user = await userCrudService.create({
  name: 'John Doe',
  email: 'john@example.com',
  role: 'user'
});

// Read
const users = await userCrudService.findMany({
  page: 1,
  limit: 20,
  search: 'john',
  filters: { role: 'user' },
  sort: { field: 'createdAt', order: 'desc' }
});

// Update
const updatedUser = await userCrudService.update('user_id', {
  name: 'John Smith'
});

// Delete
await userCrudService.delete('user_id');
```

### CRUD Controller Generator

```typescript
import { generateCrudController } from './controllers/crud';
import { userValidationSchema } from './schemas/user';

// Generate CRUD controller
const UserController = generateCrudController({
  service: userCrudService,
  validationSchema: userValidationSchema,
  permissions: {
    create: ['admin', 'user'],
    read: ['admin', 'user', 'guest'],
    update: ['admin', 'owner'],
    delete: ['admin']
  }
});

export const userController = new UserController();
```

### CRUD Routes Generator

```typescript
import { generateCrudRoutes } from './routes/crud';
import { authMiddleware } from './middleware/auth';

// Generate CRUD routes
const userRoutes = generateCrudRoutes({
  controller: userController,
  basePath: '/users',
  middleware: [authMiddleware],
  customRoutes: {
    'GET /profile': 'getProfile',
    'POST /change-password': 'changePassword'
  }
});

export default userRoutes;
```

## API Endpoints

The CRUD module automatically generates the following endpoints:

### GET /{resource}

Get paginated list of resources.

**Query Parameters:**
- `page` (number) - Page number (default: 1)
- `limit` (number) - Items per page (default: 20, max: 100)
- `search` (string) - Search term
- `sort` (string) - Sort field and order (e.g., "name:asc", "createdAt:desc")
- `filter[field]` (string) - Filter by field value

**Example:**
```
GET /users?page=1&limit=10&search=john&sort=createdAt:desc&filter[role]=admin
```

**Response:**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "user_id",
        "name": "John Doe",
        "email": "john@example.com",
        "role": "admin",
        "createdAt": "2023-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "pages": 1
    }
  }
}
```

### GET /{resource}/{id}

Get single resource by ID.

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin",
    "createdAt": "2023-01-01T00:00:00.000Z"
  }
}
```

### POST /{resource}

Create new resource.

**Request:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user",
    "createdAt": "2023-01-01T00:00:00.000Z"
  }
}
```

### PUT /{resource}/{id}

Update resource by ID (full update).

**Request:**
```json
{
  "name": "John Smith",
  "email": "johnsmith@example.com",
  "role": "admin"
}
```

### PATCH /{resource}/{id}

Partially update resource by ID.

**Request:**
```json
{
  "name": "John Smith"
}
```

### DELETE /{resource}/{id}

Delete resource by ID.

**Response:**
```json
{
  "success": true,
  "message": "Resource deleted successfully"
}
```

### POST /{resource}/bulk

Bulk operations.

**Create Multiple:**
```json
{
  "operation": "create",
  "data": [
    { "name": "User 1", "email": "user1@example.com" },
    { "name": "User 2", "email": "user2@example.com" }
  ]
}
```

**Update Multiple:**
```json
{
  "operation": "update",
  "ids": ["id1", "id2"],
  "data": { "status": "active" }
}
```

**Delete Multiple:**
```json
{
  "operation": "delete",
  "ids": ["id1", "id2"]
}
```

## Advanced Features

### Custom Field Transformations

```typescript
const userCrudService = new CrudService<User>({
  model: 'user',
  tableName: 'users',
  transformations: {
    input: {
      email: (value) => value.toLowerCase().trim(),
      name: (value) => value.trim()
    },
    output: {
      password: () => undefined, // Hide password field
      createdAt: (value) => new Date(value).toISOString()
    }
  }
});
```

### Relationship Handling

```typescript
const postCrudService = new CrudService<Post>({
  model: 'post',
  tableName: 'posts',
  relationships: {
    author: {
      type: 'belongsTo',
      model: 'user',
      foreignKey: 'authorId',
      include: ['name', 'email']
    },
    comments: {
      type: 'hasMany',
      model: 'comment',
      foreignKey: 'postId'
    }
  }
});
```

### Custom Validation

```typescript
import Joi from 'joi';

const userValidationSchema = {
  create: Joi.object({
    name: Joi.string().min(2).max(100).required(),
    email: Joi.string().email().required(),
    role: Joi.string().valid('user', 'admin').default('user')
  }),
  update: Joi.object({
    name: Joi.string().min(2).max(100),
    email: Joi.string().email(),
    role: Joi.string().valid('user', 'admin')
  })
};
```

### Hooks and Events

```typescript
const userCrudService = new CrudService<User>({
  model: 'user',
  tableName: 'users',
  hooks: {
    beforeCreate: async (data) => {
      data.password = await bcrypt.hash(data.password, 12);
      return data;
    },
    afterCreate: async (user) => {
      await emailService.sendWelcomeEmail(user.email);
    },
    beforeDelete: async (id) => {
      const user = await userCrudService.findById(id);
      if (user.role === 'admin') {
        throw new Error('Cannot delete admin user');
      }
    }
  }
});
```

## Testing

```bash
npm test -- crud
```

## Dependencies

- database
- validation
- logging
- auth (optional)

## Integration

- Integrates with `database` module for data operations
- Integrates with `validation` module for input validation
- Integrates with `auth` module for permission checking
- Integrates with `logging` module for audit trails

## Error Handling

The module provides comprehensive error handling:

- `ValidationError`: Invalid input data
- `NotFoundError`: Resource not found
- `DuplicateError`: Unique constraint violation
- `PermissionError`: Insufficient permissions
- `DatabaseError`: Database operation failed

## Performance Considerations

- **Pagination**: Always use pagination for large datasets
- **Indexing**: Ensure proper database indexes on searchable/filterable fields
- **Caching**: Consider implementing caching for frequently accessed data
- **Bulk Operations**: Use bulk operations for multiple records
- **Query Optimization**: Monitor and optimize generated queries

## License

MIT
## 🔗 Enlaces

- [Volver al índice de módulos](./README.md)
- [Documentación principal](../README.md)
- [Código fuente](../../modules/crud/)