Loop de Desenvolvimento Local AppFolio
Visão Geral
Fluxo de trabalho de desenvolvimento local para integração com a API de gerenciamento de propriedades AppFolio. Fornece um loop de feedback rápido com endpoints mockados de propriedades, inquilinos e contratos, permitindo construir e testar integrações sem consumir cota da API real. Alterne entre o modo mock para iteração rápida e o modo sandbox para validação pré-implantação contra a API AppFolio Stack real.
Pré-requisitos
- Um ambiente local apenas com mocks contendo dados sintéticos de propriedades, inquilinos, contratos e ordens de serviço, sem endereços, nomes ou pagamentos reais.
- Uma credencial sandbox gerenciada separadamente e um fixture de leitura segura aprovado para a faixa de integração dedicada; ela nunca é carregada pelo servidor de desenvolvimento local.
- Uma política de logs que registra apenas a forma e o status da requisição, além de um proprietário explícito para a cota sandbox, reset de fixtures e rotação de credenciais.
Instruções
- Execute o servidor local apenas no modo mock e faça leituras/gravações nas rotas sintéticas com fixtures determinísticas.
- Teste a validação de requisição, idempotência, redação e tratamento de erros em testes unitários antes de qualquer verificação de conectividade com o sandbox.
- Execute a faixa sandbox separadamente com o cliente gerenciado vinculado a um contrato e um fixture de leitura segura autorizado; não transforme um proxy local em um túnel para a API real.
- Pare quando o fixture, as credenciais, o orçamento de requisições ou a redação de saída não estiverem verificados e corrija o ambiente antes de continuar.
Configuração do Ambiente
cp .env.example .env
# Deixe as credenciais do provedor em branco localmente. O modo mock é o padrão.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
Servidor de Desenvolvimento
// 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("O servidor local é apenas mock; use a faixa de integração sandbox gerenciada");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`Servidor de desenvolvimento AppFolio em :3001 [mock=${MOCK}]`));
Modo Mock
// src/dev/mocks.ts — respostas realistas de gerenciamento de propriedades
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" }));
}
Fluxo de Trabalho de Testes
npm run dev:mock & # Inicia o servidor mock em segundo plano
npm run test # Testes unitários com vitest
npm run test -- --watch # Modo de observação para iteração rápida
npm run test:sandbox # Faixa sandbox gerenciada e somente leitura
Dicas de Depuração
- Defina
DEBUG=express:*para rastrear a correspondência de rotas e execução de middlewares - Use asserções de teste locais para contagens de fixtures e formato de esquema, não para despejos brutos de payload de inquilinos
- Verifique o cabeçalho
X-RateLimit-Remainingao testar contra a API real - O sandbox AppFolio retorna
403para propriedades que você não possui — verifique o escopo da sua chave de API - Use interceptores apenas para telemetria redigida de endpoint/status/contagem durante o desenvolvimento
Saída
- Um servidor local determinístico apenas mock com fixtures sintéticos de gerenciamento de propriedades e sem dependência de credenciais do provedor
- Evidências de testes unitários para validação, idempotência e observabilidade segura para PII
- Um resultado separado do sandbox gerenciado contendo apenas o status de leitura segura redigido
Exemplos
Para uma alteração na interface de ordens de serviço, adicione um fixture mock sintético e teste o esquema da requisição e o comportamento de submissão duplicada localmente. Afirme o ID e o status retornados sem emitir o corpo da requisição ou o registro do inquilino. Após os testes unitários passarem, execute a faixa sandbox dedicada contra um fixture de leitura segura aprovado. Se o modo mock estiver desabilitado, uma credencial sandbox aparecer localmente ou uma resposta contiver campos de inquilinos não redigidos, pare a execução e restaure os limites locais.
Tratamento de Erros
| Problema | Causa | Correção |
|---|---|---|
401 Unauthorized | Chave de API inválida ou expirada | Regenerar no portal AppFolio Stack |
403 Forbidden | Chave sem escopo para o endpoint | Solicitar permissões adicionais |
404 Not Found | ID de propriedade ou caminho errado | Verificar se o recurso existe no sandbox |
429 Too Many Requests | Limite de taxa excedido | Adicionar backoff exponencial, usar modo mock |
ECONNREFUSED :3001 | Servidor de desenvolvimento não está em execução | Executar npm run dev:mock primeiro |
Recursos
Próximos Passos
Consulte appfolio-debug-bundle.