freehire 应用阶段与备注能力设计与实现:从 proposal 到 PATCH /jobs/:slug/track

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

freehire 应用阶段与备注能力设计与实现:从 proposal 到 PATCH /jobs/:slug/track

本指南以 freehire 仓库中 add-application-stages 变更提案为线索,完整拆解"求职跟踪器"如何从"记录了投递时间"升级为"能管理投递流程"。读完后你将掌握:stage 受控词表的校验位置与理由、PATCH /api/v1/jobs/:slug/track 的部分更新语义(含 SQL 层 COALESCE 实现)、MarkApplied 播种 applied 的幂等规则、服务层与 HTTP 层的职责切分,以及前端看板如何以乐观更新驱动状态流转。

导读:这条变更解决了什么问题

原始提案 proposal.md 的 "Why" 部分给出了明确动机:登录用户已经可以记录"看过 / 收藏 / 投递"三种状态,但投递之后无处存放后续进展——招聘方回复、初筛、面试、offer,也无处写备注。user_jobs 模型本来就是个人求职追踪器的第一块切片,而 stage 列与备注正是"设计过但尚未实现"的下一块。

这条变更因此把 user_jobs 从"投递时间戳"扩展成"可推进的流水线位置 + 自由文本记忆",并同时向浏览器、API 客户端、CLI(freehire-cli)与 career-ops 开放同一套写入能力。

变更概览:五件事,全部可加性

原提案的 "What Changes" 列出了五项核心改动,这里保留其完整范围,并在后续章节逐一落到源码:

# 变更点 落地位置
1 user_jobs 新增两个可空列:stage(流水线位置,NULL = 未进入流水线)、notes(自由文本,NULL = 无备注) 数据库迁移 + sqlc 生成
2 一套阶段词表,在 Go 中校验(不写 DB 约束);活跃阶段与终态阶段分组 stages.go
3 MarkApplied 在 stage 为 NULL 时播种 applied,已有阶段不动 user_jobs.sql
4 新端点 PATCH /api/v1/jobs/:slug/track,body {stage?, notes?},支持 Cookie 或 API Key 鉴权 user_jobs.go
5 My Jobs 页面展示阶段徽标、下拉改阶段、内联编辑备注 JobBoard.svelte

原提案特别强调 No breaking changes:列是可加且可空的,端点只在既有响应里增加字段。这一点在后续实现中也被严格保持。

设计决策:七个 D,逐条对照源码

原设计文档 design.md 以 D1–D7 固定了方案边界与备选方案的取舍。这些决策是理解整个功能"为什么长这样"的关键。

D1:阶段与备注是属性,不是新表

提案选择在交互记录上直接加两列,而非新建 applications 表。理由是:(user, job) 一行一个交互,这条交互本身就是那条投递记录。

这一决策后来在仓库中发生了有据可查的演进:受"投递记录不应随岗位下架而消失"驱动,0064_applications.sql 把 applied_at、stage、notes、followed_up_at 迁到独立 applications 表,而 0066_user_jobs_drops_the_application.sql 则把 user_jobs 上的这四列正式删除。因此读今天的 SQL 会看到 stage/notes 来自 applications,而 user_jobs 只保留"目录行上的标记"(viewed/saved/dismissed/vote)。D1 的"一行一个交互"结构没变,变的是这条交互的物理归属——它被拆成"目录标记表 + 流程表"两张表,并用 (user_id, job_id) 左连接拼回同一个交互形状。

D2:词表在 Go 校验,不写 DB CHECK

设计文档给的理由是:与仓库中已有的 enrichment 词表保持一致,新增阶段不需要迁移,未知值得到一个干净的 400;而 Postgres enum/CHECK 太刚性。

源码印证得非常直接:词表就是一份 []string,校验就是一次线性查找。

// internal/application/userjob/stages.go
var Stages = []string{
	"preparing", "applied", "screening", "responded", "interview",
	"offer", "accepted", "rejected", "withdrawn", "expired",
}

func ValidStage(s string) bool {
	for _, st := range Stages {
		if st == s {
			return true
		}
	}
	return false
}

