專案狀態

快照日期 2026-07-13．本頁內容為 tasks.md / docs/adr/ / docs/infrastructure.md 的人工彙整快照,正典以該等檔案為準,若有出入請以 repo 原始檔案為主。

部署狀態

環境
staging
網址
https://fms-module-staging.rytass.info
版本
持續部署中(staging;CI 每次 push staging 自動遞增 patch tag)
已上線運作:push `staging` 分支經 GitHub Actions(self-hosted)自動建置 api/console 兩個 image 推 GAR、apply 到 GKE `fms-module-staging` 並滾動更新;pod 2/2 Running,api `/health` 回 ok、console `/console` 回 200。基礎設施(GKE namespace、GAR repo、Cloudflare A record→Traefik LB)皆已備妥。DB/Vault 整合為 Phase 5 TODO。

推進路線(Phase 0～6)

Phase 0 — 專案初始化

已完成

Nx + pnpm monorepo 骨架、module boundaries、kernel 全域禁用規則、CI 骨架與本地 dev supervisor 皆已完成並實測。

  • Nx + pnpm workspace(libs 四包 + apps/api + apps/console + console-e2e)

  • kernel 禁用 Date.now/Math.random/無參數 new Date 的 lint 規則,已用探針檔驗證會擋下

  • CI lint → test → build 已設定並本機全綠;e2e 步驟先以註解保留

  • pnpm dev 本地 dev supervisor(管理 api:17703 + console:17702,支援自動重啟)

Phase 1 — shared 契約 + kernel 地基

已完成

完成 2026-07-06,黑箱驗證 GO。shared 型別契約與 kernel 地圖/基礎設施/單車搜尋落地,對抗查詢驗證 A*/JPS 零不一致。

  • shared:六子目錄 + branded types + 六份手寫 VDA 5050 JSON Schema,55 測試 coverage 100%

  • kernel/map:OccupancyGrid、StaticLayer/InflationLayer、RoutingGraph

  • kernel 基礎設施:Clock、xoshiro128**(bit-identical)、BinaryHeap、MovingAI parser

  • 單車 A*/JPS 決定性搜尋,黑箱驗證 15 組合 × 6006 條對抗查詢零不一致;kernel 116 測試 coverage 98.75%

Phase 2 — 多車規劃 + 派單(v1 演算法)

已完成

完成 2026-07-06,黑箱驗證 GO。PIBT + RHCR + Dispatcher 完成,死鎖防護歷經兩輪 NO-GO 修復後最終掃描死鎖發生率 0%。

  • PIBT(windowed)+ reservation table 執行層、RHCR 滾動窗口重規劃

  • Dispatcher:Hungarian 批次指派 + aging + safety override + preemption/commitment

  • 死鎖防護(兩輪 NO-GO 修復):忙碌車讓道、StallDetector、corridor-arbiter 死巷仲裁

  • 追蹤項:LaCAM* 完備性尚未補完(現行為工程化兜底,無形式化保證)

Phase 3 — 模擬引擎 + 立體儲位

已完成

完成 2026-07-06。DES + motion tick 混合引擎、虛擬車輛/RVO2/frontier、facility lift/shuttle 排程,並以 createWarehouse facade 整合為單一deterministic tick loop。

  • DES 事件佇列 + motion tick 混合引擎、確定性重放(ReplayLog snapshot 全等)

  • 虛擬車輛(梯形運動學 + 虛擬 LiDAR)+ RVO2 互避 + frontier 探索(三策略)

  • facility:tier-captive rack + P&D synchronization + DC cycle + ABC slotting

  • createWarehouse 整合波:孤兒單邊界已根治(lockedVehicleIds 固定點鎖定);kernel 467 測試綠

Phase 4 — Demo/Testing 平台

已完成

