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