Resume Matcher 前端工作流深度解析從 Dashboard 到 PDF 的用戶流程、分頁規(guī)則與狀態(tài)管理【免費(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher本文基于 Resume Matcher 倉庫中 frontend-workflow.md 技術(shù)文檔結(jié)合前端實(shí)際源碼展開。Resume Matcher 是一個(gè)本地運(yùn)行的 AI 簡歷構(gòu)建工具支持 100 LLM 接入前端使用 Next.js App Router 構(gòu)建。讀完本文你將完整掌握它的核心用戶流程上傳主簡歷 → 針對職位定制 → 查看/編輯 → 下載 PDF、五個(gè)關(guān)鍵頁面的職責(zé)與路由設(shè)計(jì)、所見即所得編輯器中的分頁與章節(jié)管理規(guī)則以及 localStorage StatusCache Context 雙層狀態(tài)管理的具體實(shí)現(xiàn)可以直接對照源碼在自己的項(xiàng)目中復(fù)現(xiàn)這套架構(gòu)。一、核心用戶流程一條主線貫穿所有頁面文檔給出的核心流程是一個(gè)五步閉環(huán)Dashboard → Upload Master Resume → Tailor for Job → View/Edit → Download PDF這五個(gè)步驟在倉庫中分別對應(yīng)真實(shí)的路由與組件流程節(jié)點(diǎn)路由主要實(shí)現(xiàn)文件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值得注意的是上傳主簡歷在實(shí)現(xiàn)上不是一個(gè)獨(dú)立頁面Dashboard 會彈出ResumeUploadDialog完成上傳隨后把返回的resume_id寫入localStorage的master_resume_id鍵見 dashboard/page.tsx/dashboard/page.tsx#L180-L188) 的handleUploadComplete。這也是后面狀態(tài)管理章節(jié)的基礎(chǔ)。二、頁面詳解五個(gè)頁面的職責(zé)、路由與關(guān)鍵交互1. Dashboard/dashboardDashboard 是入口頁面文檔概括了它的三種呈現(xiàn)狀態(tài)源碼印證得更加細(xì)致無主簡歷No master當(dāng)localStorage中沒有master_resume_id且 LLM 已配置時(shí)顯示 Initialize Master Resume 交互卡片點(diǎn)擊后彈出MasterResumeChoiceDialog讓用戶選擇「上傳簡歷」還是「進(jìn)入 Resume Wizard 引導(dǎo)創(chuàng)建」見 dashboard/page.tsx/dashboard/page.tsx#L342-L412)LLM 未配置若systemStatus.llm_configured為假則顯示跳轉(zhuǎn)/settings的配置警告卡片頂部還會有黃色 warning banner有主簡歷Has master顯示 Master Resume 卡片帶pending / processing / ready / failed狀態(tài)徽標(biāo)failed/processing 時(shí)提供重試與刪除重傳按鈕其下是按網(wǎng)格排列的已定制簡歷Tailored卡片每個(gè)卡片通過哈希取色生成不同配色的 monogram 首字母縮略圖創(chuàng)建入口 卡片通過router.push(/tailor)打開 Tailor 頁但按鈕有門控條件isTailorEnabled Boolean(masterResumeId) processingStatus ready isLlmConfigured即主簡歷就緒且 LLM 配置好才能創(chuàng)建新定制簡歷窗口聚焦自動刷新Auto-refresh on window focus源碼中注冊了window.addEventListener(focus, ...)從其他標(biāo)簽頁切回時(shí)自動重新拉取簡歷列表dashboard/page.tsx/dashboard/page.tsx#L172-L178)。此外Dashboard 源碼里還包含幾處值得一提的工程細(xì)節(jié)并行加載 JD 摘要時(shí)使用內(nèi)存緩存與請求序號守衛(wèi)jobSnippetCacheRef避免對同一簡歷重復(fù)請求 JDloadRequestIdRef遞增序號防止并發(fā)加載時(shí)舊請求覆蓋新狀態(tài)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 寬度展示源碼中預(yù)覽容器類名為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 完全一致操作區(qū)ActionsBack返回 Dashboard、Edit跳轉(zhuǎn)/builder?idid、Download PDF、Delete刪除。針對主簡歷還會多出 Enhance Resume彈出 EnrichmentModal 語義化增強(qiáng)入口與標(biāo)題重命名針對定制簡歷則多出 Interview Prep 面試準(zhǔn)備入口resumes/[id]/page.tsx加載優(yōu)先級優(yōu)先渲染processed_resume結(jié)構(gòu)化 JSON若狀態(tài)為processing/failed或內(nèi)容為 Markdown 無法解析則展示對應(yīng)錯(cuò)誤卡片并給出「重試處理」「刪除并重新開始」的恢復(fù)路徑resumes/[id]/page.tsx刪除雙對話框先彈確認(rèn)框成功后彈 success 對話框確認(rèn)后才router.push(/dashboard)resumes/[id]/page.tsx對應(yīng)文檔「Delete shows confirmation success dialogs」。3. Tailor/tailorTailor 頁是 AI 定制的核心文檔只概括了「JD textareamin 50 chars→ Upload JD → Improve → Redirect to viewer」源碼中的實(shí)際流程遠(yuǎn)比這豐富前置守衛(wèi)進(jìn)入頁面即檢查localStorage中的master_resume_id沒有則直接router.push(/dashboard)tailor/page.tsx/tailor/page.tsx#L82-L89)。JD 輸入與校驗(yàn)textarea 最小 300px 高右下角實(shí)時(shí)顯示字符數(shù)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 生成改進(jìn)預(yù)覽校驗(yàn)返回結(jié)果中是否包含diff_summary與detailed_changes——若有彈出DiffPreviewModal讓用戶審閱 diff若缺失則彈missingDiffDialog讓用戶確認(rèn)是否直接應(yīng)用用戶確認(rèn)后confirmImproveResume(payload)落庫然后跳轉(zhuǎn)到/resumes/{newResumeId}。Prompt 選項(xiàng)頁面通過fetchPromptConfig()從后端拉取prompt_options與default_prompt_id未拉取到時(shí)回退到nudge / keywords / full三檔tailor/page.tsx/tailor/page.tsx#L91-L117)。ATS 評分預(yù)覽結(jié)果若帶ats_score頁面下方會渲染ATSScoreCard展示 ATS 分?jǐn)?shù)拆解tailor/page.tsx/tailor/page.tsx#L461-L465)。錯(cuò)誤分類捕獲異常后按關(guān)鍵詞將錯(cuò)誤歸類為 API Key / 速率限制 / 超時(shí)等對應(yīng)不同的 i18n 文案tailor/page.tsx/tailor/page.tsx#L199-L223)。此外還有一個(gè)細(xì)節(jié)確認(rèn)后的數(shù)據(jù)通過setImprovedData(confirmed)寫入ResumePreviewContext供 Builder 頁在「Tailor 流程」優(yōu)先級下直接讀取——這是跨頁面?zhèn)鬟f AI 結(jié)果的橋梁。4. Builder/builderBuilder 是所見即所得編輯器文檔概括為「左編輯右預(yù)覽 Resume/Cover Letter/Outreach 三個(gè) Tab」源碼實(shí)現(xiàn)則是一個(gè)更完整的五 Tab 工作臺resume / cover-letter / outreach / interview-prep / jd-matchresume-builder.tsx左面板EditorResume 狀態(tài)下渲染FormattingControls模板、頁邊距、間距、字號等排版控制ResumeForm個(gè)人資料、Summary、工作經(jīng)歷、教育、項(xiàng)目、附加信息的表單Cover Letter / Outreach 狀態(tài)下是富文本編輯與保存按鈕Interview Prep 是只讀的面試準(zhǔn)備視圖JD Match 是關(guān)鍵詞對比分析面板右面板Preview頂部RetroTabs切換 Tab無內(nèi)容的 Tab 會被禁用Resume 預(yù)覽使用PaginatedPreview按頁渲染Cover Letter / Outreach 有各自實(shí)時(shí)預(yù)覽數(shù)據(jù)優(yōu)先級Data priority文檔說 URL param → Context → localStorage → defaults源碼在loadResumeData中按序?qū)崿F(xiàn)resume-builder.tsx?idresume_id存在時(shí)從 APIfetchResume拉取最可靠否則讀ResumePreviewContext中 Tailor 流程寫入的improvedPreview同時(shí)備份到 localStorage否則恢復(fù)localStorage中resume_builder_draft自動保存的草稿標(biāo)記為未保存狀態(tài)最后回退到buildInitialData(t)的默認(rèn)空表單。自動保存與未保存提醒handleUpdate每次表單變更都會把數(shù)據(jù)寫入resume_builder_draft頁面還注冊了beforeunload監(jiān)聽有未保存修改時(shí)阻止直接關(guān)閉resume-builder.tsx模板設(shè)置持久化resume_builder_settings保存模板偏好讀取時(shí)對margins / spacing / fontSize做深合并避免舊版本缺字段resume-builder.tsxAI 定向重寫Resume Tab 提供RegenerateWizard可針對選中的經(jīng)歷、項(xiàng)目或技能條目下發(fā)指令由 LLM 重寫確認(rèn)應(yīng)用后重新拉取簡歷resume-builder.tsx。5. Settings/settingsSettings 頁與文檔描述對應(yīng)但細(xì)節(jié)遠(yuǎn)為豐富系統(tǒng)狀態(tài)緩存頂部 System Status 面板展示 LLM 健康度、數(shù)據(jù)庫連接、簡歷數(shù)、職位數(shù)、改進(jìn)次數(shù)、主簡歷是否已配置六張卡片數(shù)據(jù)來自 StatusCache Context顯示 last fetched 相對時(shí)間并支持手動刷新settings/page.tsx/settings/page.tsx#L675-L838)LLM 配置當(dāng)前支持 8 個(gè) ProviderPROVIDERS數(shù)組定義了openai / openai_compatible / anthropic / openrouter / gemini / deepseek / groq / ollamasettings/page.tsx/settings/page.tsx#L70-L79)。每個(gè) Provider 可配置 Model、API Key、API Base URL 與 Reasoning Effortauto / minimal / low / medium / high切換到ollama時(shí)自動填入http://localhost:11434切換到openai_compatible時(shí)自動填入http://localhost:8080/v1llama.cpp 默認(rèn)可覆蓋為 vLLM / LM Studio 等API Key 按 Provider 獨(dú)立加密存儲新建的 key 先寫入獨(dú)立加密 key 存儲updateApiKeys再保存非敏感配置切換 Provider 不會互相覆蓋 key頁面上可列出所有已保存 key 并單獨(dú)刪除settings/page.tsx/settings/page.tsx#L403-L451)保存前可測試連接handleTestConnection用當(dāng)前表單值直接調(diào)用testLlmConnection返回的 health check 結(jié)果會展示測試提示詞、模型輸出、reasoning 內(nèi)容與錯(cuò)誤碼的展開詳情settings/page.tsx/settings/page.tsx#L454-L483)。功能開關(guān)與自定義 PromptCover Letter、Cold Outreach、Interview Prep 三個(gè)功能的啟用開關(guān)啟用后可編輯自定義 Prompt留空表示使用默認(rèn)模板后端通過*_default字段回傳默認(rèn)文本作為占位符默認(rèn) Tailor Prompt可設(shè)置nudge / keywords / full中的默認(rèn)檔位語言設(shè)置UI 語言與內(nèi)容語言分別可選en / es / fr / ja / pt-BR / zhDanger Zone一鍵清除所有 API Key、重置數(shù)據(jù)庫重置后會同時(shí)清理master_resume_id、resume_builder_draft、resume_builder_settings等 localStorage 鍵settings/page.tsx/settings/page.tsx#L589-L619)。三、分頁規(guī)則PaginatedPreview 的算法實(shí)現(xiàn)文檔列出了四條分頁規(guī)則源碼usePaginationHookcomponents/preview/use-pagination.ts正是這些規(guī)則的落地實(shí)現(xiàn)文檔規(guī)則源碼實(shí)現(xiàn)Sections CAN span pages章節(jié)允許跨頁測量容器只查詢.resume-item, [data-no-break]作為不可拆分的原子單位特意不包含.resume-section見 use-pagination.ts 注釋Individual items stay together單項(xiàng)不拆分.resume-item單個(gè)職位、項(xiàng)目、教育條目與[data-no-break]顯式標(biāo)記的元素整體移動不跨頁截?cái)郟ages ≥50% full before break頁滿 50% 才允許斷頁分頁計(jì)算中若某 item 跨頁需滿足所在頁已填充到閾值附近才會被挪到下一頁避免大量留白相關(guān)判斷位于 use-pagination.ts 后續(xù)的shouldBreakBefore邏輯Headers never orphaned標(biāo)題不孤立關(guān)鍵實(shí)現(xiàn).resume-section-title與其所屬.resume-section內(nèi)第一個(gè)內(nèi)容元素綁定若標(biāo)題落在頁尾而內(nèi)容在下一頁則把標(biāo)題一并推到下一頁use-pagination.ts算法的其他工程細(xì)節(jié)測量前等待document.fonts.ready確保字體加載完成再計(jì)算分頁計(jì)算做了 150ms 防抖debounceMs每頁高度由getContentAreaPx(pageSize, margins)依據(jù)紙張A4 / US Letter與頁邊距換算所有偏移以像素px記錄最終由PaginatedPreview渲染為視覺分頁。這套算法與打印用模板app/print/resumes/[id]/page.tsx共用數(shù)據(jù)源因此「編輯器里看到的分頁」與「打印出的 PDF」保持一致。四、狀態(tài)管理localStorage 與 StatusCache Context 的雙層設(shè)計(jì)localStorage 鍵位一覽文檔中的表對應(yīng)了源碼中的實(shí)際鍵localStorage Key用途寫入點(diǎn)源碼master_resume_id主簡歷 UUID上傳完成后localStorage.setItem(master_resume_id, resumeId)dashboard/page.tsx/dashboard/page.tsx#L181)resume_builder_draft表單自動保存草稿每次編輯handleUpdate寫入resume-builder.tsxTailor 結(jié)果備份也會寫入resume_builder_settings模板/排版偏好templateSettings變化時(shí)寫入resume-builder.tsx另外源碼中還存在文檔未列出的兩個(gè)語言鍵resume_matcher_content_language與resume_matcher_ui_language在「重置數(shù)據(jù)庫」時(shí)會被一并清除settings/page.tsx/settings/page.tsx#L596-L600)。StatusCache Contextlib/context/status-cache.tsx這是全局系統(tǒng)狀態(tài)LLM 健康、數(shù)據(jù)庫統(tǒng)計(jì)、master resume 是否存在的緩存層初始拉取Provider 掛載時(shí)立即調(diào)用refreshStatus()由fetchSystemStatus()從后端/status類接口獲取全量狀態(tài)status-cache.tsx30 分鐘自動刷新常量LLM_HEALTH_CHECK_INTERVAL 30 * 60 * 1000setInterval周期調(diào)用refreshLlmHealth()靜默刷新失敗時(shí)保留舊數(shù)據(jù)status-cache.tsx樂觀計(jì)數(shù)器Optimistic counter updates暴露incrementResumes / decrementResumes / incrementJobs / incrementImprovements / setHasMasterResume在「上傳成功但后端狀態(tài)尚未返回」的空窗期內(nèi)先本地增減計(jì)數(shù)decrementResumes還做了Math.max(0, ...)下限保護(hù)status-cache.tsx使用方Dashboard 用它驅(qū)動 LLM 配置警告與 Tailor 按鈕門控Tailor 頁在上傳 JD、確認(rèn)改進(jìn)后分別調(diào)用incrementJobs / incrementImprovements / incrementResumes保持計(jì)數(shù)一致Settings 頁消費(fèi)lastFetched顯示刷新時(shí)間并調(diào)用refreshStatus手動刷新過期判斷Context 還導(dǎo)出一個(gè)useIsStatusStale(thresholdMs)Hook默認(rèn) 5 分鐘閾值STATUS_STALE_THRESHOLD每分鐘檢查一次數(shù)據(jù)是否過期status-cache.tsx。另外還有一個(gè)文檔提到但未展開的 ContextResumePreviewContextcomponents/common/resume_previewer_context.tsx它是 Tailor 頁把 AI 改進(jìn)結(jié)果含 resume_preview、cover_letter、outreach_message、interview_prep跨頁傳給 Builder 的「會話級」?fàn)顟B(tài)通道與持久化的 localStorage 互補(bǔ)。五、刪除流程完整鏈路與邊界處理文檔列出的四步刪除流程在源碼中均有對應(yīng)實(shí)現(xiàn)以 Viewer 頁 resumes/[id]/page.tsx 為準(zhǔn)點(diǎn)擊 Delete → 確認(rèn)對話框ConfirmDialog確認(rèn)框標(biāo)題與描述根據(jù)是否主簡歷區(qū)分文案variantdangerAPIDELETE /resumes/{id}調(diào)用deleteResume(resumeId)底層為apiDelete見 lib/api/resume.ts若為主簡歷則清除 localStorageisMasterResume由localStorage.getItem(master_resume_id) resumeId判定命中時(shí)執(zhí)行l(wèi)ocalStorage.removeItem(master_resume_id)并調(diào)用setHasMasterResume(false)同步 Context成功對話框 → 跳轉(zhuǎn) DashboardshowDeleteSuccessDialog彈出成功確認(rèn)框用戶確認(rèn)后router.push(/dashboard)。源碼中還處理了若干邊界情況刪除失敗會彈失敗對話框并保留頁面Dashboard 上的「刪除并重新上傳」流程confirmDeleteAndReupload在刪除后直接打開上傳對話框并刷新列表Viewer 的錯(cuò)誤分支處理失敗狀態(tài)也掛載了同一組刪除對話框保證「Delete Start Over」恢復(fù)路徑在失敗態(tài)可用resumes/[id]/page.tsx。六、章節(jié)管理Section Management與 API Client章節(jié)管理操作文檔用表格總結(jié)了五個(gè)章節(jié)操作對應(yīng) Builder 中的ResumeForm/DraggableSectionWrapper等組件components/builder/resume-form.tsx操作結(jié)果說明Rename點(diǎn)擊鉛筆圖標(biāo)章節(jié)標(biāo)題就地編輯回車確認(rèn)、Esc 取消Reorder上/下箭頭通過draggable-section-wrapper.tsx上下移動章節(jié)順序Hide眼睛圖標(biāo)隱藏的章節(jié)不再渲染到預(yù)覽但表單數(shù)據(jù)保留仍可編輯Delete隱藏默認(rèn)章節(jié)、刪除自定義章節(jié)默認(rèn)內(nèi)置章節(jié)如 Summary只能隱藏不能徹底刪除自定義章節(jié)直接移除AddAdd Section 按鈕通過add-section-dialog.tsx添加自定義章節(jié)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封裝統(tǒng)一處理API_BASE、默認(rèn)超時(shí)DEFAULT_TIMEOUT_MS、JSON 序列化與錯(cuò)誤拋出并導(dǎo)出API_BASE/API_URL供頁面展示后端地址。所有返回結(jié)構(gòu)統(tǒng)一包裹在request_id data響應(yīng)殼中processing_status的取值域?yàn)閜ending | processing | ready | failed見 lib/api/resume.ts 的ResumeResponse類型前端各頁據(jù)此渲染加載、重試或失敗 UI。七、從文檔到架構(gòu)的延伸閱讀如果想繼續(xù)深入建議按以下順序閱讀倉庫內(nèi)的關(guān)聯(lián)資料前端整體架構(gòu)docs/agent/architecture/frontend-architecture.md前端 API 契約docs/agent/apis/front-end-apis.md、docs/agent/apis/api-flow-maps.md后端 API 對應(yīng)實(shí)現(xiàn)apps/backend/app/routers/resumes.py、apps/backend/app/routers/config.pyTailor 前后端調(diào)用鏈docs/agent/features/jd-match.md、docs/superpowers/plans/2026-05-06-resume-tailor-verifier-loop.mdPDF 模板與分頁設(shè)計(jì)docs/agent/design/print-pdf-design-spec.md、docs/agent/design/template-system.mdi18n 準(zhǔn)備docs/agent/features/i18n-preparation.md前端相關(guān)測試用例apps/frontend/tests覆蓋了分頁、關(guān)鍵詞匹配、富文本編輯器、Tailor 確認(rèn)等關(guān)鍵行為例如 diff-preview-modal.test.tsx 驗(yàn)證 Tailor 的 diff 審閱交互、tracker-reorder.test.ts 驗(yàn)證拖拽排序可作為理解各模塊行為邊界的補(bǔ)充依據(jù)。運(yùn)行說明Resume Matcher 需要分別啟動后端FastAPI見 SETUP.md與前端Next.js見 apps/frontend/package.json。前端開發(fā)啟動命令為npm run dev在apps/frontend目錄下首次使用需在/settings配置 LLM Provider 與 API Key隨后即可按本文所述流程完成「上傳主簡歷 → 定制 → 編輯 → 下載 PDF」的完整閉環(huán)?！久赓M(fèi)下載鏈接】Resume-MatcherThe #1 AI Harness for Building Resumes, PDFs, Cover Letters more, locally with 100 LLMs support.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/Resume-Matcher創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考