14 · Arquitectura, estil de programació i SQL configurable

◀ Tornar a l'índex

Aquest capítol resumeix les regles tècniques amb què evoluciona Factuzam. S'adreça a desenvolupament, suport avançat i implantadors. La referència completa del repositori es manté a LIBRO_DE_ESTILO_DELPHI.md, LIBRO_DE_ESTILO_BBDD.md, PLAN_SOLID.md i MANUAL_SQL_PERFILES.md.

1. Estil de programació

Factuzam està escrit en Object Pascal/Delphi VCL i prioritza un codi llegible, previsible i compatible amb la base instal·lada.

Regles principals:

Codi, noms propis, comentaris i commits en espanyol; es respecten els prefixos de Delphi i dels components de tercers.
Una instrucció per línia. if, while i for situen la condició i l'acció en línies separades.
S'eviten Exit i Continue al codi nou per mantenir visible tot el flux del mètode.
A cada secció d'una classe es declaren primer els camps i després els mètodes, tal com exigeix Delphi.
Els comentaris són breus i expliquen decisions, límits o regles de negoci; no repeteixen una línia evident.
Els mètodes es denominen amb verbs en espanyol i han de representar un pas cohesiu. Abans d'ampliar una classe gran se n'extreu un col·laborador, una estratègia o una funció de domini.
Els formularis de manteniment hereten de TfrmMtoGen i els modals de TfrmBase; les utilitats independents conserven el seu propi projecte.
Es mantenen UniDAC, DevExpress, JEDI i FastReport com a decisions d'arquitectura; no se substitueixen per dependències noves sense justificació.

Els canvis de la base de dades es lliuren com a scripts idempotents a DESARROLLOS EN CURSO/. El dump factuzam_original.sql no es modifica.

2. SOLID aplicat progressivament

Factuzam està migrant per fascicles des d'un nucli heretat cap a una arquitectura SOLID. No es presenta com una reescriptura acabada: cada extracció fixa primer el comportament amb proves i redueix l'acoblament sense barrejar-hi canvis funcionals.

Principi	Aplicació a Factuzam
SRP — responsabilitat única	El formulari coordina la interfície, el data module persisteix i les llibreries executen regles de negoci. Les responsabilitats grans s'extreuen a col·laboradors `TGestor*` o serveis específics.
OCP — obert/tancat	Les variacions de compra, venda, impressió o document es modelen amb configuració i estratègies, evitant copiar formularis complets per a cada cas.
LSP — substitució	Les classes base publiquen contractes i hooks coherents; s'evita ampliar una base quan els descendents haurien d'anul·lar-ne el comportament amb mètodes buits.
ISP — interfícies petites	Cada consumidor només rep la capacitat que necessita. Les interfícies pròpies són petites, tenen GUID i només s'agrupen quan comparteixen una mateixa implementació.
DIP — inversió de dependències	El domini depèn de contractes `inLib*Intf`; les implementacions UniDAC es creen a fora i s'injecten des de l'arrel de composició.

La seqüència d'un fascicle és: prova que fixa el comportament, extracció d'una responsabilitat, compilació Win32/Win64, bateria DUnitX i comprovació dels trinquets automàtics d'arquitectura.

3. Capes i direcció de les dependències

fzam.dpr / Core (composición)
            |
            v
Forms / Modals (presentación y coordinación)
            |
            v
UniData* (persistencia) ---> inLib* (dominio y colaboradores)
                                  |
                                  v
                            inLib*Intf (contratos)

Capa	Responsabilitat
Core / composició	Crea connexions, repositoris, serveis i formularis; connecta implementacions amb contractes.
Forms / Modals	Mostra dades, sol·licita confirmacions, coordina pestanyes i tradueix resultats de negoci en accions visuals.
UniData / DataModules	Consulta i persisteix mitjançant UniDAC, controla datasets i límits transaccionals.
inLib	Càlculs, validacions, transformacions, orquestradors i col·laboradors reutilitzables.
*inLibIntf**	Interfícies i tipus estables sense dependències de VCL, formularis ni implementacions de persistència.

