tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Archive: System v4 - Estado al 2024-12-24

Browse Source
This commit is contained in:
ARCHITECT
2025-12-24 17:28:34 +00:00
parent a92d41c846
commit 1b392803fd
81 changed files with 24560 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
v4-archive/hst/README.md Normal file
View File

@@ -0,0 +1,47 @@
# HST - Hierarchical Semantic Tags
## Servidor
- IP: 72.62.2.84
- Directus: http://72.62.2.84:8055
## Base de Datos
- DB: `hst_images`
- Usuario: nocodb
- 973 tags en 5 tablas
## Tablas
| Tabla | Registros | Descripción |
|-------|-----------|-------------|
| hst | 658 | Tags históricos |
| spe | 145 | Especialidades |
| vsn | 84 | Versiones |
| flg | 65 | Flags |
| vue | 21 | Vistas |
## API Pública
### Endpoints
```
GET /items/hst
GET /items/spe
GET /items/vsn
GET /items/flg
GET /items/vue
```
### Ejemplo
```bash
curl http://72.62.2.84:8055/items/hst?limit=10
```
## Containers Docker
- directus_hst (8055)
- postgres_hst (5432)
- hst-images (80/443) - nginx proxy
- filebrowser (8081)
## Acceso Admin
- URL: http://72.62.2.84:8055
- Email: admin@tzzr.systems
- Password: tzzr2024

128
v4-archive/hst/docs/API.md Normal file
View File

