AppFolio 로컬 개발 루프
개요
AppFolio 부동산 관리 API 통합을 위한 로컬 개발 워크플로우입니다. 목업(mock) 부동산, 임차인, 임대 엔드포인트를 통해 빠른 피드백 루프를 제공하여 실제 API 할당량을 소모하지 않고 통합을 구축하고 테스트할 수 있습니다. 빠른 반복을 위한 목업 모드와 실제 AppFolio Stack API에 대한 배포 전 검증을 위한 샌드박스 모드 간에 전환할 수 있습니다.
필수 조건
- 프로덕션 주소, 이름, 결제 정보가 포함되지 않은 합성 부동산, 임차인, 임대, 작업 지시 픽스처를 사용하는 목업 전용 로컬 환경.
- 별도로 관리되는 샌드박스 자격 증명과 전용 통합 레인을 위한 승인된 안전 읽기 픽스처. 로컬 개발 서버에서 절대 로드되지 않습니다.
- 요청 형태와 상태만 기록하는 로그 정책과 샌드박스 할당량, 픽스처 재설정, 자격 증명 교체를 위한 명시적 소유자.
지침
- 로컬 서버를 목업 모드로만 실행하고, 결정론적 픽스처가 포함된 합성 경로에 대해 읽기/쓰기를 수행합니다.
- 샌드박스 연결 확인 전에 단위 테스트에서 요청 검증, 멱등성, 수정, 에러 처리를 테스트합니다.
- 계약에 바인딩된 관리 클라이언트와 하나의 승인된 안전 읽기 픽스처를 사용하여 샌드박스 레인을 별도로 실행합니다. 로컬 프록시를 라이브 API 터널로 전환하지 마십시오.
- 픽스처, 자격 증명, 요청 예산 또는 출력 수정이 확인되지 않은 경우 중단하고 환경을 수정한 후 계속합니다.
환경 설정
cp .env.example .env
# 로컬에서는 제공자 자격 증명을 비워둡니다. 목업 모드가 기본값입니다.
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
개발 서버
// 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("로컬 서버는 목업 전용입니다. 관리형 샌드박스 통합 레인을 사용하십시오.");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio 개발 서버 실행 중 :3001 [mock=${MOCK}]`));
목업 모드
// src/dev/mocks.ts — 현실적인 부동산 관리 응답
import express from "express";
export function mountMockRoutes(app: express.Application) {
app.get("/api/v1/properties", (_req, res) => res.json([
{ id: "prop_1", name: "선셋 아파트먼트", address: { street: "123 Sunset Blvd", city: "Los Angeles", state: "CA" }, property_type: "residential", unit_count: 24 },
{ id: "prop_2", name: "다운타운 오피스", address: { street: "456 Main St", city: "San Francisco", state: "CA" }, property_type: "commercial", unit_count: 8 },
]));
app.get("/api/v1/tenants", (_req, res) => 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, res) => 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: express.Request, res: express.Response) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}
테스트 워크플로우
npm run dev:mock & # 백그라운드에서 목업 서버 시작
npm run test # vitest를 사용한 단위 테스트
npm run test -- --watch # 빠른 반복을 위한 감시 모드
npm run test:sandbox # 관리형 읽기 전용 샌드박스 레인
디버그 팁
DEBUG=express:*를 설정하여 모든 라우트 매칭 및 미들웨어 실행을 추적합니다.- 원시 임차인 페이로드 덤프가 아닌 픽스처 개수 및 스키마 형태에 대한 로컬 테스트 어설션을 사용합니다.
- 라이브 API에 대해 테스트할 때
X-RateLimit-Remaining헤더를 확인합니다. - AppFolio 샌드박스는 소유하지 않은 속성에 대해
403을 반환합니다. API 키 범위를 확인하십시오. - 개발 중에는 수정된 엔드포인트/상태/개수 원격 측정에만 인터셉터를 사용합니다.
출력
- 제공자 자격 증명에 의존하지 않는 합성 부동산 관리 픽스처를 사용하는 결정론적 목업 전용 로컬 서버
- 검증, 멱등성, PII로부터 안전한 관찰 가능성에 대한 단위 테스트 증거
- 수정된 안전 읽기 상태만 포함하는 별도의 관리형 샌드박스 결과
예시
작업 지시 UI 변경을 위해 합성 목업 픽스처를 추가하고 로컬에서 요청 스키마와 중복 제출 동작을 테스트합니다. 반환된 ID와 상태를 어설션하되 요청 본문이나 임차인 레코드는 내보내지 않습니다. 단위 테스트가 통과한 후 승인된 하나의 안전 읽기 픽스처에 대해 전용 샌드박스 레인을 실행합니다. 목업 모드가 비활성화되거나 샌드박스 자격 증명이 로컬에 나타나거나 응답에 수정되지 않은 임차인 필드가 포함된 경우 실행을 중단하고 로컬 경계를 복원합니다.
에러 처리
| 문제 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | API 키가 유효하지 않거나 만료됨 | AppFolio Stack 포털에서 재생성 |
403 Forbidden | 키에 엔드포인트에 대한 범위가 없음 | 추가 권한 요청 |
404 Not Found | 잘못된 속성 ID 또는 경로 | 샌드박스에 리소스가 존재하는지 확인 |
429 Too Many Requests | 속도 제한 초과 | 지수 백오프 추가, 목업 모드 사용 |
ECONNREFUSED :3001 | 개발 서버가 실행 중이 아님 | npm run dev:mock 먼저 실행 |
리소스
다음 단계
appfolio-debug-bundle을 참조하십시오.