注意与提案原文的差异:提案只列了 8 个值(applied, screening, responded, interview, offer + accepted, rejected, withdrawn),当前实现扩展为 10 个,新增 preparing(CV 定制阶段的看板占位)与 expired(无人回复的结局)。这正是 D2 兑现的价值——加阶段不需要迁移。docs/API.md 也同步了这份 10 值词表,并明确 expired 是"没人回复"的结局,"没有程序会替你设置它"。

单测 track_test.go 用正反两个方向锁住词表:所有 userjob.Stages 成员必须有效,banana、空串、Applied(大小写敏感)、interviewing 必须无效。

D3:流转自由,不强制单向

提案的原话是"个人追踪器:用户会跳步,也会纠错"。因此 handler 只校验"这个值在词表里",不校验"这个值是否比上一个更靠后"。

有意思的是,仓库里确实存在一个单向规则,但它只服务于自动推进:pipeline.go 的 Forward(current, target) 严格向前、且只在活跃阶段之间移动,用于邮件分类自动推进阶段;它不是用户手动写入的门槛。这套区分很值得借鉴:人工写入宽松,机器推断保守。

func Forward(current, target string) bool {
	if IsTerminal(current) { return false }
	next, ok := activeRank[target]
	if !ok { return false }
	return next > activeRank[current]
}

D4:一个端点、部分更新、COALESCE 兜住"未提供"

设计文档规定:查询像 save/apply 一样做 upsert,并用 COALESCE(EXCLUDED.col, user_jobs.col),使 nil 字段保持原值;同时要求"至少提供一个字段,否则 400"。

当前 SQL 实现完整保留了这一语义(列名已随 0064 改为 applications):

-- internal/platform/db/queries/user_jobs.sql  (TrackJob)
DO UPDATE SET stage = COALESCE(EXCLUDED.stage, applications.stage),
              notes = COALESCE(EXCLUDED.notes, applications.notes)

COALESCE 让"缺省"和"清空"成为两个不同动作:body 没有 notes 键 → 保持原值;body 传 notes: "" → 清成空串。提案的风险章节专门把这条列为"有意为之",因为原文担心"空串 vs NULL"被误当成缺陷修掉。

D5:MarkApplied 只在 NULL 时播种

规则是 COALESCE(applications.stage, 'applied'):投递让应用进入流水线,但已经手动推进过的阶段不会被二次投递冲掉。当前实现还多了一条提案中没有的规则——把 preparing 也提升为 applied:

stage = CASE
    WHEN applications.stage IS NULL OR applications.stage = 'preparing' THEN 'applied'
    ELSE applications.stage
END

SQL 注释解释了原因:CV 定制(EnsureOnBoard)会用 preparing 占位且不设 applied_at,而"真实投递信号正是应该把它提升出去的那个事件"。集成测试把三种情况都写成了子测试(见后文测试章节)。

D6:读出侧不新增端点,只加字段

stage/notes 被加进 interactionResponse 与 my-jobs 列表行,因此 view/apply/save/unsave/track 五个响应与列表读都会携带它们,不引入新的读端点。当前代码同样如此:

type interactionResponse struct {
	JobID       int64      `json:"job_id"`
	ViewedAt    *time.Time `json:"viewed_at"`
	SavedAt     *time.Time `json:"saved_at"`
	AppliedAt   *time.Time `json:"applied_at"`
	DismissedAt *time.Time `json:"dismissed_at"`
	Stage       *string    `json:"stage"`
	Notes       *string    `json:"notes"`
}

用指针类型是为了让"未设置"序列化为 null 而不是零值 "",前端据此区分"没有阶段"和"阶段是空字符串"。

D7:能力折叠进已有页面,不新开 Applications 页

提案明确要求把阶段徽标、下拉框、备注文本域折进 My Jobs 页面,不做独立的投递页。当前实现落在求职看板组件上,并在此基础上演进为 Kanban 拖拽(见"前端实现"章节)。

API 契约:请求、响应与错误映射

端点定义

PATCH /api/v1/jobs/:slug/track
Auth: Session cookie 或 API Key(RequireAuthOrKey → mw.key)

路由注册在 user_jobs.go 的 register 中,与其他 per-user 写操作并列:

