Agregar un Nuevo Tipo de Documento¶

Guia paso a paso para agregar un nuevo tipo de documento al sistema GDI. Un tipo de documento define la categoria de un documento (Informe, Dictamen, Acta, etc.) con su acronimo, formato y reglas de visibilidad.

Contexto¶

El sistema de tipos de documento tiene dos niveles:

Global (public.global_document_types): Catalogo maestro con 61 tipos definidos. Compartido entre todas las organizaciones.
Per-tenant ({schema}.document_types): Tipos habilitados para cada organizacion, referenciando al catalogo global.

Cada organizacion puede habilitar un subconjunto de los tipos globales y definir que rangos/sectores pueden usarlos.

Ver Schema Public y Schema Municipio para el detalle de las tablas.

Paso 1: Agregar al Catalogo Global (SQL)¶

En `02-seed-global.sql`¶

Agregar el nuevo tipo al INSERT de global_document_types:

-- En GDI-BD/sql/02-seed-global.sql
-- Agregar al final del INSERT INTO public.global_document_types
INSERT INTO public.global_document_types (id, acronym, name, type, is_active)
VALUES
    -- ... tipos existentes (1-61) ...
    (62, 'MITIPO', 'Mi Tipo de Documento', 'HTML', true);

Campo	Descripcion	Valores
`id`	Secuencial unico	Siguiente disponible (62+)
`acronym`	Acronimo corto (usado en numeracion)	Ej: `INF`, `DICT`, `RESOL`
`name`	Nombre completo	Ej: `Informe`, `Dictamen`
`type`	Formato del documento	`HTML` (editor), `Importado` (PDF externo), `NOTA` (notas)
`is_active`	Visible en el catalogo	`true` / `false`

Tipos internos

Los tipos PV (Pase de Vista) y CAEX (Caratula de Expediente) tienen is_active = false porque son generados automaticamente por el sistema al transferir o crear expedientes. No deben ser visibles para los usuarios.

Ejecutar en BD existente¶

-- Agregar a BD de produccion/dev
INSERT INTO public.global_document_types (id, acronym, name, type, is_active)
VALUES (62, 'MITIPO', 'Mi Tipo de Documento', 'HTML', true);

Paso 2: Habilitar en Organizacion (SQL)¶

Cada organizacion tiene su propia tabla document_types que referencia al catalogo global. Al habilitar un tipo, se define que rangos pueden crear documentos de ese tipo.

Agregar a `document_types` de la organizacion¶

-- Habilitar el tipo en el municipio 200_muni
INSERT INTO "200_muni".document_types (
    acronym, name, type, global_document_type_id, is_active
)
VALUES (
    'MITIPO',
    'Mi Tipo de Documento',
    'HTML',
    62,    -- ID del tipo global
    true
);

Configurar permisos por rango¶

La tabla document_types_allowed_by_rank define que rangos pueden crear cada tipo:

-- Obtener el ID local del tipo recien creado
-- SELECT id FROM "200_muni".document_types WHERE acronym = 'MITIPO';

-- Permitir que rangos 1, 2 y 3 creen este tipo
INSERT INTO "200_muni".document_types_allowed_by_rank (document_type_id, rank_id)
SELECT dt.id, r.id
FROM "200_muni".document_types dt
CROSS JOIN "200_muni".ranks r
WHERE dt.acronym = 'MITIPO';

Configurar visibilidad por sector (opcional)¶

La tabla enabled_document_types_by_sector permite restringir tipos por sector:

-- Habilitar solo para sectores especificos
INSERT INTO "200_muni".enabled_document_types_by_sector (document_type_id, sector_id)
SELECT dt.id, s.sector_id
FROM "200_muni".document_types dt
CROSS JOIN "200_muni".sectors s
WHERE dt.acronym = 'MITIPO'
AND s.sector_type = 'PRIV';  -- Solo sectores privados

Sin restriccion por sector

Si no se agrega ninguna fila a enabled_document_types_by_sector, el tipo esta disponible para todos los sectores.

Actualizar seeds para futuros deploys¶

En GDI-BD/sql/04-seed-demo.sql, agregar el tipo al INSERT de document_types del schema 200_muni para que nuevas instalaciones lo incluyan:

-- En la seccion de document_types de 04-seed-demo.sql
INSERT INTO "200_muni".document_types (acronym, name, type, global_document_type_id, is_active)
VALUES
    -- ... tipos existentes ...
    ('MITIPO', 'Mi Tipo de Documento', 'HTML', 62, true);

Y tambien en el template de nuevas organizaciones 03-create-municipio.sql si debe estar disponible por defecto.

