freehire 应用 Pipeline 看板实现指南:从任务拆解到阶段聚合与手写 SVG 可视化
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 回答「它们在哪里堆积、转化如何」。
原始需求与实现边界可以从这三份归档文档读到:
一个必须先讲清楚的前提是快照语义。设计文档明确写道: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`
三个容易被忽略的健壮性处理:
- 零宽节点也要可见:节点矩形高度取
Math.max(r.nodeH, 1),避免极小比例被渲染成不存在。 - 过滤空带:
filter((b) => b.count > 0)只画有内容的带,右侧间隙也只按可见带数量计算。 - 分解行只在有意义时出现:当一条带内包含多个阶段时,标签下方会渲染
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。
十、延伸阅读
- 变更提案与设计:proposal.md、design.md
- 能力规格:specs/application-pipeline/spec.md 与当前生效版本 openspec/specs/application-pipeline/spec.md
- 领域词汇:stages.go、groups.go、counts.go、userjob/AGENTS.md
- 数据与接口:user_jobs.sql、repository.go、jobtracking.go、me_tracking.go
- 前端:PipelineView.svelte、PipelineFunnel.svelte、RateDonut.svelte、pipeline.ts
- 测试:counts_test.go、me_pipeline_integration_test.go、PipelineView.spec.ts