工作流程：透過 Web API 建構專案¶

基礎加工仿真說明專案裡有什麼。本頁說明如何把專案建到真正完成——避免返工的順序、任務該怎麼安排，以及那道驗收測試：它告訴你專案已經完成，而不只是填滿了。

本頁寫給依客戶交付物組出 .hincproj 的人——不論是操作瀏覽器介面的人，還是透過 HTTP API 執行同樣操作的代理程式 (agent)。某一步有 API 形式時，路由就寫在那一步旁邊。透過 API 重播並驗收建好的專案，見透過 HTTP API 進行重播驗收。

flowchart TD
    New["1 · 新專案<br>(自足的根目錄)"]
    Assets["2 · 放入資產<br>NC、STL、資源檔"]
    Equip["3 · 設備<br>機構鏈、主軸"]
    Job["4 · 工作<br>毛胚、目標幾何、材料"]
    Ctrl["5 · 控制器<br>品牌 + 它自己的表"]
    Tools["6 · 刀具庫"]
    Mission["7 · 任務<br>分組、各組各自的解析度"]
    Replay["8 · 重播並讀<br>每一則訊息"]
    Cross["9 · 數值交叉核對"]
    Assume["10 · 記錄每一個假設"]

    New --> Assets --> Equip --> Job --> Ctrl --> Tools --> Mission --> Replay --> Cross --> Assume
    Replay -->|任何警告| Ctrl

透過 API 建構，而不是編輯 XML¶

透過服務的 HTTP API 建立與修改專案。它與介面走的是同一條程式路徑，所以這樣建出來的專案，走的是受支援的建立／載入／儲存路線。手寫 .hincproj XML 只是 API 還碰不到的欄位的退路——而碰到這種欄位時，更好的解法是把那個端點補上。

下面各步所依賴的登入、回應封套、檔案根目錄、專案生命週期與以鍵編輯物件的模式，都在透過 HTTP 驅動網頁服務（英文，未鏡像），那一頁也列出框架自己的 OpenAPI 文件寫錯的請求本體。其中有三條規則，決定了一次腳本化的建置能不能信任：每一個回應都要檢查 success，而不只看 HTTP 狀態；透過鍵在幾何或變換器內部編輯之後，下一次執行之前要重新裝入那個欄位；不要操作別人正在使用的執行個體。

執行讀的是哪些端點¶

專案帶著兩個控制器模型：仿真播放所用的執行器，以及存在它旁邊的一個 legacy 模型。兩者有好幾條路由長得很像，而寫進 legacy 模型的值會被接受、儲存、讀回，一聲不吭，執行卻從來看不到它。機台資料要經由下面這些路由寫入：

資料項	執行讀取的路由	執行會忽略的相似路由
機構鏈	`POST /api/mech/machine-tool/load`——見下文	—
主軸能力	`POST /api/mech/spindle-capability/load-file` `{rootName, relFile}`	—
控制器品牌	`POST /api/mech/soft-nc-runner/brand` `{Brand, CopyWorkCoordinates}`	`PUT /api/Controller/cnc-brand`
X、Y、Z 行程	`PUT /api/Controller/stroke-limit-xyz` `[minX, maxX, minY, maxY, minZ, maxZ]`，單位 mm，會同時寫入兩個模型；或 `PUT /api/mech/soft-nc-runner/machine-limits/{axis}` `{Positive, Negative}`	—
快速進給率	`PUT /api/mech/soft-nc-runner/rapid-feedrates/{axis}` `{Value}`，mm/min（旋轉軸為 deg/min）	`PUT /api/Controller/rapid-feedrate`
原點／G28 參考點	`PUT /api/mech/soft-nc-runner/home-positions/{axis}` `{Value}`	—
換刀位置	`PUT /api/mech/soft-nc-runner/tool-change/{axis}` `{Value}`，或以 `{Stay: true}` 讓該軸停在原處	—
換刀時間	`PUT /api/mech/soft-nc-runner/tool-change/tooling-time` `{Value}`，單位秒	`PUT /api/Controller/tooling-time`
最高主軸轉速	`PUT /api/mech/soft-nc-runner/controller-params/max-spindle-speed` `{Value}`，rpm——只記錄、不讀取（§4）	—
副程式資料夾	`PUT /api/mech/soft-nc-runner/subprogram-folders` `{InternalFolder, ExternalFolder}`，相對於專案資料夾	—

