Resume Matcher 前端工作流深度解析从 Dashboard 到 PDF 的用户流程、分页规则与状态管理【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher本文基于 Resume Matcher 仓库中 frontend-workflow.md 技术文档结合前端实际源码展开。Resume Matcher 是一个本地运行的 AI 简历构建工具支持 100 LLM 接入前端使用 Next.js App Router 构建。读完本文你将完整掌握它的核心用户流程上传主简历 → 针对职位定制 → 查看/编辑 → 下载 PDF、五个关键页面的职责与路由设计、所见即所得编辑器中的分页与章节管理规则以及 localStorage StatusCache Context 双层状态管理的具体实现可以直接对照源码在自己的项目中复现这套架构。一、核心用户流程一条主线贯穿所有页面文档给出的核心流程是一个五步闭环Dashboard → Upload Master Resume → Tailor for Job → View/Edit → Download PDF这五个步骤在仓库中分别对应真实的路由与组件流程节点路由主要实现文件Dashboard 仪表盘/dashboardapp/(default)/dashboard/page.tsx/dashboard/page.tsx)上传主简历Master Resume/dashboard上的上传对话框components/dashboard/resume-upload-dialog.tsx针对职位定制Tailor/tailorapp/(default)/tailor/page.tsx/tailor/page.tsx)查看 / 编辑View / Edit/resumes/[id]查看、/builder?idid编辑app/(default)/resumes/[id]/page.tsx、components/builder/resume-builder.tsx下载 PDF查看页 / Builder 页的下载按钮lib/api/resume.ts值得注意的是上传主简历在实现上不是一个独立页面Dashboard 会弹出ResumeUploadDialog完成上传随后把返回的resume_id写入localStorage的master_resume_id键见 dashboard/page.tsx/dashboard/page.tsx#L180-L188) 的handleUploadComplete。这也是后面状态管理章节的基础。二、页面详解五个页面的职责、路由与关键交互1. Dashboard/dashboardDashboard 是入口页面文档概括了它的三种呈现状态源码印证得更加细致无主简历No master当localStorage中没有master_resume_id且 LLM 已配置时显示 Initialize Master Resume 交互卡片点击后弹出MasterResumeChoiceDialog让用户选择「上传简历」还是「进入 Resume Wizard 引导创建」见 dashboard/page.tsx/dashboard/page.tsx#L342-L412)LLM 未配置若systemStatus.llm_configured为假则显示跳转/settings的配置警告卡片顶部还会有黄色 warning banner有主简历Has master显示 Master Resume 卡片带pending / processing / ready / failed状态徽标failed/processing 时提供重试与删除重传按钮其下是按网格排列的已定制简历Tailored卡片每个卡片通过哈希取色生成不同配色的 monogram 首字母缩略图创建入口 卡片通过router.push(/tailor)打开 Tailor 页但按钮有门控条件isTailorEnabled Boolean(masterResumeId) processingStatus ready isLlmConfigured即主简历就绪且 LLM 配置好才能创建新定制简历窗口聚焦自动刷新Auto-refresh on window focus源码中注册了window.addEventListener(focus, ...)从其他标签页切回时自动重新拉取简历列表dashboard/page.tsx/dashboard/page.tsx#L172-L178)。此外Dashboard 源码里还包含几处值得一提的工程细节并行加载 JD 摘要时使用内存缓存与请求序号守卫jobSnippetCacheRef避免对同一简历重复请求 JDloadRequestIdRef递增序号防止并发加载时旧请求覆盖新状态dashboard/page.tsx/dashboard/page.tsx#L55-L161)失效处理若fetchResume返回 404会主动清除过期的localStorage键master_resume_iddashboard/page.tsx/dashboard/page.tsx#L86-L95)。2. Resume Viewer/resumes/[id]查看页的核心特征是只读展示 打印级布局250mm 宽度展示源码中预览容器类名为resume-print w-full max-w-[250mm] shadow-sw-lg border-2 border-black bg-whiteresumes/[id]/page.tsx与文档描述的 Read-only display at 250mm width 完全一致操作区ActionsBack返回 Dashboard、Edit跳转/builder?idid、Download PDF、Delete删除。针对主简历还会多出 Enhance Resume弹出 EnrichmentModal 语义化增强入口与标题重命名针对定制简历则多出 Interview Prep 面试准备入口resumes/[id]/page.tsx加载优先级优先渲染processed_resume结构化 JSON若状态为processing/failed或内容为 Markdown 无法解析则展示对应错误卡片并给出「重试处理」「删除并重新开始」的恢复路径resumes/[id]/page.tsx删除双对话框先弹确认框成功后弹 success 对话框确认后才router.push(/dashboard)resumes/[id]/page.tsx对应文档「Delete shows confirmation success dialogs」。3. Tailor/tailorTailor 页是 AI 定制的核心文档只概括了「JD textareamin 50 chars→ Upload JD → Improve → Redirect to viewer」源码中的实际流程远比这丰富前置守卫进入页面即检查localStorage中的master_resume_id没有则直接router.push(/dashboard)tailor/page.tsx/tailor/page.tsx#L82-L89)。JD 输入与校验textarea 最小 300px 高右下角实时显示字符数getGenerateValidationError要求去除首尾空格后长度 ≥ 50 字符否则提示jobDescriptionTooShorttailor/page.tsx/tailor/page.tsx#L165-L171)。完整处理管线runGeneratetailor/page.tsx/tailor/page.tsx#L173-L224)uploadJobDescriptions([description], resumeId)上传 JD返回job_idpreviewImproveResume(resumeId, jobId, selectedPromptId)请求 AI 生成改进预览校验返回结果中是否包含diff_summary与detailed_changes——若有弹出DiffPreviewModal让用户审阅 diff若缺失则弹missingDiffDialog让用户确认是否直接应用用户确认后confirmImproveResume(payload)落库然后跳转到/resumes/{newResumeId}。Prompt 选项页面通过fetchPromptConfig()从后端拉取prompt_options与default_prompt_id未拉取到时回退到nudge / keywords / full三档tailor/page.tsx/tailor/page.tsx#L91-L117)。ATS 评分预览结果若带ats_score页面下方会渲染ATSScoreCard展示 ATS 分数拆解tailor/page.tsx/tailor/page.tsx#L461-L465)。错误分类捕获异常后按关键词将错误归类为 API Key / 速率限制 / 超时等对应不同的 i18n 文案tailor/page.tsx/tailor/page.tsx#L199-L223)。此外还有一个细节确认后的数据通过setImprovedData(confirmed)写入ResumePreviewContext供 Builder 页在「Tailor 流程」优先级下直接读取——这是跨页面传递 AI 结果的桥梁。4. Builder/builderBuilder 是所见即所得编辑器文档概括为「左编辑右预览 Resume/Cover Letter/Outreach 三个 Tab」源码实现则是一个更完整的五 Tab 工作台resume / cover-letter / outreach / interview-prep / jd-matchresume-builder.tsx左面板EditorResume 状态下渲染FormattingControls模板、页边距、间距、字号等排版控制ResumeForm个人资料、Summary、工作经历、教育、项目、附加信息的表单Cover Letter / Outreach 状态下是富文本编辑与保存按钮Interview Prep 是只读的面试准备视图JD Match 是关键词对比分析面板右面板Preview顶部RetroTabs切换 Tab无内容的 Tab 会被禁用Resume 预览使用PaginatedPreview按页渲染Cover Letter / Outreach 有各自实时预览数据优先级Data priority文档说 URL param → Context → localStorage → defaults源码在loadResumeData中按序实现resume-builder.tsx?idresume_id存在时从 APIfetchResume拉取最可靠否则读ResumePreviewContext中 Tailor 流程写入的improvedPreview同时备份到 localStorage否则恢复localStorage中resume_builder_draft自动保存的草稿标记为未保存状态最后回退到buildInitialData(t)的默认空表单。自动保存与未保存提醒handleUpdate每次表单变更都会把数据写入resume_builder_draft页面还注册了beforeunload监听有未保存修改时阻止直接关闭resume-builder.tsx模板设置持久化resume_builder_settings保存模板偏好读取时对margins / spacing / fontSize做深合并避免旧版本缺字段resume-builder.tsxAI 定向重写Resume Tab 提供RegenerateWizard可针对选中的经历、项目或技能条目下发指令由 LLM 重写确认应用后重新拉取简历resume-builder.tsx。5. Settings/settingsSettings 页与文档描述对应但细节远为丰富系统状态缓存顶部 System Status 面板展示 LLM 健康度、数据库连接、简历数、职位数、改进次数、主简历是否已配置六张卡片数据来自 StatusCache Context显示 last fetched 相对时间并支持手动刷新settings/page.tsx/settings/page.tsx#L675-L838)LLM 配置当前支持 8 个 ProviderPROVIDERS数组定义了openai / openai_compatible / anthropic / openrouter / gemini / deepseek / groq / ollamasettings/page.tsx/settings/page.tsx#L70-L79)。每个 Provider 可配置 Model、API Key、API Base URL 与 Reasoning Effortauto / minimal / low / medium / high切换到ollama时自动填入http://localhost:11434切换到openai_compatible时自动填入http://localhost:8080/v1llama.cpp 默认可覆盖为 vLLM / LM Studio 等API Key 按 Provider 独立加密存储新建的 key 先写入独立加密 key 存储updateApiKeys再保存非敏感配置切换 Provider 不会互相覆盖 key页面上可列出所有已保存 key 并单独删除settings/page.tsx/settings/page.tsx#L403-L451)保存前可测试连接handleTestConnection用当前表单值直接调用testLlmConnection返回的 health check 结果会展示测试提示词、模型输出、reasoning 内容与错误码的展开详情settings/page.tsx/settings/page.tsx#L454-L483)。功能开关与自定义 PromptCover Letter、Cold Outreach、Interview Prep 三个功能的启用开关启用后可编辑自定义 Prompt留空表示使用默认模板后端通过*_default字段回传默认文本作为占位符默认 Tailor Prompt可设置nudge / keywords / full中的默认档位语言设置UI 语言与内容语言分别可选en / es / fr / ja / pt-BR / zhDanger Zone一键清除所有 API Key、重置数据库重置后会同时清理master_resume_id、resume_builder_draft、resume_builder_settings等 localStorage 键settings/page.tsx/settings/page.tsx#L589-L619)。三、分页规则PaginatedPreview 的算法实现文档列出了四条分页规则源码usePaginationHookcomponents/preview/use-pagination.ts正是这些规则的落地实现文档规则源码实现Sections CAN span pages章节允许跨页测量容器只查询.resume-item, [data-no-break]作为不可拆分的原子单位特意不包含.resume-section见 use-pagination.ts 注释Individual items stay together单项不拆分.resume-item单个职位、项目、教育条目与[data-no-break]显式标记的元素整体移动不跨页截断Pages ≥50% full before break页满 50% 才允许断页分页计算中若某 item 跨页需满足所在页已填充到阈值附近才会被挪到下一页避免大量留白相关判断位于 use-pagination.ts 后续的shouldBreakBefore逻辑Headers never orphaned标题不孤立关键实现.resume-section-title与其所属.resume-section内第一个内容元素绑定若标题落在页尾而内容在下一页则把标题一并推到下一页use-pagination.ts算法的其他工程细节测量前等待document.fonts.ready确保字体加载完成再计算分页计算做了 150ms 防抖debounceMs每页高度由getContentAreaPx(pageSize, margins)依据纸张A4 / US Letter与页边距换算所有偏移以像素px记录最终由PaginatedPreview渲染为视觉分页。这套算法与打印用模板app/print/resumes/[id]/page.tsx共用数据源因此「编辑器里看到的分页」与「打印出的 PDF」保持一致。四、状态管理localStorage 与 StatusCache Context 的双层设计localStorage 键位一览文档中的表对应了源码中的实际键localStorage Key用途写入点源码master_resume_id主简历 UUID上传完成后localStorage.setItem(master_resume_id, resumeId)dashboard/page.tsx/dashboard/page.tsx#L181)resume_builder_draft表单自动保存草稿每次编辑handleUpdate写入resume-builder.tsxTailor 结果备份也会写入resume_builder_settings模板/排版偏好templateSettings变化时写入resume-builder.tsx另外源码中还存在文档未列出的两个语言键resume_matcher_content_language与resume_matcher_ui_language在「重置数据库」时会被一并清除settings/page.tsx/settings/page.tsx#L596-L600)。StatusCache Contextlib/context/status-cache.tsx这是全局系统状态LLM 健康、数据库统计、master resume 是否存在的缓存层初始拉取Provider 挂载时立即调用refreshStatus()由fetchSystemStatus()从后端/status类接口获取全量状态status-cache.tsx30 分钟自动刷新常量LLM_HEALTH_CHECK_INTERVAL 30 * 60 * 1000setInterval周期调用refreshLlmHealth()静默刷新失败时保留旧数据status-cache.tsx乐观计数器Optimistic counter updates暴露incrementResumes / decrementResumes / incrementJobs / incrementImprovements / setHasMasterResume在「上传成功但后端状态尚未返回」的空窗期内先本地增减计数decrementResumes还做了Math.max(0, ...)下限保护status-cache.tsx使用方Dashboard 用它驱动 LLM 配置警告与 Tailor 按钮门控Tailor 页在上传 JD、确认改进后分别调用incrementJobs / incrementImprovements / incrementResumes保持计数一致Settings 页消费lastFetched显示刷新时间并调用refreshStatus手动刷新过期判断Context 还导出一个useIsStatusStale(thresholdMs)Hook默认 5 分钟阈值STATUS_STALE_THRESHOLD每分钟检查一次数据是否过期status-cache.tsx。另外还有一个文档提到但未展开的 ContextResumePreviewContextcomponents/common/resume_previewer_context.tsx它是 Tailor 页把 AI 改进结果含 resume_preview、cover_letter、outreach_message、interview_prep跨页传给 Builder 的「会话级」状态通道与持久化的 localStorage 互补。五、删除流程完整链路与边界处理文档列出的四步删除流程在源码中均有对应实现以 Viewer 页 resumes/[id]/page.tsx 为准点击 Delete → 确认对话框ConfirmDialog确认框标题与描述根据是否主简历区分文案variantdangerAPIDELETE /resumes/{id}调用deleteResume(resumeId)底层为apiDelete见 lib/api/resume.ts若为主简历则清除 localStorageisMasterResume由localStorage.getItem(master_resume_id) resumeId判定命中时执行localStorage.removeItem(master_resume_id)并调用setHasMasterResume(false)同步 Context成功对话框 → 跳转 DashboardshowDeleteSuccessDialog弹出成功确认框用户确认后router.push(/dashboard)。源码中还处理了若干边界情况删除失败会弹失败对话框并保留页面Dashboard 上的「删除并重新上传」流程confirmDeleteAndReupload在删除后直接打开上传对话框并刷新列表Viewer 的错误分支处理失败状态也挂载了同一组删除对话框保证「Delete Start Over」恢复路径在失败态可用resumes/[id]/page.tsx。六、章节管理Section Management与 API Client章节管理操作文档用表格总结了五个章节操作对应 Builder 中的ResumeForm/DraggableSectionWrapper等组件components/builder/resume-form.tsx操作结果说明Rename点击铅笔图标章节标题就地编辑回车确认、Esc 取消Reorder上/下箭头通过draggable-section-wrapper.tsx上下移动章节顺序Hide眼睛图标隐藏的章节不再渲染到预览但表单数据保留仍可编辑Delete隐藏默认章节、删除自定义章节默认内置章节如 Summary只能隐藏不能彻底删除自定义章节直接移除AddAdd Section 按钮通过add-section-dialog.tsx添加自定义章节API Client 一览文档给出的 TypeScript 片段与源码保持一致。前端 API 层位于 lib/api/resume.ts 与 lib/api/config.ts// Resume 操作lib/api/resume.ts fetchResume, fetchResumeList, updateResume, deleteResume, uploadJobDescriptions, previewImproveResume, confirmImproveResume, downloadResumePdf, getResumePdfUrl, retryProcessing, renameResume, fetchJobDescription, updateCoverLetter, updateOutreachMessage, generateCoverLetter, generateOutreachMessage, generateInterviewPrep // Config 操作lib/api/config.ts fetchSystemStatus, fetchLlmConfig, updateLlmConfig, testLlmConnection, fetchFeatureConfig, updateFeatureConfig, fetchPromptConfig, updatePromptConfig, fetchFeaturePrompts, updateFeaturePrompts, fetchApiKeyStatus, updateApiKeys, deleteApiKey, clearAllApiKeys, resetDatabase底层由 lib/api/client.ts 提供apiFetch / apiPost / apiPatch / apiDelete封装统一处理API_BASE、默认超时DEFAULT_TIMEOUT_MS、JSON 序列化与错误抛出并导出API_BASE/API_URL供页面展示后端地址。所有返回结构统一包裹在request_id data响应壳中processing_status的取值域为pending | processing | ready | failed见 lib/api/resume.ts 的ResumeResponse类型前端各页据此渲染加载、重试或失败 UI。七、从文档到架构的延伸阅读如果想继续深入建议按以下顺序阅读仓库内的关联资料前端整体架构docs/agent/architecture/frontend-architecture.md前端 API 契约docs/agent/apis/front-end-apis.md、docs/agent/apis/api-flow-maps.md后端 API 对应实现apps/backend/app/routers/resumes.py、apps/backend/app/routers/config.pyTailor 前后端调用链docs/agent/features/jd-match.md、docs/superpowers/plans/2026-05-06-resume-tailor-verifier-loop.mdPDF 模板与分页设计docs/agent/design/print-pdf-design-spec.md、docs/agent/design/template-system.mdi18n 准备docs/agent/features/i18n-preparation.md前端相关测试用例apps/frontend/tests覆盖了分页、关键词匹配、富文本编辑器、Tailor 确认等关键行为例如 diff-preview-modal.test.tsx 验证 Tailor 的 diff 审阅交互、tracker-reorder.test.ts 验证拖拽排序可作为理解各模块行为边界的补充依据。运行说明Resume Matcher 需要分别启动后端FastAPI见 SETUP.md与前端Next.js见 apps/frontend/package.json。前端开发启动命令为npm run dev在apps/frontend目录下首次使用需在/settings配置 LLM Provider 与 API Key随后即可按本文所述流程完成「上传主简历 → 定制 → 编辑 → 下载 PDF」的完整闭环。【免费下载链接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.项目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考