@@ -0,0 +1,128 @@
# HST Image Server API
## Base URL
```
https://tzrtech.org
```
## Endpoints
### GET /api/index.json
Returns all tables with their records.
**Response:**
```json
{
"_meta": {
"version": "1.1",
"updated": "2024-12-17T12:00:00Z",
"base_url": "https://tzrtech.org",
"image_url_pattern": "https://tzrtech.org/{mrf}.png",
"subdomain_pattern": "https://{ref}_{nombre}.tzrtech.org",
"tables": ["flg", "hst", "spe", "vue", "vsn"]
},
"hst": {
"count": 150,
"records": [
{
"ref": "ABC",
"nombre_es": "Nombre en español",
"nombre_en": "Name in English",
"mrf": "sha256hash...",
"rootref": "XYZ"
}
]
},
"flg": { ... },
"spe": { ... },
"vue": { ... },
"vsn": { ... }
}
```
## Image Access
### Direct URL
```
https://tzrtech.org/{mrf}.png
```
Example:
```
https://tzrtech.org/a1b2c3d4e5f6...png
```
### Subdomain URL
```
https://{ref}_{nombre}.tzrtech.org
```
Example:
```
https://crg_courage.tzrtech.org
```
This redirects to the direct image URL.
## Tables
| Table | Description |
|-------|-------------|
| `hst` | Hashtags - main semantic tags |
| `spe` | Specs - specifications |
| `flg` | Flags - status indicators |
| `vue` | Values - human values |
| `vsn` | Visions - archetypal visions |
## Record Schema
| Field | Type | Description |
|-------|------|-------------|
| `ref` | string | 3-letter unique code |
| `nombre_es` | string | Spanish name |
| `nombre_en` | string | English name |
| `mrf` | string | SHA-256 hash of image file |
| `rootref` | string | Parent reference (hierarchy) |
## Usage Examples
### JavaScript
```javascript
const response = await fetch('https://tzrtech.org/api/index.json');
const data = await response.json();
// Get all values
const values = data.vue.records;
// Build image URL
const imageUrl = `https://tzrtech.org/${values[0].mrf}.png`;
```
### Python
```python
import requests
response = requests.get('https://tzrtech.org/api/index.json')
data = response.json()
# Get all hashtags
hashtags = data['hst']['records']
# Build image URL
image_url = f"https://tzrtech.org/{hashtags[0]['mrf']}.png"
```
## CORS
The API allows cross-origin requests:
```
Access-Control-Allow-Origin: *
```

394
v4-archive/hst/docs/spec/HST_ROADMAP_v1.md Normal file
View File

@@ -0,0 +1,394 @@
# HST - Roadmap de Implementación
**Versión:** 1.0
**Fecha:** 2025-12-07
**Estado:** Borrador para maduración
---
# Visión General
El sistema HST (Hash Semantic Tagging) evolucionará en 4 fases, desde especificación formal hasta una aplicación cliente universal de drag & drop.
```
Fase 0 Fase 1 Fase 2 Fase 3
SPEC → Servidor → Descentralización → App Cliente
(Documentos) (KVM1 Hostinger) (Filecoin/IPFS) (Drag & Drop)
```
---
# Fase 0: Especificación Formal
## Objetivo
Documento definitivo que describe el sistema completo antes de cualquier implementación.
## Entregables
| Documento | Descripción | Estado |
|-----------|-------------|--------|
| `SPEC.md` | Especificación técnica completa del sistema HST | Pendiente |
| `SCHEMA.md` | Modelo de datos para NocoDB/PostgreSQL | Pendiente |
| `TAGS_v1.csv` | Listado consolidado de etiquetas (~850) | En progreso |
| `HIERARCHY.md` | Árbol jerárquico de categorías | Pendiente |
| `RELATIONS.md` | Grafo de relaciones entre etiquetas | Pendiente |
| `API.md` | Especificación de endpoints REST | Pendiente |
| `STYLES.md` | Tabla de estilos (4096 skins) | Pendiente |
## Contenido de SPEC.md
1. Filosofía del sistema
2. Imagen primigenia (reglas)
3. Hash maestro (H_maestro)
4. Extensiones (EXT, HSU, SP, SPU, PRJ)
5. Sistema de estilos (hash visible)
6. Cadena de metadatos (jerarquía)
7. Propiedad y acceso (H_propiedad, H_acceso)
8. Bibliotecas (sistema, empresa, usuario)
9. Pipeline de importación
10. Integración con ecosistema (SFE, IA, n8n)
## Criterios de salida
- [ ] Todos los documentos revisados y aprobados
- [ ] Sin ambigüedades técnicas
- [ ] Listado de etiquetas limpio y categorizado
---
# Fase 1: Servidor Centralizado
## Objetivo
Primera implementación funcional en servidor KVM1 de Hostinger.
## Infraestructura
```
KVM1 Hostinger
├── Docker
│ ├── NocoDB (metadatos)
│ ├── PostgreSQL (base de datos)
│ └── API HST (FastAPI/Node)
├── /hst/
│ ├── primigenias/{H_maestro}.png
│ └── skins/{hash_visible}.png
└── Nginx (proxy + SSL)
```
## Componentes
| Componente | Tecnología | Función |
|------------|------------|---------|
| Base de datos | PostgreSQL | Almacén principal |
| Interfaz datos | NocoDB | Gestión visual de etiquetas |
| API REST | FastAPI | Consulta/servicio de etiquetas |
| Almacenamiento | Sistema de archivos | Imágenes primigenias y skins |
| Proxy | Nginx | SSL + routing |
| Orquestación | n8n (Alfred) | Pipelines de importación |
## Funcionalidades
### 1. Gestión de etiquetas
- CRUD completo vía NocoDB
- Validación de imagen primigenia (sin metadatos)
- Cálculo automático de H_maestro
- Generación de skins
### 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
GET /api/v1/tags/{h_maestro}/skins # Listar skins
POST /api/v1/tags # Crear etiqueta
GET /api/v1/search?q=... # Buscar por nombre/código
GET /api/v1/hierarchy/{ref} # Obtener árbol jerárquico
```
### 3. Pipeline de importación
1. Leer desde Airtable (fuente actual)
2. Descargar imagen
3. Limpiar metadatos
4. Calcular SHA-256 → H_maestro
5. Generar estructura de metadatos
6. Subir primigenia
7. Generar skins (según tabla de estilos)
8. Registrar en NocoDB
### 4. Subdominio
- `hst.tzzr.pro` o `tags.tzzr.pro`
## Criterios de salida
- [ ] API funcional con todos los endpoints
- [ ] ~850 etiquetas migradas desde Airtable
- [ ] Pipeline de importación automatizado
- [ ] Documentación de API generada
---
# Fase 2: Descentralización
## Objetivo
Servicio multi-usuario escalable con almacenamiento descentralizado.
## Arquitectura
```
┌─────────────────────────────────────────────────────────┐
│ CAPA DE USUARIOS │
│ App Web │ App Desktop │ App Móvil │ Extensión │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ Auth + Rate Limiting + Routing │
└─────────────────────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ NocoDB/PostgreSQL │ │ Redis │ │ Filecoin/IPFS │
│ (Índice/Metadatos)│ │ (Cache) │ │ (Imágenes) │
└─────────────────┘ └─────────────┘ └─────────────────┘
```
## Componentes nuevos
| Componente | Función |
|------------|---------|
| Filecoin/IPFS | Almacenamiento descentralizado de imágenes |
| CID (Content ID) | Referencia inmutable a cada imagen |
| Sistema de bibliotecas | Pública, privada, por usuario |
| Autenticación | JWT + H_propiedad |
| Permisos | Control por H_acceso |
| Rate limiting | Protección de API pública |
## Tipos de biblioteca
| Tipo | Propiedad | Acceso | Descripción |
|------|-----------|--------|-------------|
| Sistema | HST | Público | Etiquetas base universales |
| Empresa | Organización | Miembros | Etiquetas corporativas |
| Usuario | Individual | Personal | Etiquetas propias |
| Compartida | Múltiple | Definido | Colaboración entre usuarios |
## Modelo de datos extendido
```
Etiqueta {
h_maestro: string (PK)
codigo_corto: string
nombres: { es, en, zh... }
extension: EXT | HSU | SP | SPU | PRJ
# Almacenamiento
cid_primigenia: string # IPFS/Filecoin
cid_skins: [string] # Array de CIDs
# Metadatos
cadena_metadatos: [string] # Jerarquía de hashes
h_propiedad: string # Biblioteca propietaria
h_acceso: string # Nivel de acceso
# Auditoría
created_at: timestamp
created_by: string
version: int
}
```
## Flujo de resolución
```
1. Cliente solicita etiqueta por H_maestro
2. API busca en caché Redis
3. Si no existe → busca en NocoDB (índice)
4. Obtiene CID de Filecoin/IPFS
5. Resuelve imagen desde red descentralizada
6. Cachea resultado
7. Retorna al cliente
```
## Criterios de salida
- [ ] Imágenes almacenadas en Filecoin/IPFS
- [ ] Sistema de bibliotecas funcionando
- [ ] Autenticación y permisos implementados
- [ ] API pública documentada y protegida
- [ ] Al menos 3 bibliotecas de prueba (sistema, empresa, usuario)
---
# Fase 3: Aplicación Cliente
## Objetivo
Aplicación universal de drag & drop para usar etiquetas HST en cualquier software.
## Plataformas
| Plataforma | Tecnología | Prioridad |
|------------|------------|-----------|
| Desktop (Windows/Mac/Linux) | Tauri o Electron | Alta |
| Web | React/Vue | Alta |
| Móvil (iOS/Android) | React Native o Flutter | Media |
| Extensión Chrome/Firefox | WebExtension | Media |
| Plugin Office | Office Add-in | Baja |
| Plugin Figma | Figma API | Baja |
## Funcionalidades core
### 1. Navegador de etiquetas
- Vista en árbol (jerarquía)
- Vista en grid (visual)
- Búsqueda por nombre/código/hash
- Filtros por extensión/biblioteca
### 2. Drag & Drop
- Arrastrar etiqueta a cualquier aplicación
- Formatos de salida:
- Imagen PNG
- Código corto (texto)
- Hash (texto)
- Markdown `![nombre](url)`
- HTML `<img src="url">`
### 3. Gestión de bibliotecas
- Ver bibliotecas disponibles
- Suscribirse a bibliotecas públicas
- Crear biblioteca personal
- Sincronización offline
### 4. Creación de etiquetas (usuarios)
- Subir imagen primigenia
- Asignar código y nombres
- Seleccionar extensión (HSU, SPU, PRJ)
- Proponer para validación (opcional)
## Flujo de usuario
```
1. Usuario abre app HST
2. Navega/busca etiqueta deseada
3. Arrastra etiqueta
4. Suelta en aplicación destino (Word, Figma, etc.)
5. La etiqueta se inserta como imagen/texto según contexto
```
## Integración con sistema operativo
| OS | Método |
|----|--------|
| Windows | Clipboard API + Shell Extension |
| macOS | NSPasteboard + Finder Extension |
| Linux | X11/Wayland Clipboard |
## Modelo de monetización (futuro)
| Tier | Precio | Incluye |
|------|--------|---------|
| Free | 0€ | Biblioteca pública, 10 etiquetas propias |
| Pro | 5€/mes | Bibliotecas ilimitadas, skins premium |
| Enterprise | Personalizado | Bibliotecas privadas, soporte, SLA |
## Criterios de salida
- [ ] App desktop funcional (1 plataforma mínimo)
- [ ] Drag & drop funcionando en apps comunes
- [ ] Sincronización con servidor HST
- [ ] Documentación de usuario
---
# Dependencias entre fases
```
Fase 0 ──────► Fase 1 ──────► Fase 2 ──────► Fase 3
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
SPEC.md Servidor Filecoin App
SCHEMA.md NocoDB Auth Desktop
TAGS.csv API REST Bibliotecas Drag&Drop
Pipeline Permisos Móvil
```
---
# H_propiedad y H_acceso (PENDIENTE DEFINIR)
## H_propiedad - Definición parcial
Identifica el propietario/origen de la etiqueta.
| Grupo | H_propiedad |
|-------|-------------|
| `hst` | Hash de la etiqueta "hst" (sistema) |
| `spe` | Hash de la etiqueta "especificación" (sistema) |
| `hsu` | Hash del usuario creador |
| `msu` | Hash del usuario creador |
## H_acceso - Por definir
Llave de acceso para descarga de imagen. Relacionado con:
- Sistema de monetización futuro
- Compartición de bibliotecas entre usuarios
- Colaboración en proyectos (msu)
**Notas:**
- Se exploró embeber en metadatos PNG pero no está validado
- Inicialmente innecesario: la cadena estará en NocoDB
- Los grupos hsu/msu permiten compartición (por definir mecanismo)
- Diferenciación de grupos define reglas de acceso diferentes
**TODO para próximas revisiones:**
- [ ] Definir mecanismo de compartición de bibliotecas usuario
- [ ] Definir modelo de monetización y su relación con H_acceso
- [ ] Validar si metadatos embebidos en PNG son viables
- [ ] Definir permisos de colaboración en proyectos (msu)
---
# Preguntas abiertas (a resolver)
## Fase 0
- [x] ¿Formato definitivo de código corto? → Variable según grupo
- [ ] ¿Cuántos estilos iniciales implementar?
- [x] ¿Estructura exacta de cadena_metadatos? → Definida parcialmente
## Fase 1
- [ ] ¿Dominio/subdominio para el servicio?
- [ ] ¿Migración completa desde Airtable o parcial?
- [ ] ¿Autenticación desde Fase 1 o solo Fase 2?
## Fase 2
- [ ] ¿Filecoin vs IPFS vs ambos?
- [ ] ¿Modelo de costos de almacenamiento descentralizado?
- [ ] ¿Política de bibliotecas públicas (quién puede publicar)?
## Fase 3
- [ ] ¿Prioridad de plataformas?
- [ ] ¿Modelo freemium desde el inicio?
- [ ] ¿Integración con marketplaces de plugins?
---
# Timeline estimado
| Fase | Duración estimada | Dependencias |
|------|-------------------|--------------|
| Fase 0 | 1-2 semanas | Ninguna |
| Fase 1 | 2-4 semanas | Fase 0 completa |
| Fase 2 | 4-8 semanas | Fase 1 estable |
| Fase 3 | 8-12 semanas | Fase 2 funcional |
**Total estimado:** 4-6 meses para MVP completo
---
# Notas
- Este roadmap es un documento vivo que evolucionará
- Cada fase tiene criterios de salida claros
- Las fases pueden solaparse parcialmente
- Priorizar funcionalidad sobre perfección en cada fase
---
**Próximo paso:** Consolidar SPEC.md (Fase 0)

459
v4-archive/hst/docs/spec/HST_SPEC_v1.md Normal file
View File

@@ -0,0 +1,459 @@
# 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**