程式架構¶

本檔角色：抽象介面、模組依賴、開發順序、Determinism 保證、測試矩陣、程式碼層次、頁面路由（SPA Routes）。對應模組（實作）：程式架構/interfaces.md / 程式架構/physics-engine.md / 程式架構/testing.md / 程式架構/toolchain.md。

1. 五個已接線抽象介面與一個保留接縫¶

詳見 程式架構/interfaces.md：

介面	用途
`SignalingProvider`	scoped WebRTC 握手；可換任意相容 WSS endpoint／GossipSub
`PhysicsEngine`	Rapier 包裝；step / snapshot / rollback / collider 管理
`AssetStorage`	尚未接線的內容儲存保留接縫；目前讀取走 `asset-source` / `UgcBlockSource`
`Ledger`	OrbitDB CRDT log + DerivedState
`KeyManager`	BIP39 助記詞 / Ed25519 / PIN 加密
`PinningProvider`	open-4wd-pinning 抽象

五個已接線介面各有 TypeScript 定義、目前實作與測試替身；AssetStorage 只保留未來替換點，首發不宣稱已有實作或注入 consumer。

2. 物理鏈三層架構¶

物理鏈只在此保留主幹指標：排序後輸入 → PhysicsEngine → Renderer／HUD；賽果事件在賽後進 ledger。公開介面、固定步、snapshot／rollback、CCD 與 Rapier 版本鎖定的 implementation authority 見程式架構/physics-engine.md 與程式架構/interfaces.md §3。

3. 模組依賴圖¶

system-constants（地基）
   ↓
interfaces + key-manager + security
   ↓
physics-engine + material-params + builtin-assets
   ↓
editor（Stage 2 編輯器）
   ↓
peer-discovery + signaling-service
   ↓
network-sync + ledger
   ↓
ugc-fork + anti-piracy + dmca + economy + ugc-rating
   ↓
matchmaking + reputation + moderation + room-runtime
   ↓
mechanics-catalog
   ↓
spectator + audio-system + chat-system
   ↓
settings + i18n + ui-kit + viewport + pages + themes + seo
   ↓
bootstrap + race-runtime
   ↓
versioning + pwa-offline
   ↓
testing（貫穿全程）

本圖只表示主要依賴脊柱與開發分層、不是模組 inventory 或嚴格 DAG；完整模組清單以 §9 為準。derive 層存在互饋與上行邊（ugc-rating ⇄ reputation：評分權重讀 getEffectiveScore、高評分里程碑回饋信譽 delta；ledger ⇄ economy：ledger 只可值引 economy/config、economy/state-helpers 葉檔，兩葉檔不得 runtime 回引 ledger；economy ← moderation 黑名單閘；matchmaking ← versioning 開賽前驗證；editor ← ui-kit 共用元件； audio-system ← themes 槽位解析 resolveAsset），以 interfaces 抽象 / 測試 stub 解耦先行。

4. 模組功能矩陣¶

模組類別	模組	主要功能
核心架構	`interfaces/`	5 個已接線抽象介面 + 1 個未接線保留接縫
	`physics-engine/`	Rapier 三層架構
	`physics-manifest/`	Canonical PhysicsManifest 衍生、完整性 digest、隔離 admission 重建與本機 receipt
	`weapon-physics/`	武器物理埠與武器類型共用定義
	`builtin-assets/`	公版資產（UGC-in-GLB 名錄；物理烘焙進 GLB extras、只差不上鏈）
	`asset-schema/`	UGC 資產 schema 與版本契約
UGC 規範	`material-params/`	31 種材質
	`ugc-content/`	canonical UnixFS profile、取塊限制與多來源排程
	`ugc-archive/`	UGC 匯出／匯入封裝與本機封存
	`asset-library/`	身分分域資產庫、pin 保護與可用性驗證
網路與同步	`network-sync/`	Rollback Netcode
	`pinning/`	client 端 pinning provider adapter 與授權請求
	`signaling-service/`	open-4wd-signaling
	`community-registry/`	社群 provider registry 載入、驗證與快取
	`connectivity-state/`	實體連線狀態與離線原因投影
	`room-identity/`	RoomId、房間 scope 與 invite identity
UGC 衍生與防護	`anti-piracy/`	五層防複製
	`ugc-fork/`	Fork + 三層分潤
