AppFolio 參考架構
概述
適用於與 AppFolio Stack API 整合的物業管理生產級架構。專為需要即時空房追蹤、租戶生命週期管理、工單派發以及會計對帳的多物業組合而設計。關鍵設計考量:確保租賃決策的資料新鮮度、實現財務準確性的冪等同步,以及維持租戶入口網站的即時回應能力。
先決條件
- 一份由供應商驗證的合約,涵蓋端點、驗證、事件(如有)、速率限制、資料駐留以及允許的下游會計/CRM 影響。
- 獨立的分段環境與生產環境,配備受管密碼、合成測試數據、持久佇列/冪等儲存,以及指定的對帳負責人。
- 資料分類應將儀表板和快取模型限制為最小允許欄位;租戶聯絡人、付款和餘額資料需要獨立加密儲存和存取控制。
操作說明
- 首先建立合約約束的客戶端和安全唯讀服務層,在加入寫入或事件處理之前,先設定端點預算、最小化快取條目和可觀測性。
- 僅在合約以及持久性原始訊息主體、簽章、持久性和重播邊界都經過驗證後,才啟用供應商事件;否則使用有界限的增量式對帳。
- 在進行任何工單、會計、租戶或租約變更之前,先持久化一個冪等/對帳記錄,並要求明確授權。
- 在推升到生產環境前,先在分段環境中使用合成數據、強制供應商故障、重複事件/重試以及回滾演練來驗證架構。
架構圖
儀表板 (React) ──→ 物業服務 ──→ Redis 快取 ──→ AppFolio Stack API
↓ /properties
佇列 (Bull) ──→ 同步工作者 /tenants
↓ /leases
事件處理器 ←── 供應商事件* /work-orders
↓ /bills
會計同步 ──→ QuickBooks/Xero
* 僅在有效合約確認其傳遞和安全語義時使用供應商事件;否則餵養佇列給有界限的對帳。
服務層
class PropertyService {
constructor(private client: AppFolioClient, private cache: CacheLayer) {}
async getPortfolioSummary(propertyIds: string[]): Promise<PortfolioSummary> {
const properties = await Promise.all(
propertyIds.map(id => this.cache.getOrFetch(`prop:${id}`, () => this.client.get(`/properties/${id}`)))
);
return { totalUnits: properties.reduce((sum, p) => sum + p.units.length, 0),
vacancyRate: this.calcVacancy(properties), pendingWorkOrders: await this.getPendingOrders(propertyIds) };
}
async routeWorkOrder(order: WorkOrderRequest): Promise<string> {
const property = await this.client.get(`/properties/${order.propertyId}`);
const vendor = this.selectVendor(property.region, order.category);
return this.client.post('/work-orders', { ...order, assigned_vendor: vendor });
}
}
快取策略
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5 分鐘 — 變更不頻繁
tenants: { ttl: 120, prefix: 'tenant' }, // 2 分鐘 — 中等變動率
leases: { ttl: 60, prefix: 'lease' }, // 1 分鐘 — 財務準確性
workOrders: { ttl: 30, prefix: 'wo' }, // 30 秒 — 即時追蹤
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15 秒 — 租賃速度至關重要
};
// Webhook 驅動的快取失效:AppFolio 事件立即刷新對應的快取鍵
事件管線
class PropertyEventPipeline {
private queue = new Bull('appfolio-events', { redis: process.env.REDIS_URL });
async onWebhook(event: AppFolioEvent): Promise<void> {
await this.queue.add(event.type, event, { attempts: 3, backoff: { type: 'exponential', delay: 2000 } });
}
async processLeaseEvent(event: LeaseEvent): Promise<void> {
if (event.type === 'lease.signed') await this.updateVacancy(event.propertyId);
if (event.type === 'lease.terminated') await this.triggerMoveOutWorkflow(event);
}
async processWorkOrderEvent(event: WorkOrderEvent): Promise<void> {
if (event.status === 'completed') await this.reconcileVendorInvoice(event);
}
}
資料模型
interface Property { id: string; name: string; address: Address; units: Unit[]; region: string; }
interface TenantRef { id: string; leaseId: string; contactCiphertextRef: string; }
interface Lease { id: string; propertyId: string; unitId: string; tenantId: string; startDate: string; endDate: string; monthlyRent: number; status: 'active' | 'pending' | 'terminated'; }
interface WorkOrder { id: string; propertyId: string; unitId: string; category: 'plumbing' | 'electrical' | 'hvac' | 'general'; status: string; assignedVendor: string; }
擴展考量
- 按物業區域劃分同步工作者,以避免跨區域的 API 速率限制
- 對儀表板查詢使用唯讀副本;寫入路徑通過事件管線處理
- 透過佇列批次發送租戶通知(租金提醒、維護更新),以避免電子郵件速率限制
- 積極快取空房資料 — 租賃專員對此端點的訪問次數是其他端點的 10 倍
- 按物業組合分片處理工單派發,以實現每個管理群組的獨立擴展
錯誤處理
| 元件 | 故障模式 | 復原方式 |
|---|---|---|
| 物業同步 | AppFolio 429 速率限制 | 含抖動的指數退避,按物業的斷路器 |
| 租約 webhook | 重複事件傳遞 | 基於租約 ID + 事件時間戳的冪等鍵 |
| 工單派發 | 供應商 API 逾時 | 佇列重試,並回退至人工指派 |
| 會計同步 | 餘額不匹配 | 對帳佇列,帶有人工審查標記 |
| 租戶入口網站 | 快取未命中風暴 | 過時-重新驗證模式,API 層的斷路器 |
輸出
- 一個合約約束的、分階段的架構,其中服務、快取、佇列、資料和對帳責任明確分離
- 最小化的儀表板參照,以及對租戶聯絡人、付款和餘額資料的加密/受控邊界
- 一個基於分段環境故障、重複/重播、速率限制、回滾和對帳證據支援的部署決策
範例
對於空房儀表板的部署,從合成物業和單元 ID、一個有界限的唯讀服務層以及一個公開資料年齡的快取開始。注入一個重複事件或對帳記錄、一個 429 錯誤和一個下游會計逾時,以證明佇列和冪等儲存能防止重複影響。僅在結果保持完整且經授權,且回滾/對帳負責人能展示其路徑時才進行推升。如果事件支援、資料分類、持久狀態或寫入結果未經驗證,則保持相應路徑停用,並使用操作員主導的對帳。
資源
後續步驟
請參閱 appfolio-deploy-integration。