# Recall - Resumen del Proyecto

## Fecha
2026-03-22

## Descripción
Recall es una aplicación de gestión de conocimiento personal (PKM) para captura y recuperación de notas, comandos, snippets y conocimiento técnico.

## Stack Tecnológico
- **Framework**: Next.js 16.2.1 con App Router
- **Base de datos**: SQLite via Prisma ORM
- **Lenguaje**: TypeScript
- **UI**: TailwindCSS + shadcn/ui components
- **Testing**: Jest

## Estructura del Proyecto

```
src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── notes/         # CRUD de notas, versions, quick
│   │   ├── tags/          # Tags y sugerencias
│   │   ├── search/        # Búsqueda avanzada
│   │   ├── usage/          # Tracking de uso
│   │   ├── metrics/       # Métricas internas
│   │   ├── centrality/     # Notas centrales
│   │   └── export-import/  # Import/export JSON
│   ├── notes/[id]/        # Detalle de nota
│   ├── edit/[id]/         # Edición de nota
│   └── new/               # Nueva nota
├── components/             # Componentes React
│   ├── ui/               # shadcn/ui components
│   ├── dashboard.tsx      # Dashboard inteligente
│   ├── quick-add.tsx      # Captura rápida
│   ├── note-form.tsx      # Formulario de nota
│   ├── note-connections.tsx # Panel de conexiones
│   ├── related-notes.tsx   # Notas relacionadas
│   ├── version-history.tsx  # Historial de versiones
│   └── track-note-view.tsx # Tracking de vistas
└── lib/                   # Utilidades
    ├── prisma.ts          # Cliente Prisma
    ├── usage.ts           # Tracking de uso y co-uso
    ├── search.ts          # Búsqueda con scoring
    ├── query-parser.ts    # Parser de queries avanzadas
    ├── versions.ts        # Historial de versiones
    ├── related.ts         # Notas relacionadas
    ├── backlinks.ts       # Sistema de enlaces [[wiki]]
    ├── tags.ts            # Normalización y sugerencias
    ├── metrics.ts         # Métricas de dashboard
    ├── centrality.ts      # Cálculo de centralidad
    ├── type-inference.ts  # Detección automática de tipo
    ├── link-suggestions.ts # Sugerencias de enlaces
    ├── features.ts        # Feature flags
    └── validators.ts      # Zod schemas
```

## Modelos de Datos

### Note
```prisma
model Note {
  id             String    @id @default(cuid())
  title          String
  content        String
  type           String    @default("note")  // command, snippet, decision, recipe, procedure, inventory, note
  isFavorite     Boolean   @default(false)
  isPinned       Boolean   @default(false)
  createdAt      DateTime  @default(now())
  updatedAt      DateTime  @updatedAt
  creationSource String    @default("form")  // form, quick, import
}
```

### NoteUsage
```prisma
model NoteUsage {
  id        String   @id @default(cuid())
  noteId    String
  eventType String   // view, search_click, related_click, link_click, copy_command, copy_snippet
  query     String?
  createdAt DateTime @default(now())
}
```

### NoteCoUsage
```prisma
model NoteCoUsage {
  id         String   @id @default(cuid())
  fromNoteId String
  toNoteId   String
  weight     Int      @default(1)
}
```

### Backlink
```prisma
model Backlink {
  sourceNoteId String
  targetNoteId String
}
```

### NoteVersion
```prisma
model NoteVersion {
  id        String   @id @default(cuid())
  noteId    String
  title     String
  content   String
  createdAt DateTime @default(now())
}
```