客戶端與 UX	`versioning/`	版本管理 + SW
	`pwa-offline/`	PWA 離線
	`settings/`	設定八大正式分類＋可關閉的第九開發者分類
	`pages/`	路由頁面構圖與唯一資料入口契約；詳見程式架構/pages-contracts.md
	`ui-kit/`	`o4-` 共用元件庫（全站強制、權威 = ui-frontend.md §4）＋表單檢核層（Reactive Forms；門檻值取 system-constants／領域模組、錯誤訊息 i18n `validation.`、表單過檢 ≠ 被接受）
	`viewport/`	O4Viewport 3D 檢視器（three 場景管理＋GLB 載入管線 DRACO／KTX2＋stage preset 燈光；場景描述子契約＝`pages/contracts`、比賽幀由 FrameSource 餵入；車輛擺位讀 baked extras mount 座標）
	`bootstrap/`	站點組裝、正式 provider 與 runtime 接線；詳見程式架構/bootstrap.md
	`editor/`	Stage 2 編輯器（零件＋場地共用；互動 spec = 編輯器操作.md、實作 = 程式架構/editor.md）
	`i18n/`	四語系
	`themes/`	主題（token＋manifest 資源包、分類註冊表、fallback 預設；見主題系統.md）
	`announcements/`	公告 catalog、四語內容載入與安全呈現
	`onboarding/`	建立、匯入與解鎖身分的引導流程
	`local-backup/`	身分分域本機備份、還原與撤銷協調
	`app/`	Angular 應用殼、routes 與根層 providers
	`styles/`	全域樣式、design tokens 與 responsive 基礎
	`types/`	全域 ambient 型別補充
經濟與分散式信任	`economy/`	三層分潤 + 通膨控制
	`ledger/`	OrbitDB 帳本檢查點 + Fork
	`reputation/`	玩家信譽
	`ugc-rating/`	UGC 評分（Bayesian + 隱式 fallback）
	`moderation/`	檢舉 / 純仲裁 / 黑名單（純 derive 三振）
比賽體驗	`matchmaking/`	TrueSkill
	`room-runtime/`	等待房 star 拓撲（成員單線連房主、房主權威中繼）/ presence 房域探索 / 繼任 / 可驗 ReadyDeclaration／ReadySet / LockedStartPackage / 自動倒數與 match-start handoff / quickMatch gossip 接線
	`race-runtime/`	比賽主迴圈：逐回合 race-ready 屏障（world／network／presentation）/ rollback 接線 / 回合共識錨 / 結算窗 / loadout 交換 / HUD derive
	`race-routing/`	正式／本機比賽與結果 route identity；詳見程式架構/race-routing.md
	`spectator/`	觀戰
房間社群	`audio-system/`	BGM／SE 槽位播放＋轉場＋三路混音（程式架構/audio-system.md；檔案由主題供給）
	`chat-system/`	房間聊天
	`race-messages/`	賽中圖示訊息目錄、圖庫、九格設定、wire 與 HUD 投影
跨模組基礎建設	`key-manager/`	BIP39 + Ed25519
	`identity/`	共用 PeerId 顯示身分解析、暱稱快照與穩定短指紋
	`security/`	sanitize + CSP + 私密漏洞通報／重現
	`peer-discovery/`	libp2p DHT + GossipSub
	`encoding/`	dependency-free bytes 編碼工具（lowercase hex、exact ArrayBuffer）
	`testing/`	跨瀏覽器確定性 / 壓測 / Fuzz
	`system-constants/`	四層常數
	`seo/`	靜態 metadata / sitemap
	`dmca/`	DMCA / Counter-Notice 與 provider signed inbox wire
	`inbox/`	第一層 provider-scoped Inbox 協調器、來源、本機 signed snapshot、已讀與更新政策
	`mechanics-catalog/`	60 機制庫
	`deployment/`	部署 profile、trust root 與 provider policy

零件／晶片／場地等領域規範非程式模組，見零件與場景.md・建模參數.md・遊戲機制.md（晶片技能）——material-params/ 只覆蓋材質資料。

5. 開發階段門檻建議¶

下列序列是依賴脊柱的交付門檻，不是模組 inventory；同一階段可並行，完整目錄仍以 §9 為準。

