用途:依据 Instructor「Hermes × Codex 虚拟办公室」7.4 节(BI 仪表板制作)的工作流程技能。读取 Supabase 中准备好的整理视图,在 Evidence.dev 项目中以一张 Markdown+SQL 页面构建销售仪表板,并做静态构建部署。流程不止于画图,还包含把页面数字与原始数据核对并汇报。
前提:Evidence 项目需已搭好(npx degit evidence-dev/template <文件夹> + npm install),否则先提示用户创建;需 Node 18 以上;数据源是 Supabase 的视图(如 v_sales),若视图不存在则停止并汇报,不继续制作。
主要能力与用法:
- 连接数据源。创建 sources/magma/connection.yaml,type 为 postgres,host 为 aws-1-ap-northeast-2.pooler.supabase.com,port 5432,database 为 postgres,ssl 设为 require。凭据只放在项目根 .env(EVIDENCE_SOURCE__magma__user 与 EVIDENCE_SOURCE__magma__password),不写入页面、文件或报告。
- CA 证书。Supabase 连接池使用自签类证书,直接连接会报 self-signed certificate in certificate chain。禁止关闭证书校验(不得用 rejectUnauthorized: false)。改为下载 Supabase 官方 CA 并加入信任列表:curl -sL "https://supabase-downloads.s3.ap-southeast-1.amazonaws.com/prod/ssl/prod-ca-2021.crt" -o prod-ca-2021.crt;此后所有 evidence 命令前加 NODE_EXTRA_CA_CERTS=./prod-ca-2021.crt。
- 定义并加载数据源:sources/magma/sales.sql 写 select * from v_sales,用 npm run sources 加载并记录行数。
- 编写 pages/index.md:KPI 四项(总销售额、订单数、购买客户数、平均订单金额)、月度销售折线、渠道堆叠柱状与渠道环形、品类与地区横向条形、星期与时段热力图、按商品明细表(销售额、数量、利润率)。组件用法见 references/components.md。
- 核对(必需,不可省略):页面渲染后,直接对原始数据查询,与页面值比对并输出对照表;检查销售额、订单数、客户数是否与 v_sales 直接聚合一致;构成比图表之和是否等于总计;若表中出现异常数字或接近 100% 的比率,指出可能是清洗问题,不擅自修改,由用户决定取舍。
- 构建与部署(按需):NODE_EXTRA_CA_CERTS=./prod-ca-2021.crt npm run build 生成 build/ 静态产物;Vercel 部署需用户确认并指定项目名。
限制与注意:数据库连接信息仅存于 .env;不得关闭证书校验;过滤默认值不得用 like '%' 模式(会静默丢弃 NULL 行,实测漏掉空品类 825 行、总销售额减少约 15%),全选应省略 where 或显式分支;韩元金额轴用 fmt 缩略为亿单位;无核对不得报告完成。已知坑:证书链错误需按上述加 CA;总销售额偏小多因 like '%' 过滤;利润率异常多为原数据单价离群值,应报告而非修改;热力图 0 时异常大因无时间日期被解析为午夜;改视图列后页面不变需重跑 npm run sources;Evidence 未提供环形图组件,使用 references/components.md 中的 ECharts 代码片段。产出物:pages/index.md、核对对照表,以及部署时的 build/ 静态产物与公开 URL。其他细节资料暂未提供。