Primero se prueba. Después se construye.

#La prueba

Toda prueba sigue la misma estructura. El problema es el protagonista y la tecnología queda detrás.

1. 01 · Fricción¿Qué no funciona bien?
2. 02 · Hoy¿Cómo se hace hoy?
3. 03 · Oportunidad¿Qué podría cambiar?
4. 04 · PruebaDemo funcional
5. 05 · Impacto¿Qué mejora y cómo se mide?

• Funcional, no maqueta. La persona la usa y entiende cómo funcionaría en su empresa: decide, reasigna, cambia una regla y ve el efecto.
• Lógica visible. Cada decisión del sistema dice qué regla la produjo (ver Lógica visible).
• Datos creíbles. Nombres, montos y lugares realistas. Los casos usan la Ciudad de México.
• Una forma por caso. Cada caso tiene la vista que su problema pide. Proveedores es un expediente, Aprobaciones es una bandeja con vencimientos. Nunca una plantilla de tablero genérica.

Las pruebas viven en el mismo proyecto del sitio, con un patrón fijo de tres archivos:

app/demos/aprobaciones/page.tsx        la ruta y sus metadatos
components/demos/ApprovalDemo.tsx      la página: intro, demo, impacto
components/demos/Workbench.tsx         la aplicación funcional
lib/demos/approvals.ts                 el motor: reglas, rutas, datos de ejemplo

El motor (lib/demos/*.ts) es TypeScript puro, sin React. Es la parte que se traduce casi literal al servidor cuando la prueba se vuelve sistema. El estado de la demo se guarda en el navegador de quien la usa.

#Arquitectura de referencia

Un sistema de Naoro tiene cuatro capas y algunas piezas a los lados. Se usa solo lo que el caso pide: un tablero quizá no necesita trabajos en segundo plano.

#Estructura de un servicio

La API se organiza por dominio del negocio, no por tipo de archivo. Cada dominio tiene sus rutas, esquemas, modelos y servicios juntos.

servicio/
├── app/
│   ├── main.py              crea la app, monta routers, lifespan
│   ├── config.py            Settings con pydantic-settings (lee .env)
│   ├── db.py                engine y sesión async de SQLAlchemy
│   ├── auth.py              dependencias de usuario actual y roles
│   ├── aprobaciones/        un dominio del negocio
│   │   ├── router.py        endpoints (delgados)
│   │   ├── schemas.py       modelos Pydantic de entrada y salida
│   │   ├── models.py        tablas SQLAlchemy
│   │   ├── service.py       casos de uso: aquí vive la lógica
│   │   └── rules.py         motor de reglas, Python puro y probado
│   ├── integraciones/       clientes de ERP, CRM y APIs externas
│   └── workers/             tareas de Celery
├── migrations/              Alembic
├── tests/                   pytest, espejo de app/
├── pyproject.toml
└── docker-compose.yml       api, db, redis, worker

• Los routers solo traducen HTTP: validan con el esquema, llaman al servicio y devuelven el resultado.
• Las reglas no importan nada de FastAPI ni de SQLAlchemy. Así se prueban con datos en memoria.
• Cada cambio de estado importante escribe una línea en la bitácora: quién, cuándo, qué regla y por qué.

#De la prueba al sistema

#Integraciones

Conectar es tan importante como construir. Una integración frágil devuelve a la gente a la captura doble.

• Idempotencia. Repetir una sincronización no duplica registros. Guarda el identificador externo.
• Reintentos con espera creciente para fallas temporales (tenacity). Las fallas permanentes se registran y se avisan.
• Bitácora de cada llamada: qué se pidió, qué respondió, cuánto tardó.
• Una sola fuente de verdad por dato. Decide con el cliente dónde vive cada dato y en qué dirección fluye.
• Conciliación. Un proceso periódico compara ambos lados y reporta diferencias.

#Flujo de trabajo

1. Cada tarea nace de una ficha de fricción o de la ficha de sistema. Si no se puede ligar a una, se cuestiona.
2. Rama corta por tarea y cambios pequeños, fáciles de revisar.
3. Revisión de otra persona antes de integrar. Se revisa que funcione y que se lea igual que el código de alrededor.
4. Verificaciones automáticas: ruff y pytest en el servidor, tsc y next build en la interfaz.
5. Tres ambientes: local, pruebas con datos de ejemplo y producción. Las migraciones se prueban antes en el ambiente de pruebas.
6. Producción solo con aprobación explícita del responsable del proyecto.

#Definición de terminado

Algo está terminado cuando funciona en la operación, no cuando se entrega. Nos importa que funcione.

• Funciona con datos reales, volumen real y los permisos de cada rol.
• La lógica se puede explicar: cada decisión del sistema dice qué regla la produjo.
• Tiene pruebas para las reglas y para los casos que fallaron en la prueba.
• La ficha de sistema está actualizada: qué hace, reglas, integraciones, responsables.
• La métrica de impacto se mide y se compara contra la línea base del diagnóstico.
• Quienes lo usan saben a quién avisar cuando algo falla.

#El papel de la IA

La IA es parte de cómo construimos, no la razón para construir.

• Al construir: investigar, analizar documentos y datos del levantamiento, escribir y revisar código. Lo que produce se revisa igual que el trabajo de una persona.
• Dentro del sistema, solo cuando una regla no alcanza: leer documentos, clasificar texto libre, buscar en conocimiento interno, detectar anomalías. Siempre con un camino para que una persona revise y corrija.
• Nunca decide qué problema resolver. Eso lo deciden la operación y las personas que hacen el trabajo.