Definición de estructura y nomenclatura API
===

Introducción
--
En el presente documento se darán a conocer todas las definiciones correspondientes a la arquitectura de desarrollo 2020.

#### Tabla de contenidos
[TOC]

[[_TOC_]]

### Proyecto
---
El proyecto consta de dos ambientes:
* Front End
* Back End

El Back-End se trabajará desde una api quien controlará la parte logica del proyecto.

Front End
---
### Estructura
### Variables
### Funciones

Back End
---

### WEB API

Una API es una interfaz de programación de aplicaciones (del inglés API: Application Programming Interface). Es un conjunto de rutinas que provee acceso a funciones de un determinado software.

En el caso de HQBDOC se utilizará una arquitectura está basada en la inyección de dependencias, esta estructurada pensada en el concepto de la arquitectura limpia y principios SOLID.

### Estructura Jerárquica Solución

* Solución "WebAPI"
* Carpeta Modules
* Proyecto WebAPI.Module.Core
* Proyecto WebAPI.Module.Localization
* Proyecto WebAPI.Host
* Proyecto WebAPI.Infraestructure

**Definiciones:**
* Carpeta Modules: Dentro de esta carpeta se encuentran los diferentes módulos de la solución. Entiendase módulo como conjunto de funcionalidades encapsuladas referente a un área o lógica particular.
* Proyecto WebAPI.Module.Core: Contiene todas las implementaciones generales, útiles y soporte que deberían ser usados por los demás módulos.
* Proyecto WebAPI.Localization: Contiene las diferentes configuraciones de idioma.
* Proyecto WebAPI.Host: Dentro de este proyecto se encuentran las configurar el framework, además se encarga de inicializar el proyecto.
* Proyecto WebAPI.Infraestructure: Contiene todas las interfaces y clases requeridas para facilitar la implementación de código modular y de la inyección de dependencias.

### Nombres de espacios de nombres

* TODO
https://docs.microsoft.com/es-es/dotnet/standard/design-guidelines/names-of-namespaces

### Estructura Jerárquica Módulo

* HQB.HQBDOC.WebAPI.Module.Modulo
* Resources
* src
* Areas
* Attributes
* Data
* Extensions
* Filters
* Models
* Responses
* Services
* Support
* Utils

**Definiciones**
* Resources: Carpeta donde se almacenan recursos que no requieren compilación y que se necesitan dentro del módulo de manera transversal. Por ejemplo, archivos .resx
* src: Carpeta donde se almacenan sub-carpetas donde cada una de ellas contiene en su interior clases que implementan funcionalidades específicas.
* Areas: Sub-Carpeta donde se almacenan las diferentes áreas del módulo. Entiendase área como una sección del negocio específica, por ejemplo, usuarios. Cada área específica se descompone en cuatro carpetas:
* Controllers: Dentro de esta se definen las clases que se encargan de obtener las entradas y responder los parámetros de salida.
* Requests: Dentro de esta se definen las clases que permiten mapear los datos entradas de los métodos http.
* Response: Dentro de esta se definen las clases que permiten mapear los datos de salida de los métodos http.
* Use Cases: Dentro de esta se definen las clases que se encargan de definir los métodos que pertenecen a las reglas de negocio del módulo.
* Attributes: Dentro de esta se definen clases para poder realizar validaciones
* Data: Dentro de esta se definen clases para poder realizar interacciones con base de datos.
* Exensions: Dentro de este se definen clases que contienen métodos que extienden a clases existentes.
* Filters: Dentro de este se definen clases que permiten declarar métodos que se utilizan como filtro antes de entrar al controlador.
* Models: Dentro de esta se definen las clases que permitirán declarar las entidades de la base de datos.
* Responses: Dentro de esta se definen clases de respuesta de la API, estas son transversales para todo el módulo.
* Services: Dentro de esta se definen clases que configuran o implementan servicios/middleware que utiliza el módulo.
* Support: Dentro de esta se definen clases auxiliares para varios fines.
* Utils: Dentro de esta se definen clases que declaran métodos que son utilizados transversalmente.

### Clases

>:bulb:Resumen
>> * Idioma Español (es)
>> * Pascal Case
>> * Nombre en Singular
>> * Patrón de Diseño Singleton

