docs: reorganize architecture strategy documentation

Split current project diagnostics into a dedicated analysis document and trim the main architecture strategy to focus on core guidance. This makes the documentation easier to navigate and separates observed issues from recommended architectural principles.docs: reorganize architecture strategy documentation Split current project diagnostics into a dedicated analysis document and trim the main architecture strategy to focus on core guidance. This makes the documentation easier to navigate and separates observed issues from recommended architectural principles.
2026-05-19 14:13:10 +08:00
parent 9ae91418e0
commit 96b96bcaaa
12 changed files with 1373 additions and 1077 deletions
@@ -0,0 +1,81 @@
+## 一、Apple App Store 專案的核心架構特徵
+
+### 1.1 單一業務邏輯門面（Jet Facade）
+
+```
+browser.ts → bootstrap → Jet.load → runtime + objectGraph
+                              ↓
+                    UI 層僅透過 jet.dispatch(intent) / jet.perform(action) 溝通
+```
+
+- **Jet** 封裝所有業務邏輯：路由、資料取得、動作分發、metrics。
+- UI 層**不直接**呼叫 API、不直接操作 storage、不直接操作 history。
+- 所有外部依賴（fetch、storage、locale、user）統一注入 `Dependencies`，再組裝成 `ObjectGraph`。
+
+### 1.2 Intent / Action 分離（查詢與命令）
+
+| 類型 | 職責 | 回傳值 | 例子 |
+|------|------|--------|------|
+| **Intent** | 取得頁面資料（Query） | `Promise<Page>` | `RouteUrlIntent` → 回傳 `ProductPage` |
+| **Action** | 執行副作用（Command） | `'performed' \| 'unsupported'` | `FlowAction` → 導航到新頁面 |
+
+- `FlowAction` 是主要導航機制：內含 `destination Intent` + `pageUrl` + `presentationContext`。
+- Action handler 註冊採用**型別註冊制**：`jet.onAction('flowAction', handler)`。
+
+### 1.3 Page Model 驅動 UI（資料驅動）
+
+```ts
+// App.svelte 的介面極簡
+export let page: Promise<Page> | Page
+```
+
+- 整個應用由單一 `page` prop 驅動。
+- `PageResolver` 處理 `Promise<Page>` 的 loading / error 狀態。
+- `Page.svelte` 用 type guard 分發到對應的 page component：`isProductPage(page)` → `<ProductPage>`。
+- **Page 是 union type**，不是 route-based 的硬編碼映射。
+
+### 1.4 Shelf / Item 分層（容器與內容分離）
+
+```
+Page (TodayPage / ProductPage / ...)
+  └── Shelf[] (水平捲軸 / 網格)
+        └── ShelfItemLayout (佈局抽象：HorizontalShelf or Grid)
+              └── Item (BrickItem / LargeLockupItem / ...)
+```
+
+- **Shelf** = 容器邏輯：決定是水平捲軸還是網格、rowsPerColumn、邊框。
+- **ShelfItemLayout** = 佈局中介：根據 `isHorizontal` 選擇 `HorizontalShelf` 或 `Grid`。
+- **Item** = 純粹內容渲染：只關心單一資料單位的呈現，不知道自己是水平還是網格。
+- **FallbackShelf** = 優雅的降級策略：遇到未實作的 shelf 類型顯示 placeholder，不 crash。
+
+### 1.5 Svelte Context 作為跨層依賴注入
+
+```ts
+// bootstrap.ts
+context.set('jet', jet)
+context.set('i18n', i18nStore)
+
+// 深層元件
+const jet = getJet()      // 從 Svelte Context 取得
+const i18n = getI18n()    // 從 Svelte Context 取得
+```
+
+- 避免 props drilling：Jet、i18n、accessibility layout、today-card layout 都透過 context 傳遞。
+- Context 在啟動時注入，生命周期與應用一致，不是用來傳遞 UI 狀態的。
+
+### 1.6 命令式外殼 + 聲明式 UI
+
+```ts
+// browser.ts（命令式啟動層）
+const app = new App({ target: container, context, hydrate: true })
+registerActionHandlers({
+  jet,
+  updateApp: (props) => app.$set(props),  // 橋接命令式 → 聲明式
+})
+```
+
+- 導航、歷史管理、scroll 復原由命令式的 action handler 處理。
+- UI 渲染完全聲明式，只接收 `page` 與 `isFirstPage` 兩個 prop。
+
+---
+