在 freehire 岗位流中实现 CV 相似度排序:`sort=cv` 的模型、路由与空态设计
在 freehire 岗位流中实现 CV 相似度排序:sort=cv 的模型、路由与空态设计
本文以 freehire 的变更记录 cv-sort-jobs-feed 为主线,完整拆解一次“把独立的 /my/recommendations 页面折叠为岗位流内排序模式”的前端重构:排序值如何在 URL、localStorage 与 API 请求之间往返,分页器如何按排序值切换数据源,SSR 种子为何在 CV 模式下必须作废,以及如何用“是否存在 facet 过滤”区分两种语义不同的空列表。读完你可以掌握一套可复用的模式:把一个“新端点”包装成“前端路由信号”,在不动后端的前提下把能力嵌进已有列表,并能看清这套设计后来为何被技能匹配排序取代。
一、变更要解决的问题
变更提案 proposal.md 给出的动机非常直接:CV 相似度排序当时只存在于 /my/recommendations 独立页面,浏览主岗位流的用户根本发现不了它;而这个页面又重复实现了 /jobs 的筛选侧栏。方案是把它降维成主列表上的一个排序模式("Newest" 与 "Recommended"),既提升发现性,又消掉一个冗余页面。
技术前提在 design.md 里写得很清楚:CV 排序链路已经端到端存在。GET /api/v1/me/recommendations 由处理器 Recommendations 承接,内部调用 search.RecommendByVector,用一次 Meilisearch 查询同时施加 Filter 与 Vector(SemanticRatio: 1、查询文本为空):facet 过滤圈定候选集,CV 向量决定顺序。facet 参数经与关键词搜索同一个 search.FilterFromValues 翻译,因此两个端点接受完全相同的 facet 查询串,并返回同一个 jobview 结构。
反过来看主列表:/ 与 /jobs 由 JobsView.svelte 渲染,其分页器永远调用 api.searchJobs();facetModel.ts 里的排序词汇只有单一取值 'posted_at',且 filtersFromParams 从不回读 sort。也就是说,URL 里写 ?sort=cv 在当时会被完全忽略。
一次变更的边界由此确定:
| 维度 | 内容 |
|---|---|
| 改动范围 | 仅 Web 前端:facetModel.ts、JobsView.svelte、HeaderMenu.svelte,删除 routes/my/recommendations/* 与 RecommendationsView.svelte |
| 后端 | 零改动,GET /api/v1/me/recommendations 与 api.recommendations() 原样复用 |
| 数据库 / 索引 | 无迁移、无重建 |
| 明确不做 | 自由文本 q 与 CV 排序组合、公司内嵌岗位流提供 CV 排序、逐行匹配百分比徽标 |
二、五个关键设计决策
设计文档给出的五个决策,构成了后面所有任务项的依据。它们是理解这套实现的关键,比任务清单本身更值得先读。
决策 1:sort=cv 是前端路由信号,不是后端排序字段。 当生效排序为 cv 时,分页器改调 api.recommendations(),而不是给 api.searchJobs() 传一个它不认识的排序值。sort 参数在到达任何 API 之前会被剥离——搜索端点的排序白名单是 posted_at/created_at/salary_*,cv 传过去最好的结果是“被忽略”,最坏的结果是“产生误导”。这个值只留在 URL 与 store 里用于往返。
设计文档还记录了一个被否决的替代方案:给 /jobs/search 增加 cv 排序模式。否决理由充分——该端点未鉴权,接收的是查询文本向量而非调用者的 CV 向量,拿不到调用者身份,因此 RecommendByVector 才是唯一干净路径。
决策 2:SSR 继续提供公开的 “Newest” 流,CV 模式纯客户端。 首页与 /jobs 的 +page.server.ts 继续用 searchJobs 服务端渲染第一页(可抓取、可缓存、无鉴权)。当访问者带着 ?sort=cv 落地时,SSR 出来的种子是按最新排序的,在 CV 语义下是错的,于是客户端在首个 effect 运行时强制重载。这里复用了既有的 initialStale 守卫(原本用于“种子为另一个 URL 抓取”的场景),把它扩展成“initialStale 或 filters.applied.sort === 'cv'”。
决策 3:排序复用既有过滤器模型往返。 filtersToParams 已经会为非默认排序写出 ?sort=<v>,无需修改;只需让 filtersFromParams 学会回读 sort(白名单解析,未知值退回默认),顺带就让独立列表的 localStorage 也能恢复 CV 模式。store 侧的 setSort() 早已存在,UI 直接调用即可。
决策 4:空态消歧从 RecommendationsView 搬进列表。 空的 CV 列表在 API 层是有歧义的——“没有 CV”和“过滤条件无匹配”都返回 []。原页面的做法是看“是否有 facet 过滤生效”,这段逻辑必须在删页面之前先搬进列表。另外,登出的 CV 模式在客户端就被拦住(不发请求),因为端点会返回 401。
决策 5:删导航链接不需要 header-navigation 的 spec delta。 该能力的“Consolidated menu”需求从未列出 Recommendations 项(代码跑在了规格前面),删链接属于实现清理而非规格变更。
三、任务组 1:排序模型与 URL 往返
任务 1.1 要求先写失败的单测,把契约钉死:
filtersFromParams能把sort=cv读回为sort: 'cv';- 未知或缺失的
sort落到默认值(当时是'posted_at'); filtersToParams在 CV 模式写出sort=cv,默认模式则不写sort。
任务 1.2 把 SortField 扩成 'posted_at' | 'cv',并让解析只接受已知值。
这三条契约在今天的 facetModel.ts 里以更成熟的形式沉淀下来了。先是“词汇 + 参数名双向映射”,而不是在解析处硬编码字符串:
// web/src/lib/facetModel.ts#L139
export type JobSort = 'relevance' | 'newest' | 'views' | 'match';
// L169-L178:只列出“需要写线上参数”的排序;relevance 缺省即不写
const SORT_PARAM: Partial<Record<JobSort, string>> = {
newest: 'posted_at',
views: 'view_count',
match: 'match',
};
/** SORT_PARAM inverted, so the two directions cannot drift. */
const SORT_FROM_PARAM: Record<string, JobSort> = Object.fromEntries(
Object.entries(SORT_PARAM).map(([sort, param]) => [param, sort as JobSort]),
);
再是解析端的白名单回退,位于 facetModel.ts:
// Anything but a recognized value reads as the contextual default — including the
// retired `sort=cv` and the endpoint's `created_at` ...
f.sort = SORT_FROM_PARAM[p.get('sort') ?? ''] ?? null;
这段注释正是本次变更的遗迹:sort=cv 后来被摘除了,解析规则退化为“不认识就当作未选择”。而“未选择”之所以是 null 而非某个具体默认值,是因为默认值依赖 q(见 defaultSortFor):有查询文本时默认 relevance,无文本时默认 newest。设计文档里“把默认写成参数缺失”的原则,在这里以 filtersToParams 的几行代码落地:
const sort = effectiveSort(f);
const sortParam = SORT_PARAM[sort];
if (sortParam && sort !== defaultSortFor(f.q)) p.set('sort', sortParam);
这段逻辑与任务 1.1 的第三条断言完全同构:默认值不写、非默认值才写。好处是浏览态与相关度搜索都能序列化出干净的 URL;而当有查询文本却显式选择“最新”时,sort=posted_at 会被显式写出,不会被服务端的“有 q 就走 relevance”规则静默吞掉。
任务 1.3 关注 canonicalQuery 与持久化路径的往返。canonicalQuery 的实现是“解析再序列化”,因此只要解析与序列化两个方向对齐,排序值就自然被保留:
// web/src/lib/facetModel.ts#L425
export function canonicalQuery(query: string): string {
return savedSearchQuery(filtersFromParams(new URLSearchParams(query)));
}
需要注意,当前仓库里 canonicalQuery 走的是 savedSearchQuery,它在生成“保存搜索/提醒”的目标查询时会显式把 sort 置空({ ...f, sort: null }),理由写在函数注释里:保存搜索关心的是“哪些岗位在集合里”,排序不改变集合成员,把排序纳入 key 会让“改个排序”把保存搜索标脏并产生重复。持久化侧则由 filterStorage.ts 的 hire.jobFilters 键承载:URL 始终是唯一真相,storage 只是“最近一次显式筛选集”的镜像,回到裸 /jobs 时用于恢复。也就是说,sort=cv 的持久化往返依赖的是 storage 里存的是完整序列化查询串,而不是专门的排序字段——这正是决策 3 想要的效果。
四、任务组 2:数据路由与 SSR 种子作废
这一段是整个变更最容易出错的地方,因为它同时涉及三条路径:请求参数、分页器、SSR 种子。
任务 2.1 要求:在 scopedParams() 里,当 filters.applied.sort === 'cv' 时把 sort 从参数中剥掉。任务 2.2 要求:makePaginator() 按排序分支。当前代码里这两处的骨架是:
// web/src/lib/components/JobsView.svelte#L94
const standalone = $derived(Object.keys(scope).length === 0);
// L108-L113:生效的 facet 过滤 + 固定 scope(company_slug 等)
const scopedParams = () => {
const p = filtersToParams(filters.applied);
for (const [k, v] of Object.entries(scope)) p.set(k, v);
return p;
};
// L116-L119:当时的请求永远走关键词搜索
const makePaginator = () =>
new Paginator<Job>((limit, offset) => api.searchJobs(scopedParams(), limit, offset), {
keyOf: (job) => job.public_slug,
});
按任务清单,变更后这两处应演化为(以下为依据 tasks.md 2.1/2.2 的示意,不是仓库现存代码):
const scopedParams = () => {
const p = filtersToParams(filters.applied);
// 路由信号不得到达 API:搜索端点的排序白名单不含 cv
if (filters.applied.sort === 'cv') p.delete('sort');
for (const [k, v] of Object.entries(scope)) p.set(k, v);
return p;
};
const makePaginator = () =>
filters.applied.sort === 'cv'
? new Paginator<Job>((limit, offset) => api.recommendations(scopedParams(), limit, offset), {
keyOf: (job) => job.public_slug,
})
: new Paginator<Job>((limit, offset) => api.searchJobs(scopedParams(), limit, offset), {
keyOf: (job) => job.public_slug,
});
standalone 的存在是任务 3.1 与规格里“公司内嵌流不得出现 CV 排序”的实现基础:scope 为空即独立列表,非空即公司范围列表。
任务 2.3 是 SSR 种子守卫。当前代码里 initialStale 的定义与首轮 effect 的短路如下:
// web/src/lib/components/JobsView.svelte#L320
const initialStale = browser && page.url.search !== location.search;
// L495-L500
const firstRun = !started;
if (firstRun) {
started = true;
// Keep the SSR `initial` page unless it was loaded for a different URL than
// the address bar (stale shallow-routing restore)
if (!initialStale) return;
}
首轮 effect 的语义是“种子可用就直接用,不重复请求”。CV 模式打破了这个前提:种子是按 newest 排的,即使 URL 完全一致也不可用。因此任务 2.3 把短路条件改成“initialStale 或 处于 CV 模式时继续往下走,强制 reloadList”。
这里有一个值得记住的通用判据:SSR 种子的“新鲜”不只是“URL 对得上”,还包括“这份数据是否由同一套排序/过滤语义产出”。如果排序改变了数据源端点,那么 URL 相等并不代表种子有效。
配套的还有一个工程细节:Paginator 的构造签名为 (limit, offset) => Promise<Slice<T>>,并带 keyOf 做跨页去重(见 paginated.svelte.ts),因此切换数据源只是换一个 fetch 函数,分页/加载态/去重逻辑全部复用。这正是“同参数、同 jobview 形状”这一后端契约带来的红利。
五、任务组 3:排序控件
任务 3.1 的位置选择很具体:计数行右侧、仅 standalone 渲染,选项为 "Newest"(posted_at)与 "Recommended"(cv),绑定到 filters.setSort(...),读取 filters.value.sort。
setSort 的实现细节解释了“为什么切换排序不需要防抖”:
// web/src/lib/filters.ts#L155-L159
/** Switch the feed ordering. setNow, not setSoon: this is a discrete choice from a
* select, not a dragged gesture, and it re-orders the whole feed — debouncing it
* would leave the old order on screen with no indication anything is coming. */
setSort(sort: JobSort) {
this.#url.setNow({ ...this.#url.value, sort });
}
同一文件里滑杆类控件用 setSoon(拖拽过程会产生多个中间值),而下拉选择用 setNow。这个区分对“排序”尤其重要:整张列表要重新排序,延迟提交只会让用户看着旧顺序发呆。
当前仓库里的排序控件仍然保持这个形态,只是选项由 sortOptionsFor(q) 动态生成:
<!-- web/src/lib/components/JobsView.svelte#L685 -->
{#snippet sortSelect()}
<label class="flex shrink-0 items-center gap-1.5 text-sm text-muted-foreground">
<span class="hidden sm:inline">Sort</span>
<select
aria-label="Sort jobs"
value={selectedSort}
onchange={(e) => filters.setSort(e.currentTarget.value as JobSort)}
>
{#each sortOptions as opt (opt.value)}
<option value={opt.value}>{opt.label}</option>
{/each}
</select>
</label>
{/snippet}
selectedSort 与 sortOptions 都由纯函数产出(selectedSortFor / sortOptionsFor),放在 facetModel.ts 而不是组件里,理由是“它决定了用户看到什么,放在组件里就无法测试”。selectedSortFor 还处理了一个边界:共享链接可能带来一个当前选项列表里不存在的排序值(例如没有查询文本时却带着 relevance),此时返回服务端实际会用的排序,避免 <select> 因值不匹配某个 <option> 而渲染成空白。
有一个口径差异值得指出:spec.md 明确规定“排序控件仅向已登录用户提供”(Recommended 需要 CV,登出访客用不上),而 tasks.md 3.1 只写了“仅 standalone 渲染”。落实到实现,需要把两个条件取交集;后面的资格提示(任务组 4)正是为“登出者仍通过共享链接进入 CV 模式”这条残留路径兜底的。
六、任务组 4:资格提示与空态消歧
三条规则来自任务 4.1~4.3,也对应规格里的三个场景:
sort === 'cv'且用户登出 → 显示登录提示,跳过 fetch(不调用需要鉴权的端点,避免黄页式的 401 报错);sort === 'cv'、已登录、列表为空 → 若没有 facet 过滤生效,显示“添加/更新你的 CV”提示(链接到/my/profile);- 若有 facet 过滤生效,则显示普通的“无匹配”状态。
第 2、3 条的分叉依据是单 bit 信息——“是否应用了任意 facet 过滤”(activeFilterCount(f) > 0)。这是一个诚实的近似:API 无法区分“无 CV 向量”和“过滤后无匹配”,但用户可以仅凭“我到底加了过滤条件没有”做出正确解释。
这条“提示 + 说明降级原因”的模式在当前仓库里有同构实现。技能匹配排序不要求登录,但服务端对无法排序的调用者会降级为 newest,于是列表用一条提示解释原因而不是留白:
<!-- web/src/lib/components/JobsView.svelte#L802-L812 -->
<p class="font-medium text-foreground">Sorted by match needs to know about you</p>
<p class="mt-1 text-muted-foreground">
We rank these against your own skills, and we don't have them yet. Showing the
newest first for now.
</p>
判定逻辑同样被抽成纯函数 matchSortNeedsSkills(f, hasSkills),在组件里只做一层组合:
// web/src/lib/components/JobsView.svelte#L220-L222
const matchNeedsSkills = $derived(
skillsSettled && matchSortNeedsSkills(filters.value, matchFilterAvailable),
);
skillsSettled 这个前置条件值得学习:用户档案是异步加载的,在档案落地之前就断言“你没有技能”会闪出一条假提示。CV 模式同理——在确认用户有没有可用 CV 向量之前,不要把空列表直接解读成“该上传 CV 了”。
七、任务组 5:删除 /my/recommendations
删除清单很短但要求彻底(任务 5.1~5.3):
- 删除
web/src/routes/my/recommendations/+page.server.ts、+page.svelte与web/src/lib/components/RecommendationsView.svelte; - 从
HeaderMenu.svelte移除{ href: '/my/recommendations', label: 'Recommendations' }; - 全仓 grep
my/recommendations与RecommendationsView,确认只剩保留的api.recommendations()与 OpenSpec 变更记录本身。
从当前仓库状态看,这一步执行得比清单更彻底:web/src/routes/my/ 下已经没有 recommendations 目录,web/src/lib/api.ts 中也搜不到 recommendations 函数。与之对应,后端在后续变更中断言该端点已移除——search.go 的接口注释明确写着 “/me/recommendations was removed outright”,semantic.sql 也保留了同样的说明。
删除带来的迁移路径写在规格的 “REMOVED Requirements” 里,非常简洁:用主岗位流(/)并选择“Recommended”排序,或直接链接到 /?sort=cv;GET /api/v1/me/recommendations 契约不变,仍为该流提供数据。设计文档补充了部署后的行为:/my/recommendations 路由直接 404,功能等价物是 /?sort=cv;回滚就是一次普通 revert,因为后端自始至终未被触碰。
把“空态逻辑先搬走、再删页面”写进任务顺序(4 在 5 之前)是这次变更里最值得复制的一条流程纪律:删组件的风险不在删本身,而在行为随组件一起消失却没人发现。
八、任务组 6:验证矩阵
清单里的验证被拆成三层,并且明确指出了一个 CI 事实:
| 层级 | 命令 / 手段 | 覆盖 |
|---|---|---|
| 单元测试 | vitest(facetModel 往返用例) |
解析白名单、默认值不序列化、sort=cv 往返 |
| 静态检查 | svelte-check + eslint |
组件类型与规范;清单特别注明 web CI 并不 gate 这两项,需本地跑 |
| 手工端到端 | 见下 | 路由、提示、刷新恢复 |
手工验证项写得像一份可执行的验收脚本:
- 已登录且有 CV 的用户在 Newest 与 Recommended 之间来回切换;
- 在 CV 模式下叠加一个 facet 过滤,确认排名流被收窄;
- 刷新
?sort=cv,确认恢复 CV 模式而非回落到最新; - 登出用户与无 CV 用户分别看到对应提示。
其中“在 CV 模式下叠加 facet 过滤”这一条是后端的既有能力(facet 参数经同一个 FilterFromValues 翻译),前端要验的其实是参数没有被 scopedParams() 的剥离逻辑误伤——剥离只针对 sort 一个键。
九、风险与权衡
设计文档列出的四条风险,实际上定义了这套实现的“可接受退化”边界:
| 风险 | 表现 | 处置 / 判断 |
|---|---|---|
| CV 模式下的 newest 闪现 | 带 ?sort=cv 落地时先看到 SSR 的最新流 |
接受;与当时纯客户端的推荐页行为一致,重载立即发生 |
持久化的 sort=cv 对已不适用用户 |
老访客的 storage 里仍有 sort=cv,看到提示而非岗位 |
由常驻提示承接,不是错误态 |
| CV 模式下自由文本被静默忽略 | 输入了关键词又选 CV 排序,排名未使用文本 | 明确列为非目标;facet 过滤仍然生效 |
| 删除视图会孤立空态逻辑 | 无 CV / 无匹配无法区分 | 先搬逻辑再删页面(任务 4 先于任务 5),并用列表侧用例验证 |
第三条尤其需要在产品文案上诚实:端点忽略查询文本,所以 CV 模式下 q 不影响排名。变更选择了“延后组合”而不是“看起来支持实则无效”。
十、这套设计的结局:被技能匹配排序取代
写作时最重要的一条事实核对是:sort=cv 在当前仓库里已经是历史。
web/src/lib/facetModel.ts#L393-L399 的注释直言 “the retired sort=cv”,对应的单元测试也固化了这个行为:
// web/src/lib/facetModel.test.ts#L457-L459
it('ignores a legacy sort=cv param — falls back to the default feed, not an error', () => {
expect(filtersFromParams(new URLSearchParams('sort=cv'))).toEqual(filtersFromParams(new URLSearchParams('')));
});
退场原因记录在 drop-hybrid-search-pgvector-similar/proposal.md 里:把 /recommendations 迁移到 pgvector 需要“为任意请求级 facet 过滤写一套 SQL 转译器”,或者做一次“Meili 先过滤再 pgvector 排序”的两段式查询;面对一个使用量不确定的特性,维护者选择整体移除而不是迁移——端点、排序模式以及简历上传时的 CV 向量写入路径一并删除。取代它的是 skill-match-sort/proposal.md 引入的 sort=match:把候选者技能与岗位技能各自变成定宽向量(技能是有限字典里的规范 slug,向量可算术构造,不涉及 embedding 模型),按稀有度加权后做余弦排序。这也解释了当前 JobSort 里为什么是 'relevance' | 'newest' | 'views' | 'match'。
值得注意的是,本次变更沉淀的模式并没有随之消失,而是被复用在了新排序上:
- 排序词汇与线上参数的双向映射表(
SORT_PARAM/SORT_FROM_PARAM),避免两个方向漂移; - 默认值序列化为“参数缺失”,并由
effectiveSort做纯函数解析; - 排序的可用性判定与解释文案走纯函数(
matchSortNeedsSkills),组件只负责渲染; - 服务端对无法服务的排序降级而非报错,因此客户端不需要隐藏选项,共享链接在登录后自动生效。
与 sort=cv 的关键差别在于:match 是搜索端点真正支持的排序值,不再需要“前端路由信号”这层间接;只有当排序必须换端点、且换端点意味着换鉴权语义时,sort=cv 那套“剥离参数 + 切换分页器 + 作废 SSR 种子”的三件套才是必要的。
十一、可复用的经验清单
如果要把这次变更压缩成可迁移的工程判断,大致是以下几条:
- 区分“路由信号”与“线上参数”。一个只用于选择数据源的取值,绝不应该出现在另一个端点的参数列表里;剥离动作要放在参数构造的最后一环(
scopedParams()),而不是散落在各个调用点。 - SSR 种子的有效性要包含语义维度。URL 相同不代表种子可用;当排序改变了数据源,首轮 effect 必须允许强制重载。
- 默认值写成“不写参数”。这既让 URL 干净,也让“用户没选”和“用户选了默认值”在语义上可区分——后者在带查询文本时尤其重要。
- 歧义空态要用可得信息消歧,并诚实标注近似。“无 CV”与“无匹配”在 API 层无法区分,用“是否应用了 facet 过滤”做判据并接受其局限,好过含糊地显示一个空列表。
- 先搬逻辑,再删页面。删除路径的风险是行为静默丢失,任务顺序本身就是一种防回归手段。
- 降级优先于拒绝。无法服务的排序由服务端降级、由前端解释,共享链接因此不会变成坏链接。
相关文件索引
- 变更文档:proposal.md、design.md、tasks.md、spec.md
- 排序模型:facetModel.ts、facetModel.test.ts
- 列表视图与分页器:JobsView.svelte、paginated.svelte.ts
- 过滤器 store 与持久化:filters.ts、filterStorage.ts
- SSR 首屏:+page.server.ts
- 后续演进:drop-hybrid-search-pgvector-similar、skill-match-sort