KWDB Community Insight

KWDB Community Insight 是一个用于展示 KWDB 社区各项指标和发展趋势的可视化仪表盘。

📋 项目概述

本项目的主要目标是聚合和展示开源社区的关键指标。

核心特性：

• 现代技术栈：基于 Next.js 14 (App Router) 和 React 18 开发。
• 静态导出 (SSG)：支持完全静态化输出，适配 GitHub Pages 等静态托管环境。
• 配置驱动：通过 YAML 文件定义图表元数据，通过 TypeScript 模块定义数据查询逻辑，易于扩展。
• PWA 支持：内置 Manifest 配置，支持移动端安装和离线访问体验。
• 自动化运维：集成 GitHub Actions，实现自动化测试和部署。

📖 使用说明

构建与部署

本项目配置为静态导出模式 (output: 'export')。

构建静态文件：

pnpm build

构建产物将输出到 out/ 目录，可直接部署到任何静态文件服务器。

图表配置 (YAML)

所有的图表定义位于 charts/ 目录，每一个 YAML 文件代表一个图表配置。

配置示例：

id: downloads_trend            # 唯一标识符
title: Downloads Over Time     # 图表标题
description: 趋势说明          # 图表描述
queryModule: queries/downloadsTrend.ts   # 对应的数据查询模块路径
viz: line                      # 可视化类型：line(折线), bar(柱状), area(面积), table(表格), stat(统计卡片)
options:                       # 图表特定选项
  xKey: date                   # X轴字段名
  yKey: count                  # Y轴字段名
section: trends                # 布局分区标识
order: 1                       # 分区内排序权重
colSpan: 2                     # 栅格占位列数
defaultTimeRange:              # 默认时间范围
  from: now-7d
  to: now
refreshSec: 60                 # 自动刷新间隔（秒）

数据查询开发

查询逻辑位于 queries/ 目录。每个模块需要导出一个默认函数，处理与 Supabase 的交互。

时间过滤示例：

// 在查询模块中应用时间过滤
import { timeFilter } from '@/lib/time';

export default async function query(supabase, params) {
  // 生成 gte (大于等于) 和 lte (小于等于) 时间边界
  const { gte, lte } = timeFilter('date', params.range);
  
  const { data } = await supabase
    .from('downloads_view')
    .select('date, count')
    .gte('date', gte)
    .lte('date', lte);
    
  return { data };
}

工具函数说明 (lib/queryUtils.ts)

为了简化数据处理，项目提供了一系列实用工具函数：

• normalizeSeries(rows, opts): 将任意行数据规范化为标准的时间序列数据，支持自动排序。
• extractFromRpc(data, key): 从 RPC 调用返回的结果中提取特定数值。
• sumByKeys(rows, keys): 根据优先级键名对行数据进行求和聚合。

📂 项目结构

kwdb-insight/
├── app/                  # Next.js App Router 页面与布局
├── components/           # React UI 组件 (图表渲染器、控件等)
├── charts/               # YAML 图表配置文件
├── queries/              # TypeScript 数据查询逻辑
├── lib/                  # 核心工具库 (Supabase 客户端、数据处理)
├── public/               # 静态资源 (Favicon, Manifest, Sitemap)
├── .github/workflows/    # CI/CD 自动化工作流配置
└── tests/                # Playwright E2E 测试用例

📄 许可证

本项目采用 Apache License 2.0 许可证。