sales-reporting

事实来源

hubspot <command> --help 是权威依据。基于 bulk-operations/SKILL.md 编写——JSONL 结构、批量读取规则和分页说明都在那里。数据整形模式见：bulk-operations/resources/json-patterns.md。search/list 每次调用最多返回 100 行；结果恰好为 100 行时，几乎总是被截断了——汇总前请按照 bulk-operations/SKILL.md 进行分页。

属性和输出结构说明

• 所有 CRM 属性值在 JSONL 中都以字符串形式返回——包括布尔值。hs_is_closed_won 返回 "true"/"false"（字符串）；amount 是数字字符串。进行算术运算时使用 tonumber；在客户端筛选时，将布尔值作为字符串比较（== "true"）。
• 数值属性在未设置或为空时，可能是 null 或空字符串（""）。tonumber 遇到 "" 会中止。请务必使用 select(. != null and . != "") | tonumber 进行保护。
• 在 --filter 表达式中，hs_is_closed_won=true 和 hs_is_closed!=true 都可用——API 会解析该值。
• --properties 返回标准的嵌套结构：{"id":"123","properties":{"amount":"5000","dealname":"..."}}。在 jq 中使用 .properties.amount 引用字段。
• dealstage 中的阶段 ID 因门户而异。使用 hubspot pipelines stages --type deals --pipeline <id> 映射阶段（或读取 hubspot pipelines list/get 内嵌的 stages 数组）。hubspot pipelines 仅支持应用令牌——请参阅“身份验证”部分；使用用户 OAuth 时会返回 403。
• hubspot_owner_id 是数字字符串。使用 hubspot owners list 将其解析为姓名（字段：id、firstName、lastName、email）。hubspot owners list 支持用户 OAuth（hubspot auth login）和服务密钥。

1. 每日简报

macOS 和 GNU date 的日期范围写法不同：

# macOS
TODAY=$(date +%Y-%m-%d); NEXT_7=$(date -v+7d +%Y-%m-%d); YESTERDAY=$(date -v-1d +%Y-%m-%d)
# Linux
TODAY=$(date +%Y-%m-%d); NEXT_7=$(date -d '7 days' +%Y-%m-%d); YESTERDAY=$(date -d '1 day ago' +%Y-%m-%d)

未来 7 天内结束的交易：

hubspot objects search --type deals \
  --filter "closedate>$TODAY AND closedate<$NEXT_7 AND hs_is_closed!=true" \
  --properties dealname,amount,closedate,hubspot_owner_id

过去 24 小时内更新的交易：

hubspot objects search --type deals \
  --filter "hs_lastmodifieddate>$YESTERDAY AND hs_is_closed!=true" \
  --properties dealname,amount,dealstage,hs_lastmodifieddate

开放管道摘要行：

hubspot objects search --type deals --filter "hs_is_closed!=true" --properties amount \
| jq -rs '{count: length, value: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)}
          | "Open pipeline: \(.count) deals, $\(.value)"'

2. 管道快照

按阶段 — 统计每个 dealstage 的数量和金额：

hubspot objects search --type deals --filter "hs_is_closed!=true" \
  --properties dealstage,amount \