Paso 3: Backend - Schemas y Validaciones¶

El Backend ya carga los tipos de documento de la BD dinamicamente. No necesitas cambiar codigo para tipos basicos (HTML o Importado).

Verificar carga del tipo¶

El endpoint GET /document-types retorna todos los tipos activos de la organizacion:

curl http://localhost:8000/document-types \
  -H "X-User-ID: user-uuid" \
  -H "X-Tenant-Schema: 200_muni"

Para tipos con logica especial¶

Si el nuevo tipo necesita logica diferente (como NOTA que tiene destinatarios), debes modificar el service de creacion:

# services/documents/lifecycle/creation.py
async def create_document(data, *, schema_name: str):
    # ... logica existente ...

    # Si el tipo tiene logica especial
    if document_type == "MITIPO":
        # Validaciones adicionales
        # Campos extras
        pass

Ver Documents Lifecycle para entender el flujo de creacion.

Paso 4: PDFComposer - Template Jinja2 (si necesario)¶

Si el nuevo tipo necesita un formato PDF diferente al estandar, debes crear un template en GDI-PDFComposer.

Crear template HTML¶

<!-- GDI-PDFComposer/app/templates/mitipo_template.html -->
<!DOCTYPE html>
<html>
<head>
    <style>
        /* Estilos del documento */
        body { font-family: Arial, sans-serif; margin: 40px; }
        .header { text-align: center; margin-bottom: 30px; }
        .content { line-height: 1.6; }
        .footer { margin-top: 40px; font-size: 10px; color: #666; }
    </style>
</head>
<body>
    <div class="header">
        {% if logo_url %}
        <img src="{{ logo_url }}" height="60"/>
        {% endif %}
        <h2>{{ document_reference }}</h2>
    </div>

    <div class="content">
        {{ document_content | safe }}
    </div>

    <div class="footer">
        <p>{{ entity_name }} - {{ city }}</p>
    </div>
</body>
</html>

Registrar template en el servicio¶

# GDI-PDFComposer/app/services/pdf_service.py
TEMPLATE_MAP = {
    "default": "plantilla.html",
    "CAEX": "caex_template.html",
    "PV": "pv_template.html",
    "MITIPO": "mitipo_template.html",  # Nuevo template
}

Template por defecto

La mayoria de los tipos de documento usan el template default (plantilla.html). Solo crea un template custom si el formato PDF difiere significativamente del estandar.

Paso 5: Frontend - UI de Creacion¶

Agregar a la UI de creacion¶

El Frontend carga los tipos de documento del Backend dinamicamente via GET /document-types. Para tipos basicos, el selector ya los muestra sin cambios.

Si necesitas un icono o color especifico:

// GDI-FRONTEND/src/lib/document-type-config.ts
export const DOCUMENT_TYPE_CONFIG: Record<string, DocumentTypeConfig> = {
  // ... tipos existentes ...
  MITIPO: {
    icon: "FileText",       // Icono de Lucide React
    color: "#4A90D9",       // Color para badges y bordes
    description: "Mi Tipo de Documento",
  },
};

Para tipos con campos adicionales¶

Si el tipo requiere campos extra en el formulario de creacion (como NOTA que tiene destinatarios):

// GDI-FRONTEND/src/components/documents/create/MiTipoFields.tsx
export function MiTipoFields({ onChange }: MiTipoFieldsProps) {
  return (
    <div>
      {/* Campos especificos del tipo */}
    </div>
  );
}

Y condicionar su renderizado en el formulario principal:

// En el componente de creacion
{documentType === "MITIPO" && <MiTipoFields onChange={handleChange} />}

Paso 6: BackOffice - Configuracion¶

El BackOffice permite a administradores gestionar los tipos de documento habilitados. Si el tipo ya esta en global_document_types, aparecera automaticamente en la interfaz de configuracion.

Para agregar configuraciones especificas:

Habilitar/deshabilitar tipo: La tabla document_types de la organizacion con is_active
Permisos por rango: La tabla document_types_allowed_by_rank
Restriccion por sector: La tabla enabled_document_types_by_sector

Checklist¶

Ejemplo: Tipo NOTA¶

El tipo NOTA es un buen ejemplo de tipo con logica especial:

SQL: Tiene type = 'NOTA' (enum document_type_source)
Backend: Service dedicado en services/notes/ con destinatarios, tracking de lectura, archivado
BD: Tablas adicionales notes_recipients y notes_openings
Frontend: UI especifica con selector de destinatarios y bandejas (recibidos, enviados, archivados)

Ver Notes Service y Endpoints de Notas.