# Documentación Permisos y Perfiles

## Modeo de perfiles y permisos

flowchart TD
    A[Usuario] --> B[Perfil A - Agilizador]
    A[Usuario] --> C[Perfil B - Trabajador]
    B[Perfil A - Agilizador] --> D[Permiso 1 - PATCH /services/#]
    B[Perfil A - Agilizador] --> E[Permiso 2 - GET /balance]
    C[Perfil B - Trabajador] --> F[Permiso 3 - GET /services]

* **Usuario**: Puede ser un usuario cualquiera registrado en base de datos
* **Perfil**: Un rol de usuario y a la vez un grupo de permisos, esta identificado por un nombre como Agilizador, Administrador, Trabajador, entre otros.
* **Permiso**: Identificado por una URL que hace referencia a un endpoint de la aplicacion y un metodo que hace referencia al metodo de la peticion HTTP como puede ser POST - /login

Todas las validaciones se realizan mediante un middleware definido en la API, el cual esta identificado como **PermissionsMiddleware** en la ruta **/runer/middleware.py**.

flowchart LR
    A[PATH: /login \n METHOD: POST \n HEADERS  \n BODY] --> B[Middleware]
    B[Middleware] --> |ok| C[API]

Al momento de evaluar la peticion para garantizar o no acceso se evaluan 3 factores los cuales esta ordenados jerarquicamente.
* Validación de Superusuario
* Validación URL y METODO excluido
* Validación de perfil y permisos (estandar)

De lo anterior se resalta que existe uno o varios perfiles de superusuario (si asi se requiere) los cuales pueden tener acceso a todos los endpoints de la API y se pueden excluir endpoints de validaciones con el fin de poder dejar ciertas funcionalidades abiertas para el correcto funcionamiento de la operación.

## Perfiles de usuario
Un perfil de usuario es un rol con el que se identificara un usuario, este puede ser Agilizador, Desarrollador, Administrador entre otros, dicho de otra manera un perfil es un grupo de permisos.

| ID | Perfil |
| --- | --------------------- |
| 1 | Agilizador |
| 2 | Desarrollador |
| 3 | Administrador |
| 4 | Trabajador |
| 5 | Cliente |
| 6 | Administrador Empresa |
| 7 | Cliente Empresa |
| 8 | Coordinador |
| 9 | Comercial |
| 10 | Superusuario |

:::info
**Base de datos**: 💻
La informacion de los perfiles se puede encontrar en la tabla **users_profile_types** y las relaciones con los permisos se encuentra en la tabla **users_profile_types_permission_type**
:::

### Listar perfil
Lista el perfil de usuario identificado por el id proporcionado

<span class="get">**GET**</span> <span class="endpoint">{{HOST}}/users/profile_types/{int}</span>

#### Response - 200 OK

{
    "id": 21,
    "name": "Administrador",
    "description": "Perfil administrador",
    "active": true,
    "permission_type": [
        {
            "id": 191,
            "url": "/services",
            "method": "GET",
            "description": null,
            "active": true,
            "excluded": true
        },
        {
            "id": 192,
            "url": "/services",
            "method": "POST",
            "description": null,
            "active": true,
            "excluded": true
        }
    ]
}

### Crear un perfil
Crea un perfil de usuario de acuerdo a los parmetros especificados

<span class="post">**POST**</span> <span class="endpoint">{{HOST}}/users/profile_types</span>

#### Request

| Clave | Requerida | Tipo | Descripcion |
| -------------------- | --------- | ----------- | ----------------------------------------------------------- |
| name | si | string | Nombre del perfil |
| description | si | string | Descripcion del perfil |
| active | si | string | Perfil activo? |
| permissions_included | no | array [int] | Define los permisos que se van a agregar al perfil |
| permissions_excluded | no | array [int] | Agrega todos los permisos al perfil y excluye los definidos |
| all_permissions | no | bool | Agrega todos los permisos al perfil |

{
    "name": "Administrador",
    "description": "Perfil de administrador",
    "active": true,
    "permissions_included": [1,2]
}

:::info
**Solo se requiere una o ninguna de las claves opcionales dependiendo del resultado que se requiera**
:::

#### Response - 201 CREATED

{
    "id": 18,
    "name": "Administrador",
    "description": "Perfil de administrador",
    "active": true,
    "permission_type": [
        {
            "id": 1,
            "url": "/services/mobile/rings",
            "method": "GET",
            "description": null,
            "active": true,
            "excluded": false
        },
        {
            "id": 2,
            "url": "/services",
            "method": "GET",
            "description": null,
            "active": true,
            "excluded": false
        }
    ]
}

### Modificar un perfil
Modifica un perfil de usuario de acuerdo a los parametros especificados

<span class="patch">**PATCH**</span> <span class="endpoint">{{HOST}}/users/profile_types/{int}</span>

| Clave | Requerida | Tipo | Descripcion |
| -------------------- | --------- | ----------- | ---------------------------------------------------- |
| name | no | string | Nombre del perfil |
| description | no | string | Descripcion del perfil |
| active | no | string | Perfil activo? |
| permissions_included | no | array [int] | Define los permisos que se van a agregar al perfil |
| permissions_excluded | no | array [int] | Define los permisos que se van a eliminar del perfil |
| all_permissions | no | bool | Agrega todos los permisos al perfil |
| delete_permissions | no | bool | Elimina todos los permisos del perfil |

#### Request

{
    "name": "Administrador",
    "description": "Perfil de administrador",
    "active": true,
    "permissions_included": [1,2,3]
}

:::info
**Las claves no son de uso obligatorio para el metodo patch**, se deben definir solo las claves de los datos a modificar
:::

:::warning
**Tener en cuenta**: 💡
Se recomienda **solo seleccionar una opcion entre permissions_included, permissions_excluded, all_permissions o delete_permissions** dado que el resultado se sobrescribe y puede dar a resultados no esperados.
:::

#### Response - 200 OK

{
    "id": 15,
    "name": "Administrador",
    "description": "Perfil de administrador",
    "active": true,
    "permission_type": [1,2,3]
}

### Eliminar un perfil
Elimina el perfil de usuario identificado con el id proporcionado.

<span class="delete">**DELETE**</span> <span class="endpoint">{{HOST}}/users/profile_types/{int}</span>

#### Response - 204 NO CONTENT

{}

:::info
**El borrado del perfil es logico**, al momento de realizarlo solo se eliminan la relaciones entre el perfil y los respectivos permisos para evitar posibles inconvenientes.
:::

## Permisos de usuario

Un permiso garantiza al usuario tener acceso a un endpoint especifico de la aplicacion.

:::info
**Base de datos**: 💻
La informacion de los permisos se puede encontrar en la tabla **users_permissions** y las relaciones con los perfiles se encuentra en la tabla **users_profile_types_permission_type**
:::

### Listar permisos

Lista todos los permisos que coincidan con los query params especificados, si no se proporcionan query params lista todos los permisos.

<span class="get">**GET**</span> <span class="endpoint">{{HOST}}/users/permissions</span>

| Query param | Tipo | Descripcion |
| ----------- | ------ | -------------------------------------------------- |
| url | string | Filtra por url |
| method | string | Filtra por metodo de peticion HTTP (GET, POST ...) |
| active | bool | Filtra por permisos activos |
| excluded | bool | Filtra por permisos excluidos de validacion |

#### Response - 200 OK

[
    {
        "id": 482,
        "url": "/users/profiles/#",
        "method": "PATCH",
        "description": null,
        "active": true,
        "excluded": true
    },
    {
        "id": 284,
        "url": "/services/#/integrations/payments",
        "method": "GET",
        "description": null,
        "active": true,
        "excluded": false
    },
    {
        "id": 285,
        "url": "/services/#/integrations/payments",
        "method": "PATCH",
        "description": null,
        "active": true,
        "excluded": false
    }
]

### Crear permiso
Crea un permiso en base a los parametros especificados

<span class="post">**POST**</span> <span class="endpoint">{{HOST}}/users/permissions</span>

| Clave | Requerida | Tipo | Descripcion |
| ----------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| url | Si | string | Url asociada al permiso, si la URL contiene un parametro se debe identificar como #, los query params no son tenidos en cuenta |
| method | Si | string | Metodo HTTP asociado a la URL (GET, POST ...) |
| description | Si | string | Descripcion del endpoint |
| active | Si | bool | Permiso activo? |
| excluded | Si | bool | Permiso excluido de validacion |
| profiles | Si | Array [int] | Lista de perfiles a los que se agregara el permiso |
:::info
**Tener en cuenta 👇👇‼️**
**Parametros en URL** se deben identificar con **#** ejemplo **/services/{int}** 👉 **/services/#**
**Query Params** los query params no son tenidos en cuenta por lo tanto **no se deben agregar**
:::

#### Request

{
    "url": "/users/permissions/#",
    "method": "GET",
    "description": "Endpoint de prueba",
    "active": true,
    "excluded": true,
    "profiles": [1,2]
}

#### Response - 201 CREATED

{
    "id": 493,
    "url": "/users/permissions/#",
    "method": "GET",
    "description": "Endpoint de prueba",
    "active": true,
    "excluded": true,
    "profiles": [
        {
            "id": 1,
            "name": "Administrador",
            "description": "Perfil de administrador",
            "active": true
        },
        {
            "id": 2,
            "name": "Agilizador",
            "description": "Perfil de agilizador",
            "active": true
        }
    ]
}

### Modificar un permiso
Modifica un permiso de acuerdo con los parametros especificados

<span class="patch">**PATCH**</span> <span class="endpoint">{{HOST}}/users/permissions/{int}</span>

| Clave | Requerida | Tipo | Descripcion |
| -------------------- | --------- | ----------- | --------------------------------------------------- |
| url | no | string | Modifica la URL |
| method | no | string | Modifica el metodo (GET, POST ...) |
| description | no | string | Modifica la descripcion |
| active | no | bool | Activa o desactiva el permiso |
| excluded | no | bool | Excluye la URL de validacion de permisos |
| profiles | no | Array [int] | Agrega el permiso a los perfiles especificados |
| exclude_profiles | no | Array [int] | Elimina el permiso de los perfiles especificados |
| include_all_profiles | no | Array [int] | Agrega el permiso a todos los perfiles existentes |
| exclude_all_profiles | no | Array [int] | Elimina el permiso de todos los perfiles existentes |

:::info
**Tener en cuenta 👇👇‼️**
**Parametros en URL** se deben identificar con **#** ejemplo **/services/{int}** 👉 **/services/#**
**Query Params** los query params no son tenidos en cuenta por lo tanto **no se deben agregar**
:::

#### Request

{
    "url": "/users/permissions/#",
    "method": "GET",
    "description": "Endpoint de prueba",
    "active": true,
    "excluded": false,
    "profiles": [1,2]
}

:::info
**Las claves no son de uso obligatorio para el metodo patch**, se deben definir solo las claves de los datos a modificar
:::

#### Response - 200 OK

{
    "id": 494,
    "url": "/users/permissions/#",
    "method": "GET",
    "description": "Endpoint de prueba",
    "active": true,
    "excluded": true,
    "profiles": [
        {
            "id": 1,
            "name": "Administrador",
            "description": "Perfil de administrador",
            "active": false
        },
        {
            "id": 2,
            "name": "Agilizador",
            "description": "Perfil de agilizador",
            "active": true
        }
    ]
}

### Eliminar permiso
Elimina el permiso identificado con el id proporcionado de manera fisica

<span class="delete">**DELETE**</span> <span class="endpoint">{{HOST}}/users/permissions/{int}</span>

#### Response - 204 NO CONTENT

{}

:::info
**El borrado del permiso es logico**, al momento de realizarlo solo se eliminan la relaciones entre el permiso y los respectivos perfiles para evitar posibles inconvenientes.
:::

<style>
*, html {
box-sizing: border-box;
}
.delete, .get, .head, .patch, .post, .put {
display: inline-block;
padding: 6px 8px;
background-color: #888;
border-radius: 4px;
color: #fff;
margin-right: 8px;
font-family: sans-serif;
}
.get {
background-color: #61affe;
}
.post {
background-color: #49cc90;
}
.patch {
background-color: #ffc330;
}
.delete {
background-color: #fc6238;
}

blockquote {
border-left: 6px solid #fdd402;
margin-bottom: auto;
padding: 5px 10px;
font-size: 13px;
}
.endpoint {
display: inline-block;
padding: 6px 12px;
background-color: #eee;
border-radius: 4px;
color: #444;
font-family: monospace;
}
</style>