---
name: kanban
lang: go
domain: tools
version: 0.5.0
description: "Kanban board con persistencia SQLite, drag-and-drop entre columnas (dnd-kit), tracking del tiempo por columna, adjuntos de archivos por card, notificaciones realtime (SSE) y modulos externos (Jira). Frontend Vite + React + Mantine v9 embebido en el binario Go. Endpoint MCP Streamable HTTP en /mcp."
tags: [service, kanban, web, dnd-kit, mantine, sqlite, time-tracking]
uses_functions:
  - random_hex_id_go_core
  - parse_date_or_default_go_core
  - sqlite_open_go_infra
  - sqlite_apply_migrations_go_infra
  - sqlite_column_exists_go_infra
  - spa_handler_go_infra
  - http_router_go_infra
  - http_serve_go_infra
  - http_middleware_chain_go_infra
  - http_cors_middleware_go_infra
  - http_logger_middleware_go_infra
  - http_json_response_go_infra
  - http_error_response_go_infra
  - http_parse_body_go_infra
  - http_session_cookie_middleware_go_infra
  - http_session_token_extract_go_infra
  - http_session_cookie_set_go_infra
  - http_session_cookie_clear_go_infra
  - password_hash_go_infra
  - password_verify_go_infra
  - session_create_go_infra
  - session_cleanup_go_infra
  - duration_stats_go_datascience
  - format_duration_ts_core
  - format_datetime_short_ts_core
  - string_hash_palette_ts_core
  - color_bg_ts_ui
  - color_border_ts_ui
  - color_swatch_ts_ui
  - fetch_json_ts_infra
  - claude_stream_go_core
  - mcp_server_stdio_go_infra
  - mcp_server_http_go_infra
  - ws_upgrader_go_infra
uses_types:
  - DurationStats_go_datascience
framework: "net/http + vite + react + mantine + dnd-kit"
entry_point: "backend/main.go"
dir_path: "apps/kanban"
service:
  port: 8095
  health_endpoint: /api/board
  health_timeout_s: 3
  systemd_unit: kanban.service
  systemd_scope: user
  restart_policy: always
  runtime: systemd-user
  pc_targets:
    - aurgi-pc
  is_local_only: false

# Validacion end-to-end (fase 4 del bucle reactivo). Ver issue 0068.
e2e_checks:
  - id: build_frontend
    cmd: "cd frontend && pnpm install --frozen-lockfile && pnpm build"
    timeout_s: 180
    expect_exit: 0
  - id: build_backend
    cmd: "CGO_ENABLED=1 go build -tags fts5 -o kanban ."
    timeout_s: 120
    expect_exit: 0
  - id: migrations_apply
    cmd: "rm -f /tmp/kanban_e2e.db && ./kanban --port 0 --db /tmp/kanban_e2e.db --migrate-only"
    timeout_s: 15
    expect_exit: 0
  - id: migrations_schema
    cmd: "sqlite3 /tmp/kanban_e2e.db 'SELECT version FROM schema_migrations ORDER BY version;'"
    expect_stdout_contains: "1"
  - id: smoke_api
    cmd: "./kanban --port 8195 --db /tmp/kanban_e2e.db &"
    health: "http://127.0.0.1:8195/api/board"
    timeout_s: 10
  - id: tests_go
    cmd: "go test -tags fts5 -count=1 ./..."
    timeout_s: 120
    expect_exit: 0
  - id: smoke_files
    cmd: "bash e2e/files_smoke.sh"
    timeout_s: 30
    expect_exit: 0
---

## Arquitectura

Single-binary: backend Go con frontend Vite embebido. SQLite local con tres tablas (`columns`, `cards`, `card_column_history`) y endpoints REST.

```
./kanban --port 8095 --db kanban.db
```

### Schema SQLite (`migrations/001_init.sql` … `010_card_messages.sql`)

- **columns** — id, name, position, created_at
- **cards** — id, title, description, column_id (FK), position, created_at, updated_at
- **card_column_history** — id, card_id (FK), column_id, entered_at, exited_at
  - Una entrada con `exited_at IS NULL` = posicion actual
  - Al mover una tarjeta a otra columna: cierra la entrada activa (`exited_at = now`) e inserta una nueva
  - El borrado de tarjeta hace CASCADE sobre el historial
