Guía de contribución

Las reglas completas están en AGENTS.md. A continuación el resumen práctico.

Arquitectura por capas

Backend:

1. api/ → routers FastAPI, validan entrada y llaman al servicio.
2. services/ → lógica de negocio, sin dependencias HTTP.
3. repositories/ → acceso a datos.
4. models/ → SQLAlchemy.
5. schemas/ → Pydantic v2.

Frontend:

1. pages/ → vistas.
2. components/ → componentes reutilizables.
3. hooks/ → TanStack Query.
4. api/ → clientes HTTP (axios).
5. stores/ → Zustand.
6. types/ → TypeScript.
7. utils/ → helpers.

Límites estrictos

• Máximo 15 métodos/funciones por clase.
• Máximo 30 líneas por función.
• Máximo 180 líneas por archivo.

Si un archivo supera los límites, se debe refactorizar antes de seguir añadiendo código.

DRY

No duplicar lógica. Extraer a servicios o helpers compartidos:

• Backend: backend/app/services/shared/, helpers en repositories/ o utils/.
• Frontend: frontend/src/utils/ o hooks compartidos.

Componentes compartidos

Usar Ant Design nativos y ProComponents siempre que sea posible. No reinventar componentes básicos.

Layout

• Layout full-width con tope de 1920px.
• Usar clase .app-container.
• Breakpoints en frontend/src/styles/tokens.css.

Reactividad asíncrona

• staleTime de 5-30 segundos en TanStack Query.
• Invalidar queries en onSuccess de mutaciones.
• Optimistic updates en drag&drop, reordenar y toggles.
• Sin useState para datos del servidor.
• Loading states con Spin/Skeleton.

Git

• Rama de trabajo: serconsa-react.
• Commits con conventional commits: tipo(scope): descripcion.
• No trabajar en main.
• Merge a main con --ff-only.

OpenSpec

Antes de implementar funcionalidades relevantes, crear un change de OpenSpec:

openspec-propose → openspec-apply-change → openspec-archive-change

Seguridad

• Todo cambio pasa por @security-specialist.
• No exponer secretos.
• Validar ownership en recursos.
• Usar AST seguro en lugar de eval().

Cómo empezar una tarea

1. Leer AGENTS.md y esta documentación.
2. Revisar la tarea de kanban asignada.
3. Explorar el código relevante con search_files / read_file.
4. Si es funcionalidad relevante, crear change de OpenSpec.
5. Implementar siguiendo las capas y límites.
6. Escribir o actualizar tests.
7. Ejecutar lint y tests.
8. Hacer commit en serconsa-react.

Revisión de código

Antes de marcar una tarea como lista:

• Tests pasan.
• Lint sin errores nuevos.
• No se superan límites de líneas/métodos.
• Se ha verificado la funcionalidad.
• Se actualiza la documentación si procede.