api.Post("/jobs/:slug/view", mw.key, h.RecordView)
api.Post("/jobs/:slug/apply", mw.key, h.MarkApplied)
api.Patch("/jobs/:slug/track", mw.key, h.TrackJob)
api.Delete("/jobs/:slug/stage", mw.key, h.ClearStage)
api.Delete("/jobs/:slug/track", mw.key, h.Untrack)

一个细节值得注意:路由参数是 :slug 而不是提案早期版本里的 :id。注释说明了原因——handler 会把 slug 解析成内部 id 再写库,这样浏览器与持有 API Key 的脚本可以走完全相同的流程。

请求体与响应

字段 类型 必填 说明
stage string 否 必须属于受控词表;未知值 → 400
notes string 否 自由文本;传 "" 表示清空

两者至少提供一个,否则 400。以下示例取自 docs/API.md:

curl -X PATCH "https://freehire.me/api/v1/jobs/<slug>/track" \
  -H "Authorization: Bearer $FREEHIRE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"stage":"interview","notes":"call on Friday"}'
{ "data": { "job_id": 42, "stage": "interview", "notes": "call on Friday" } }

错误映射表

trackingError 把领域哨兵错误翻译成 HTTP 状态码,其他错误(如数据库故障)落到统一渲染的 500:

领域错误 HTTP 消息
ErrJobNotFound 404 job not found
ErrInvalidStage 400 invalid stage
ErrEmptyTrack 400 provide stage and/or notes
ErrInvalidFilter 400 filter must be one of: all, viewed, saved, applied, board
ErrApplicationNotFound 404 application not found
applydate.ErrOutOfRange 400 由服务层给出的具体越界说明

未认证则走中间件,返回 401 且不写任何数据。

服务层:先校验,再解析 slug

提案只说了"一个 handler",但仓库随后把规则下沉到独立服务(见 extract-job-tracking-service 提案)。这一层是理解校验顺序的关键:jobtracking.go 的 Track 先校验 body,再做 slug 查询,因此坏请求永远到不了数据库。

func (s *Service) Track(ctx context.Context, userID int64, slug string, stage, notes *string, source string) (Interaction, error) {
	if stage == nil && notes == nil {
		return Interaction{}, ErrEmptyTrack
	}
	if stage != nil && !userjob.ValidStage(*stage) {
		return Interaction{}, ErrInvalidStage
	}
	jobID, err := s.repo.JobIDBySlug(ctx, slug)
	if err != nil {
		return Interaction{}, err
	}
	return s.repo.TrackJob(ctx, userID, jobID, stage, notes, source)
}

这个顺序也被测试利用:track_test.go 里的 stubTrackingRepo 注释直言,这些用例在触碰 repository 之前就被拒绝,所以桩方法只要存在即可——一旦校验顺序回归,请求会意外打到桩上并 panic。

服务依赖的是窄接口 Repository(含 TrackJob、TrackApplication、ClearJobProgress、UntrackJob 等),真实实现 QueriesRepository 在 repository.go 中把 *db.Queries 适配进来。

阶段词表的唯一来源与前端生成

提案的风险章节预判了"词表在 Go 后端 ↔ SPA 标签 ↔ 未来 CLI 之间重复"的问题,给出的答案是:Go 是唯一真源,SPA 镜像它,漂移时按人类可读标签降级显示、永不崩溃。

仓库后来把这条约束做成了生成 + 编译期断言:

  • groups.go 定义 Groups(阶段→粗粒度看板列)与 stageLabels(人类可读文案),并配套 GroupOf、Label;
  • cmd/gen-contracts 把它们发射成 contracts.ts 中的 STAGE_VALUES、STAGE_LABELS、STAGE_GROUPS;
  • stages.ts 只读取生成物,不再自带第二份文案,并用 Assert<Eq<Stage, GroupedStage>> 做双向类型检查——任何新阶段若未归组,pnpm run check 直接失败。

当前分组在流水线顺序上是五个:preparing、applied(含 applied/screening/responded)、interview、offer、closed(含 accepted/rejected/withdrawn/expired)。注意 closed 这一组把三种终态收进同一列,卡片仍保留自己的精确阶段标签——这是"粗列 + 细标签"的组合,避免三列几乎恒空。

