Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

配置用于 AppFolio 物业管理集成的 CI/CD 流水线。

tons-of-skills-marketplace 是什么?

此技能指导开发者配置 CI 流水线,以验证 AppFolio 物业管理 API 集成。它采用双层策略:单元测试模拟 AppFolio REST 客户端,在不消耗 API 配额的情况下验证租户查询、工单创建和物业列表逻辑;集成测试仅在主分支合并时针对 AppFolio 沙箱环境运行,使用存储为 GitHub Secrets 的基本认证凭据。这种方法在保持 PR 反馈快速且免费的同时,能在生产部署前捕获真实的 API 契约漂移。技能支持 GitHub Actions,并提供了详细的准备工作、指令、Workflow 配置、模拟测试、集成测试、成本管理、错误处理和输出示例。

兼容平台✓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. 保持拉取请求检查仅使用模拟;不要将 AppFolio 凭据暴露给不可信代码或复刻的拉取请求。
  2. 在 lint、类型检查和单元检查通过后,将实时沙箱作业限制为受保护的 main 推送,并仅通过仓库 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 次请求/分钟的速率限制

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 次请求/分钟)使用 --maxWorkers=1 运行集成测试
租户列表为空AppFolio 定期重置沙箱数据停止作业并在 CI 外部恢复预配的夹具
API 响应类型检查失败AppFolio 架构未经通知已更新从 OpenAPI 规范重新生成类型,更新接口
集成作业被跳过分支保护规则与 refs/heads/main 不匹配验证工作流的 if 条件是否与您的默认分支名称匹配

输出

  • 来自仅模拟的 lint、类型和单元检查的拉取请求结果
  • 一个受保护分支的沙箱收据,包含脱敏的提供商状态、夹具身份、请求计数和集成测试结果
  • 一个有限的发布决策,在凭据不可用、提供商错误、夹具漂移或请求预算耗尽时阻塞

示例

对于工单映射更改,添加一个合成模拟响应并在 PR 套件中验证新字段。合并后,受保护的 main 工作流读取一个预配的沙箱工单并确认标准化形状,而无需创建租户、物业或工单。如果夹具不可用、凭据失败或请求预算超出,则将发布标记为阻塞,并在重新运行实时通道之前由沙箱所有者恢复夹具或凭据。

资源

后续步骤

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

相关技能