Una llibreria de domini no crea cap repositori, no coneix cap formulari i no obté una connexió global. Rep per constructor o paràmetre el contracte que necessita. Les connexions, la identitat i les credencials tenen un propietari i un cicle de vida explícits.

Les escriptures que afecten diverses taules són atòmiques: respecten una transacció existent o fan Commit/Rollback al mateix nivell. Els fils no comparteixen datasets ni connexions amb la interfície.

4. Consultes SQL configurables i consultables

El catàleg SQL per perfils permet corregir determinades consultes de lectura sense recompilar ni substituir fzam.exe. El domini sol·licita una operació de negoci a un repositori; la implementació de persistència tria entre:

L'SQL base, inclòs i provat amb l'executable.
Un SQL personalitzat actiu a fza_usuarios_perfiles.

El domini no rep text SQL ni ofereix cap mètode genèric Ejecutar(SQL). Cada operació manté una clau estable amb aquesta forma:

KEY_USUPER    = SQL_REPOSITORIOS
SUBKEY_USUPER = SQL__Repositorio__Operacion

Activació per pantalla

La propietat de perfil oGetSQLFromDB activa el catàleg per a cada formulari consumidor. En obrir la pantalla:

Factuzam carrega les definicions del catàleg compartit.
Publica les operacions base que encara faltin, sense sobreescriure cap personalització existent.
Resol cada lectura contra el perfil actiu o contra l'SQL base.

Desactivar l'interruptor en un formulari no canvia els altres consumidors de la mateixa operació.

L'inventari d'unitats que llegeixen l'interruptor, publiquen perfils o aporten definicions al catàleg, juntament amb el recorregut històric dels data modules, es troba a MANUAL_SQL_PERFILES.md.

Validació i fallback segur

Abans d'executar una personalització es comprova que:

no sigui buida;
sigui una lectura vàlida (SELECT o CALL amb dataset);
conservi exactament els paràmetres declarats;
retorni tots els camps i àlies obligatoris;
no contingui diverses sentències;
no inclogui DROP, ALTER ni TRUNCATE.

Si la validació falla, la consulta personalitzada es descarta, se'n registra la causa i s'executa l'SQL base. Si supera la validació però falla en obrir-se o retorna una estructura incorrecta, Factuzam ho torna a intentar una vegada amb l'SQL base. Si també falla la base, l'error es mostra de manera normal.

Les escriptures no utilitzen aquest reintent automàtic: qualsevol personalització futura d'escriptura ha d'estar protegida per transacció i fer Rollback abans de canviar d'implementació.

Revisió, auditoria i marxa enrere

L'administrador del catàleg permet publicar, revisar i exportar les definicions base i de perfil. La revisió mostra l'estat, la política, la versió, les empremtes, la validació i l'última causa de fallback. Cada fila també desa l'instant i l'usuari de modificació.

Per tornar immediatament al comportament inclòs a l'executable es pot:

Desactivar una operació canviant-ne l'estat de S a N.
Eliminar únicament la seva fila personalitzada.
Establir oGetSQLFromDB=False per a tota la pantalla.

No cal desplegar cap altre executable. Abans d'editar una consulta es fa una còpia de l'SQL i de les seves metadades; mai no es canvien els paràmetres ni els àlies exigits pel contracte.

5. Proves i regles de no regressió

DUnitX cobreix funcions de domini, col·laboradors i repositoris falsos sense necessitat d'una base de dades real.
Les proves d'integració cobreixen procediments, SQL i transaccions.
Els scripts de trinquet impedeixen reintroduir dependències de capes, SQL nou al domini, variables globals o creixement de classes i mètodes per sobre dels límits vigents.
Una refactorització no barreja canvis funcionals, canvis massius de nom ni normalitzacions de format.
Abans de tancar un canvi transversal es validen les plataformes Win32 i Win64 afectades.

La finalitat és que cada millora deixi una barrera automàtica que el codi posterior no pugui tornar a travessar.

◀ Aplicacions mòbils · Índex · Següent ▶ Integració amb PrestaShop