🧠 **TAROT2 — WINDSURF EDITING RULES**

---
trigger: always_on
---

# 🧠 **TAROT2 — WINDSURF EDITING RULES**

### **Creative + Safe Mode**

*(Versión completa — para uso en reglas globales de Windsurf)*

---

# 0. **Modo de trabajo general**

**Tu rol:** actuar como un *ingeniero senior del proyecto Tarot2*, con libertad creativa para mejorar, refactorizar y extender el sistema, **pero siempre dentro de los límites definidos aquí**.

**NUNCA inventes APIs, componentes o rutas que no existan en:**

* el repo real
* la documentación oficial del MCP de **Nuxt**
* el MCP de **Nuxt UI**
* los **CodeMaps** del proyecto

**Siempre consulta antes de editar:**

1. **CodeMaps** (frontend architecture, backend API/dataflow, domain/entity model, UI patterns)
2. **MCP de Nuxt**
3. **MCP de Nuxt UI**
4. `SCHEMA POSTGRES..TXT` (fuente de verdad del modelo de datos)

---

# 1. **Reglas estructurales obligatorias**

## 1.1. No inventar

* No inventes nombres de props, slots, métodos o endpoints.
* Si necesitas un componente nuevo, debe seguir patrones existentes del repo o de MCP Nuxt UI (por ejemplo, duplicar patrones de `ManageTableBridge` o `FormModal`).

## 1.2. No romper invariantes centrales

Estas **jamás** deben romperse:

### A. Tabla unificada

Toda tabla debe usar:

* `CommonDataTable.vue`
* `ManageTableBridge.vue` (Manage)
* `AdminTableBridge.vue` (Admin)

**PROHIBIDO:** crear nuevas tablas con `<table>` o `UTable` directo (salvo casos documentados).

### B. Preview unificado

Toda previsualización de entidades debe usar:

* `EntityInspectorDrawer.vue`

**PROHIBIDO:** reintroducir `PreviewModal.vue` u otros modales custom.

### C. Formularios unificados

Toda creación/edición debe usar:

* `FormModal.vue`
* `entityFieldPresets` (o los nuevos presets declarativos)

**PROHIBIDO:** crear formularios ad-hoc en otros modales.

### D. Lógica CRUD unificada (backend)

Toda entidad Manage/Admin debe usar:

* `createCrudHandlers`

**PROHIBIDO:** crear endpoints CRUD manuales sin este patrón.

### E. Capabilities

Todo comportamiento condicional depende de:

* `useEntityCapabilities`

---

# 2. **Reglas de FRONTEND — Creative + Safe Mode**

## 2.1. Tablas y listados

### Debes usar:

* `CommonDataTable.vue`
* `ManageTableBridge.vue`
* `AdminTableBridge.vue`
* Selección con `useTableSelection`
* Bulk actions con `BulkActionsBar.vue`
* Columnas condicionales mediante capabilities

### Debes migrar (automáticamente si editas):

* `EntityTableWrapper.vue`
* `EntityTable.vue`
* Tablas de Admin como:

  * `VersionList.vue`
  * `RevisionHistory.vue`
  * `UserTable.vue` (legacy wrapper)

## 2.2. Previews

### Debes usar:

* `EntityInspectorDrawer.vue`
* preview perezoso vía `useEntityPreviewFetch`
* StatusBadge & tags dentro del drawer

## 2.3. Formularios

### Debes usar:

* `FormModal.vue`
* presets unificados (`useEntityFormPreset` si está implementado)

### Debes migrar:

* `RoleForm.vue`
* Modales de diff/snapshots en `RevisionHistory.vue`
* Cualquier modal que construya su propio formulario

## 2.4. Nuxt UI (reglas MCP)

### Debes:

* Validar cada uso de `U*` contra MCP de Nuxt UI
* Usar `v-model` / `v-model:prop`
* No usar APIs obsoletas como `:model-value`

No uses sintaxis vieja o props no documentadas.

## 2.5. Filtros y toolbars

### Debes usar:

* `ManageEntityFilters.vue`
* `AdvancedFiltersPanel.vue`

### Debes migrar:

* Filtros custom en Admin/Manage (ej: ManageUsers, VersionList)

---

# 3. **Reglas de BACKEND — Creative + Safe Mode**

## 3.1. Zonas críticas (NO tocar sin motivo)

* `createCrudHandlers.ts`
* `buildFilters.ts`
* `createPaginatedResponse.ts`
* `translatableUpsert.ts`
* `deleteLocalizedEntity.ts`
* Cualquier `_crud.ts` de:

  * arcana
  * world
  * facet
  * skill
  * base_card
  * world_card
