# 🏗️ ARQUITECTURA SERVIDOR DE CONTENIDO - TES

**Versión:** 1.0.0  
**Fecha:** 2025-01-06  
**Estado:** Diseño Técnico - Sin Implementación

---

## 🎯 PRINCIPIOS FUNDAMENTALES

1. **Servidor Propio**
   - ✅ PostgreSQL en nuestro servidor
   - ✅ API REST de solo lectura para app
   - ✅ Panel admin separado (solo editores)
   - ❌ NO Supabase
   - ❌ NO servicios externos
   - ❌ NO CMS externo

2. **App PWA (Solo Consumo)**
   - ✅ Consume Content Pack JSON
   - ✅ Funciona offline-first
   - ✅ Cache local (IndexedDB)
   - ❌ NO edita contenido
   - ❌ NO tiene panel admin

3. **Separación Clara**
   - Servidor → Genera Content Pack
   - App → Consume Content Pack
   - Panel Admin → Edita en servidor

---

## 📐 ARQUITECTURA GENERAL

```
┌─────────────────────────────────────────────────────────┐
│                    SERVIDOR PROPIO                       │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  PostgreSQL Database                             │   │
│  │  ├── content_items                               │   │
│  │  ├── media_resources                             │   │
│  │  ├── associations                                │   │
│  │  ├── versions                                    │   │
│  │  └── audit_logs                                  │   │
│  └──────────────────────────────────────────────────┘   │
│                          │                               │
│                          │                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  API REST (Node.js + Express)                    │   │
│  │  ├── GET /api/content/pack/latest                │   │
│  │  ├── GET /api/content/pack/:version              │   │
│  │  ├── GET /api/content/protocol/:id                │   │
│  │  ├── GET /api/content/guide/:id                   │   │
│  │  └── GET /api/health                             │   │
│  │  (SOLO LECTURA - Sin autenticación para app)     │   │
│  └──────────────────────────────────────────────────┘   │
│                          │                               │
│                          │                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Panel Admin (React - Puerto 5174)                │   │
│  │  ├── Editor de contenido                          │   │
│  │  ├── Gestor de recursos                          │   │
│  │  ├── Validación clínica                          │   │
│  │  └── Exportación de packs                        │   │
│  │  (REQUIERE AUTENTICACIÓN)                        │   │
│  └──────────────────────────────────────────────────┘   │
│                          │                               │
│                          │                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Generador Content Pack                           │   │
│  │  ├── Lee de PostgreSQL                           │   │
│  │  ├── Genera JSON optimizado                      │   │
│  │  ├── Calcula hash SHA-256                        │   │
│  │  └── Guarda en /packs/                           │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└─────────────────────────────────────────────────────────┘
                          │
                          │ (Content Pack JSON)
                          ▼
┌─────────────────────────────────────────────────────────┐
│              APP PWA (Frontend)                          │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────┐   │
│  │  Service Worker                                 │   │
│  │  ├── Descarga pack al iniciar                   │   │
│  │  ├── Cache en IndexedDB                         │   │
│  │  └── Funciona 100% offline                       │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Content Adapter                                  │   │
│  │  ├── Lee de cache local                          │   │
│  │  ├── Fallback a procedures.ts si no hay pack    │   │
│  │  └── Sin modificar código existente              │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

---

## 🗄️ BASE DE DATOS (PostgreSQL)

### Esquema: `tes_content`

**Justificación:**
- Schema dedicado para contenido
- Separado de otros datos del sistema
- Fácil backup y migración

### Tablas Principales

Ver `docs/SERVER_DATABASE_SCHEMA.sql` (se creará a continuación)

---

## 🔌 API REST (Solo Lectura)

### Endpoints Públicos (Sin Autenticación)

#### 1. Health Check
```
GET /api/health
```
**Respuesta:**
```json
{
  "status": "ok",
  "timestamp": "2025-01-06T12:00:00Z",
  "database": "connected",
  "latest_pack_version": "1.0.0"
}
```

#### 2. Content Pack Latest
```
GET /api/content/pack/latest
```
**Respuesta:** Content Pack JSON completo (ver especificación)

**Headers:**
- `If-None-Match: <hash>` - Para validar si hay cambios
- `ETag: <hash>` - Hash del pack en respuesta

#### 3. Content Pack por Versión
```
GET /api/content/pack/:version
```
**Ejemplo:** `GET /api/content/pack/1.0.0`

#### 4. Protocolo Individual
```
GET /api/content/protocol/:slug
```
**Ejemplo:** `GET /api/content/protocol/rcp-adulto-svb`

**Respuesta:**
```json
{
  "id": "...",
  "type": "protocol",
  "slug": "rcp-adulto-svb",
  "title": "RCP Adulto - Soporte Vital Básico",
  "content": { ... },
  "resources": {
    "images": [...],
    "videos": [...]
  }
}
```

#### 5. Guía Individual
```
GET /api/content/guide/:slug
```

#### 6. Recurso Multimedia
```
GET /api/content/media/:id
```
**Respuesta:** URL del recurso o redirección a archivo

---

### Endpoints Admin (Con Autenticación)

Ver sección "Panel Admin" más abajo.

---

## 📦 CONTENT PACK JSON

### Estructura (Optimizada para Offline)

```json
{
  "metadata": {
    "version": "1.0.0",
    "generated_at": "2025-01-06T12:00:00Z",
    "hash": "sha256:abc123...",
    "total_items": 45,
    "total_resources": 120,
    "size_bytes": 5242880
  },
  "content": {
    "protocols": [...],
    "guides": [...],
    "manuals": [...],
    "drugs": [...],
    "checklists": [...]
  },
  "media": {
    "resources": [...],
    "associations": [...]
  },
  "links": {
    "protocol_to_guide": [...],
    "guide_to_protocol": [...],
    "manual_to_protocols": [...]
  }
}
```

**Características:**
- ✅ Solo contenido `published`
- ✅ Solo última versión
- ✅ Recursos asociados incluidos
- ✅ Enlaces bidireccionales pre-calculados
- ✅ Hash SHA-256 para verificación
- ✅ Tamaño optimizado (< 10MB recomendado)

**Ubicación en Servidor:**
```
/packs/
├── pack-v1.0.0.json
├── pack-v1.1.0.json
└── pack-latest.json (symlink)
```

---

## 🎛️ PANEL ADMIN (Conceptual)

### Arquitectura

```
┌─────────────────────────────────────────┐
│  Panel Admin (React - Puerto 5174)      │
├─────────────────────────────────────────┤
│  ┌───────────────────────────────────┐ │
│  │  Auth (JWT)                        │ │
│  │  - Login en servidor               │ │
│  │  - Token almacenado localmente     │ │
│  └───────────────────────────────────┘ │
│  ┌───────────────────────────────────┐ │
│  │  Editor de Protocolo               │ │
│  │  - Tabs: Básico, Pasos, Checklist │ │
│  │  - Preview "Modo TES"             │ │
│  │  - Guarda en servidor via API     │ │
│  └───────────────────────────────────┘ │
│  ┌───────────────────────────────────┐ │
│  │  Gestor de Recursos                │ │
│  │  - Upload a servidor              │ │
│  │  - Asociar a contenido            │ │
│  └───────────────────────────────────┘ │
│  ┌───────────────────────────────────┐ │
│  │  Generador de Pack                 │ │
│  │  - Botón "Generar Pack"            │ │
│  │  - Seleccionar versión             │ │
│  │  - Descargar JSON                  │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
           │
           │ (API REST con Auth)
           ▼
