fix(console): /_console/setup is a stable deep link into platform administration

[yinlianghui]

Fixes#2794

Premise, re-measured at this tip

The card is 18 days old, so its premise was re-checked before anything was written. It holds — and the cause is not the one the card assumed.

/setup was never a missing route. It was occupied. apps/console/src/App.tsx:183 mounted the first-run owner-bootstrap wizard there (pages/auth/SetupPage, ported here when the Account SPA was retired), and that page evicts everyone it is not for:

• SetupPage.tsx:88 — if (user && !submitting) window.location.assign('/')
• SetupPage.tsx:78 — if (bootstrapped === true and no user) navigate('/login', ...)

So a signed-in admin opening the deep link was sent to /, which resolveLandingPath() resolves to /home on any multi-app deployment with no isDefault app. That is the card's exact observation, and being a full-page location.assign is why it read as "被重定向回 home" rather than as a routing error. The unauthenticated half was defective too, more quietly: it reached a bare /login, so signing in dropped the deep link entirely.

The card's literal target address needed correcting as well. apps/com.objectstack.setup/dashboard/system_overview — only the first segment pair is a fact about Setup; dashboard/system_overview is a fact about Setup's navigation on the day it was measured (it is SETUP_NAV_CONTRIBUTIONS' first group_overview child). The redirect therefore resolves the app root and lets the shell's existing landing resolution pick the page.

What changed

/setup now discriminates between its two meanings on the condition the wizard itself already probes — whether the deployment has an owner (GET /api/v1/auth/bootstrap-status). It is the honest discriminator because it is exactly the condition under which the wizard is the right page, and it is monotonic: a deployment crosses it once, forever.

• no owner yet → the first-run wizard, unchanged;
• otherwise → the platform-administration deep link.

A live session short-circuits the probe, because hasOwner: false cannot be true while somebody is signed in. That keeps the common case off the round-trip, and keeps a failed probe (which falls open to the wizard, matching SetupPage's own catch) from re-creating the bounce this card is about.

No new routing idiom.SetupRedirect is modelled on SystemRedirect sitting beside it in ConsoleShell.tsx — resolve a target, one Navigate replace, search and hash carried over. Its policy is the pure, router-free resolveSetupAppPath(), the same shape RootLandingRedirect's resolveLandingPath() uses for /.

The target is read from metadata, not spelled out.resolveSetupAppPath() finds the Setup app and builds its segment with appRouteSegment() — the same helper console/home/AppCard.tsx uses — so this alias and the home launcher's 「系统设置」 card cannot disagree about where Setup lives, and re-ordering Setup's nav cannot drift the alias.

The absent-app case is handled, not papered over.SETUP_APP.requiredPermissions = ['setup.access'], so "Setup is missing from metadata" is a normal permission outcome, not only a stripped build. The fallback is the canonical package-id URL, deliberately neither of the two tempting alternatives: /home is the defect being fixed, and the bare /apps/setup is AppContent's isSetupRoute pseudo-route, which resolves to the default app — it would silently render a different app. /apps/com.objectstack.setup matches no pseudo-route, so AppContent's own requestedAppMissing branch answers it with the "App not available" screen every other missing app gets, retry and one-shot metadata re-check included.

The auth-redirect contract is reused, not re-spelled. The settings branch goes through the console's existing ProtectedRoute, so an unauthenticated deep link becomes /login?redirect=%2Fsetup and returns here after signing in. LoginRedirect builds that param from the router's location, so it stays correct under a base href-mounted basename (#4168's lesson). ProtectedRoute / LoginRedirect were lifted out of App.tsx verbatim into components/ProtectedRoute.tsx — both were module-private, so no published surface widened; the move exists so the test exercises the real contract instead of a transcription that would be free to agree with itself.

No latch, and that is deliberate.signUp() flips the session to authenticated while the wizard is still renaming the bootstrap organization; re-deciding on that flip would unmount the wizard mid-submission and kill the rename — the failure SetupPage's own "not mid-submission" guard was written for. Rather than freeze the verdict, the probe is gated on being unauthenticated, so a fresh verdict can only come from a probe that ran with no session, and reading fresh first makes the decision immune to the flip. The ordering is the guard, and it is pinned as such.

/_console/studio — the consistency half

Measured, coherent, unchanged:

• App.tsx:190 — bare /studio is a declared front door rendering BuilderLanding inside ProtectedRoute, not a fall-through to the catch-all;
• App.tsx:210 — /studio/:packageId redirects to its data pillar;
• it has a live in-product producer (console/home/HomePage.tsx:417, navigate('/studio')).

The card's /_console/studio// spelling no longer describes anything. Nothing was changed here, per the card's "align it only if it misbehaves".

Tests

New: packages/app-shell/src/console/__tests__/setupRedirectTarget.test.tsx (9) and apps/console/src/components/SetupRoute.test.tsx (14). The console file wires / to the realresolveLandingPath over a multi-app list, so /home is a destination the router can actually settle on — "never lands on home" is then an assertion about a reachable place rather than about an unwired stub. AuthGuard and LoginRedirect stay real; SetupPage and ConnectedShell are stubbed, because this measures routing rather than the wizard's form or the provider stack.

Reverse verification — direction predicted before running, then observed

Two independent reverts, both red as predicted:

1. resolveSetupAppPath forced to '/home' + SetupRoute reduced to the pre-fix unconditional SetupPage → 11 reds / 11 passed, including THE FIX: /setup lands on the Setup app, not back on home and THE FIX: the unauthenticated deep link carries a redirect back to /setup. That reproduces the card's bounce and the dropped deep link.
2. The fresh-first ordering moved below the session checks → exactly 2 reds: a fresh verdict outranks a session — that ordering IS the wizard guard and THE REGRESSION GUARD: signUp() flipping the session does not evict the wizard. Nothing else moved, which is what shows the ordering carries that property alone.

Local gates

pnpm exec vitest run --maxWorkers=2 packages/app-shell/
Test Files 323 passed (323) Tests 3030 passed | 1 skipped (3031)
pnpm exec vitest run --maxWorkers=2 apps/console/
Test Files 31 passed (31) Tests 322 passed (322)
pnpm --filter @object-ui/app-shell --filter @object-ui/console type-check → Done, Done
pnpm --filter @object-ui/app-shell --filter @object-ui/console lint → 0 errors
node scripts/check-control-bytes.mjs → OK (3851 tracked text files)

Build closure (--filter '@object-ui/console^...' build) was run first — the console's type-check reads workspace .d.ts and reports 21 phantom TS2307s without it.

Changeset: @object-ui/console + @object-ui/app-shell, both patch.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 5:43pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	28.3 KB	350 KB
Entry file	index-D_vOA-KO.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.88KB	3.25KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	485.06KB	107.21KB
core (index.js)	3.04KB	1.15KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	140.66KB	36.25KB
fields (index.js)	229.40KB	56.93KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.65KB	1.06KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	9.48KB	3.27KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	4.52KB	1.96KB
layout (index.js)	38.87KB	10.80KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.23KB	12.45KB
plugin-charts (index.js)	61.52KB	17.49KB
plugin-chatbot (index.js)	180.33KB	42.79KB
plugin-dashboard (index.js)	118.52KB	30.68KB
plugin-designer (index.js)	210.51KB	42.51KB
plugin-detail (index.js)	237.80KB	59.48KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	114.58KB	27.68KB
plugin-gantt (index.js)	162.81KB	39.67KB
plugin-grid (index.js)	188.04KB	49.91KB
plugin-kanban (index.js)	48.60KB	13.41KB
plugin-list (index.js)	110.04KB	26.67KB
plugin-map (index.js)	17.00KB	5.32KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.58KB	10.58KB
plugin-timeline (index.js)	26.21KB	7.52KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	23.71KB	7.95KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.23KB	0.66KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	2.71KB	1.34KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped