Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

為 AppFolio 物業管理整合配置 CI/CD 管線。

tons-of-skills-marketplace 是什麼?

此技能提供了一套完整的 CI/CD 管線配置方案,專門用於驗證 AppFolio 物業管理 API 的整合。它採用雙層策略:單元測試會模擬 AppFolio REST 用戶端,來驗證房客查詢、工單建立和房源列表邏輯,而不耗用 API 配額;而整合測試則僅在主分支合併時,針對 AppFolio 沙箱環境執行,並使用儲存在 GitHub Secrets 中的基本認證。這種設計能讓 PR 回饋快速且免費,同時在部署至生產環境前,及早發現 API 合約發生變動的問題。該技能支援 GitHub Actions 平台,並詳細說明了必要條件、CI 成本管理、錯誤處理方式以及具體的工作流程和程式碼範例,幫助開發者建立一個安全、高效且可控的 CI 流程。

相容平台✓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-ci-integration

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

AppFolio CI 整合

概述

配置 CI 管線,以雙層策略驗證 AppFolio 物業管理 API 的整合。單元測試會模擬 AppFolio REST 用戶端,以驗證房客查詢、工單建立和房源列表邏輯,而不耗用 API 配額。整合測試僅在主分支合併時,針對 AppFolio 沙箱環境執行,並使用儲存為 GitHub Secrets 的基本認證。這使得 PR 回饋快速且免費,同時在部署至生產環境前,及早發現真實的 API 合約變動。

先決條件

  • 一個啟用 Actions、具有鎖定的相依性安裝以及僅使用合成房客、房產和工單固定數據的單元測試的儲存庫。
  • 一個獨立管理的 AppFolio 沙箱憑證,以及一個預先配置好的、整合擁有者被允許讀取的非生產固定數據記錄。
  • 定義的 CI 擁有者、固定的請求預算,以及用於處理憑證輪換、供應商中斷或沙箱數據重設的事件處理路徑。

指示

  1. 保持 Pull Request 檢查僅使用模擬;不要將 AppFolio 憑證暴露給不受信任的程式碼或 Fork 的 Pull Request。
  2. 將即時沙箱任務限制在受保護的 main 推送,並在 lint、型別和單元檢查通過後執行,且僅透過儲存庫 Secrets 注入憑證。
  3. 將整合執行限制在一個已知的唯讀固定數據、一個工作執行緒和所述請求預算內;僅記錄經過修訂的狀態和計數證據。
  4. 將失敗的身份驗證、速率限制或缺少固定數據視為阻斷釋出的條件,而不是從 CI 建立共享的沙箱數據。

GitHub Actions 工作流程

# .github/workflows/appfolio-tests.yml
name: AppFolio API 測試
on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run lint && npm run typecheck
      - run: npm test -- --testPathPattern=unit  # 不需要 API 憑證

  integration-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --testPathPattern=integration
        env:
          APPFOLIO_CLIENT_ID: ${{ secrets.APPFOLIO_CLIENT_ID }}
          APPFOLIO_CLIENT_SECRET: ${{ secrets.APPFOLIO_CLIENT_SECRET }}
          APPFOLIO_BASE_URL: ${{ secrets.APPFOLIO_SANDBOX_URL }}

基於模擬的單元測試

// tests/unit/work-order-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createWorkOrder } from '../../src/services/work-order-service';
import * as appfolioClient from '../../src/lib/appfolio-client';

vi.mock('../../src/lib/appfolio-client');

describe('WorkOrderService', () => {
  it('為一個物業建立維修工單', async () => {
    vi.mocked(appfolioClient.post).mockResolvedValue({
      id: 'wo-4821',
      property_id: 'prop-100',
      category: 'Plumbing',
      status: 'Open',
    });

    const result = await createWorkOrder('prop-100', 'Plumbing', 'Leaking faucet unit 3B');
    expect(result.status).toBe('Open');
    expect(appfolioClient.post).toHaveBeenCalledWith('/work_orders', {
      property_id: 'prop-100',
      category: 'Plumbing',
      description: 'Leaking faucet unit 3B',
    });
  });
});

整合測試

// tests/integration/tenant-lookup.test.ts
import { describe, it, expect } from 'vitest';
import { AppFolioClient } from '../../src/lib/appfolio-client';

const canRun = process.env.APPFOLIO_CLIENT_ID && process.env.APPFOLIO_CLIENT_SECRET;

describe.skipIf(!canRun)('AppFolio 房客查詢 (即時沙箱)', () => {
  const client = new AppFolioClient({
    clientId: process.env.APPFOLIO_CLIENT_ID!,
    clientSecret: process.env.APPFOLIO_CLIENT_SECRET!,
    baseUrl: process.env.APPFOLIO_BASE_URL!,
  });

  it('列出已知物業的房客', async () => {
    const tenants = await client.get('/tenants', { property_id: 'prop-100' });
    expect(Array.isArray(tenants)).toBe(true);
    expect(tenants[0]).toHaveProperty('lease_status');
  });
});

CI 成本管理

// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // AppFolio 沙箱有 100 req/min 的速率限制

export function trackApiCall(): void {
  callCount++;
  if (callCount > MAX_CALLS_PER_RUN) {
    throw new Error(
      `CI API 預算超額:已進行 ${callCount}/${MAX_CALLS_PER_RUN} 次呼叫。` +
      '請減少整合測試範圍或將測試拆分到多個任務中。'
    );
  }
}

export function getCallCount(): number { return callCount; }

錯誤處理

CI 問題原因修復方法
整合任務中的 401 未授權沙箱憑證過期或輪換在 GitHub Secrets 中重新產生 APPFOLIO_CLIENT_ID 和 APPFOLIO_CLIENT_SECRET
429 請求過多並行測試達到沙箱速率限制 (100 req/min)使用 --maxWorkers=1 執行整合測試
房客列表為空AppFolio 定期重設沙箱數據停止任務並在 CI 外部還原預先配置的固定數據
API 回應的型別檢查失敗AppFolio 架構未經通知即更新從 OpenAPI 規範重新產生型別,更新介面
整合任務被跳過分支保護規則與 refs/heads/main 不匹配驗證工作流程的 if 條件是否符合您的預設分支名稱

產出

  • 來自僅使用模擬的 lint、型別和單元檢查的 Pull Request 結果
  • 一個受保護分支的沙箱收據,包含經過修訂的供應商狀態、固定資料身份識別、請求計數和整合測試結果
  • 一個有界限的釋出決策,當憑證不可用、供應商錯誤、固定資料漂移或請求預算耗盡時,會阻斷釋出

示例

對於工單映射的變更,請新增一個合成的模擬回應,並在 PR 套件中驗證新欄位。合併後,受保護的主分支工作流程會讀取一個預先配置的沙箱工單,並確認標準化後的資料形狀,而不會建立新的房客、物業或工單。如果固定資料不可用、憑證失敗或請求預算超額,請標記為釋出受阻,並讓沙箱擁有者在重新執行即時流程之前,先還原固定資料或憑證。

資源

後續步驟

請參閱 appfolio-deploy-integration。

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

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

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

相關技能