freehire 应用阶段与备注追踪:PATCH track 接口、受控阶段词表与 My Jobs 看板实现解析

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

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。其它任何已有阶段在重复投递时都原样保留。

语句还处理了两件与计数器相关的事:

  • prior CTE 读取 upsert 之前的 applied_at,只有从未设置变为设置时,才在同一语句内 applied_count = applied_count + 1;
  • event CTE 在同一谓词下写入 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 已设置则以人性化徽章展示;提供包含完整词表的控件用于切换阶段;备注支持行内编辑。未登录用户不应看到这些控件。

前端实现对应三处:

  1. API 封装。web/src/lib/api.ts 提供 trackJob(slug, {stage?, notes?}),走 PATCH /api/v1/jobs/${slug}/track;同一段还提供按行 id 寻址的 trackApplication(id, patch)、clearApplicationStage(id)、untrackApplication(id)。
  2. 标签与分组。web/src/lib/stages.ts 不再自己维护词表,而是从生成的 STAGE_GROUPS / STAGE_LABELS 读取:humanizeStage 给出人类可读标签,未知值退化为首字母大写而不会崩;groupedStages() 返回按流水线顺序分组的选项,供下拉框渲染成带标题的选项组。
  3. 编译期一致性。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 的验收场景逐条对照源码,即可完整复刻或审计这一能力。

登录后查看全文
freehire