程式資料表也有同樣的分裂：執行所解析的工件偏移與刀具補正，是執行器的那一份，位於 /api/mech/soft-nc-runner/ 之下（§4）。每一個值都要在儲存並重新載入之後，用同一條路由的 GET 讀回來。

載入機構鏈¶

從檔案載入時，機構鏈經由 POST /api/mech/machine-tool/load 載入，本體為 {"RootName": "ProjectDirectory", "RelFile": "MachineTool/<name>.mt"}。RootName 是 ProjectDirectory 或 ResourceDir，其他任何根目錄都會以 400 拒絕。因此，在別處建好的機構鏈要先放進專案資料夾——經由檔案路由上傳——再從 ProjectDirectory 載入。在 ResourceDir 底下挑中的機構鏈，會連同附屬檔案以相同的相對路徑寫進專案，並在那裡被參照。（POST /api/mech/machine-tool/update 安裝的是已經在物件存放區裡的機構鏈，…/create 則安裝一個空白的刀位 (cutter-location) 裝置；兩者都不讀檔案。）

不論載入成功與否，這條路由都回應 HTTP 200：檔案不存在，或載入器拒收的機構鏈，會以 "success": false 回來，原因寫在 message 裡。成功時，本體會寫出機構鏈的 typeName 與專案所記錄的 relFile，之後 GET /api/mech/machine-tool 也回報同樣的內容。載入的回應不帶載入器的訊息：機台缺少的端錨點、或大小寫寫錯的端錨點，會回報到服務日誌（GET /api/Project/logs），並在專案儲存之後，出現在下一次 POST /api/Project/reload 的 messages 裡。兩個端錨點缺了任何一個的機台都無法執行。資源庫裡沒有的機台，可以不帶任何形狀建出來——見沒有模型的機台。

1. 單一自足的根目錄¶

.hincproj 與它參照的每一項資產都放在同一個資料夾底下——專案自己的目錄——而每一個參照都相對於它，不帶 ../。

<project>/
├── <name>.hincproj
├── NC/                     任務播放的程式
├── Delivered/              客戶的檔案，與收到時完全一樣
├── Geom/                   工件／夾具 STL
├── MachineTool/            運動學機構鏈
├── SpindleCapability/
├── WorkpieceMaterial/
├── CuttingParameter/
├── CutterMaterial/
└── README.md               假設了什麼，以及為什麼

有兩樣東西不會自己搬過來，所以在接上任何東西之前，先手動把它們帶進來：

NC 檔案。 程式檔案命令只存一個單純的相對路徑，沒有任何東西會替你複製檔案。
工具機的附屬檔案。 把機構外置的機構鏈，以不帶路徑的檔名參照附屬檔案與它的 STL 實體，相對於 .mt 自己所在的資料夾——整個資料夾要放在一起。

資源檔（機構鏈、主軸、切削參數、工件材料、刀具材料）是事先備好、以參照載入的資料。從 Resource 根目錄載入其中一個，會在相同的子路徑——例如 WorkpieceMaterial/<name>——寫出專案自己的副本，並記錄那個相對於專案的路徑，所以儲存後的專案從不指向共用資源庫；已經在專案裡的檔案，就在原處被參照。先把檔案上傳進專案、再從 Project 根目錄載入，結果相同，而且在每個版本上都行得通：每次從資源庫挑選之後，都要確認副本已經落在專案資料夾裡，沒有的話就自己上傳（檔案與具名根目錄（英文，未鏡像））。

程式：保留交付原件，播放副本¶

每一支程式都照客戶交付時的原樣保留在 Delivered/ 底下，播放的是 NC/ 裡的副本。只做兩種修改，而且只改副本：

