tzzr/system-docs

Fork 0

Files

ARCHITECT 1b392803fd Archive: System v4 - Estado al 2024-12-24

2025-12-24 17:28:34 +00:00

12 KiB

Raw Blame History

HST - Especificación Técnica

Sistema de Etiquetado Semántico basado en Hashes

Versión: 1.0
Fecha: 2025-12-10
Estado: Borrador para implementación

1. Visión General

1.1 Propósito

HST (Hash Semantic Tagging) es un sistema de etiquetado universal que:

Representa conceptos mediante imágenes e identificadores criptográficos
Desvincula el significado del lenguaje humano
Permite múltiples estilos visuales sin alterar la semántica
Soporta bibliotecas de sistema y de usuario
Está diseñado para uso en documentos, presentaciones y aplicaciones profesionales

1.2 Principios fundamentales

Identidad inmutable: El hash SHA-256 de la imagen primigenia es la referencia absoluta
Separación semántica/visual: Los estilos no alteran el significado
Códigos memorizables: Agilidad de uso mediante códigos cortos
Jerarquía flexible: Múltiples árboles y relaciones entre etiquetas
Extensibilidad: Usuarios pueden crear etiquetas propias

2. Imagen Primigenia

2.1 Definición

La imagen primigenia es el archivo visual origen de cada etiqueta.

2.2 Requisitos

Formato: PNG (por defecto), extensible a otros formatos
Sin metadatos: EXIF, ICC, XMP eliminados
Archivo limpio y 100% reproducible
Cualquier cambio genera un concepto diferente

2.3 Proceso de limpieza

1. Recibir imagen original
2. Eliminar todos los metadatos (EXIF, ICC, XMP)
3. Normalizar canal Alpha si existe
4. Resultado: Buffer binario puro

3. Hash Maestro (H_maestro)

3.1 Generación

H_maestro = SHA256(imagen_primigenia_limpia)

3.2 Propiedades

Longitud: 64 caracteres hexadecimales
Inmutable: nunca cambia para una imagen dada
Único: identifica el concepto de forma absoluta
Independiente del nombre, idioma o estilo visual

3.3 Ejemplo

Imagen: factura.png (limpia)
H_maestro: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

4. Sistema de Estilos (Skins)

4.1 Propósito

Permitir múltiples variantes visuales de un concepto sin alterar su identidad.

4.2 Capacidad

4 caracteres hexadecimales = 65,536 estilos posibles (0000-FFFF)
Estilo 0000 reservado implícitamente (no se usa, la primigenia no lleva estilo)

4.3 Algoritmo de hash visible

Entrada:
  H_maestro (64 chars): a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
  estilo (4 chars): 0A3F

Proceso:
  1. Tomar primeros 60 caracteres de H_maestro
  2. Dividir en dos mitades de 30 caracteres
     - H_left = chars 0-29
     - H_right = chars 30-59
  3. Descartar últimos 4 caracteres (60-63)
  4. Insertar estilo entre las dos mitades

Resultado:
  hash_visible = H_left + estilo + H_right
  hash_visible = a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5 + 0A3F + p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0

4.4 Almacenamiento

Tipo	Hash	Ruta
Primigenia	H_maestro completo (64 chars)	`/hst/primigenias/{H_maestro}.png`
Skin	hash_visible (64 chars)	`/hst/skins/{hash_visible}.png`

4.5 Comportamiento

La imagen primigenia se almacena con H_maestro original (sin modificar)
Cada skin se almacena con su hash_visible calculado
En base de datos siempre se guarda H_maestro como referencia

5. Grupos y Extensiones

5.1 Definición de grupos

Grupo	Propiedad	Memorizable	Formato código	Descripción
`hst`	Sistema	✅ Sí	Alfabético único	Etiquetas semánticas base
`spe`	Sistema	❌ No	"spe" repetido	Especificaciones técnicas
`hsu`	Usuario	❌ No	"hsu" repetido	Etiquetas de usuario
`msu`	Usuario	✅ Sí	Ordinal (001-999)	Proyectos de usuario

5.2 Filosofía de códigos

Códigos memorizables (hst, msu):

Objetivo: agilizar uso mediante memorización
Ejemplos: inv (factura), dnt (albarán), 105 (proyecto)

Códigos repetidos (spe, hsu):