┌─────────────────────────────────────────┐
│  API Admin (Node.js + Express)          │
│  - POST /api/admin/content              │
│  - PUT /api/admin/content/:id           │
│  - POST /api/admin/media                │
│  - POST /api/admin/pack/generate        │
└─────────────────────────────────────────┘
```

### Endpoints Admin

#### Autenticación
```
POST /api/admin/auth/login
POST /api/admin/auth/logout
GET  /api/admin/auth/me
```

#### Contenido
```
GET    /api/admin/content              # Lista con filtros
GET    /api/admin/content/:id          # Detalle
POST   /api/admin/content              # Crear
PUT    /api/admin/content/:id           # Actualizar
DELETE /api/admin/content/:id          # Eliminar (soft delete)
POST   /api/admin/content/:id/validate # Solicitar validación
POST   /api/admin/content/:id/publish   # Publicar
```

#### Recursos
```
GET    /api/admin/media                # Lista
POST   /api/admin/media/upload          # Upload archivo
PUT    /api/admin/media/:id             # Actualizar metadatos
DELETE /api/admin/media/:id             # Eliminar
POST   /api/admin/media/:id/associate   # Asociar a contenido
```

#### Content Pack
```
POST   /api/admin/pack/generate        # Generar nuevo pack
GET    /api/admin/pack/versions        # Lista de versiones
GET    /api/admin/pack/:version        # Descargar pack específico
```

---

## 🔒 SEGURIDAD

### API Pública (App)
- ✅ Sin autenticación (solo lectura)
- ✅ Rate limiting (100 req/min por IP)
- ✅ CORS configurado (solo dominios permitidos)
- ✅ Validación de inputs

### API Admin
- ✅ Autenticación JWT obligatoria
- ✅ RBAC (Roles: editor, validador, admin)
- ✅ Rate limiting (50 req/min por usuario)
- ✅ Validación de permisos por endpoint
- ✅ Audit log de todas las acciones

---

## 📁 ESTRUCTURA DE DIRECTORIOS (Servidor)

```
server/
├── config/
│   ├── database.js              # Config PostgreSQL
│   └── storage.js               # Config almacenamiento archivos
├── database/
│   ├── migrations/
│   │   ├── 001_create_schema.sql
│   │   └── 002_create_tables.sql
│   └── seeds/
│       └── initial_data.sql
├── src/
│   ├── api/
│   │   ├── public/               # Endpoints públicos (app)
│   │   │   ├── health.js
│   │   │   ├── content-pack.js
│   │   │   └── content.js
│   │   └── admin/                # Endpoints admin
│   │       ├── auth.js
│   │       ├── content.js
│   │       ├── media.js
│   │       └── pack.js
│   ├── services/
│   │   ├── content-service.js
│   │   ├── media-service.js
│   │   └── pack-generator.js    # Generador de Content Pack
│   ├── middleware/
│   │   ├── auth.js
│   │   ├── rbac.js
│   │   └── rate-limit.js
│   └── utils/
│       ├── validation.js
│       └── hash.js
├── storage/
│   ├── media/
│   │   ├── images/
│   │   └── videos/
│   └── packs/
│       ├── pack-v1.0.0.json
│       └── pack-latest.json
├── admin-panel/                 # Panel admin (React)
│   └── (ya existe)
└── index.js                     # Servidor Express principal
```

---

## 🔄 FLUJO DE TRABAJO

### 1. Editor Crea Contenido
```
Editor → Panel Admin → POST /api/admin/content
→ Guarda en PostgreSQL (status: 'draft')
```

### 2. Validador Revisa
```
Validador → Panel Admin → POST /api/admin/content/:id/validate
→ Actualiza status: 'approved'
```

### 3. Admin Publica
```
Admin → Panel Admin → POST /api/admin/content/:id/publish
→ Actualiza status: 'published'
```

### 4. Generar Content Pack
```
Admin → Panel Admin → POST /api/admin/pack/generate
→ Genera JSON desde PostgreSQL
→ Calcula hash
→ Guarda en /storage/packs/
→ Crea symlink pack-latest.json
```

### 5. App Consume
```
App → GET /api/content/pack/latest
→ Descarga JSON
→ Cache en IndexedDB
→ Funciona offline
```

---

## 📊 MODELO DE DATOS (Resumen)

Ver `docs/SERVER_DATABASE_SCHEMA.sql` para detalles completos.

**Tablas:**
- `content_items` - Contenido principal
- `media_resources` - Recursos multimedia
- `content_resource_associations` - Asociaciones
- `content_versions` - Historial de versiones
- `audit_logs` - Auditoría
- `users` - Usuarios del panel admin

---

## ✅ CHECKLIST DE IMPLEMENTACIÓN

### Fase 1: Base de Datos
- [ ] Crear schema `tes_content`
- [ ] Crear tablas (content_items, media_resources, etc.)
- [ ] Crear índices
- [ ] Crear triggers
- [ ] Migrar contenido inicial

### Fase 2: API Pública
- [ ] Endpoint `/api/health`
- [ ] Endpoint `/api/content/pack/latest`
- [ ] Endpoint `/api/content/pack/:version`
- [ ] Endpoint `/api/content/protocol/:slug`
- [ ] Endpoint `/api/content/guide/:slug`
- [ ] Rate limiting
- [ ] CORS configurado

### Fase 3: Generador de Pack
- [ ] Servicio `pack-generator.js`
- [ ] Lectura desde PostgreSQL
- [ ] Generación de JSON
- [ ] Cálculo de hash SHA-256
- [ ] Guardado en `/storage/packs/`
- [ ] Symlink `pack-latest.json`

### Fase 4: API Admin
- [ ] Autenticación JWT
- [ ] RBAC middleware
- [ ] Endpoints CRUD contenido
- [ ] Endpoints gestión recursos
- [ ] Endpoint generación pack
- [ ] Audit logging

### Fase 5: Panel Admin
- [ ] Editor de protocolos
- [ ] Editor de guías
- [ ] Gestor de recursos
- [ ] Generador de pack (UI)
- [ ] Dashboard de estado

### Fase 6: Integración App
- [ ] ContentAdapter en app
- [ ] Descarga de pack al iniciar
- [ ] Cache en IndexedDB
- [ ] Fallback a procedures.ts
- [ ] Testing offline

---

**Fin del Documento**