呼叫查找所需的檔名。 以編號呼叫的副程式或巨集，只會在副程式資料夾裡的一組固定檔名下被找到——P25 呼叫找的是 O0025.NC 或 O25.NC 等等；見通用 NC 碼支援。以 O25.dat 交付的被呼叫程式，就以其中一個檔名複製一份，內容一字不動。找不到的被呼叫程式會回報為錯誤，該次呼叫被跳過，執行仍會跑完——而所有切削都在被呼叫程式裡時，就什麼也沒切到。
會改變結果的寫法。 當一次重播顯示，有某種結果所依賴的寫法，讀取器沒有照它的意思處理——由變數選定的 G 碼（G[#120]）、以變數寫成的巨集引數（G65 P25 A#120）、軸字排在同一單節另一個 G 碼之後的參考點返回（G91 G28 G0 Z0）——就把副本裡的那一行改寫成機台實際執行的字面形式（G[#120] 的值為 55 時寫 G55；G65 P25 A55；該單節是讓 Z 回原點時寫 G91 G28 Z0），其餘每一行都維持交付時的樣子。

每一份改寫過的副本，開頭都加一行註解說明改了什麼，並在專案的 README 裡列出同樣的修改與各自的理由，好讓副本能與交付原件逐行比對。等某個版本能原生讀取那種寫法時，就撤掉改寫，改播放交付的那一行。

只會引發一則已知訊息、不改變運動的寫法——具名的程式標頭、平滑化或前瞻 (look-ahead) 碼、讀取循環時間計時器——可以維持交付時的樣子。把它們以預期訊息列在 README 裡，寫明 id 與每次播放出現的次數，這樣下一次重播就拿這份清單來核對，而不必再調查一次。

2. 安排建置順序以避免返工¶

後面的步驟會讀前面的結果，所以這個順序花費最少：

新專案，建在它最終的路徑上。它不是空的——見 §3。
工具機，然後是主軸能力。
工件：毛胚幾何、目標幾何、解析度、工件通往程式原點錨點與夾具安裝點那兩條連接的變換器，然後是材料與切削參數。零件若是以 CAM 匯出的網格送來，而不是分別標明的毛胚與設計 CAD，就先判斷那個網格是什麼、程式原點在它的哪裡——見由參照網格建立工件，那一頁也列出 STL 欄位的 API 呼叫。
控制器：先定品牌——之後再切換品牌會重設品牌專屬的表——然後是控制器自己的表（§4）。
刀具庫，逐把刀具依這個順序——每一步都讀前一步的結果：
1. 先建立，再編號。 新刀具取刀具庫裡最大號碼再加一；把它改號成程式所呼叫的 T 號（POST /api/ToolHouse/CreateTool，再 POST /api/ToolHouse/RenameTool?toolId=…&newId=…）。補正表更新之後，這個號碼也就是 H 字與 D 字所讀的補正列。
2. 刃包絡形（PUT /api/Cutter/{id}/shaper-profile），例如 {"AptType": "BallApt", "Diameter_mm": 4, "FluteHeight_mm": 5}；AptType 是 ColumnApt、ConeApt、BallApt、TaperApt 與 GeneralApt 之一，不分大小寫，帶不帶 Apt 都可以。球形輪廓只需要直徑與有效切削長度。刀具本體的路由會在第一次使用時建立該刀具的銑刀，所以不必另外呼叫。
3. 刃雕構型（PUT /api/Cutter/{id}/fluting），放在刃包絡形之後：刃是依當下的包絡形建出來的，所以包絡形每次變更之後，都要重新送一次刃雕構型。它是整份取代的："Type": "uniform" 是必要的——其他任何值都以 400 拒絕——而且沒送的其他每一個欄位都取這條路由自己的預設值——2 刃、螺旋角 30°、徑向前角 0°、徑向後角 5°、刃偏移角 0°。前角 0° 並不是中性值，因為前角決定每個刃點所產生之力的方向；刀具表沒給時，依工件材料選一個（刀具幾何）。每一個值都要送，包括先前輸入過的刃偏移角，以及側向刃雕本身（"SideContour": {"Type": "consthelix", …}）：沒帶側向刃雕、或帶著這條路由不認得之類型的刃雕構型，一樣會被接受，而刃上就沒有側刃。
4. 刀尖至刀把鼻端高度——也就是伸出量（PUT /api/ToolHouse/{id}/exposed-height）。新刀具從 0 開始，刀具本體藏在刀把裡。
5. 安裝角——刀具本體在刀把裡轉過多少（PUT /api/ToolHouse/{id}/setup-angle，請求本體就是一個單純的度數）。它預設為 0，只有銑削物理會讀它；刃的角位置有影響時就要填，例如以感測器自己的座標系回報的智慧刀把（智慧刀把）。它是夾持的屬性，所以重新送出刃雕構型也不會把它洗掉。
6. 刀把。 先列出資源庫（GET /api/file-explorer/list?rootName=ResourceDir&relativePath=Holder）：那裡的 .Holder 檔帶著完成的輪廓。沒有任何路由能把它載入到刀具上，所以用 GET /api/file-explorer/read-text 讀它，再照下面的方式把它的 Z–R 數對整份送出。設定刀把類型（POST /api/ToolHouse/SetHolderType），讀取它的輪廓鍵（帶著工作階段鍵呼叫 POST /api/CylindroidHolder/Get，會在 cylindroidKey 裡回應，形式為 <sessionKey>-HolderCylindroid），用 POST /api/Cylindroid/UpdateAllPairs 取代整份輪廓——新柱狀刀把的輪廓是從 Z 40 到 Z 80 的 Ø6 佔位，在刀把重新導出它之前不會增加任何長度——然後呼叫 POST /api/CylindroidHolder/UpdateGeometryContent，讓刀把重新導出它的長度。輪廓的座標系見刀具幾何。
7. 夾持柱。 經由刀具本體建立它（POST /api/Cutter/{id}/upper-beam/create?kind=Cylindroid&key=…——新的柱狀體存放在你傳入的鍵之下），在那個鍵上用 POST /api/Cylindroid/UpdateAllPairs 寫入數對——從刀尖量起，第一組在刃頂，最後一組在刀具全長處（刀具幾何）——然後呼叫 POST /api/Cutter/{id}/upper-beam/resync，並讀它傳回的警告；空清單就是通過。
8. 刀具材料，刀具有塗層的話也包括塗層。沒有刃部材料的刀具不會執行熱物理，也不會回報降伏應力比（Tool-FluteMaterial--Missing）。
9. 智慧刀把的觀測點，在刀具帶著感測器時。新刀具指向刀把鼻端，高度為 0；見智慧刀把。
接著從刀具庫更新補正表，並核對每一個刀長列是否等於刀把的量規長度加上伸出量。GET /api/ToolHouse/{id} 會傳回儲存的刃雕構型、包絡形與夾持數值——setupAngle_deg 也在其中——供最後一次讀回核對。
程式原點：工件擺好、機構鏈載入之後，依這件工作所需的方向把兩者對齊——見程式原點對齊。客戶提供了記錄下來的偏移時，保留它們，把零件移到它們上面（§4）；只有在規劃一件沒有記錄偏移的工作時，才從模型推導出一列。好幾件零件共用工作臺時，只有帶著程式原點錨點的那件零件，它那一列可以來自模型：其他零件的各列，是那一列加上零件間距。
任務（§3）。
儲存，然後把存好的檔案載回來再檢查一次。無法乾淨地重新載入的專案，就還沒建好。

載入工具機之後核對軸組（重要）

載入工具機之後要核對軸組。每一根軸都是工具機的一個角色（AxisX … AxisC），繫結到它的某一條連接上；機構鏈檔案是依連接名稱（X/Y/Z/A/B/C）繫結它們的，所以一條還停在編寫時預設名稱的連接不會繫結任何軸，那根軸就悄悄地不存在。對線性軸而言，控制器的軸清單顯示不出這一點——每個品牌預設組都已宣告了 X、Y、Z，而機構鏈只會增加軸——所以要讀角色：GET /api/mech/equipment-topology/roles/machine-tool 列出每一根軸、它所繫結的連接，以及它的檢查結果（未繫結的軸就只是未繫結；AxisTransformerMismatch 點名種類不對的連接）。每一根軸都需要一條帶著 DynamicTranslation（X、Y、Z）或 DynamicRotation（A、B、C）的連接；機構鏈本身用 POST /api/mech/machine-tool/xml 取得。主軸（Spindle）不是軸，而且是按拓樸找的，不是按名稱：抵達刀具安裝點所掛之處的那條連接，帶著繞刀具安裝點 −Z、穿過其原點旋轉的 DynamicRotation 時，就是主軸。沒有主軸的機台照原本的方式播放，只是主軸在畫面上不會轉；旋轉軸偏離刀具軸的會被標為 SpindleOffToolAxis。

3. 依製程而不是依檔案清單安排任務¶

新專案一建立，裡面就已經有任務：五個設定類命令、兩個指名佔位檔案 NC/NC-File-Name-1.nc 與 NC/NC-File-Name-2.nc 的程式檔案項目，以及一個所有輸出都關閉的執行後作業。每個佔位項目在每次播放時都會引發錯誤 RunNcFile--NotFound 並被跳過，而經由 POST /api/Mission/list-command/entries 新增、沒帶插入索引的項目，會落在它們之後。編輯這些預先放入的項目，或從最後一個索引往前用 DELETE /api/Mission/list-command/entries/{path} 刪除它們——被刪項目之後的 path 會重新編號——再用 GET /api/Mission/list-command/entries 讀回結果。

一份平鋪的程式檔案清單執行起來是對的，但讀起來很糟，而且整件工作只給你一個旋鈕。把程式分組，每一類工序一個清單命令，依製程實際執行的順序排列：

運動解析度
碰撞偵測                 [關]
失敗時暫停               [關]
物理模擬                 [開]
記錄網格幾何             首次讀取，否則寫入 · Cache/0-stock.wct         （僅限 STL 毛胚）
▸ 1 · 鑽孔                        加工解析度 0.5 mm
      中心鑽、鑽孔
      記錄網格幾何                首次讀取，否則寫入 · Cache/1-drilling-done.wct
▸ 2 · 外形粗加工                  加工解析度 0.5 mm
      粗加工 1 … 5
      記錄網格幾何                首次讀取，否則寫入 · Cache/2-outside-roughing-done.wct
▸ 3 · 外形精加工                  加工解析度 0.2 mm
      精加工 1 … 7
      記錄網格幾何                首次讀取，否則寫入 · Cache/3-outside-finishing-done.wct
▸ 4 · 挖槽粗加工                  加工解析度 0.5 mm
  …
▸ 8 · 去毛邊                      加工解析度 0.2 mm
執行後處理                        幾何差異偵測 開

為什麼是這個形狀：

記錄是形狀的一部分，而不是一項優化。 毛胚是 STL 時，在第一個群組之上保留一筆記錄網格幾何項目：毛胚是在第一行 NC 播放之前、以工件的初始解析度網格化的，而三角化很細的 STL，在被快取之前，每一次播放都要為此花上幾分鐘。每個群組都以一筆以該群組命名的階段末記錄收尾，這樣之後的執行就能從其中任何一筆接續。之後若變更毛胚幾何或它的初始解析度，快取的毛胚不會跟著更新，直到把快取檔刪除為止。完整的配置見能接續的任務。
分組不能改變順序。 毛胚從一道工序演變到下一道，所以順序本身就承載著結果。只把相鄰的工序分在一組；如果整理成整齊的類別會讓某道工序越過另一道，就絕不要這樣排序。
每個群組帶著自己的加工解析度。 粗加工關心的是力，不是表面，所以粗的解析度就夠了，而且跑得快。精加工、肋部與去毛邊的加工是用小刀與球刀留下最終表面，值得用更細的解析度。在任務中途設定解析度，只會改變實際切削時所用的值——工件不會重建，而幾何容器是自適應的——所以在群組之間粗細交替是安全的。
一個群組就是一個開關。 停用一個清單就跳過整個階段，這就是不刪除任何東西、只重跑精加工的方法。
用短程式反覆調整；完整的工作放在旁邊，關著。 重播整件工作是驗收用的執行，不是除錯迴圈。在基準、刀具與偏移都還在變動時，把一支衍生出來、只跑工作中一個代表性片段的主程式——對於夾在同一塊夾具板上的四件相同零件，就是加工第一件零件的那一段程式——放進它自己的清單裡播放，並把完整程式放在第二個清單裡、取消勾選它的核取方塊；以本體 true 或 false 呼叫 PUT /api/Mission/commands/{path}/enabled，就能切換執行哪一個。把第 0 階段的記錄放在根層級、兩個群組之上，讓兩種版本都從同一份快取的毛胚開始，並給每種版本各自的階段末檔案。新專案最初的幾次播放，最可能產生不出任何步、或切在錯的地方，而一支只有一件零件的程式，只要一小部分時間就能讓這些問題現形。
為細的群組編預算。 加工解析度決定的是移除材料的成本，而不是仿真步的數量——步數跟著運動解析度走，不會改變。在一件 33 道工序的工作上，把精加工群組從 0.5 mm 細化到 0.2 mm，步數完全相同，實際耗時則變成約 2.8 倍。決定精加工解析度時要把這個取捨放在眼前，並在專案的 README 裡寫明它的代價，免得有人意外。
設定類命令是細分的。 加工解析度、運動解析度、碰撞偵測、失敗時暫停與物理模擬是各自獨立的命令，所以每一個都能放在它該生效的確切位置——全域的放在最上面，各階段專屬的放在群組裡。

透過 HTTP 時，任務是一次一個項目建構起來的。POST /api/Mission/list-command/entries 在根層級新增，POST /api/Mission/list-command/entries/{path} 在某個清單裡新增，本體為 {"CommandType": "<kind>", "IsEnabled": true}，可另帶 "InsertIndex"；回應中的 path 就是新項目在之後每一次呼叫中的位址。path 是以點串起來的一串索引——6 是根層級的第七個項目，6.1 是它裡面的第二個項目。各路由預期的值：

項目	值
`CommandType`	命令的類別名稱去掉 `Command`、轉成小寫：`list`、`ncfile`、`nccode`、`script`、`machiningresolution`、`machiningmotionresolution`、`collisiondetection`、`pauseonfailure`、`physics`、`recordmeshedgeom`、`postexecution`、`exportmeshedgeom`、`ncoptoption`；`GET /api/Mission/command-catalog` 列出這個服務可以新增的那些
清單標題	`PUT /api/Mission/commands/{path}/listcommand`，本體為 `{"Title": "…"}`
程式檔案	`PUT /api/Mission/commands/{path}/ncfile`，本體為以 JSON 字串表示、相對於專案的路徑
開／關類的設定命令	`PUT /api/Mission/commands/{path}/fields/enable`，本體為 `true` 或 `false`
加工解析度	`PUT /api/Mission/commands/{path}/fields/machiningResolution_mm`，本體為一個數字
運動解析度	`PUT /api/Mission/commands/{path}/machiningmotionresolution/type`，本體為 `"feedpercycle"`、`"feedpertooth"` 或 `"fixed"`
記錄網格幾何	`PUT /api/Mission/commands/{path}/recordmeshedgeom/main-action`，本體為 `"ReadOnFirstOrWrite"`，並以 `…/rel-file` 設定快取檔

需要的欄位不在表中時，GET /api/Mission/commands/{path}/fields 會列出命令的各個欄位鍵。

Tip

載入了目標幾何卻從不拿來比對的專案，就是沒完成。在執行後作業命令裡打開幾何差異偵測，讓完整重播以量測已加工毛胚與成品零件的差異作結。沒有目標可比對的差異什麼也不做，卻仍會回報它已建立——怎麼分辨，見幾何驗證。

4. 填好控制器自己的表¶

刀具庫描述的是實體刀具。控制器對同一把刀具有它自己的記錄，而 NC 程式讀的是控制器那一份。兩者都必須存在。

以 Siemens 式的控制器而言，那是兩張表：

表	存放	若是空的
刀具名稱 → 刀號	`T="…"` 呼叫所用的名稱	刀具永遠不會裝上，程式完全不產生任何加工步
刀刃補正	每個 `(tool, edge)`（刀具、切削刃）：沿刀軸的長度、半徑	每一次刀刃呼叫都退回通用補正表，並記錄一則警告

數值取自刀具庫，並且寫入之前先斷言兩者相符。警告消失、切削位置卻完全沒動，就證明各列帶的數字是對的——幾何若有偏移，就是兩張表之一錯了。

Note

並不是每一個控制器參數都有讀取它的一方。有些——例如最高主軸轉速——是記錄下來的機台資料，目前處理流程裡沒有任何東西會讀它。把它們填上是好習慣，但不要把這件事回報成修好了一個缺陷；也要記得，把一個猜測的值（例如假設的主軸）複製到第二個地方，就表示真實資料送到時兩處都要改。

透過 API 設定工件偏移¶

服務公開了兩張工件偏移表，而它們不會保持同步：

表	路由	讀取者
執行器自己的表——在 Fanuc 與 Mazak 上是參數表（`#5221`+、`#7001`+）	`GET /api/mech/soft-nc-runner/work-coordinates`、`PUT …/work-coordinates/{id}` `{X, Y, Z}`	執行，以及設備頁面的工作座標 (G54…) 葉節點
legacy ISO 座標表	`GET /api/Controller/iso-coordinate-table`、`PUT …/iso-coordinate-table/{index}` `{Index, X, Y, Z}`	下面的對齊呼叫、執行頁的座標標記，以及指名它的腳本

程式選用的每一列都要寫進執行器的表，然後在儲存並重新載入之後讀回來。只填 legacy 表的建置，會繞著機械零點播放整支程式：什麼都沒切到，唯一的徵兆是一則 Play-Touch--None 警告，因為停留在零的 G54–G59 列會被當成一種編寫慣例，不發出任何訊息。使用對齊呼叫時，也要把同一列寫進 legacy 表。它的 PUT 只能編輯表裡原本就有的列（G54–G59 與 G59.1–G59.9），其他任何 id 都回應 400。

一列是每根軸都在機械零點時，主軸的刀具安裝點與程式原點相遇的那個機械位置。刀具長度不在其中：G43 H 所選的長度補正會加上刀把長度與伸出量。在程式不做長度補正的情況下、拿刀具對刀記錄下來的偏移，已經包含了那把刀的長度，輸入之前必須先換算。

透過 API 把零件擺到記錄的偏移上¶

重現的方向——保留記錄的偏移，把零件移到它上面——只要一個呼叫：POST /api/Controller/iso-coordinate-table/{index}/align-workpiece-program-zero。它從 legacy 表讀取 {index} 列，把夾具那條從幾何錨點通到床台安裝點的連接上的變換器，改寫成一個靜態平移，使程式原點錨點在每根軸都位於機械零點時落在那個偏移上。回應帶著這個平移，以及變換器改寫前後的 XML；把「改寫前」的 XML POST 到 …/iso-coordinate-table/revert-align-workpiece-program-zero 就能復原。任務腳本裡的同一項操作是 AlignWorkpieceProgramZeroToIso("G54")。

它需要專案上有夾具，以及一條帶線性軸（旋轉軸可有可無）的機構鏈。缺了任一樣，它都回應 400，什麼也不改；純粹的刀位裝置不算這樣的機構鏈。
它寫入的是從夾具的幾何錨點直通床台安裝點的那條連接——預設形狀的夾具都有這條連接。夾具沒有這條連接、這條連接帶的是動態變換器，或從工作臺到程式原點的路徑不是只經過這條連接時，它會回應 400 並附上原因，什麼也不改。
它會以純平移取代那條連接原本的內容，旋轉也包括在內。
它只讀一次工件幾何座標系，以及工件通往夾具安裝點與程式原點錨點那兩條連接的現況。先把這些設好，改動其中任何一個之後都要重新對齊。

用探測來證明擺放，而不是信任這個呼叫。在第一次播放之前、或按下重置之後——在重置之前，播放過的工作階段會一直沿用它開始時的擺放——在一個程式從不使用的列上按 P0：POST /api/Controller/iso-coordinate-table/G59/set-to-program-zero 會回應它寫入的 X、Y、Z，這些值必須在捨入誤差內等於記錄的那一列。儲存之前，用 …/G59/set-to-machine-zero 把探測列恢復成機械零點。執行器的 POST /api/mech/soft-nc-runner/work-coordinates/{id}/set-to-program-zero 只回應 success；它的值要用 GET /api/mech/soft-nc-runner/work-coordinates 讀取。

對齊之後，記錄偏移裡的錯誤就不再改變切出什麼，但它會讓整套設置在機械座標裡整體位移，而行程檢查與機台碰撞都看得到這個位移。同一張工作臺上有好幾件零件、每件一個偏移時，P0 只能填帶著程式原點錨點那件零件的那一列——見幾件零件、幾個偏移。

5. 終點是一次乾淨的重播，而不是填滿的表單¶

重播整個任務，並依 id 盤點訊息。 每一則警告都是待辦清單上的一項。不要把任何一則寫成可接受的退路：退路被觸發，就表示專案從沒提供那個退路本來要補上的資料。

讀取訊息時把嚴重性門檻設低，才不會漏掉任何一則。嚴重性有 Message、Success、Progress、Warning、Error——注意沒有 Info，而無法辨識的名稱是在回應本體裡被拒絕，而不是以 HTTP 錯誤拒絕，讀起來跟「沒有訊息」一模一樣。

只剩下已宣告的資訊性訊息——那些陳述一項已知、刻意之限制的訊息——再加上維持交付原樣之寫法的預期訊息（§1），而且每一則都以 id 及它為何不改變結果的理由列在 README 裡時，才停下來。典型會留下來的訊息：

每個 NC 檔一則，回報行數；
執行器認得並消化、但不建模的機台 M 碼（OEM 輔助功能，例如冷卻液閥），它們會被宣告出來，而不是悄悄忽略。

其他任何訊息都是待做的工作。

乾淨的訊息清單還不等於通過。 從未裝上刀具的執行完全不產生步，仍以 Finished 結束，也不發出播放結束的警告；而沒有先重置就開始的執行，會疊在上一次執行之上播放。這兩者，連同抓出它們的檢查，都在透過 HTTP API 進行重播驗收裡。

6. 兩項數值交叉核對——以及它們證明不了什麼¶

訊息抓到的是執行器注意到的東西。這兩項抓的則是完全不產生訊息的基準錯誤。

切削深度對照程式的層深。 在一趟能從 NC 讀出每層下刀量的粗加工上，切削深度的峰值必須等於它。這就釘住了 Z 基準：程式原點若錯了，刀具切下的量就不同，峰值也不會落在程式的數字上。精加工程式沒有層深可讀；改拿它留下的表面來核對它的基準（由參照網格建立工件）。

循環時間對照後處理器自己的估計。 許多後處理器會把每道工序的加工時間以註解寫進程式。把它們加總，與仿真時間比較。

Warning

誠實界定循環時間核對的範圍。它確認的是進給率與路徑長度被正確地採用。它不是與真實機台的比較，因為兩邊忽略的是同樣的東西：沒有加速度模型（時間是路徑長度除以進給率，沒有加減速——這在由數千段短線段構成的精加工上代價最大）、換刀時間預設為零，而且在控制器的原點／G28 參考點與換刀位置表依機台資料填好之前，原點與換刀位置都預設為機械零點（換刀時 Z 移到 0，X 與 Y 不動）。

基於同樣的理由，客戶的「總加工時間」遠高於各工序註解的總和，通常並不矛盾——註解是切削時間，總時間則是包含換刀與工序間移動的實際時間。這是兩個不同的量。

7. 記錄每一個假設¶

真實的交付物都不完整。用合理的數值建置，並把每一個都寫進 .hincproj 旁邊的 README.md——假設了什麼、依據什麼推斷，以及真實數值送到時會改變什麼。常見的項目有：工件偏移、毛胚尺寸與材料、刀具的螺旋角與前角、塗層、伸出量、刀把尺寸、智慧刀把的感測器高度、主軸的功率–扭矩曲線、夾具幾何、對程式副本所做的改寫，以及上面的循環時間輸入。

對照：專案資料盤點清單是建置之前交給客戶的清單；本節則是建置之後交回去的東西。