Objetivo: indicar categoría, no identificar
El hash es la referencia real
Compromiso entre utilidad y limpieza de biblioteca

5.3 Ejemplos

Etiqueta sistema memorizable:
  grupo: "hst"
  codigo: "inv"
  nombre_es: "factura"
  nombre_en: "invoice"

Especificación sistema:
  grupo: "spe"
  codigo: "spe"
  nombre_es: "dc 24v"
  nombre_en: "dc 24v"

Etiqueta usuario:
  grupo: "hsu"
  codigo: "hsu"
  nombre_es: "mi concepto"

Proyecto usuario:
  grupo: "msu"
  codigo: "105"
  nombre_es: "SAGRADA FAMILIA 25"

6. Cadena de Metadatos

6.1 Estructura

cadena_metadatos: [
  H_maestro_raiz,
  H_maestro_nivel1,
  H_maestro_nivel2,
  ...,
  H_maestro_actual,
  H_propiedad,
  H_acceso
]

6.2 Componentes

Posición	Campo	Descripción
0..n-3	Jerarquía	Hashes de ancestros hasta raíz
n-2	H_maestro	Hash de la etiqueta actual
n-1	H_propiedad	Propietario (ver sección 7)
n	H_acceso	Llave de acceso (ver sección 8)

6.3 Cadena de códigos (auxiliar)

Para legibilidad humana, se mantiene cadena de códigos separada por guiones:

jerarquia_codigos: "mhs-flg-rul-spc-spe"

7. H_propiedad

7.1 Definición

Identifica el propietario/origen de la etiqueta.

7.2 Valores según grupo

Grupo	H_propiedad
`hst`	Hash de la etiqueta "hst" del sistema
`spe`	Hash de la etiqueta "especificación" del sistema
`hsu`	Hash del identificador de usuario creador
`msu`	Hash del identificador de usuario creador

7.3 Nota

La implementación exacta se definirá con el sistema de usuarios y monetización.

8. H_acceso

8.1 Definición

Llave de acceso que controla quién puede descargar/usar la imagen.

8.2 Estado

PENDIENTE DEFINIR

Relacionado con:

Sistema de monetización futuro
Compartición de bibliotecas entre usuarios
Colaboración en proyectos (msu)

8.3 Notas para implementación futura

Inicialmente la cadena completa estará en NocoDB
Se exploró embeber en metadatos PNG (pendiente validar viabilidad)
Los grupos hsu/msu permiten compartición (mecanismo por definir)
Diferenciación de grupos define reglas de acceso diferentes

9. Schema de Base de Datos

9.1 Tabla: hst_tags

Almacena todas las etiquetas del sistema.

Campo	Tipo	Restricciones	Descripción
id	UUID	PK	Identificador interno
h_maestro	CHAR(64)	UNIQUE, NOT NULL	Hash SHA-256 de imagen primigenia
grupo	ENUM	NOT NULL	hst, spe, hsu, msu
codigo	VARCHAR(10)	NOT NULL	Código memorizable o repetido
nombre_es	VARCHAR(255)	NOT NULL	Nombre en español
nombre_en	VARCHAR(255)		Nombre en inglés
imagen_url	VARCHAR(500)		URL temporal (migración)
h_propiedad	CHAR(64)		Hash de propietario
h_acceso	CHAR(64)		Llave de acceso
created_at	TIMESTAMP	DEFAULT NOW()	Fecha creación
metadata	JSONB		Datos extensibles

9.2 Tabla: hst_trees

Define árboles jerárquicos. Una etiqueta puede aparecer en múltiples árboles.

Campo	Tipo	Restricciones	Descripción
id	UUID	PK	Identificador interno
tree_name	VARCHAR(100)	NOT NULL	Nombre del árbol
h_maestro	CHAR(64)	FK → hst_tags	Etiqueta
h_padre	CHAR(64)	FK → hst_tags, NULL	Padre (null = raíz)
orden	INT		Posición entre hermanos
rango	INT		Profundidad en árbol

9.3 Tabla: hst_relations

Grafo de relaciones entre etiquetas. Direccional con peso.

Campo	Tipo	Restricciones	Descripción
id	UUID	PK	Identificador interno
h_from	CHAR(64)	FK → hst_tags	Etiqueta origen
h_to	CHAR(64)	FK → hst_tags	Etiqueta destino
peso	DECIMAL		Fuerza de relación (0-1)
tipo	VARCHAR(50)		related, part_of, type_of...
metadata	JSONB		Datos extensibles

