設計：模板、排版與頁邊距的復用與分層約束)
【免費下載鏈接】freehirefreehire — the open-source search engine for job seekers項目地址https://gitcode.com/GitHub_Trending/fr/freehire點擊查看免費下載本文圍繞 freehire 倉庫中的add-cv-appearance-defaults設計文檔解析一項典型的多層改動如何在不復制校驗邏輯、不侵入既有 CV 文檔路徑的前提下為每個用戶保存一份“新 CV 默認外觀”。文章完整繼承原設計文檔的上下文、目標與非目標、七項關鍵決策、風險與遷移計劃并結(jié)合倉庫中已經(jīng)落地的遷移 SQL、Go 領域代碼、HTTP 處理器與 Svelte 前端組件說明每個決策在代碼中的真實形態(tài)與驗證方式。讀者讀完后可以掌握分層架構(gòu)下“用戶級偏好”應放在哪一層、為什么把默認值寫在創(chuàng)建入口而非 sanitizer、以及如何把自持久化組件改造成受控組件而不破壞原有調(diào)用方。背景一個只在單份 CV 里存在的設置設計文檔的Context一節(jié)先界定了既有狀態(tài)。CV 的外觀由三部分組成并且這三部分都存放在每一條cvs行上template_id模板標識Style{font_family, font_size, line_height}字體族、字號pt、行高emMargins{top, right, bottom, left}四邊頁邊距英寸。這三者由internal/candidate/cv負責校驗與鉗制Style.sanitized()、Margins.sanitized()以及template.go中的模板注冊表。同時設計文檔明確了一條重要的所有權(quán)規(guī)則internal/candidate/cvedit是已有CV 文檔的唯一寫入方。問題在proposal.md變更提案中被直白地描述外觀只能在 tailoring 工作區(qū)內(nèi)逐份 CV 編輯每份新 CV 都從同一組硬編碼值開始——classic-ats模板、0.5 英寸頁邊距、模板自帶排版。已經(jīng)調(diào)好一次外觀的候選人每新建一份基礎 CV 都需要重來一遍系統(tǒng)里沒有地方表達“我始終想讓我的 CV 長這樣”。三個硬編碼的系統(tǒng)默認種子點設計文檔指出當前恰好有三個調(diào)用點會用硬編碼系統(tǒng)默認值為新的基礎CVjob_id IS NULL播種調(diào)用點設計文檔標注位置當前倉庫實現(xiàn)Store.Tailor的簡歷播種分支internal/candidate/cv/store.go:314store.go從簡歷重置/重建cv_reset.go:132cv_reseed.go文件已更名CreateCV處理器internal/api/handler/cv.go約 356-390 行cv.go而 tailoring綁定職位的副本始終從基礎 CV 繼承template_id/Style/Margins通過CreateTailored與Align因此它們不需要任何改動。這一點決定了整個改動的邊界只需處理“基礎 CV 誕生的一瞬間”。目標與非目標先劃清不可越界的范圍設計文檔用 Goals / Non-Goals 把改動鎖在一個很小的面上。Goals一條持久的、按用戶存儲的外觀默認值記錄并使用與 CV 文檔完全相同的規(guī)則校驗在三個既有的基礎 CV 創(chuàng)建調(diào)用點上非侵入地應用它原樣復用StyleSettings/MarginSettings把TemplateGallery泛化而不是分叉。Non-Goals明確不做不把默認值重新應用到已存在/已打開的 CV即 tailoring 工作區(qū)里不做“重置為我的默認值”不新增頂層/my/*導航入口不改變 tailoredjob-boundCV 的創(chuàng)建流程。非目標并非隨手排除而是這個設計的“低成本”來源一旦允許回寫已有 CV“保存默認值”就會變成一次批量文檔遷移需要處理版本歷史、并發(fā)編輯與用戶預期。關鍵決策逐條解析決策一數(shù)據(jù)放在internal/candidate/cv而不是internal/identity/userprofile這是整份文檔中最有架構(gòu)價值的一條。userprofile已經(jīng)持有一個類似的 per-user 偏好LocationPreferences是“用戶級默認值”最接近的既有范式。按直覺外觀默認值也應放進userprofile。但倉庫的分層規(guī)則internal/platform/arch/layering禁止identity第 3 層導入candidate第 4 層的類型。而Style、Margins、模板注冊表與字體注冊表都住在internal/candidate/cv。這意味著放在identity里就必須復制一份校驗與注冊表邏輯設計文檔進一步借用倉庫自身normalize包對公司法律形式詞表的告警來說明后果副本一定會漂移。選擇同包新文件appearance_defaults.go后SetAppearanceDefaults調(diào)用的就是 CV 文檔路徑已經(jīng)在用的Style.sanitized()、Margins.sanitized()、ResolveTemplate/TemplateIDs()——不存在第二份實現(xiàn)。這是“依賴方向決定數(shù)據(jù)歸屬”而非“業(yè)務語義決定數(shù)據(jù)歸屬”的典型案例。決策二新增一張表而不是給users加列cv_appearance_defaults鏡像了cvs表的template_id/style jsonb/margins jsonb形狀主鍵是user_id但沒有title與job_id。設計文檔給出三點理由可選、可刪除——用戶沒保存過就沒有行與users行自身的遷移歷史解耦與cvs結(jié)構(gòu)一致因此同一套 jsonb 編解碼/清洗輔助函數(shù)可以直接復用。落地的遷移見migrations/0128_cv_appearance_defaults.sqlCREATE TABLE IF NOT EXISTS cv_appearance_defaults ( user_id bigint PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE, template_id text NOT NULL, style jsonb NOT NULL, margins jsonb NOT NULL, updated_at timestamptz NOT NULL DEFAULT now() );ON DELETE CASCADE讓刪號時這行自然消失正好對應設計文檔所說的“optional and deletable”。查詢側(cè)使用 upsert語義是“整份替換”而非字段級 patch見internal/platform/db/queries/cv_appearance_defaults.sqlINSERT INTO cv_appearance_defaults (user_id, template_id, style, margins, updated_at) VALUES ($1, $2, $3, $4, now()) ON CONFLICT (user_id) DO UPDATE SET template_id EXCLUDED.template_id, style EXCLUDED.style, margins EXCLUDED.margins, updated_at now() RETURNING user_id, template_id, style, margins, updated_at;由于一用戶一行ON CONFLICT的更新分支就等價于“把這一行整體換成新的完整集合”無需在應用層區(qū)分首次寫入與覆蓋寫入。決策三GET 永遠返回具體形狀設計文檔規(guī)定沒有保存過默認值時GetAppearanceDefaults返回(系統(tǒng)默認值, false, nil)而不是零值或缺失值。這樣設置界面永遠有內(nèi)容可渲染也永遠有東西可以 diff“未保存的改動”客戶端不必特判空狀態(tài)。實現(xiàn)中這一點體現(xiàn)得很直接appearance_defaults.gorow, err : s.repo.GetAppearanceDefaults(ctx, userID) if err ! nil { if errors.Is(err, pgx.ErrNoRows) { return AppearanceDefaults{TemplateID: DefaultTemplateID, Style: Style{}, Margins: DefaultMargins()}, false, nil } return AppearanceDefaults{}, false, err }注意Style{}的零值不是疏漏。cv.go中明確寫著Style的零值表示“使用當前模板自帶的排版”且Sanitize會保留零值這與Margins把零邊距解析為具體 0.5in 的行為刻意相反。原因是模板應保持為一個完整的設計選擇——切換到行距更松的模板時行距應當真的變松因為那個值從未被凍結(jié)進文檔。所以在“系統(tǒng)默認外觀”里排版就是“交給模板決定”。布爾返回值ok用于區(qū)分“真的存過”和“回落到系統(tǒng)默認”但在本特性中客戶端并不需要這個區(qū)分設計文檔也把它列為可接受的信息損失。決策四應用點在創(chuàng)建時的 seed 值而不是給Sanitize加鉤子這是改動最容易被做錯的一處。誘人的做法是讓Sanitize知道 per-user 狀態(tài)在清理時順便套用用戶默認值。設計文檔拒絕了它理由是這會讓Sanitize的語義——“把一個確實未設置的值填成系統(tǒng)默認”——在其它所有調(diào)用路徑上被污染。尤其關鍵的是對已有CV 的編輯必須繼續(xù)把“未設置”理解為 0.5in/模板默認而絕不能理解成“這個用戶保存的默認值”。只有創(chuàng)建時的首次播種才讀用戶默認。因此三個調(diào)用點各自在調(diào)用Store.Create/CreateTailored之前查一次默認值替換掉今天的硬編碼值然后Sanitize照舊對到達的值運行。Store.Tailor的播種分支store.godefaults, _, err : s.GetAppearanceDefaults(ctx, userID) if err ! nil { return Meta{}, Meta{}, false, err } doc : Seed(st) doc.Style defaults.Style doc.Margins defaults.Margins meta, err : s.Create(ctx, userID, defaultBaseTitle, defaults.TemplateID, doc)重建處理器cv_reseed.go在同一位置做同一件事只是它還會寫一條版本歷史里程碑defaults, _, err : h.cvStore.GetAppearanceDefaults(c.Context(), userID) ... seeded.Style defaults.Style seeded.Margins defaults.Margins meta, err : h.cvStore.Create(c.Context(), userID, My CV, defaults.TemplateID, seeded)需要注意的是reseeds只在沒有基礎 CV時才讀默認值當已存在基礎 CV 時函數(shù)走CommitDocument路徑并保留既有外觀TemplateID: base.TemplateID這與“保存默認值從不回寫已有 CV”的規(guī)格要求一致。決策五CreateCV請求里顯式template_id優(yōu)先CreateCV的請求本就接受調(diào)用方傳入的template_id例如“先建空白、再選模板”的客戶端流程。設計文檔規(guī)定顯式指定優(yōu)先未指定時才用保存的默認模板而排版與頁邊距今天沒有 per-request 覆蓋字段所以它們始終來自保存的或系統(tǒng)的默認值。實現(xiàn)見cv.godefaults, _, err : h.cvStore.GetAppearanceDefaults(c.Context(), userID) if err ! nil { return err } requestedTemplateID : in.TemplateID if requestedTemplateID { requestedTemplateID defaults.TemplateID } tmplID, err : validCVTemplate(requestedTemplateID) ... doc.Style defaults.Style doc.Margins defaults.Margins meta, err : h.cvStore.Create(c.Context(), userID, cvTitle(in.Title), tmplID, doc)這段代碼的注釋甚至專門說明了它為什么不能直接依賴validCVTemplate()——那條路徑會一路落回classic-ats從而在用戶已保存默認模板時悄悄忽略它。代碼審查階段的修復tasks.md第 8 項也順帶更正了createCVRequest.TemplateID上過時的文檔注釋。決策六TemplateGallery.svelte增加受控模式而不是分叉TemplateGallery原本綁定cvId點擊時通過api.setCvTemplate自行持久化。設計文檔的做法是新增可選value/onChange屬性傳入cvId行為與今天逐字節(jié)相同拉取 自持久化傳入value純展示渲染同一套網(wǎng)格與縮略圖點擊只調(diào)onChange(id)不發(fā) API 請求。組件頂部注釋把這兩種模式寫得很清楚TemplateGallery.svelte// - cvId given: self-persisting, exactly as the tailoring workspace has always used it // - cvId omitted: controlled — the highlighted thumbnail mirrors the bindable value, // and picking one only updates value; no API call.好處是“有哪些模板、縮略圖長什么樣”這件事仍然只有一個組件在維護。這是把自持久化組件改造成受控組件的標準手法保留舊屬性作為行為開關新增受控屬性而不是復制組件。決策七設置界面顯式保存而不是工作區(qū)式自動保存?zhèn)}庫里其它/my/*設置界面如 profile 表單都在顯式動作時保存tailoring 工作區(qū)的 800ms 防抖自動保存是針對“用戶正在實時編輯的活文檔”的特例。默認值界面沒有實時預覽來為自動保存的響應性辯護因此遵循更常見的/my/*模式。落地后這一決策進一步演化外觀默認值從“一個由按鈕進入的 Settings 頁”變成了 CV 區(qū)塊的兩個視圖/my/cvs/template與/my/cvs/typography由web/src/routes/my/cvs/layout.svelte的 TabStrip 承載。兩個頁面共享同一個記錄因此保存邏輯被提到共享外殼CvAppearancePane.svelte中——它負責加載門控、說明文案與唯一的 Save 按鈕只有控件本身留在各自頁面里。頁面本身非常薄web/src/routes/my/cvs/template/page.svelte、web/src/routes/my/cvs/typography/page.svelteCvAppearancePane lead{s.lead} TemplateGallery bind:value{cvAppearance.templateId} / /CvAppearancePaneCvAppearancePane lead{s.lead} StyleSettings bind:style{cvAppearance.style} fonts{cvAppearance.fonts} / section classspace-y-2 h2.../h2 MarginSettings bind:margins{cvAppearance.margins} / /section /CvAppearancePane“頁邊距與字體放在同一個 tab”也有明確理由它們回答的是同一個問題——文字如何落在頁面上而一個只有四個數(shù)字輸入框的 tab 沒人會打開。共享狀態(tài)放在web/src/lib/cvAppearance.svelte.ts采用UserResource基類。這里有兩個值得學習的工程細節(jié)為什么是一個 store 而不是每頁各自 stateAPI 一次讀寫三個字段如果每個 pane 持有自己的副本切 tab 就會重新拉取并丟掉另一個 pane 尚未保存的編輯放在共享 store 里編輯能跨 tab 存活任一 tab 的 Save 都寫整條記錄。為什么必須記錄加載失敗基類把加載失敗當作“保留默認狀態(tài)”這對只讀緩存合理對表單卻是陷阱——一個顯示空白默認值的 pane 會誘使用戶保存從而用空白覆蓋真實記錄。因此 store 單獨記錄loadFailedpane 在加載成功前拒絕渲染控件。保存實現(xiàn)也直接呼應“整份替換”的存儲語義const result await api.setCvAppearanceDefaults({ template_id: this.#templateId, style: this.#style, margins: this.#margins, }); this.apply({ defaults: result, fonts: this.#fonts });由于PUT返回的就是清洗后實際保存的值客戶端不需要再發(fā)一次 GET 回讀——這正是tasks.md第 8.2 項把SetAppearanceDefaults的簽名從“只返回 error”改為返回(AppearanceDefaults, error)的原因。服務端實現(xiàn)校驗規(guī)則的唯一來源類型與兩個方法領域類型刻意極簡appearance_defaults.gotype AppearanceDefaults struct { TemplateID string Style Style Margins Margins }它只承載“一份新 CV 的創(chuàng)建調(diào)用點否則會硬編碼的那三樣東西”不含任何文檔內(nèi)容。寫入方法appearance_defaults.go先解析模板、再清洗、再序列化最后 upserttmpl, err : ResolveTemplate(defaults.TemplateID) if err ! nil { return AppearanceDefaults{}, err } saved : AppearanceDefaults{ TemplateID: tmpl.ID, Style: defaults.Style.sanitized(), Margins: defaults.Margins.sanitized(), }這里體現(xiàn)了兩條與 CV 文檔完全一致的約束未知模板被拒絕ResolveTemplate返回ErrUnknownTemplate越界值被鉗制而非拒絕sanitized()。鉗制規(guī)則的準確取值由于復用了同一套函數(shù)默認值記錄享有與 CV 文檔一字不差的邊界。相關常量在internal/candidate/cv/cv.go維度默認行為允許范圍其它規(guī)則Margins單邊0未設置→ 0.5 in0.25 in – 1.5 in超出上下界鉗到最近邊界font_size0 交給模板8.5 pt – 12.0 pt先按 0.5 pt 步長四舍五入再鉗制line_height0 交給模板0.3 em – 0.9 em直接鉗制font_family空 交給模板必須是字體注冊表中的 id未知字體被清空而不是報錯Style.sanitized()的語義值得單獨強調(diào)只鉗制被設置過的值零值保持為零。代碼注釋解釋了這樣做的兩個理由——所有在Style類型出現(xiàn)之前寫入的 CV 都沒有 style 塊因此渲染結(jié)果不變、無需遷移以及模板作為整體設計選擇不應被凍結(jié)的行距值悄悄破壞。相反Margins.sanitized()會把每個為 0 的邊解析成defaultMargin。這意味著通過 API 提交{top:0,...}保存的邊距記錄會是 0.5而不是 0——這是“邊距屬于文檔內(nèi)容”的語義在默認值上的自然延續(xù)。模板注冊表與陳舊模板的自愈模板注冊表在internal/candidate/cv/template.go當前包含 9 個模板classic-ats默認、centered、modern-sans、timeline、compact、mono-tech、sidebar、portrait、headshot。擴展方式是追加注冊項并放置同名templates/id.typ再用make cv-previews重新生成畫廊縮略圖——這也是“新增模板無需 schema 變更”的具體含義。代碼審查階段發(fā)現(xiàn)了一個真實缺陷注冊表可能在用戶保存默認值之后收縮。而Store.Create從不校驗它的templateID參數(shù)因此一個已失效的 id 會被靜默帶入新 CV直到渲染時才失敗。修復方式是在讀取時自愈appearance_defaults.gotemplateID : row.TemplateID if _, err : ResolveTemplate(templateID); err ! nil { templateID DefaultTemplateID }排版與頁邊距不受影響只有模板會回落到系統(tǒng)默認。對應測試為TestStoreGetAppearanceDefaultsHealsAStaleTemplate。從三層 helper 收斂到一個共享讀取點tasks.md第 2.5/2.6 項記錄了一次有價值的“簡化迭代”值得在設計類文章中保留因為它展示了設計文檔與實現(xiàn)之間的一次糾偏。設計文檔的 Risks 一節(jié)提出把“為新 CV 解析有效外觀”的邏輯收斂到一個 helper讓三個調(diào)用點都調(diào)它以避免第四個創(chuàng)建路徑出現(xiàn)時忘記同步。初版據(jù)此實現(xiàn)了Store.effectiveAppearance并在注釋里聲稱自己是“所有調(diào)用點讀取該值的唯一位置”。但這個說法是假的三個調(diào)用點中有兩個位于internal/api/handler不同包只能直接調(diào)導出方法GetAppearanceDefaultshelper 實際只被Store.Tailor使用。最終版本刪除了 helper 及其兩個只重復測試GetAppearanceDefaults的測試讓Store.Tailor也直接調(diào)用GetAppearanceDefaults。于是GetAppearanceDefaults才真正成為唯一的共享讀取入口其文檔注釋現(xiàn)在也如實這么寫。這個結(jié)果對設計文檔的原始風險項給出了一種更輕的緩解不靠“一個 helper 包辦”而靠“一個導出方法被所有調(diào)用點直接調(diào)用”。對跨包調(diào)用點來說后者才是真正可行的收斂方式。HTTP 表面兩個端點與錯誤映射路由注冊在internal/api/handler/cv.go兩者都是 cookie-onlyapi.Get(/me/cv-appearance-defaults, mw.cookie, h.GetCVAppearanceDefaults) api.Put(/me/cv-appearance-defaults, mw.cookie, h.SetCVAppearanceDefaults)處理器在internal/api/handler/cv_appearance_defaults.go。請求與響應形狀一致都是template_id/style/margins并統(tǒng)一包在{data: ...}中{ data: { template_id: sidebar, style: { font_family: inter, font_size: 10.5, line_height: 0.55 }, margins: { top: 0.75, right: 0.5, bottom: 0.75, left: 0.5 } } }PUT的語義是整份替換而不是部分更新處理器注釋明確寫了“a save always replaces the complete set, never a partial patch”。這一點的實際影響是客戶端必須把三個字段完整提交只在某一 tab 提交自己那一部分會清空另一部分——這正是前端用一個共享 store 承載整條記錄、由任一 tab 的 Save 寫全量的原因。錯誤映射沿用mapCVErrorcv.gocv.ErrUnknownTemplate→ HTTP 400unknown template請求體解析失敗 → 400。因此“未知模板被拒絕且不保存任何默認值”這條規(guī)格由ResolveTemplate在寫庫之前失敗來保證而不是靠事后回滾。處理器讀取時丟棄了ok布爾值defaults, _, err : ...因為它對客戶端沒有可觀察影響無論有無保存過返回的都是可直接渲染的具體形狀。測試與驗證策略規(guī)格文檔中的每條要求都對應可執(zhí)行的測試層測試文件覆蓋點領域?qū)觓ppearance_defaults_test.go回落系統(tǒng)默認、讀取已保存值、陳舊模板自愈、按用戶隔離、寫入往返、拒絕未知模板、越界鉗制HTTP 層cv_appearance_defaults_integration_test.goGET 回落、GET 已保存、PUT 持久化合法輸入、拒絕未知模板、越界鉗制、重復 PUT 覆蓋創(chuàng)建路徑cv_integration_test.go、cv_reseed_integration_test.go播種/空骨架兩條路徑使用保存的默認值未保存時仍用系統(tǒng)默認顯式template_id優(yōu)先集成測試使用真實 Postgres通過 testcontainers并經(jīng)由實際 HTTP 處理器驅(qū)動運行方式在測試文件頭部注明go test -tagsintegration ./internal/api/handler/tasks.md第 7 節(jié)誠實地記錄了人工驗證被跳過的原因機器上 5432/8080/8090 端口已有 docker-compose 棧在運行很可能屬于同一倉庫上的并發(fā)會話搭建隔離棧既不安全也耗時因此用戶選擇依賴自動化覆蓋前端另有svelte-check0 錯誤與pnpm test1376 通過。文檔同時明確指出自動化不能證明的事新頁面與入口在真實瀏覽器中的渲染與交互行為這仍是一個待補的缺口。這種“說清楚證據(jù)邊界”的寫法比籠統(tǒng)聲稱“已驗證”更有工程參考價值。風險、權(quán)衡與遷移四項已知權(quán)衡改了默認值不會追溯影響已有 CV。這是刻意的但設計文檔要求在設置界面的文案里明說否則會被讀成 bug。當前實現(xiàn)把這條說明放在兩個 pane 共享的leadSuffix里一次維護、兩處生效。三個調(diào)用點必須保持同步。如果將來出現(xiàn)第四條基礎 CV 創(chuàng)建路徑就會漏掉默認值。原本計劃用一個 helper 消解實踐后收斂為“所有調(diào)用點直接調(diào)用同一個導出方法GetAppearanceDefaults”見上文簡化迭代。GET 無保存時返回系統(tǒng)默認客戶端無法區(qū)分“沒存過”與“存的值恰好等于系統(tǒng)默認”。設計文檔判定可接受因為本特性沒有需要該區(qū)分的“恢復系統(tǒng)默認”開關。事實上連ok布爾值都已被處理器忽略。模板注冊表收縮會讓已保存的模板失效。這不是理論風險而是審查階段實際發(fā)現(xiàn)的缺陷最終以讀取時自愈解決。遷移計劃設計文檔給出的遷移方案是純增量新表、新端點、新路由、新的可選組件屬性。沒有既有數(shù)據(jù)變更沒有既有端點響應形狀變化。一次部署即可上線回滾也不需要越過標準 revert——如果先回滾代碼新表會保持為空且無人讀取。這一性質(zhì)在很大程度上來自兩條早期決策把數(shù)據(jù)放在獨立表而非users列不觸碰用戶行的遷移歷史以及把應用點放在創(chuàng)建入口而非Sanitize不改變既有文檔路徑的行為。實現(xiàn)落點速查關注點文件設計決策全文design.md變更動機與影響面proposal.md可執(zhí)行任務與審查修復記錄tasks.md能力規(guī)格新增specs/cv-appearance-defaults/spec.md能力規(guī)格CV 構(gòu)建器改動specs/cv-builder/spec.md建表遷移0128_cv_appearance_defaults.sqlsqlc 查詢cv_appearance_defaults.sql領域類型與讀寫方法appearance_defaults.go校驗與鉗制規(guī)則cv.go模板注冊表template.go簡歷播種創(chuàng)建路徑store.go重建創(chuàng)建路徑cv_reseed.go顯式創(chuàng)建路徑與路由cv.goHTTP 處理器cv_appearance_defaults.go前端共享狀態(tài)cvAppearance.svelte.ts共享設定外殼CvAppearancePane.svelte模板/排版頁面與分欄my/cvs/layout.svelte受控模板畫廊TemplateGallery.svelte結(jié)語這份設計真正示范了什么這個改動的代碼量不大但它把三類容易出錯的決策處理得很干凈。第一類是層與歸屬當“業(yè)務上屬于用戶”與“依賴方向上必須待在候選域”沖突時選擇讓依賴方向獲勝并用同包復用換取校驗邏輯的單一來源而不是在低層復制一份會漂移的注冊表。第二類是語義邊界Sanitize的含義是“填充確實未設置的值”因此 per-user 默認不能塞進它只有創(chuàng)建入口有權(quán)讀取用戶偏好編輯路徑繼續(xù)把“未設置”理解為系統(tǒng)默認。這條邊界一旦破掉保存默認值就會悄悄改寫用戶已有的文檔。第三類是改動的可回退性獨立表、獨立端點、顯式保存、受控組件屬性、純增量遷移——每一項都讓這次上線可以被簡單回滾而不需要數(shù)據(jù)修復腳本。tasks.md中那次 helper 刪除同樣值得記住設計文檔提出的緩解措施在真實的分層與包邊界面前未必成立當注釋宣稱的“唯一入口”事實上不成立時正確做法是讓代碼回到真實收斂點并同步修正注釋而不是保留一個看起來優(yōu)雅、實際只覆蓋三分之一的抽象。贊分享【免費下載鏈接】freehirefreehire — the open-source search engine for job seekers項目地址https://gitcode.com/GitHub_Trending/fr/freehire點擊查看免費下載相關推薦better-sqlite3 表設計實戰(zhàn)指南主鍵、默認值與外鍵約束的最佳實踐better sqlite3 表設計實戰(zhàn)指南主鍵、默認值與外鍵約束的最佳實踐 本文源自 better sqlite3 https://link.gitcode數(shù)據(jù)庫嵌入式數(shù)據(jù)庫freehire 的 internal/ai 分層架構(gòu)第 3 層 AI 能力塊的邊界、依賴約束與雙重強制校驗freehire 的 internal/ai 分層架構(gòu)第 3 層 AI 能力塊的邊界、依賴約束與雙重強制校驗 internal/ai 在 freehire 的10 分鐘跑通 FreeLLMAPI一鍵免費 LLM API 聚合路由新手指南10 分鐘跑通 FreeLLMAPI一鍵免費 LLM API 聚合路由新手指南 FreeLLMAPI 把 34 家 AI 提供商的免費額度聚合成一個 Open人工智能LLM 網(wǎng)關后端前端CLI桌面應用上一篇REFramework 使用指南RE 引擎游戲 MOD 框架、VR 支持與腳本平臺快速上手下一篇Cap錄完即得分享鏈接的開源錄屏工具創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 freehire 中 per-user CV 外觀默認值的架構(gòu)設計：模板、排版與頁邊距的復用與分層約束
【免費下載鏈接】freehirefreehire — the open-source search engine for job seekers項目地址https://gitcode.com/GitHub_Trending/fr/freehire點擊查看免費下載本文圍繞 freehire 倉庫中的add-cv-appearance-defaults設計文檔解析一項典型的多層改動如何在不復制校驗邏輯、不侵入既有 CV 文檔路徑的前提下為每個用戶保存一份“新 CV 默認外觀”。文章完整繼承原設計文檔的上下文、目標與非目標、七項關鍵決策、風險與遷移計劃并結(jié)合倉庫中已經(jīng)落地的遷移 SQL、Go 領域代碼、HTTP 處理器與 Svelte 前端組件說明每個決策在代碼中的真實形態(tài)與驗證方式。讀者讀完后可以掌握分層架構(gòu)下“用戶級偏好”應放在哪一層、為什么把默認值寫在創(chuàng)建入口而非 sanitizer、以及如何把自持久化組件改造成受控組件而不破壞原有調(diào)用方。背景一個只在單份 CV 里存在的設置設計文檔的Context一節(jié)先界定了既有狀態(tài)。CV 的外觀由三部分組成并且這三部分都存放在每一條cvs行上template_id模板標識Style{font_family, font_size, line_height}字體族、字號pt、行高emMargins{top, right, bottom, left}四邊頁邊距英寸。這三者由internal/candidate/cv負責校驗與鉗制Style.sanitized()、Margins.sanitized()以及template.go中的模板注冊表。同時設計文檔明確了一條重要的所有權(quán)規(guī)則internal/candidate/cvedit是已有CV 文檔的唯一寫入方。問題在proposal.md變更提案中被直白地描述外觀只能在 tailoring 工作區(qū)內(nèi)逐份 CV 編輯每份新 CV 都從同一組硬編碼值開始——classic-ats模板、0.5 英寸頁邊距、模板自帶排版。已經(jīng)調(diào)好一次外觀的候選人每新建一份基礎 CV 都需要重來一遍系統(tǒng)里沒有地方表達“我始終想讓我的 CV 長這樣”。三個硬編碼的系統(tǒng)默認種子點設計文檔指出當前恰好有三個調(diào)用點會用硬編碼系統(tǒng)默認值為新的基礎CVjob_id IS NULL播種調(diào)用點設計文檔標注位置當前倉庫實現(xiàn)Store.Tailor的簡歷播種分支internal/candidate/cv/store.go:314store.go從簡歷重置/重建cv_reset.go:132cv_reseed.go文件已更名CreateCV處理器internal/api/handler/cv.go約 356-390 行cv.go而 tailoring綁定職位的副本始終從基礎 CV 繼承template_id/Style/Margins通過CreateTailored與Align因此它們不需要任何改動。這一點決定了整個改動的邊界只需處理“基礎 CV 誕生的一瞬間”。目標與非目標先劃清不可越界的范圍設計文檔用 Goals / Non-Goals 把改動鎖在一個很小的面上。Goals一條持久的、按用戶存儲的外觀默認值記錄并使用與 CV 文檔完全相同的規(guī)則校驗在三個既有的基礎 CV 創(chuàng)建調(diào)用點上非侵入地應用它原樣復用StyleSettings/MarginSettings把TemplateGallery泛化而不是分叉。Non-Goals明確不做不把默認值重新應用到已存在/已打開的 CV即 tailoring 工作區(qū)里不做“重置為我的默認值”不新增頂層/my/*導航入口不改變 tailoredjob-boundCV 的創(chuàng)建流程。非目標并非隨手排除而是這個設計的“低成本”來源一旦允許回寫已有 CV“保存默認值”就會變成一次批量文檔遷移需要處理版本歷史、并發(fā)編輯與用戶預期。關鍵決策逐條解析決策一數(shù)據(jù)放在internal/candidate/cv而不是internal/identity/userprofile這是整份文檔中最有架構(gòu)價值的一條。userprofile已經(jīng)持有一個類似的 per-user 偏好LocationPreferences是“用戶級默認值”最接近的既有范式。按直覺外觀默認值也應放進userprofile。但倉庫的分層規(guī)則internal/platform/arch/layering禁止identity第 3 層導入candidate第 4 層的類型。而Style、Margins、模板注冊表與字體注冊表都住在internal/candidate/cv。這意味著放在identity里就必須復制一份校驗與注冊表邏輯設計文檔進一步借用倉庫自身normalize包對公司法律形式詞表的告警來說明后果副本一定會漂移。選擇同包新文件appearance_defaults.go后SetAppearanceDefaults調(diào)用的就是 CV 文檔路徑已經(jīng)在用的Style.sanitized()、Margins.sanitized()、ResolveTemplate/TemplateIDs()——不存在第二份實現(xiàn)。這是“依賴方向決定數(shù)據(jù)歸屬”而非“業(yè)務語義決定數(shù)據(jù)歸屬”的典型案例。決策二新增一張表而不是給users加列cv_appearance_defaults鏡像了cvs表的template_id/style jsonb/margins jsonb形狀主鍵是user_id但沒有title與job_id。設計文檔給出三點理由可選、可刪除——用戶沒保存過就沒有行與users行自身的遷移歷史解耦與cvs結(jié)構(gòu)一致因此同一套 jsonb 編解碼/清洗輔助函數(shù)可以直接復用。落地的遷移見migrations/0128_cv_appearance_defaults.sqlCREATE TABLE IF NOT EXISTS cv_appearance_defaults ( user_id bigint PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE, template_id text NOT NULL, style jsonb NOT NULL, margins jsonb NOT NULL, updated_at timestamptz NOT NULL DEFAULT now() );ON DELETE CASCADE讓刪號時這行自然消失正好對應設計文檔所說的“optional and deletable”。查詢側(cè)使用 upsert語義是“整份替換”而非字段級 patch見internal/platform/db/queries/cv_appearance_defaults.sqlINSERT INTO cv_appearance_defaults (user_id, template_id, style, margins, updated_at) VALUES ($1, $2, $3, $4, now()) ON CONFLICT (user_id) DO UPDATE SET template_id EXCLUDED.template_id, style EXCLUDED.style, margins EXCLUDED.margins, updated_at now() RETURNING user_id, template_id, style, margins, updated_at;由于一用戶一行ON CONFLICT的更新分支就等價于“把這一行整體換成新的完整集合”無需在應用層區(qū)分首次寫入與覆蓋寫入。決策三GET 永遠返回具體形狀設計文檔規(guī)定沒有保存過默認值時GetAppearanceDefaults返回(系統(tǒng)默認值, false, nil)而不是零值或缺失值。這樣設置界面永遠有內(nèi)容可渲染也永遠有東西可以 diff“未保存的改動”客戶端不必特判空狀態(tài)。實現(xiàn)中這一點體現(xiàn)得很直接appearance_defaults.gorow, err : s.repo.GetAppearanceDefaults(ctx, userID) if err ! nil { if errors.Is(err, pgx.ErrNoRows) { return AppearanceDefaults{TemplateID: DefaultTemplateID, Style: Style{}, Margins: DefaultMargins()}, false, nil } return AppearanceDefaults{}, false, err }注意Style{}的零值不是疏漏。cv.go中明確寫著Style的零值表示“使用當前模板自帶的排版”且Sanitize會保留零值這與Margins把零邊距解析為具體 0.5in 的行為刻意相反。原因是模板應保持為一個完整的設計選擇——切換到行距更松的模板時行距應當真的變松因為那個值從未被凍結(jié)進文檔。所以在“系統(tǒng)默認外觀”里排版就是“交給模板決定”。布爾返回值ok用于區(qū)分“真的存過”和“回落到系統(tǒng)默認”但在本特性中客戶端并不需要這個區(qū)分設計文檔也把它列為可接受的信息損失。決策四應用點在創(chuàng)建時的 seed 值而不是給Sanitize加鉤子這是改動最容易被做錯的一處。誘人的做法是讓Sanitize知道 per-user 狀態(tài)在清理時順便套用用戶默認值。設計文檔拒絕了它理由是這會讓Sanitize的語義——“把一個確實未設置的值填成系統(tǒng)默認”——在其它所有調(diào)用路徑上被污染。尤其關鍵的是對已有CV 的編輯必須繼續(xù)把“未設置”理解為 0.5in/模板默認而絕不能理解成“這個用戶保存的默認值”。只有創(chuàng)建時的首次播種才讀用戶默認。因此三個調(diào)用點各自在調(diào)用Store.Create/CreateTailored之前查一次默認值替換掉今天的硬編碼值然后Sanitize照舊對到達的值運行。Store.Tailor的播種分支store.godefaults, _, err : s.GetAppearanceDefaults(ctx, userID) if err ! nil { return Meta{}, Meta{}, false, err } doc : Seed(st) doc.Style defaults.Style doc.Margins defaults.Margins meta, err : s.Create(ctx, userID, defaultBaseTitle, defaults.TemplateID, doc)重建處理器cv_reseed.go在同一位置做同一件事只是它還會寫一條版本歷史里程碑defaults, _, err : h.cvStore.GetAppearanceDefaults(c.Context(), userID) ... seeded.Style defaults.Style seeded.Margins defaults.Margins meta, err : h.cvStore.Create(c.Context(), userID, My CV, defaults.TemplateID, seeded)需要注意的是reseeds只在沒有基礎 CV時才讀默認值當已存在基礎 CV 時函數(shù)走CommitDocument路徑并保留既有外觀TemplateID: base.TemplateID這與“保存默認值從不回寫已有 CV”的規(guī)格要求一致。決策五CreateCV請求里顯式template_id優(yōu)先CreateCV的請求本就接受調(diào)用方傳入的template_id例如“先建空白、再選模板”的客戶端流程。設計文檔規(guī)定顯式指定優(yōu)先未指定時才用保存的默認模板而排版與頁邊距今天沒有 per-request 覆蓋字段所以它們始終來自保存的或系統(tǒng)的默認值。實現(xiàn)見cv.godefaults, _, err : h.cvStore.GetAppearanceDefaults(c.Context(), userID) if err ! nil { return err } requestedTemplateID : in.TemplateID if requestedTemplateID { requestedTemplateID defaults.TemplateID } tmplID, err : validCVTemplate(requestedTemplateID) ... doc.Style defaults.Style doc.Margins defaults.Margins meta, err : h.cvStore.Create(c.Context(), userID, cvTitle(in.Title), tmplID, doc)這段代碼的注釋甚至專門說明了它為什么不能直接依賴validCVTemplate()——那條路徑會一路落回classic-ats從而在用戶已保存默認模板時悄悄忽略它。代碼審查階段的修復tasks.md第 8 項也順帶更正了createCVRequest.TemplateID上過時的文檔注釋。決策六TemplateGallery.svelte增加受控模式而不是分叉TemplateGallery原本綁定cvId點擊時通過api.setCvTemplate自行持久化。設計文檔的做法是新增可選value/onChange屬性傳入cvId行為與今天逐字節(jié)相同拉取 自持久化傳入value純展示渲染同一套網(wǎng)格與縮略圖點擊只調(diào)onChange(id)不發(fā) API 請求。組件頂部注釋把這兩種模式寫得很清楚TemplateGallery.svelte// - cvId given: self-persisting, exactly as the tailoring workspace has always used it // - cvId omitted: controlled — the highlighted thumbnail mirrors the bindable value, // and picking one only updates value; no API call.好處是“有哪些模板、縮略圖長什么樣”這件事仍然只有一個組件在維護。這是把自持久化組件改造成受控組件的標準手法保留舊屬性作為行為開關新增受控屬性而不是復制組件。決策七設置界面顯式保存而不是工作區(qū)式自動保存?zhèn)}庫里其它/my/*設置界面如 profile 表單都在顯式動作時保存tailoring 工作區(qū)的 800ms 防抖自動保存是針對“用戶正在實時編輯的活文檔”的特例。默認值界面沒有實時預覽來為自動保存的響應性辯護因此遵循更常見的/my/*模式。落地后這一決策進一步演化外觀默認值從“一個由按鈕進入的 Settings 頁”變成了 CV 區(qū)塊的兩個視圖/my/cvs/template與/my/cvs/typography由web/src/routes/my/cvs/layout.svelte的 TabStrip 承載。兩個頁面共享同一個記錄因此保存邏輯被提到共享外殼CvAppearancePane.svelte中——它負責加載門控、說明文案與唯一的 Save 按鈕只有控件本身留在各自頁面里。頁面本身非常薄web/src/routes/my/cvs/template/page.svelte、web/src/routes/my/cvs/typography/page.svelteCvAppearancePane lead{s.lead} TemplateGallery bind:value{cvAppearance.templateId} / /CvAppearancePaneCvAppearancePane lead{s.lead} StyleSettings bind:style{cvAppearance.style} fonts{cvAppearance.fonts} / section classspace-y-2 h2.../h2 MarginSettings bind:margins{cvAppearance.margins} / /section /CvAppearancePane“頁邊距與字體放在同一個 tab”也有明確理由它們回答的是同一個問題——文字如何落在頁面上而一個只有四個數(shù)字輸入框的 tab 沒人會打開。共享狀態(tài)放在web/src/lib/cvAppearance.svelte.ts采用UserResource基類。這里有兩個值得學習的工程細節(jié)為什么是一個 store 而不是每頁各自 stateAPI 一次讀寫三個字段如果每個 pane 持有自己的副本切 tab 就會重新拉取并丟掉另一個 pane 尚未保存的編輯放在共享 store 里編輯能跨 tab 存活任一 tab 的 Save 都寫整條記錄。為什么必須記錄加載失敗基類把加載失敗當作“保留默認狀態(tài)”這對只讀緩存合理對表單卻是陷阱——一個顯示空白默認值的 pane 會誘使用戶保存從而用空白覆蓋真實記錄。因此 store 單獨記錄loadFailedpane 在加載成功前拒絕渲染控件。保存實現(xiàn)也直接呼應“整份替換”的存儲語義const result await api.setCvAppearanceDefaults({ template_id: this.#templateId, style: this.#style, margins: this.#margins, }); this.apply({ defaults: result, fonts: this.#fonts });由于PUT返回的就是清洗后實際保存的值客戶端不需要再發(fā)一次 GET 回讀——這正是tasks.md第 8.2 項把SetAppearanceDefaults的簽名從“只返回 error”改為返回(AppearanceDefaults, error)的原因。服務端實現(xiàn)校驗規(guī)則的唯一來源類型與兩個方法領域類型刻意極簡appearance_defaults.gotype AppearanceDefaults struct { TemplateID string Style Style Margins Margins }它只承載“一份新 CV 的創(chuàng)建調(diào)用點否則會硬編碼的那三樣東西”不含任何文檔內(nèi)容。寫入方法appearance_defaults.go先解析模板、再清洗、再序列化最后 upserttmpl, err : ResolveTemplate(defaults.TemplateID) if err ! nil { return AppearanceDefaults{}, err } saved : AppearanceDefaults{ TemplateID: tmpl.ID, Style: defaults.Style.sanitized(), Margins: defaults.Margins.sanitized(), }這里體現(xiàn)了兩條與 CV 文檔完全一致的約束未知模板被拒絕ResolveTemplate返回ErrUnknownTemplate越界值被鉗制而非拒絕sanitized()。鉗制規(guī)則的準確取值由于復用了同一套函數(shù)默認值記錄享有與 CV 文檔一字不差的邊界。相關常量在internal/candidate/cv/cv.go維度默認行為允許范圍其它規(guī)則Margins單邊0未設置→ 0.5 in0.25 in – 1.5 in超出上下界鉗到最近邊界font_size0 交給模板8.5 pt – 12.0 pt先按 0.5 pt 步長四舍五入再鉗制line_height0 交給模板0.3 em – 0.9 em直接鉗制font_family空 交給模板必須是字體注冊表中的 id未知字體被清空而不是報錯Style.sanitized()的語義值得單獨強調(diào)只鉗制被設置過的值零值保持為零。代碼注釋解釋了這樣做的兩個理由——所有在Style類型出現(xiàn)之前寫入的 CV 都沒有 style 塊因此渲染結(jié)果不變、無需遷移以及模板作為整體設計選擇不應被凍結(jié)的行距值悄悄破壞。相反Margins.sanitized()會把每個為 0 的邊解析成defaultMargin。這意味著通過 API 提交{top:0,...}保存的邊距記錄會是 0.5而不是 0——這是“邊距屬于文檔內(nèi)容”的語義在默認值上的自然延續(xù)。模板注冊表與陳舊模板的自愈模板注冊表在internal/candidate/cv/template.go當前包含 9 個模板classic-ats默認、centered、modern-sans、timeline、compact、mono-tech、sidebar、portrait、headshot。擴展方式是追加注冊項并放置同名templates/id.typ再用make cv-previews重新生成畫廊縮略圖——這也是“新增模板無需 schema 變更”的具體含義。代碼審查階段發(fā)現(xiàn)了一個真實缺陷注冊表可能在用戶保存默認值之后收縮。而Store.Create從不校驗它的templateID參數(shù)因此一個已失效的 id 會被靜默帶入新 CV直到渲染時才失敗。修復方式是在讀取時自愈appearance_defaults.gotemplateID : row.TemplateID if _, err : ResolveTemplate(templateID); err ! nil { templateID DefaultTemplateID }排版與頁邊距不受影響只有模板會回落到系統(tǒng)默認。對應測試為TestStoreGetAppearanceDefaultsHealsAStaleTemplate。從三層 helper 收斂到一個共享讀取點tasks.md第 2.5/2.6 項記錄了一次有價值的“簡化迭代”值得在設計類文章中保留因為它展示了設計文檔與實現(xiàn)之間的一次糾偏。設計文檔的 Risks 一節(jié)提出把“為新 CV 解析有效外觀”的邏輯收斂到一個 helper讓三個調(diào)用點都調(diào)它以避免第四個創(chuàng)建路徑出現(xiàn)時忘記同步。初版據(jù)此實現(xiàn)了Store.effectiveAppearance并在注釋里聲稱自己是“所有調(diào)用點讀取該值的唯一位置”。但這個說法是假的三個調(diào)用點中有兩個位于internal/api/handler不同包只能直接調(diào)導出方法GetAppearanceDefaultshelper 實際只被Store.Tailor使用。最終版本刪除了 helper 及其兩個只重復測試GetAppearanceDefaults的測試讓Store.Tailor也直接調(diào)用GetAppearanceDefaults。于是GetAppearanceDefaults才真正成為唯一的共享讀取入口其文檔注釋現(xiàn)在也如實這么寫。這個結(jié)果對設計文檔的原始風險項給出了一種更輕的緩解不靠“一個 helper 包辦”而靠“一個導出方法被所有調(diào)用點直接調(diào)用”。對跨包調(diào)用點來說后者才是真正可行的收斂方式。HTTP 表面兩個端點與錯誤映射路由注冊在internal/api/handler/cv.go兩者都是 cookie-onlyapi.Get(/me/cv-appearance-defaults, mw.cookie, h.GetCVAppearanceDefaults) api.Put(/me/cv-appearance-defaults, mw.cookie, h.SetCVAppearanceDefaults)處理器在internal/api/handler/cv_appearance_defaults.go。請求與響應形狀一致都是template_id/style/margins并統(tǒng)一包在{data: ...}中{ data: { template_id: sidebar, style: { font_family: inter, font_size: 10.5, line_height: 0.55 }, margins: { top: 0.75, right: 0.5, bottom: 0.75, left: 0.5 } } }PUT的語義是整份替換而不是部分更新處理器注釋明確寫了“a save always replaces the complete set, never a partial patch”。這一點的實際影響是客戶端必須把三個字段完整提交只在某一 tab 提交自己那一部分會清空另一部分——這正是前端用一個共享 store 承載整條記錄、由任一 tab 的 Save 寫全量的原因。錯誤映射沿用mapCVErrorcv.gocv.ErrUnknownTemplate→ HTTP 400unknown template請求體解析失敗 → 400。因此“未知模板被拒絕且不保存任何默認值”這條規(guī)格由ResolveTemplate在寫庫之前失敗來保證而不是靠事后回滾。處理器讀取時丟棄了ok布爾值defaults, _, err : ...因為它對客戶端沒有可觀察影響無論有無保存過返回的都是可直接渲染的具體形狀。測試與驗證策略規(guī)格文檔中的每條要求都對應可執(zhí)行的測試層測試文件覆蓋點領域?qū)觓ppearance_defaults_test.go回落系統(tǒng)默認、讀取已保存值、陳舊模板自愈、按用戶隔離、寫入往返、拒絕未知模板、越界鉗制HTTP 層cv_appearance_defaults_integration_test.goGET 回落、GET 已保存、PUT 持久化合法輸入、拒絕未知模板、越界鉗制、重復 PUT 覆蓋創(chuàng)建路徑cv_integration_test.go、cv_reseed_integration_test.go播種/空骨架兩條路徑使用保存的默認值未保存時仍用系統(tǒng)默認顯式template_id優(yōu)先集成測試使用真實 Postgres通過 testcontainers并經(jīng)由實際 HTTP 處理器驅(qū)動運行方式在測試文件頭部注明go test -tagsintegration ./internal/api/handler/tasks.md第 7 節(jié)誠實地記錄了人工驗證被跳過的原因機器上 5432/8080/8090 端口已有 docker-compose 棧在運行很可能屬于同一倉庫上的并發(fā)會話搭建隔離棧既不安全也耗時因此用戶選擇依賴自動化覆蓋前端另有svelte-check0 錯誤與pnpm test1376 通過。文檔同時明確指出自動化不能證明的事新頁面與入口在真實瀏覽器中的渲染與交互行為這仍是一個待補的缺口。這種“說清楚證據(jù)邊界”的寫法比籠統(tǒng)聲稱“已驗證”更有工程參考價值。風險、權(quán)衡與遷移四項已知權(quán)衡改了默認值不會追溯影響已有 CV。這是刻意的但設計文檔要求在設置界面的文案里明說否則會被讀成 bug。當前實現(xiàn)把這條說明放在兩個 pane 共享的leadSuffix里一次維護、兩處生效。三個調(diào)用點必須保持同步。如果將來出現(xiàn)第四條基礎 CV 創(chuàng)建路徑就會漏掉默認值。原本計劃用一個 helper 消解實踐后收斂為“所有調(diào)用點直接調(diào)用同一個導出方法GetAppearanceDefaults”見上文簡化迭代。GET 無保存時返回系統(tǒng)默認客戶端無法區(qū)分“沒存過”與“存的值恰好等于系統(tǒng)默認”。設計文檔判定可接受因為本特性沒有需要該區(qū)分的“恢復系統(tǒng)默認”開關。事實上連ok布爾值都已被處理器忽略。模板注冊表收縮會讓已保存的模板失效。這不是理論風險而是審查階段實際發(fā)現(xiàn)的缺陷最終以讀取時自愈解決。遷移計劃設計文檔給出的遷移方案是純增量新表、新端點、新路由、新的可選組件屬性。沒有既有數(shù)據(jù)變更沒有既有端點響應形狀變化。一次部署即可上線回滾也不需要越過標準 revert——如果先回滾代碼新表會保持為空且無人讀取。這一性質(zhì)在很大程度上來自兩條早期決策把數(shù)據(jù)放在獨立表而非users列不觸碰用戶行的遷移歷史以及把應用點放在創(chuàng)建入口而非Sanitize不改變既有文檔路徑的行為。實現(xiàn)落點速查關注點文件設計決策全文design.md變更動機與影響面proposal.md可執(zhí)行任務與審查修復記錄tasks.md能力規(guī)格新增specs/cv-appearance-defaults/spec.md能力規(guī)格CV 構(gòu)建器改動specs/cv-builder/spec.md建表遷移0128_cv_appearance_defaults.sqlsqlc 查詢cv_appearance_defaults.sql領域類型與讀寫方法appearance_defaults.go校驗與鉗制規(guī)則cv.go模板注冊表template.go簡歷播種創(chuàng)建路徑store.go重建創(chuàng)建路徑cv_reseed.go顯式創(chuàng)建路徑與路由cv.goHTTP 處理器cv_appearance_defaults.go前端共享狀態(tài)cvAppearance.svelte.ts共享設定外殼CvAppearancePane.svelte模板/排版頁面與分欄my/cvs/layout.svelte受控模板畫廊TemplateGallery.svelte結(jié)語這份設計真正示范了什么這個改動的代碼量不大但它把三類容易出錯的決策處理得很干凈。第一類是層與歸屬當“業(yè)務上屬于用戶”與“依賴方向上必須待在候選域”沖突時選擇讓依賴方向獲勝并用同包復用換取校驗邏輯的單一來源而不是在低層復制一份會漂移的注冊表。第二類是語義邊界Sanitize的含義是“填充確實未設置的值”因此 per-user 默認不能塞進它只有創(chuàng)建入口有權(quán)讀取用戶偏好編輯路徑繼續(xù)把“未設置”理解為系統(tǒng)默認。這條邊界一旦破掉保存默認值就會悄悄改寫用戶已有的文檔。第三類是改動的可回退性獨立表、獨立端點、顯式保存、受控組件屬性、純增量遷移——每一項都讓這次上線可以被簡單回滾而不需要數(shù)據(jù)修復腳本。tasks.md中那次 helper 刪除同樣值得記住設計文檔提出的緩解措施在真實的分層與包邊界面前未必成立當注釋宣稱的“唯一入口”事實上不成立時正確做法是讓代碼回到真實收斂點并同步修正注釋而不是保留一個看起來優(yōu)雅、實際只覆蓋三分之一的抽象。贊分享【免費下載鏈接】freehirefreehire — the open-source search engine for job seekers項目地址https://gitcode.com/GitHub_Trending/fr/freehire點擊查看免費下載相關推薦better-sqlite3 表設計實戰(zhàn)指南主鍵、默認值與外鍵約束的最佳實踐better sqlite3 表設計實戰(zhàn)指南主鍵、默認值與外鍵約束的最佳實踐 本文源自 better sqlite3 https://link.gitcode數(shù)據(jù)庫嵌入式數(shù)據(jù)庫freehire 的 internal/ai 分層架構(gòu)第 3 層 AI 能力塊的邊界、依賴約束與雙重強制校驗freehire 的 internal/ai 分層架構(gòu)第 3 層 AI 能力塊的邊界、依賴約束與雙重強制校驗 internal/ai 在 freehire 的10 分鐘跑通 FreeLLMAPI一鍵免費 LLM API 聚合路由新手指南10 分鐘跑通 FreeLLMAPI一鍵免費 LLM API 聚合路由新手指南 FreeLLMAPI 把 34 家 AI 提供商的免費額度聚合成一個 Open人工智能LLM 網(wǎng)關后端前端CLI桌面應用上一篇REFramework 使用指南RE 引擎游戲 MOD 框架、VR 支持與腳本平臺快速上手下一篇Cap錄完即得分享鏈接的開源錄屏工具創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考