freehire 应用阶段与备注追踪:PATCH track 接口、受控阶段词表与 My Jobs 看板实现解析
freehire 应用阶段与备注追踪:PATCH track 接口、受控阶段词表与 My Jobs 看板实现解析
本文以 freehire 仓库中 user-job-tracking 能力的规范文档为主体,系统讲解“把一次投递变成可追踪流程”的完整实现:如何幂等地标记已投递、如何用 PATCH /api/v1/jobs/:slug/track 部分更新阶段与备注、阶段词表为何放在 Go 而不是数据库约束里,以及 My Jobs 页面如何展示与编辑这些状态。读完后你应能照着规范与源码,自行调用(或复刻)这套追踪 API,并理解其幂等、校验顺序与 SQL 层语义。
一、问题起点:投递之后就没有下文了
freehire 的 user_jobs 原本一行一个 (user, job),只承载 viewed_at、saved_at、applied_at 三个时间戳。用户能记录“看过 / 收藏 / 投过”,但一旦投出去,就没有地方记录接下来发生了什么(招聘方回复、初筛、面试、offer),也没有地方写一句备注。
本次变更的目标非常克制(见 proposal.md):
- 新增可空字段
stage(流程位置,NULL 表示不在流程中)与notes(自由文本,NULL 表示没有备注); - 定义一套受控阶段词表,在 Go 中校验而不是数据库
CHECK; - 新增
PATCH /api/v1/jobs/:slug/track端点,支持会话 Cookie 或 API Key 认证; - 交互记录和 my-jobs 列表行都带上
stage与notes; - My Jobs 页面显示阶段徽章、提供下拉切换、备注失焦即保存。
明确的非目标同样重要:不做阶段专属筛选标签页、不做备注时间线、不做“只能前进不能回退”的流转约束、不做漏斗分析。这些边界决定了后面几乎所有的设计取舍。
二、规范里的两条主干需求
规范文档把需求分成“修改(MODIFIED)”与“新增(ADDED)”两组,前者保证原有投递语义不被破坏,后者引入阶段与备注。原文见 spec.md。
2.1 标记已投递:幂等,且只在阶段为空时播种
规范要求:已登录用户可以把职位标记为已投递,并且必须幂等;当 stage 当前未设置时,播种 stage = 'applied',已经设置过的阶段保持不变。认证可以是会话 Cookie 或 API Key,两者识别出的用户完全一致。端点必须返回更新后的交互记录。
对应的五个场景即为验收条件:
| 场景 | 期望 |
|---|---|
| 浏览后投递 | applied_at 被设置,返回 200 且 {"data": {job_id, viewed_at, applied_at}},其中 applied_at 非 null |
| 重复投递 | 行被原地更新,不产生重复行,也不报错 |
| 播种初始阶段 | stage 由空变为 applied;再次投递、或阶段已推进后再投递,均不改动既有阶段 |
| 未认证 | 返回 401,不写任何数据 |
| 不存在的职位 | 外键冲突表现为 404,而不是 500 |
2.2 追踪阶段与备注:一个端点,部分更新
新增需求规定:用户通过 PATCH /api/v1/jobs/:slug/track 设置 stage 和/或 notes,认证方式同上。请求体两个字段都是可选的,但至少要有一个(否则 400)。端点对 (user, job) 交互执行 upsert(不存在则创建),并做部分更新——请求体里省略的字段保持原值。提供的 stage 必须属于受控词表,未知值 400。端点返回更新后的记录。
规范中给出的词表是:
- 活跃阶段:
applied、screening、responded、interview、offer - 终态阶段:
accepted、rejected、withdrawn
并且流转不受限制:任意合法阶段都可以从任意阶段设置过来。这是一个个人追踪器,用户会跳步、会纠错,强制单向流转属于过度设计(见 design.md 中的 D3)。
七个场景覆盖了行为边界:
- 对从未交互过的职位
PATCH {"stage":"interview"}→ 创建交互记录、200; {"notes":"recruiter called Friday"}不带stage→ 只更新备注,阶段不变;{"stage":"banana"}→400且不产生任何变更;- 空 body →
400; - API Key 认证等价于 Cookie 认证;
- 无有效凭证 →
401且不写数据。
2.3 交互记录与列表都要带 stage/notes
规范要求交互记录在 view、apply、save、unsave、track 的响应里,以及 my-jobs 列表的每一行里,都携带 stage 与 notes(未设置时为 null),并且不改变既有交互形状的其它字段。
三、数据模型:阶段与备注最终落在 applications 表
值得注意的是规范写作时的设计决策与今天的实现已经不同。原文 D1 选择把 stage/notes 作为可空 TEXT 列加在 user_jobs 上,理由是这个交互行本身“就是”一次申请。但仓库当前的实现把它迁移到了独立的 applications 表,原因是 user_jobs 的 (user_id, job_id) 同时承载了两类语义不同的事实:对目录行的标记(查看、收藏、忽略、投票),以及一次真实的申请过程。职位被裁剪时级联删除会连带抹掉申请记录,而申请是“候选人生活里的事实”,不应随目录消失。
0064_applications.sql 建表的注释把这个推理写得很清楚,关键列如下:
| 列 | 类型 | 语义 |
|---|---|---|
id |
bigint 自增主键 |
追踪行自身的身份,看板按它寻址 |
user_id |
bigint NOT NULL |
归属用户,账号删除时 CASCADE |
company_slug / role_title |
text NOT NULL DEFAULT '' |
投递当时的雇主与职位名,冗余存储,因为职位可能消失 |
job_id |
bigint REFERENCES jobs ON DELETE SET NULL |
发现该职位的入口,可合法变为未知 |
applied_at |
timestamptz |
投递时间 |
stage |
text |
流程位置,词表由 Go 校验 |
notes |
text |
候选人自己的文本,这也是账本(ledger)无法替代此表的原因 |
followed_up_at |
timestamptz |
最近一次主动跟进的时间 |
并发约束保留在数据库层:applications_user_job_idx 是部分唯一索引,只在 job_id IS NOT NULL 时生效,于是“同一用户对同一职位至多一次申请”仍然成立,而未关联职位的两次申请被视为两个不同角色。另有 applications_user_applied_idx 支撑看板按投递时间倒序读取,applications_company_idx 支撑按公司聚合。
后续的 0065_applications_applied_at_optional.sql 进一步把 applied_at 改为可空,直接原因就是本文的主角:PATCH /jobs/:slug/track 可以在从未标记投递的职位上设置阶段。于是 NULL applied_at 的含义被明确定义为“被追踪,但尚未记录为已投递”,任何判断“确实投过”的消费者都必须显式检查 applied_at IS NOT NULL。
四、阶段词表:单一事实源与 JS 契约生成
规范说词表在 Go 中校验。实现把词表放在 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
}
与规范相比,当前词表多了两个值,这是需求落地的自然演进,不应视为冲突:
preparing:CV 定制功能把职位放到看板时使用,此时还没有投递(applied_at为空)。真正的投递信号会把preparing提升为applied。expired:无人回应的结局;docs/API.md 明确说明“没有任何东西会替你设置它”。
词表本身只是校验入口,展示与分组则需要另一套结构。groups.go 定义了粗粒度分组,把细粒度阶段折叠成看板列与漏斗带:
| 分组 ID | 标签 | 包含阶段 |
|---|---|---|
preparing |
Preparing | preparing |
applied |
Applied | applied、screening、responded |
interview |
Interview | interview |
offer |
Offer | offer |
closed |
Closed | accepted、rejected、withdrawn、expired |
三条终态被折进同一个 closed 列而非各占一列,理由是三个常年空着的列远不如一个承载大部分历史的列有用;卡片自身仍显示精确阶段标签,信息不丢。GroupOf 对词表外的值返回空串,而不是回退到 applied——一个无法归位的阶段不构成“雇主已沉默”的证据,而看板的沉默徽章恰好读取 applied 分组。
为了避免后端词表与前端标签各写一份,仓库用 cmd/gen-contracts 生成前端契约,vocab.go 负责把 userjob.Groups 渲染成有序数组字面量:
export const STAGE_GROUPS = [
{ id: 'applied', label: 'Applied', stages: ['applied', 'screening', 'responded'] },
…
] as const;
export type StageGroup = (typeof STAGE_GROUPS)[number];
用数组而非 map、且按表自身顺序而非排序输出,是因为这个顺序就是看板列序与漏斗带序;若交给前端自己声明顺序,就会再次产生重复副本。
五、API 契约与错误语义
5.1 路由注册
internal/api/handler/user_jobs.go 把交互类端点统一挂在 mw.key 上,允许会话 Cookie 或 API Key:
api.Post("/jobs/:slug/view", mw.key, h.RecordView)
api.Post("/jobs/:slug/apply", mw.key, h.MarkApplied)
api.Post("/jobs/:slug/save", mw.key, h.SaveJob)
api.Delete("/jobs/:slug/save", mw.key, h.UnsaveJob)
api.Post("/jobs/:slug/dismiss", mw.key, h.DismissJob)
api.Delete("/jobs/:slug/dismiss", mw.key, h.UndismissJob)
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;所有写入都是幂等 upsert。认证层由 internal/identity/auth/middleware.go 的 RequireAuthOrKey 提供,它先试 Cookie,再试全范围 API Key;作用域不覆盖该路由的活跃 Key 返回 403(权限不足),而不是 401。
5.2 请求体与响应形状
trackRequest 使用指针区分“字段缺省”和“字段为空字符串”(user_jobs.go):
type trackRequest struct {
Stage *string `json:"stage"`
Notes *string `json:"notes"`
}
这正是部分更新的实现基础:nil 代表“不改这一列”,而 notes: "" 代表“清空备注”。规范的风险章节把这两种情况都视为有意为之。
响应结构 interactionResponse 省略了 user_id(调用者就是用户自己),并在未设置时以 null 输出:
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"`
}
5.3 错误码映射
处理函数通过 trackingError 把领域哨兵错误映射为状态码(user_jobs.go):
| 哨兵错误 | HTTP | 消息 |
|---|---|---|
ErrJobNotFound |
404 |
job not found |
ErrInvalidStage |
400 |
invalid stage |
ErrInvalidFilter |
400 |
filter must be one of: all, viewed, saved, applied, board |
ErrEmptyTrack |
400 |
provide stage and/or notes |
ErrApplicationNotFound |
404 |
application not found |
applydate.ErrOutOfRange |
400 |
服务层给出的具体越界说明 |
其它错误(例如数据库故障)继续向上,由集中的 RenderError 输出 500。共用一条映射链的好处是:无 Cookie 无 Key 的请求由中间件直接 401,而“body 不合法”与“slug 不存在”永远不会被误报成 500。
5.4 校验顺序:先校验,后触库
internal/application/jobtracking/jobtracking.go 的 Track 顺序是刻意的:
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)
}
也就是说:坏请求永远不会触碰数据库,即使用户同时写错阶段和 slug,返回的也是 400 而不是 404。这一点被单元测试直接利用——测试替身里那些方法一旦被调用就会 panic,用“不 panic”来证明校验确实发生在仓储之前(见 track_test.go 的注释)。
六、SQL 层:播种、部分更新与事件账本
6.1 投递时播种阶段
internal/platform/db/queries/user_jobs.sql 的 MarkJobApplied 是一条带多个 CTE 的语句,与规范“只在阶段为空时播种”对应的是这段冲突更新:
stage = CASE
WHEN applications.stage IS NULL OR applications.stage = 'preparing' THEN 'applied'
ELSE applications.stage
END
preparing 被特别处理,是因为 CV 定制会把尚未投递的职位放到看板上;真正的投递信号正是应该把它推进到 applied 的事件,同时补上 applied_at。其它任何已有阶段在重复投递时都原样保留。
语句还处理了两件与计数器相关的事:
priorCTE 读取 upsert 之前的applied_at,只有从未设置变为设置时,才在同一语句内applied_count = applied_count + 1;eventCTE 在同一谓词下写入applied账本事件,occurred_at取行自身的applied_at,source由调用方传入(用户、助手、邮件来源)。
之所以强调“同一谓词”,是因为两条分别判定的记录迟早会不一致。而 prior 读的是语句快照,所以必须先在事务中取 LockJobForApply 串行化,否则两个并发投递都会看到 applied_at 为空并重复自增——仓储实现 repository.go 正是这样做的。
6.2 部分更新的实现
TrackJob 的 upsert 用 COALESCE 表达“缺省即不改”(user_jobs.sql):
ON CONFLICT (user_id, job_id) WHERE job_id IS NOT NULL
DO UPDATE SET stage = COALESCE(EXCLUDED.stage, applications.stage),
notes = COALESCE(EXCLUDED.notes, applications.notes)
Go 侧的 textFromPtr 负责把 nil 指针转成无效的 pgtype.Text(即 NULL),从而让 COALESCE 保留原值;非 nil 则转成有效值(repository.go)。
同一语句还写 stage_set 账本事件,但仅在阶段真的发生变化时:
WHERE u.stage IS NOT NULL
AND u.stage IS DISTINCT FROM (SELECT prior.stage FROM prior)
记录“相同阶段重设一次”或纯备注更新没有意义,反而会让“这个阶段持续了多久”无法回答。注释还说明该事件不带可信日期:source 是调用者而非雇主,因此暂时没有任何时间化的用法。
另外,TrackJob 故意不设置 applied_at:设置阶段不等于投递,这正是 0065 让该列可空的原因。
6.3 清空阶段与移出看板是两个不同动作
这两点常被混淆,源码里区分得很清楚:
DELETE /jobs/:slug/stage→ClearJobProgress:把stage与applied_at置空,保留saved_at、viewed_at与notes,对应看板把卡片拖回 “Saved” 列(user_jobs.sql)。注释强调申请记录本身保留,因为“清空进度”是候选人重新考虑,不是宣称过程没发生。DELETE /jobs/:slug/track→UntrackJob:直接DELETE FROM applications,并清掉saved_at,只保留viewed_at,因为职位仍应留在浏览历史里(user_jobs.sql)。这是候选人对自己记录做出的决定,只有他自己有资格做出。
七、My Jobs 的展示与编辑
规范要求:对于已登录用户,My Jobs 页面在每个被追踪职位上,若 stage 已设置则以人性化徽章展示;提供包含完整词表的控件用于切换阶段;备注支持行内编辑。未登录用户不应看到这些控件。
前端实现对应三处:
- API 封装。web/src/lib/api.ts 提供
trackJob(slug, {stage?, notes?}),走PATCH /api/v1/jobs/${slug}/track;同一段还提供按行 id 寻址的trackApplication(id, patch)、clearApplicationStage(id)、untrackApplication(id)。 - 标签与分组。web/src/lib/stages.ts 不再自己维护词表,而是从生成的
STAGE_GROUPS/STAGE_LABELS读取:humanizeStage给出人类可读标签,未知值退化为首字母大写而不会崩;groupedStages()返回按流水线顺序分组的选项,供下拉框渲染成带标题的选项组。 - 编译期一致性。
stages.ts里有一个刻意导出的类型断言StagesAreFullyGrouped,它保证“Go 词表里的每个阶段都被某个分组覆盖,且分组里提到的每个阶段都真实存在”。如果后端新增了一个阶段却没有归组,pnpm run check会失败,而不是让一张卡片出现在没有列的看板上。
看板卡片组件 BoardCard.svelte 用 humanizeStage(item.stage) 渲染徽章,并且只在 notes 非空时显示备注标记;抽屉组件 JobDrawer.svelte 负责阶段选择与展示的细节。这与规范 D7 的“折叠进既有页面、不新开 Applications 页面”一致。
八、端到端调用示例
以下示例取自 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" } }
只改备注、不动阶段(stage 字段省略即保留):
curl -X PATCH ".../api/v1/jobs/<slug>/track" \
-H "Authorization: Bearer $FREEHIRE_API_KEY" -H 'Content-Type: application/json' \
-d '{"notes":"recruiter called Friday"}'
清空阶段但保留备注与收藏:
curl -X DELETE ".../api/v1/jobs/<slug>/stage" -H "Authorization: Bearer $FREEHIRE_API_KEY"
标记投递(可带 applied_on 指定实际投递日):
curl -X POST ".../api/v1/jobs/<slug>/apply" \
-H "Authorization: Bearer $FREEHIRE_API_KEY" -H 'Content-Type: application/json' \
-d '{"applied_on":"2026-07-27"}'
按行 id 操作(当职位置已被裁剪、没有 slug 可用时):
curl -X PATCH ".../api/v1/me/applications/42" \
-H "Authorization: Bearer $FREEHIRE_API_KEY" -H 'Content-Type: application/json' \
-d '{"stage":"offer"}'
这条路径正是 repository.go 中三个 *Application 方法存在的理由:slug 是“可能消失的那部分”,一旦职位被删除,按 slug 寻址的写入就无从解析,看板上的卡片会变成动不了的状态。仓储层对这三条语句都按 user_id 限定,别人的行与不存在的行返回同一个 ErrApplicationNotFound,处理函数统一渲染成 404。
九、测试与验证证据
规范要求的每一条行为都能在仓库里找到对应验证:
| 验证目标 | 测试位置 |
|---|---|
| 空 body / 未知阶段 → 400 | track_test.go,用无 DB 的桩仓储证明校验发生在触库之前 |
| 无凭证 → 401 | track_test.go |
词表成员全通过、banana/Applied/interviewing 全拒绝 |
track_test.go |
响应含 stage 与 notes 字段 |
track_test.go |
expired 能被接受(词表是唯一闸门) |
track_test.go |
阶段部分更新、applied 播种、preparing 提升、重复投递不回退 |
user_jobs_stage_integration_test.go |
| 清空进度保留备注与收藏;移出看板清空全部流水线标记 | user_jobs_stage_integration_test.go |
集成测试需要真实 Postgres,运行方式是 go test -tags=integration ./internal/platform/db/;而 TestTrackJob_AcceptsExpired 的注释点出了一个设计收益:新增阶段只需改 internal/application/userjob,端点的接受能力自动跟随,任何在别处复制一份校验的实现都会在这个测试上失败。
任务清单 还记录了一条手工端到端验证:用真实 API Key 对 /jobs/<slug>/track 发起 PATCH 得到 200 并带回 stage 与 notes,再确认 GET /me/jobs 的行里两者都在。注意清单里列出的 /me/jobs 对应的是当时的实现;当前仓库的追踪列表读端点是 GET /me/tracking,行结构 myJobResponse 依旧携带 stage 与 notes(me_tracking.go)。
十、边界、取舍与演进提示
为什么不用数据库约束锁死词表。 若用 Postgres enum 或 CHECK,每加一个阶段都要迁移;放在 Go 里则只需改一个切片,未知值自然是干净的 400。代价是词表可能被复制——这正是后来引入 cmd/gen-contracts 生成前端契约所要消除的问题。
为什么允许任意跳转。 个人追踪器的用户会直接跳到 offer,也会把误标的 rejected 改回 interview。规范明确把“只能前进”列为非目标;UI 用分组顺序暗示推荐路径,但服务端不强制。
空字符串与缺省的区别。 notes: "" 会真的把备注清空(COALESCE 只跳过 NULL,不跳过空串);省略 notes 则保持原值。客户端要清空备注,必须显式发送空串。
规范与当前实现的差异,应作为演进理解而非矛盾:
- 路径参数:规范写作
:id,实现统一使用:slug(职位按公开 slug 寻址,处理函数解析为内部 id)。 - 阶段词表:规范为 8 个值,现行为 10 个(新增
preparing与expired)。 - 存储位置:规范设计为
user_jobs上的两列,现行为applications表上的两列,因此“阶段 + 备注”与“对职位的时间戳标记”在存储层分离。 - 列表端点:规范写作
GET /api/v1/me/jobs,现行为GET /me/tracking,并在其基础上扩展了孤儿申请行、沉默状态、跟进时间等看板字段。 - 筛选:
filter=board的定义是“有saved_at、applied_at或stage的行”,也就是说只设阶段、从未投递的记录也会进看板——这正是applied_at必须可空的原因。
可扩展的下游。 任务清单把 freehire-cli 的 stage / note 子命令列为独立仓库的后续工作,其接口就是本端点。任何持有 API Key 的脚本都能驱动同一套流程,因为 Cookie 与 Key 在服务端被识别为同一个用户,没有任何语义差别。
小结
这套实现的核心可以浓缩成四句话:阶段与备注是既有交互行的属性,因此用一个部分更新端点而不是一堆专用端点;词表放在 Go 里以获得演进自由,再用代码生成把前端契约与之锁定;幂等与“只在为空时播种”由 SQL 的 CASE/COALESCE 保证,applied_count 与账本事件必须在同一谓词、同一把行锁下写入;当职位消失时,用 applications 表自身的 id 继续寻址,从而让候选人的记录不随目录裁剪而消失。照着 spec.md 的验收场景逐条对照源码,即可完整复刻或审计这一能力。