0. system-constants                          （地基常數 — 所有模組之前）
1. interfaces + key-manager + security       （抽象 + 身分 + 安全）
2. physics-engine + material-params + builtin-assets （物理 + 材質 + 公版資產）
3. editor                                     （Stage 2 編輯器：零件 + 場地共用）
4. peer-discovery + signaling-service         （連線探索 + 握手）
5. network-sync + ledger                      （同步 + 鏈）
6. ugc-fork + anti-piracy + dmca + economy + ugc-rating （UGC 衍生 + 分潤 + 評分 + IP）
7. matchmaking + reputation + moderation + room-runtime （配對 + 治理 + 等待房）
8. mechanics-catalog                          （機制庫 + 晶片技能）
9. spectator + audio-system + chat-system     （比賽體驗）
10. settings + i18n + ui-kit + pages + themes + seo （客戶端整合）
11. viewport                                  （3D 檢視器 + 統一資產載入）
12. bootstrap                                 （站點組裝 + 真埠 / 上鏈編排接線）
13. race-runtime                              （比賽主迴圈）
14. versioning + pwa-offline                  （上線前最後）
15. testing                                   （貫穿全程）

6. Determinism 保證¶

跨 peer / 跨 platform 完全一致的關鍵：

6.1 時間步長¶

固定 60Hz：dt = 1 / FIXED_FRAMERATE_HZ s 精確值；不另設取整毫秒常數（protocol.md §2）
MAX_SUBSTEPS: 4

6.2 數值精度¶

f32 全物理計算（避免 f64 跨平台差異）
bigint 全鑄幣公式（避免浮點累積誤差）
整數量化（INTEGER_SCALE: 1000，1mm 精度）

6.3 Collider 排序¶

Rapier collider handle 對應 GLB sub-mesh 固定索引（建構順序）
跨 peer 與跨 platform deterministic
若 Rapier upstream 變更導致 handle 順序不穩，改走 sub-mesh fingerprint 路徑（convert 為每 sub-mesh 計算 fingerprint 作為 collider userdata）

6.4 序列化¶

IPLD dag-cbor canonical
固定欄位順序
跨瀏覽器 JS engine 與上游 Rapier deterministic WASM 組合一致

6.5 Provider 故障域觀測（資料可得性）¶

LEDGER_PROVIDER_FAULT_DOMAINS_RECOMMENDED: 3 是 bootstrap 與健康 pinning 服務跨獨立 provider 故障域的 best-effort 可得性建議；不是硬下限，0 個外部 provider 時仍可保持本地模式
故障域數是 UI／營運觀測值，不是 OrbitDB runtime replication 選項，不構成資料留存、持續供應、可恢復或 determinism 保證

6.6 單執行緒物理¶

Rapier deterministic build 與 SIMD / parallel feature 互斥；主站（GitHub Pages）無 COOP/COEP → SharedArrayBuffer 不可用 → 物理必然單執行緒（使用技術.md §14）
消除 thread-scheduling 帶來的非決定性；WASM 為硬需求、無多執行緒降級軸

7. 測試矩陣¶

本檔只保留驗證面指標：跨瀏覽器確定性、8 人 mesh、fuzz 與 CI 組合。工具、輸入、門檻及執行命令的 implementation authority 見程式架構/testing.md 與程式架構/toolchain.md。

8. 模組通訊規範¶

通訊	規範
模組之間 import	已接線基礎設施介面走 interfaces 抽象、不直接 import 實作；資料模組（material-params / system-constants）與展示層（ui-kit / pages / themes 資源）直接 import
共用常數	從 `@open4wd/system-constants` 取，禁止 hardcode
跨模組事件	寫 ledger，DerivedState 衍生

