Communitygithub.com

AppFolio 업그레이드 및 마이그레이션

AppFolio API 버전 간 마이그레이션 및 엔드포인트 변경 처리

AppFolio 업그레이드 및 마이그레이션란 무엇인가요?

이 스킬은 AppFolio 부동산 관리 통합 시스템의 API 버전 업그레이드를 자동화합니다. 현재 API 버전을 감지하고, 속성(property) 및 임차인(tenant) 객체의 스키마 변경을 마이그레이션하며, 페이지네이션 모델 변경과 엔드포인트 URL 업데이트를 처리합니다. 마이그레이션 실패 시 자동 롤백 전략을 지원하여 안정적인 업그레이드를 보장하며, Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 실행 가능합니다. 스킬은 TypeScript 인터페이스와 함수를 통해 버전 감지, 스키마 마이그레이션, 롤백 로직을 제공하며, 사전 조건으로 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에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

AppFolio 업그레이드 및 마이그레이션은(는) 무엇을 하나요?

개요

AppFolio 부동산 관리 통합은 플랫폼과 함께 진화하는 버전이 지정된 REST API 엔드포인트에 의존합니다. 업그레이드는 속성(property) 및 임차인(tenant) 객체의 필드 이름을 변경하고, 페이지네이션 모델을 변경하며, 작업 지시(work-order) 엔드포인트를 폐기하고, 기본 인증(basic-auth) 흐름을 변경할 수 있습니다. 이 스킬은 현재 API 버전을 감지하고, 폐기된 응답 형태를 대체 형태로 매핑하며, 새 버전이 실패하면 자동으로 롤백합니다.

사전 조건

  • 현재 API 버전 접두사 문서화 (예: /api/v1/)
  • AppFolio API 변경 로그(changelog) 및 릴리스 노트에 접근 권한
  • 테스트 속성 및 임차인 데이터가 있는 스테이징 환경
  • 환경 변수에 저장된 클라이언트 ID 및 시크릿
  • 핵심 엔드포인트를 다루는 기존 통합 테스트 스위트

지침

  1. 버전 감지를 실행하여 활성 API 버전을 최신 버전과 비교합니다.
  2. AppFolio 변경 로그에서 두 버전 간의 호환성을 깨는 변경 사항(Breaking Changes)을 검토합니다.
  3. 속성 및 임차인 응답 객체에 스키마 마이그레이션 변환을 적용합니다.
  4. 엔드포인트 URL을 이전 버전 접두사에서 새 버전 접두사로 업데이트합니다.
  5. 새 버전에서 필요한 경우 페이지네이션을 오프셋(offset)에서 커서(cursor) 기반으로 전환합니다.
  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 발생클라이언트 시크릿 재생성, 환경 변수 업데이트
웹훅 페이로드 변경이벤트 핸들러 파싱 오류 발생새 페이로드 형식에 맞게 파서 업데이트

리소스

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".

관련 스킬