- **card_messages** (migration 010) — id, card_id (FK CASCADE), author_id (nullable), body, created_at. Comentarios humano-a-humano por card; distintos de `card_events` (sistema) y `/api/chat` (LLM global).

### API REST

| Metodo | Path | Cuerpo |
|---|---|---|
| GET | `/api/board` | — (retorna `{columns, cards}`, cada card incluye `time_in_column_ms`) |
| POST | `/api/columns` | `{name}` |
| PATCH | `/api/columns/{id}` | `{name?, position?}` |
| DELETE | `/api/columns/{id}` | — (cascade a cards) |
| POST | `/api/columns/reorder` | `{ids: [...]}` |
| POST | `/api/cards` | `{column_id, title, description?}` |
| PATCH | `/api/cards/{id}` | `{title?, description?}` |
| DELETE | `/api/cards/{id}` | — |
| POST | `/api/cards/{id}/move` | `{column_id, ordered_ids: [...]}` |
| POST | `/api/cards/{id}/duplicate` | — (clona la card en la misma columna al final; copia titulo+" (copia)", descripcion, color, requester, assignee, tags, stickers, deadline; NO copia historial ni mensajes) |
| GET | `/api/cards/{id}/messages` | — (lista de comentarios humano-a-humano de la card) |
| POST | `/api/cards/{id}/messages` | `{body}` (crea comentario; author = usuario de la sesion) |
| DELETE | `/api/cards/{cid}/messages/{mid}` | — (solo el autor puede borrar su mensaje) |
| GET | `/api/cards/{id}/history` | — (timeline con duraciones por columna) |
| GET | `/api/flags` | — (retorna `{ <name>: bool }` con los feature flags efectivos en esta instancia) |
| POST | `/api/auth/register` | `{username, password, display_name?}` (devuelve 403 `registration_disabled` si el flag `registration-enabled` esta en `false`) |

### Feature flags

`dev/feature_flags.json` (lado del repo) define los flags por instancia. Se cargan al arrancar (override con `--flags <path>`); fichero ausente equivale a "todos los flags en `false`". El endpoint `GET /api/flags` expone el estado actual para que el frontend oculte UI condicional (ej. el toggle de "Registrate" en `LoginPage` solo aparece cuando `registration-enabled` es `true`).

| Flag | Default | Efecto cuando esta en `true` |
|---|---|---|
| `registration-enabled` | `false` | Permite crear cuentas nuevas via `POST /api/auth/register` y muestra el toggle "Registrate" en la pantalla de login. |

### Frontend

- **dnd-kit** (`@dnd-kit/core` + `@dnd-kit/sortable`) para drag-and-drop entre y dentro de columnas (multi-container).
- **Mantine v9** + `@tabler/icons-react` para UI.
- **Modales** con `@mantine/modals` (confirmacion borrado, history timeline).
- Time-in-column live: `time_in_column_ms` del backend + tick local cada segundo para que el badge se actualice sin reload.
- DnD con `closestCorners` + `DragOverlay` para feedback visual al arrastrar.
- **Auto-refresh:** el board se recarga cada 30s (`api.getBoard`) sin interaccion del usuario; equivalente a pulsar el boton de refresco. El tick de 1s del time-in-column es independiente y no toca red.
- **Modal de card en dos columnas** (`CardEditPanel`): izquierda mantiene `CardForm` (titulo, solicitante, descripcion, asignacion, tags); derecha es un `Tabs` con `Chat` (por defecto) | `Enlaces` | `Archivos` (proximamente). Tamaño del modal: 85% del viewport.
  - **Chat per-card** (`CardChatPanel`): lista de comentarios humano-a-humano persistidos en `card_messages`. Enter envia, Shift+Enter salto de linea. Solo el autor puede borrar su propio mensaje.
  - **Enlaces** (`CardLinksPanel`): extrae URLs (`https?://...`) de titulo, descripcion y cuerpo de cada mensaje del chat. Deduplica, muestra hostname + URL completa + badge de origen. Click abre en pestaña nueva (`target="_blank"`).