瀏覽器 runtime 的重型網路套件必須留在動態載入邊界：從 src/main.ts 可達的靜態依賴圖不得包含 helia、@helia/*、libp2p、@libp2p/* 或 @chainsafe/libp2p-*。現行入口包含 peer-discovery/node-config.ts 的 import('@libp2p/webrtc') 與 ledger/ipfs-node.ts 的 import('@helia/libp2p')；完整家族守門以 scripts/import-boundaries.test.mjs 為準，避免 Node 測試／SSR 在載入階段碰到瀏覽器網路堆疊或 node-datachannel 原生依賴。

9. 程式碼層次¶

src/                     # 依 §3 層序排列
├── system-constants/    # 地基
├── interfaces/          # 抽象 + types
├── encoding/            # dependency-free bytes 編碼 helper
├── key-manager/         # 身分 + 簽章
├── identity/            # PeerId 顯示身分解析 + 暱稱快照 + 穩定短指紋
├── security/            # sanitize + CSP
├── physics-engine/      # Rapier 包裝
├── physics-manifest/    # canonical manifest 衍生 / admission 重建 / receipt
├── material-params/     # 材質表 (materials.ts)
├── builtin-assets/      # 公版資產（UGC-in-GLB 名錄、只差不上鏈）
├── asset-schema/        # UGC 資產 schema 與版本契約
├── ugc-content/         # canonical UnixFS profile + 取塊排程
├── ugc-archive/         # UGC 本機封存匯出／匯入
├── asset-library/       # 身分分域資產庫 + pin 保護
├── editor/              # Stage 2 編輯器（零件 + 場地共用）
├── weapon-physics/      # 武器物理共用定義
├── peer-discovery/      # libp2p + DHT + GossipSub
├── signaling-service/   # WebRTC signaling client
├── pinning/             # pinning provider client adapter
├── community-registry/  # 社群 provider registry
├── connectivity-state/  # 實體連線狀態投影
├── room-identity/       # RoomId + invite scope identity
├── network-sync/        # Rollback + Snapshot
├── ledger/              # OrbitDB + DerivedState
├── ugc-fork/            # Fork 樹 + 70/20/10
├── anti-piracy/         # mesh fingerprint
├── dmca/                # DMCA 流程
├── economy/             # 鑄幣 / 燒幣
├── ugc-rating/          # UGC 評分
├── matchmaking/         # TrueSkill
├── room-runtime/        # 等待房 star 拓撲 / 開賽編排
├── race-routing/        # 比賽／結果 route identity
├── race-runtime/        # 比賽主迴圈（GO 前 race-ready / rollback / 回合共識錨 / 結算 / HUD derive）
├── reputation/          # 信譽 derive
├── moderation/          # 檢舉 / 仲裁
├── mechanics-catalog/   # 60 機制庫
├── spectator/           # 觀戰
├── audio-system/        # BGM/SE 槽位播放（audio-system.md）
├── chat-system/         # 房間聊天
├── race-messages/       # 賽中圖示訊息目錄 / 九格設定 / wire / HUD
├── settings/            # 設定頁
├── i18n/                # 四語系
├── ui-kit/              # o4-* 共用元件庫 + 表單檢核（[ui-frontend.md §4](程式架構/ui-frontend.md)）
├── viewport/            # O4Viewport 3D 檢視器（three 場景 / GLB 載入管線 / stage 燈光）
├── pages/               # 路由頁面元件（§13 routes 構圖層）
├── announcements/       # 公告 catalog + 安全呈現
├── inbox/               # provider-scoped Inbox
├── onboarding/          # 身分建立／匯入／解鎖引導
├── local-backup/        # 身分分域本機備份／還原
├── themes/              # 主題資源包（categories.json + default fallback）
├── styles/              # 全域樣式（design tokens）
├── seo/                 # 靜態 metadata
├── bootstrap/           # 站點組裝（registry 鏈 / 真埠工廠 / asset-source / createOpen4wdApp）
├── deployment/          # 部署 profile + trust root policy
├── app/                 # Angular 應用殼（app.config / routes / 根元件 / OfflineBanner）
├── versioning/          # 版本檢查 + SW 升版
├── pwa-offline/         # Service Worker
├── types/               # 全域 ambient 型別補充（*.d.ts）
└── testing/             # fixtures + harness

9.1 實作細節文檔（`程式架構/`）¶

已有獨立實作細節文檔的程式模組列於下表；檔名用英文模組名（對應 src/）。本表是深入閱讀索引，不是 src/ inventory；完整 inventory 只以 §9 為準。

文檔	中文說明	對應
`程式架構/system-constants.md`	四層常數套件結構 / `as const` / Brand 型別 / 統一匯出 / economy-config runtime / 不變式 CI（值見程式參數分冊）	`src/system-constants/`
`程式架構/interfaces.md`	五個已接線抽象介面 + AssetStorage 保留接縫、共用型別與介面版本管理	`src/interfaces/`
`程式架構/key-manager.md`	助記詞 / Ed25519 / Argon2id PIN 加密 / IndexedDB profile / 暴力鎖 / 硬體錢包 / SignedPayload	`src/key-manager/`
`程式架構/security.md`	Mesh Sanitize Worker / P2P 驗簽（nonce）/ CSP·SRI / 依賴管控 / Pinning Header / 本地安全日誌 / CVE	`src/security/`
`程式架構/physics-engine.md`	Rapier 封裝 `DeterministicWorld` / 固定 timestep / 整數量化 / mesh 體積 / 每幀模擬管線（算式 defer 算式表）/ determinism	`src/physics-engine/`
`程式架構/builtin-assets.md`	`builtin:*` 命名空間 / 物理烘焙 extras 同 UGC（只差不上鏈）/ 版本控管 / 公版清單 / fork·economy 整合 / 維護	`src/builtin-assets/`
`程式架構/editor.md`	Stage 2 編輯器（wave A 管線 / 幾何工具（拼接·切分）/ 逐 sub-mesh 材質指派 / 檢核引擎·收件端共用 validator / session 無草稿 / 送出驅動（雙出口）；互動權威 = 編輯器操作.md）	`src/editor/`
`程式架構/peer-discovery.md`	libp2p 組態 / GossipSub topic·簽章訊息 / DHT / Peer Scoring / 房間發現 / NAT 穿透 / bootstrap	`src/peer-discovery/`
`程式架構/signaling-service.md`	WebRTC 握手中介 / 訊息協議 / 協定核心＋Cloudflare Worker／Node adapters / 伺服器義務·安全規則 / rate limit / TURN	`src/signaling-service/`（client）+ open-4wd-signaling repo（模板）
`程式架構/pinning-service.md`	IPFS pinning 自架 / 管理 API / Ed25519 授權 / Cluster / k8s·CI/CD / 訂閱檢查點自動 pin·P5 退役 unpin	open-4wd-pinning repo（TypeScript app＋kubo＋cluster 三容器）；client 端以 interfaces `PinningProvider`＋`src/pinning/` HTTP adapter 對接
`程式架構/network-sync.md`	Rollback Netcode / InputBuffer 預測 / StateBuffer / checksum 去同步 / DataChannel 序列化 / 重連	`src/network-sync/`
`程式架構/ledger.md`	事件鏈 / DerivedState 巢狀 / 帳本檢查點 / partition / sync / fork resolution / API	`src/ledger/`
`程式架構/ugc-fork.md`	兩階段 fork 偵測 / per-type 物理指紋 / 衍生樹 API / fingerprintVersion	`src/ugc-fork/`
`程式架構/anti-piracy.md`	mesh 指紋 / 標準化 / 相似度搜尋 / 上傳期 pending / 爭議路由（仲裁歸 moderation）	`src/anti-piracy/`
`程式架構/dmca.md`	Notice/Counter 表單 / 後端 API / 黑名單檢查 / 下架·恢復·repeat-infringer	`src/dmca/`
`程式架構/inbox.md`	第一層 Provider-scoped Inbox / signed stale snapshot / 本機已讀 / PeerId session 隔離 / refresh 與 backoff	`src/inbox/`、`src/pages/inbox-page/`
`程式架構/economy.md`	鑄幣 / 燒幣 / 比賽結算 / 分潤拆分 / 消耗入口 / 查詢面 / EconomyConfig	`src/economy/`
`程式架構/ugc-rating.md`	UGC 評分（整數量化 / Bayesian / 隱式 fallback / 24h 防抖 / 高評分里程碑）	`src/ugc-rating/`
`程式架構/matchmaking.md`	TrueSkill / 配對訊息 / 動態窗口 / 房間管理 / 賽前 loadout 提交·驗證 / RoomId	`src/matchmaking/`
`程式架構/room-runtime.md`	等待房 star 拓撲（wire／link／host·member）/ presence 探索 / 房主繼任 / ReadySet 驗證 / LockedStartPackage / 自動倒數與 match-start handoff / quickMatch gossip 接線	`src/room-runtime/`
`程式架構/player-favorites.md`	身分分域玩家收藏 / 公開房間衍生狀態 / 房主授權通關來源與生命週期	`src/chat-system/favorites.ts`、`src/peer-discovery/room-discovery.ts`、`src/pages/`
`程式架構/reputation.md`	玩家信譽純 derive（無獨立事件：來源事件→delta / 加減分觸發 / 新手保護 / 惡意檢舉者判定 / 連動權重 / API）	`src/reputation/`
`程式架構/moderation.md`	檢舉 / 純仲裁（隨機抽選 + 加權 60%）/ 黑名單×經濟 / fork 不傳染 / 執行邊界	`src/moderation/`
`程式架構/spectator.md`	觀戰連線 / deterministic replay 主模式 / 10Hz 精簡 fallback / 3 種產品相機模式 / physicsRetired 後本機轉觀戰	`src/spectator/`
`程式架構/chat-system.md`	等待房共用文字聊天 / host-star 中繼 / 速率限制 / 本機文字過濾 / 最近隊友	`src/chat-system/`
`程式架構/race-messages.md`	賽中圖示訊息 catalog / 九格設定 / signed wire / HUD 投影	`src/race-messages/`
`程式架構/audio-system.md`	播放槽名錄 / 主題音訊 fallback·null 語意 / BGM 轉場 / 保留 SFX / `AudioService` 三路混音	`src/audio-system/`
`程式架構/settings.md`	`AppSettings` 資料模型 / 預設值 / 設定頁路由 / 即時生效 vs 重整 / persist（八大正式分類設計見遊戲機制 §9）	`src/settings/`
`程式架構/i18n.md`	字典載入·flatten / I18nService / Angular Pipe / ICU 複數 / Intl 格式化 / PWA 快取 / schema 驗證	`src/i18n/`
`程式架構/announcements.md`	repo-owned 四語公告 scanner／generator / summary-content lazy split / catalog / safe renderer / public routes / SEO·PWA 接線	`src/announcements/` + 公告頁
`程式架構/themes.md`	主題系統（ThemeService / token 套用 / 資產 fallback / SW 快取 / themes:validate）	`src/themes/`
`程式架構/seo.md`	`<head>` metadata / MetadataService / JSON-LD / sitemap / robots / Angular SSG / Lighthouse CI	`src/seo/`
`程式架構/versioning.md`	版本管理（版本收集 / 相容性 / 開賽前驗證 / 升版檢查 / SW 升版 / 強制重整 / build）	`src/versioning/`
`程式架構/pwa-offline.md`	PWA manifest / SW 快取分路 / 線上偵測·離線 UI / IndexedDB / UGC 快取 LRU（Helia GC）	`src/pwa-offline/`
`程式架構/testing.md`	Vitest / Playwright / fast-check / 確定性 harness / 8 人 mesh / CI matrix / coverage / perf budget	`src/testing/`
`程式架構/toolchain.md`	正式 build／check／test／proof 命令、compound 子命令、current execution 與 workflow evidence 的雙向 inventory	`package.json scripts` + `scripts/` + `e2e/` + `.github/workflows/`

流程圖的完整索引與產品流程對應以 流程.md §2 為準；本表只索引程式模組的實作細節，不複製另一份流程 inventory。

9.2 Onboarding 正式 mutation policy¶

src/bootstrap/formal-ledger-mutation-policy.ts 是玩家主動正式 ledger mutation 的集中登錄表與 fail-closed 授權入口。real-providers 的車位購買、UGC 評分／撤回、檢舉、仲裁投票與創作者發布必須先通過 current profile 的完整四里程碑與 chainUnlocked；未知 command 一律拒絕。協定自行產生的賽事／仲裁收尾事件只可出現在同檔具名且附理由的 pre-onboarding allowlist，不能由未登錄呼叫形成隱性例外。EditorPage 的查核只是昂貴工作前的 UX preflight，不能替代 provider 邊界。

10. Service Worker 與 PWA¶

詳見 程式架構/pwa-offline.md：

PWA Manifest（四語系）
Service Worker 快取分路（network-first HTML / cache-first 靜態 / SWR 文件）
升版策略（版本規範.md §8）
UGC 本地快取 LRU（Helia GC）

11. 部署架構¶

詳見部署資訊.md：

GitHub Pages 主站（靜態 + 客戶端）
pinning-service：互不從屬的社群／自架節點（選配 provider-scoped DMCA 下架＋訂閱檢查點 pin）；公版 Template repo open-4wd-pinning 只提供實作與 image，不指定官方部署或 client 預設清單
signaling-service：互不從屬的社群／自架 provider；公版保留同一協議的 Cloudflare Worker 與 Node adapter，兩者地位相同且不代表 deployment
TURN / STUN：公版 open-4wd-turn 只提供 coturn template、manifests、安全預設與 signaling token 配對契約；來源由玩家設定、配對 provider、session route 或 ice.json 決定
bootstrap／relay：分別由玩家手動設定、接受的 session route 與 bootstrap.json／relay.json 發現；listing 只給 capability，不授予信任
正式域名：open4wd.org（已購入；第一次公開部署即使用；open4wd.com 防禦性 301 → .org）。xjustloveux.github.io/open-4wd 僅保留為顯式 preview／災難回復 hosting target，不是 canonical origin。

12. 介面版本管理¶

詳見 程式架構/interfaces.md §8 介面版本管理：

介面有 semver（避免實作之間版本不相容）
升版策略對應版本規範.md protocol_version

13. 頁面路由（SPA Routes）¶

單頁應用（SPA）完整頁面路由；各頁 wireframe / 視覺見美術資源.md §5（含頁面線框.md 與參考成品 §6）。

Route	頁面	對應流程 / spec
`/`	公開首頁（未登入可瀏覽，不載入玩家資料）	程式架構/seo.md §1 · 玩家整體旅程.md
`/announcements`	公告列表（四語搜尋／tag 篩選）	公告系統.md · 程式架構/announcements.md
`/announcements/:id`	公告詳情（published／expired／retracted 歷史）	公告系統.md §2 · 程式架構/seo.md
`/login`	登入（建立 / 輸入助記詞）	玩家整體旅程.md
`/home`	Race Bench（登入後賽事工作台）	美術資源/頁面線框.md §1.2 · 玩家整體旅程.md
`/garage`	車庫總覽（loadout 清單）	車輛組裝.md
`/garage/edit/:id`	車間（編輯單一 loadout）	車輛組裝.md §8
`/editor`	Stage 2 編輯器（零件＋場地共用；上傳 GLB 後自動進入、編輯本機測試資產）	編輯器操作.md · UGC上傳.md
`/inbox`	已解鎖玩家的第一層 Inbox（目前 `dmca` tab；本機已讀與 signed stale snapshot）	程式架構/inbox.md · DMCA.md
`/ugc`	公開 UGC 展示廳（part／track 聯集與類型篩選）	UGC機制.md · 零件與場景.md
`/ugc/:cid`	UGC 詳情（依資料 kind 切換 part／track；SSG 收錄／分享登陸頁）	UGC機制.md · 程式架構/seo.md §1
`/race-config`	共用賽事設定：乾淨 URL；一般／本機狀態由 Browser History State 決定	配對.md · 車輛組裝.md · 程式架構/pwa-offline.md §6
`/room/:roomId`	房間等待 + ReadySet 狀態 + P2P 診斷	配對.md §9
`/race/:sessionId`	共用 `RacePage`／race runtime：正式以 RoomId 定位 RoomSession，本機以 `local-session-<uuid>` 定位	比賽進行.md
`/result/:resultId`	共用 `ResultPage`：正式 resultId 是 matchId，本機為 `local-result-<uuid>`	比賽結算.md
`/creator/:peerId`	創作者個人頁；本人已解鎖時另顯示私人可用餘額	信譽系統.md
`/settings`	公開設定頁（預設顯示；裝置偏好未登入可用）	遊戲機制.md §9 · 程式架構/settings.md
`/settings/:section`	設定頁深連結（八分類；身分／機密單項依能力解鎖）	程式架構/settings.md
`/about`	關於（專案介紹、靜態）	程式架構/seo.md §1
`/help`	說明 / 治理 / DMCA	流程.md
`/dmca`	DMCA Notice / Counter-Notice 表單	版權.md §6.1
`/dmca/transparency`	DMCA 透明度報告	版權.md §6.1

22 個產品 route（語系前綴門牌不重複計數）。組裝車輛是本機 loadout，沒有 /vehicles 或 /vehicle/:cid 公開作品路由。

路由 shell、Race Config History State、Race／Result identity、RoomSession 恢復、verified result 與語系前綴細節統一見程式架構/race-routing.md。

14. 程式碼風格與註解規範¶

Formatter＝Prettier（使用技術.md §10 Lint 列）：printWidth: 100、singleQuote: true、其餘預設，另有 *.html → angular parser 之 override；.editorconfig 隨 workspace；CI format:check 掛 lint 步（流程/升版.md §3）——格式不合＝阻擋 merge。

主 repo 註解語言＝繁體中文（識別字／變數／函式名一律英文）；用語沿 specs 鐵則（本機測試、黑名單 vs 封鎖清單等）。這是官方 open-4wd 上游維護政策，不是 fork 的建置／部署契約。Pinning、Signaling、TURN 公開 Template 的第一方註解可用英文或繁中，營運設定、公開 API 與安全邊界優先採較廣泛可讀的英文；vendor 保留來源擁有者的語言。三個 Template 不得把註解語言接入 build／test／deploy 硬閘（D-20260813-01、D-20260815-02）。

元件檔案結構：Angular 元件一律「一元件一同名資料夾」、邏輯（.ts）／template（.html）／樣式（.scss）分檔（templateUrl／styleUrl、禁 inline template/styles）——單檔不致冗長、降低開源協作的合併衝突面；服務／純邏輯模組不在此列。檔名循 Angular 20+ 新式（無 .component 後綴，如 button/button.ts）。

註解鐵則：自足、零文檔引用——程式碼註解不得出現 spec 檔名／章節（章節會重編＝引用必漂移；開源讀者無從對照；且不預設 specs 公開）。一句話把語意／約束講完、單看程式碼可讀。深層設計理由單一權威＝specs、不複述進註解（複本必漂移）。雙向對照鍵＝名稱：常數／模組／介面名 spec 與 code 同名（spec↔const CI 按名對帳）；spec→code 對應由 spec 側維護（§9.1 表、程式參數分冊對應 src 欄），code 側零反向指標。

對象	覆蓋要求
exported API（直接／同檔間接 export、class expression、public／protected method、常數群）	TSDoc `/** */`：自足一句用途；param／return 僅在單位、範圍、null、所有權、副作用、callback 或安全邊界不明顯時寫
private declaration（所有納管 class 的欄位／方法／accessor／`#private`）	TSDoc `/** */`：與 exported API 同樣自足一句用途，不以名稱重述充數；overload 群一份有效說明即可
模組進入點（各 `src/<module>/index.ts`）	檔頭註解＝模組角色一句（自足、不引 spec 檔）
inline 註解	只寫「程式碼看不出的 why／約束」；不寫 what、不留變更紀錄（歷程歸 git）

