freehire 应用 Pipeline 看板实现指南:从任务拆解到阶段聚合与手写 SVG 可视化

原创2026-10-23 19:42:171,688 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

freehire 应用 Pipeline 看板实现指南:从任务拆解到阶段聚合与手写 SVG 可视化

本指南以 freehire 仓库中 add-my-jobs-pipeline-tab 变更的归档任务清单为主线,还原一个「求职申请 Pipeline」功能从领域聚合、HTTP 契约、前端数据层到 SVG 可视化组件的完整落地路径。读完后你将掌握:如何为一个只有「当前状态」而无状态迁移历史的业务模型设计诚实的统计口径、如何用 Go 纯函数承载唯一的阶段映射、以及如何在不引入任何图表依赖的前提下手写 Sankey 与环形图。

一、变更背景:为什么需要一个 Pipeline 标签页

freehire 的 /my/tracking(在变更归档时还是 /my/jobs)页面原本只有 Board 与 History 两个标签页,用户能逐个查看每份申请的卡片,却看不到「我的申请整体上堆在哪个阶段」以及「有多少比例走到了面试或 Offer」。这个变更的价值主张写在提案里:Board 与 History 回答「每份申请现在在哪」,Pipeline 回答「它们在哪里堆积、转化如何」。

原始需求与实现边界可以从这三份归档文档读到:

  • 提案:新增 Pipeline 标签页、专用聚合端点、手写 SVG、零新依赖。
  • 设计:快照语义、阶段到七个桶的映射、端点选型、组件拆分。
  • 能力规格:可验收的行为契约(已认证/未认证/空数据三种场景)。

一个必须先讲清楚的前提是快照语义。设计文档明确写道:user_jobs 的每一行只保存一个当前 stage,没有阶段迁移历史、也没有每个阶段的时间戳,因此「真正的历史漏斗」在现有数据模型下不可能实现。于是系统采取的口径是:每份申请只被计入一个当前桶,面试率与 Offer 率是「目前到达过」的下界(一份面试后被拒的申请只会显示为 rejected),这一点由 UI 的脚注明确告知用户,而不是藏在图表背后。

二、任务骨架:六个工作包

任务清单把工作切成六组,每组都有可勾选的验收项,这种「先写纯函数、再接查询、再做 UI」的顺序本身就值得借鉴:领域逻辑可以在完全没有数据库和浏览器的情况下被测试。

任务组 内容 产出物
1 纯领域聚合 桶词汇表 + Buckets/Aggregate 函数
2 查询与 handler CountMyJobsByStage sqlc 查询、handler、路由、集成测试
3 前端数据层 PipelineStats 类型、getMyPipeline()
4 展示组件 RateDonut.svelte、PipelineFunnel.svelte
5 容器与标签页 PipelineView.svelte、标签页接入
6 验证 Go 构建/静态检查/测试、svelte-check、契约与依赖检查

下面按这六组逐层展开,并结合当前仓库源码说明每一层最终长成了什么样。

三、任务组 1:把聚合写成纯函数

3.1 任务定义

1.1 要求定义一个桶词汇表与一个纯函数,把 (stage, count) 行(包括 stage 为 NULL 的行)折叠成七个桶加一个 applications 总数,映射的唯一真源就在这个函数里。1.2 要求先写测试(RED first),覆盖:每份申请只计一次(各桶之和等于 applications)、screening/responded → in_progress、空 stage → no_answer、终态阶段正确映射、空输入全零、未知阶段有确定性处理。

3.2 原始映射规则

按设计文档第 2 条决策,七个桶与阶段的对应关系是:

阶段(stage) 桶(bucket)
applied(无进一步阶段) no_answer
screening、responded in_progress
interview interviewing
offer offer
accepted accepted
rejected rejected
withdrawn declined

统计分母(applications)的定义是:applied_at IS NOT NULL OR stage IS NOT NULL 的行数,仅收藏(saved-only)的行被排除。两个比率定义为:Interview Rate = (interviewing + offer + accepted) / applications,Offer Rate = (offer + accepted) / applications。

3.3 当前仓库的实现形态

这里必须说明一个事实:这份任务清单是 2026-06-30 的历史快照,仓库在之后的 tracker-one-vocabulary 变更里重构了这一层。当前实现位于 counts.go,核心类型是 StageCount{Stage, Count} 与 Pipeline{Applications, Stages},聚合函数名为 CountByStage:

