簡介面向用友NC Cloud 2105用戶的離線數(shù)據(jù)字典以網(wǎng)頁形式收錄了系統(tǒng)核心數(shù)據(jù)表、字段、索引、視圖及業(yè)務對象關聯(lián)信息適合實施顧問、開發(fā)人員、數(shù)據(jù)庫管理員和業(yè)務分析師查閱也可作為企業(yè)數(shù)字化轉型中理解數(shù)據(jù)模型的基礎資料。這一版本經(jīng)過細致校對修正消除了原始文檔中的常見不一致問題內(nèi)容準確性有保障同時無需聯(lián)網(wǎng)即可在瀏覽器中快速檢索十分適合無網(wǎng)絡或弱網(wǎng)環(huán)境。資源共11203個文件其中11191個html頁面承載數(shù)據(jù)字典正文另配少量js、css、gif用于頁面交互與樣式呈現(xiàn)壓縮包整體僅2.98MB輕量易部署。目前已有706人學習瀏覽。借助這份資料讀者可以按模塊梳理客戶、供應商、庫存、訂單等業(yè)務實體及數(shù)據(jù)表結構理解權限與角色劃分、接口集成規(guī)范并參考其中關于查詢報表與數(shù)據(jù)庫調(diào)優(yōu)的說明更高效地支撐NCC2105的實施和日常運維。1. 為什么要把NCC2105數(shù)據(jù)字典做成離線網(wǎng)頁版1.1 原始需求從哪來做過NCC2105二次開發(fā)的朋友應該都有過這種經(jīng)歷剛接手一個項目還沒開始寫代碼先被一摞表結構文檔勸退了。NCC2105作為成熟的ERP產(chǎn)品后臺表數(shù)量輕輕松松上千張字段更是上萬起步業(yè)務表、中間表、配置表、日志表混在一起如果不依賴數(shù)據(jù)字典連“這個字段到底存的是什么”都搞不清楚。最原始的做法是直接連數(shù)據(jù)庫查。開發(fā)環(huán)境有權限還好說生產(chǎn)環(huán)境給你只讀賬號都算客氣很多時候只能找DBA要一份導出。就算拿到了視圖翻起來也極不順手字段注釋、枚舉值、主外鍵關系全擠在一起。更麻煩的是項目組里不同角色的人都在頻繁翻閱同一份字典前端要看狀態(tài)位含義后端要核對字段類型測試要確認邊界值一份好用的字典幾乎是全組剛需。1.2 三個核心痛點缺一不可做這個離線網(wǎng)頁版之前我先后試過幾種形態(tài)最終確定了三個必須滿足的條件。第一必須離線可用。項目現(xiàn)場經(jīng)常是內(nèi)網(wǎng)環(huán)境甚至客戶機房都不讓帶外部設備進去線上文檔、云端筆記全部失效。把字典做成一個本地網(wǎng)頁文件雙擊就能打開不依賴任何服務器和網(wǎng)絡環(huán)境這才叫真正的隨時可查。第二必須帶全局搜索。NCC2105的表名是NX開頭加數(shù)字不熟悉的人根本記不住靠肉眼在一千多張表里找目標那不是在查字典是在練眼力。支持按表名、按表注釋、按字段名、按字段注釋模糊搜索這才算達到“字典”的及格線。第三必須有層級導航。NCC2105的表有清晰的模塊歸屬比如基礎檔案、供應鏈、財務、人力資源等這些信息藏在表名前綴或元數(shù)據(jù)分類里。一個好的字典頁面應該能先按模塊縮小范圍再精確定位到具體表最后查看字段明細。層級導航加搜索兩條路徑互補才是完整的檢索體驗。2. 方案選型我為什么放棄PDF最終選了純靜態(tài)網(wǎng)頁2.1 PDF方案的致命缺陷很多人第一反應是導成PDF我最早也這么干過。工具也好找數(shù)據(jù)庫客戶端基本都自帶導出功能選好表就能生成一份幾十頁甚至上百頁的PDF。真正用起來才發(fā)現(xiàn)問題一堆。PDF是靜態(tài)排版內(nèi)容不會變但NCC2105的表結構是動態(tài)的二次開發(fā)過程中經(jīng)常會加字段、改注釋、調(diào)整長度。PDF只要導出一版這張表就“過期”了想更新必須重新導出整份文檔然后重復發(fā)給所有人。字典本該是隨時查閱的參考工具而不是一份需要反復替換的存檔文件。還有個很實際的問題PDF的搜索體驗非常差。Adobe Reader的CtrlF只能逐頁跳轉對上千張表來說基本形同虛設。手機上打開更是災難頁面縮放、排版錯亂字小到要拿放大鏡看。字段描述和枚舉值在PDF里往往擠在一個大單元格里閱讀體驗遠談不上友好。2.2 離線網(wǎng)頁版的兩個路線對比確定要做網(wǎng)頁版之后我評估了兩條實現(xiàn)路線。第一條是搭建Web服務方案典型做法是用Python的Flask或Django寫一個后臺數(shù)據(jù)放SQLite通過瀏覽器訪問。好處是查詢能力強支持復雜篩選缺點是必須啟動服務現(xiàn)場機器可能沒裝Python環(huán)境即便裝好了進程掛了又得有人去重啟。第二條就是最終采用的純靜態(tài)方案把所有表結構數(shù)據(jù)預生成成一個JSON文件配合一個HTML頁面用瀏覽器直接打開file://協(xié)議訪問。沒有任何服務端進程沒有依賴安裝一個文件夾拷到哪都能用。搜索、導航、字段明細全部在前端完成。兩條路線的取舍本質是你更在乎查詢能力的上限還是部署的零門檻。對于NCC2105數(shù)據(jù)字典這種“低頻高可靠性”工具零門檻部署的優(yōu)先級遠高于復雜查詢能力。JSON文件雖然需要全量加載但幾千張表、幾萬個字段的結構化數(shù)據(jù)壓縮后通常只有幾MB現(xiàn)代瀏覽器解析起來完全沒有壓力。2.3 “完美修正版本”到底修正了什么標題里提到“完美修正版本”是因為早先我做過一個初版用起來有幾個明顯缺陷這次一并處理掉了。第一個缺陷是搜索邏輯太“笨”。初版用簡單的includes匹配搜“供應商”會把所有注釋里帶“供應商”三個字的表全部撈出來結果幾百條等于沒搜。修正版改成了分詞匹配加權重排序完全匹配的表名排最前注釋包含關鍵詞的表名次之字段命中再次之。這樣搜索“供應商”不再是海撈而是真正給你一條有優(yōu)先級的檢索列表。第二個缺陷是字段枚舉值缺失。NCC2105很多字段是字符型存數(shù)字編碼比如單據(jù)狀態(tài)存0、1、2如果不看枚舉文檔根本不知道0代表什么。初版漏掉了這部分修正版把字段的enum取值說明也納入生成邏輯在字段詳情中一并展示查字典的時候不用再另開一張枚舉對照表。第三個缺陷是移動端適配太差。現(xiàn)場調(diào)試、去車間看問題經(jīng)常是拿手機臨時查一下。初版沒有做響應式布局手機上頁面縮放錯位表格擠成一團。修正版對卡片式布局做了全面適配PC端左右分欄手機端上下堆疊滿足了現(xiàn)場隨時查的需求。這三個修正點看起來不大但每一項都直接影響日常使用體驗也是我在實際項目中反復碰壁后才意識到的。3. 核心實現(xiàn)細節(jié)從NCC2105數(shù)據(jù)庫到離線頁面的全鏈路3.1 第一步從元數(shù)據(jù)抽取表結構NCC2105的數(shù)據(jù)庫基于Oracle或PostgreSQL表結構的元數(shù)據(jù)存儲在系統(tǒng)表中。以Oracle為例核心信息從ALL_TAB_COLUMNS、ALL_COL_COMMENTS、ALL_TAB_COMMENTS這三張視圖取。用一條SQL就能獲得表名、表注釋、字段名、字段類型、字段長度、字段注釋等信息SELECT c.table_name, tc.comments AS table_comment, c.column_name, c.data_type, c.data_length, cc.comments AS column_comment FROM all_tab_columns c LEFT JOIN all_tab_comments tc ON c.table_name tc.table_name LEFT JOIN all_col_comments cc ON c.table_name cc.table_name AND c.column_name cc.column_name WHERE c.owner NCC_USER ORDER BY c.table_name, c.column_id;這里有個容易踩的坑如果owner不寫會把系統(tǒng)表、臨時表全部掃出來數(shù)據(jù)量爆炸且沒有任何參考價值。NCC2105的業(yè)務表統(tǒng)一在特定schema下寫SQL時務必帶上owner條件。提取完字段信息還需要補一張“表級維度”的清單每張表屬于哪個業(yè)務模塊、是主表還是子表、核心邏輯主鍵是什么。這些信息不在系統(tǒng)表里需要結合NCC2105的建模規(guī)范來判斷。我根據(jù)表名前綴和NCC的元數(shù)據(jù)分類做了映射比如以bd開頭的表屬于基礎數(shù)據(jù)以po開頭的是采購訂單模塊以so開頭的是銷售模塊。把模塊信息拼進表清單導航才能按“模塊分組”來組織。3.2 第二步生成結構化JSON數(shù)據(jù)原始SQL查詢結果是二維表結構不適合前端頁面直接使用。我寫了一個Python腳本把查詢結果轉換成嵌套JSON結構大致是{ modules: [ { name: 采購管理, tables: [ { tableName: po_order, comment: 采購訂單主表, columns: [ { name: pk_order, type: varchar2(20), comment: 訂單主鍵, enumValue: }, { name: billstatus, type: int, comment: 單據(jù)狀態(tài), enumValue: 0:自由, 1:審批中, 2:已生效, 3:關閉 } ] } ] } ] }關鍵點在于枚舉值的整合。NCC2105的枚舉信息通常散落在代碼里、配置表里或者干脆只有老員工口口相傳。我的做法是在生成腳本里維護一份“字段枚舉值映射表”定期從開發(fā)環(huán)境中核對補齊。對于沒有枚舉信息的字段enumValue字段留空字符串前端就不顯示枚舉區(qū)塊保持頁面干凈。數(shù)據(jù)量方面NCC2105完整庫大概有1500張表1.8萬個字段生成后的JSON大約4MB左右不壓縮也能接受。但如果未來要擴展到更多項目建議對JSON做一次Gzip體積能壓縮到1MB以內(nèi)。3.3 第三步前端頁面實現(xiàn)與檢索邏輯前端使用純原生HTMLCSSJavaScript不引入任何框架理由很簡單框架需要構建、需要CDN、需要npm install這些在離線環(huán)境全是障礙。原生三件套寫完之后整個字典就是一個文件夾放U盤里甚至可以直接拷給同事。頁面布局采用左右兩欄左側是模塊樹和表名列表右側展示選中表的字段明細。頂部放一個全局搜索框輸入關鍵詞后左側列表實時刷新為搜索結果。搜索邏輯是這套頁面的靈魂。我實現(xiàn)了一個簡單的加權評分函數(shù)表名完全等于關鍵詞權重100表名以關鍵詞開頭權重80表名包含關鍵詞權重60表注釋包含關鍵詞權重40字段名包含關鍵詞權重20字段注釋包含關鍵詞權重10每個結果取最高權重作為排序依據(jù)同時顯示命中的字段信息。這個設計看似簡單實際使用效果遠超初版的“無腦includes”方案。搜索“客戶”時客戶主表排在前面而客戶名稱字段命中的結果排在后面用戶一眼就能找到最核心的表。3.4 性能優(yōu)化幾萬字段的搜索如何做到秒開有人說才4MB的數(shù)據(jù)不至于談性能吧。但最開始我確實踩過性能坑。初版搜索是遍歷所有表的字段做循環(huán)匹配每次輸入一個字符就全量跑一遍在低配辦公本上明顯卡頓。后來做了三處優(yōu)化整個體驗就順了。第一處是輸入防抖。用戶停止輸入300毫秒后才觸發(fā)搜索而不是每個字符都觸發(fā)。第二處是數(shù)據(jù)預索引。頁面加載時把所有字段的“表名字段名注釋”拼接成一個長字符串數(shù)組搜索時只需遍歷這個預先打平的索引不用反復嵌套訪問對象。第三處是結果數(shù)量限制。搜索列表最多渲染前100條結果避免DOM一次性插入過多節(jié)點導致頁面無響應。這三處優(yōu)化沒有用到任何高深技術但實實在在地把搜索響應時間從幾百毫秒降到了幾乎無感知。性能優(yōu)化這件事很多時候不是靠框架而是靠“減少無用功”。4. 實測記錄與問題排查4.1 常見問題速查表版本做出來之后我讓項目組幾位同事各用了兩周收集到一批真實反饋整理成表格。問題現(xiàn)象原因分析解決方法雙擊html文件后頁面空白瀏覽器禁止本地文件讀取外部JSON將JSON文件改為內(nèi)聯(lián)到HTML中打包成一個單文件搜索中文關鍵詞無結果JSON編碼不是UTF-8中文亂碼生成腳本中強制指定encodingutf-8Oracle的CLOB字段顯示為[CLOB]查詢結果未做類型轉換SQL中用DBMS_LOB.SUBSTR轉換為字符串部分表注釋為空開發(fā)階段未維護注釋生成腳本跳過空注釋并在前端顯示“無注釋”表名點擊后字段明細加載慢每次點擊都重建表格DOM改為預渲染所有表詳情CSS控制顯隱4.2 幾個值得說的坑與教訓第一個坑是瀏覽器安全策略。HTML用file://協(xié)議打開時瀏覽器出于安全考慮會攔截本地JSON文件的異步請求控制臺報CORS錯誤。這個問題我排查了大半天一度以為是代碼寫錯了。后來發(fā)現(xiàn)解決方案無非兩種要么把JSON轉成JS文件通過script標簽引用要么啟動一個本地靜態(tài)服務器但這就違背了“零部署”的初衷。我最終選擇將JSON內(nèi)容直接內(nèi)聯(lián)進HTML雖然文件變大了一些但徹底規(guī)避了跨域問題單文件拷貝非常方便。第二個坑是Oracle大小寫敏感。NCC2105數(shù)據(jù)庫里表名既有大寫又有小寫如果不加處理前端按字母排序時會混亂。我在生成腳本中對表名統(tǒng)一做了大寫處理同時保留原始表名用于實際SQL查詢時復制使用。這個細節(jié)看似微不足道但確實影響日常使用的觀感。第三個坑是枚舉值數(shù)據(jù)的準確性。一次更新時我把某個狀態(tài)字段的枚舉值寫錯了導致組里同事按錯誤值去排查數(shù)據(jù)浪費了半天時間。從那以后我養(yǎng)成了一個習慣任何枚舉值變更必須在生成腳本的映射表里同步修改并且導出前自動打印一份變更日志人工確認無誤后再生成HTML。數(shù)據(jù)字典這種工具內(nèi)容出錯比沒有更可怕。5. 幾個可以繼續(xù)擴展的方向離線網(wǎng)頁版做到這個程度核心需求已經(jīng)全部滿足了但用久了之后我自己的體會是它還有幾個值得繼續(xù)深挖的方向。一個方向是支持增量更新?，F(xiàn)在的流程是數(shù)據(jù)庫結構變化后必須重新跑一次完整腳本再打包。對于頻繁迭代的開發(fā)項目來說這個操作頻率其實挺高的。如果能在頁面里內(nèi)置一個“數(shù)據(jù)更新”入口允許導入一份增量JSON就能省去重新打包的步驟對多人協(xié)作場景會友好很多。另一個方向是加入表間關系可視化。NCC2105的主外鍵關系比較隱蔽依賴字段命名規(guī)范和ER圖才能看清。如果能從數(shù)據(jù)庫約束或數(shù)據(jù)流中解析出表間關聯(lián)在前端以簡單的父子關系列表形式展示排查問題時能省不少事。不需要畫復雜的關系圖列出來就夠了。還有一個小方向是導出能力收口?，F(xiàn)在字典只能看如果要引文檔到項目周報或交付物里還得手動復制粘貼。如果給每張表加一個“導出Markdown”按鈕一鍵生成當前表的字典片段對交付文檔的整理會非常方便。這些方向我目前都只是在腦子里過了一遍還沒有全部落地。但數(shù)據(jù)字典這種工具本質上是越用越順手、越迭代越貼合團隊習慣的東西每次小改動都能帶來實打實的效率提升。本文還有配套的精品資源點擊獲取