這套系統(tǒng)我從需求梳理、技術(shù)選型到落地部署一共花了三周時間。起因是公司行政每個月底都要用Excel把打卡記錄、請假單、績效評分匯總到工資表里VLOOKUP串行、公式改壞、漏算遲到是家常便飯。后來我直接用 Python Vue3 做了一套企業(yè)員工考勤打卡薪酬績效管理系統(tǒng)把員工、主管、HR、系統(tǒng)管理員四個角色的流程全部打通。這篇文章把這套系統(tǒng)的業(yè)務(wù)設(shè)計、數(shù)據(jù)庫建模、前后端核心實(shí)現(xiàn)和踩過的真實(shí)坑完整寫出來適合正在做畢業(yè)設(shè)計、企業(yè)內(nèi)部系統(tǒng)或者想搞懂考勤薪酬業(yè)務(wù)邏輯的開發(fā)者復(fù)現(xiàn)和參考。1. 業(yè)務(wù)視角先想清楚四個角色到底在折騰什么很多人一上來就寫代碼這是做管理系統(tǒng)最忌諱的?？记?、薪酬、績效這種系統(tǒng)業(yè)務(wù)規(guī)則比代碼復(fù)雜得多角色邊界一旦沒劃清楚后面每個頁面都要返工。我先把四個角色在系統(tǒng)里的職責(zé)理了一遍再做數(shù)據(jù)庫和接口設(shè)計。1.1 四個角色的權(quán)限邊界這個系統(tǒng)我定義了四種用戶身份普通員工、部門主管、HR管理員、系統(tǒng)管理員。別看角色少權(quán)限差異非常大我把功能權(quán)限和數(shù)據(jù)權(quán)限分開設(shè)計。功能權(quán)限是能不能點(diǎn)某個菜單數(shù)據(jù)權(quán)限是看得到哪些數(shù)據(jù)兩者必須同時校驗(yàn)。功能模塊普通員工部門主管HR管理員系統(tǒng)管理員上下班打卡本人打卡本人打卡全部考勤全部考勤考勤記錄查詢僅本人本部門成員全公司全公司補(bǔ)卡/請假申請發(fā)起審批本部門審核/歸檔配置規(guī)則績效目標(biāo)與評分自評部門成員評分績效結(jié)果管理指標(biāo)庫配置工資條查看僅本人僅本人月度薪資核算薪資項配置用戶與權(quán)限管理無無用戶信息維護(hù)角色授權(quán)、菜單管理實(shí)際開發(fā)時我并沒有在前端寫死這些權(quán)限而是把菜單和按鈕都注冊成權(quán)限碼。比如員工端登錄后返回的菜單只有打卡、我的考勤、我的績效、我的工資條主管端多出團(tuán)隊考勤、待辦審批HR端則有考勤匯總、薪資核算、績效管理。后端每個接口都做權(quán)限注解校驗(yàn)避免前端隱藏菜單后接口還能被直接調(diào)用。1.2 考勤、薪酬、績效三件事的流轉(zhuǎn)關(guān)系很多初學(xué)管理系統(tǒng)的人會把考勤、薪酬、績效做成三個孤立模塊這是不對的。這三個模塊的數(shù)據(jù)是串起來的員工的打卡流水生成月度考勤匯總考勤匯總里的遲到次數(shù)、缺勤天數(shù)、加班時長直接進(jìn)薪資計算績效評分經(jīng)過加權(quán)匯總得到績效等級績效等級映射成績效系數(shù)再乘以績效獎金基數(shù)影響最終實(shí)發(fā)工資。我把這條鏈路簡化成一個公式應(yīng)發(fā)工資 基本工資 崗位工資 績效獎金基數(shù) × 績效系數(shù) 加班費(fèi) - 缺勤扣款 - 五險一金個人部分 - 個人所得稅?？记诤涂冃Ф汲蔀樾匠暧嬎闫鞯妮斎朐炊皇歉髯元?dú)立的數(shù)據(jù)孤島。這也是為什么系統(tǒng)里工資獨(dú)立于打卡和績效存在但每個月核算時又必須讀取這兩個模塊的結(jié)果。1.3 先把Excel里的潛規(guī)則翻譯成系統(tǒng)規(guī)則我花了一天時間和HR對需求發(fā)現(xiàn)Excel時代有很多“人肉規(guī)則”。比如遲到15分鐘以內(nèi)不扣錢只記錄超過15分鐘按半小時扣比如績效評分自評占30%、主管評分占70%比如工資條要求保留兩位小數(shù)但是必須四舍五入而非銀行家舍入。如果這些潛規(guī)則不提前變成系統(tǒng)里的配置項開發(fā)到一半就會因?yàn)椤斑@不對我們以前不是這么算的”反復(fù)推翻。所以我在系統(tǒng)里專門建了基礎(chǔ)配置模塊把考勤班次、遲到寬限分鐘數(shù)、績效系數(shù)映射表、薪資項配置全部做成數(shù)據(jù)庫表由管理員在界面上維護(hù)。代碼里只寫通用計算邏輯具體規(guī)則全部讀配置這是這套系統(tǒng)能落地的關(guān)鍵一步。2. 技術(shù)選型Python Vue3這個組合解了什么題技術(shù)?？雌饋硎恰皃ython vue3”但Python生態(tài)里Web框架那么多Vue3也有一堆配套庫真正決定開發(fā)效率的是具體選型。這一章我把我最終選的方案和理由講清楚順便說說對比之后放棄的方案。2.1 后端為什么用FastAPI而不是Flask或Django后端框架我對比過三個Flask、Django、FastAPI。Flask靈活但要自己拼很多組件搭一個帶數(shù)據(jù)庫遷移、參數(shù)校驗(yàn)、API文檔的項目需要額外裝一堆擴(kuò)展Django生態(tài)最全自帶Admin后臺和ORM但比較重對前端Vue3這種前后端完全分離的開發(fā)模式來說它的模板系統(tǒng)基本用不上還有點(diǎn)約束FastAPI是后起之秀基于Pydantic做參數(shù)校驗(yàn)?zāi)苌賹懞芏嘀貜?fù)代碼自帶Swagger文檔方便聯(lián)調(diào)性能在純Python框架里也很能打。最終我選了 FastAPI SQLAlchemy MySQL。FastAPI還有兩個很實(shí)用的特性一個是依賴注入我用來做角色權(quán)限校驗(yàn)另一個是異步接口打卡這類高頻寫入接口在上班高峰期不會因?yàn)閿?shù)據(jù)庫連接阻塞拖垮服務(wù)。對于中小型企業(yè)的考勤并發(fā)量這個組合非常夠用。2.2 前端為什么直接上Vue3 TypeScript Pinia Element PlusVue3的組合式APIComposition API相比Vue2的選項式API最大的優(yōu)勢是邏輯復(fù)用。考勤、審批、薪資核算這些頁面都有“查詢列表、加載狀態(tài)、分頁”的重復(fù)邏輯我用組合式函數(shù)封裝了通用的useTable、useForm每個頁面只用幾行代碼就能接上接口。因?yàn)檫@套系統(tǒng)角色多、權(quán)限邏輯復(fù)雜我選了TypeScript接口返回體、用戶信息、表格數(shù)據(jù)全部定義類型前端字段寫錯在編譯期就暴露了不用等到運(yùn)行時一臉懵。狀態(tài)管理用的Pinia而不是Vuex。Pinia的API更簡潔沒有Mutation那層概念store之間互相調(diào)用很自然。我用一個userStore存登錄用戶信息和角色一個permStore存動態(tài)路由和按鈕權(quán)限。Element Plus負(fù)責(zé)后臺管理系統(tǒng)的UI組件表格、表單、彈窗、日期選擇器這些都能滿足圖表部分直接上ECharts工資趨勢、部門遲到率這些可視化報表用它畫非常簡單。2.3 前后端聯(lián)調(diào)約定前后端分離的項目最怕接口規(guī)范不統(tǒng)一。我一開始就定了一套標(biāo)準(zhǔn)響應(yīng)結(jié)構(gòu)所有接口統(tǒng)一返回 stateCode、message、data 三個字段成功時 stateCode 為200業(yè)務(wù)錯誤用400或自定義錯誤碼。前端封裝了一個axios實(shí)例攔截器里統(tǒng)一處理token過期、錯誤提示后端接口只需要返回數(shù)據(jù)或拋異常前端不用在每個頁面寫重復(fù)的錯誤判斷邏輯。登錄認(rèn)證用的JWT前端登錄后把token存在localStorageaxios請求頭自動帶Authorization: Bearer 。前端路由守衛(wèi)每次跳轉(zhuǎn)前檢查token和角色無權(quán)限直接重定向到登錄頁或401頁面。這套約定讓前后端可以并行開發(fā)后端寫接口的同時前端用Mock聯(lián)調(diào)最后合在一起只處理少量字段差異。3. 數(shù)據(jù)庫建?？记诹魉?、績效表、薪酬表怎么設(shè)計才不打架數(shù)據(jù)庫設(shè)計是這類系統(tǒng)的地基。我的經(jīng)驗(yàn)是寧可多拆表不要把什么都塞進(jìn)一張大寬表?？记诹魉歉哳l插入數(shù)據(jù)薪資是每月結(jié)算數(shù)據(jù)績效是按季度或月度產(chǎn)生的評估數(shù)據(jù)它們的數(shù)據(jù)特征完全不同拆開建表不僅邏輯清晰還能避免一張表字段爆炸導(dǎo)致后來加需求無從下手。3.1 用戶、部門與角色的表結(jié)構(gòu)用戶這塊我建了三張核心表sys_user 用戶表、sys_dept 部門表、sys_role 角色表。用戶表不直接存角色名字符串而是通過關(guān)系表把用戶和角色關(guān)聯(lián)起來因?yàn)橐粋€用戶可能有多個角色。用戶表里必須包含的基本信息包括用戶名、密碼哈希、姓名、手機(jī)號、部門ID、崗位、入職日期、在職狀態(tài)。密碼存儲必須用哈希我用的bcrypt絕對不允許明文存密碼。部門表做了一層父子級結(jié)構(gòu)用 parent_id 表示層級關(guān)系方便主管能看到子部門成員的數(shù)據(jù)。角色表里除了角色名還可以加一個 data_scope 字段比如“僅本人”“本部門”“全公司”HR的考勤匯總頁就是靠這個字段控制數(shù)據(jù)范圍的。3.2 考勤流水與月度匯總考勤模塊我建了班次表、打卡流水表、月度匯總表。班次表存上下班時間規(guī)則比如上午 09:00-12:00、下午 13:30-18:00可配置彈性寬限分鐘數(shù)。打卡流水表記錄每一次打卡事件字段包括用戶ID、打卡日期、打卡時間、打卡類型上班/下班以及打卡來源指紋機(jī)導(dǎo)入、手機(jī)定位、二維碼還有GPS坐標(biāo)方便后端做位置校驗(yàn)。這里有個重要設(shè)計打卡流水只負(fù)責(zé)“記”不負(fù)責(zé)“算”。每天每個人可能多條流水比如早上打了一次、中午補(bǔ)打了一次判斷哪條是有效打卡的邏輯比較復(fù)雜。所以我單獨(dú)建了一張考勤月度匯總表每天晚上通過定時任務(wù)自動計算每個人的出勤天數(shù)、遲到次數(shù)、早退次數(shù)、缺勤天數(shù)、請假天數(shù)、加班時長。這樣HR核算薪資時直接查匯總表不需要實(shí)時重算全部流水。3.3 績效指標(biāo)、評分與等級映射績效模塊我拆成三張表績效指標(biāo)表存“客戶滿意度”“項目完成度”“團(tuán)隊協(xié)作”這類評分項每個指標(biāo)有名稱、分值上限、權(quán)重績效評分表存具體的評分記錄包含被評人、評分類別自評/主管評、各項得分、評分狀態(tài)績效結(jié)果表則存最終加權(quán)總分、績效等級、績效系數(shù)。為什么要把評分記錄和最終結(jié)果分開因?yàn)樵u分過程是動態(tài)的主管可以多次修改自評未提交、主管未評分這些狀態(tài)需要區(qū)分。而績效結(jié)果一旦確認(rèn)就要凍結(jié)供薪資計算使用不能因?yàn)楦牧四硞€評分項讓歷史工資跟著變。等級映射規(guī)則也是可配置的總分≥90定A級績效系數(shù)1.280-89定B級系數(shù)1.070-79定C級系數(shù)0.8低于70定D級系數(shù)0.5。3.4 薪酬表薪資項配置與月度工資薪酬模塊我建了薪資項配置表和月度工資表。薪資項配置表用來定義有哪些薪資組成比如基本工資5000、崗位工資3000、績效獎金基數(shù)2000、全勤獎200以及扣款項養(yǎng)老保險、醫(yī)療保險、失業(yè)保險、公積金、個稅。這些配置項通過一個 type 字段區(qū)分是加項還是減項加項在計算時相加減項在計算時扣除。月度工資表保存每個員工某個月的核算結(jié)果字段包括月份、用戶ID、各薪資項金額、應(yīng)發(fā)工資、應(yīng)扣部分、實(shí)發(fā)工資、核算狀態(tài)。核算狀態(tài)我用了一個狀態(tài)流草稿、待審核、已發(fā)布、已歸檔。新版工資算出來后先存草稿HR核對沒問題審核審核后員工才能看到工資條歸檔就鎖定數(shù)據(jù)不能修改。這個狀態(tài)機(jī)幫我和HR省去了大量“手滑改錯工資”的麻煩。4. 后端核心邏輯打卡判重、遲到計算、薪資核算怎么實(shí)現(xiàn)數(shù)據(jù)庫設(shè)計好后真正見功夫的是業(yè)務(wù)接口里的核心算法。這一章全是能直接復(fù)用的Python邏輯包括打卡接口怎么寫才能防止重復(fù)提交、遲到早退怎么和班次配置關(guān)聯(lián)、薪資計算怎么保證金額精度。4.1 打卡API與防重復(fù)提交打卡接口是員工每天用最多的接口高頻操作最需要防重。我設(shè)計的接口流程是拿到當(dāng)前登錄用戶的ID、打卡時的GPS坐標(biāo)、定位半徑后端先查班次表得到今天的上下班時間范圍然后判斷當(dāng)前時間落在哪個時段。如果當(dāng)前時間在上班時段內(nèi)打卡類型為上班如果在下班時段內(nèi)打卡類型為下班。判重邏輯很簡單但容易被忽略同一個用戶、同一天、同一種打卡類型只能有一條記錄。我用了一個數(shù)據(jù)庫唯一約束 guarantee在打卡時間上直接加“同一個 user_id、clock_date、clock_type 不能重復(fù)”的聯(lián)合唯一索引從數(shù)據(jù)庫層面防止重復(fù)插入而不是只靠代碼里的if判斷。GPS校驗(yàn)則使用 geopy 計算打卡坐標(biāo)和公司坐標(biāo)的距離超過設(shè)置的半徑比如200米就拒絕打卡提示“不在考勤范圍內(nèi)”。router.post(/attendance/clock) async def clock_in(payload: ClockPayload, user: User Depends(get_current_user)): today datetime.now().date() # 同一用戶同一天同類型只能打一次卡數(shù)據(jù)庫聯(lián)合唯一索引兜底 exists db.query(AttendanceRecord).filter( AttendanceRecord.user_id user.id, AttendanceRecord.clock_date today, AttendanceRecord.clock_type payload.clock_type, ).first() if exists: raise HTTPException(status_code400, detail今日該時段已打卡不能重復(fù)提交) distance geopy.distance.distance((user.lat, user.lng), (payload.lat, payload.lng)).meters if distance configured_radius: raise HTTPException(status_code400, detail不在考勤范圍內(nèi)) record AttendanceRecord( user_iduser.id, clock_datetoday, clock_timedatetime.now().time(), clock_typepayload.clock_type, latpayload.lat, lngpayload.lng, sourceAPP, ) db.add(record) db.commit() return JSONResponse({stateCode: 200, message: 打卡成功})4.2 遲到、早退、缺勤的判定邏輯打卡流水記錄好了考勤匯總邏輯才是HR真正關(guān)心的。我用了兩個配置參數(shù)上班時間 09:00、寬限分鐘數(shù) 15。打卡時間晚于9:00且不超過9:15判定為“正常但遲到一次”不扣款只是記錄晚于9:15但不超過9:45判定為遲到按遲到時長扣工資超過9:45則直接判定為半天曠工。早退的邏輯剛好反過來下班時間早于18:00判定早退早退超過1小時算半天曠工。這一整套判定我寫成一個純函數(shù)輸入是班次配置和打卡流水輸出是考勤狀態(tài)方便單元測試和復(fù)用。def calc_daily_attendance(on_time, off_time, config): # 判斷上班狀態(tài) if on_time is None: work_status ABSENT # 無打卡記錄默認(rèn)缺勤 elif on_time config.late_grace_deadline: # 比如 09:15 work_status NORMAL elif on_time config.late_cutoff: # 比如 09:45 work_status LATE else: work_status HALF_ABSENT # 判斷下班狀態(tài) if off_time is None: leave_status ABSENT elif off_time config.off_time: # 18:00 leave_status NORMAL elif off_time config.early_cutoff: # 17:00 以前走算早退嚴(yán)重 leave_status EARLY else: leave_status HALF_ABSENT return work_status, leave_status加班時長計算我用了這樣的規(guī)則工作日下班后超過30分鐘開始累計不足1小時按1小時計周末加班需要走審批有審批單才算加班。加班費(fèi)倍率默認(rèn)工作日1.5倍休息日2倍法定節(jié)假日3倍這些倍率也全部放配置表。4.3 薪資計算器的精度問題處理工資計算最容易被忽視的問題就是浮點(diǎn)數(shù)精度。Python里 0.1 0.2 的結(jié)果不是0.3而是0.30000000000000004如果工資表用float直接算最后實(shí)發(fā)工資會出現(xiàn)一分的誤差。我所有金額字段在數(shù)據(jù)庫里用 Decimal(10,2)后端代碼里全程用 decimal.Decimal 運(yùn)算絕對不碰float。四舍五入規(guī)則也要統(tǒng)一。Python內(nèi)置的 round 做的是銀行家舍入round(2.675, 2) 結(jié)果不是2.68而是2.67這在工資里會出大問題。我封裝了一個統(tǒng)一換算函數(shù)使用 ROUND_HALF_UP 模式所有金額先算到小數(shù)點(diǎn)后4位再四舍五入到2位。from decimal import Decimal, ROUND_HALF_UP def money(value): return Decimal(value).quantize(Decimal(0.01), roundingROUND_HALF_UP) def calc_salary(base, post, perf_base, perf_coef, overtime_hours, late_count): total money(base) money(post) money(perf_base) * perf_coef total money(overtime_hours) * money(25) # 每小時加班費(fèi)示例 total - money(late_count) * money(30) # 每次遲到扣30示例 return total薪資計算的輸入數(shù)據(jù)來自三個地方員工基礎(chǔ)檔案里的基本工資和崗位工資、考勤匯總表里的遲到次數(shù)與加班時長、績效結(jié)果表里的績效系數(shù)。我寫了一個核算任務(wù)先把全公司所有員工的薪資明細(xì)算成草稿HR界面上能看到每個人的計算明細(xì)確認(rèn)無誤后一鍵審核發(fā)布。算錯了也不用慌未發(fā)布之前可以重新核算覆蓋草稿。4.4 績效評分加權(quán)匯總與系數(shù)聯(lián)動績效評分做了一個加權(quán)匯總每個員工每個指標(biāo)有兩個分自評分和主管評分最終指標(biāo)分 自評分 × 0.3 主管評分 × 0.7?？偡质撬兄笜?biāo)分乘以權(quán)重的總和。比如“項目完成度”權(quán)重40%自評90主管評80那這個指標(biāo)分值就是 90×0.380×0.783再乘以40%得到33.2分所有這樣算出來的分?jǐn)?shù)加起來就是總分?？偡殖鰜碇笥玫鹊谟成浜瘮?shù)轉(zhuǎn)換成A/B/C/D等級和績效系數(shù)。這個系數(shù)會傳到薪酬接口作為績效獎金基數(shù)的倍數(shù)。我在代碼里明確返回等級和系數(shù)避免HR手工填數(shù)字?？冃ЫY(jié)果的每次修改都保留審計記錄誰改的、改了什么、什么時候改的全部存在記錄表里防止績效申訴時說不清。5. 前端Vue3落地四個角色怎么進(jìn)入各自的頁面前端是我花時間最多的部分不是因?yàn)閂ue3難而是角色權(quán)限和頁面交互細(xì)節(jié)多。我的核心思路是動態(tài)路由 組合式函數(shù) 組件化頁面讓四個角色登錄后看到完全不同的操作臺。5.1 動態(tài)路由、菜單權(quán)限與登錄跳轉(zhuǎn)前端權(quán)限的核心邏輯在路由守衛(wèi)里。我定義了一份靜態(tài)路由包含login、404、403這些公共頁面業(yè)務(wù)頁面全部走動態(tài)路由后端根據(jù)登錄用戶的角色返回對應(yīng)的菜單和路由表。前端在Pinia里存路由表每次路由跳轉(zhuǎn)前先判斷當(dāng)前用戶的路由是否存在不存在就動態(tài) addRoute。四個角色登錄后的默認(rèn)首頁我做了差異化員工默認(rèn)跳打卡頁主管默認(rèn)跳待辦審批HR默認(rèn)跳考勤匯總看板系統(tǒng)管理員默認(rèn)跳用戶管理。這樣登錄后不用點(diǎn)來點(diǎn)去找入口。菜單權(quán)限用v-permission這樣的自定義指令控制按鈕級別比如員工沒有“導(dǎo)出工資表”按鈕渲染時直接過濾掉不能只靠隱藏按鈕來防越權(quán)后端接口權(quán)限依然要嚴(yán)格校驗(yàn)。router.beforeEach(async (to) { const userStore useUserStore(); if (!userStore.token) { if (to.path /login) return true; return { path: /login, query: { redirect: to.fullPath } }; } if (!userStore.routesLoaded) { const menuRoutes await userStore.fetchUserRoutes(); // 從后端拉角色路由 menuRoutes.forEach((route) router.addRoute(route)); return { ...to, replace: true }; } if (to.meta?.roles !to.meta.roles.includes(userStore.role)) { return /403; } return true; });5.2 員工端定位打卡頁和工資條頁打卡頁我用了Vue3的響應(yīng)式API頁面加載時調(diào)用瀏覽器的定位接口拿到經(jīng)緯度后實(shí)時顯示當(dāng)前位置和距公司的距離。如果定位失敗用戶拒絕授權(quán)頁面只能手動輸入定位驗(yàn)證碼或者改用公司W(wǎng)iFi名匹配方案這個作為兜底。打卡按鈕會根據(jù)今天是否已打卡自動置灰并顯示打卡時間避免員工反復(fù)點(diǎn)擊。工資條頁是一個典型的“一人一張表”頁面。我查接口拿到當(dāng)前用戶某個月份的應(yīng)發(fā)項、扣款項、實(shí)發(fā)工資用卡片式布局展示。下面再用ECharts畫一個最近6個月的工資趨勢折線圖應(yīng)發(fā)和實(shí)發(fā)兩條線員工能直觀看到自己的工資變化。因?yàn)楣べY數(shù)據(jù)敏感前端拿到后我還要做脫敏顯示默認(rèn)部分字段用星號遮擋點(diǎn)擊“查看”按鈕才展示完整金額。5.3 主管端補(bǔ)卡、請假與績效評分審批流主管端最核心的頁面是待辦審批。我做了兩個Tab考勤審批補(bǔ)卡、請假和績效評分。考勤審批列表用卡片顯示申請人的姓名、申請類型、申請理由、申請時間主管點(diǎn)進(jìn)詳情能看到該員工當(dāng)天考勤流水和所在部門的平均考勤時間作為審批參考。批準(zhǔn)或駁回接口會更新申請單狀態(tài)同時通知員工用的簡短的站內(nèi)信?？冃гu分頁我面對一個現(xiàn)實(shí)問題主管同時給多個下屬評分單個頁面來回切換效率低。所以評分頁做了表格批量模式一屏顯示該主管名下的所有下屬、所有評分指標(biāo)主管在表格里直接打分支持草稿保存全部打完再一鍵提交。提交后狀態(tài)變更員工端馬上能看到自評分和最終分。5.4 HR端考勤看板與月度薪酬核算頁HR端的首頁是考勤看板我用ECharts做三塊可視化一個日歷熱力圖顯示全公司每天的打卡率一個柱狀圖統(tǒng)計各部門遲到率排名一個餅圖展示出勤狀態(tài)分布正常、遲到、早退、缺勤、請假。每張圖都可下鉆點(diǎn)擊某個部門跳轉(zhuǎn)到部門明細(xì)列表讓HR能快速定位考勤異常集中點(diǎn)。薪酬核算頁則用了類似Excel的表格界面左側(cè)勾選要核算的部門點(diǎn)“生成草稿”后表格里列出每個員工的基本工資、績效獎金、加班費(fèi)、扣款、應(yīng)發(fā)、實(shí)發(fā)。HR雙擊某個單元格可以查看這筆金額的計算明細(xì)比如績效獎金后面有個小鏈接點(diǎn)開能看到績效系數(shù)來源。確認(rèn)無誤后點(diǎn)“審核通過”系統(tǒng)給所有員工發(fā)工資條生成通知這個頁面是最能體現(xiàn)系統(tǒng)替代Excel價值的。6. 聯(lián)調(diào)、部署與踩坑記錄一個項目做完不難難的是聯(lián)調(diào)階段遇到的問題排查。這一章記錄我在這個項目里真實(shí)踩過并且解決了的坑每一個都有具體原因和修復(fù)辦法復(fù)現(xiàn)概率很高。6.1 時區(qū)Bug打卡時間憑空多了8小時部署上線第一天HR就發(fā)現(xiàn)所有員工的打卡時間顯示成了下午而不是上午。這個Bug的根因是前端瀏覽器用的是本地時區(qū)而服務(wù)器默認(rèn)時區(qū)是UTC前端傳時間戳給后端后端直接 new Date() 格式化得到的是UTC時間導(dǎo)致顯示時間比真實(shí)時間少了8小時。修復(fù)方案是在后端啟動時強(qiáng)制設(shè)置時區(qū)為Asia/Shanghai同時數(shù)據(jù)庫連接串里也要加 serverTimezoneAsia/Shanghai。前端統(tǒng)一用時間戳傳參展示時再按客戶端時區(qū)格式化。日期字符串不要用“YYYY-MM-DD HH:mm:ss”這種格式跨端傳解析歧義太大我直接全換成了時間戳。6.2 計算金額出現(xiàn)一堆小數(shù)點(diǎn)聯(lián)調(diào)時發(fā)現(xiàn)工資明細(xì)表里出現(xiàn)一串6666.666666666666之類的數(shù)字。排查后確認(rèn)是薪資計算時把 Decimal 和 float 混用了比如績效獎金基數(shù)存的是Decimal但績效系數(shù)是float兩者相乘后精度被污染。我定了一個硬規(guī)則金額字段在數(shù)據(jù)庫、后端、前端任何環(huán)節(jié)都統(tǒng)一字符串或Decimal不在計算中途用float。前端表格拿到后端返回的數(shù)字也用toFixed(2)顯示防止出現(xiàn)浮點(diǎn)尾巴。6.3 前端跨域與生產(chǎn)環(huán)境部署開發(fā)環(huán)境通過Vite的 proxy 把 /api 代理到后端地址能友好解決跨域問題。但部署到生產(chǎn)環(huán)境時不能依賴前端的代理配置我用Nginx做了統(tǒng)一的反向代理前端靜態(tài)文件放在 /dist后端 uvicorn 監(jiān)聽 127.0.0.1:8000Nginx把 /api 開頭的請求轉(zhuǎn)發(fā)到后端服務(wù)。這樣瀏覽器訪問的始終是同一個域名不會產(chǎn)生跨域。Nginx配置里我特別加了處理history路由的規(guī)則Vue3用history模式時前端路由刷新會出現(xiàn)404需要在location / 里加 try_files $uri $uri/ /index.html;。這個配置忘了加生產(chǎn)環(huán)境刷新頁面就白屏排查了半天。6.4 權(quán)限緩存員工切換角色后跳回舊菜單后臺測試時發(fā)現(xiàn)一個隱蔽問題用戶退出登錄后再換一個賬號登錄顯示的還是上一個賬號的菜單權(quán)限。原因是動態(tài)路由在Pinia和Vue Router里已經(jīng)注冊過了退出登錄時只清空了token沒有重置路由表和新賬號的權(quán)限store。修復(fù)方式是封裝一個 resetPermission 函數(shù)退出登錄時遍歷當(dāng)前路由表把動態(tài)添加的路由逐條移除再重置Pinia里對應(yīng)的store狀態(tài)。不能只是頁面跳轉(zhuǎn)整個應(yīng)用狀態(tài)必須重新初始化。同樣的邏輯也適用于賬號被管理員修改角色之后必須重新登錄才能生效因?yàn)榕f的路由表帶著舊的權(quán)限碼。我還遇到過pandas方式導(dǎo)入Excel考勤數(shù)據(jù)時時間字段被識別成數(shù)字的情況排查下來是Excel里的時間列被設(shè)置成了自定義格式標(biāo)準(zhǔn)pandas read_excel解析出來是datetime格式但有些導(dǎo)出工具生成的是文本需要在導(dǎo)入時先做統(tǒng)一轉(zhuǎn)換。我的建議是規(guī)范導(dǎo)入模板列的格式并寫try-except兜住異常數(shù)據(jù)寧可讓HR手動改一行也不要導(dǎo)入時靜默丟棄。這套系統(tǒng)內(nèi)部跑了三個月累積了上千條打卡記錄每月工資核算從過去的大半天縮短到十幾分鐘。給還在猶豫選什么技術(shù)棧的朋友一個建議管理系統(tǒng)這類業(yè)務(wù)系統(tǒng)別追求新框架Python FastAPI Vue3這套組合從開發(fā)效率、類型安全、生態(tài)成熟度上都夠用了。里面最難的不是寫接口而是把考勤遲到怎么算、績效系數(shù)怎么映射這類業(yè)務(wù)規(guī)則真正做成可配置的能力這一層想透了系統(tǒng)才算真正立得住。