Communitygithub.com

AppFolio 升级与迁移

在 AppFolio API 版本之间进行迁移,并处理端点变更。

AppFolio 升级与迁移 是什么?

此技能专为 AppFolio 物业管理系统集成而设计,帮助开发者在不同版本的 REST API 之间进行升级和迁移。它能够自动检测当前 API 版本,识别已弃用的端点,并应用模式转换(例如,将属性对象的 `address_line1` 字段映射为 `street_address`,租户对象的 `lease_end` 字段映射为 `lease_expiry_date`)。该技能支持版本检测、模式迁移、从基于偏移的分页过渡到基于游标的分页,以及内置的回滚策略(在 410/404 错误时自动回退到旧版本)。主要适用于 AppFolio 平台,能够显著降低因 API 变更导致的集成故障风险。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-upgrade-migration

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AppFolio 升级与迁移 是做什么的?

概述

AppFolio 物业管理集成依赖于版本化的 REST API 端点,这些端点会随着平台的演进而变化。升级可能会重命名物业和租客对象上的字段、更改分页模型、弃用工单端点,以及改变基本身份验证流程。此技能可检测您当前的 API 版本,将弃用的响应形状映射到替代形状,并在新版本失败时自动回滚。

前提条件

  • 文档中记录了当前 API 版本前缀(例如 /api/v1/)
  • 可以访问 AppFolio API 变更日志和发布说明
  • 包含测试物业和租客数据的暂存环境
  • 客户端 ID 和密钥存储在环境变量中
  • 现有的集成测试套件覆盖了核心端点

操作说明

  1. 运行版本检测,将您当前的 API 版本与最新版本进行比较。
  2. 查看 AppFolio 变更日志,了解两个版本之间的破坏性变更。
  3. 对物业和租客响应对象应用模式迁移转换。
  4. 将端点 URL 从旧版本前缀更新为新版本前缀。
  5. 如果新版本要求,将分页从基于偏移切换为基于游标。
  6. 在暂存环境中运行冒烟测试套件,验证所有端点是否正常响应。
  7. 启用回滚策略后部署到生产环境。
  8. 监控错误日志中表示遗漏迁移步骤的 410/401 响应。

输出

成功迁移后,此技能会生成:

  • 一个 VersionInfo 对象,确认当前版本、最新版本和已弃用的版本
  • 符合新模式的已转换物业和租客对象
  • 针对物业、租客、工单和会计端点的冒烟测试结果
  • 回滚日志条目(如果任何端点回退到了之前的版本)

版本检测

interface VersionInfo { current: string; latest: string; deprecated: string[]; }

async function detectApiVersion(baseUrl: string, headers: Record<string, string>): Promise<VersionInfo> {
  const res = await fetch(`${baseUrl}/api/status`, { headers });
  const body = await res.json();
  const current = res.headers.get("X-AppFolio-Api-Version") ?? body.api_version;
  const deprecated: string[] = body.deprecated_versions ?? [];
  if (deprecated.includes(current)) {
    console.warn(`版本 ${current} 已弃用。请迁移到 ${body.latest_version}。`);
  }
  return { current, latest: body.latest_version, deprecated };
}

模式迁移

interface LegacyProperty { address_line1: string; unit_count: number; mgr_id: string; }
interface CurrentProperty { street_address: string; total_units: number; manager_id: string; }

function migrateProperty(old: LegacyProperty): CurrentProperty {
  return { street_address: old.address_line1, total_units: old.unit_count, manager_id: old.mgr_id };
}

interface LegacyTenant { lease_end: string; balance_due: number; }
interface CurrentTenant { lease_expiry_date: string; outstanding_balance: number; }

function migrateTenant(old: LegacyTenant): CurrentTenant {
  return { lease_expiry_date: old.lease_end, outstanding_balance: old.balance_due };
}

回滚策略

async function versionAwareRequest(
  baseUrl: string, path: string, headers: Record<string, string>,
  targetVersion: string, fallbackVersion: string
): Promise<any> {
  const res = await fetch(`${baseUrl}/api/${targetVersion}${path}`, { headers });
  if (res.status === 410 || res.status === 404) {
    console.warn(`${targetVersion} 被拒绝;回退到 ${fallbackVersion}`);
    const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
    if (!fallback.ok) throw new Error(`回退失败:${fallback.status}`);
    return fallback.json();
  }
  if (!res.ok) throw new Error(`请求失败:${res.status}`);
  return res.json();
}

示例

// 检测版本并在必要时迁移
const info = await detectApiVersion("https://acme.appfolio.com", authHeaders);
if (info.deprecated.includes(info.current)) {
  const oldProps = await fetchLegacyProperties();
  const migrated = oldProps.map(migrateProperty);
  await smokeTestEndpoints("https://acme.appfolio.com", authHeaders);
}

错误处理

迁移问题症状修复方法
已弃用的版本前缀每次请求都收到 410 Gone将基础 URL 更新为最新版本前缀
重命名的属性字段属性同步中出现 undefined 值应用 migrateProperty 转换
移除的分页偏移第一页之后的结果集为空切换到基于游标的分页
身份验证头部被拒升级后收到 401 Unauthorized重新生成客户端密钥,更新环境变量
Webhook 信封变更事件处理程序解析错误为新的信封更新负载解析器

资源

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

相关技能