Bucle de Desarrollo Local AppFolio
Resumen
Flujo de trabajo de desarrollo local para la integración con la API de administración de propiedades de AppFolio. Proporciona un ciclo de retroalimentación rápida con endpoints mock de propiedades, inquilinos y arrendamientos, para que puedas construir y probar integraciones sin consumir cuota de API en vivo. Alterna entre modo mock para iteración rápida y modo sandbox para validación previa al despliegue contra la API real de AppFolio Stack.
Requisitos previos
- Un entorno local exclusivamente mock con fixtures sintéticos de propiedades, inquilinos, arrendamientos y órdenes de trabajo que no contengan direcciones, nombres o pagos reales.
- Una credencial sandbox gestionada por separado y un fixture de solo lectura aprobado para el carril de integración dedicado; nunca es cargado por el servidor de desarrollo local.
- Una política de registro que solo registre la forma y el estado de la solicitud, más un propietario explícito para la cuota sandbox, el restablecimiento de fixtures y la rotación de credenciales.
Instrucciones
- Ejecuta el servidor local solo en modo mock y realiza lecturas/escrituras contra rutas sintéticas con fixtures deterministas.
- Prueba la validación de solicitudes, idempotencia, enmascaramiento y manejo de errores en pruebas unitarias antes de cualquier verificación de conectividad sandbox.
- Ejecuta el carril sandbox por separado con el cliente gestionado vinculado al contrato y un fixture de solo lectura autorizado; no conviertas un proxy local en un túnel de API en vivo.
- Detente cuando el fixture, las credenciales, el presupuesto de solicitudes o el enmascaramiento de salida no estén verificados, luego corrige el entorno antes de continuar.
Configuración del Entorno
cp .env.example .env
# Deja las credenciales del proveedor en blanco localmente. El modo mock es el predeterminado.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
Servidor de Desarrollo
// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("El servidor local es solo mock; usa el carril de integración sandbox gestionado");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`Servidor de desarrollo AppFolio en :3001 [mock=${MOCK}]`));
Modo Mock
// src/dev/mocks.ts — respuestas realistas de gestión de propiedades
export function mountMockRoutes(app: any) {
app.get("/api/v1/properties", (_req: any, res: any) => res.json([
{ id: "prop_1", name: "Sunset Apartments", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
{ id: "prop_2", name: "Downtown Office", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commercial", unit_count: 8 },
]));
app.get("/api/v1/tenants", (_req: any, res: any) => res.json([
{ id: "t1", first_name: "Jane", last_name: "Smith", email: "[email protected]", unit_id: "u1", lease_id: "l1" },
]));
app.get("/api/v1/leases", (_req: any, res: any) => res.json([
{ id: "l1", unit_id: "u1", start_date: "2025-01-01", end_date: "2026-01-01", rent_amount: 2500, status: "active" },
]));
app.post("/api/v1/work-orders", (req: any, res: any) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}
Flujo de Trabajo de Pruebas
npm run dev:mock & # Inicia el servidor mock en segundo plano
npm run test # Pruebas unitarias con vitest
npm run test -- --watch # Modo vigilancia para iteración rápida
npm run test:sandbox # Carril sandbox gestionado y de solo lectura
Consejos de Depuración
- Configura
DEBUG=express:*para rastrear todas las coincidencias de rutas y la ejecución de middleware - Usa aserciones locales de prueba para conteos de fixtures y forma del esquema, no volcados de payload de inquilinos en bruto
- Revisa el encabezado
X-RateLimit-Remainingal probar contra la API en vivo - El sandbox de AppFolio devuelve
403para propiedades que no posees: verifica el alcance de tu clave API - Usa interceptores solo para telemetría de endpoint/estado/recuento enmascarada durante el desarrollo
Salida
- Un servidor local determinista solo mock con fixtures sintéticos de gestión de propiedades y sin dependencia de credenciales del proveedor
- Evidencia de pruebas unitarias para validación, idempotencia y observabilidad segura de PII
- Un resultado sandbox gestionado separado que contiene solo estado de lectura segura enmascarado
Ejemplos
Para un cambio de UI de órdenes de trabajo, agrega un fixture mock sintético y prueba el esquema de solicitud más el comportamiento de envío duplicado localmente. Verifica el ID y estado devueltos sin emitir el cuerpo de la solicitud ni el registro del inquilino. Después de que pasen las pruebas unitarias, ejecuta el carril sandbox dedicado contra un fixture de solo lectura aprobado. Si el modo mock está deshabilitado, aparece una credencial sandbox localmente, o una respuesta contiene campos de inquilino sin enmascarar, detén la ejecución y restablece el límite local.
Manejo de Errores
| Problema | Causa | Solución |
|---|---|---|
401 Unauthorized | Clave API inválida o expirada | Regenerar en el portal de AppFolio Stack |
403 Forbidden | La clave no tiene alcance para el endpoint | Solicitar permisos adicionales |
404 Not Found | ID de propiedad o ruta incorrectos | Verificar que el recurso exista en el sandbox |
429 Too Many Requests | Límite de tasa excedido | Agregar retroceso exponencial, usar modo mock |
ECONNREFUSED :3001 | El servidor de desarrollo no está en ejecución | Ejecuta npm run dev:mock primero |
Recursos
Próximos Pasos
Consulta appfolio-debug-bundle.