9.4 Tabla: hst_skins

Estilos disponibles por etiqueta.

Campo	Tipo	Restricciones	Descripción
id	UUID	PK	Identificador interno
h_maestro	CHAR(64)	FK → hst_tags	Etiqueta base
estilo	CHAR(4)	NOT NULL	Código de estilo (0000-FFFF)
hash_visible	CHAR(64)	UNIQUE	Hash calculado con estilo
nombre	VARCHAR(50)		Nombre del estilo
tipo	VARCHAR(20)		basic, premium, custom

10. Estructura de Archivos

10.1 Directorios

/hst/
├── primigenias/
│   └── {H_maestro}.png
└── skins/
    └── {hash_visible}.png

10.2 Reglas

Primigenias: siempre con H_maestro original completo
Skins: siempre con hash_visible calculado
Formato PNG por defecto
Sin metadatos embebidos (inicialmente)

11. Pipeline de Importación

11.1 Desde Airtable (migración inicial)

1. Leer registro de Airtable
2. Descargar imagen desde URL
3. Limpiar metadatos (EXIF, ICC, XMP)
4. Calcular SHA-256 → H_maestro
5. Determinar grupo (hst, spe, hsu, msu)
6. Renombrar archivo → {H_maestro}.png
7. Subir a /hst/primigenias/
8. Crear registro en NocoDB (hst_tags)
9. Crear entradas en hst_trees según jerarquía
10. Actualizar referencias

11.2 Nueva etiqueta (flujo normal)

1. Usuario sube imagen
2. Sistema limpia metadatos
3. Calcula H_maestro
4. Verifica unicidad (no duplicados)
5. Asigna grupo y código
6. Almacena primigenia
7. Crea registro en base de datos
8. Genera skins si aplica

12. Integraciones

12.1 n8n (Alfred)

Pipeline de importación automatizado
Asignación de etiquetas en flujos OCR
Sincronización con Airtable (migración)

12.2 API REST

GET  /api/v1/tags                     # Listar etiquetas
GET  /api/v1/tags/{h_maestro}         # Obtener etiqueta
GET  /api/v1/tags/{h_maestro}/image   # Obtener imagen primigenia
GET  /api/v1/tags/{h_maestro}/skins   # Listar skins
POST /api/v1/tags                     # Crear etiqueta
GET  /api/v1/search?q=...             # Buscar
GET  /api/v1/trees/{tree_name}        # Obtener árbol
GET  /api/v1/relations/{h_maestro}    # Obtener relaciones

12.3 Futuro: App Cliente

Drag & drop universal
Sincronización de bibliotecas
Creación de etiquetas usuario

13. Consideraciones de Seguridad

13.1 Integridad

H_maestro garantiza integridad de imagen
Cualquier alteración genera hash diferente
Verificación posible en cualquier momento

13.2 Acceso

H_acceso controlará permisos (pendiente definir)
Grupos definen reglas base de visibilidad
Sistema vs usuario claramente separados

13.3 Almacenamiento

Rutas públicas pero no indexadas
Migración futura a almacenamiento descentralizado (Filecoin/IPFS)

14. Glosario

Término	Definición
H_maestro	Hash SHA-256 de imagen primigenia (64 chars)
hash_visible	Hash con estilo insertado (64 chars)
Imagen primigenia	Archivo imagen sin metadatos, origen del concepto
Skin	Variante visual de una etiqueta
Grupo	Categoría de etiqueta (hst, spe, hsu, msu)
Código	Identificador corto memorizable
Cadena de metadatos	Array de hashes: jerarquía + propiedad + acceso

15. Pendientes y TODOs

Definición

Mecanismo de compartición de bibliotecas usuario
Modelo de monetización y relación con H_acceso
Validar viabilidad de metadatos embebidos en PNG
Permisos de colaboración en proyectos (msu)
Definir estilos iniciales a implementar

Implementación

Pipeline de limpieza de metadatos
Cálculo de H_maestro para etiquetas existentes
Migración desde Airtable
API REST
Integración n8n

16. Historial de Cambios

Versión	Fecha	Cambios
1.0	2025-12-10	Versión inicial

Fin del documento

12 KiB Raw Blame History