Base de datos workspace · arquitectura técnica

Referencia técnica del esquema D1 del workspace. Para una explicación accesible ve a [[workspace-tech—bd—coloquial]].

1. Stack de persistencia

Bindings (wrangler.toml)

[[d1_databases]]
binding = "DB"
database_name = "crearacksl-workspace-db"
database_id = "<uuid>"

[[r2_buckets]]
binding = "R2"
bucket_name = "crearacksl-workspace-blobs"

[[vectorize]]
binding = "VECTORIZE"
index_name = "bib-chunks-embeddings"

Limitaciones D1 documentadas (footguns)

2. Migrations · estado actual

30 migrations aplicadas (migrations/ en el repo workspace):

Aplicar migrations

# Local dev
pnpm wrangler d1 execute crearacksl-workspace-db --local --file=./migrations/0030_create_chat.sql

# Producción
pnpm wrangler d1 migrations apply crearacksl-workspace-db --remote

Footgun s64: migrations aplicadas con execute --file directo NO quedan en d1_migrations table. Un migrations apply posterior las re-aplica silenciosamente. Causó duplicado de 27 quick_links. Solución: usar siempre migrations apply para migrations versionadas + UNIQUE constraints donde haga falta.

Desde el 11-09-2026 (s323) nadie aplica migraciones a mano: las aplica el deploy de OPS (cf-pages-deploy.sh) antes de publicar, con candado contra el registro desincronizado (reincidencia del 11-09: 0045-0053 sin registrar, migrations apply reventó en la 0045). Flujo: PR con el .sql en migrations/ + su línea en scripts/seed-d1-migrations.sql → merge → el tick del deploy la aplica. Detalle: [[ia-tech—automatismos—metodo—cf-pages-deploy]].

3. Mapa ER por dominios

3.1 Dashboard del home

erDiagram
    news {
        int id PK
        string title
        string content
        string author
        string category
        int pinned
        string created_at
        string updated_at
    }
    notes {
        int id PK
        string title
        string content
        string color "blue|green|yellow|pink|orange"
        string author
        string created_at
        string updated_at
    }
    alerts {
        int id PK
        string message
        string type "info|warning|critical"
        int active
        string author
        string created_at
    }
    reports {
        int id PK
        string type
        string title
        string data "JSON"
        string ai_analysis
        string period
        string created_at
    }

Tablas independientes, sin FKs. CRUD simple desde React + Workers.

3.2 Tasks ecosystem