## APIs Principales

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/notes` | GET, POST | Listar/crear notas |
| `/api/notes/[id]` | GET, PUT, DELETE | CRUD de nota |
| `/api/notes/[id]/versions` | GET, POST | Listar/crear versiones |
| `/api/notes/[id]/versions/[vid]` | GET, PUT | Ver/restaurar versión |
| `/api/notes/quick` | POST | Creación rápida |
| `/api/notes/links` | GET | Sugerencias de enlaces |
| `/api/search` | GET | Búsqueda con scoring |
| `/api/tags` | GET | Listar/buscar tags |
| `/api/tags/suggest` | GET | Sugerencias automáticas |
| `/api/usage` | GET | Estadísticas de uso |
| `/api/usage/co-usage` | GET | Notas co-usadas |
| `/api/metrics` | GET | Métricas de dashboard |
| `/api/centrality` | GET | Notas más centrales |

## Features Implementadas

### MVP-1 (Completado)
- CRUD completo de notas
- Sistema de tags
- Búsqueda básica

### MVP-2 (Completado)
- Búsqueda avanzada con scoring
- Quick Add con prefijos (cmd:, snip:, etc.)
- Backlinks con sintaxis [[wiki]]
- Formularios guiados por tipo de nota

### MVP-3 Sprint 1
- Usage tracking (vistas, clics, copias)
- Dashboard inteligente (Recientes, Más usadas, Por tipo)
- Scoring boost basado en uso

### MVP-3 Sprint 2
- Sugerencias automáticas de tags
- Panel "Conectado con" (backlinks, enlaces, relacionadas)

### MVP-3 Sprint 3
- Quick Add multilínea
- Pegado inteligente con detección de tipo
- Sugerencia automática de tipo de nota
- Sugerencia de enlaces internos

### MVP-3 Sprint 4
- Registro de co-uso entre notas
- Métricas internas (notas por tipo, más vistas, por origen)
- Cálculo de notas centrales (centrality score)
- Registro de origen de creación (form/quick/import)
- Feature flags configurables

### Mejoras UI Recientes
- Header responsive con menú hamburguesa en móvil
- Desktop: una fila con logo, nav links, QuickAdd y botón Nueva nota
- Mobile: logo + QuickAdd + hamburguesa → dropdown con nav links y botón Nueva nota

### MVP-4 Sprint 1
- Query parser para búsquedas avanzadas (`type:`, `tag:`, `is:favorite`, `is:pinned`)
- Búsqueda en tiempo real con 300ms debounce
- Navegación por teclado (↑↓ Enter ESC) estilo Spotlight
- Dropdown de resultados con cache de 50 entradas

### MVP-4 Sprint 2
- Sidebar contextual con co-uso (notas vistas juntas)
- Cache de resultados de búsqueda

### MVP-4 Sprint 3
- Historial de versiones de notas
- API de versiones (crear, listar, restaurar)
- UI de historial en diálogo de nota

### MVP-4 Sprint 4
- Tests de historial de versiones (11 tests)

## Algoritmo de Scoring

```typescript
// Search scoring
score = baseScore + favoriteBoost(+2) + pinnedBoost(+1) + usageBoost

// Related notes scoring
score = sameType(+3) + sharedTags(×3) + titleKeywords(max+3) + contentKeywords(max+2) + usageBoost

// Centrality score
centrality = backlinks(×3) + outboundLinks(×1) + usageViews(×0.5) + coUsageWeight(×2)
```

## Tests

**211 tests** cubriendo:
- API routes (CRUD, search, tags, etc.)
- Search y scoring
- Query parser
- Notas relacionadas
- Backlinks
- Type inference
- Link suggestions
- Usage tracking
- Dashboard
- Version history

## Comandos

```bash
npm run dev      # Desarrollo
npm run build    # Build producción
npm run test     # Tests
npx prisma db push  # Sync schema
npx prisma studio   # UI de BD
```

## Configuración de Feature Flags

```bash
FLAG_CENTRALITY=true
FLAG_PASSIVE_RECOMMENDATIONS=true
FLAG_TYPE_SUGGESTIONS=true
FLAG_LINK_SUGGESTIONS=true
```

## Roadmap
- [ ] Panel de métricas visible en UI
- [ ] Configuración de feature flags en Settings
- [ ] Visualización del grafo de conocimiento
- [ ] Exportación mejorada (Markdown, HTML)
- [ ] Tests de integración E2E