first commit - init repo and docus

* closes https://codeberg.org/minenux/minenux-skindb-webdb/issues/1
* works https://codeberg.org/minenux/minenux-skindb-webdb/issues/2
* api format is inside docs directory with API.md file
This commit is contained in:
mckaygerhard 2024-04-02 17:39:32 -04:00
commit cd2f3fd9ce
5 changed files with 561 additions and 0 deletions

26
README.md Normal file
View File

@ -0,0 +1,26 @@
# Skindb-webdb
## Contenido
## Introduccion
## HOW TO
[docs/README.md](docs/README.md)**
## LICENSE
The Guachi Framework is open-source software under the MIT License, this downstream part is a reduced version for!
Este minicore conteine partes del framework Banshee bajo la misma licencia.
* (c) 2023 Dias Victor @diazvictor
This proyect is CC-BY-SA-NC
* (c) 2023 PICCORO Lenz McKAY <mckaygerhard>
* (c) 2023 Dias Victor @diazvictor
* (c) 2023 Tyron Lucero

63
docs/00-auth.sql Normal file
View File

@ -0,0 +1,63 @@
/**!
* @package ReceiptAPI
* @filename 00-auth.sql
* @version 1.0
* @autor Díaz Urbaneja Víctor Eduardo Diex <diazvictor@tutamail.com>
* @date 21.11.2023 17:05:17 -04
*/
drop table if exists users_profiles;
drop table if exists permissions;
drop table if exists profiles;
create table profiles (
id_profile int not null auto_increment primary key,
profile varchar(32) not null,
reserved varchar(255) null
);
insert into profiles
(profile, beging, ending)
values
('admin', '00:00:00', 'powered'),
('minetest', '00:00:00', 'uploader');
drop table if exists modules;
create table modules (
id_module int not null auto_increment primary key,
module varchar(32) not null,
description varchar(32) not null,
unique (module)
);
create table permissions (
id_permission int not null auto_increment primary key,
id_profile int not null,
id_module int not null,
`read` boolean not null default true,
`write` boolean not null default true,
`update` boolean not null default true,
foreign key (id_profile) references profiles(id_profile),
foreign key (id_module) references modules(id_module)
);
drop table if exists users;
create table users (
id_user int not null auto_increment primary key,
username varchar(16) not null,
password char(128) not null,
type_user enum('admin', 'minetest'),
status boolean not null default true
);
insert into users
(username, password, type_user)
values
('jhondoe', '$2y$10$JgaTqfeMUhkii.Sj9NBc8e0NjLeMwmLKAgqGwhiUiw1nK/e7E6VdC', 2),
create table users_profiles (
id_user int not null,
id_profile int not null,
foreign key (id_user) references users(id_user),
foreign key (id_profile) references profiles(id_profile)
);

216
docs/API.md Normal file
View File