mezzanine-ui 操作介面、three.js 3D 主視覺(ADR-0014)、貨物物理連續性(ADR-0017)全鏈路完成,經多輪使用者回饋波與獨立代理黑箱驗證。

  • mezzanine-ui 操作元件:TaskWorklist、DispatchModal、KpiPanel、VehicleDetailPanel、AlertFeed

  • three.js 3D 深色主控台(ADR-0014),PixiJS WarehouseCanvas 降為 2D fallback 後移除(ADR-0016)

  • 貨物物理連續性(ADR-0017 v3 telemetry 即時鏡像):3 輪追修根除幽靈甲板箱/瞬移/提前出現

  • direct/pnd 交接模式可配置(RackSystemConfig.handover);最終整合黑箱驗證 7 項全 PASS

Phase 4.5 — 實體樓層 / 多倉並行

已完成

完成 2026-07-07(ADR-0015)。BuildingScenario 多層建築、多實例 Worker、useBuildingWorker 全棟編排落地;後續兩份 PIBT tie-break ADR(0018/0019)修復讓路蠕動問題。

  • BuildingScenario:每 floor 一個獨立 WarehouseHandle,單 setInterval 驅動全棟同步

  • useBuildingWorker:per-floor stream client、KPI/WMS 本層/全棟切換、跨層自動切層高亮

  • ADR-0018(2026-07-13):sticky goal 讓閒置車輛讓路後就地停留,不再歸位不一致

  • ADR-0019(2026-07-13):候選排序加入側向優先層級,消滅開放區域推擠蠕動(1-wide 走廊拓樸性蠕動仍殘留,已聲明範圍界線)

Phase 4.6 — 部署骨架(無狀態)

已完成

2026-07-13。比照 BPMCore 複製 Dockerfile/CI/K8s manifest,沿用既有 GKE/GAR/Cloudflare 基礎設施;已實際部署上線,staging 現以 v0.0.2 運作。

  • 多階段 Dockerfile(api/console 雙 build-arg target)+ .github/workflows/staging.yml

  • tools/deployment-staging.yml:單 Deployment(api 17703 + console 17702)+ Traefik IngressRoute

  • 已上線:push staging 分支經 CI 自動建置/推 GAR/rollout,pod 2/2 Running、/health ok、/console 200

  • 待補(Phase 5):Vault path、migrate initContainer、vault-secret 範本、cloud-sql bootstrap

Phase 5 — NestJS 模組 + 車機閘道

待啟動

尚未啟動。規劃 FmsRootModule 持久化/GraphQL 層、雙層事件、VDA 5050 車機閘道,以及 console 從純前端模擬切換到連線模式。

  • FmsRootModule + 子模組、Symbol token 全表(ADR-0004)、Order → Item → Change entity + GraphQL

  • 雙層事件(operation + domain、post-commit flush、beforeHooks)

  • VehicleGateway:in-memory(模擬)+ MQTT(VDA 5050)transport,base/horizon 增量放行

  • apps/console 連線模式(SSE telemetry + GraphQL 指令)+ e2e

Phase 6 — 進階(規劃過但不阻塞發布)

待啟動

已規劃但不阻塞發布的進階演算法/排程精修項目。

  • LaCAM* + MAPF-LNS 精修(ADR-0008 v2 完備性保證)

  • orientation + 轉彎成本 + 固定單行道 highway

  • lift look-ahead 排程、動態 re-slotting

  • SIPP 連續時間(v3)、拖曳排單

ADR 索引

