From 6259a383435c7f418f919642a2662415cd113c9c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 03:33:56 +0000 Subject: [PATCH] =?UTF-8?q?docs(guide):=20=E5=88=A0=E6=8E=89=20console-arc?= =?UTF-8?q?hitecture=20=E9=87=8C=E4=B8=8D=E5=AD=98=E5=9C=A8=E7=9A=84=20MSW?= =?UTF-8?q?=20Mock=20Mode,=E5=B9=B6=E6=8C=89=E5=8C=85=E5=BD=92=E5=B1=9E?= =?UTF-8?q?=E6=A0=A1=E6=AD=A3=E7=BB=84=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `MSW Mock Mode` 整节描述的能力不存在,且与 #3532 刚改写的 console.md:18 ("There is no bundled mock backend")直接矛盾 —— 而 console.md 的 See Also 正把读者往这一页送。实测 origin/main a2c8f2a29:`MSWPlugin`/`msw` 在 apps/console 源码与 package.json 零命中,`apps/console/src/mocks/` 随 2b7435b76(refactor: remove MSW mock server setup)删除。整节删除,换成一段 「没有内置 mock 后端、dev 与生产一样要连活服务器」的说明 + 指向 console.md Quick Start 的链接(不重复其内容);数据流图上的 `MSW / Real Server` 边标注 一并改成真实的 `ObjectStack server (HTTP, VITE_SERVER_URL)`。 第二类是组件归属漂移:页面按 `apps/console` 的口径点名的 ExpressionProvider / ConsoleLayout / AppHeader / ObjectView / RecordDetailView / ObjectDataPage 现均由 `@object-ui/app-shell` 导出, CreateAppPage / EditAppPage 由 `@object-ui/plugin-designer` 导出(逐项 `git grep -l` 复核)。按 role/package 口径校正,**不写死文件路径** (#3534 已证明路径树必漂移):开篇加一段总述说明 apps/console 只是薄壳, Routing 节点明表内组件的导出方,§3 把 "The console's ObjectView" 的主语 改成 shell 的 ObjectView,§4 改成 plugin-designer 端到端拥有。 图里 `AppSidebar` 改用角色措辞「sidebar nav」:它虽在 app-shell,但 ConsoleLayout 已改挂 `UnifiedSidebar`,直接点名会写下一句可证伪的话。 顺手修了 SchemaRendererProvider 那格的一格错位(纯空格,无内容变更)。 同页另发现三处过期陈述(objectstack.config.ts 顶层 box 与 console.md 同源、 已死的建应用入口、Routing 表不全),按文件面纪律只报不改,已立 #3543。 Fixes #3540 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- content/docs/guide/console-architecture.md | 54 ++++++++++++++-------- 1 file changed, 34 insertions(+), 20 deletions(-) diff --git a/content/docs/guide/console-architecture.md b/content/docs/guide/console-architecture.md index acf73018e6..8fff649e4c 100644 --- a/content/docs/guide/console-architecture.md +++ b/content/docs/guide/console-architecture.md @@ -5,7 +5,14 @@ description: Internal architecture of the ObjectStack Console — data flow, rou # Console Architecture -This document describes the internal architecture of the Console app (`apps/console`). +This document describes the internal architecture of the Console SPA. + +`apps/console` is a thin host: it owns the Vite build, the outermost route tree, and plugin +registration. Almost everything named below is a **component exported by a package**, not a file +under `apps/console` — the shell (providers, layout, object and record views) ships from +`@object-ui/app-shell`, view rendering from `@object-ui/plugin-view`, and the app wizard from +`@object-ui/plugin-designer`. Packages are named where it matters; import from the package, never +from a path. ## Data Flow @@ -14,7 +21,7 @@ This document describes the internal architecture of the Console app (`apps/cons │ objectstack.config.ts │ │ (defineStack → apps, objects, views) │ └────────────────────┬────────────────────────────────────┘ - │ MSW / Real Server + │ ObjectStack server (HTTP, VITE_SERVER_URL) ▼ ┌─────────────────────────────────────────────────────────┐ │ ObjectStackAdapter (@object-ui/data-objectstack) │ @@ -25,20 +32,20 @@ This document describes the internal architecture of the Console app (`apps/cons │ DataSource interface ▼ ┌─────────────────────────────────────────────────────────┐ -│ SchemaRendererProvider (@object-ui/react) │ +│ SchemaRendererProvider (@object-ui/react) │ │ • provides dataSource + registry to all children │ └────────────────────┬────────────────────────────────────┘ │ React Context ▼ ┌─────────────────────────────────────────────────────────┐ -│ App.tsx │ +│ Console shell (@object-ui/app-shell) │ │ ├── ExpressionProvider (user, app, evaluator) │ │ ├── ConsoleLayout │ │ │ ├── AppShell (@object-ui/layout) │ │ │ │ └── useAppShellBranding (CSS vars) │ -│ │ ├── AppSidebar (navigation tree) │ +│ │ ├── sidebar nav (app switcher + nav tree) │ │ │ └── AppHeader (breadcrumbs, status) │ -│ └── Routes │ +│ └── Routes (mounted by apps/console at /apps/:appName) │ │ ├── /apps/:appName/:objectName → ObjectView │ │ ├── /apps/:appName/:objectName/record/:id → Detail │ │ └── /apps/:appName → Home Page │ @@ -47,7 +54,12 @@ This document describes the internal architecture of the Console app (`apps/cons ## Routing -The console uses React Router DOM v7 with a simple flat route structure: +Routing is React Router DOM v7. `apps/console` mounts the per-app subtree at +`/apps/:appName/*`; the routes below are declared inside it by the console shell +(`@object-ui/app-shell`). Every component in the table is exported by `@object-ui/app-shell`, +except `CreateAppPage` / `EditAppPage`, which are lazy-loaded from `@object-ui/plugin-designer`. +These are the object-facing routes — the shell declares more (record create/edit, the metadata +admin subtree), and `apps/console` adds the unauthenticated auth surfaces outside this subtree. | Route Pattern | Component | Purpose | |---------------|-----------|---------| @@ -73,7 +85,7 @@ Navigation items can be conditionally hidden using expressions: } ``` -The `ExpressionProvider` wraps the layout and provides an `ExpressionEvaluator` that resolves `${}` templates against context variables (`user`, `app`, `data`). +`ExpressionProvider` (`@object-ui/app-shell`) wraps the layout and provides an `ExpressionEvaluator` that resolves `${}` templates against context variables (`user`, `app`, `data`). ### 2. Action System @@ -98,21 +110,24 @@ The `ActionRunner` supports: ### 3. Plugin ObjectView Delegation -The console's `ObjectView` is a **thin wrapper** around `@object-ui/plugin-view`'s `ObjectView`: +The shell's `ObjectView` — the one exported by `@object-ui/app-shell` and bound to the routes +above — is a **thin wrapper** around `@object-ui/plugin-view`'s `ObjectView`: - Resolves views from the object definition's `list_views` - Passes a `renderListView` callback for multi-view rendering (kanban, calendar, chart) -- Handles console-specific concerns: URL routing, MetadataInspector, record detail Sheet +- Handles shell-level concerns: URL routing, MetadataInspector, record detail overlay ### 4. App Creation & Editing -The console integrates the `AppCreationWizard` from `@object-ui/plugin-designer` for creating and editing apps: +App creation and editing are owned end to end by `@object-ui/plugin-designer`: it exports both +route pages and the `AppCreationWizard` they render. The console shell only lazy-loads them onto +routes. - **Create App** — `CreateAppPage` at `/apps/:appName/create-app`. Passes metadata objects as `availableObjects`, handles `onComplete` (converts draft via `wizardDraftToAppSchema()`, navigates to new app), `onCancel` (navigate back), and `onSaveDraft` (localStorage persistence). - **Edit App** — `EditAppPage` at `/apps/:appName/edit-app/:editAppName`. Loads existing app config as `initialDraft` and updates on completion. **Entry Points:** -- AppSidebar app switcher → "Add App" / "Edit App" buttons +- Sidebar app switcher → "Add App" / "Edit App" buttons - CommandPalette (⌘+K) → "Create New App" command in Actions group - Empty state CTA → "Create Your First App" button when no apps are configured @@ -131,13 +146,12 @@ Per-app branding is applied via `AppShell`'s `branding` prop: This sets CSS custom properties (`--brand-primary`, `--brand-primary-hsl`, etc.) on the document root. -## MSW Mock Mode - -In development, the console uses MSW (Mock Service Worker) to simulate an ObjectStack backend: +## Development Mode -1. `objectstack.config.ts` defines apps and objects via `@objectstack/spec` -2. `@objectstack/runtime` boots an `ObjectKernel` with `MSWPlugin` -3. MSW intercepts `/api/v1/*` requests and serves in-memory data -4. The `ObjectStackAdapter` connects to this mock server transparently +There is **no bundled mock backend** — offline development is not a thing here. In dev exactly as +in production, `ObjectStackAdapter` talks over HTTP to a live ObjectStack server at +`VITE_SERVER_URL`, and everything above the adapter in the data flow depends on that call +succeeding: no server, no discovery, no apps in the sidebar. -This allows full offline development without a real backend. +See [Console App → Quick Start](/docs/guide/console#quick-start) for the dev server port, the +default `VITE_SERVER_URL`, and how to point the console at a different backend.