From 6c4194250d4a468f6b013ea0241d48b689a57613 Mon Sep 17 00:00:00 2001 From: philc Date: Mon, 6 Mar 2023 09:47:25 +0100 Subject: [PATCH] devrules update --- Devrules.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 126 insertions(+), 12 deletions(-) diff --git a/Devrules.md b/Devrules.md index 77f950d..201f46e 100644 --- a/Devrules.md +++ b/Devrules.md @@ -2,34 +2,57 @@ This page is about to save time to a dev to quickly onboard to add a features or debug any issues. This is also a good start if you want just dev a plugin for a tribe. -## Key point +## Key points * this is a npm/yarn classical organization (package.json give you 1st info) -* Entry point ./apxtrib.js +* **Entry point** ./apxtrib.js * apXtrib is organize around an express.js api and respect the restFULL concept on an object. -* An object has: +* An **object** has: - a unique objectName - a metadata definition that describe each character to qualify an object - a route named ./routes/objectName.js from the api /objectName/ parameters to request acting on items of this objectName - a model named ./models/ObjectName.js that act on items -* Access control is done by 3 middlewares: + - a language info in infolg/ObjectName.js +* **Access control** is done by 3 middlewares: - checkHeaders.js that check ./tribes/townconf.json.exposedHeaders are presents - isAuthenticated.js check the token (header.xauth ) for header.xpaganid is valid - hasAccessrighton.js check accessright of pagan to act (CRUD) on an object into a tribe (xworkon) -* Multilanguage management +* A **request** is send with specific header to be accepted. + ``` + { + xauth: 'jwt token 24hours valid or 1 if not authenticated', + xpaganid: 'uuid of the connected user' + xlang:' lang international notification 2 letters of the request', + xtribe: 'name of the tribe, xpaganId belongs to', + xworkon: 'name of tribe user want to act if accessrights are properly set up', + xapp: 'name of app requesting action "tribename:nappname" if accessrights are set up' + } + ``` +* A **response** is structured as +``` + { + status: mandatory Integer, + info: optional string, + data: optional object + } +``` + (web status code)[https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP] +* **Multilanguage management** depending of header.xlang request + - info:"#model#key" starting by # mean a file is available in ./nationchains/static/info/model_lg.json to match {key:"information in language lg} + ### apXtrib Coding Convention Standard: Eslint 6 with a .eslintrc.js lib used for: -* file json manipulation: fs-extra.js +- file json manipulation: fs-extra.js - templating szysteme: mustache.js - encryption with simple hash : bcrypt that is more efficient than crypto-js that is use inside a browser or node for cypher and uncipher - time management use luxon and no more moment -* cross domain management: cors.js -* to generate unique id use lib uuid.v4() -* stripe to allow payment in $,€,... any device +- cross domain management: cors.js +- to generate unique id use lib uuid.v4() +- stripe to allow payment in $,€,... any device In general try to not install other lib in your dev. An apXtrib town mayor have to globaly valid to add a new lib into apxtrib so if you do then you can only use your town to provide your service and cannot use other town to deal wwith. @@ -45,8 +68,6 @@ global variable into node: * const app is an express instance that is set into apixtrib.js -### Object organization - ### route template @@ -59,6 +80,99 @@ export model to make it importable into route or any other app +### Object organization + +Object properties are strongly inspire of https://schema.org/docs/schemas.html +Fom https://json-schema.org/learn/ + https://json-schema.org/understanding-json-schema/index.html + https://json-schema.org/draft/2020-12/release-notes.html +Warning: stay in those specification much as it is possible, try to use existing object like person, organisation, .... +As it is still on draft, a Odmdb.js (Objectdatamodeldatabase) is managing any CRUD on json object +Any apxtrib key word is prefix by apx to inform that it does not exist in JSON schema protocole. This can be change in the futur if json schema will be stable enough. + +An **object is defined by a schema** store into ./nationchains/socialworld/schema/objectName.json or tribe/tribeId/plugins/pluginName/schema/objectName.json +It lists key definition of an item's object. +Items object are store into ./nationchains/socialworld/objects/objectName/objectNameid.json or tribe/tribeId/objects/objectName/objectNameid.json +If an **item have a language** properties:lang that describe in with language is used by this item. If the object item cannot be translate this means that it is a different object. + +apXtrib **convention to manage language** to get a schema in a language:lg : +|objectName|keyword => file ./nationchains/socialworld/objects_lang/objectName_lg.json = {keyword:description in lg} +or tribe/tribeId/objects_lang/objectName_lg.json + +If any string start with | mean it exist a file translation + +A models/objectName.js manage all items of an objectName: + - CRUD action on any items depind of pagan accessright + - index builder that are store into /objectName/searchindex/ + a searchindex file is named as objectname_idfield1_idfiled2_lg.json + and contain: { value1idfiled1:[ value1idfield2 ] } + Depending of volume, it is possible to have objectName_UUID_UUID_lg.json this contain + { valueuuid: { key:value of object} } + + +#### Object key description + +Main properties key: +* **description** a short description that can be use in GUI +* **desclong** a long description +* **info** a long or short html description +* **default** value by default if not set when object is save, this can be a function + example: UUID.v4() or moment(new Date()).format('YYYY-MM-DD') +* **format** usefull for date or any text structured example:"YYYY-MM-DD" +* **type** string / int / +* **enum** list of valid data +* **$apxenumkey** if "data" then properties status.data has to be set as a {key:value} + else a web link (absolute http:/... or relative ./...) to a {key:value} + mean the value have to be one of the key of this json file if it is required +* + +En prevision de smatchit : +person shema + { + "idfield": "telephone", + "desc": "|Pagans|telephonedesc", + "check": ["phone"] + "tpl": "input", + "type": "text" + }, + { + "idfield": "familyName", + "desc": "|Pagans|familyNamedesc", + "tpl": "input", + "type": "text" + }, + { + "idfield": "givenName", + "desc": "|Pagans|givenNamedesc", + "tpl": "input", + "type": "text" + }, + { + "idfield": "additionalName", + "desc": "|Pagans|additionalNamedesc", + "tpl": "input", + "type": "text", + "info": "|Pagans|additionalNameinfo" + }, + + + +**searchindex** array of index to generate + keyword "all" => generate objectname/searchinndex/objectname_UUID_UUID.json = {uuid:{full key:value}} +* **nouserupdate** user cannot modify this field from a request (only internal process can change this) +* **check** array of keyword required, unique, ... + + a checkdata lib (./natonchains/socialworld/contracts/checkdata.js) can be used + into a browser : + or into a node.js : const checkdata = require( `../nationchains/socialworld/contracts/checkdata.js`); + + Some test function need context (ctx ) for example to check a value is unique + example: @TODO key example + + checkdata.evaluate = (contexte (list ), metaobject (definition of object metaobject/name.json), data (item object set to evaluate)) + + In case of unconsistency(ies) a new field call invalidfor array of list of unconsitencies is returned + ### Object Nationschains @@ -69,4 +183,4 @@ export model to make it importable into route or any other app ### Object Tribes - +### Object Pagans