- **Duplicar card:** click derecho sobre la card abre el menu contextual (mismo que el boton `⋮`), donde aparece el item "Duplicar". Al pulsarlo invoca `POST /api/cards/{id}/duplicate`. La copia se inserta al final de la misma columna con titulo + " (copia)".
- **Sesion obligatoria para chat:** `POST/DELETE /api/cards/{id}/messages` exige sesion activa (401 si falta). `author_id` siempre poblado; no hay comentarios anonimos.
- **Archivos** (`CardFilesPanel`): adjuntos por card almacenados en `apps/kanban/uploads/<card_id>/<random>__<safe_filename>` (filesystem, gitignored). Tabla `card_files` con soft-delete. Limite 10 MB por archivo. Tres vias de upload:
  1. Drag&drop en el editor de descripcion (`CardForm`) → inserta `![name](url)` (imagen) o `[name](url)` (resto) en la posicion del cursor.
  2. Drag&drop o boton paperclip en el chat (`CardChatPanel`) → crea un mensaje cuyo cuerpo es la ref markdown.
  3. Boton "Subir" en el tab Archivos → sube sin embed.
  - El renderer de mensajes (`MessageBody`) reconoce `![alt](url)` -> `<Image>` thumb 220px y `[name](url)` -> `<Anchor>`. Texto plano se renderiza con `whiteSpace: pre-wrap`.
  - Endpoints: `POST /api/cards/{id}/files` (multipart, 10 MB max), `GET /api/cards/{id}/files`, `GET /api/files/{id}` (sirve binario con `inline` o `attachment` segun MIME), `DELETE /api/files/{id}` (soft delete).

### Build

```bash
cd frontend && pnpm install && pnpm build
cd .. && CGO_ENABLED=1 go build -tags fts5 -o kanban .
./kanban --port 8095 --db kanban.db
# Browser: http://localhost:8095
```

### Dev (frontend con HMR contra backend)

```bash
# Terminal 1
./kanban --port 8095 --db kanban.db

# Terminal 2
cd frontend && pnpm dev
# Browser: http://localhost:5180 (vite proxy /api → 8095)
```

## Notas

- Puerto por defecto 8095.
- DB por defecto `kanban.db` en cwd.
- IDs de columnas y tarjetas: 16 chars hex (8 bytes random) via `random_hex_id_go_core`.
- El historial conserva la cronologia exacta — incluso despues de cerrar y reabrir el server, los tiempos vivos siguen contando desde `entered_at`.
- El borrado de columna hace CASCADE: las tarjetas se borran y su historial tambien. Si se quiere preservar el historial al borrar, deberia archivarse en lugar de borrar.


## Capability growth log

Una linea por bump SemVer. Bump-type segun `.claude/commands/version.md`:
- `major`: breaking observable (CLI args, schema BBDD propia, formato wire).
- `minor`: feature aditiva (nuevo panel, endpoint, opcion).
- `patch`: bugfix sin cambio observable.

- v0.1.0 (2026-05-18) — baseline.
- v0.2.0 (2026-05-27) — adjuntos de archivos por card (issue 0128): tabla `card_files` con soft-delete, endpoints REST (`POST/GET/DELETE /api/cards/{id}/files`, `GET/DELETE /api/files/{id}`), tres vias de upload (drag&drop en descripcion y chat, boton en tab Archivos), render inline de imagenes via `MessageBody`. Limite 10 MB.
- v0.3.1 (2026-05-21) — patch: debounce board.invalidated (300ms trailing) + autoClose 4s en toasts de notification.created. Fix de blow-up de memoria en navegador por ráfagas de SSE.
- v0.4.0 (2026-05-22) — minor: endpoint MCP Streamable HTTP `/mcp` con per-user bearer tokens (tabla `mcp_tokens`, migration 017). Modal "MCP tokens" en avatar menu para generar/listar/revocar. Vite proxy enruta `/mcp` a WSL. Usa nueva funcion `mcp_server_http_go_infra`. Doc en `docs/MCP.md`.
- v0.5.0 (2026-05-27) — minor: merge ramas notifications-realtime + modules con master post-files. Trae notificaciones SSE (tabla `notifications`, migration 015), modulos externos para sincronizacion bidireccional (Jira, etc., tabla `modules`, migration 016), tokens MCP per-user (migration 017). Conserva files attachments del 0128. Renumeradas migrations notif 014/015/016 -> 015/016/017.
