Commit 5314f39a authored by seykron's avatar seykron

Adds documentation

parent 762430f4
......@@ -27,7 +27,7 @@ Domino cuenta con los siguientes componentes:
* Un **sistema contable** que permite el asiento de todas las transacciones que se realizan dentro y fuera de
la organización.
* Un **bot de Telegram** (Dominah) que hace de front-end para operar el sistema contable.
* Una **API REST** para operar el sistema contable.
* Un frontend para ver los balances de cada período.
### Sistema contable
......@@ -36,7 +36,7 @@ El sistema contable permite el manejo distribuído de dineros. Todas las persona
del sistema. Los agentes tienen
[cuentas](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/domain/model/Account.kt), y
cualquier
[transacciones](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/domain/model/Transaction.kt)
[transacción](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/domain/model/Transaction.kt)
que se realice en el sistema queda asociada a una cuenta.
#### Cuentas
......@@ -113,6 +113,25 @@ cuenta de la organización, y cancela el monto pagado en el crédito de la empre
el monto total de la factura, la deuda que se creó en la cuenta de la organización queda saldada, y el crédito de la
empresa de servicio queda cancelado.
Los servicios que emiten facturas tienen dos modos de facturación:
* Total: cada factura tiene el monto de toda la deuda pendiente
* Mensual: cada factura tiene el monto del último período de facturación
Las facturas *totales* siempre reemplazan a la factura anterior del mismo servicio. Si existe una factura anterior con
un pago parcial, se asume que la nueva factura va a tener el monto de la factura anterior entonces sólo se carga la
diferencia entre el monto nuevo y el pago parcial existente.
Las facturas *mensuales* siempre generan una nueva factura cada vez que se cargan.
#### Notas de crédito
Las [Notas de Crédito](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/domain/model/CreditNote.kt)
se generan cuando se debe invalidar una transacción. Las transacciones nunca se borran, pero se pueden invalidar. Las
transacciones inválidas no se computan en los balances.
Actualmente solamente se generan notas de crédito para cancelar una factura mal cargada.
### Bot de Telegram
Decidimos utilizar un bot de Telegram porque es lo más simple y accesible para todas las personas que vamos a usar
......@@ -164,3 +183,68 @@ Muestra la lista de facturas pendientes.
[/balance](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/command/Balance.kt):
Muestra el balance de todas las cuentas de la organización.
## Desarrollo
El sistema está programado en Kotlin, y utiliza las siguientes herramientas:
* Base de datos: mariadb para ambientes productivos y H2 para desarrollo
* Acceso a datos: [exposed](https://github.com/JetBrains/Exposed), una librería liviana de acceso a datos
* Web: spring mvc
* Telegram: [tehanu](https://git.rlab.be/seykron/tehanu), un bot de telegram extensible
* Configuración: [typesafe](https://github.com/lightbend/config)
* Rendering de vistas: [freemarker](https://freemarker.apache.org/)
### Organización del código
La aplicación utiliza maven como sistema de build. Como criterio general de desarrollo se está utilizando
[Domain Driven Design](https://es.wikipedia.org/wiki/Dise%C3%B1o_guiado_por_el_dominio), por lo que la aplicación
está separada en dos grandes capas: domain layer y application layer. El sistema contable es parte del domain layer. El
frontend y el bot son parte del application layer.
El código está organizando en los siguientes packages:
* *be.rlab.domino.application*: todo lo relacionado al application layer
* *be.rlab.domino.application.model*: modelo común a todo el application layer
* *be.rlab.domino.application.bot*: comandos del bot de Telegram
* *be.rlab.domino.application.web*: controllers de Spring MVC
* *be.rlab.domino.domain*: todo lo relacionado al domain layer
* *be.rlab.domino.domain.model*: entidades del dominio
* *be.rlab.domino.domain.persistence*: definición y mapeo de los objetos de exposed para persistencia
* *be.rlab.domino.config*: componentes para configurar e inicializar toda la aplicación
* *be.rlab.domino.util*: componentes de soporte para varias tareas
Los recursos están organizados en los siguientes packages:
* /db: scripts para inicializar la base de datos
* /public: contenido que se expone públicamente en la web
* /views: vistas de freemarker
### Ejecutar la aplicación
Domino tiene un servidor [netty](https://github.com/reactor/reactor-netty) embebido y corre como una aplicación
standalone. Para correrlo dentro del IDE:
* Setear las siguientes variables de entorno en tu IDE:
```.env
bot_access_token=access token del bot de Telegram que provee @BotFather
bot_handle=@HandleDelBot
bot_default_admin=id de ususario de telegram que es admin del bot
```
* Ejecutar la clase que inicializa la aplicación:
[be.rlab.domino.ApplicationKt](https://git.rlab.be/seykron/domino/blob/master/src/main/kotlin/be/rlab/domino/Application.kt)
Cuando se corre dentro del IDE la aplicación automáticamente crea la base de datos y las tablas en una base de datos H2.
La base de datos queda guardada en disco, por lo que los datos se mantienen en cada reinicio.
Para ejecutar la aplicación en el sistema operativo se utiliza [docker-compose](https://docs.docker.com/compose). Primero
hay que setear las mismas variables de entorno que se mencionan arriba pero en el
[archivo de configuración de ambiente](https://git.rlab.be/seykron/domino/blob/master/.env) de docker-compose. Luego de
buildear la aplicación se puede utilizar docker-compose para ejecutarla con una base de datos mariadb:
```shell script
$ mvn clean install
$ docker-compose up
```
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment