PDMS-AVEVA-E3D二次開(kāi)發(fā)教程20收官——PDMS/E3D 二次開(kāi)發(fā)工具箱與交付體系版本與事實(shí)聲明產(chǎn)品錨點(diǎn)AVEVA E3D Design 為官方現(xiàn)名發(fā)布錨點(diǎn) 3.1.4.0 / 3.1.5.0當(dāng)前版本以官方發(fā)布說(shuō)明為準(zhǔn)AVEVA PDMS自 2024 年 4 月 1 日起停止銷售與技術(shù)支持。官方專設(shè) “Minimising Problems for Future Upgrades” 與 “Serious Warning About Software Customisation” 兩節(jié)——軟件定制會(huì)影響未來(lái)升級(jí)這是本篇架構(gòu)設(shè)計(jì)的根本約束而非免責(zé)聲明。本篇不引入任何新語(yǔ)法全部代碼是前 19 篇已給出來(lái)源的標(biāo)準(zhǔn) PowerShell / PML 組織方式。示例目錄名、版本號(hào)、清單條目均為示例性數(shù)據(jù)。一句話結(jié)論一個(gè)可維護(hù)的 E3D 二次開(kāi)發(fā)工具箱由五層構(gòu)成——環(huán)境探測(cè)層先說(shuō)清我在哪跑、數(shù)據(jù)訪問(wèn)層只讀優(yōu)先、規(guī)則層規(guī)則是數(shù)據(jù)不是代碼、批處理層冪等與賬本、交付層產(chǎn)出物必須自證判斷一套工具箱好不好不看功能多少只看三件事能不能整體卸載、能不能一鍵回歸、能不能交給第二個(gè)人維護(hù)。〇、認(rèn)知問(wèn)題Q119 篇寫(xiě)下來(lái)的函數(shù)與腳本憑什么能組成為一個(gè)工具箱而不是一堆文件Q2五層架構(gòu)里為什么環(huán)境探測(cè)層必須排在最下面而不是最上面Q3PDMS 已停售停支持遷移期為什么還要做雙軌雙軌怎么做才不失控Q4回歸測(cè)試要測(cè)什么測(cè)多少才夠Q5一份交付清單到底要交什么才能讓接手的人不罵人一、機(jī)制解析1.1 五層架構(gòu)每一層解決一類會(huì)變化的東西工具箱的本質(zhì)不是功能集合而是把會(huì)變化的東西分層隔離。五層的劃法如下┌─────────────────────────────────────────────────────────────────┐ │ ⑤ 交付層 Delivery │ │ 圖紙目錄/快照發(fā)布/DQ 報(bào)告/交接報(bào)告/產(chǎn)出物核驗(yàn) │ │ 會(huì)變的交付格式、命名規(guī)則、接收方要求 │ ├─────────────────────────────────────────────────────────────────┤ │ ④ 批處理層 Batch │ │ 作業(yè)編排/冪等/賬本/重試/環(huán)境檢查/進(jìn)度與中斷 │ │ 會(huì)變的調(diào)度方式、運(yùn)行時(shí)段、并發(fā)策略 │ ├─────────────────────────────────────────────────────────────────┤ │ ③ 規(guī)則層 Rules │ │ 規(guī)則表(CSV/JSON)/數(shù)據(jù)字典/契約表/清單 │ │ 會(huì)變的業(yè)務(wù)規(guī)定、閾值、依據(jù)文件 │ ├─────────────────────────────────────────────────────────────────┤ │ ② 數(shù)據(jù)訪問(wèn)層 Access │ │ 只讀校驗(yàn)器/范圍裁剪/屬性讀寫(xiě)/三態(tài)契約/現(xiàn)場(chǎng)保護(hù) │ │ 會(huì)變的產(chǎn)品版本、屬性名、導(dǎo)航語(yǔ)法、模塊差異 │ ├─────────────────────────────────────────────────────────────────┤ │ ① 環(huán)境探測(cè)層 Probe │ │ 產(chǎn)品與版本/PMLLIB/程序集清點(diǎn)/權(quán)限與會(huì)話/能力清單 │ │ 會(huì)變的安裝位置、部署方式、升級(jí)節(jié)奏 │ └─────────────────────────────────────────────────────────────────┘ ▲ 全部層都向上依賴這一層的事實(shí)為什么環(huán)境探測(cè)層排在最下面而不是最上面因?yàn)樯厦嫠膶拥囊磺信袛喽冀⒃谒峁┑氖聦?shí)上——數(shù)據(jù)訪問(wèn)層要問(wèn)這個(gè)屬性名在這個(gè)版本上存在嗎第 02、06 篇的ATTLIS規(guī)則層要問(wèn)這條規(guī)則的依據(jù)文件在哪個(gè)版本有效第 17 篇的basis列批處理層要問(wèn)我連的是哪個(gè)庫(kù)、有沒(méi)有 Claim 權(quán)限第 09 篇的四段結(jié)構(gòu)第一段交付層要問(wèn)產(chǎn)出物對(duì)應(yīng)的產(chǎn)品版本是多少第 18、19 篇的元數(shù)據(jù)文件。排在最下面是對(duì)依賴方向的物理表達(dá)越靠下越穩(wěn)定、越靠上越易變。第 02 篇的e3d_env_inventory.csv、第 13 篇的dotnet_inventory.csv就是這個(gè)地基。1.2 判斷工具箱好壞的三條標(biāo)準(zhǔn)前面 19 篇給了一堆最佳實(shí)踐但它們都是局部的。用全局視角看一套工具箱只有三條硬標(biāo)準(zhǔn)標(biāo)準(zhǔn)判據(jù)可操作對(duì)應(yīng)篇章能不能整體卸載每一處加都有對(duì)應(yīng)的減菜單項(xiàng)可移除、工具條 gadget 可移除、命令可 Killing、表單可隱藏、字段可釋放第 08 篇官方 Removing/Killing 類機(jī)制能不能一鍵回歸有一條命令跑完全部自檢與驗(yàn)收輸出通過(guò)/未通過(guò)清單第 08、17 篇MYCO_LibSelfTest、acceptance.ps1能不能交給第二個(gè)人維護(hù)規(guī)則在 CSV 里、字典在 JSON 里、依據(jù)有列、版本有函數(shù)、卸載有說(shuō)明第 16、17、19 篇為什么是這三條而不是功能多不多因?yàn)楣ぞ呦涞膲勖Q于這三條。功能多但不可卸載的定制產(chǎn)品升級(jí)一次就廢不可回歸的定制第二次改動(dòng)就沒(méi)人敢動(dòng)不可交接的定制作者離職即失傳。官方那句Minimising Problems for Future Upgrades想說(shuō)的就是這件事。1.3 遷移期雙軌PDMS 與 E3D Design官方事實(shí)AVEVA PDMS 已被 AVEVA E3D Design 取代并自 2024 年 4 月 1 日起停止銷售與技術(shù)支持“AVEVA Everything3D is now AVEVA E3D Design”。為什么還要做雙軌因?yàn)樵O(shè)計(jì)院里的存量項(xiàng)目不會(huì)因?yàn)楫a(chǎn)品停售而消失——老項(xiàng)目仍要在原環(huán)境上維護(hù)新項(xiàng)目按 E3D Design 建設(shè)。工具箱必須同時(shí)服務(wù)兩者否則會(huì)出現(xiàn)老項(xiàng)目沒(méi)人管或新項(xiàng)目從零重寫(xiě)。雙軌的三條控制原則控制的是不要讓它失控而不是不要做原則做法失控的表現(xiàn)要避免差異顯式化代碼里凡涉及兩代差異處用統(tǒng)一注釋標(biāo)記如-- VER-DIFF: PDMS 12.x / E3D Design并在自檢里輸出當(dāng)前判定靠人記差異 → 每次都在猜公共部分最大化規(guī)則層、字典層、交付層完全共用它們不依賴產(chǎn)品版本僅數(shù)據(jù)訪問(wèn)層與探測(cè)層分叉上下都復(fù)制兩份 → 維護(hù)量翻倍單點(diǎn)分叉數(shù)據(jù)訪問(wèn)層里凡有差異的能力導(dǎo)航、寫(xiě)屬性、文件 I/O收斂到少數(shù)幾個(gè)函數(shù)做版本判定差異散落各處 → 無(wú)法說(shuō)清支持哪些版本關(guān)鍵洞察五層里只有 ①② 兩層是產(chǎn)品相關(guān)的③④⑤ 三層是工程相關(guān)的。所以雙軌的實(shí)際成本遠(yuǎn)低于直覺(jué)——只要 ③④⑤ 不復(fù)制雙軌就是可承受的。最佳實(shí)踐在工具箱自檢里輸出一行當(dāng)前環(huán)境判定例如env: familyE3DDesign / version實(shí)際版本 / runtimedetected讓這套工具箱在某臺(tái)機(jī)器上以哪條軌運(yùn)行成為可見(jiàn)事實(shí)。1.4 回歸測(cè)試測(cè)三層不測(cè)全部回歸測(cè)試不是把每個(gè)函數(shù)都測(cè)一遍成本太高、維護(hù)不了。只需要測(cè)三層層次測(cè)什么為什么只測(cè)這些冒煙層能否加載、版本函數(shù)能否返回、PMLLIB 是否含本工具箱目錄加載失敗是最常見(jiàn)故障且一秒可判契約層核心函數(shù)的返回契約是否符合三態(tài)前綴、字段數(shù)量與位置契約變化會(huì)靜默破壞所有下游解析器端到端層一條最小完整流程選一個(gè)小范圍 → 跑檢查 → 產(chǎn)出報(bào)告 → 核驗(yàn)報(bào)告它覆蓋了 90% 的集成問(wèn)題且能自動(dòng)判定不測(cè)的部分單個(gè)內(nèi)部函數(shù)的細(xì)節(jié)邏輯、UI 的視覺(jué)效果、極端輸入組合。理由這些測(cè)試的維護(hù)成本高于其收益把有限精力放在契約與端到端上回歸才跑得起來(lái)、才會(huì)有人跑?；貧w的觸發(fā)時(shí)機(jī)三條工具箱自身改動(dòng)后產(chǎn)品升級(jí)前后各一次這是最重要的一次用于評(píng)估影響面交付前作為交付清單的一個(gè)必過(guò)項(xiàng)。1.5 交付清單交給接手人的東西第 02 篇講了環(huán)境清單、第 08 篇講了升級(jí)自查、第 19 篇講了數(shù)據(jù)發(fā)布。交付清單是把這些清單合并成一份交接包類別交付內(nèi)容為什么必須交環(huán)境事實(shí)環(huán)境探測(cè)清單產(chǎn)品/版本/路徑/權(quán)限/程序集沒(méi)有它接手人不知道在哪跑能力邊界支持的產(chǎn)品代際與版本范圍、明確不支持的場(chǎng)景沒(méi)有它接手人會(huì)以為什么都能干代碼資產(chǎn)五層目錄、生成物、構(gòu)建腳本、版本函數(shù)代碼本身配置資產(chǎn)規(guī)則表、數(shù)據(jù)字典、契約表、圖紙清單這是業(yè)務(wù)可維護(hù)的部分最容易被漏交紀(jì)律資產(chǎn)鐵律清單、代碼評(píng)審要點(diǎn)、卸載說(shuō)明沒(méi)有它接手人會(huì)把工具箱改壞驗(yàn)證資產(chǎn)回歸腳本、驗(yàn)收腳本、最近一次回歸結(jié)果沒(méi)有它接手人不敢動(dòng)運(yùn)行資產(chǎn)運(yùn)行賬本、模型/數(shù)據(jù)臺(tái)賬、最近發(fā)布記錄用于追溯上次跑到哪最容易被漏交的是配置資產(chǎn)與紀(jì)律資產(chǎn)——因?yàn)榇a看得見(jiàn)規(guī)則與規(guī)矩看不見(jiàn)。但恰恰是這兩類決定接手人能不能在三個(gè)月后還不罵人。1.6 團(tuán)隊(duì)規(guī)范與評(píng)審要點(diǎn)濃縮成一張表20 篇下來(lái)團(tuán)隊(duì)規(guī)范其實(shí)就這些。把它做成評(píng)審時(shí)的檢查表#評(píng)審提問(wèn)不通過(guò)的表現(xiàn)1這段邏輯會(huì)被調(diào)用第二次嗎是就寫(xiě)成函數(shù)業(yè)務(wù)邏輯寫(xiě)在宏里2這段代碼改了!!ce嗎改了就在兩個(gè)出口都還原只還原正常出口3屬性名從哪來(lái)核對(duì)過(guò)ATTLIS嗎憑記憶寫(xiě)屬性名4數(shù)值帶單位嗎裸數(shù)值參與比較5判存在用的是Defined()還是值判空用取值判空0 被誤判6批量腳本報(bào)了幾個(gè)計(jì)數(shù)加起來(lái)自洽嗎只返回Success7失敗信息里有沒(méi)有該怎么辦只有失敗三個(gè)字8這個(gè)動(dòng)作在離線副本上驗(yàn)證過(guò)嗎直接在生產(chǎn)庫(kù)首次運(yùn)行9有沒(méi)有對(duì)應(yīng)的卸載路徑只加不減10規(guī)則/閾值/依據(jù)寫(xiě)在哪業(yè)務(wù)能改嗎埋在代碼里11這一段是 PML 該做的嗎第 13 篇五條判據(jù)用 .NET 做界面12用了官方還是臆測(cè)的語(yǔ)法網(wǎng)上抄來(lái)未核對(duì)的寫(xiě)法第 12 條是元規(guī)則它是前 11 條之所以可靠的保證。官方文檔查不到就標(biāo)注以官方文檔為準(zhǔn)并給出章節(jié)定位——這條紀(jì)律比任何一條語(yǔ)法規(guī)則都重要因?yàn)檎Z(yǔ)法會(huì)變、會(huì)被記錯(cuò)而知道去哪查的能力不會(huì)。1.7 八條鐵律收官回顧全系列確立的八條鐵律全系列不超過(guò) 10 條其余為最佳實(shí)踐與經(jīng)驗(yàn)法則#鐵律一句話記法1語(yǔ)法只寫(xiě)官方手冊(cè)記載的形態(tài)查不到就指向官方章節(jié)寧缺毋編2單位與屬性必顯式數(shù)值必帶單位3先探測(cè)環(huán)境再運(yùn)行先說(shuō)清在哪跑4破壞性操作先離線驗(yàn)證副本先行5對(duì)接必聲明邊界與版本寫(xiě)清誰(shuí)算哪段6PDMS 與 E3D Design 差異必須顯式標(biāo)注代際差異不許含糊7不混寫(xiě)產(chǎn)品能力無(wú)PML 內(nèi)嵌 Python不把 APS 能力安到 E3D 上不張冠李戴8示例數(shù)據(jù)必標(biāo)注示例不等于規(guī)定二、完整代碼與逐行剖析代碼 20-1工具箱目錄骨架結(jié)構(gòu)即架構(gòu)e3d_devkit/ ├── README.md # 工具箱總覽能力邊界 / 支持版本 / 安裝步驟 / 卸載步驟 ├── CHANGELOG.md # 每個(gè)版本改了什么含規(guī)則表變更 ├── 00_env/ # ① 環(huán)境探測(cè)層 │ ├── probe_install.ps1 # 安裝與運(yùn)行時(shí)盤(pán)點(diǎn)第 01/02 篇 │ ├── pml_lib_census.ps1 # PMLLIB 內(nèi)容與命名沖突普查第 02 篇 │ ├── asm_identity.ps1 # .NET 程序集身份清點(diǎn)第 13 篇 │ ├── type_census.ps1 # 公開(kāi)類型清點(diǎn)第 13 篇 │ └── out/ # 探測(cè)產(chǎn)物CSV隨交付一起交 ├── 10_pml/ # ② 數(shù)據(jù)訪問(wèn)層PML │ ├── lib_version.pmlf # 版本函數(shù)第 08 篇 │ ├── lib_selftest.pmlf # 依賴自檢第 08 篇 │ ├── nav_helpers.pmlf # 導(dǎo)航輔助按官方 DBRM2.03.x 實(shí)現(xiàn)第 05 篇 │ ├── lint_core.pmlf # 只讀檢查內(nèi)核第 06/17 篇 │ ├── ifc_export.pmlf # IFC 導(dǎo)出封裝第 12 篇 │ ├── draw_batch.pmlf # 批量導(dǎo)出作業(yè)第 18 篇 │ └── rules.pmlf # 【生成物】由 30_rules 構(gòu)建勿手改 ├── 20_ui/ # ② 層的界面部分 │ ├── lint_ui.pmlfrm # 表單第 07 篇 │ └── commands.pmlf # 命令定義與裝配/卸載第 08 篇 ├── 30_rules/ # ③ 規(guī)則層業(yè)務(wù)可維護(hù) │ ├── rules.csv # 檢查規(guī)則表第 17 篇 │ ├── data_dictionary.json # 數(shù)據(jù)字典第 19 篇 │ ├── dq_rules.csv # 數(shù)據(jù)質(zhì)量規(guī)則第 19 篇 │ ├── draw_manifest.csv # 圖紙清單第 18 篇 │ ├── contract.csv # 跨專業(yè)數(shù)據(jù)契約第 16 篇 │ ├── gen_rules.ps1 # 構(gòu)建腳本CSV - rules.pmlf第 17 篇 │ └── apply_pml.ps1 # 構(gòu)建物落盤(pán)到 PMLLIB 目錄 提示索引重建 ├── 40_run/ # ④ 批處理層 │ ├── run_lint.ps1 # 檢查作業(yè)入口第 09/17 篇 │ ├── run_draw.ps1 # 出圖作業(yè)入口第 18 篇 │ ├── run_snapshot.ps1 # 快照作業(yè)入口第 19 篇 │ ├── job_ledger.ps1 # 作業(yè)賬本第 09 篇 │ └── verify_outputs.ps1 # 產(chǎn)出物核驗(yàn)第 09/12/18 篇 ├── 50_deliver/ # ⑤ 交付層 │ ├── gen_index.ps1 # 圖紙目錄生成第 18 篇 │ ├── dq_check.ps1 # 數(shù)據(jù)質(zhì)量檢查第 19 篇 │ ├── snapshot_diff.ps1 # 快照差分與變更集第 19 篇 │ └── release.ps1 # 打包一次發(fā)布字典快照元數(shù)據(jù)DQ ├── test/ │ ├── smoke.ps1 # 冒煙層回歸第 20 篇 1.4 節(jié) │ ├── contract.ps1 # 契約層回歸 │ ├── e2e.ps1 # 端到端回歸 │ └── acceptance.ps1 # 項(xiàng)目級(jí)驗(yàn)收第 17 篇 └── docs/ ├── 交付清單.md # 本篇 1.5 節(jié)的落地交接包索引 ├── 鐵律與評(píng)審要點(diǎn).md # 本篇 1.6 節(jié)的落地 └── 卸載說(shuō)明.md # 本篇 1.2 節(jié)第 1 條的落地逐行剖析目錄編號(hào)00_/10_/20_…直接對(duì)應(yīng)五層順序編號(hào)讓依賴方向在文件管理器的排序里就可讀——排在上面的層依賴排在下層的事實(shí)。這是結(jié)構(gòu)即架構(gòu)的最省事表達(dá)方式。00_env/out/的探測(cè)產(chǎn)物隨交付一起交這是 1.5 節(jié)環(huán)境事實(shí)必須是交付物的落地。很多團(tuán)隊(duì)把探測(cè)腳本交了、產(chǎn)物留在自己機(jī)器上接手人得先跑一遍才知道情況——而這恰恰是最容易卡住的地方。10_pml/rules.pmlf明確標(biāo)注為生成物且構(gòu)建腳本在30_rules/生成物與它的源放在不同層源在規(guī)則層產(chǎn)物在數(shù)據(jù)訪問(wèn)層。這個(gè)安排逼著人思考我改的是源還是產(chǎn)物從目錄結(jié)構(gòu)上防止手改生成物第 17 篇報(bào)錯(cuò) 3-2。docs/卸載說(shuō)明.md是獨(dú)立文件卸載路徑不能只寫(xiě)在代碼注釋里。它是能不能整體卸載這條標(biāo)準(zhǔn)的物理載體1.2 節(jié)。一個(gè)沒(méi)有卸載說(shuō)明的定制在產(chǎn)品升級(jí)時(shí)的處理方式通常是不管它——然后升級(jí)出問(wèn)題。test/分四個(gè)腳本對(duì)應(yīng)四個(gè)層級(jí)冒煙/契約/端到端/驗(yàn)收分層讓回歸可以只跑需要的部分改了一個(gè) PML 函數(shù)跑冒煙契約改了端到端流程跑全部。一次要跑十分鐘的回歸很快就不會(huì)有人跑。代碼 20-2一鍵回歸PowerShell可運(yùn)行# -*- coding: utf-8 -*-# regress.ps1 —— 工具箱一鍵回歸冒煙 / 契約 / 端到端 / 驗(yàn)收 設(shè)計(jì)要點(diǎn) * 分層執(zhí)行失敗即匯總不中斷最后給出總判定 * 每一層都有可自動(dòng)判定的成功標(biāo)準(zhǔn)不允許看起來(lái)正常 * 結(jié)果同時(shí)輸出給人看屏幕與給機(jī)器看regress_result.csv 用法 .\regress.ps1 -KitRoot . -Level all #param([Parameter(Mandatory$true)][string]$KitRoot,[ValidateSet(smoke,contract,e2e,all)][string]$Levelall,[string]$OutDir.\test\out)$ErrorActionPreferenceSilentlyContinueif(-not(Test-Path-LiteralPath$OutDir)){New-Item-ItemType Directory-Path$OutDir|Out-Null}$resultsNew-ObjectSystem.Collections.Generic.List[object]functionRun-Layer{param([string]$Name,[string]$Script,[int]$ExpectedExit)$rec[pscustomobject]{layer $Name;script $Script;ran $falseexit_code ;verdict ;detail ;seconds 0}$pJoin-Path$KitRoot$Scriptif(-not(Test-Path-LiteralPath$p)){$rec.verdict SKIP_NO_SCRIPT;$rec.detail 未提供$Script$results.Add($rec)|Out-NullWrite-Host([{0}] 跳過(guò)腳本不存在-f$Name)return}$sw[System.Diagnostics.Stopwatch]::StartNew()$p-KitRoot$KitRoot-OutDir$OutDir|Out-Host$code$LASTEXITCODE$sw.Stop()$rec.ran $true$rec.exit_code $code$rec.seconds [math]::Round($sw.Elapsed.TotalSeconds,1)$rec.verdict if($code-eq$ExpectedExit){PASS}else{FAIL}$rec.detail if($code-eq$ExpectedExit){}else{(期望退出碼 {0}實(shí)際 {1}-f$ExpectedExit,$code)}$results.Add($rec)|Out-NullWrite-Host([{0}] {1}退出碼 {2}耗時(shí) {3}s-f$Name,$rec.verdict,$code,$rec.seconds)}# ---- 冒煙層0 表示工具箱可加載且環(huán)境可判定 ----if($Level-in(smoke,all)){Run-Layersmoketest\smoke.ps10}# ---- 契約層0 表示全部返回契約符合 ----if($Level-in(contract,all)){Run-Layercontracttest\contract.ps10}# ---- 端到端層0 表示最小完整流程產(chǎn)出且核驗(yàn)通過(guò) ----if($Level-in(e2e,all)){Run-Layere2etest\e2e.ps10}# ---- 驗(yàn)收層0 表示項(xiàng)目驗(yàn)收標(biāo)準(zhǔn)全部滿足 ----if($Level-eqall){Run-Layeracceptancetest\acceptance.ps10}$results|Export-Csv-LiteralPath(Join-Path$OutDirregress_result.csv)-NoTypeInformation-Encoding UTF8$failed ($results|Where-Object{$_.verdict-eqFAIL})$skipped ($results|Where-Object{$_.verdict-eqSKIP_NO_SCRIPT})Write-HostWrite-Host(回歸結(jié)果通過(guò) {0} / 失敗 {1} / 跳過(guò) {2}-f (($results|Where-Object{$_.verdict-eqPASS}).Count),$failed.Count,$skipped.Count)if($failed.Count-gt0){Write-Host失敗項(xiàng)$failed|ForEach-Object{Write-Host( - {0}: {1}-f$_.layer,$_.detail)}Write-Host★ 回歸未通過(guò)禁止交付也禁止在原環(huán)境做進(jìn)一步修改。exit1}if($skipped.Count-gt0){Write-Host★ 有層被跳過(guò)腳本缺失當(dāng)前結(jié)果不能作為交付依據(jù)。exit3}Write-Host回歸全部通過(guò)。請(qǐng)把 regress_result.csv 連同交付包一起交接。exit0逐行剖析“失敗即匯總、不中斷”Run-Layer不拋異常也不 return所有層都跑完再匯總。理由回歸的價(jià)值在于一次看到全部問(wèn)題如果第一層失敗就中斷你修完再跑再發(fā)現(xiàn)第二層也壞了——迭代次數(shù)翻倍。每層都有一個(gè)顯式的期望退出碼$ExpectedExit把什么叫成功寫(xiě)成參數(shù)。這是本系列從頭到尾的紀(jì)律在回歸層的體現(xiàn)——看起來(lái)正常不是判定標(biāo)準(zhǔn)。SKIP_NO_SCRIPT是一個(gè)獨(dú)立結(jié)論而不是 PASS腳本缺失時(shí)絕不能算通過(guò)。并且專門(mén)打印一句當(dāng)前結(jié)果不能作為交付依據(jù)退出碼 3。這是沒(méi)測(cè)與測(cè)過(guò)沒(méi)問(wèn)題的區(qū)分——這個(gè)區(qū)分在本系列里出現(xiàn)了至少四次第 09 篇 STALE、第 11 篇假空碰撞、第 18 篇 STALE、第 19 篇無(wú)變更它是全系列最一致的一條思維習(xí)慣。耗時(shí)被記錄進(jìn)結(jié)果表seconds列用于監(jiān)控回歸是否在變得太慢。當(dāng)端到端從 30 秒漲到 10 分鐘時(shí)就是該拆分的時(shí)候了——否則回歸會(huì)先被跳過(guò)然后被遺忘。regress_result.csv隨交付包交接1.5 節(jié)驗(yàn)證資產(chǎn)它是這套工具箱在某臺(tái)機(jī)器上是好的這一論斷的證據(jù)。結(jié)尾那句禁止交付也禁止在原環(huán)境做進(jìn)一步修改第二條同樣重要——回歸失敗時(shí)繼續(xù)改代碼會(huì)讓下次回歸也說(shuō)不清是新改動(dòng)引入的還是原本就壞的。代碼 20-3交付清單Markdown交接包的索引# 交付清單 · e3d_devkit 版本號(hào) ## A 環(huán)境事實(shí)必須交 - [ ] 00_env/out/probe_install.csv安裝與運(yùn)行時(shí) - [ ] 00_env/out/pml_lib_census.csvPMLLIB 與命名沖突 - [ ] 00_env/out/asm_identity.csv.NET 程序集身份如啟用 .NET 通道 - [ ] 一行結(jié)論產(chǎn)品代際與版本 / 模塊 / 權(quán)限范圍 ## B 能力邊界必須交 - [ ] 支持的產(chǎn)品與版本范圍填寫(xiě) - [ ] 明確不支持逐條填寫(xiě) - [ ] 已確認(rèn)的官方章節(jié)引用清單PML/DBRM/DRAW/IFC 等 ## C 代碼資產(chǎn) - [ ] 五層目錄10_pml / 20_ui / 30_rules / 40_run / 50_deliver - [ ] 生成物清單及其源rules.pmlf ← rules.csv - [ ] 版本函數(shù)輸出!!MYCO_LibVersion() 實(shí)際返回值 ## D 配置資產(chǎn)最易漏交 - [ ] rules.csv / dq_rules.csv / draw_manifest.csv / contract.csv / data_dictionary.json - [ ] 每份配置的負(fù)責(zé)人 依據(jù)文件 最近變更日期 ## E 紀(jì)律資產(chǎn)最易漏交 - [ ] 鐵律與評(píng)審要點(diǎn)12 條提問(wèn) - [ ] 卸載說(shuō)明每一處加對(duì)應(yīng)的減 - [ ] 代際差異標(biāo)注約定-- VER-DIFF: ## F 驗(yàn)證資產(chǎn) - [ ] test/regress_result.csv最近一次回歸 - [ ] test/acceptance 結(jié)果 - [ ] 已知未通過(guò)項(xiàng)及其原因與計(jì)劃 ## G 運(yùn)行資產(chǎn) - [ ] jobs_ledger.csv作業(yè)賬本 - [ ] model_ledger.csv模型/數(shù)據(jù)臺(tái)賬如啟用模型 - [ ] 最近一次發(fā)布記錄發(fā)布版本號(hào) 時(shí)間 內(nèi)容逐項(xiàng)剖析A、B 兩組放在最前因?yàn)樗鼈兪墙邮秩说谝惶熳钚枰臇|西先知道在哪跑、能跑到什么程度代碼才有意義。D、E 兩組標(biāo)注最易漏交1.5 節(jié)。這是把經(jīng)驗(yàn)寫(xiě)成流程的形態(tài)——漏交這兩組的原因不是疏忽而是代碼看得見(jiàn)、規(guī)則看不見(jiàn)的認(rèn)知偏差。標(biāo)注出來(lái)評(píng)審時(shí)就會(huì)被專門(mén)檢查。B 組第 2 條明確不支持是刻意的一份只寫(xiě)支持什么的說(shuō)明會(huì)誘導(dǎo)過(guò)度期待。寫(xiě)明不支持什么是專業(yè)交付姿態(tài)的一部分。F 組第 3 條已知未通過(guò)項(xiàng)及其原因與計(jì)劃允許交付有未通過(guò)項(xiàng)但不允許未記錄的未通過(guò)項(xiàng)。這條讓交付可以推進(jìn)現(xiàn)實(shí)項(xiàng)目里很難全綠同時(shí)保留誠(chéng)實(shí)。G 組的最近一次發(fā)布記錄把第 19 篇的發(fā)布版本概念延伸到整個(gè)工具箱——接手人應(yīng)該能一眼看到這個(gè)工具最近產(chǎn)出了什么、什么時(shí)候。三、常見(jiàn)報(bào)錯(cuò)與排查報(bào)錯(cuò) 3-1產(chǎn)品升級(jí)后工具箱部分功能不好使但不知道影響面?，F(xiàn)象升級(jí)后故障。根因沒(méi)有升級(jí)前后的可比基線第 08、13 篇的清單沒(méi)有留存。解法升級(jí)前后各跑一次環(huán)境探測(cè)與回歸用asm_identity.csv程序集身份、type_census.csv公開(kāi)類型、pml_lib_census.csvPMLLIB 內(nèi)容做差分把升級(jí)評(píng)估作為一條固定流程——對(duì)應(yīng)官方 “Minimising Problems for Future Upgrades” 一節(jié)的立場(chǎng)。報(bào)錯(cuò) 3-2想停用某個(gè)功能但菜單里刪不掉、命令還在跑?，F(xiàn)象卸不干凈。根因只寫(xiě)了加沒(méi)寫(xiě)減——官方為此專門(mén)提供了 Removing Menu Items、Removing Gadgets from a Toolbar、Killing a Command、Hiding Forms when Exiting Applications 等機(jī)制第 08 篇但實(shí)現(xiàn)時(shí)容易只做一半。解法在開(kāi)發(fā)階段就把卸載路徑作為該功能的一部分實(shí)現(xiàn)并在docs/卸載說(shuō)明.md里逐項(xiàng)列出回歸里加一項(xiàng)卸載后重裝能正常的檢查。報(bào)錯(cuò) 3-3接手人說(shuō)看不懂這個(gè)規(guī)則為什么這么定?，F(xiàn)象無(wú)法維護(hù)。根因規(guī)則缺basis依據(jù)列或依據(jù)文件沒(méi)有被交接。解法規(guī)則表強(qiáng)制basis與owner非空第 17 篇構(gòu)建腳本已強(qiáng)制交付時(shí)把依據(jù)文件設(shè)計(jì)規(guī)定、等級(jí)管理規(guī)定等的編號(hào)與版本一起交不必交全文但必須可追溯評(píng)審時(shí)把依據(jù)能不能查到作為檢查項(xiàng)。報(bào)錯(cuò) 3-4雙軌維護(hù)變成兩份代碼各改一遍?，F(xiàn)象維護(hù)量翻倍。根因把 ③④⑤ 層也復(fù)制成了兩份1.3 節(jié)。解法規(guī)則層、字典層、批處理層、交付層完全共用只在數(shù)據(jù)訪問(wèn)層做單點(diǎn)分叉版本判定收斂到少數(shù)函數(shù)差異用統(tǒng)一標(biāo)記-- VER-DIFF:顯式化自檢里輸出當(dāng)前以哪條軌運(yùn)行。報(bào)錯(cuò) 3-5回歸越來(lái)越慢最后被跳過(guò)?，F(xiàn)象回歸失效。根因端到端層把全量模型當(dāng)測(cè)試范圍或者把 UI 相關(guān)的檢查都塞了進(jìn)來(lái)。解法端到端用一個(gè)極小范圍幾十個(gè)元素做冒煙式的全流程驗(yàn)證只測(cè)三層1.4 節(jié)記錄每層耗時(shí)代碼 20-2 的seconds列并在超過(guò)閾值時(shí)告警把回歸必須能在幾分鐘內(nèi)跑完作為架構(gòu)約束而不是愿望。四、動(dòng)手練習(xí)練習(xí) 1骨架落地按代碼 20-1 建立目錄骨架把前 19 篇你實(shí)際完成的腳本按層歸位。判定標(biāo)準(zhǔn)五層目錄都存在且非空30_rules/rules.pmlf被明確標(biāo)注為生成物docs/下三個(gè)文件存在哪怕是初稿。歸位過(guò)程中若發(fā)現(xiàn)某個(gè)腳本不知道該放哪層把它記下來(lái)——這正是你架構(gòu)還沒(méi)想清的地方。練習(xí) 2一鍵回歸實(shí)現(xiàn)test/smoke.ps1、test/contract.ps1、test/e2e.ps1三個(gè)最小版本每個(gè)只要 5~20 行能做出一項(xiàng)可自動(dòng)判定的檢查即可然后用代碼 20-2 跑一次。判定標(biāo)準(zhǔn)三層都執(zhí)行且退出碼符合預(yù)期regress_result.csv含layer / exit_code / verdict / seconds四列故意讓契約層失敗改掉一個(gè)契約前綴總判定必須為失敗且退出碼為 1。練習(xí) 3卸載演練按docs/卸載說(shuō)明.md完整卸載工具箱移除菜單項(xiàng)、移除工具條 gadget、Killing 命令、隱藏表單然后重新安裝。判定標(biāo)準(zhǔn)卸載后產(chǎn)品原有功能不受影響用任一原有菜單命令驗(yàn)證重新安裝后工具箱功能全部恢復(fù)正常跑一次回歸。兩次操作都要在筆記里記錄實(shí)際步驟——卸載說(shuō)明寫(xiě)不下去的地方就是卸載實(shí)現(xiàn)不完整的地方。練習(xí) 4交付清單按代碼 20-3 填一份完整清單A~G 七組。判定標(biāo)準(zhǔn)七組全部有勾選項(xiàng)D、E 組逐項(xiàng)填寫(xiě)不許寫(xiě)見(jiàn)代碼F 組注明最近一次回歸的時(shí)間與結(jié)果G 組包含最近一次發(fā)布記錄。填完后請(qǐng)一名未參與開(kāi)發(fā)的同事按清單在另一臺(tái)機(jī)器上只看清單復(fù)現(xiàn)一次工具箱的安裝與運(yùn)行記錄他卡住的每一步。思考題無(wú)標(biāo)準(zhǔn)答案為什么能不能交給第二個(gè)人維護(hù)是判斷工具箱好壞的最終標(biāo)準(zhǔn)而不是功能是否強(qiáng)大驗(yàn)證要點(diǎn)① 一個(gè)功能強(qiáng)大但只有作者能改的工具在作者調(diào)崗后的實(shí)際處境② 規(guī)則在 CSV、依據(jù)有列、版本有函數(shù)、卸載有說(shuō)明這四件事分別降低了接手人的哪一類成本③ 如果你現(xiàn)在要交接自己寫(xiě)的工具最可能被漏交的是哪一類資產(chǎn)對(duì)照 20-3 清單自檢。五、小結(jié)與全系列收束工具箱的本質(zhì)是把會(huì)變化的東西分層隔離環(huán)境探測(cè)層越穩(wěn)定越靠下、數(shù)據(jù)訪問(wèn)層、規(guī)則層、批處理層、交付層。判斷它好不好只看三條——能不能整體卸載、能不能一鍵回歸、能不能交給第二個(gè)人維護(hù)。PDMS 已于 2024 年 4 月 1 日停售停支持雙軌的現(xiàn)實(shí)成本遠(yuǎn)低于直覺(jué)因?yàn)槲鍖永镏挥袛?shù)據(jù)訪問(wèn)與探測(cè)兩層是產(chǎn)品相關(guān)的控制雙軌失控靠三條差異顯式化、公共部分最大化、單點(diǎn)分叉。回歸只測(cè)三層冒煙、契約、端到端并堅(jiān)持沒(méi)測(cè) ≠ 測(cè)過(guò)沒(méi)問(wèn)題。交付清單七組里配置資產(chǎn)與紀(jì)律資產(chǎn)最容易漏交也最決定接手人三個(gè)月后是否罵人。全系列回顧三十句三維工廠設(shè)計(jì)的交付物全部源自模型所以模型側(cè)的規(guī)范化會(huì)被交付物放大第 01 篇PML 只有兩條官方通道PML 與 .NET APIPML 的能被找到由搜索路徑與索引決定第 02 篇代碼形態(tài)三層遞進(jìn)、判據(jù)是會(huì)不會(huì)被調(diào)用第二次第 03 篇表達(dá)式有類型、單位是語(yǔ)言層面的事、數(shù)組可稀疏且無(wú)負(fù)下標(biāo)第 04 篇數(shù)據(jù)是以 WORLD 為根的樹(shù)!!CE是會(huì)話狀態(tài)必須保護(hù)現(xiàn)場(chǎng)第 05 篇屬性分標(biāo)準(zhǔn)/UDA/偽屬性ATTLIS 是區(qū)分沒(méi)填與寫(xiě)錯(cuò)的唯一手段第 06 篇gadget 不支持自定義成員所以界面必須與邏輯分層第 07 篇每一處加都要有減第 08 篇冪等判據(jù)要放模型里產(chǎn)出物核驗(yàn)要能識(shí)別 STALE第 09 篇目錄數(shù)據(jù)只存一份所以對(duì)賬只做待核對(duì)清單第 10 篇碰撞判定取決于 OBST 與容差規(guī)則類代碼的頭號(hào)陷阱是 RESULT 默認(rèn)值寫(xiě)反第 11 篇IFC 導(dǎo)出有完全可編程的官方 PML 對(duì)象第 12 篇.NET 通道的正確起點(diǎn)是反射清點(diǎn)而非猜測(cè)第 13 篇PMLNETCALLABLE 讓特征契約成為接口第 14 篇接口成功不等于數(shù)據(jù)正確日志里的假設(shè)才是真憑據(jù)第 15 篇雙向同步必須先定主屬側(cè)第 16 篇只讀內(nèi)核加外部規(guī)則表是檢查工具的正確形態(tài)第 17 篇圖紙目錄必須由核驗(yàn)結(jié)果生成第 18 篇數(shù)據(jù)字典先行、快照不可變、變更集必須能重建第 19 篇而最后的最后——查不到就標(biāo)注以官方文檔為準(zhǔn)絕不編造。本篇認(rèn)知問(wèn)題回顯FAQQ1一堆腳本憑什么能組成工具箱A靠分層。把會(huì)變化的東西按穩(wěn)定性分層隔離環(huán)境探測(cè)層安裝位置、部署方式、升級(jí)節(jié)奏會(huì)變、數(shù)據(jù)訪問(wèn)層產(chǎn)品版本、屬性名、導(dǎo)航語(yǔ)法會(huì)變、規(guī)則層業(yè)務(wù)規(guī)定與閾值會(huì)變、批處理層調(diào)度與并發(fā)策略會(huì)變、交付層格式與接收方要求會(huì)變。越靠下越穩(wěn)定上層依賴下層提供的事實(shí)因此結(jié)構(gòu)本身表達(dá)了依賴方向。Q2為什么環(huán)境探測(cè)層排在最下面A因?yàn)樯厦嫠膶拥囊磺信袛喽冀⒃谒峁┑氖聦?shí)上數(shù)據(jù)訪問(wèn)層要確認(rèn)屬性名是否存在、規(guī)則層要確認(rèn)依據(jù)文件的版本、批處理層要知道連接了哪個(gè)庫(kù)與權(quán)限范圍、交付層要記錄產(chǎn)出物對(duì)應(yīng)的產(chǎn)品版本。環(huán)境探測(cè)清單如 probe_install.csv、pml_lib_census.csv、asm_identity.csv是工具箱的地基而且必須作為交付物隨包交接不能只交腳本。Q3PDMS 已停售停支持為什么還要做雙軌A因?yàn)榇媪宽?xiàng)目不會(huì)因產(chǎn)品停售而消失老項(xiàng)目仍在原環(huán)境維護(hù)、新項(xiàng)目按 E3D Design 建設(shè)。雙軌的實(shí)際成本遠(yuǎn)低于直覺(jué)五層里只有環(huán)境探測(cè)層與數(shù)據(jù)訪問(wèn)層是產(chǎn)品相關(guān)的規(guī)則層、批處理層與交付層完全共用?？刂齐p軌失控靠三條原則差異顯式化統(tǒng)一標(biāo)記并讓自檢輸出當(dāng)前判定、公共部分最大化上下三層不復(fù)制、單點(diǎn)分叉差異收斂到少數(shù)函數(shù)。Q4回歸測(cè)試要測(cè)什么、測(cè)多少A只測(cè)三層冒煙層能否加載、版本函數(shù)能否返回、PMLLIB 是否含本工具箱目錄、契約層核心函數(shù)的返回契約是否符合三態(tài)前綴與字段位置、端到端層一條最小完整流程選小范圍、跑檢查、產(chǎn)出報(bào)告、核驗(yàn)報(bào)告。不測(cè)內(nèi)部函數(shù)細(xì)節(jié)邏輯、UI 視覺(jué)效果與極端輸入組合因?yàn)榫S護(hù)成本高于收益。回歸觸發(fā)時(shí)機(jī)是工具箱改動(dòng)后、產(chǎn)品升級(jí)前后各一次、以及交付前。Q5交付清單要交什么才讓接手人不罵人A七組環(huán)境事實(shí)、能力邊界含明確的不支持清單、代碼資產(chǎn)、配置資產(chǎn)規(guī)則表、字典、清單、契約——最易漏交、紀(jì)律資產(chǎn)鐵律與評(píng)審要點(diǎn)、卸載說(shuō)明——最易漏交、驗(yàn)證資產(chǎn)最近一次回歸結(jié)果與已知未通過(guò)項(xiàng)、運(yùn)行資產(chǎn)作業(yè)賬本、模型臺(tái)賬、最近發(fā)布記錄。判斷標(biāo)準(zhǔn)是接手人能否只看清單在另一臺(tái)機(jī)器上完成安裝與運(yùn)行。