Una clase es una plantilla para la creación de objetos de datos según un modelo predefinido. Las clases se utilizan para representar entidades o concepto.
El nombre de una clase debe representar lo que hace nombrandolo en singular y debe estar escrita en español. A menos que por limitaciones técnicas del lenguaje utilizado no lo permita. Un ejemplo de esto es "UsuarioController.cs" donde "Controller" debe estar en ingles ya que la misma tecnologia o lenguaje obliga a que tenga esta nomenclatura para que sea reconocido dentro del código.

>:pushpin: **Ejemplos:**

public class Usuario
{
    public void Ingresar()
    {
        //..
    }

    public void Eliminar()
    {
        //..
    }
}

>:bulb: **Sufijos:** A continuación se definen sufijos especiales para clases según finalidad:
>>* **Controllers** Ej: UsuarioController.cs
>>* **Requests** Ej: UsuarioRequest.cs
>>* **Responses** Ej: UsuarioResponse.cs
>>* **Use Cases** Ej: UsuarioCase.cs
>>* **Attributes** Ej: UsuarioAtribute.cs
>>* **Models Builders** Ej: UsuarioModelBuilder.cs
>>* **Extensions** Ej: UsuarioExtension.cs
>>* **Filters** Ej: UsuarioFilter.cs
>>* **Models** Ej: UsuarioModel.cs
>>* **Services** Ej: UsuarioService.cs

#### Atributos de la Clase
>* Resumen
>>* Idioma Español (es)
>>* Pascal Case
>>* Nombre en Singular

Descripciónlalala

>:pushpin: **Ejemplos:**

..
 public int Edad { get; set; }
 public string Rut { get; set; }
.. 

#### Métodos de la Clase
>* Resumen
>>* Firma Método:
>>* Idioma Español (es)
>>* Pascal Case
>>* Variables de Firma:
>>* Idioma Español (es)
>> * Camel Case

Los métodos en general deben estar escritos en español y en pascal case. El nombre del método debe resumir a grandes rasgos su funcionalidad. Los nombres de las variables de la firma deben estar, de igual forma, en español pero en camel case.

>:pushpin: **Ejemplo:**

public Datos MetodoParaObtenerDatosPorIdentificador(int identificadorUnico)
{
    //..
}

#### Resumen de Metodo (Summary)
>* Resumen
>>* Idioma Español (es)
>>* Estandar Microsoft

El Summary es el resumen de un objeto. La etiqueta ```<summary>``` debe usarse para describir un tipo o un miembro de tipo.

>:pushpin: **Ejemplo:**

/// <summary>
/// Verifica si el nombre de usuario y contraseña son válidos y devuelve el Token JWT de la sesión.
/// </summary>
/// <param name="request">Solicitud con nombre de usuario y contraseña</param>
/// <returns>Retorna la información relevante del usuario si la verificación es exitosa</returns>
/// <response code="200">La autenticación se ha realizado exitosamente</response>
/// <response code="400">El nombre de usuario o contraseña son incorrectos, el usuario no existe o no tiene los permisos para usar la API</response>
public async Task<IActionResult> LogIn([FromBody] AuthenticationRequest request)
{
//..
}

>Referencias:
>>https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/summary

### Variables
>* Resumen
>>* Idioma Español (es)
>>* Camel Case

La variable está formada por un espacio en el sistema de almacenaje (memoria principal de un ordenador) y un nombre simbólico (un identificador) que está asociado a dicho espacio. Ese espacio contiene una cantidad de información conocida o desconocida, es decir un valor. Una variable debe nombrarse segun el contenido que tiene o tendrá la misma. Por ejemplo, fechaDeEntrada

>:pushpin: **Ejemplo:**

int usuarioId = 1;
DateTime fechaEntrada = DateTime.Now;
string nombreUsuario = string.empty;

### Constantes
>* Resumen
>>* Idioma Español (es)
>>* Pascal Case

Una constante es un valor que no puede ser alterado/modificado durante la ejecución de un programa, únicamente puede ser leído.

Una constante corresponde a una longitud fija de un área reservada en la memoria principal del ordenador, donde el programa almacena valores fijos.

Las constantes deben tener el prefijo **Const** para saber a primera vista que son constantes

>:pushpin: **Ejemplo:**

int ConstUsuarioId = 1;
string ConstNombreJuan = "Juan Andrés";

### Casos de Uso
>* Resumen
>>* Idioma Español (es)

Representa la parte comercial o mirada al negocio se deberia realizar un caso de uso por cada accion.

>:pushpin: **Ejemplo:**

Este es un ejemplo de que se puede poner UML. hay que adaptarlo

Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!
Note left of Alice: Alice responds
Alice->Bob: Where have you been?