Communitygithub.com

AppFolio 调试包

收集 AppFolio API 调试证据,用于支持工单。

AppFolio 调试包 是什么?

此技能生成一个自包含的调试包,用于诊断 AppFolio 物业管理系统 API 集成问题。它通过探测属性、租户和工作订单端点来捕获 API 连接性、身份验证状态(使用客户端 ID/密钥对)、近期的错误日志(仅目录)以及 SDK 版本信息。支持 curl/node 环境(bash 脚本)和 TypeScript(健康检查函数),结果以 tarball 格式输出,可安全地提交给支持团队。该脚本遵循严格的数据最小化原则,仅收集元数据(状态码、延迟、速率限制标头),不收集原始响应体、租户或财务数据,从而确保符合数据隐私政策。其设计目标是:在无需实时访问环境的情况下,帮助工程师诊断连接失败、身份验证拒绝和数据同步问题。

兼容平台✓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-debug-bundle

在你喜欢的 AI 中提问

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

文档

AppFolio 调试包 是做什么的?

概览

本调试包从 AppFolio 物业管理 API 集成中收集诊断证据,用于支持升级和根因分析。它捕获针对属性、租户和工作订单端点的 API 连接性、使用客户端凭证对的身份验证状态、集成管道中的近期错误日志以及 SDK 版本信息。生成的 tarball 包为支持工程师提供了诊断连接故障、身份验证拒绝和数据同步问题所需的一切,无需实时访问您的环境。

前提条件

  • 已安装 curl、jq、tar
  • 已配置 APPFOLIO_CLIENT_ID 和 APPFOLIO_CLIENT_SECRET(基本认证对)
  • 已将 APPFOLIO_BASE_URL 设置为您的 Stack API 基础地址(例如 https://yourcompany.appfolio.com/api/v1)

使用说明

  1. 获得事件批准并确定受影响的时段、投资组合和安全只读探测项;不要仅因为可用就收集租户、租约、付款或原始日志正文。
  2. 仅创建包含脱敏配置状态、提供商状态/延迟、速率限制标头和包版本的包;将凭据保留在 argv 之外。
  3. 在共享之前检查每个文件,使用加密或批准的支持渠道传输归档文件,并根据事件策略删除本地副本。
  4. 如果证据需要敏感记录,请停止并获取单独批准的极简导出,而不是扩展此通用调试包。

调试收集脚本

#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
  "$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"

probe() {
  endpoint="$1"
  curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
    --netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
    || printf 'UNREACHABLE\n'
}

# 环境检查
echo "=== 环境 ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"

# 仅 API 连接性元数据 — 切勿将 API 正文写入此包中。
echo "=== API 健康状态 ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"

# 工作订单端点探测
echo "=== 工作订单 ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"

# 租户端点探测
echo "=== 租户 ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"

# 仅日志清单;原始日志可能包含租户和财务数据。
echo "=== 日志清单 ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
  || echo "No sync logs found" >> "$BUNDLE/app-logs.txt"

# 速率限制标头
echo "=== 速率限制 ===" > "$BUNDLE/rate-limits.txt"
curl -sI --netrc-file "$NETRC_FILE" \
  "${APPFOLIO_BASE_URL}/properties?per_page=1" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"

# 包版本
echo "=== 依赖项 ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "No AppFolio npm packages found" >> "$BUNDLE/deps.txt"

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

分析包

tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt     # 验证凭证已设置
cat debug-appfolio-*/api-health.txt      # 检查 HTTP 状态和延迟
cat debug-appfolio-*/rate-limits.txt     # 确认未被限流
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null  # 解析错误负载

常见问题

症状在包中检查修复方法
所有端点返回 401environment.txt 显示客户端 ID/密钥未设置在环境中设置 APPFOLIO_CLIENT_ID 和 APPFOLIO_CLIENT_SECRET
租户端点返回 403 禁止访问tenants.txt HTTP 403Stack API 作用域缺失;在 AppFolio 合作伙伴门户中请求租户读取权限
429 请求过多rate-limits.txt 显示 retry-after 标头退避并实现指数重试;AppFolio 允许 120 req/min
工作订单超时api-health.txt 显示时间 > 30s减小 per_page 参数;通过 updated_since 过滤以缩小结果集
属性列表为空api-health.txt 返回 []验证 APPFOLIO_BASE_URL 指向正确的投资组合;检查属性组过滤器
SSL 证书错误api-health.txt 显示 curl SSL 错误更新 CA 包:sudo update-ca-certificates;检查代理设置

输出

  • 一个可审查、脱敏的包,包含配置存在性、端点状态和延迟、速率限制标头、日志清单和依赖项元数据
  • 一个支持交接收据,其中说明了事件范围和敏感数据排除项,而不是打包租户、付款或原始应用程序记录
  • 当所需证据无法安全收集时,执行失败关闭决策

错误处理

将探测失败视为探测失败的证据,而不是捕获更大响应或绕过凭证控制的权限。对于 401/403,与凭证所有者验证受管客户端配置;对于 429,保留速率标头并暂停进一步探测;对于 5xx 或超时,仅收集脱敏的时序/状态证据并检查提供商状态页面。如果支持人员需要特定的租户或付款记录,请使用单独批准的极简导出,该导出具有自己的保留和访问控制。

示例

对于生产同步超时,创建一个覆盖受影响时段和一个属性安全只读探测的包。确认其中包含状态/延迟、速率标头、依赖项版本和日志文件元数据,但不包含响应体、凭证、租户或财务数据。在将归档文件上传到批准的加密支持通道之前,请对其进行审查。如果审查发现存在原始负载或密钥,请删除归档文件,根据需要轮换密钥,并在上报之前重新生成最小化的包。

自动化健康检查

async function checkAppFolioHealth(): Promise<{
  status: string;
  latencyMs: number;
  endpoints: Record<string, number>;
}> {
  const baseUrl = process.env.APPFOLIO_BASE_URL;
  const creds = Buffer.from(
    `${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
  ).toString("base64");
  const headers = { Authorization: `Basic ${creds}` };
  const endpoints = ["properties", "tenants", "work_orders"];
  const results: Record<string, number> = {};
  const start = Date.now();
  for (const ep of endpoints) {
    const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
    results[ep] = res.status;
  }
  return {
    status: Object.values(results).every((s) => s === 200) ? "healthy" : "degraded",
    latencyMs: Date.now() - start,
    endpoints: results,
  };
}

资源

后续步骤

参见 appfolio-rate-limits。

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

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

相关技能