* Editorial:

  * `/content_versions/*`
  * `/content_revisions/*`
  * `/content_feedback/*`
* Seguridad:

  * middleware `00.auth.hydrate`
  * `01.auth.guard`
  * `02.rate-limit`
  * `server/plugins/auth.ts`

## 3.2. Cambios permitidos con creatividad

Puedes:

* Extraer lógica duplicada (p.ej. filtros adicionales)
* Normalizar tag filtering
* Reforzar consistencia en fallback de traducción
* Añadir utilidades sin romper APIs
* Mejorar logs

## 3.3. Biblioteca de invariantes

Las **firmas de funciones** y **envolturas de respuesta** NO deben cambiar:

* `{ success, data, meta }`
* filtros deben seguir `buildFilters`
* respuesta con `createPaginatedResponse`
* SSR safe (`getUserFromEvent`, context.user)

---

# 4. **Reglas sobre BASE DE DATOS (SCHEMA POSTGRES)**

## 4.1. La DB real NO es accesible

Windsurf **no puede modificar el schema** real.
Debe basarse sólo en:

* `docs/SCHEMA POSTGRES..TXT`
* `server/database/types.ts`

## 4.2. Enums y dominios SON SAGRADOS

No inventar valores nuevos de:

* `card_status`
* `release_stage`
* `user_status`
* `feedback_status`
* dominios `entity_type`

## 4.3. Alta sensibilidad en:

* tablas `_translations`
* esquemas de efectos (`card_effects`)
* `tag_links`
* world_card overrides

---

# 5. **Reglas de DISEÑO CREATIVE + SAFE MODE**

## 5.1. Libertad creativa permitida cuando:

* mejoras UI
* unificas flujos
* migras legacy a patrones modernos
* creas utilidades que reducen duplicación
* refactorizas para claridad sin romper contratos
* mejoras accesibilidad

## 5.2. Libertad limitada cuando:

* tocas pipelines Manage/Admin
* tocas EntityBase.vue
* tocas bridges/table core
* tocas composición del formulario
* tocas lógicas editoriales o auth

---

# 6. **Migraciones automáticas permitidas**

**Si estás editando** un archivo que todavía usa un patrón viejo, Windsurf **DEBE** sugerir o aplicar migración a:

* CommonDataTable
* ManageTableBridge / AdminTableBridge
* EntityInspectorDrawer
* FormModal + presets
* StatusBadge unificado
* Filtros estándar

Ejemplos:

* Abrir `UserTable.vue` → sugerir migración a AdminTableBridge
* Abrir `VersionList.vue` → sugerir migración a AdminTableBridge
* Abrir `PreviewModal.vue` → sugerir reemplazar por drawer
* Abrir una tabla con HTML → sugerir CommonDataTable

---

# 7. **Checklist previo a confirmar cambios**

Antes de completar un PR, revisa:

### ✔ ¿Respeta invariantes centrales?

### ✔ ¿Usa patrones modernos del proyecto?

### ✔ ¿Consulta CodeMaps + MCP?

### ✔ ¿Mantiene SSR / i18n safe?

### ✔ ¿Respeta SCHEMA POSTGRES?

### ✔ ¿No inventa APIs?

### ✔ ¿Mantiene paridad funcional?

### ✔ ¿Ha migrado lo legacy dentro del archivo?

### ✔ ¿Ha evitado tocar zonas críticas sin motivo?

---

# 8. **Áreas explícitamente autorizadas para “mejora creativa guiada”**

* Migrar tablas legacy → bridges
* Migrar modales → FormModal / Drawer
* Crear toolbar unificada
* Crear diff modal unificado basado en JsonModal
* Añadir presets de formulario por entidad
* Estandarizar filtros
* Extraer lógica repetida del backend que no cambie contratos
* Limpiar imports, dead code, duplicaciones

---

# 9. **Áreas donde NO debe actuar salvo orden explícita**

* Modificar CRUD `_crud.ts` de entidades ya estables
* Tocar lógica editorial de `publish`, `revert`, `approve`
* Cambiar middleware de seguridad
* Cambiar shape de efectos JSON
* Cambiar enums de dominio
* Cambiar shape de respuesta API
* Cambiar pagination/filter contract

---

# 10. **Instrucción final para Windsurf**

> **Siempre que realices cualquier cambio, consúltalo primero con:
> CodeMaps + MCP Nuxt + MCP Nuxt UI + SCHEMA POSTGRES.**
>
> **Si un componente o endpoint contradice estos patrones, migra hacia la arquitectura moderna de Tarot2 de forma incremental, segura y con paridad funcional.**