降级路径也实现了:humanizeStage 对词表外的值做首字母大写兜底,因此老前端遇到新阶段不会崩,只是显示得不那么漂亮。

数据库实现细节

部分更新与幂等 upsert

TrackJob 的完整结构是"读旧值 → 保证交互行存在 → upsert 应用记录 → 条件写事件账本 → 返回拼装行":

  • prior CTE 先取该应用当前 stage,供后面判断"是否真的发生了变化";
  • touch CTE 对 user_jobs 做 upsert,保证即使从未打开过该岗位也留下交互行(viewed_at 走默认值);
  • upsert CTE 写 applications,冲突键是 (user_id, job_id) WHERE job_id IS NOT NULL 这个部分唯一索引;
  • 返回行的列顺序在各查询间保持一致,让 Go 层的 db.UserJob(row) 转换可以复用。

一个容易忽略但很重要的语义写在 SQL 注释里:applied_at 刻意为空。设置阶段不等于投递,一条没有日期的记录读起来就是"已跟踪、但未记为已投递"。这与迁移 0065_applications_applied_at_optional.sql 把 applied_at 改为可空是配套的。

事件账本:只在阶段真正移动时写

提案的 TrackJob 只写表;当前实现额外写了一条 stage_set 事件,但仅当阶段确实变化:

INSERT INTO application_events (... kind, signal, occurred_at, source)
SELECT ..., 'stage_set', u.stage, now(), sqlc.arg(event_source)::text
  FROM upsert u JOIN jobs j ON j.id = sqlc.arg(job_id)::bigint
 WHERE u.stage IS NOT NULL
   AND u.stage IS DISTINCT FROM (SELECT prior.stage FROM prior)

理由同样写在注释里:账本记录的是"迁移",若每个 no-op 也留一行,"这个阶段持续了多久"就再也算不出来。对应的 Go 侧常量在 appevent.go(KindStageSet、SourceUser);handler 传入 appevent.SourceUser,这样"人改的"与"邮件推断的"在账本里可区分。

MarkJobApplied 的播种规则

当前实现的播种逻辑(含 preparing 提升)与"首次投递才自增 applied_count"共用同一谓词。SQL 注释点明了并发要求:必须在先取 LockJobForApply 的事务里执行,否则两个并发投递都会看到 applied_at 为空并各自自增一次。仓库还在同一语句里写了 applied 事件,使"计数器"和"账本"这两份关于同一次转换的记录不可能分歧。

前端实现:从徽标下拉到看板拖拽

提案的 D7 描述的是"阶段徽标 + 下拉 + blur 保存的备注文本域"。当前实现沿用了同一套 API 调用,但界面演进为看板:

  • API 封装在 api.ts:trackJob(slug, patch) 打 PATCH /api/v1/jobs/:slug/track;后续新增的 trackApplication(id, patch) 打 PATCH /api/v1/me/applications/:id,用于"岗位被下架、只剩行 id"的场景——两者 body 与规则完全一致,包括部分更新。
  • JobBoard.svelte 里,拖拽落点直接映射成后端写入:preparing/applied/interview/offer 各调用一次 trackApplication;落到 closed 时不猜结局,而是打开抽屉要求用户选择(因为"组不决定阶段");落回无阶段列则调用 clearStage。
  • 备注走 blur 保存:
async function saveNotes(notes: string) {
  if (!openItem) return;
  openItem.notes = notes;
  try {
    await api.trackApplication(openItem.id, { notes });
  } catch {
    /* keep optimistic value; a transient failure shouldn't drop the edit */
  }
}

乐观更新 + 失败重载是这套界面的统一策略:阶段变更失败时 await load() 重新对齐服务端,备注失败则保留用户输入,避免把正在编辑的文本吞掉。"无阶段"的语义也被精心处理——它清除的是流水线位置而不是岗位本身,所以先把收藏标记补回去,再清阶段,这样已收藏岗位会退回看板起点列而不是消失。

测试覆盖:三层验证

原提案的 tasks 把验证分成单元、集成、端到端三层,仓库现状与之一致:

