實(shí)戰(zhàn)：從拆包到上線避坑指南)
簡介這套辦公自動(dòng)化系統(tǒng)源碼采用Java語言開發(fā)基于Spring Boot框架并結(jié)合MySQL數(shù)據(jù)庫與Maven構(gòu)建工具面向需要學(xué)習(xí)企業(yè)級(jí)應(yīng)用開發(fā)流程的初中級(jí)Java工程師也適合高校學(xué)生用于課程設(shè)計(jì)或畢業(yè)設(shè)計(jì)參考。整個(gè)資源壓縮包共包含1031個(gè)文件整體大小約5.49兆字節(jié)文件結(jié)構(gòu)較為完整其中237個(gè)Java源文件覆蓋了后端控制層、服務(wù)層與數(shù)據(jù)訪問層的核心邏輯152個(gè)FreeMarker模板和39個(gè)HTML文件用于渲染頁面85個(gè)JavaScript文件與56個(gè)CSS文件分別處理前端交互效果和頁面樣式另有20張JPG圖片以及大量GIF動(dòng)圖可直觀展示系統(tǒng)運(yùn)行流程。附帶SQL數(shù)據(jù)庫腳本可幫助使用者快速搭建本地環(huán)境。通過研讀源碼能夠理解OA系統(tǒng)中的審批流程、權(quán)限分配、消息提醒等常見模塊的設(shè)計(jì)思路并可直接將部分代碼改造成自有項(xiàng)目。目前已有1899人學(xué)習(xí)下載口碑較好適合實(shí)戰(zhàn)練手。1. Java開發(fā)OA自動(dòng)化辦公系統(tǒng)源碼包能干什么一個(gè)OA自動(dòng)化辦公系統(tǒng)的源碼包在Java工程師手里往往不是“打開即用”的成品而是拆開揉碎后二次開發(fā)的骨架。以我接手過的多個(gè)類似源碼包來看這類項(xiàng)目通常圍繞三塊核心展開審批流引擎、表單設(shè)計(jì)器、組織權(quán)限模型其余考勤、公告、會(huì)議都是在這三塊上長出來的枝葉。你能用它快速搭起企業(yè)的請(qǐng)假、報(bào)銷、用印審批也能把流轉(zhuǎn)了半年的紙質(zhì)簽批一次性搬到線上。適合正在選型的小型團(tuán)隊(duì)也適合拿來做Java課程設(shè)計(jì)或畢業(yè)設(shè)計(jì)的同學(xué)或者想在Spring Boot MyBatis-Plus這條技術(shù)棧上找一套完整案例的工程師。這篇文章就按“源碼結(jié)構(gòu)長什么樣 → 怎么跑起來 → 核心模塊怎么改 → 踩過哪些坑 → 上線前還要做什么”的順序把這條路走一遍。2. 先拆包再動(dòng)手看清OA源碼包的技術(shù)棧與工程結(jié)構(gòu)2.1 從pom.xml判斷項(xiàng)目血緣Spring Boot版本和依賴全家桶Java OA源碼包最常見的組織方式是Maven多模塊工程拿到手第一件事不是解壓就跑而是打開根目錄的pom.xml看血緣。絕大多數(shù)OA源碼基于Spring Boot MyBatis-Plus Vue這套組合少數(shù)老項(xiàng)目還在用Spring MVC JSP。判斷依據(jù)很直接看parent標(biāo)簽里的Spring Boot版本看有沒有mybatis-plus-boot-starter再看前端是獨(dú)立目錄還是靜態(tài)資源塞在后端里。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter/artifactId version6.7.2/version /dependency /dependencies為什么這套組合在OA源碼里成為事實(shí)標(biāo)準(zhǔn)MyBatis-Plus的BaseMapper讓CRUD零SQL這對(duì)表單、部門、用戶這類固定結(jié)構(gòu)的表特別合適Flowable提供BPMN流程定義和任務(wù)節(jié)點(diǎn)的底層能力。關(guān)鍵是這兩者的學(xué)習(xí)曲線都算平緩源碼包使用者能在一天內(nèi)把“業(yè)務(wù)表如何映射為UserMapper、流程如何發(fā)起為一個(gè)ProcessInstance”這層對(duì)應(yīng)關(guān)系摸透?？吹揭蕾?yán)镉衋ctiviti或flowable說明審批流是走標(biāo)準(zhǔn)BPMN引擎如果沒有工作流依賴那多半是自研的節(jié)點(diǎn)表 狀態(tài)機(jī)這種要重點(diǎn)評(píng)估流程設(shè)計(jì)的靈活度別等上線后才去補(bǔ)“駁回、會(huì)簽、加簽”這類復(fù)雜流轉(zhuǎn)。2.2 目錄結(jié)構(gòu)里的公共約定模塊拆分與包命名的門道我見過幾十個(gè)OA源碼包后得出一個(gè)經(jīng)驗(yàn)不要看Readme寫了什么要看包名怎么分。規(guī)范的工程一般拆成oa-common通用工具、異常、常量、oa-system用戶、角色、菜單、部門、oa-workflow流程定義、任務(wù)、歷史、oa-business報(bào)銷單、請(qǐng)假單、用印申請(qǐng)和前端目錄。包名按業(yè)務(wù)域而不是按層拆意味著后續(xù)加需求時(shí)知道自己該改哪個(gè)模塊。oa-parent ├── oa-common # 工具類、統(tǒng)一返回、異常碼 ├── oa-system # 組織、用戶、角色、菜單權(quán)限 ├── oa-workflow # 流程部署、任務(wù)處理、流程實(shí)例 ├── oa-business # 各種業(yè)務(wù)單據(jù) ├── oa-api # 對(duì)外接口REST DTO ├── sql/ # 初始化腳本和示例數(shù)據(jù) └── web/ # Vue前端工程拿到源碼包先對(duì)照這個(gè)結(jié)構(gòu)檢查少一個(gè)模塊并不致命但要有意識(shí)地找補(bǔ)沒有oa-workflow說明審批是死寫在業(yè)務(wù)代碼里的沒有sql目錄說明數(shù)據(jù)庫腳本要靠逆向工程導(dǎo)出。這兩個(gè)缺項(xiàng)決定了你是把包當(dāng)作“可運(yùn)行系統(tǒng)”還是“參考腳手架”。前端如果是Vue3 Element Plus注意Node版本要在16以上Vue2則12即可這個(gè)版本錯(cuò)位常讓很多人卡在npm install那一步后面避坑章會(huì)展開說。2.3 核心表結(jié)構(gòu)設(shè)計(jì)用戶、角色、菜單與審批流的關(guān)系鏈OA系統(tǒng)的數(shù)據(jù)模型有一個(gè)相對(duì)固定的范式sys_user、sys_role、sys_user_role、sys_menu、sys_role_menu這五張表構(gòu)成權(quán)限主體act_ru_task、act_ru_execution、act_hi_procinst、act_hi_taskinst這組ACT前綴的表由Flowable自動(dòng)創(chuàng)建。CREATE TABLE sys_user ( user_id BIGINT NOT NULL COMMENT 用戶ID, dept_id BIGINT COMMENT 部門ID, username VARCHAR(30) NOT NULL COMMENT 登錄賬號(hào), password VARCHAR(100) NOT NULL COMMENT 密碼BCrypt加密, nick_name VARCHAR(30) COMMENT 姓名, email VARCHAR(50) COMMENT 郵箱, phonenumber VARCHAR(11) COMMENT 手機(jī)號(hào), status CHAR(1) DEFAULT 0 COMMENT 狀態(tài)0正常1停用, create_time DATETIME COMMENT 創(chuàng)建時(shí)間, PRIMARY KEY (user_id) ) ENGINEInnoDB COMMENT用戶信息表;這張sys_user表幾乎是所有Java OA源碼里必有的表字段名也高度一致根本原因是大量二開項(xiàng)目都從同一個(gè)開源基線出來。你在拿到自己那份源碼時(shí)重點(diǎn)核對(duì)的不是字段多少而是“密碼字段是否用了BCrypt加密”“部門是否掛在dept_id外鍵上”。權(quán)限這塊要再做一層驗(yàn)證菜單表里如果每行都有perms字符串如system:user:add說明走的是Spring Security的PreAuthorize注解鑒權(quán)如果只能在按鈕上綁個(gè)布爾值那基本是前端路由攔截后端不設(shè)防上線會(huì)很被動(dòng)。3. 把OA源碼在本地跑起來數(shù)據(jù)庫初始化與啟動(dòng)全流程3.1 準(zhǔn)備JDK、Maven與MySQL環(huán)境版本匹配是玄學(xué)要當(dāng)回事跑OA源碼前最容易被忽視的是版本匹配。Spring Boot 2.7.x要求JDK 8或11JDK 17也能跑但部分舊依賴會(huì)有反射告警MySQL建議5.7或8.0連接驅(qū)動(dòng)要帶cj前綴。先檢查java -version和mvn -v不要等到編譯報(bào)錯(cuò)再回頭折騰。# 檢查本機(jī)環(huán)境這里假設(shè)JDK 8/11、Maven 3.6、MySQL 5.7 java -version mvn -v mysql -uroot -p很多源碼發(fā)行時(shí)是在局域網(wǎng)內(nèi)網(wǎng)編譯的Maven中央倉庫可能拉不到內(nèi)網(wǎng)私服上的自研依賴最穩(wěn)妥的做法是一開始就強(qiáng)制離線編譯一次看缺什么再聯(lián)網(wǎng)補(bǔ)。改完pom里依賴版本后要先用mvn clean compile驗(yàn)證能否通過編譯再用mvn spring-boot:run啟動(dòng)。這一步能提前暴露“本地類重復(fù)”或“flowable版本和mybatis沖突”這類麻煩。3.2 導(dǎo)入數(shù)據(jù)庫腳本別急著一鍵執(zhí)行先看編碼和表前綴OA源碼包里都會(huì)放一份初始化SQL常見命名是oa_init.sql或oa_db_2023.sql。導(dǎo)入前必須用文本編輯器打開看兩點(diǎn)第一建庫語句里的utf8mb4和排序規(guī)則是否一致第二是否有CREATE DATABASE如果有說明這個(gè)腳本假設(shè)你現(xiàn)在連的是一個(gè)空實(shí)例。mysql -uroot -p sql/oa_init.sql # 檢查前10張表是否建成功 mysql -uroot -p -e use oa; show tables;如果腳本是分庫導(dǎo)出的比如每個(gè)業(yè)務(wù)模塊單獨(dú)的schema那你得手動(dòng)把oa-workflow、oa-business的腳本按順序執(zhí)行。這里有個(gè)常見坑flowable建表腳本往往被放在程序啟動(dòng)時(shí)自動(dòng)執(zhí)行不需要手動(dòng)導(dǎo)入但很多源碼包把ACT前綴表的CREATE語句也合并到了初始化SQL里兩套腳本同時(shí)運(yùn)行會(huì)報(bào)表已存在。我的習(xí)慣是先手動(dòng)執(zhí)行業(yè)務(wù)表腳本啟動(dòng)時(shí)用Flowable的databaseSchemaUpdate配置項(xiàng)去自動(dòng)補(bǔ)齊流程表。3.3 修改application.yml數(shù)據(jù)源配置并啟動(dòng)后端服務(wù)默認(rèn)配置里數(shù)據(jù)庫地址往往指向開發(fā)機(jī)的內(nèi)網(wǎng)IP這臺(tái)機(jī)器關(guān)機(jī)了你就連不上。把URL改成localhost同時(shí)把賬號(hào)密碼改成自己本地的。推薦把密碼用環(huán)境變量引用而不是寫死在代碼里這樣后續(xù)部署到服務(wù)器不用改一堆源碼。server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/oa?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLfalseserverTimezoneAsia/Shanghai username: root password: ${DB_PASSWORD:root} servlet: multipart: max-file-size: 100MB max-request-size: 200MB flowable: database-schema-update: true async-executor-activate: true注意url里serverTimezoneAsia/Shanghai這一項(xiàng)很多人在這一步翻車因?yàn)镸ySQL 8默認(rèn)時(shí)區(qū)是UTC導(dǎo)致系統(tǒng)里所有待辦時(shí)間差8個(gè)小時(shí)。如果你拿到的源碼里沒有這個(gè)參數(shù)啟動(dòng)后登錄進(jìn)去看審批時(shí)間全是亂的第一反應(yīng)先補(bǔ)時(shí)區(qū)參數(shù)重啟別去查代碼。3.4 啟動(dòng)前端工程npm install兩個(gè)常見的卡殼點(diǎn)前端工程如果是Vue2把package.json里node-sass替換成sass才能過安裝Vue3則要小心Element Plus版本和Vite版本。啟動(dòng)命令都差不多cd web npm install npm run dev如果npm install慢或直接卡住大概率是registry源的問題改成淘寶鏡像源再試。npm config set registry https://registry.npmmirror.com npm install前端啟動(dòng)后訪問 http://localhost:80 或http://localhost:3000 具體端口看vue.config.js里配置。我建議先把前端代理配好再登錄代理配置通常長這樣// vue.config.js module.exports { devServer: { port: 80, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }不理解這段代理也沒關(guān)系你只需要知道前端請(qǐng)求 /api/login會(huì)被轉(zhuǎn)發(fā)到后端8080端口如果漏了這段登錄永遠(yuǎn)報(bào)403或404。一旦看到Network里的請(qǐng)求狀態(tài)碼從404變成200基本就算跑通了。4. 撕開OA系統(tǒng)的核心審批流引擎、表單設(shè)計(jì)器與權(quán)限模型4.1 審批流到底有多難為什么大多數(shù)源碼包不敢用Flowable很多自稱OA的源碼實(shí)際上沒有真正的流程引擎只在業(yè)務(wù)表里加了一個(gè)status字段用if else判斷“當(dāng)前誰可以批”。這種實(shí)現(xiàn)在考勤這種一朵流程是夠的一旦扯上報(bào)銷、采購、用印、轉(zhuǎn)正這些多節(jié)點(diǎn)會(huì)簽代碼會(huì)迅速腐化成一坨硬編碼。專業(yè)源碼會(huì)用Flowable或Activiti這類BPMN引擎流程定義是一個(gè)獨(dú)立的XML文件掛上表單JSON運(yùn)行時(shí)引擎根據(jù)當(dāng)前節(jié)點(diǎn)查審批人再往待辦表里插一條記錄。我見過太多二次開發(fā)團(tuán)隊(duì)在“要不要上引擎”上反復(fù)橫跳最后因?yàn)榧雍炐枨髷∠玛噥?。這里選擇Flowable的理由是它社區(qū)活躍、文檔全、Spring Boot集成最順手而且大部分源碼包已經(jīng)是對(duì)接好的你不需要從零設(shè)計(jì)表結(jié)構(gòu)。4.2 一張審批流程定義表BPMN XML里的節(jié)點(diǎn)與條件映射在這里先看一個(gè)請(qǐng)假流程的BPMN定義流程里兩個(gè)用戶任務(wù)節(jié)點(diǎn)分別分配給部門經(jīng)理和人事。process idleaveProcess name請(qǐng)假流程 isExecutabletrue startEvent idstartEvent name開始/ userTask idtaskManager name部門經(jīng)理審批 flowable:assignee${applyUser.managerId}/ userTask idtaskHR name人事審批 flowable:assignee${applyUser.hrId}/ endEvent idendEvent name結(jié)束/ sequenceFlow idflow1 sourceRefstartEvent targetReftaskManager/ sequenceFlow idflow2 sourceReftaskManager targetReftaskHR conditionExpression xsi:typetFormalExpression ![CDATA[${passtrue}]] /conditionExpression /sequenceFlow sequenceFlow idflow3 sourceReftaskHR targetRefendEvent/ /process這段XML里最關(guān)鍵的是assignee表達(dá)式${applyUser.managerId}。引擎在進(jìn)入下一節(jié)點(diǎn)時(shí)會(huì)從流程變量里取applyUser再調(diào)managerId這個(gè)字段拿審批人ID。這要求你在發(fā)起流程前把發(fā)起人的部門經(jīng)理ID算好塞進(jìn)流程變量否則引擎會(huì)報(bào)“沒有找到處理人”錯(cuò)誤。很多二開需求改審批人都是改動(dòng)這個(gè)表達(dá)式里的變量來源而不是去XML里硬寫死一個(gè)ID。4.3 發(fā)起一次審批的完整Java調(diào)用鏈RuntimeService與TaskService找到流程定義后發(fā)起審批的最小Java代碼塊如下。這一段在OA源碼里通常封裝在WorkflowService里。Transactional(rollbackFor Exception.class) public String startLeaveProcess(LeaveDTO dto, String applyUserId) { // 1. 組裝流程變量發(fā)起人、表單數(shù)據(jù)、業(yè)務(wù)主鍵 MapString, Object variables new HashMap(); variables.put(applyUser, dto); // 引擎從dto.managerId取值 variables.put(days, dto.getDays()); variables.put(pass, false); // 默認(rèn)不讓通過 IdentityService identityService flowableEngine.getIdentityService(); identityService.setAuthenticatedUserId(applyUserId); // 2. 啟動(dòng)流程實(shí)例businessKey就是業(yè)務(wù)表主鍵方便反查 ProcessInstance instance runtimeService .startProcessInstanceByKey(leaveProcess, String.valueOf(dto.getId()), variables); // 3. 完成第一個(gè)任務(wù)讓流程往前走 Task task taskService.createTaskQuery() .processInstanceId(instance.getId()) .taskAssignee(applyUserId) .singleResult(); if (task ! null) { taskService.complete(task.getId()); } return instance.getId(); }這段代碼的注釋值得細(xì)看startProcessInstanceByKey的第二個(gè)參數(shù)businessKey填的是業(yè)務(wù)表單主鍵之后隨時(shí)可以通過runtimeService.createProcessInstanceQuery().processInstanceBusinessKey(主鍵)把流程實(shí)例和業(yè)務(wù)單關(guān)聯(lián)起來。identityService設(shè)置登錄用戶是為了讓引擎在ACT_HI_PROCINST表里記錄發(fā)起人否則歷史查詢會(huì)丟。完成第一個(gè)任務(wù)那兩行很多人會(huì)省略但如果不做流程會(huì)停在你自己的審批節(jié)點(diǎn)上體驗(yàn)上就像是“發(fā)起沒反應(yīng)”。完整方案里會(huì)把待辦任務(wù)的創(chuàng)建監(jiān)聽器做成異步這里為了演示用同步寫法二開時(shí)按自己需要調(diào)整。4.4 表單設(shè)計(jì)器原理用JSON定義部門字段的“所見即所得”O(jiān)A里另一個(gè)容易讓人眼前一亮的功能是表單設(shè)計(jì)器。核心做法非常樸素表單頁面是一個(gè)JSON數(shù)組每個(gè)元素描述一種控件類型和字段名運(yùn)行時(shí)前端遍歷JSON動(dòng)態(tài)渲染提交時(shí)按字段名把值收集回JSON再由后端落到一個(gè)FormData里。[ { type: input, label: 出差地點(diǎn), name: destination, placeholder: 請(qǐng)輸入城市, required: true }, { type: number, label: 出差天數(shù), name: days, unit: 天, min: 1, max: 30, required: true }, { type: textarea, label: 事由說明, name: reason, maxLength: 200 } ]前端的動(dòng)態(tài)渲染用Vue Element Plus實(shí)現(xiàn)起來大約這幾十行代碼template el-form :modelformData :rulesrules refdynamicForm el-form-item v-for(item, index) in formSchema :keyindex :labelitem.label :propitem.name el-input v-ifitem.type input v-modelformData[item.name] :placeholderitem.placeholder/ el-input-number v-else-ifitem.type number v-modelformData[item.name] :minitem.min :maxitem.max/ el-input v-else-ifitem.type textarea typetextarea v-modelformData[item.name] :maxlengthitem.maxLength/ /el-form-item /el-form /template這段代碼的核心價(jià)值在于“表單數(shù)據(jù)和流程變量解耦”表單單據(jù)的JSON存在業(yè)務(wù)表one_row里流程引擎只關(guān)心審批通過還是駁回完全不解析表單內(nèi)容。新增一個(gè)報(bào)銷單只要在后臺(tái)拖一個(gè)JSON配置出來連Java代碼都不用改。字段加密如果走泛微那種企業(yè)OA的路線還會(huì)在渲染層做脫敏展示源碼實(shí)現(xiàn)一般是給input控件加一個(gè)encrypt: true屬性前端只看到星號(hào)提交時(shí)用AES加密再送到后端這也是OA系統(tǒng)權(quán)限管理中最低成本的敏感數(shù)據(jù)保護(hù)方式。4.5 權(quán)限模型落地按鈕鑒權(quán)與數(shù)據(jù)范圍的雙重校驗(yàn)權(quán)限模型要能“見得了人”光有登錄是不夠的。用Spring Security的注解鑒權(quán)時(shí)Controller方法上要掛權(quán)限標(biāo)記比如這樣PreAuthorize(ss.hasPermi(oa:leave:audit)) PostMapping(/leave/audit) public R audit(RequestBody AuditDTO dto) { // 只有擁有oa:leave:audit權(quán)限的用戶能進(jìn)入這個(gè)入口 }更復(fù)雜的“行級(jí)權(quán)限”——比如部門經(jīng)理只能看到本部門單據(jù)人事能看到全公司單據(jù)——往往要結(jié)合數(shù)據(jù)權(quán)限注解實(shí)現(xiàn)DataScope(deptAlias d, userAlias u) GetMapping(/leave/list) public R list(RequestBody UserQuery query) { // 進(jìn)入Service后MyBatis-Plus會(huì)拼接dept_id范圍 }這個(gè)DataScope注解不是MyBatis-Plus自帶的是二開時(shí)自己實(shí)現(xiàn)的攔截器原理是解析SQL后按當(dāng)前用戶角色拼接WHERE條件。很多源碼包里這一層做得比較薄我遇到過項(xiàng)目上線后銷售抱怨“業(yè)務(wù)員能看到總經(jīng)理報(bào)銷單金額”就是行級(jí)權(quán)限沒做或被直接截?cái)唷Ｄ玫絆A源碼后建議用兩個(gè)賬號(hào)實(shí)測普通職員登錄后創(chuàng)建一條單子再讓部門經(jīng)理登錄看列表確認(rèn)列表頁沒有越權(quán)數(shù)據(jù)再談后續(xù)部署。5. 跑源碼時(shí)一定避不開的五個(gè)坑現(xiàn)象、原因與解決順序5.1 啟動(dòng)報(bào)錯(cuò)“Failed to configure a DataSource”現(xiàn)象Spring Boot啟動(dòng)器打了雞血一樣轉(zhuǎn)幾圈后直接退出控制臺(tái)最底部一行紅色報(bào)錯(cuò)說無法配置數(shù)據(jù)源。原因絕大多數(shù)是application.yml里的url或賬號(hào)密碼寫錯(cuò)或者驅(qū)動(dòng)類沒匹配MySQL版本。少數(shù)情況是工程里引了多個(gè)數(shù)據(jù)源依賴但沒指定主從切換。解決先把yml里數(shù)據(jù)源部分改成localhost和正確賬號(hào)再加一個(gè)spring.datasource.initialization-modealways觀察后端的SQL輸出日志。如果日志里能看到SQL執(zhí)行記錄但連接還是失敗就要查MySQL的max_connections是否被跑滿或防火墻擋了3306端口。5.2 前端登錄后白屏或菜單一直轉(zhuǎn)圈現(xiàn)象輸入admin和密碼后頁面跳轉(zhuǎn)進(jìn)首頁但左側(cè)菜單一個(gè)都不出來接口面板上報(bào)401或403。原因前端token沒存住或后端鑒權(quán)接口返回了不匹配的權(quán)限。OA源碼包的token處理方式分兩種一種存localStorage一種放內(nèi)存刷新頁面時(shí)內(nèi)存token丟失就得重新登錄這種在中老年工程里很常見。解決打開F12看Network請(qǐng)求找到permissions接口看它的響應(yīng)體是否是JSON數(shù)組。如果是空數(shù)組去數(shù)據(jù)庫的sys_role_menu表查一下admin角色有沒有綁定菜單如果報(bào)401直接看請(qǐng)求頭里Authorization令牌是不是被ngnix代理改掉了。5.3 審批流發(fā)起時(shí)提示“沒有找到審批人”現(xiàn)象剛填完請(qǐng)假單點(diǎn)提交后臺(tái)拋異常內(nèi)容大致是“EngineException: No assignee found”。原因流程定義XML里指定的assignee表達(dá)式在流程變量里取不到值。寫角色表達(dá)式結(jié)果引擎拿角色名去找用戶表沒找到對(duì)應(yīng)的用戶寫用戶ID結(jié)果是字符串而不是Long類型匹配不上。解決把complete那一行之前的variables打出來直接debug看map里key對(duì)應(yīng)的value類型。這里有個(gè)通用技巧在任何assignee表達(dá)式里寧可傳用戶表的主鍵Long也不傳賬號(hào)字符串因?yàn)榻涌谡{(diào)用方可能傳大寫用戶名而庫里存的是小寫屬性對(duì)不上就找不著人。5.4 附件下載的document文件名是亂碼或直接404現(xiàn)象OA里上傳的合同附件能傳上去但下載到本地后文件名是一串百分號(hào)或井號(hào)亂碼偶爾是HTTP 404。原因文件服務(wù)用了本地磁盤路徑下載時(shí)把相對(duì)路徑錯(cuò)拼到了Nginx靜態(tài)資源目錄上或者文件名編碼用了ISO-8859-1而瀏覽器按UTF-8解析。解決下載接口的響應(yīng)頭里確保Content-Disposition帶UTF-8編碼String fileName URLEncoder.encode(合同.pdf, UTF-8); response.setHeader(Content-Disposition, attachment; filename fileName);如果部署在Nginx后面注意location的alias路徑要和文件服務(wù)的基礎(chǔ)路徑一致否則就是404。這條坑在Windows服務(wù)器上高發(fā)因?yàn)殚_發(fā)機(jī)用的D:/uploadLinux服務(wù)器用的/opt/upload路徑寫死導(dǎo)致一換環(huán)境就廢。5.5 數(shù)據(jù)庫里中文全變問號(hào)現(xiàn)象表單里錄入“張三”落到MySQL里是“???”。原因建庫時(shí)沒指定utf8mb4或者JDBC連接串沒帶characterEncodingutf8。現(xiàn)在源碼普遍都用utf8mb4了因?yàn)橐鎒moji和生僻字。解決改兩條管線第一條建表時(shí)指定DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_general_ci第二條在連接串里加characterEncodingutf8。ALTER DATABASE oa CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ALTER TABLE sys_user CONVERT TO CHARACTER SET utf8mb4;這句ALTER TABLE會(huì)把表的列也轉(zhuǎn)換一遍而且不會(huì)丟數(shù)據(jù)已經(jīng)是“后悔藥”級(jí)別的操作。執(zhí)行后重啟后端再試錄入。亂碼問題的特點(diǎn)是修改簡單但發(fā)現(xiàn)成本高最好在建庫那一刻就定下規(guī)范。6. 二次開發(fā)與上線把流程引擎變成數(shù)據(jù)驅(qū)動(dòng)而不是硬編碼真正值錢的二次開發(fā)不是把考勤模塊從三張表擴(kuò)成五張表而是把“流程節(jié)點(diǎn)該由誰審批”這件事從Java代碼里挪到數(shù)據(jù)庫里。我接手過的一個(gè)項(xiàng)目最初把部門經(jīng)理審批寫死在一行Java字符串里結(jié)果公司組織架構(gòu)一調(diào)整經(jīng)理換成總監(jiān)就要發(fā)版一次。后來我把a(bǔ)ssignee改成從一張approve_rule表讀取SELECT role_key FROM workflow_rule WHERE flow_key leaveProcess AND node_key taskManager;節(jié)點(diǎn)ID與角色綁定角色再與用戶通過sys_user_role關(guān)聯(lián)這樣調(diào)一次審批人只需要維護(hù)表數(shù)據(jù)不用碰代碼重新打包。這個(gè)改動(dòng)同時(shí)也順手解決了多公司多事業(yè)部的權(quán)限隔離問題因?yàn)橐?guī)則表里再加一個(gè)部門字段就能做數(shù)據(jù)范圍過濾。上線的另一件大事是把定時(shí)任務(wù)設(shè)計(jì)成可重復(fù)執(zhí)行。OA里的考勤統(tǒng)計(jì)、流程超時(shí)提醒、合同到期預(yù)警都是定時(shí)任務(wù)。定時(shí)任務(wù)最怕“重跑一遍數(shù)據(jù)翻倍”要么用分布式鎖要么給任務(wù)加一個(gè)冪等表記錄批次號(hào)比如統(tǒng)計(jì)完工資條后在task_log里插入batch_id下次掃描發(fā)現(xiàn)同一批次已存在就直接跳過。沒做這個(gè)防護(hù)的項(xiàng)目每個(gè)月一號(hào)凌晨都可能被財(cái)務(wù)群里的一句“工資怎么多了”拉起來查日志。最后說到驗(yàn)證方法我維護(hù)一個(gè)習(xí)慣每次改完流程定義不急著測頁面先在單元測試?yán)锱芤槐镽untimeService的發(fā)起、審批、駁回、撤回四個(gè)動(dòng)作確認(rèn)ACT_HI_TASKINST里的記錄狀態(tài)流轉(zhuǎn)正確再回到頁面做手工冒煙測試。這樣把“頁面能不能點(diǎn)”和“引擎邏輯對(duì)不對(duì)”分開出錯(cuò)時(shí)省一半排查時(shí)間。OA源碼給你的起點(diǎn)是一套能跑的骨架真正的價(jià)值在于你愿意花多少時(shí)間把規(guī)則數(shù)據(jù)化、權(quán)限邊界化、任務(wù)冪等化。先把前端、后端、數(shù)據(jù)庫三端跑通了再開工改代碼希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 Java OA源碼包二次開發(fā)實(shí)戰(zhàn)：從拆包到上線避坑指南
簡介這套辦公自動(dòng)化系統(tǒng)源碼采用Java語言開發(fā)基于Spring Boot框架并結(jié)合MySQL數(shù)據(jù)庫與Maven構(gòu)建工具面向需要學(xué)習(xí)企業(yè)級(jí)應(yīng)用開發(fā)流程的初中級(jí)Java工程師也適合高校學(xué)生用于課程設(shè)計(jì)或畢業(yè)設(shè)計(jì)參考。整個(gè)資源壓縮包共包含1031個(gè)文件整體大小約5.49兆字節(jié)文件結(jié)構(gòu)較為完整其中237個(gè)Java源文件覆蓋了后端控制層、服務(wù)層與數(shù)據(jù)訪問層的核心邏輯152個(gè)FreeMarker模板和39個(gè)HTML文件用于渲染頁面85個(gè)JavaScript文件與56個(gè)CSS文件分別處理前端交互效果和頁面樣式另有20張JPG圖片以及大量GIF動(dòng)圖可直觀展示系統(tǒng)運(yùn)行流程。附帶SQL數(shù)據(jù)庫腳本可幫助使用者快速搭建本地環(huán)境。通過研讀源碼能夠理解OA系統(tǒng)中的審批流程、權(quán)限分配、消息提醒等常見模塊的設(shè)計(jì)思路并可直接將部分代碼改造成自有項(xiàng)目。目前已有1899人學(xué)習(xí)下載口碑較好適合實(shí)戰(zhàn)練手。1. Java開發(fā)OA自動(dòng)化辦公系統(tǒng)源碼包能干什么一個(gè)OA自動(dòng)化辦公系統(tǒng)的源碼包在Java工程師手里往往不是“打開即用”的成品而是拆開揉碎后二次開發(fā)的骨架。以我接手過的多個(gè)類似源碼包來看這類項(xiàng)目通常圍繞三塊核心展開審批流引擎、表單設(shè)計(jì)器、組織權(quán)限模型其余考勤、公告、會(huì)議都是在這三塊上長出來的枝葉。你能用它快速搭起企業(yè)的請(qǐng)假、報(bào)銷、用印審批也能把流轉(zhuǎn)了半年的紙質(zhì)簽批一次性搬到線上。適合正在選型的小型團(tuán)隊(duì)也適合拿來做Java課程設(shè)計(jì)或畢業(yè)設(shè)計(jì)的同學(xué)或者想在Spring Boot MyBatis-Plus這條技術(shù)棧上找一套完整案例的工程師。這篇文章就按“源碼結(jié)構(gòu)長什么樣 → 怎么跑起來 → 核心模塊怎么改 → 踩過哪些坑 → 上線前還要做什么”的順序把這條路走一遍。2. 先拆包再動(dòng)手看清OA源碼包的技術(shù)棧與工程結(jié)構(gòu)2.1 從pom.xml判斷項(xiàng)目血緣Spring Boot版本和依賴全家桶Java OA源碼包最常見的組織方式是Maven多模塊工程拿到手第一件事不是解壓就跑而是打開根目錄的pom.xml看血緣。絕大多數(shù)OA源碼基于Spring Boot MyBatis-Plus Vue這套組合少數(shù)老項(xiàng)目還在用Spring MVC JSP。判斷依據(jù)很直接看parent標(biāo)簽里的Spring Boot版本看有沒有mybatis-plus-boot-starter再看前端是獨(dú)立目錄還是靜態(tài)資源塞在后端里。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter/artifactId version6.7.2/version /dependency /dependencies為什么這套組合在OA源碼里成為事實(shí)標(biāo)準(zhǔn)MyBatis-Plus的BaseMapper讓CRUD零SQL這對(duì)表單、部門、用戶這類固定結(jié)構(gòu)的表特別合適Flowable提供BPMN流程定義和任務(wù)節(jié)點(diǎn)的底層能力。關(guān)鍵是這兩者的學(xué)習(xí)曲線都算平緩源碼包使用者能在一天內(nèi)把“業(yè)務(wù)表如何映射為UserMapper、流程如何發(fā)起為一個(gè)ProcessInstance”這層對(duì)應(yīng)關(guān)系摸透?？吹揭蕾?yán)镉衋ctiviti或flowable說明審批流是走標(biāo)準(zhǔn)BPMN引擎如果沒有工作流依賴那多半是自研的節(jié)點(diǎn)表 狀態(tài)機(jī)這種要重點(diǎn)評(píng)估流程設(shè)計(jì)的靈活度別等上線后才去補(bǔ)“駁回、會(huì)簽、加簽”這類復(fù)雜流轉(zhuǎn)。2.2 目錄結(jié)構(gòu)里的公共約定模塊拆分與包命名的門道我見過幾十個(gè)OA源碼包后得出一個(gè)經(jīng)驗(yàn)不要看Readme寫了什么要看包名怎么分。規(guī)范的工程一般拆成oa-common通用工具、異常、常量、oa-system用戶、角色、菜單、部門、oa-workflow流程定義、任務(wù)、歷史、oa-business報(bào)銷單、請(qǐng)假單、用印申請(qǐng)和前端目錄。包名按業(yè)務(wù)域而不是按層拆意味著后續(xù)加需求時(shí)知道自己該改哪個(gè)模塊。oa-parent ├── oa-common # 工具類、統(tǒng)一返回、異常碼 ├── oa-system # 組織、用戶、角色、菜單權(quán)限 ├── oa-workflow # 流程部署、任務(wù)處理、流程實(shí)例 ├── oa-business # 各種業(yè)務(wù)單據(jù) ├── oa-api # 對(duì)外接口REST DTO ├── sql/ # 初始化腳本和示例數(shù)據(jù) └── web/ # Vue前端工程拿到源碼包先對(duì)照這個(gè)結(jié)構(gòu)檢查少一個(gè)模塊并不致命但要有意識(shí)地找補(bǔ)沒有oa-workflow說明審批是死寫在業(yè)務(wù)代碼里的沒有sql目錄說明數(shù)據(jù)庫腳本要靠逆向工程導(dǎo)出。這兩個(gè)缺項(xiàng)決定了你是把包當(dāng)作“可運(yùn)行系統(tǒng)”還是“參考腳手架”。前端如果是Vue3 Element Plus注意Node版本要在16以上Vue2則12即可這個(gè)版本錯(cuò)位常讓很多人卡在npm install那一步后面避坑章會(huì)展開說。2.3 核心表結(jié)構(gòu)設(shè)計(jì)用戶、角色、菜單與審批流的關(guān)系鏈OA系統(tǒng)的數(shù)據(jù)模型有一個(gè)相對(duì)固定的范式sys_user、sys_role、sys_user_role、sys_menu、sys_role_menu這五張表構(gòu)成權(quán)限主體act_ru_task、act_ru_execution、act_hi_procinst、act_hi_taskinst這組ACT前綴的表由Flowable自動(dòng)創(chuàng)建。CREATE TABLE sys_user ( user_id BIGINT NOT NULL COMMENT 用戶ID, dept_id BIGINT COMMENT 部門ID, username VARCHAR(30) NOT NULL COMMENT 登錄賬號(hào), password VARCHAR(100) NOT NULL COMMENT 密碼BCrypt加密, nick_name VARCHAR(30) COMMENT 姓名, email VARCHAR(50) COMMENT 郵箱, phonenumber VARCHAR(11) COMMENT 手機(jī)號(hào), status CHAR(1) DEFAULT 0 COMMENT 狀態(tài)0正常1停用, create_time DATETIME COMMENT 創(chuàng)建時(shí)間, PRIMARY KEY (user_id) ) ENGINEInnoDB COMMENT用戶信息表;這張sys_user表幾乎是所有Java OA源碼里必有的表字段名也高度一致根本原因是大量二開項(xiàng)目都從同一個(gè)開源基線出來。你在拿到自己那份源碼時(shí)重點(diǎn)核對(duì)的不是字段多少而是“密碼字段是否用了BCrypt加密”“部門是否掛在dept_id外鍵上”。權(quán)限這塊要再做一層驗(yàn)證菜單表里如果每行都有perms字符串如system:user:add說明走的是Spring Security的PreAuthorize注解鑒權(quán)如果只能在按鈕上綁個(gè)布爾值那基本是前端路由攔截后端不設(shè)防上線會(huì)很被動(dòng)。3. 把OA源碼在本地跑起來數(shù)據(jù)庫初始化與啟動(dòng)全流程3.1 準(zhǔn)備JDK、Maven與MySQL環(huán)境版本匹配是玄學(xué)要當(dāng)回事跑OA源碼前最容易被忽視的是版本匹配。Spring Boot 2.7.x要求JDK 8或11JDK 17也能跑但部分舊依賴會(huì)有反射告警MySQL建議5.7或8.0連接驅(qū)動(dòng)要帶cj前綴。先檢查java -version和mvn -v不要等到編譯報(bào)錯(cuò)再回頭折騰。# 檢查本機(jī)環(huán)境這里假設(shè)JDK 8/11、Maven 3.6、MySQL 5.7 java -version mvn -v mysql -uroot -p很多源碼發(fā)行時(shí)是在局域網(wǎng)內(nèi)網(wǎng)編譯的Maven中央倉庫可能拉不到內(nèi)網(wǎng)私服上的自研依賴最穩(wěn)妥的做法是一開始就強(qiáng)制離線編譯一次看缺什么再聯(lián)網(wǎng)補(bǔ)。改完pom里依賴版本后要先用mvn clean compile驗(yàn)證能否通過編譯再用mvn spring-boot:run啟動(dòng)。這一步能提前暴露“本地類重復(fù)”或“flowable版本和mybatis沖突”這類麻煩。3.2 導(dǎo)入數(shù)據(jù)庫腳本別急著一鍵執(zhí)行先看編碼和表前綴OA源碼包里都會(huì)放一份初始化SQL常見命名是oa_init.sql或oa_db_2023.sql。導(dǎo)入前必須用文本編輯器打開看兩點(diǎn)第一建庫語句里的utf8mb4和排序規(guī)則是否一致第二是否有CREATE DATABASE如果有說明這個(gè)腳本假設(shè)你現(xiàn)在連的是一個(gè)空實(shí)例。mysql -uroot -p sql/oa_init.sql # 檢查前10張表是否建成功 mysql -uroot -p -e use oa; show tables;如果腳本是分庫導(dǎo)出的比如每個(gè)業(yè)務(wù)模塊單獨(dú)的schema那你得手動(dòng)把oa-workflow、oa-business的腳本按順序執(zhí)行。這里有個(gè)常見坑flowable建表腳本往往被放在程序啟動(dòng)時(shí)自動(dòng)執(zhí)行不需要手動(dòng)導(dǎo)入但很多源碼包把ACT前綴表的CREATE語句也合并到了初始化SQL里兩套腳本同時(shí)運(yùn)行會(huì)報(bào)表已存在。我的習(xí)慣是先手動(dòng)執(zhí)行業(yè)務(wù)表腳本啟動(dòng)時(shí)用Flowable的databaseSchemaUpdate配置項(xiàng)去自動(dòng)補(bǔ)齊流程表。3.3 修改application.yml數(shù)據(jù)源配置并啟動(dòng)后端服務(wù)默認(rèn)配置里數(shù)據(jù)庫地址往往指向開發(fā)機(jī)的內(nèi)網(wǎng)IP這臺(tái)機(jī)器關(guān)機(jī)了你就連不上。把URL改成localhost同時(shí)把賬號(hào)密碼改成自己本地的。推薦把密碼用環(huán)境變量引用而不是寫死在代碼里這樣后續(xù)部署到服務(wù)器不用改一堆源碼。server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/oa?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLfalseserverTimezoneAsia/Shanghai username: root password: ${DB_PASSWORD:root} servlet: multipart: max-file-size: 100MB max-request-size: 200MB flowable: database-schema-update: true async-executor-activate: true注意url里serverTimezoneAsia/Shanghai這一項(xiàng)很多人在這一步翻車因?yàn)镸ySQL 8默認(rèn)時(shí)區(qū)是UTC導(dǎo)致系統(tǒng)里所有待辦時(shí)間差8個(gè)小時(shí)。如果你拿到的源碼里沒有這個(gè)參數(shù)啟動(dòng)后登錄進(jìn)去看審批時(shí)間全是亂的第一反應(yīng)先補(bǔ)時(shí)區(qū)參數(shù)重啟別去查代碼。3.4 啟動(dòng)前端工程npm install兩個(gè)常見的卡殼點(diǎn)前端工程如果是Vue2把package.json里node-sass替換成sass才能過安裝Vue3則要小心Element Plus版本和Vite版本。啟動(dòng)命令都差不多cd web npm install npm run dev如果npm install慢或直接卡住大概率是registry源的問題改成淘寶鏡像源再試。npm config set registry https://registry.npmmirror.com npm install前端啟動(dòng)后訪問 http://localhost:80 或http://localhost:3000 具體端口看vue.config.js里配置。我建議先把前端代理配好再登錄代理配置通常長這樣// vue.config.js module.exports { devServer: { port: 80, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }不理解這段代理也沒關(guān)系你只需要知道前端請(qǐng)求 /api/login會(huì)被轉(zhuǎn)發(fā)到后端8080端口如果漏了這段登錄永遠(yuǎn)報(bào)403或404。一旦看到Network里的請(qǐng)求狀態(tài)碼從404變成200基本就算跑通了。4. 撕開OA系統(tǒng)的核心審批流引擎、表單設(shè)計(jì)器與權(quán)限模型4.1 審批流到底有多難為什么大多數(shù)源碼包不敢用Flowable很多自稱OA的源碼實(shí)際上沒有真正的流程引擎只在業(yè)務(wù)表里加了一個(gè)status字段用if else判斷“當(dāng)前誰可以批”。這種實(shí)現(xiàn)在考勤這種一朵流程是夠的一旦扯上報(bào)銷、采購、用印、轉(zhuǎn)正這些多節(jié)點(diǎn)會(huì)簽代碼會(huì)迅速腐化成一坨硬編碼。專業(yè)源碼會(huì)用Flowable或Activiti這類BPMN引擎流程定義是一個(gè)獨(dú)立的XML文件掛上表單JSON運(yùn)行時(shí)引擎根據(jù)當(dāng)前節(jié)點(diǎn)查審批人再往待辦表里插一條記錄。我見過太多二次開發(fā)團(tuán)隊(duì)在“要不要上引擎”上反復(fù)橫跳最后因?yàn)榧雍炐枨髷∠玛噥?。這里選擇Flowable的理由是它社區(qū)活躍、文檔全、Spring Boot集成最順手而且大部分源碼包已經(jīng)是對(duì)接好的你不需要從零設(shè)計(jì)表結(jié)構(gòu)。4.2 一張審批流程定義表BPMN XML里的節(jié)點(diǎn)與條件映射在這里先看一個(gè)請(qǐng)假流程的BPMN定義流程里兩個(gè)用戶任務(wù)節(jié)點(diǎn)分別分配給部門經(jīng)理和人事。process idleaveProcess name請(qǐng)假流程 isExecutabletrue startEvent idstartEvent name開始/ userTask idtaskManager name部門經(jīng)理審批 flowable:assignee${applyUser.managerId}/ userTask idtaskHR name人事審批 flowable:assignee${applyUser.hrId}/ endEvent idendEvent name結(jié)束/ sequenceFlow idflow1 sourceRefstartEvent targetReftaskManager/ sequenceFlow idflow2 sourceReftaskManager targetReftaskHR conditionExpression xsi:typetFormalExpression ![CDATA[${passtrue}]] /conditionExpression /sequenceFlow sequenceFlow idflow3 sourceReftaskHR targetRefendEvent/ /process這段XML里最關(guān)鍵的是assignee表達(dá)式${applyUser.managerId}。引擎在進(jìn)入下一節(jié)點(diǎn)時(shí)會(huì)從流程變量里取applyUser再調(diào)managerId這個(gè)字段拿審批人ID。這要求你在發(fā)起流程前把發(fā)起人的部門經(jīng)理ID算好塞進(jìn)流程變量否則引擎會(huì)報(bào)“沒有找到處理人”錯(cuò)誤。很多二開需求改審批人都是改動(dòng)這個(gè)表達(dá)式里的變量來源而不是去XML里硬寫死一個(gè)ID。4.3 發(fā)起一次審批的完整Java調(diào)用鏈RuntimeService與TaskService找到流程定義后發(fā)起審批的最小Java代碼塊如下。這一段在OA源碼里通常封裝在WorkflowService里。Transactional(rollbackFor Exception.class) public String startLeaveProcess(LeaveDTO dto, String applyUserId) { // 1. 組裝流程變量發(fā)起人、表單數(shù)據(jù)、業(yè)務(wù)主鍵 MapString, Object variables new HashMap(); variables.put(applyUser, dto); // 引擎從dto.managerId取值 variables.put(days, dto.getDays()); variables.put(pass, false); // 默認(rèn)不讓通過 IdentityService identityService flowableEngine.getIdentityService(); identityService.setAuthenticatedUserId(applyUserId); // 2. 啟動(dòng)流程實(shí)例businessKey就是業(yè)務(wù)表主鍵方便反查 ProcessInstance instance runtimeService .startProcessInstanceByKey(leaveProcess, String.valueOf(dto.getId()), variables); // 3. 完成第一個(gè)任務(wù)讓流程往前走 Task task taskService.createTaskQuery() .processInstanceId(instance.getId()) .taskAssignee(applyUserId) .singleResult(); if (task ! null) { taskService.complete(task.getId()); } return instance.getId(); }這段代碼的注釋值得細(xì)看startProcessInstanceByKey的第二個(gè)參數(shù)businessKey填的是業(yè)務(wù)表單主鍵之后隨時(shí)可以通過runtimeService.createProcessInstanceQuery().processInstanceBusinessKey(主鍵)把流程實(shí)例和業(yè)務(wù)單關(guān)聯(lián)起來。identityService設(shè)置登錄用戶是為了讓引擎在ACT_HI_PROCINST表里記錄發(fā)起人否則歷史查詢會(huì)丟。完成第一個(gè)任務(wù)那兩行很多人會(huì)省略但如果不做流程會(huì)停在你自己的審批節(jié)點(diǎn)上體驗(yàn)上就像是“發(fā)起沒反應(yīng)”。完整方案里會(huì)把待辦任務(wù)的創(chuàng)建監(jiān)聽器做成異步這里為了演示用同步寫法二開時(shí)按自己需要調(diào)整。4.4 表單設(shè)計(jì)器原理用JSON定義部門字段的“所見即所得”O(jiān)A里另一個(gè)容易讓人眼前一亮的功能是表單設(shè)計(jì)器。核心做法非常樸素表單頁面是一個(gè)JSON數(shù)組每個(gè)元素描述一種控件類型和字段名運(yùn)行時(shí)前端遍歷JSON動(dòng)態(tài)渲染提交時(shí)按字段名把值收集回JSON再由后端落到一個(gè)FormData里。[ { type: input, label: 出差地點(diǎn), name: destination, placeholder: 請(qǐng)輸入城市, required: true }, { type: number, label: 出差天數(shù), name: days, unit: 天, min: 1, max: 30, required: true }, { type: textarea, label: 事由說明, name: reason, maxLength: 200 } ]前端的動(dòng)態(tài)渲染用Vue Element Plus實(shí)現(xiàn)起來大約這幾十行代碼template el-form :modelformData :rulesrules refdynamicForm el-form-item v-for(item, index) in formSchema :keyindex :labelitem.label :propitem.name el-input v-ifitem.type input v-modelformData[item.name] :placeholderitem.placeholder/ el-input-number v-else-ifitem.type number v-modelformData[item.name] :minitem.min :maxitem.max/ el-input v-else-ifitem.type textarea typetextarea v-modelformData[item.name] :maxlengthitem.maxLength/ /el-form-item /el-form /template這段代碼的核心價(jià)值在于“表單數(shù)據(jù)和流程變量解耦”表單單據(jù)的JSON存在業(yè)務(wù)表one_row里流程引擎只關(guān)心審批通過還是駁回完全不解析表單內(nèi)容。新增一個(gè)報(bào)銷單只要在后臺(tái)拖一個(gè)JSON配置出來連Java代碼都不用改。字段加密如果走泛微那種企業(yè)OA的路線還會(huì)在渲染層做脫敏展示源碼實(shí)現(xiàn)一般是給input控件加一個(gè)encrypt: true屬性前端只看到星號(hào)提交時(shí)用AES加密再送到后端這也是OA系統(tǒng)權(quán)限管理中最低成本的敏感數(shù)據(jù)保護(hù)方式。4.5 權(quán)限模型落地按鈕鑒權(quán)與數(shù)據(jù)范圍的雙重校驗(yàn)權(quán)限模型要能“見得了人”光有登錄是不夠的。用Spring Security的注解鑒權(quán)時(shí)Controller方法上要掛權(quán)限標(biāo)記比如這樣PreAuthorize(ss.hasPermi(oa:leave:audit)) PostMapping(/leave/audit) public R audit(RequestBody AuditDTO dto) { // 只有擁有oa:leave:audit權(quán)限的用戶能進(jìn)入這個(gè)入口 }更復(fù)雜的“行級(jí)權(quán)限”——比如部門經(jīng)理只能看到本部門單據(jù)人事能看到全公司單據(jù)——往往要結(jié)合數(shù)據(jù)權(quán)限注解實(shí)現(xiàn)DataScope(deptAlias d, userAlias u) GetMapping(/leave/list) public R list(RequestBody UserQuery query) { // 進(jìn)入Service后MyBatis-Plus會(huì)拼接dept_id范圍 }這個(gè)DataScope注解不是MyBatis-Plus自帶的是二開時(shí)自己實(shí)現(xiàn)的攔截器原理是解析SQL后按當(dāng)前用戶角色拼接WHERE條件。很多源碼包里這一層做得比較薄我遇到過項(xiàng)目上線后銷售抱怨“業(yè)務(wù)員能看到總經(jīng)理報(bào)銷單金額”就是行級(jí)權(quán)限沒做或被直接截?cái)唷Ｄ玫絆A源碼后建議用兩個(gè)賬號(hào)實(shí)測普通職員登錄后創(chuàng)建一條單子再讓部門經(jīng)理登錄看列表確認(rèn)列表頁沒有越權(quán)數(shù)據(jù)再談后續(xù)部署。5. 跑源碼時(shí)一定避不開的五個(gè)坑現(xiàn)象、原因與解決順序5.1 啟動(dòng)報(bào)錯(cuò)“Failed to configure a DataSource”現(xiàn)象Spring Boot啟動(dòng)器打了雞血一樣轉(zhuǎn)幾圈后直接退出控制臺(tái)最底部一行紅色報(bào)錯(cuò)說無法配置數(shù)據(jù)源。原因絕大多數(shù)是application.yml里的url或賬號(hào)密碼寫錯(cuò)或者驅(qū)動(dòng)類沒匹配MySQL版本。少數(shù)情況是工程里引了多個(gè)數(shù)據(jù)源依賴但沒指定主從切換。解決先把yml里數(shù)據(jù)源部分改成localhost和正確賬號(hào)再加一個(gè)spring.datasource.initialization-modealways觀察后端的SQL輸出日志。如果日志里能看到SQL執(zhí)行記錄但連接還是失敗就要查MySQL的max_connections是否被跑滿或防火墻擋了3306端口。5.2 前端登錄后白屏或菜單一直轉(zhuǎn)圈現(xiàn)象輸入admin和密碼后頁面跳轉(zhuǎn)進(jìn)首頁但左側(cè)菜單一個(gè)都不出來接口面板上報(bào)401或403。原因前端token沒存住或后端鑒權(quán)接口返回了不匹配的權(quán)限。OA源碼包的token處理方式分兩種一種存localStorage一種放內(nèi)存刷新頁面時(shí)內(nèi)存token丟失就得重新登錄這種在中老年工程里很常見。解決打開F12看Network請(qǐng)求找到permissions接口看它的響應(yīng)體是否是JSON數(shù)組。如果是空數(shù)組去數(shù)據(jù)庫的sys_role_menu表查一下admin角色有沒有綁定菜單如果報(bào)401直接看請(qǐng)求頭里Authorization令牌是不是被ngnix代理改掉了。5.3 審批流發(fā)起時(shí)提示“沒有找到審批人”現(xiàn)象剛填完請(qǐng)假單點(diǎn)提交后臺(tái)拋異常內(nèi)容大致是“EngineException: No assignee found”。原因流程定義XML里指定的assignee表達(dá)式在流程變量里取不到值。寫角色表達(dá)式結(jié)果引擎拿角色名去找用戶表沒找到對(duì)應(yīng)的用戶寫用戶ID結(jié)果是字符串而不是Long類型匹配不上。解決把complete那一行之前的variables打出來直接debug看map里key對(duì)應(yīng)的value類型。這里有個(gè)通用技巧在任何assignee表達(dá)式里寧可傳用戶表的主鍵Long也不傳賬號(hào)字符串因?yàn)榻涌谡{(diào)用方可能傳大寫用戶名而庫里存的是小寫屬性對(duì)不上就找不著人。5.4 附件下載的document文件名是亂碼或直接404現(xiàn)象OA里上傳的合同附件能傳上去但下載到本地后文件名是一串百分號(hào)或井號(hào)亂碼偶爾是HTTP 404。原因文件服務(wù)用了本地磁盤路徑下載時(shí)把相對(duì)路徑錯(cuò)拼到了Nginx靜態(tài)資源目錄上或者文件名編碼用了ISO-8859-1而瀏覽器按UTF-8解析。解決下載接口的響應(yīng)頭里確保Content-Disposition帶UTF-8編碼String fileName URLEncoder.encode(合同.pdf, UTF-8); response.setHeader(Content-Disposition, attachment; filename fileName);如果部署在Nginx后面注意location的alias路徑要和文件服務(wù)的基礎(chǔ)路徑一致否則就是404。這條坑在Windows服務(wù)器上高發(fā)因?yàn)殚_發(fā)機(jī)用的D:/uploadLinux服務(wù)器用的/opt/upload路徑寫死導(dǎo)致一換環(huán)境就廢。5.5 數(shù)據(jù)庫里中文全變問號(hào)現(xiàn)象表單里錄入“張三”落到MySQL里是“???”。原因建庫時(shí)沒指定utf8mb4或者JDBC連接串沒帶characterEncodingutf8。現(xiàn)在源碼普遍都用utf8mb4了因?yàn)橐鎒moji和生僻字。解決改兩條管線第一條建表時(shí)指定DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_general_ci第二條在連接串里加characterEncodingutf8。ALTER DATABASE oa CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ALTER TABLE sys_user CONVERT TO CHARACTER SET utf8mb4;這句ALTER TABLE會(huì)把表的列也轉(zhuǎn)換一遍而且不會(huì)丟數(shù)據(jù)已經(jīng)是“后悔藥”級(jí)別的操作。執(zhí)行后重啟后端再試錄入。亂碼問題的特點(diǎn)是修改簡單但發(fā)現(xiàn)成本高最好在建庫那一刻就定下規(guī)范。6. 二次開發(fā)與上線把流程引擎變成數(shù)據(jù)驅(qū)動(dòng)而不是硬編碼真正值錢的二次開發(fā)不是把考勤模塊從三張表擴(kuò)成五張表而是把“流程節(jié)點(diǎn)該由誰審批”這件事從Java代碼里挪到數(shù)據(jù)庫里。我接手過的一個(gè)項(xiàng)目最初把部門經(jīng)理審批寫死在一行Java字符串里結(jié)果公司組織架構(gòu)一調(diào)整經(jīng)理換成總監(jiān)就要發(fā)版一次。后來我把a(bǔ)ssignee改成從一張approve_rule表讀取SELECT role_key FROM workflow_rule WHERE flow_key leaveProcess AND node_key taskManager;節(jié)點(diǎn)ID與角色綁定角色再與用戶通過sys_user_role關(guān)聯(lián)這樣調(diào)一次審批人只需要維護(hù)表數(shù)據(jù)不用碰代碼重新打包。這個(gè)改動(dòng)同時(shí)也順手解決了多公司多事業(yè)部的權(quán)限隔離問題因?yàn)橐?guī)則表里再加一個(gè)部門字段就能做數(shù)據(jù)范圍過濾。上線的另一件大事是把定時(shí)任務(wù)設(shè)計(jì)成可重復(fù)執(zhí)行。OA里的考勤統(tǒng)計(jì)、流程超時(shí)提醒、合同到期預(yù)警都是定時(shí)任務(wù)。定時(shí)任務(wù)最怕“重跑一遍數(shù)據(jù)翻倍”要么用分布式鎖要么給任務(wù)加一個(gè)冪等表記錄批次號(hào)比如統(tǒng)計(jì)完工資條后在task_log里插入batch_id下次掃描發(fā)現(xiàn)同一批次已存在就直接跳過。沒做這個(gè)防護(hù)的項(xiàng)目每個(gè)月一號(hào)凌晨都可能被財(cái)務(wù)群里的一句“工資怎么多了”拉起來查日志。最后說到驗(yàn)證方法我維護(hù)一個(gè)習(xí)慣每次改完流程定義不急著測頁面先在單元測試?yán)锱芤槐镽untimeService的發(fā)起、審批、駁回、撤回四個(gè)動(dòng)作確認(rèn)ACT_HI_TASKINST里的記錄狀態(tài)流轉(zhuǎn)正確再回到頁面做手工冒煙測試。這樣把“頁面能不能點(diǎn)”和“引擎邏輯對(duì)不對(duì)”分開出錯(cuò)時(shí)省一半排查時(shí)間。OA源碼給你的起點(diǎn)是一套能跑的骨架真正的價(jià)值在于你愿意花多少時(shí)間把規(guī)則數(shù)據(jù)化、權(quán)限邊界化、任務(wù)冪等化。先把前端、后端、數(shù)據(jù)庫三端跑通了再開工改代碼希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取