460 lines
12 KiB
Markdown
460 lines
12 KiB
Markdown
# 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
|
|
|
|
1. **Identidad inmutable**: El hash SHA-256 de la imagen primigenia es la referencia absoluta
|
|
2. **Separación semántica/visual**: Los estilos no alteran el significado
|
|
3. **Códigos memorizables**: Agilidad de uso mediante códigos cortos
|
|
4. **Jerarquía flexible**: Múltiples árboles y relaciones entre etiquetas
|
|
5. **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**
|