freehire 应用阶段与备注能力设计与实现:从 proposal 到 PATCH /jobs/:slug/track
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 应用记录 → 条件写事件账本 → 返回拼装行":
priorCTE 先取该应用当前stage,供后面判断"是否真的发生了变化";touchCTE 对user_jobs做 upsert,保证即使从未打开过该岗位也留下交互行(viewed_at走默认值);upsertCTE 写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 nulltrack notes-only leaves the stage unchanged (partial update)MarkApplied seeds stage='applied' only when unset(推进到offer后再次 apply,仍是offer)MarkApplied promotes a preparing stage to appliedMarkApplied 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(岗位仍留在浏览历史里)。这类"清什么、留什么"的边界,正是最容易在重构中被悄悄改变的契约。
迁移与上线:提案的做法与仓库的演进
提案给出的迁移计划是三步:
- 新增
migrations/0014_application_stage.sql(ADD COLUMN IF NOT EXISTS stage TEXT/notes TEXT),跑make sqlc,重建开发卷; - 发布代码(查询、handler、路由、SPA);
- 生产环境按 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 服务、把词表与标签改为契约生成)中都保持了形状不变,只在物理位置上做了迁移与收回——这正是当初把"加性、可空、可回滚"写进提案的回报。