func CountByStage(counts []StageCount) Pipeline {
	stages := make(map[string]int64, len(Stages))
	for _, stage := range Stages {
		stages[stage] = 0
	}

	var p Pipeline
	for _, c := range counts {
		p.Applications += c.Count
		if !ValidStage(c.Stage) {
			stages["applied"] += c.Count
			continue
		}
		stages[c.Stage] += c.Count
	}
	p.Stages = stages
	return p
}

相比原设计,当前版本不再输出七个粗粒度桶,而是输出每个阶段的计数,并把「分组成面板上的列」这件事交给渲染方,用同一份 Groups 表(groups.go)驱动。原因写在 Pipeline 的注释里:no_answer、in_progress、declined 这些桶名在产品的其他任何界面都不会出现,等于为同一个状态造了第三套词汇。

3.4 三个值得抄走的实现细节

其一,零值键必须存在。 聚合函数预先把 Stages 里每个阶段都置零,所以响应中的键永远齐全。这不是洁癖:如果键只在非零时出现,调用方就无法区分「没人处在这个阶段」和「服务端忘了这个阶段」,前端也就不得不自己维护一份阶段列表——而这正是被移除的那份拷贝。

其二,未知阶段要折叠而不是丢弃。 stage 是自由文本列,没有 CHECK 约束,历史数据、手写 UPDATE 或回滚的发布都可能留下词表外的值。当前实现把这类行归入 applied,保证「各部分之和等于总数」这条不变量不因一个无法解释的行而破。

其三,NULL 的处理下沉到仓储层。 sqlc 生成的 CountMyJobsByStageRow.Stage 是 pgtype.Text,仓储层把 row.Stage.String 取出后,NULL 自然变成空字符串,于是「已投递但未设置阶段」和「阶段为空」在领域函数里走同一条路径,不需要第二套判空分支,见 repository.go。

对应的单元测试在 counts_test.go,它逐条守住了任务组 1.2 列的断言:词表完整、计数求和、未设阶段计入 applied、未知阶段不新增键、空输入仍带全键。

四、任务组 2:查询、仓储与 handler

4.1 sqlc 查询

任务 2.1 给出的 SQL 是:

SELECT stage, count(*) FROM user_jobs
WHERE user_id=$1 AND (applied_at IS NOT NULL OR stage IS NOT NULL)
GROUP BY stage;

要求跑 make sqlc 并提交生成物。仓库的 Makefile 里这条命令通过容器执行 sqlc generate,因此本地无需安装 sqlc 二进制。

当前版本的同名查询在 user_jobs.sql,表名已跟随数据模型演进改为 applications:

-- name: CountMyJobsByStage :many
SELECT stage, count(*) AS count
FROM applications
WHERE user_id = $1
  AND (applied_at IS NOT NULL OR stage IS NOT NULL)
GROUP BY stage;

生成物在 user_jobs.sql.go,它是一个标准的 :many 方法,返回 []CountMyJobsByStageRow。注意不要手改生成文件——make sqlc 会覆盖它。

4.2 handler 与路由

任务 2.2 要求 handler 从 c.Locals 取当前用户、把查询结果喂给桶函数、返回 {"data": {...}} 并让错误交给中央 ErrorHandler。当前实现是 me_tracking.go 的 TrackingPipeline:调用 requireUserID(c),委托 h.tracking.Pipeline,最后 c.JSON(fiber.Map{"data": pipeline})——错误直接 return,由 RenderError 统一映射状态码。

任务 2.3 要求把路由挂到 /me/jobs 组下的 RequireAuthOrKey。当前路由注册在 user_jobs.go:

api.Get("/me/tracking/pipeline", mw.key, h.TrackingPipeline)

mw.key 就是 RequireAuthOrKey 中间件,意味着会话 Cookie 与 API Key 都能访问——这一点对脚本和 Agent 场景很关键,docs/API.md 也据此给了 curl 示例。

服务层在 jobtracking.go。一个值得注意的工程细节:在拿到阶段计数之后,它还会尽力而为地附加一个回复率基准(ReplyRate)。查询失败时只记日志、不返回错误,因为「整体聚合」这个主能力早就存在且稳定,不该被一个可选的对比信号拖垮。

4.3 接口契约

规范中约定的响应信封是:

{
  "data": {
    "applications": 12,
    "stages": {
      "applied": 4, "screening": 2, "responded": 1, "interview": 2,
      "offer": 1, "accepted": 1, "rejected": 1, "withdrawn": 0
    }
  }
}

