feat: initial commit

This commit is contained in:
2026-03-22 09:18:07 -03:00
parent f2e4706b4a
commit af0910f428
22 changed files with 10339 additions and 0 deletions

761
mvp_recall.md Normal file
View File

@@ -0,0 +1,761 @@
# MVP — Gestor de conocimiento personal práctico
Documento de ejecución pensado para usar directamente con Claude Code.
---
## 1. Objetivo del MVP
Construir una aplicación web local-first para gestión de conocimiento personal enfocada en **captura rápida**, **relación automática** y **recuperación útil**.
No es una app de notas genérica. El MVP debe resolver bien estos casos:
- guardar comandos frecuentes
- guardar snippets de código
- registrar decisiones técnicas
- guardar recetas
- guardar trámites o procedimientos
- mantener inventario doméstico simple
La propuesta de valor del MVP es:
1. **Guardar info rápido** con fricción mínima.
2. **Relacionarla sola** usando metadatos, enlaces sugeridos y contenido similar.
3. **Devolverla cuando importa** mediante búsqueda potente y vistas útiles.
---
## 2. Principios del producto
### 2.1 Principios funcionales
- Crear una nota debe tomar menos de 10 segundos.
- La búsqueda debe encontrar contenido por título, texto, tags y tipo.
- La app debe sugerir relaciones sin exigir organización manual compleja.
- El sistema debe ser útil desde el día 1 con pocas notas.
- Debe funcionar bien para conocimiento práctico, no solo escritura larga.
### 2.2 Principios técnicos
- **Local-first**: los datos viven primero en el dispositivo.
- **Simple de desplegar y mantener**.
- **Escalable por capas**: empezar pequeño sin bloquear futuras mejoras.
- **Estructura tipada**: tipos de contenido claros.
- **Extensible** para futuro tagging semántico, embeddings y sincronización.
---
## 3. Alcance del MVP
### 3.1 Incluye
#### Captura
- Crear nota rápida desde un input o modal.
- Campos mínimos:
- título
- contenido
- tipo
- tags manuales opcionales
- Crear desde plantillas simples según tipo.
#### Tipos de nota del MVP
- `command`
- `snippet`
- `decision`
- `recipe`
- `procedure`
- `inventory`
- `note` (genérico)
#### Organización automática
- Extracción automática de:
- fecha de creación
- fecha de actualización
- tipo
- tags sugeridos por heurística simple
- Detección de notas relacionadas por:
- coincidencia de tags
- similitud de título
- palabras clave compartidas
- mismo tipo
#### Recuperación
- Búsqueda full-text.
- Filtros por tipo y tags.
- Vista de resultados ordenada por relevancia simple.
- Vista de “relacionadas” dentro de cada nota.
- Vista de “recientes”.
#### Edición
- Editar nota existente.
- Eliminar nota.
- Marcar favorita.
- Pin opcional para destacar notas críticas.
#### Persistencia
- Base local con SQLite.
- Exportar/importar JSON.
---
### 3.2 No incluye en el MVP
- colaboración multiusuario
- sincronización en la nube
- permisos y autenticación compleja
- edición en tiempo real
- embeddings/vector DB en producción
- OCR
- app móvil nativa
- plugins
- automatizaciones complejas
- parser avanzado de documentos adjuntos
---
## 4. Stack sugerido
## Frontend
- **Next.js 15** con App Router
- **TypeScript**
- **Tailwind CSS**
- **shadcn/ui** para componentes
## Backend
- API routes / server actions de Next.js
- **Prisma** como ORM
- **SQLite** para MVP
## Búsqueda
- inicialmente con consultas SQL + normalización simple
- opcional: SQLite FTS si da tiempo
## Validación
- **Zod**
## Estado
- React server components + estado local mínimo
- si hace falta: Zustand muy limitado
## Testing
- **Vitest** para lógica
- **Playwright** para flujo principal si alcanza
## Motivo de esta elección
Este stack permite:
- iterar rápido
- mantener una sola codebase
- ejecutar localmente fácil
- migrar luego a Postgres sin rehacer todo
---
## 5. Arquitectura funcional
### 5.1 Entidades principales
#### Note
Campos sugeridos:
- `id`
- `title`
- `content`
- `type`
- `createdAt`
- `updatedAt`
- `isFavorite`
- `isPinned`
#### Tag
- `id`
- `name`
#### NoteTag
- `noteId`
- `tagId`
#### RelatedNote
- `id`
- `sourceNoteId`
- `targetNoteId`
- `score`
- `reason`
Opcional en MVP si se prefiere calcular en runtime en vez de persistir.
---
### 5.2 Modelo de datos recomendado
```prisma
model Note {
id String @id @default(cuid())
title String
content String
type NoteType @default(note)
isFavorite Boolean @default(false)
isPinned Boolean @default(false)
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
tags NoteTag[]
}
model Tag {
id String @id @default(cuid())
name String @unique
notes NoteTag[]
}
model NoteTag {
noteId String
tagId String
note Note @relation(fields: [noteId], references: [id], onDelete: Cascade)
tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade)
@@id([noteId, tagId])
}
enum NoteType {
command
snippet
decision
recipe
procedure
inventory
note
}
```
---
## 6. UX mínima del MVP
### 6.1 Pantallas
#### Home / Dashboard
Debe mostrar:
- barra de búsqueda principal
- botón “Nueva nota”
- sección de notas recientes
- sección de favoritas o pineadas
- filtros rápidos por tipo
#### Lista de notas
- búsqueda
- filtros por tipo
- filtros por tags
- cards compactas con:
- título
- tipo
- preview corta
- tags
- fecha de actualización
#### Detalle de nota
- título
- tipo
- contenido
- tags
- acciones: editar, borrar, favorita, pin
- bloque “Notas relacionadas”
#### Crear/editar nota
- formulario simple
- selector de tipo
- área de contenido grande
- campo de tags opcional
- templates por tipo
---
### 6.2 Flujo ideal
1. Usuario abre app.
2. Escribe una nota nueva en segundos.
3. La nota se guarda localmente.
4. El sistema sugiere tags y notas relacionadas.
5. Días después el usuario la encuentra por búsqueda, filtro o relación.
---
## 7. Lógica de negocio del MVP
### 7.1 Reglas de creación
Al crear una nota:
- validar que título y contenido no estén vacíos
- normalizar espacios
- guardar tipo
- parsear tags manuales si existen
- generar tags sugeridos por heurística opcional
### 7.2 Heurísticas de tags sugeridos
Heurística simple inicial:
- extraer palabras frecuentes relevantes del título
- detectar bloques de código para sugerir `code`, `bash`, `sql`, etc.
- detectar patrones:
- receta → `cocina`
- decisión → `arquitectura`, `backend`, etc. según keywords
- inventario → `hogar`
No hace falta IA real en MVP. Debe ser determinístico y simple.
### 7.3 Cálculo de relacionadas
Implementación simple:
- +3 puntos si comparten tipo
- +2 por cada tag compartido
- +1 por palabra relevante compartida en título
- +1 si una keyword del contenido aparece en ambas
Mostrar top 5 relacionadas con score > umbral.
Se puede calcular:
- on-demand en el detalle de la nota, o
- al guardar/editar la nota
Para el MVP, **on-demand** es suficiente.
### 7.4 Búsqueda
Primera versión:
- buscar en `title`
- buscar en `content`
- buscar en nombres de tags
- permitir filtro por `type`
Orden sugerido:
1. coincidencia en título
2. coincidencia en tags
3. coincidencia en contenido
4. updatedAt desc
---
## 8. Templates por tipo
### command
Campos base:
- título
- comando
- explicación
- contexto de uso
Template de contenido sugerido:
```md
## Comando
## Qué hace
## Cuándo usarlo
## Ejemplo
```
### snippet
```md
## Snippet
## Lenguaje
## Qué resuelve
## Notas
```
### decision
```md
## Contexto
## Decisión
## Alternativas consideradas
## Consecuencias
```
### recipe
```md
## Ingredientes
## Pasos
## Tiempo
## Notas
```
### procedure
```md
## Objetivo
## Pasos
## Requisitos
## Problemas comunes
```
### inventory
```md
## Item
## Cantidad
## Ubicación
## Notas
```
---
## 9. Estructura de carpetas sugerida
```txt
src/
app/
page.tsx
notes/
page.tsx
[id]/page.tsx
new/page.tsx
edit/[id]/page.tsx
api/
notes/route.ts
notes/[id]/route.ts
search/route.ts
components/
note-form.tsx
note-card.tsx
note-list.tsx
search-bar.tsx
related-notes.tsx
filters.tsx
dashboard.tsx
lib/
prisma.ts
db.ts
search.ts
related.ts
tags.ts
templates.ts
validators.ts
types/
note.ts
prisma/
schema.prisma
```
---
## 10. API / acciones mínimas
### CRUD de notas
- `GET /api/notes`
- `POST /api/notes`
- `GET /api/notes/:id`
- `PUT /api/notes/:id`
- `DELETE /api/notes/:id`
### búsqueda
- `GET /api/search?q=...&type=...&tag=...`
### export/import
- `GET /api/export`
- `POST /api/import`
---
## 11. Historias de usuario principales
### HU1 — Crear nota rápida
Como usuario,
quiero crear una nota en pocos segundos,
para no perder información útil.
Criterios de aceptación:
- puedo crear una nota con título, contenido y tipo
- queda persistida localmente
- aparece en recientes inmediatamente
### HU2 — Buscar conocimiento guardado
Como usuario,
quiero encontrar una nota por texto libre,
para recuperar información cuando la necesito.
Criterios:
- la búsqueda encuentra coincidencias en título y contenido
- puedo filtrar por tipo
- resultados aparecen rápido
### HU3 — Ver contenido relacionado
Como usuario,
quiero que el sistema me muestre notas relacionadas,
para redescubrir información útil.
Criterios:
- cada nota muestra hasta 5 relacionadas
- la relación se basa en reglas simples entendibles
### HU4 — Usar plantillas
Como usuario,
quiero crear notas con estructura base según el tipo,
para capturar mejor cada caso.
Criterios:
- al elegir un tipo puedo cargar un template sugerido
- puedo editar el template libremente
### HU5 — Exportar datos
Como usuario,
quiero exportar mis datos,
para no quedar atado a la app.
Criterios:
- exporta a JSON válido
- puedo reimportar ese JSON
---
## 12. Roadmap de implementación del MVP
### Fase 1 — Base funcional
Objetivo: tener CRUD y persistencia.
Entregables:
- setup Next.js + Tailwind + Prisma + SQLite
- schema Prisma
- migraciones
- CRUD básico de notas
- listado y detalle
- formulario crear/editar
### Fase 2 — Búsqueda y filtros
Objetivo: recuperar bien.
Entregables:
- search por título/contenido
- filtros por tipo
- filtros por tags
- home con recientes y favoritas
### Fase 3 — Relación automática
Objetivo: conectar conocimiento.
Entregables:
- heurística de tags sugeridos
- cálculo de relacionadas
- UI de relacionadas en detalle
### Fase 4 — Pulido MVP
Objetivo: dejarlo presentable y usable.
Entregables:
- templates por tipo
- export/import JSON
- validaciones
- estados vacíos
- seed de ejemplo
---
## 13. Definición de terminado
El MVP está listo cuando:
- se puede crear, editar y borrar notas
- las notas se persisten en SQLite
- se puede buscar por texto
- se puede filtrar por tipo y tags
- cada nota muestra relacionadas
- existen templates por tipo
- existe export/import JSON
- la UI es suficientemente clara para uso diario local
---
## 14. Riesgos y cómo reducirlos
### Riesgo 1: demasiada ambición
Mitigación:
- no agregar sync ni IA real al MVP
- priorizar velocidad de uso y recuperación
### Riesgo 2: búsqueda pobre
Mitigación:
- priorizar calidad de búsqueda antes de features cosméticas
- evaluar SQLite FTS si la búsqueda simple queda corta
### Riesgo 3: relaciones poco útiles
Mitigación:
- mantener heurísticas transparentes
- mostrar razones simples del match en una versión futura
### Riesgo 4: modelo demasiado genérico
Mitigación:
- usar tipos concretos desde el inicio
- mantener `note` genérico solo como fallback
---
## 15. Mejoras post-MVP
- sincronización entre dispositivos
- embeddings para similitud semántica real
- parser de comandos/snippets automático
- extensión de navegador para guardar rápido
- captura por share sheet móvil
- recordatorios contextuales
- grafos de relación
- OCR y adjuntos
- versionado de notas
- vistas especializadas por tipo
---
## 16. Prompt maestro para ejecutar en Claude Code
Usar este prompt como instrucción principal:
```txt
Quiero que construyas un MVP funcional de una aplicación llamada “Gestor de conocimiento personal práctico”.
Objetivo del producto:
- guardar info rápido
- relacionarla sola
- devolverla cuando importa
Casos de uso principales:
- comandos
- snippets
- decisiones técnicas
- recetas
- trámites/procedimientos
- inventario doméstico
Stack requerido:
- Next.js 15 con App Router
- TypeScript
- Tailwind CSS
- shadcn/ui
- Prisma
- SQLite
- Zod
Requisitos funcionales del MVP:
1. CRUD completo de notas.
2. Tipos de nota: command, snippet, decision, recipe, procedure, inventory, note.
3. Formulario de creación/edición con título, contenido, tipo y tags opcionales.
4. Dashboard con búsqueda, recientes y favoritas/pineadas.
5. Lista de notas con filtros por tipo y tags.
6. Búsqueda por título, contenido y tags.
7. Página de detalle con notas relacionadas.
8. Templates simples por tipo.
9. Exportar e importar JSON.
10. Persistencia local usando SQLite.
Reglas de relacionadas:
- +3 si comparten tipo
- +2 por cada tag compartido
- +1 por palabra relevante compartida en el título
- +1 por keyword compartida en el contenido
- mostrar top 5 con score suficiente
Restricciones:
- No implementar autenticación.
- No implementar sync cloud.
- No implementar IA compleja ni vector DB.
- Mantener el código limpio, modular y listo para evolucionar.
Quiero que generes:
1. La estructura inicial del proyecto.
2. El schema de Prisma.
3. Los componentes principales.
4. Las rutas/páginas necesarias.
5. Las utilidades para búsqueda, tags y relacionadas.
6. Un seed de datos de ejemplo.
7. Instrucciones claras para correr el proyecto.
Además:
- usa buenas prácticas
- separa responsabilidades
- evita sobreingeniería
- deja comentarios donde aporten claridad
- entrega una primera versión funcional de punta a punta
```
---
## 17. Prompt por etapas para Claude Code
### Etapa 1 — Setup base
```txt
Crea el proyecto base con Next.js 15, TypeScript, Tailwind, Prisma y SQLite. Configura la estructura de carpetas, instala dependencias, crea el schema inicial de Prisma para Note, Tag y NoteTag, genera migración y deja una app corriendo con una página home básica.
```
### Etapa 2 — CRUD
```txt
Implementa el CRUD completo de notas. Debe existir listado, detalle, creación, edición y borrado. Cada nota debe tener title, content, type, tags opcionales, isFavorite e isPinned. Usa validación con Zod.
```
### Etapa 3 — Búsqueda y filtros
```txt
Implementa búsqueda por texto sobre título, contenido y tags. Agrega filtros por tipo y tags. Crea una home con notas recientes, favoritas y acceso rápido a crear nota.
```
### Etapa 4 — Relacionadas
```txt
Implementa la lógica de notas relacionadas usando reglas heurísticas simples. Muestra hasta 5 notas relacionadas en la vista de detalle.
```
### Etapa 5 — Templates y export/import
```txt
Agrega templates por tipo de nota y funciones para exportar e importar datos en JSON. Incluye manejo básico de errores y estados vacíos.
```
---
## 18. Checklist de validación manual
- [ ] La app inicia sin errores.
- [ ] Se puede crear una nota.
- [ ] Se puede editar una nota.
- [ ] Se puede eliminar una nota.
- [ ] La búsqueda encuentra texto por título.
- [ ] La búsqueda encuentra texto por contenido.
- [ ] Se puede filtrar por tipo.
- [ ] Las tags se guardan y se pueden usar como filtro.
- [ ] El detalle muestra relacionadas.
- [ ] Se puede exportar JSON.
- [ ] Se puede importar JSON.
- [ ] Hay seed de ejemplo útil para probar.
---
## 19. Criterio de éxito del MVP
El MVP será exitoso si una persona puede usarlo durante una semana para guardar y recuperar conocimiento práctico sin sentir que necesita otra herramienta para:
- recordar comandos
- reutilizar snippets
- revisar decisiones
- seguir procedimientos
- consultar inventario o recetas
---
## 20. Recomendación final
Para este MVP conviene optimizar en este orden:
1. velocidad de captura
2. calidad de búsqueda
3. utilidad de relacionadas
4. claridad visual
5. exportabilidad
No priorizar IA antes de demostrar que la base manual + heurística ya resuelve valor real.