层次 文件 覆盖内容
Handler 单元(无 DB) track_test.go 空 body → 400;banana → 400;无凭证 → 401;expired → 200;响应含 stage/notes 字段
SQL 集成(testcontainers) user_jobs_stage_integration_test.go 部分更新、播种、清空进度、整行移除
端到端 tasks.md 记录的手工 curl 验证 PATCH ... track 返回 200 且 GET /me/jobs 行内携带 stage+notes

集成测试里最值得借鉴的是那段"阶段只写一次就够用"的子测试设计,它把提案 D4/D5 的每条断言都变成了可执行代码:

  • track stage-only creates the row and leaves notes null
  • track notes-only leaves the stage unchanged (partial update)
  • MarkApplied seeds stage='applied' only when unset(推进到 offer 后再次 apply,仍是 offer)
  • MarkApplied promotes a preparing stage to applied
  • MarkApplied does not regress a stage beyond applied

运行方式写在文件头:go test -tags=integration ./internal/platform/db/。

另外,ClearJobProgress 与 UntrackJob 两个后续新增操作也有对应断言:前者清 stage 与 applied_at、保留 saved_at 与 notes(拖回 Saved 的语义);后者清掉所有流水线标记、但保留 viewed_at(岗位仍留在浏览历史里)。这类"清什么、留什么"的边界,正是最容易在重构中被悄悄改变的契约。

迁移与上线:提案的做法与仓库的演进

提案给出的迁移计划是三步:

  1. 新增 migrations/0014_application_stage.sql(ADD COLUMN IF NOT EXISTS stage TEXT / notes TEXT),跑 make sqlc,重建开发卷;
  2. 发布代码(查询、handler、路由、SPA);
  3. 生产环境按 ops runbook 用 psql 手工执行 0014,再部署 app 与 web 镜像。

回滚策略也被明确写出:只回退代码;列是加性且可空的,可以留着忽略,也可以删掉,因为没有任何其他东西引用它们。

必须提醒读者:该仓库当前不存在 migrations/0014_application_stage.sql(0014 号已被 0014_gmail_inbox.sql 占用)。这是有意的演进结果——applications 表在 0064 中携带 stage/notes 落地,user_jobs 上的旧列在 0066 中被删除。0066 的注释特别强调了这次回滚性质的变化:在 0066 之前回退代码能完全恢复旧行为(列还在、值还在),之后"回滚就是一次数据恢复",所以才把删列拆成独立且更晚的一次发布。

如果你要在自己的部署里复现这条变更的设计,可操作的检查清单是:

  • 迁移只做加性、可空变更,并写成幂等(IF NOT EXISTS);
  • 改完 SQL 跑 make sqlc,确认生成的参数结构体里 stage/notes 是可空类型(当前为 pgtype.Text,Valid=false 表示"未提供");
  • 部署前用集成测试验证 COALESCE 语义,而不是只测 happy path;
  • 生产改表与代码发布解耦,先表后码。

边界与刻意不做的事

提案的 "Out of scope" 不是遗漏,而是划界,值得原样继承:

  • 阶段专用筛选标签页;
  • 备注时间线 / 操作日志(当前以 application_events 账本记录阶段迁移,但不记录备注历史);
  • 强制单向流转(人工写入自由);
  • 漏斗分析(由 career-ops 承担);
  • freehire-cli 的 stage/note 命令(属于独立仓库的下游跟进,见 tasks 5.4 未完成项)。

理解这些"不做",才能理解为什么 handler 里没有任何"上一个阶段是否合法"的判断,也才能理解为什么 notes 被设计成覆盖式单字段而不是追加式条目——需要历史时,答案在账本与专用分析侧,而不在这个字段上。

小结

这条提案的价值不只在"加了两列一个端点",而在于它示范了一套可复制的小步演进方法:受控词表放在代码里以获得演化弹性、部分更新用 COALESCE 表达"未提供"、播种遵循"只填空不覆盖"、读出侧只加字段不新增端点、能力折叠进已有页面而非新开页面。这些决策在仓库后续的重构(迁移到 applications 表、抽出 jobtracking 服务、把词表与标签改为契约生成)中都保持了形状不变,只在物理位置上做了迁移与收回——这正是当初把"加性、可空、可回滚"写进提案的回报。

登录后查看全文
freehire