erDiagram
    tasks ||--o{ task_attachments : "tiene"
    tasks ||--o{ task_comments : "tiene"
    tasks ||--o{ task_calendar_events : "vinculado a"
    tasks ||--o{ task_emails : "vinculado a"
    tasks {
        int id PK
        string title
        string description
        string assignee "Edu|Dani|Txell|Equipo"
        string status "pending|in_progress|completed|deleted"
        string priority "low|normal|high|urgent"
        string due_date
        string created_by
        string created_at
        string updated_at
    }
    task_attachments {
        int id PK
        int task_id FK
        string r2_key UK "tasks/{id}/{uuid}.{ext}"
        string filename
        string content_type
        int size_bytes
        string uploaded_by
        string uploaded_at
    }
    task_comments {
        int id PK
        int task_id FK
        string author
        string body
        string target_user_ids "JSON array"
        string created_at
    }
    task_calendar_events {
        int task_id PK
        string zoho_event_uid PK
        string calendar_uid
        string title
        string start_at
        string end_at
        string url
        string created_by
        string created_at
    }
    task_emails {
        int task_id PK
        string zoho_message_id PK
        string thread_id
        string subject
        string from_address
        string email_date
        string url
        string linked_by
        string linked_at
    }

Único bloque con FKs reales (ON DELETE CASCADE). Borrar una task limpia attachments, comments, calendar links y email links en cascada. Los blobs R2 los elimina el endpoint DELETE manualmente.

3.3 Herramientas personales (scope user)

erDiagram
    notebook_notes {
        int id PK
        string owner_id "email CF Access"
        string title
        string content "JSON TipTap"
        int word_count
        int pinned
        string archived_at
        string created_at
        string updated_at
    }
    directions {
        int id PK
        string type "person|company"
        string name
        string nif
        string company
        string role
        string email
        string phone
        string linkedin
        string street
        string zip
        string city
        string province
        string country
        string tags "CSV"
        string notes
        string archived_at
        string owner_id
        string created_at
        string updated_at
    }
    quick_links {
        int id PK
        string label
        string url
        string description
        string category "infrastructure|code|ai|monitoring|product|selfhosted|admin|general"
        string icon_url
        int position
        int is_shared "1=team|0=private"
        string owner_id
        string archived_at
        string created_at
        string updated_at
    }

Patrón común: owner_id (email CF Access) + archived_at para soft-delete.

3.4 OAuth Zoho · evolución per-user

erDiagram
    zoho_oauth_tokens {
        string team_member PK "CHECK Edu|Dani|Txell"
        string zoho_email
        string refresh_token
        string access_token
        string access_token_expires_at
        string dc "default eu"
        string granted_by_cf_email
        string granted_at
        string updated_at
    }
    zoho_oauth_state {
        string state PK
        string created_by
        string created_at
    }

Evolución:

• s67 (0026): singleton (CHECK id = 1) con un solo refresh token del “equipo”
• s68 pivot (0027): migrado a per-user, team_member como PK, preservando token de Edu

3.5 Supercontexto · grafo + wiki

Es el dominio más rico del workspace. Conceptualmente:

erDiagram
    bib_nodes ||--o{ bib_edges : "source"
    bib_nodes ||--o{ bib_edges : "target"
    bib_nodes ||--o| bib_docs : "metadata doc"
    bib_nodes ||--o| bib_endpoints : "metadata endpoint"
    bib_nodes ||--o{ bib_chunks : "chunks para search"
    bib_nodes ||--o{ bib_change_log : "auditoría"
    bib_nodes }o--o| bib_communities : "cluster"
    bib_index_runs ||--o{ bib_change_log : "registra"
    bib_wiki_pages ||--o{ bib_wiki_log : "operaciones"
    bib_wiki_pages ||--o{ bib_wiki_utility : "eventos uso"
    bib_wiki_pages }o--o| bib_communities : "cluster"
    bib_wiki_pages }o--o{ bib_wiki_contradictions : "página A"
    bib_wiki_pages }o--o{ bib_wiki_contradictions : "página B"

Tablas (~13):

3.6 Chat del equipo + activity_log + ai_eval_runs

erDiagram
    chat_messages {
        int id PK
        string author "Edu|Dani|Txell"
        string body
        string created_at
    }
    chat_typing {
        string author PK
        string last_typed_at "TTL 5s"
    }
    activity_log {
        int id PK
        string timestamp
        string actor
        string action
        string entity_type
        string entity_id
        string entity_title
        string details "JSON"
        string source "default mcp"
        int duration_ms
    }
    ai_eval_runs {
        int id PK
        string created_at
        string user_email
        string candidates "JSON array"
        string cases "JSON array"
        string results "JSON matrix"
        int total_cells
        int duration_ms
        string status "completed|partial|failed"
        string notes
    }
    auth_codes {
        string nonce PK
        string used_at
        string created_at
    }

4. Persistencia híbrida wiki

Cada página wiki vive en dos sitios a la vez:

src/content/wiki/<slug>.md   (commit GitHub, source of truth para Astro build)
        ↕
bib_wiki_pages D1            (metadata, lint, search, utility tracking)

Flujo de creación

Footguns wiki documentados

5. Search semántico · pipeline

.md / código  →  bib_index_*  →  bib_nodes + bib_chunks
                                       ↓
                                  Embedding (Gemma 4 vía Google AI Studio o Workers AI)
                                       ↓
                                  Vectorize (CF) → vectorize_id en bib_chunks
                                       ↓
                                  bib_search_semantic tool → top-k chunks por cosine sim

Fallback embebido en D1: embedding_b64 (base64 del vector) usado si Vectorize está caído.

6. Backups y DR

Restaurar desde cero

# 1. Clonar repo workspace
git clone https://github.com/CreaRackSL/CreaRackSL-workspace.git

# 2. Crear D1 nueva
wrangler d1 create crearacksl-workspace-db

# 3. Importar último dump
wrangler d1 execute crearacksl-workspace-db --remote --file=/opt/dr-backups/d1-LATEST.sql

# 4. Deploy
pnpm build && wrangler pages deploy

7. Operaciones comunes

Query directa contra D1 remoto

# Single query
pnpm wrangler d1 execute crearacksl-workspace-db --remote --command="SELECT COUNT(*) FROM bib_nodes"

# Desde fichero
pnpm wrangler d1 execute crearacksl-workspace-db --remote --file=./query.sql

# Export tabla
pnpm wrangler d1 export crearacksl-workspace-db --table tasks --output tasks.sql

Listar tablas

SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;

Tamaño aproximado por tabla

SELECT name, SUM(pgsize) AS bytes
FROM dbstat
GROUP BY name
ORDER BY bytes DESC;

Migrations aplicadas vs en repo

SELECT * FROM d1_migrations ORDER BY id;
-- comparar con ls migrations/

8. Acceso operativo

Véase también

• [[workspace-tech—bd—coloquial]] — Versión accesible para entrada al proyecto
• [[crearack-tech—bd—tecnico]] — BD del SaaS CreaRack-Pro (PostgreSQL)
• [[crearack-tech—general—feature-catalog]] — Sección Biblioteca/Supercontexto desde el lado producto