@ -0,0 +1,216 @@
# skindb/api/reference
## message format
```
{
"sucess": true, //boolean
"message": "server message", //a message from the server
"page": 1, //curent page you are on
"pages": 18, //max number of pages
"per_page": 20, //how many results are per page
"skins": [ //array containing skin items
{ //skin item
"id": Int, // same id as original api, new ones has new format
"name": "String", // alpha numeric only
"author": "String", // alpha numeric only
"license": "String",
"type": "String",
"img": "String" //base64 encoded image content string
}
]
}
```
## use cases
| flujo | tarea | caso de uso / actor | ANON USER | AUTH USER |
| ----- | ----- | ------------------- | --------- | ---------- |
| 1. | #4 | login | x | |
| 2. | #8 | load skin | x | x |
| 3. | #5 | list skin | x | x |
| 6. | #6 | mark skin | | x |
| 7. | #7 | delete skin | | x |
### login
##### Condiciones y flujo
* 1 send POST parameters
- `username` : REQUERIDO : usuario entre 6 y 20 caracters alfanumericos
- `userpass` : REQUERIDO : contraseña entre 6 y 20 caracteres alfanumericos
- `userkey` : REQUERIDO : palabra de 40 caracteres alfanumerica
* 2 check DB api parameters
##### Post condiciones
* 3 response sucess
- mensaje json de datos correctos y permisos de usuarios
```
{
"sucess": true,
"message": "auth success"
}
```
##### Flujos Alternativos
* 2 response fails
- mensaje json de datos incorrectos session invalida
```
{
"sucess": false,
"message": "auth fail"
"data": [
{
".. invalid api key"
}
]
}
```
### load skin
##### Pre conditions
- #8 [login](#login)
##### Condiciones y flujo
* 1 el API recibe los parametros POST
- `rif_agente` : REQUERIDO : rif del comprador
- `rif_sujeto` : OPCIONAL : rif del vendedor
- `num_skin ` : OPCIONAL/REQUERIDO : si hay rif de vendedor, es requerido, es el numero de factura
- `num_control` : OPCIONAL/REQUERIDO : si hay rif de vendedor, requerido, es numero caja o numero linea MH
- `fecha_skin ` : REQUERIDO : fecha de la factura/nota indicada en el skin
- `fecha_compra` : OPCIONAL : se pone a la fecha actual (de no venir) o maximo DIASCARGA atras
- `monto_skin ` : REQUERIDO : base imponible monto total todo el skin , solo positivos sin cero
- `monto_excento` : REQUERIDO : monto de la compra que no se le aplica ningun impuesto, solo positivos incluye cero
- `tipo_skin ` : REQUERIDO : factura o nota
- `adjunto_skin ` : REQUERIDO : el skin de la factura o nota escaneado
* 2 El API valida los datos: PROCESA LOS DATOS
- el api guarda en base de datos los datos y tambien el skin en base64
- el api tambien guarda el skin en el sistema de archivos, tabla anual
- la ruta en el sistema de archivos es separada directorios por años
- mensaje json de el id del skin YYYYMMDDHHmmss, mensaje archivo subido correctamente
##### Post condiciones
* 3 El API valida los datos: RESPUESTA detalle del skin cargado
- mensaje json de la clasificacion de el skin y ruta del archivo adjuntado
- la respuesta de [CAso de uso #7 : detalle skin ]()
##### Flujos Alternativos
* 2 El API valida los datos: RESPUESTA error en el proceso
- mensaje json de datos correctos y el error del sistema si no puedo guardar o paso algo
* 3 El API valida los datos: RESPUESTA datos incompletos o incorrectos
- mensaje json de datos correctos y los campos que tienen los datos incorrectos
### Caso de Uso listar skin s
Listar resumido los skin s o documentos cargados en el sistema segun criterios de filtrado o busqueda
- Actores Principales COMPRADOR, GASTOS, CONTABILIDAD
- Actor Secundario: Base de datos, API receiptsapi
##### Pre condiciones
- #5 [Caso de uso iniciar sesion](#caso-de-uso-iniciar-sesión)
esta se verifica desde las cabeceras junto con su clave.
- DIASCARGA : cantidad de dias permitido para load skin s
##### Condiciones y flujo
* 1 el API recibe los parametros GET, solo llama el punto de entrada
- `rif_agente` : OPCIONAL : rif del comprador
- `rif_sujeto` : OPCIONAL : rif del vendedor
- `num_skin ` : OPCIONAL : numero de factura o nota de skin
- `num_control` : OPCIONAL : numero caja o numero linea MH
- `fecha_skin ` : OPCIONAL : fecha de la factura/nota indicada en el skin
- `fecha_compra` : OPCIONAL : se pone a la fecha actual (de no venir) o maximo DIASCARGA atras
- `monto_factura` : OPCIONAL : total toda la factura, solo positivos sin cero
- `tipo_skin ` : OPCIONAL : factura o nota
##### Post condiciones
* 2 El API lista paginado la primera pagina y en ella los ultimos 100 skin s segun los criterios filtrados
- Si el actor es COMPRADOR, solo se listan sus skin s, Caso contrario se listan todos los skin s
- mensaje json de exito segun el actor en sesion
- listado con estas colunmas:
- `cod_skin ` : mostrar : YYYYMMDDHHMMSS
- `rif_agente` : mostrar
- `rif_sujeto` : mostrar si existe sino vacio
- `fecha_compra` : mostrar, formato YYYYMMDD
- `monto_skin ` : mostrar o 0, si cero mostrar "error" al lado
##### Flujos Alternativos
* 2 El API no muestra skin s si no los hay o no pertenecen al actor GASTOS o CONTABILIDAD
- mensaje json con el estado en error y el mensaje
- devuelve una linea enla primera pagina todos los mismos campos pero con valores en 0 o vacios
* 2 El API no muestra skin s si los existentes son mas de un año o no pertenecen al actor GASTOS o CONTABILIDAD
- mensaje json con el estado en error y el mensaje que no se han realizado cargas recientes
- devuelve una linea enla primera pagina todos los mismos campos pero con valores en 0 o vacios
Realizar el cuarto punto de entrada del api:
### Caso de Uso detalle skin
Detalle completo de un skin o documento en el sistema ya cargado este anulado o no, tenga mas de un año o no!
- Actores Principales COMPRADOR, GASTOS, CONTABILIDAD
- Actor Secundario: Base de datos, API receiptsapi
##### Pre condiciones
- #5 [Caso de uso iniciar sesion](#caso-de-uso-iniciar-sesión)
esta se verifica desde las cabeceras junto con su clave.
- COMPRADOR: se mostrara el skin si este lo cargo dicho usuario
- GASTOS/CONTABILIDAD: puede ver cualquier skin
##### Condiciones y flujo
* 1 el API recibe los parametros GET, solo llama el punto de entrada
- `cod_skin ` : REQUERIDO : id de skin YYYYMMDDHHMMSS
##### Post condiciones
* 2 El API lista paginado la primera pagina y en ella EL DETALLE del skin segun el codigo de id dado
- Si el actor es COMPRADOR, solo se listan sus skin s, Caso contrario se listan todos los skin s
- mensaje json de exito segun el actor en sesion
- listado con estas colunmas:
- `cod_skin ` : mostrar : YYYYMMDDHHMMSS
- `rif_agente` : mostrar
- `rif_sujeto` : mostrar si existe sino vacio
- `num_skin ` : mostrar siempre
- `num_control` : mostrar si existe sino vacio
- `fecha_skin ` : mostrar, formato YYYYMMDD
- `fecha_compra` : mostrar, formato YYYYMMDD
- `monto_skin ` : mostrar o 0, si cero mostrar "error" al lado
- `monto_excento` : mostrar o 0
- `tipo_skin ` : FACTURA/NOTA
- `adjunto_skin ` :
- ruta en sistema de archivo, el api debe verificar si existe, ruta publica del server
- caso contrario usa el guardado en la DB base64 y lo vuelve colocar en el sistema de ficheros
##### Flujos Alternativos
* 2 El API no muestra skin s porque no existe el id
- mensaje json con el estado en error y el mensaje, EL ID skin NO EXISTE EN EL SISTEMA
- devuelve una linea enla primera pagina todos los mismos campos pero con valores en 0 o vacios
* 2 El API no muestra skin s porque el skin no le pertenece
- mensaje json con el estado en error y el mensaje, EL ID skin NO LE PERTENECE
- devuelve una linea enla primera pagina todos los mismos campos pero con valores en 0 o vacios
* 2 El API no muestra skin s porque el parametro es incorrecto o hay un problema en la db
- mensaje json con el estado en error y el mensaje, ERROR INTERNO O PARAMETRO INCORRECTO
- devuelve una linea enla primera pagina todos los mismos campos pero con valores en 0 o vacios

144
docs/DEVEL.md Normal file
View File

@ -0,0 +1,144 @@
## Skindb development
### Prerequisites
* you must have your user as `/home/general`
* you must have `Devel` subpath for development as then `/home/general/Devel`
* you must not work as root never!
* all files must have LF as new line and good identation
### Formato de api request
* Old way, php site `/api/v2/get.json.php?getlist&page=%i&outformat=base64` with `%i` as number page
* New way, astro site `/api/v1/content?client=mod&page=%i` with `%i` as number page, only base64 output
File public assets
* preview asset `/skins/1/%i.png` with `%i` as id skin
### Formato de api response
```
{
"sucess": true,
"message": "message",
"page": 1,
"pages": 18,
"per_page": 20,
"skins": [
{
"id": Int,
"name": "String",
"author": "String",
"license": "String",
"type": "String",
"img": "String",
"url": "string"
},
...
]
}
```
### Formato de metadata skins
* name : string | alphanumeric
* author : string | alphanumeric
* comment : string | alphanumeric, used in the old api for licensing
* license : string | https://spdx.org/licenses/ identifier
```
name = "Sam 0",
author = "Jordach",
comment = "CC BY-SA 3.0",
```
New format uses same order and types but removes the string of titles like `name`:
```
Sam 0
Jordach
CC BY-SA 3.0
```
Fourth line will be the new comment
### FLUJO DE SISTEMA
Simple request response .. con login para subir
### BASE DE DATOS
Se intentara omitir la carga hacia DB, usando los archivos de metadatos de los skins
y la carga directamente en el git.
Cada skin tendra su propio historico, que lo dara el git, y el usuario lo determina
el mismo sistema git.
Los skins viejos emplearan la base de datos vieja. los skins nuevos guardaran a data
en el git y su id sera el formato nuevo.
##### Diccionario de datos
Solo empleado para el api y acceso a la web para la gui [script de la DB skindb.sql](skindb.sql)
### WEBSERVER
Para que esto funcione debe tener un dns interno apuntando "skindb.minenux" a 127.0.0.1
* lighttpd: la configuracion puede ser insertada en una seccion server
o en una seccion de directorio de usurio:
```
$HTTP["host"] =~ "skindb\.minenux$" {
server.document-root = "/home/general/Devel/receiptsapi/public/"
accesslog.filename = "/var/log/lighttpd/receiptsapi.log"
alias.url = ()
url.redirect = ()
url.rewrite-once = (
"^/(css|img|js|fonts)/.*\.(jpg|jpeg|gif|png|swf|avi|mpg|mpeg|mp3|flv|ico|css|js|woff|ttf)$" => "$0",
"^/(favicon\.ico|robots\.txt|sitemap\.xml)$" => "$0",
"^/[^\?]*(\?.*)?$" => "index.php/$1"
)
}
```
* apache2: esta es la mejor opcion, no por popular, sino por ser mas
flexible en opciones para el novato, es la peor para produccion:
```
<VirtualHost *:80>
ServerName skindb.minenux
DocumentRoot /home/general/Devel/receiptsapi/public
<Directory "/home/general/Devel/receiptsapi/public">
DirectoryIndex index.php
Options FollowSymLinks Indexes
AllowOverride All
Order deny,allow
allow from All
</Directory>
</VirtualHost>
```
* nginx: la conffiguracion debe secuestrar un puerto entero, asi que
no es la mejor opcion para servidor:
```
server {
listen 80;
server_name skindb\.minenux;
root /home/general/Devel/receiptsapi/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```

112
docs/README.md Normal file
View File

@ -0,0 +1,112 @@
# skindb
TODO
## Contenido
TODO
## Introduccion
TODO
## How to use this repo
```
rm -rf $HOME/Devel/minenux-skindb-webdb && mkdir $HOME/Devel
git clone --recursive https://codeberg.org/codeigniter/erp-recibosapi $HOME/Devel/minenux-skindb-webdb
cd $HOME/Devel && git submodule foreach git checkout develop && git submodule foreach git pull
```
## Deploy and develop
TODO
#### Requisitos
* Linux:
* Debian 7+ o Alpine 3.12+ unicamente
* git 2.0+
* php 5+ 7+ o 8+
* database
* sqlite3 o perconadb 5.7+ (no se recomienda mariadb, pero sirve o tambien mysql 5.7) + myrocksdb
#### Despliegue
El servicio levantara en `localhost/minenux-skindb-webdb`, sin configuraciones al no ser
una plataforma "domain driven", pero las implementaciones a estas
deberan trabajar con CORS, por lo que el despliege para desarrollo
sera con vesel remoto o en su defecto simple pull en una copia git `git pull origin develop`
#### Desarrollo
Con **GitFlow simplificado**, esta una rama de desarrollo `develop` predeterminada,
y se realiza como la rama "principal" de inmediato (aqui `develop`).
La rama de preproducción es `main`, ambas ramas son protegidas
nadie puede hacer merge sin revision, y todos los merge son squases,
evitando mensajes vanales.
Cada merge debe cerrar uno o mas issue tipo Meta/Casos, ya que el proyecto
se basa en alcances. Este tipo de flujo se emplea en equipos pequeños sin
necesidad de conocimientos git, ya que ellos trabajan juntos en una "rama trabajo"
por cada tarea asignada. Esto no sirve para grupos grandes.
https://medium.com/goodtogoat/simplified-git-flow-5dc37ba76ea8
El desarrollador clona el repositorio y crea una rama, esta
la empieza a trabajar pero cada dia debe realizar un `git pull origin develop`
hacia la rama trabajada.
#### Casos de uso
Deben de cumplirse todos en cada rama de etapa de proyecto, use el dashboard de los issues!
Estos describen que se quiere y como deben cumplirse
#### Estructura del repositorio
TODO
- [ ] authentication system
- [ ] user roles and crud for admins
- [ ] debug error handler
- [ ] api documentation system
- [ ] proyect documentation system
#### Convenciones de codigo
El proyecto contiene una interfaz no usable, pero que encaminan
dos ejemplos de como construir el api:
- [ ] public upload example (Usar esto como ejemplo)
- [ ] local upload example : (usar esto como ejemplo)
Cada commit debe especificar que archivo modifica y
al menos en que funcionalidad se esta trabajando, de al menos 1 linea
de mas de 30 caracteres explicito.
TODO
#### pruebas de despliegue y documentacion
TODO
#### rutas definidas default api
TODO
## LICENSE
The Guachi Framework is open-source software under the MIT License, this downstream part is a reduced version for!
Este minicore conteine partes del framework Banshee bajo la misma licencia.
* (c) 2023 Dias Victor @diazvictor
El proyecto minenux-skindb-webdb es open source y free software bajo la licencia **CC-BY-SA-NC** Compartir igual sin derecho comercial a menos que se pida permiso esten de acuerdo ambas partes, y con atribuciones de credito.
* (c) 2023 PICCORO Lenz McKAY <mckaygerhard>
* (c) 2023 Dias Victor @diazvictor