From cd2f3fd9cede2eebb9203ce8a54ae96d980b5c64 Mon Sep 17 00:00:00 2001 From: mckaygerhard Date: Tue, 2 Apr 2024 17:39:32 -0400 Subject: [PATCH] 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 --- README.md | 26 ++++++ docs/00-auth.sql | 63 ++++++++++++++ docs/API.md | 216 +++++++++++++++++++++++++++++++++++++++++++++++ docs/DEVEL.md | 144 +++++++++++++++++++++++++++++++ docs/README.md | 112 ++++++++++++++++++++++++ 5 files changed, 561 insertions(+) create mode 100644 README.md create mode 100644 docs/00-auth.sql create mode 100644 docs/API.md create mode 100644 docs/DEVEL.md create mode 100644 docs/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f3b7d9 --- /dev/null +++ b/README.md @@ -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 +* (c) 2023 Dias Victor @diazvictor +* (c) 2023 Tyron Lucero + diff --git a/docs/00-auth.sql b/docs/00-auth.sql new file mode 100644 index 0000000..c9a2f6b --- /dev/null +++ b/docs/00-auth.sql @@ -0,0 +1,63 @@ +/**! + * @package ReceiptAPI + * @filename 00-auth.sql + * @version 1.0 + * @autor Díaz Urbaneja Víctor Eduardo Diex + * @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) +); + diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..bad1d2d --- /dev/null +++ b/docs/API.md @@ -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 + diff --git a/docs/DEVEL.md b/docs/DEVEL.md new file mode 100644 index 0000000..27a8498 --- /dev/null +++ b/docs/DEVEL.md @@ -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: + +``` + + ServerName skindb.minenux + DocumentRoot /home/general/Devel/receiptsapi/public + + + DirectoryIndex index.php + Options FollowSymLinks Indexes + AllowOverride All + Order deny,allow + allow from All + + +``` + +* 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; + } +} +``` + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ad89ab3 --- /dev/null +++ b/docs/README.md @@ -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 +* (c) 2023 Dias Victor @diazvictor +