Communitygithub.com

AppFolio 本地開發循環

為 AppFolio 物業管理 API 整合設定本地開發環境。

AppFolio 本地開發循環 是什麼?

此技能為 AppFolio 物業管理 API 整合提供完整的本地開發工作流程。它建立一個具有模擬(mock)物業、租戶和租約端點的本地伺服器,讓開發者可以在不耗用即時 API 配額的情況下快速構建與測試整合。透過切換模擬模式(mock mode)進行快速迭代,以及沙箱模式(sandbox mode)在部署前使用真實的 AppFolio Stack API 進行驗證,開發者能夠兼顧開發速度與部署信心。此技能支援多種 AI 代理平台,包括 Claude Code、Cursor 和 Codex,並提供詳細的環境設定、開發伺服器範例、測試工作流程、除錯提示及錯誤處理表格,有效引導開發者安全且高效地在 AppFolio 生態系統中進行整合開發。

相容平台✓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-local-dev-loop

在你喜歡的 AI 中提問

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

說明文件

AppFolio 本地開發循環 是做什麼的?

概述

適用於 AppFolio 物業管理 API 整合的本地開發工作流程。提供快速的回饋循環,包含模擬的物業、租戶和租約端點,讓您能夠建置並測試整合,而不會消耗即時 API 配額。在模擬模式下進行快速迭代,並在沙箱模式下針對真實的 AppFolio Stack API 進行部署前驗證,兩者之間切換自如。

先決條件

  • 僅限模擬的本地環境,包含合成的物業、租戶、租約和工單固定數據,其中不包含任何生產地址、姓名或付款資訊。
  • 另外管理的沙箱憑證,以及針對專屬整合通道的已核准唯讀固定數據;本地開發伺服器絕不會載入此憑證。
  • 一項日誌政策,僅記錄請求的格式和狀態,並為沙箱配額、固定數據重置和憑證輪替指定明確的負責人。

說明

  1. 僅在模擬模式下執行本地伺服器,並針對具有確定性固定數據的合成路由進行讀寫操作。
  2. 在進行任何沙箱連線檢查之前,先在單元測試中測試請求驗證、冪等性、資料遮罩和錯誤處理。
  3. 使用符合合約規範的受管理用戶端和一個已授權的唯讀固定數據,單獨執行沙箱通道;請勿將本地代理轉變為即時 API 通道。
  4. 當固定數據、憑證、請求預算或輸出遮罩無法驗證時,請停止操作,先修正環境再繼續。

環境設定

cp .env.example .env
# 在本地端保留提供者憑證為空白。預設為模擬模式。
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

開發伺服器

// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("本地伺服器僅限模擬;請使用受管理的沙箱整合通道");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio 開發伺服器執行於 :3001 [mock=${MOCK}]`));

模擬模式

// src/dev/mocks.ts — 逼真的物業管理回應


```typescript
// src/dev/mocks.ts — 逼真的物業管理回應
export function mountMockRoutes(app: any) {
  app.get("/api/v1/properties", (_req: any, res: any) => res.json([
    { id: "prop_1", name: "日落公寓", address: { street: "日落大道123號", city: "洛杉磯", state: "CA" }, property_type: "住宅", unit_count: 24 },
    { id: "prop_2", name: "市中心辦公室", address: { street: "主街456號", city: "舊金山", state: "CA" }, property_type: "商業", unit_count: 8 },
  ]));
  app.get("/api/v1/tenants", (_req: any, res: any) => res.json([
    { id: "t1", first_name: "小明", last_name: "王", email: "[email protected]", unit_id: "u1", lease_id: "l1" },
  ]));
  app.get("/api/v1/leases", (_req: any, res: any) => res.json([
    { id: "l1", unit_id: "u1", start_date: "2025-01-01", end_date: "2026-01-01", rent_amount: 2500, status: "active" },
  ]));
  app.post("/api/v1/work-orders", (req: any, res: any) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}

測試工作流程

npm run dev:mock &                    # 在背景啟動模擬伺服器
npm run test                          # 使用 vitest 執行單元測試
npm run test -- --watch               # 監看模式,快速迭代
npm run test:sandbox                     # 受管理的唯讀沙箱通道

除錯提示

  • 設定 DEBUG=express:* 以追蹤所有路由匹配和中間件執行
  • 對固定數據計數和結構綱要使用本地測試斷言,而非原始租戶資料傾印
  • 在測試即時 API 時檢查 X-RateLimit-Remaining 標頭
  • AppFolio 沙箱會對非您擁有的物業回傳 403 — 請驗證您的 API 金鑰範圍
  • 開發期間,僅將攔截器用於遮罩後的端點/狀態/計數遙測

輸出

  • 具有合成物業管理固定數據且無提供者憑證依賴的確定性模擬本地伺服器
  • 針對驗證、冪等性和 PII 安全可觀測性的單元測試證據
  • 僅包含遮罩後唯讀狀態的獨立受管理沙箱結果

範例

若要進行工單 UI 變更,請新增一個合成模擬固定數據,並在本地端測試請求綱要和重複提交行為。斷言回傳的 ID 和狀態,但不發出請求主體或租戶記錄。單元測試通過後,針對一個已核准的唯讀固定數據執行專屬沙箱通道。如果模擬模式被停用、本地出現沙箱憑證,或回應包含未遮罩的租戶欄位,請停止執行並恢復本地界限。

錯誤處理

問題原因修正
401 UnauthorizedAPI 金鑰無效或過期在 AppFolio Stack 入口網站重新產生
403 Forbidden金鑰缺乏端點所需範圍請求額外權限
404 Not Found錯誤的物業 ID 或路徑驗證資源是否存在於沙箱中
429 Too Many Requests超過速率限制加入指數退避,使用模擬模式
ECONNREFUSED :3001開發伺服器未執行先執行 npm run dev:mock

資源

後續步驟

請參閱 appfolio-debug-bundle。

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

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

相關技能