L’Agencia Estatal de Administración Tributaria (AEAT) és propietària de l’estructura oficial dels models. API vol dir interfície de programació d’aplicacions.
Publicació de l’autoritat d’execució
L’autoritat d’execució és la publicació amb resum verificat del registre validat de l’AEAT, destinada als càlculs instal·lats i a les exportacions de declaracions. És contingut generat amb dos fitxers: authority.current.json és un descriptor canònic petit, i el seu membre database anomena la càrrega útil exacta authority-<database_sha256>.sqlite3 que hi ha al costat. El descriptor i la base de dades s’admeten junts; la base de dades s’obre en mode només de lectura i no s’hidrata en un únic graf de model per a tot el procés.
El parell es resol des d’un directori, i quin sigui aquest directori depèn de com s’hagi instal·lat Cadrumo. Una distribució instal·lada el porta a cadrumo/_data/registry/authority/ i el resol allà sense configuració. Una còpia de treball publica la seva a .authority/ a l’arrel del repositori, que està exclosa del control de versions, i l’anomena amb la variable d’entorn CADRUMO_AUTHORITY_ROOT. Quan aquesta variable està definida, és la resposta completa: la resolució llegeix el directori indicat i no recorre a la ubicació empaquetada, de manera que una còpia de treball no pot respondre en silenci amb bytes empaquetats que creia haver reemplaçat. Un directori que no conté cap descriptor és una negativa que anomena l’ordre de publicació, no una autoritat buida. Consulteu Publicar una autoritat d’execució validada.
Terme |
Significat |
|---|
Candidat validat |
Les entrades del registre i de les proves d’origen acceptades pel compilador de desenvolupament. |
Rebut de fonts |
Contingut del registre i de les evidències d’origen relatiu a l’arrel, incloses les evidències complementàries mantingudes manualment. |
Rebut del compilador |
Codi relevant de Cadrumo i del compilador, manifestos de dependències, versió major/menor de Python i versions de Pydantic. |
Rebut de components |
Els rebuts de fonts i de compilador vinculats a una única generació d’autoritat completa i nova. |
Resum d’identitat |
La combinació adreçada per contingut d’aquests rebuts, registrada per poder detectar un artefacte obsolet. |
Descriptor d’autoritat |
El selector reemplaçat atòmicament que conté el nom base de la base de dades, el nombre de bytes, el SHA-256 físic i la generació lògica. |
Base de dades d’autoritat |
La publicació SQLite adreçada per contingut que conté els components tipats, les files de dependències i el manifest complet. |
El format del descriptor és cadrumo-authority-descriptor-v1; els seus membres exactes són format, database, database_size, database_sha256 i logical_generation. El format de la base de dades és cadrumo-authority-sqlite-v1. El seu manifest vincula la generació lògica i el directori complet de components. El resum físic de la base de dades és a la vegada la comprovació d’admissió del descriptor i el nom de fitxer adreçat per contingut, de manera que una càrrega útil modificada o en col·lisió es rebutja abans que comenci la feina de l’entorn d’execució.
L’ordre de publicació de desenvolupament és python -m dev.registry.pipeline publish-authority. Escriu a l’arrel d’autoritat configurada i es nega en lloc de triar una ubicació quan no n’hi ha cap configurada; la seva opció --destination selecciona en canvi un directori d’autoritat aïllat. Els valors personalitzats de --registry-root o --source-root han d’anar acompanyats d’un --profile-schema explícit. El paquet del producte que porta les ordres no té cap ordre que compili o repari aquesta publicació.
El rebut de fonts plega el camí relatiu a l’arrel i el resum de contingut de cada fitxer de registre i d’evidència d’origen. Els fitxers de registre converteixen CRLF en LF; l’evidència d’origen és exacta byte a byte. El rebut del compilador també canvia amb el codi font relevant, pyproject.toml, uv.lock, la versió major/menor de Python o les versions instal·lades de pydantic i pydantic-core. Una còpia nova del repositori en el mateix entorn declarat és estable, sense prometre identitat entre entorns de compilació incompatibles.
Cada càrrega útil de component és una projecció canònica compacta d’un valor d’autoritat tipat. Els camps obligatoris sempre s’escriuen; un camp només s’omet quan el seu valor tipat coincideix amb el valor predeterminat declarat pel seu esquema. La rehidratació estricta restaura aquests valors predeterminats. Els discriminadors i les grafies de les unions definides per l’autoria romanen a la representació transmesa, per això la compactació no endevina mai quina variant tipada ha de construir. Els decimals i les dates són cadenes JSON quan l’esquema tipa un camp com a decimal o data. Un valor de fet governat pot ser text, un enter, un decimal, un booleà o una data, i JSON no els pot distingir només pel seu valor. Per tant, tot valor de fet no textual s’escriu com un objecte amb una etiqueta que identifica el seu tipus:
Valor del fet |
S’escriu com |
|---|
Decimal |
{"$decimal": "0.40"}
|
Data |
{"$date": "2025-01-01"}
|
Enter |
{"$int": 5}
|
Booleà |
{"$bool": true}
|
Text |
La cadena JSON nua, per exemple "0.40" |
El temps d’execució descodifica la càrrega útil amb el mateix esquema estricte que utilitza el compilador de desenvolupament. Rebutja una etiqueta desconeguda, un valor etiquetat mal format o no canònic i un valor de fet no textual sense etiqueta; mai no infereix un tipus a partir de la forma d’una cadena.
El compilador, i no l’entorn d’execució del producte, expandeix les diferències d’autoria en revisions canòniques completes. La base de dades també porta catàlegs tipats de l’entorn d’execució per a la normativa de l’IVA, les regles del lloc de realització, els àlies de països, els territoris postals espanyols, les exclusions territorials, les bandes de recàrrec i els àmbits d’apoderament. Són registres congelats de l’esquema, no bytes TOML incrustats ni un contenidor JSON sense tipus. Una escriptura o lectura rebutja una autoritat quan qualsevol catàleg obligatori de l’entorn d’execució és buit.
Els tipus de modelo i del domini fiscal validen la sintaxi estable dels identificadors sense carregar l’arbre d’autoria. L’autoritat compilada n’és la propietària i valida aquests identificadors contra els vocabularis publicats. La mateixa autoritat projecta l’envolupant temporal compartida floor, horizon i hard_ceiling opcional, utilitzada per admetre coordenades compatibles.
La via IndexedRegistryAuthority.operation() no compila fonts, no carrega l’arbre d’autoria sense processar, no ofereix cap ruta de reparació, ni cap dorsal JSON de càrrega total per a l’entorn d’execució, ni cap via alternativa JSON. Un descriptor o una base de dades que faltin produeixen un error de disponibilitat. Un descriptor mal format, un membre inesperat de la base de dades, un manifest incomplet o un component no vàlid produeixen un error de format. Una discrepància de resum del descriptor, de la base de dades o d’un component produeix un error d’integritat. Aquestes fallades passen abans que continuïn els càlculs o les declaracions que depenen de l’autoritat. Els components es carreguen només quan una operació fixada els demana; els valors correctes romanen en una memòria cau limitada a l’àmbit de la generació.
El punt de control C de desenvolupament pot comparar el lector indexat amb una línia base JSON explícita de dev.registry.indexed_authority_benchmark. La línia base s’escriu a partir del mateix AuthorityArtifact validat en memòria que el candidat exacte, conserva la seva identitat de generació lògica i descodifica amb càrrega total la mateixa semàntica pública completa de l’autoritat. El mesurament verifica els bytes físics de la base de dades del descriptor abans de mesurar. La línia base és un accessori de mesurament, no un mòdul del producte ni una via alternativa distribuïda. Els resultats numèrics de latència i memòria continuen pendents fins que el punt de control C s’executi sobre un candidat estable; aquesta descripció de l’API no implica cap guany mesurat.
El contracte de l’entorn d’execució és per a rodes instal·lades en un sistema de fitxers ordinari, on el descriptor i la base de dades SQLite tenen camins físics estables. No s’admet l’execució directa per importació des d’un zip: SQLite no pot obrir un membre d’arxiu comprimit com la seva base de dades de només lectura.
python -m dev.registry.conformance integrity rebutja una publicació descriptor/base de dades el resum d’identitat registrat de la qual difereix de la identitat del registre actiu i del seu entorn de compilació. Consulteu Publicar una autoritat d’execució validada per conèixer l’ordre canònica, les garanties de publicació, les comprovacions d’actualitat i la ruta de recuperació.