| jq -rs '
    group_by(.properties.dealstage)
    | map({stage: .[0].properties.dealstage, count: length,
           total: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(-.total) | .[] | "\(.stage)\tcount: \(.count)\tvalue: $\(.total)"' \
| column -t -s$'\t'

按所有者：

hubspot objects search --type deals --filter "hs_is_closed!=true" \
  --properties amount,hubspot_owner_id \
| jq -rs '
    group_by(.properties.hubspot_owner_id)
    | map({owner: .[0].properties.hubspot_owner_id, count: length,
           total: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(-.total) | .[] | "owner \(.owner)\tdeals: \(.count)\tvalue: $\(.total)"' \
| column -t -s$'\t'

要为所有者 ID 标注姓名，请一次性导出所有者文件并进行关联：

hubspot owners list | jq -r '"\(.id)\t\(.firstName) \(.lastName) <\(.email)>"' > /tmp/owners.tsv

3. 成交／流失分析

成交的筛选条件为 hs_is_closed_won=true；流失的筛选条件为 hs_is_closed=true AND hs_is_closed_won!=true。使用 closedate>=YYYY-MM-DD AND closedate<YYYY-MM-DD 指定范围。

某个时期内成交／流失的交易：

hubspot objects search --type deals \
  --filter "hs_is_closed_won=true AND closedate>=2026-04-01 AND closedate<2026-07-01" \
  --properties dealname,amount,closedate,hubspot_owner_id

hubspot objects search --type deals \
  --filter "hs_is_closed=true AND hs_is_closed_won!=true AND closedate>=2026-04-01 AND closedate<2026-07-01" \
  --properties dealname,amount,closedate,hubspot_owner_id

按销售代表统计成交率 — 拉取该时期内所有已结束的交易，分组后计算比率。注意：hs_is_closed_won 返回为字符串，因此要比较 == "true"。

hubspot objects search --type deals \
  --filter "hs_is_closed=true AND closedate>=2026-01-01" \
  --properties hubspot_owner_id,hs_is_closed_won,amount \
| jq -rs '
    group_by(.properties.hubspot_owner_id)
    | map({owner: .[0].properties.hubspot_owner_id,
           total: length,
           won: ([.[] | select(.properties.hs_is_closed_won == "true")] | length),
           won_value: ([.[] | select(.properties.hs_is_closed_won == "true")
                       | .properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | map(. + {win_rate: ((.won / .total * 100) | round)})
    | sort_by(-.won_value)
    | .[] | "owner \(.owner)\twon: \(.won)/\(.total)\trate: \(.win_rate)%\twon: $\(.won_value)"' \
| column -t -s$'\t'

按结束月份统计收入（成交交易）：

hubspot objects search --type deals \
  --filter "hs_is_closed_won=true AND closedate>=2026-01-01" \
  --properties amount,closedate \
| jq -rs '
    group_by(.properties.closedate[0:7])
    | map({month: .[0].properties.closedate[0:7], count: length,
           revenue: ([.[].properties.amount | select(. != null and . != "") | tonumber] | add // 0 | round)})
    | sort_by(.month) | .[] | "\(.month)\tdeals: \(.count)\trevenue: $\(.revenue)"' \
| column -t -s$'\t'

4. 已保存的报告

hubspot reports 系列命令会在服务器端运行 HubSpot 已保存的报告和 CRM-SQL 报告，因此无需在客户端重新计算汇总数据：

• reports list / get <id> — 浏览和检查已保存的报告。
• reports fetch-dataset <id> — 在服务器端重新运行已保存的报告并返回其数据集。
• reports create "<CRM SQL>" — 根据 CRM-SQL 查询创建报告（配套技能可生成 SQL）；reports insights <id> 可生成 AI 洞察（异步执行，并轮询直至完成）。
• reports update <id> / clone <id> / favorite <id> / unfavorite <id> — 管理报告元数据。
• reports delete <id> — 不可撤销，且需要摘要校验：先运行 --dry-run，然后运行 --digest <hash> --confirm "<report name>"（confirm = 报告名称）。

运行 hubspot reports --help 查看完整命令列表和 CRM-SQL 语法。

5. 成交／流失背景信息：序列报名记录

hubspot sequences enrollments <contact_id> 会返回联系人的 Sales Hub 序列报名历史（只读）——有助于将成交／流失归因于外联活动。每行格式为：{"contactId":789,"enrollments":[{"sequenceName":"Q4 Outbound","state":"FINISHED","enrolledAt":"...","currentStepOrder":5,"totalSteps":6}]}。将其与交易关联的联系人进行关联，即可查看“该交易是否通过某个序列跟进？”。参见 hubspot sequences enrollments --help。

已知限制

• 可以通过 hubspot pipelines stages 识别赢单／输单阶段：每个阶段的 metadata 都包含 isClosed／probability（例如，jq -r 'select(.metadata.probability=="1.0") | .id'）。交易对象本身的 hs_is_closed_won 也可用。
• 没有团队对象——按 hubspot_owner_id 分组，并在客户端通过 hubspot owners list 解析名称。
• hubspot pipelines 仅支持应用令牌，使用用户 OAuth 时会返回 403。hubspot owners list 支持用户 OAuth。如果无法获取管道，请保留原始 ID 并发出警告；不要因此导致报告失败。
• 数值型 CRM 属性可能为 null 或 ""；使用 tonumber 时，始终通过 select(. != null and . != "") 进行保护。