ADR
標題
狀態
日期
ADR-0001
以 ADR 記錄架構決策
Accepted
2026-07-05
ADR-0002
Monorepo 佈局與工具鏈
Accepted
2026-07-05
ADR-0003
套件切分與依賴邊界
Accepted
2026-07-05
ADR-0004
Host 整合模式(DynamicModule + Symbol Token 注入)
Accepted
2026-07-05
ADR-0005
測試策略
Accepted
2026-07-05
ADR-0006
Kernel 領域模型(openTCS 式五件式抽象)
Accepted
2026-07-05
ADR-0007
地圖表示與導航堆疊(SLAM/探索/避障的模擬與介面分工)
Accepted
2026-07-05
ADR-0008
多 AGV 路徑規劃與交通管理
Accepted
2026-07-05
ADR-0009
動態派單與優先權機制
Accepted
2026-07-05
ADR-0010
立體儲位設備排程與儲位指派
Accepted
2026-07-05
ADR-0011
車機介接協議(VDA 5050)
Accepted
2026-07-05
ADR-0012
模擬引擎架構(DES 核心 + 確定性 + 同構部署)
Accepted
2026-07-05
ADR-0013
Demo/Testing 平台 UI(渲染、即時資料流、排單介面)
Accepted
2026-07-05
ADR-0014
主視覺改為 three.js 可旋轉 3D 場景
Accepted
2026-07-07
ADR-0015
實體樓層 = 多 WarehouseHandle 並行
Accepted
2026-07-07
ADR-0016
Console 移除 2D 平面檢視
Accepted
2026-07-08
ADR-0017
Rack 貨物階段 telemetry(wire contract v3)與 shuttle 空跑建模
Accepted
2026-07-10
ADR-0018
閒置車輛讓路後就地停留(sticky positioning)
Accepted
2026-07-13
ADR-0019
讓路優先側向(tie-break 層級,非覆蓋 heuristic)
Accepted
2026-07-13
ADR-0020
Facility task cancel/fault API 與物理 rollback 語意
Accepted
2026-07-19

待處理問題

問題
範圍
嚴重度
說明
TypeScript 7 / ESLint 10 major 升級待評估(Dependabot Stage 2)
相依套件
低
Stage 1 已於 2026-07-19 完成:nx 22→23 + reflect-metadata 0.2 + overrides 清掉全部 32 條 advisory(15 high)。殘留 TypeScript 5.9→7.0 (4 年最大 breaking、無 security 價值)與 ESLint 9→10 + plugins 為 Stage 2,獨立評估後再做;目前無排程壓力。
Phase 5 NestJS 模組與車機閘道尚未啟動
Phase 5
中
FmsRootModule、雙層事件、VehicleGateway(VDA 5050)與 console 連線模式皆待啟動;啟動前 apps/api 仍是無 DB/TypeORM 的 Phase 0 空殼。
Staging 部署 DB/Vault 整合待補
部署
中
目前部署骨架為無狀態版本:尚無 Vault path、migrate initContainer、vault-secret 範本與 cloud-sql bootstrap,需等 Phase 5 apps/api 接上 TypeORM 後補齊。
Facility scheduler cancel/fault API 與物理 rollback 已實作(ADR-0020)
kernel / facility
低
ADR-0020 已 Accepted 並實作(2026-07-19):WarehouseHandle.cancelStorageOperation 原子取消 AGV leg + facility task,依 cargo stage 分級處理 — clean cancel (未離開 source cell)、rolling-back (在 shuttle/lift 上以 reverse chain 倒帶)、 at-pnd spawn put-back。孤兒貨失效模式已解決(kernel +8 facility cancel 測試、 +4 warehouse cancel 測試)。Phase 5 後續:storage-in cancel 的 warehouse 層 bookkeeping、 fault injection 自動 rollback、cargo-on-AGV 反向 trip。
1-wide 走廊蠕動與 livelock 監控(已部分處理)
kernel / planning(ADR-0019)
低
2026-07-19 已做:through corridor 偵測 + bidirectional arbitration、farthest-in-corridor depth priority boost、livelock-suspected 監控事件、highway 基礎建設(RoutingGraph `highways` 選項、能力到位但 demo 未配置)。殘留:走廊入口 pre-commit(BL-01 backlog)、Phase 6.1 orientation+highway 落地。Phase 6.2 LaCAM* 補完備性後此區域全面關閉。
Phase 6 進階演算法精修(roadmap 已展開)
Phase 6
低
2026-07-19 已將 Phase 6 展開為可執行條目進 tasks.md:6.1 orientation+highway、6.2 LaCAM*+LNS(關閉 #14 livelock)、6.3 lift look-ahead+re-slotting、6.4 SIPP+拖曳排單 UI。依賴順序與面積已記錄,等排程啟動。