AppFolio 参考架构
概述
针对 AppFolio Stack API 的物业管理系统集成的生产级架构。专为需要实时空置跟踪、租户生命周期管理、工单分配和财务对账的多物业组合而设计。关键设计驱动因素:租赁决策的数据新鲜度、财务准确性的幂等同步以及面向租户的门户响应能力。
前提条件
- 一份经过提供商验证的合同,涵盖端点、认证、事件(如有)、速率限制、数据驻留以及允许的下游会计/CRM 效果。
- 独立的暂存和生产环境,具有托管密钥、合成测试数据、持久队列/幂等存储以及指定的对账负责人。
- 数据分类将仪表盘和缓存模型限制为最小的允许字段;租户联系方式、支付和余额数据需要单独的加密存储和访问控制。
指令
- 首先构建合同绑定的客户端和安全只读服务层,包括端点预算、最小化的缓存条目和可观测性,然后再添加写入或事件处理。
- 仅当合同和持久的原始消息体、签名、持久化和重放边界已通过验证后,才启用提供商事件;否则使用有界增量对账。
- 在任何工单、会计、租户或租约变更之前,持久化一个幂等性/对账记录,并要求明确授权。
- 在暂存环境中使用合成数据、模拟提供商故障、重复事件/重试以及回滚演练来验证架构,然后再进行投产。
架构图
Dashboard (React) ──→ Property Service ──→ Redis Cache ──→ AppFolio Stack API
↓ /properties
Queue (Bull) ──→ Sync Worker /tenants
↓ /leases
Event Handler ←── Provider events* /work-orders
↓ /bills
Accounting Sync ──→ 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 超时 | 队列重试,并回退到手动分配 |
| 会计同步 | 余额不匹配 | 带有审核标记的对账队列 |
| 租户门户 | 缓存未命中风暴 | Stale-while-revalidate 模式,API 层熔断器 |
输出
- 一个合同绑定、分阶段的架构,其中服务、缓存、队列、数据和对账职责明确分离
- 最小化的仪表盘引用,以及针对租户联系方式、支付和余额数据的加密/控制边界
- 基于暂存失败、重复/重放、速率、回滚和对账证据的部署决策
示例
对于空置仪表盘的部署,首先使用合成的物业和单元 ID、一个有界的安全读取以及一个暴露数据时效的缓存。注入一个重复事件或对账记录、一个 429 错误以及一个下游会计超时,以验证队列和幂等存储能够防止重复影响。仅当结果保持完整且经过授权,并且回滚/对账负责人能够演示其路径时,方可投产。如果事件支持、数据分类、持久状态或写入结果未经验证,请保持相应路径禁用,并使用人工主导的对账流程。
资源
下一步
参见 appfolio-deploy-integration。