wuling-overseas-dealer-expansion-skill/references/dashboard.md

Customer Dashboard

Use this reference when the user asks for a 中台、看台、看板、客户统计、建联率、客户数量、渠道分布、邮件发送统计, or wants a more visual view of the outreach workbook.

Scope

The dashboard belongs in the skill as a reusable generator, not as customer data.

• Skill package contains only reusable files:
  • scripts/dashboard/build_dashboard.py
  • assets/dashboard_template.html
  • assets/dashboard_config.example.json
• Project/runtime outputs must be written outside the skill:
  • runs/YYYYMMDD/<run_id>/customer_dashboard.html
  • runs/YYYYMMDD/<run_id>/dashboard_data.json
  • Optional stable copy: dashboards/latest/customer_dashboard.html

Do not put generated dashboards, customer rows, Feishu URLs, tokens, screenshots, or run JSON files into the skill package.

Data Source

The default customer source is 客户信息汇总表. If Facebook对话记录 exists, read it as an optional event source for Facebook reply metrics; never treat message rows as customer rows.

Before generating a dashboard after new scraping or write-back work, refresh the summary sheet first:

python scripts/common/build_customer_summary.py --excel "<建联表路径>" --write-summary --run-id "<run_id>"

Then generate the dashboard:

python scripts/dashboard/build_dashboard.py --excel "<建联表路径>" --run-id "<run_id>" --latest-dir "dashboards/latest"

Preview, dry-run, or search-only tasks do not need to refresh the dashboard unless the user asks.

Metric Definitions

• 有效客户: rows in 客户信息汇总表 that are not marked as 已剔除, 跳过, 低优先级, or skip_* in status/notes.
• 可建联客户: valid customers with at least one email, phone/WhatsApp, website, Facebook, LinkedIn, or Google Maps entry.
• 已建联客户: valid customers whose status or notes include 已发送邮件, 已发邮件, 邮件已发送, 邮件发送成功, 已发私信, 已关注并私信, 已建联, 等待回复, 已回复, or 有意向, excluding bounced/rejected emails.
• 建联率: 已建联客户数 / 可建联客户数.
• 邮箱覆盖率: valid customers with 个人邮箱 or 公共邮箱 divided by all valid customers.
• 退信率: customers marked with 邮件退回, 退回, 拒收, 无法送达, 域名不存在, 邮箱不存在, or 发送失败 divided by customers with email.
• 待人工复核: valid customers whose notes, type, or attribute contain 待确认, 人工复核, 需人工, 需确认, or 信息不足.
• Facebook回复率: unique customers with at least one effective customer reply divided by unique customers with at least one outgoing Facebook message.
• Facebook高意向: unique customers whose latest effective reply is 明确有意向 or 潜在意向.
• System messages, auto replies, reactions, likes, and read receipts do not count as effective replies.

Dashboard Views

The default HTML dashboard should show:

• KPI cards:
  • 有效客户
  • 可建联客户
  • 建联率
  • 邮箱覆盖率
  • 退信率
  • 待人工复核
• Distribution sections:
  • 客户属性分布
  • 建联状态分布
  • 客户来源分布
  • 细分客户类型 Top
• Attention table:
  • contactable customers that have not yet been contacted and are not bounced.
• Facebook follow-up sections:
  • five-level cooperation-intent distribution;
  • effective-reply trend for the latest 30 days;
  • high-intent customer table with Chinese reply summary and next action.

The dashboard is a management view. Do not use it as the source of truth for customer edits; the local Excel workbook remains the source of truth.

Feishu Integration

If feishu_sync_config.json is present and enabled, normal workbook write-back still follows references/feishu-sync.md.

Dashboard generation itself does not automatically push to Feishu unless the project has an explicit dashboard_config.json with:

{
  "sync_dashboard_metrics_to_feishu": true
}

When enabled, the agent should use WorkBuddy lark-sheets to sync dashboard metric tables after the local workbook has been saved and the local dashboard data has been generated. Do not store real Feishu tokens, cookies, or URLs inside the skill.

Encoding Rules

Dashboard JSON and HTML must be written with encoding="utf-8" and ensure_ascii=False.

After generating dashboard files, scan them for repeated-question-mark corruption. If found, stop and repair the source text generation before sharing the dashboard.

Visual Design Requirements

Dashboard HTML should look like a practical sales-operations middle platform, not a plain report. It must include visual charts and not rely on external CDN assets.

Required visual modules:

• KPI cards with compact progress meters.
• Outreach funnel from total customers to valid customers, contactable customers, contacted customers, and manual-review customers.
• Customer attribute distribution using horizontal bar charts.
• Customer source distribution using vertical column/bar charts.
• Outreach status structure using a donut-style CSS chart with legend.
• Customer type and city distribution using horizontal bar charts.
• A filterable customer table with search, customer-attribute filter, status filter, and email availability filter.

Keep the style close to CRM / B2B SaaS dashboards: light background, restrained business colors, high information density, clear visual hierarchy, and no marketing hero layout.