相鄰且同一語意邊界的 exported 常數可由一則群組 TSDoc 涵蓋；空行、非 const 宣告或新的獨立 TSDoc 即切開群組。不得為通過檢查而逐列重述常數名稱，也不得用 baseline 或豁免隱藏缺口。

強制手段採四層：ESLint 即時診斷、本機 issue 處理中 → 已處理 原子 gate、repo-local opt-in staged／full hooks、官方上游 CI。主 repo 將語言中立的 check:comment-quality 與繁中 check:comment-language 分開；maintainer profile 硬擋兩者，contributor 只硬擋結構並報告語言。三個公開 Template 的官方 CI 只執行語言中立品質 job，且不成為 build／test／deploy 前置；不得以 baseline 隱藏缺口。

外語 PR 可先開啟並進行 review；主 repo 合併前由維護者完成繁中技術複核。預設以 suggested changes 讓作者自行套用；直接更新 fork branch 僅在作者允許且先確認該 fork workflow 的 secret 風險後使用。自動翻譯結果不能取代技術語意 review。

15. 工具鏈與驗證架構¶

領域 canon／ADR（定義規則）
  → package.json scripts（人工與 CI 的穩定命令入口）
    → scripts/ 或 test suite（建置／生成／驗證實作；不進 runtime bundle）
      → .github/workflows/（目前是否、何時、在哪個 job 真正執行）

src/  = runtime product modules
e2e/  = Playwright 跨模組、跨頁面與真實資產旅程

完整命令、主要 entrypoint、compound 子命令、current／target execution、CI job／condition、需求與 skip／failure 語意，以 程式架構/toolchain.md 為權威。package.json、該表與 workflows 由 repository contract test 雙向比對；因此文件不得把只在本機存在、被 skip 或尚未接線的檢查宣稱為 CI pass。測試方法、suite 分組與 E2E profile／旗標仍由 程式架構/testing.md 說明。