/**
@file
@brief Documentación para desarrolladores
@mainpage

# Documentación para desarrolladores

Bienvenido o bienvenida a la documentación para desarrolladores del proyecto
IntegralCES. Ésta es una documentación permanentemente en construcción que
vamos completando a medida que nos es necesario.

@section about Acerca de

Integral CES es un conjunto de módulos de Drupal para la gestión de monedas sociales
y sus comunidades. 

ver integralces.net <http://www.integralces.net> para obtener más documentación y
demo.integralces.net <http://demo.integralces.net> para un sitio de demostración.

@section alta_exchange Dar de alta nuevo exchange

Visitar el link 'New exchange'. Rellenar el formulario múltiple y enviarlo. El
administrador lo activará, con lo que daremos de alta el grupo de intercambio y
el usuario drupal que necesitas, con una cuenta vinculada al grupo de
intercambio.

A partir de que demos de alta el exchange y tu usuario administrador, los 
otros usuarios de la eco-xarxa se tendrán que dar de alta usando el 
selector de la home (New to IntegralCES?), seleccionando el pais, i 
pidiendo una cuenta en el exchange que acabamos de dar de alta. Esas 
peticiones de usuarios ya tendrían que llegar al administrador, Se activan
y listo!  

@section modulo_raiz Módulo raíz CES

El módulo de la raíz se denomina ICES. Este módulo por sí solo no proporciona
ninguna función para el usuario final. Tiene un par de objetivos:

- Se trata de un contenedor para todos los demás módulos en una carpeta
  principal por lo que facilitar la instalación y actualización.

- Proporcionar algunas bibliotecas compartidas para ser utilizados por
  cualquiera de los submódulos.

Los archivos que pertenecen directamente al módulo de raíz son incluyen la
ces.info obligatorio y ces.module y las bibliotecas compartidas. Actualmente
hay una biblioteca compartida. Consiste en un capa de abstracción de base de
datos ubicada en el archivo commons.db.logic.inc.

### Base de datos

Hay una forma común para acceder a la base de datos de Drupal en todos los
sub-módulos CES. Se trata de un versión aproximada del [patrón de registro
activo](http://en.wikipedia.org/wiki/Active_record_pattern). El objetivo de
esta capa es concentrar toda la el trabajo de base de datos en un solo lugar
estandarizada. Aísla a otro código de la capa de base de datos de Drupal y
aquellos que facilita la detección de errores, permite un sistema de captura
centralizada y hace que la adaptación a API Drupal cambia casi trivial. Esta
interfaz común se define en el archivo commons.db.logic.inc.

Este archivo define varias clases:

- IcesDBObject: La clase abstracta que cualquier objeto persistente debe
  extenderse. Por ejemplo, la clase Exchange extiende IcesDBObject. Para cada clase
  se extiende DBOBJECT hay una tabla en la base de datos. Esta clase tiene una
  propiedad crucial llamada table. Una clase hija debe establecer esta variable
  para el nombre de tabla asociado con él. También tienen implementaciones por
  defecto para los dos métodos que convierten las variables de objeto interno
  en un array asociativo se salven y viceversa. Por objeto predeterminado
  propiedades públicas se convertirán en campos de la tabla.

- IcesSerializer: Esta clase tiene métodos para guardar, actualizar, cargar y
  eliminar cualquier objeto de tipo IcesDBObject. Es el puente real con la capa de
  base de datos de Drupal. Más allá de la interface CRUD básica, que ofrece
  algunos otros métodos de ayuda que también cuenta con una serialización
  especial estrategia para las jerarquías de clases que implementan el [patrón
  decorador](https://es.wikipedia.org/wiki/Decorator_%28patr%C3%B3n_de_dise%C3%B1o%29).

- IcesLockSerializer: Esta es una subclase de IcesSerializer para aquellas
  operaciones que son delicadas debido a la concurrencia. Esta clase asegura que
  cuando se carga un objeto, que no será cargado por cualquier otro
  LockSerializer hasta que lo guarde.

- DbTransaction: Un contenedor vacío para el módulo CesBank transaction.

![Base de datos](/../img/database.png)

@section modulo_ces_bank Módulo CES BANK

Este es el módulo bancario principal. Define y trabaja con todos los objetos de
banca: grupos de intercambio (exchnages a partir de ahora), cuentas,
transacciones ... Este módulo se divide en dos partes:

- La API de banco (@subpage ces_bank.logic.inc) es el responsable de hacer toda
  la lógica de la banca. Se encuentra en el fichero bank.logic.inc. Cuenta con
  una interfaz pública para crear cuentas, hacer transacciones, etc

- El módulo de banco (@subpage ces_bank) es propiamente el módulo de Drupal con
  su .info y archivos module y otros archivos de páginas y formularios. Utiliza
  la API de banco para realizar las acciones ordenadas por la interfaz de
  usuario web.

#### La API del banco

La API del banco contiene toda la lógica de la gestión de cuentas. Se organiza
en un conjunto de clases. Hay sólo una clase pública que actúa al mismo tiempo
como un controlador para el conjunto y como interfaz publica. Todas las otras
clases son privadas y no deben utilizarse desde fuera. Incluso los parámetros
públicos de la clase Bank no están accesibles para los otros los tipos de
clases. La API banco debe ser pensada como una biblioteca externa. En
particular, es independiente de Drupal. Por la forma en que podría ser
utilizado en integraciones dentro de otras plataformas. Utiliza las funciones
de acceso a base de datos desde el módulo raíz CES y utiliza las funciones de
mensajería del módulo @subpage ces_message. A continuación se comenta el
director clases y sus atribuciones.

- CesBank: Interfaz pública para todas las funciones previstas para esta API. Los
  parámetros y el regreso Los valores de esta clase son, cuando se necesitan
  datos estructurados, arrays asociativos. El trabajo es diferido a los objetos
  particulares concretos. Una implementación típica función de esta clase es
  recibir y (mínimamente) analizar la entrada, cree el objeto privado
  apropiado, llamar a este objeto de función adecuada, (mínimamente) analizar
  el resultado, y devolverlo a la persona que llama.

- CesBankExchange: Representa un grupo de intercambio de comercio. Tiene un
  nombre, un código de 4 letras, y la cúpula opciones configurables.

- CesBankAccount: Es una interfaz que representa una cuenta bancaria.
  Actualmente sólo hay una implementación de esta interfaz. Se espera para el
  futuro utilizar esta interfaz para recoger cuentas a distancia.

  - CesBankLocalAccount: Implementación de la cuenta para las cuentas
    almacenadas en la base de datos local.  Una cuenta pertenece a un
    intercambio particular. Cada uno tiene un identificador único, comenzado
    con el código de 4 letras de su intercambio, seguido de 4 números. Especial
    cuentas pueden terminar con 4 letras en lugar de números. Cada LocalAccount
    es potencialmente relacionadas con uno o más usuarios, y cada usuario puede
    tener uno o más cuentas de este tipo. Cada cuenta tiene también un
    LimitChain, que determina la límites para esta cuenta especial de crédito y
    débito (y otros).

- CesBankAccountLimit: Límite abstracto Atómica para una cuenta. Es la piedra
  angular de LimitChains.

  - AbsoluteDebitLimit: Limita el débito total de una cuenta.

  - AbsoluteCreditLimit: Limita el crédito total de la cuenta.

- CesBankLimitChain: Un conjunto ordenado de AccountLimit, identificado con un nombre.
  Cada cuenta tiene un enlazar con un objeto de este tipo. Una cuenta satisface
  una LimitChain si satisface todas sus CesBankAccountLimits. Un intercambio puede
  configurar varios CesBankLimitChains para varios tipos de cuentas. Por ejemplo, un
  'default' para los nuevos miembros, una "organización" para las cuentas
  compartidas que necesitan más flexibilidad y una "pública" para las cuentas
  públicas sin ningún tipo de límite.

- CesBankTransactionInterface: Interfaz para la transacción entre dos cuentas. Tiene métodos
  para acceso a ambos códigos de cuenta, la cantidad y la descripción o el
  concepto de la transacción.  Existen varias implementaciones utilizando un
  esquema de patrón decorador.

  - CesBankBasicTransaction: Transacción entre dos cuentas del mismo intercambio.

  - CesBankDecoratedTransaction: Resumen de transacciones que delega todos los métodos
    para una transacción "padre" que contiene como una propiedad. Esta clase
    puede heredar añadir funciones a una transacción.

  - CesBankInterExchangeTransaction: Hijo de DecoratedTransaction para permitir el
    comercio entre cuentas de distintos intercambios.
    

### ciclo de vida de una transacción.
  
Las transacciones tienen sólo dos operaciones: aplicar una nueva transacción
y revocar una aplicada anteriormente. Sin embargo, una transacción pasará
por varios estados entre que se crea y pasa a ser efectiva e irreversible. 

Este ciclo de vida se resume en el siguiente diagrama que ahora será comentado
estado por estado.

- NEW: Estado inicial. La transacción ha sido creada pero aún no se ha activado.
  Este es el estado mientras la transacción puede ser editada. A la espera de 
  que el usuario confirme la transacción.

- TRIGGERED: La transacción esta a la espera de ser aceptada. Inmediatamente 
  después de que se pide aceptación por parte de todas las autoridades 
  pertinentes. Se está a la espera de su respuesta. Se pasará a ACCEPTED o 
  REJECTED.

- ACCEPTED: La transacción ha sido aceptada por todas las autoridades. Este 
  estado tiene una vida muy corta en las transacciones locales. El siguiente
  estado es ERROR si el sistema no aplica la transacción, por ejemplo, un 
  servidor remoto no pudo responder, o COMMITED.

- COMMITTED: La transacción se aplicó con éxito. Sin embargo, puede ser
  revocada. Si hay no son temas para esta transacción después de un tiempo
  prudencial, que se archivará.

- ARCHIVED: La transacción está archivada y aplicada con éxito. Nada se puede
  hacer con ella. Existe sólo como datos históricos.

- REJECTED: La transacción, previamente disparada para ser aplicada, ha sido
  rechazada por algunos de las autoridades. Se desecha después de un tiempo
  prudencial. Puede pasar a ACCEPTED si algunas autoridades rectifican.

- DISCARDED: La transacción se descarta y no se ha aplicado. Nada se puede
  hacer con ella. Existe sólo como datos históricos.

- ERROR: Se produjo un error del sistema al aplicar o revocar la transacción.
  El administrador debe tener cuidado de él.  
  
Estos fueron los distintos estados que una transacción puede pasar, A 
continuación los estados relacionados con la operación de revocación. 
El estado inicial de la operación de revocación es el de COMMITTED.

- REVOKE TRIGERED: La transacción se ha disparado paraa ser revocada. 
  Esperando la aceptación de la operación por parte de todas las autoridades.

- REVOKE ACCEPTED: La operación de revocación ha sido aceptada por todas las
  autoridades. El sistema está revocando efectivamente la transacción. Este
  estado es muy efímero en transacciones locales. El siguiente estado
  será REVOKED o ERROR si el sistema no revoca la transacción.

- REVOKE REJECTED: Algunas autoridades no aceptaron la operación de
  revocación. La transacción seguirá en estado COMMITTED y pasará a 
  ARCHIVED después de un tiempo prudencial.

- REVOKED: La transacción ha sido revocado con éxito. Pasara a DISCARDED
  después de un tiempo prudencial.

El estado de la transacción se cambia el uso de la función setstate() de la
interfaz de transacción. Este función también desencadena las acciones
apropiadas. Por ejemplo, cuando el estado se cambia de TRIGGERED a ACCEPTED,
que inicia la aplicación efectiva de la transacción.

![Estados de las transacciones](/../img/states_transaction.png)


#### CES Banco diagrama de clases del módulo

Diagrama de clases para el módulo bancario. Es una aproximación a la
implementación real: hay muchos más propiedades y métodos, y algunos de ellos
pueden tener nombres distintos. Sin embargo, la esencia arquitectónica es
correcta.

![Diagrama de clases](/../img/class_diagram.png)

### Algunos componentes de IntegralCES

- @subpage install
- @subpage flujo_trabajo
- @subpage ces_permissions_doc
- @subpage external_transactions_doc

*/
