Lanaren xehetasuna

Arazoa

Kudeaketa komertzialeko aplikazioak askotan modu desordenatuan hazten dira:

• negozio logika sakabanatua,
• dokumentatu gabeko arau inplizituak,
• modeloetara zuzenean lotutako endpoint-ak,
• aldaketak sartzeko zailtasuna fluxuak apurtu gabe.

Gainera, eragiketa hauek:

• erosketa edo salmenten berrespena,
• stock mugimenduak,
• cash mugimenduak,
• backups eta leheneratzeak,

kontrola, trazabilitatea eta babesa behar dute, ez CRUD soilak.

Soluzioa

API bat diseinatu nuen arkitektura zorrotz gobernatuarekin, non erantzukizun bakoitza argi mugatuta eta dokumentatuta dagoen.

Geruzazko arkitektura

Erantzukizunen banaketa esplizitu eta negoziaezina:

• Model Datu-basearen egitura eta serializazioa adierazten ditu (to_dict).
• Service negozio logika eta arau operatiboak ditu.
• Controller Datuak, baliozkotzeak eta deien orkestrazioa kudeatzen ditu.
• API / Router Endpoint-ak eta API kontratua definitzen ditu.

Zerbait aldatzen bada, geruza bakarra ukitzen da, ez sistema osoa.

Oinarri + Hedapen arkitektura

Proiektu honetan ikasitako gakoetako bat Oinarri + espezializazio arkitektura erabiltzea da:

• BaseModel
  • id
  • auditoria (created_at, updated_at)
  • soft delete (is_active, deleted_at)
  • to_dict()
• Benetako modeloek behar dena bakarrik heredatzen, zabaltzen edo gainidazten dute.

Gauza bera gertatzen da honekin:

• BaseService
• BaseController
• BaseRouter

CRUD estandarra inplementatzen dutenak:

• create
• get_all
• get_by_id
• update
• delete (soft delete)
• restore

Eta ondoren negozio arau dokumentatuen arabera espezializatzen direnak.

• koherentzia proiektu osoan,
• bikoizketa gutxiago,
• eboluzio kontrolatua.

Domeinua eta kontzeptu-eredua (DDD informala)

Garapenean zehar konturatu nintzen modu naturalean DDD informala aplikatzen ari nintzela:

• Entities
  • users
  • products
  • customers
  • suppliers
• Aggregates
  • stock locations
  • produktu bakoitzeko stock
  • cash accounts
• Documents
  • erosketa-albaranak
  • salmenta-albaranak
  • stock-gordailuak
  • cash transferentziak
• Events
  • stock mugimenduak
  • kutxa mugimenduak

Dokumentuak ez dira datuak bakarrik: aggregate-ak eragiten dituzten ekintzak adierazten dituzte event-en bidez.

Funtzionalitate nagusia

Kudeaketa komertziala

• Erabiltzaileak eta rolak (ADMIN / USER)
• Produktuak, bezeroak eta hornitzaileak

Stock

• Kokalekuak
• Kokaleku bakoitzeko stocka
• Kokalekuen arteko gordailuak

Cash

• Kutxa kontuak
• Transferentziak eta mugimenduak

Negozio dokumentuak

• Erosketa-albaranak
• Salmenta-albaranak
• Dokumentuen berrespena
• Egoeraren araberako arau esplizituak (DRAFT / CONFIRMED)

Segurtasuna, rolak eta sarbide kontrola

• JWT (access + refresh) bidezko autentifikazioa
• Tokenek password_changed_at dute
• Tokenen baliogabetze automatikoa pasahitza aldatzean

Rolak:

• ADMIN
  • erabiltzaile kudeaketa
  • backups eta restores
  • eragiketa kritikoak
• USER
  • negozioaren ohiko eragiketak

Segurtasun arau esplizituak:

erabiltzaile batek ezin du bere burua ezabatu ezta azken admin-a ezabatu ere.

Babeskopiak eta datuen babesa

Sistemak backupetarako euskarri esplizitua dauka:

• Datu-basearen esportazio osoa endpoint bidez
• Backup-etik leheneratzea
• Eragiketa hauetarako zerbitzu dedikatua

Datuen babesa diseinuaren parte da, ez geroagoko gehigarri bat.

Stack teknikoa

• Hizkuntza: Python
• Frameworka: Flask (WSGI)
• Datu-basea: SQLite
• ORM: SQLAlchemy
• Autentifikazioa: JWT
• Testing: pytest, pytest-cov
• CORS: Flask-Cors
• Konfigurazioa: python-dotenv

Operazioa eta despliegua

• Backend-a PythonAnywhere-n desplegatuta
• Eguneratze operatiboa repoan dokumentatuta
• SQLite datu-basea ekoizpenean
• Sistema martxan eta publikoa

🔗 APIa ekoizpenean

🔗 GitHub biltegia

Lan-sistemaren jatorria

Proiektu hau izan zen garapenean AAren erabilera formalizatzen hasi nintzen lehenetariko bat.

docs/ karpetak hau dauka:

• arkitektura kontratuak,
• AA erabiltzeko arau esplizituak,
• oinarrizko txantiloiak,
• errore katalogoak,
• dokumentazioa egia-iturri gisa.

Hemen agertzen dira geroago honetara eboluzionatu zuten kontzeptuak:

• lan gobernatua,
• erabakien itxiera formala,
• rolen bereizketa,
• eta azkenik gaur egun erabiltzen dudan PDCA + orchestrator / executor ikuspegia.

Proiektu honek zer erakusten du

Proiektu honek nire gaitasuna erakusten du:

• Benetako negozio arauekin backend konplexuak diseinatzea
• Arkitektura gobernatu eta hedagarriak eraikitzea
• DDD-ren inguruko printzipioak aplikatzea
• Segurtasuna, kontrola eta trazabilitatea integratzea
• Softwarea ekoizpenean operatzea
• Lan-sistema errepikakor eta kontrolatua eboluzionatzea

Proiektuaren irudiak