(变更归档时该字段名为 buckets,含七个桶;当前的 stages 形态见 docs/API.md。)规范要求每个键始终存在、空时为 0,未认证请求返回 401,无申请用户返回全零而非错误。

4.4 集成测试的种子设计

任务 2.4 要求用 testcontainers 播种各类 user_jobs 行并断言总数、桶计数与 401。当前测试 me_pipeline_integration_test.go 的种子集值得当作模板:每个非空桶各一行、两行「已投递但无 stage」、再加一行仅收藏和一行仅浏览作为反例。断言侧除了比对具体计数,还额外验证了三件事——所有阶段键都存在、各计数之和等于 applications、键数量恰好等于词表长度(防止词表外的键泄漏到线上)。

五、任务组 3:前端数据层

任务 3.1、3.2 只有两行,但把「类型」和「取数」分开是必要的:类型定义在 types.ts,取数函数在 api.ts:

export interface PipelineStats {
  applications: number;
  stages: PipelineStageCounts;
  reply_rate?: ReplyRateBenchmark;
}

async function getMyPipeline(): Promise<PipelineStats> {
  return requestData<PipelineStats>('/api/v1/me/tracking/pipeline');
}

reply_rate 是可选字段,注释说明了原因:低于服务端样本门槛时它整个缺席,而不是给 0 或给一个估算值。消费方必须用 stats?.reply_rate 判断存在性,而不是判断真假值——这个约定在后面的容器组件里体现为 {#if benchmark} 才渲染第三张卡片。

六、任务组 4:两个手写 SVG 展示组件

6.1 RateDonut:单值环图

任务 4.1 要求 percent、label、sublabel 三个 props、手写 SVG 且对零安全。实现见 RateDonut.svelte:

  • 半径 R = 42,周长 CIRC = 2πR,用 stroke-dasharray 表达比例:${CIRC * fraction} ${CIRC}。
  • fraction 先做 Math.max(0, Math.min(1, ...)) 钳制,畸形输入不会画出负弧或溢出弧。
  • 起点整体 rotate(-90 50 50),让进度从 12 点方向开始。
  • 显示文本对小比例保留一位小数(fraction < 0.1 时),否则取整,且 0 直接显示 0%,避免出现 0.0%。
  • aria-label 拼成 "{label}: {display}",让读屏用户也能得到数值。

6.2 PipelineFunnel:单层 Sankey

任务 4.2 要求 props 为 applications 与 buckets、用比例带绘制单层 Sankey、维护静态的标签/颜色/顺序表、并优雅处理全零。当前实现在 PipelineFunnel.svelte,几何参数构成一张可直接复用的坐标表:

常量 值 含义
W 940 viewBox 宽,刻意取宽使缩放系数接近 1
HH 230 左侧源条与右侧节点块的总高
PAD 12 上下内边距
GAP 10 右侧节点间距
LX / LW 8 / 18 左侧源条位置与宽度
RX / RW 760 / 14 右侧节点位置与宽度
MID (LX+LW+RX)/2 贝塞尔控制点横坐标,决定缎带弯曲形状

比例的核心只有两行:h = (count / applications) * HH,左侧条带累积、右侧条带累积后再加 GAP,于是右侧节点被拉开,缎带自然扇出而不是平行贴在一起。路径用两段三次贝塞尔加闭合直线成形:

path: `M ${LX + LW} ${ly0} C ${MID} ${ly0}, ${MID} ${ry0}, ${RX} ${ry0}
       L ${RX} ${ry1} C ${MID} ${ry1}, ${MID} ${ly1}, ${LX + LW} ${ly1} Z`

三个容易被忽略的健壮性处理:

  1. 零宽节点也要可见:节点矩形高度取 Math.max(r.nodeH, 1),避免极小比例被渲染成不存在。
  2. 过滤空带:filter((b) => b.count > 0) 只画有内容的带,右侧间隙也只按可见带数量计算。
  3. 分解行只在有意义时出现:当一条带内包含多个阶段时,标签下方会渲染 Interview 2 · Offer 1 这样的分解;只有一个阶段时干脆不写,因为「Offer · Offer 2」不提供任何新信息。

此外,注释里明确说明了 viewBox 为什么要宽:元素按容器宽度铺满,宽 viewBox 让缩放系数接近 1,漏斗高度才合理、标签也不会被放大到失真。

七、任务组 5:容器组件与标签页

5.1 PipelineView:一次拉取、四态渲染

任务 5.1 要求:通过 getMyPipeline() 取数、处理 loading/error/empty、从桶计算两个比率、组合漏斗与两个环图、附上快照说明文字。当前容器 PipelineView.svelte 的结构是:

const pipeline = new AsyncData<PipelineStats | null>(null);
$effect(() => {
  if (isAuthenticated()) void pipeline.run(() => api.getMyPipeline());
});

渲染分四支:loading 用骨架、error 用提示、!stats || stats.applications === 0 用空态文案、其余渲染图表。空态判断放在容器而不是漏斗里,这样漏斗可以假设 applications > 0(但它仍自带兜底 if (applications <= 0 || visible.length === 0))。

比率的计算被抽到 pipeline.ts,而不是内联在模板里:

export function interviewRate(s: PipelineStats): number {
  if (s.applications === 0) return 0;
  return (s.stages.interview + s.stages.offer + s.stages.accepted) / s.applications;
}

这就是规范里「零申请时两个比率渲染为 0% 且不发生除零」那条场景的实现位置。比率函数返回 0–1 的分数,环图负责格式化——服务端从不返回预先除好的百分比,这条先例在设计文档里被特意保留。

脚注文案是快照语义的对外表达:「A snapshot of where your applications stand now. Rates are a lower bound — a job rejected after an interview counts only as rejected.」没有这句话,下界口径就会变成误导。文案本身走 PipelineView.messages.ts 的 i18n 消息表,并提供了俄语版本。

5.2 标签页顺序与鉴权

任务 5.2 要求标签顺序为 Board / Pipeline / History、默认仍为 Board,并继承页面已有的鉴权门控。当前仓库的导航已从单页 MyJobsView.svelte 演化为分区布局 web/src/routes/my/tracking/+layout.svelte,五个页面片段的顺序是 Board、List、Pipeline、Calendar、Activity,activeRouteTab(..., 'board') 保证未选择时落在 Board。鉴权则继承自整个 tracking 分区,Pipeline 没有自己的守卫。

八、任务组 6:验证清单

任务组 6 把验证写成三条可执行命令,这在多语言仓库里尤其重要,因为前后端各有自己的门槛:

任务 命令 检查内容
6.1 go build ./... && go vet ./... && go test ./... 编译、静态检查、单元测试
6.1 go test -tags=integration ./... 带 testcontainers 的集成测试
6.2 npm run check svelte-kit sync && svelte-check --tsconfig ./tsconfig.json
6.2 手工运行 用真实 /me/tracking/pipeline 数据确认 Sankey、环图与空态
6.3 契约与依赖 若动到生成契约需重新生成;确认没有新增 npm 依赖

最后一条「确认没有新增 npm 依赖」不是形式主义:整个功能从环图到 Sankey 全用原生 SVG 绘制,package.json 里没有任何图表库,这直接决定了组件的可测试性与包体积。

前端的单元测试也落在容器层,见 PipelineView.spec.ts:它 mock api.getMyPipeline,分别验证有数据与空数据两种渲染分支。

九、从这份任务清单能学到的三件事

第一,把领域口径钉在一个纯函数里。 阶段到分组的映射如果散落在前端静态表、后端 SQL 和组件内部,就会出现同一个已结束的申请在抽屉里叫 Rejected、在面板上叫 Closed、在桶里叫 rejected 的三重命名。设计文档把「桶词汇漂移」列为已知风险,并写下缓解办法:映射函数和前端静态表必须一起改,且由映射单元测试兜底。仓库后续的演进正是这条思路的极端化——干脆只保留一套阶段词汇,分组由 Go 的 Groups 表生成到前端契约,见 groups.go 与 web/src/lib/generated/contracts 中的 STAGE_GROUPS。

第二,聚合必须在服务端做,且必须覆盖全量。 列表接口是分页的,若在客户端对「当前页」做分组,得到的比例会随翻页漂移。所以设计决策 3 明确否决了「扩展 /me/jobs 的 meta」,改为一个只返回聚合的专用端点:契约更小,也不会让列表响应膨胀。

第三,诚实表达模型的局限比美化图表重要。 没有迁移历史就画不出真漏斗,方案没有伪造过渡,而是把每个申请固定在一个当前桶里,并在 UI 里说明这是当前状态快照、比率是下界。这条约束同时决定了「添加迁移日志」被显式列为 Non-Goal。

十、延伸阅读

登录后查看全文
freehire