[Setup] First-run admin experience: gaps vs. mainstream admin consoles (onboarding, auth hardening, provisioning, IA)

[os-zhuang]

Summary

I dogfooded the Setup app (系统设置) as a brand-new system administrator standing up the platform for a company — booted examples/app-showcase with objectstack dev --seed-admin, logged in as the seeded admin, and walked the full admin-configuration surface end-to-end, benchmarking against Salesforce Setup, ServiceNow, Microsoft Power Platform admin, and Okta/Entra ID.

The backend config surface is genuinely strong: 9 well-modeled settings manifests (Company, Localization, Branding, Authentication, Mail, Storage, AI, Knowledge, Feature Flags) with a proper tenant→default cascade, working save round-trips (PUT /api/settings/:ns verified), runtime-applied auth settings (applyConfigPatch / bindAuthSettings), and a complete RBAC + sharing model. This issue tracks the gaps a real admin hits during first-run setup.

Already patched while auditing (working tree, pending review)

• Company & Localization were unreachable from the Setup sidebar. Both are registered settings manifests and the two lowest-order Workspace settings (the first things a new admin configures), but no nav contribution pinned them — they were reachable only by drilling into the "All Settings" hub. Pinned both in group_configuration (packages/platform-objects/src/apps/setup-nav.contributions.ts) + added zh labels. Verified live: group_configuration now renders 全部设置 → 本地化 → 公司信息 → 品牌 → …
• "Capabilities" nav item rendered untranslated in zh sessions — added the missing nav_capabilities zh translation (packages/platform-objects/src/apps/translations/zh-CN.ts). Now renders 能力.

Open gaps (prioritized)

P1 — No guided first-run / onboarding

A new admin lands on the System Overview analytics dashboard (all zeros) with no next-step guidance. Mainstream consoles greet a new admin with a setup checklist (Salesforce Setup Assistant, ServiceNow Guided Setup, Power Platform onboarding).
Suggest: a "Get started" checklist on System Overview — Company → Localization → Branding → Authentication → Invite users → Roles — with per-step completion state.

P1 — Enterprise auth/security hardening (settings exist but thin)

auth.manifest.ts exposes: email/password toggle, self-signup toggle, email-verification toggle, password min/max length, session expiry/refresh days, and Google OAuth. Missing vs. Salesforce/Okta/Entra:

• Password policy: complexity (upper/lower/digit/special), expiry/rotation, history/no-reuse, account lockout after N failed attempts.
• MFA enforcement: TOTP + backup codes exist per-user (sys_user actions enable_two_factor etc.) but there is no admin control to require MFA org-wide.
• SSO: only Google is configurable via UI; a generic OIDC path exists in code but isn't surfaced in settings; no SAML; other social providers (Microsoft/GitHub/Apple/…) are hardcoded, not configurable.
• Sessions: no idle timeout, no concurrent-session cap / "sign out all other sessions".
• Network: no IP allowlist / login-IP restriction.
• Brute-force: no login rate-limiting / throttling.

Note: per the platform-base-settings principle, these must be enforcement-wired, not declaration-only — a settings field with no runtime enforcement is a false surface. Each item above should ship with its enforcement path.

P2 — User provisioning at scale

Present and working: invite-by-email (sys_invitation), ban/unban (deactivate), admin password reset, impersonate, set-role. Missing: bulk CSV import and SCIM / directory provisioning — both expected for any org beyond a handful of seats.

P2 — Access-control conceptual overload

Three primitives sit side-by-side in the Access Control nav — Roles, Capabilities (sys_capability, ADR-0066), Permission Sets — with overlapping vocabulary and no in-UI explanation of how they relate (role → permission set → capability). A new admin won't know which to reach for.
Suggest: group them with a one-line explainer, or move the low-level Capabilities registry into an advanced/system section until ADR-0066 adoption matures.

P2 — "Organizations" shown but unmanageable

System Overview shows an Organizations KPI (0), but Organizations & Invitations management is hidden in the nav (gated behind the org-scoping service, which is off in single-tenant). The admin sees a metric they can't act on, and nav_organizations / nav_invitations never appear.
Suggest: hide the Organizations KPI when org-scoping is disabled, or surface an enable path.

P3 — i18n coverage gaps (remaining)

Still untranslated in a zh session (owned by other packages): nav labels "Cloud Connection", "Datasources", "Recent"; System Overview KPI sublabels (Users / Organizations / Sessions / Events); and some settings field help text (e.g. Localization → Number format: "Grouping and decimal separators for displayed numbers."). (Capabilities / Company / Localization already fixed above.)

P3 — Settings API read/write shape asymmetry (DX)

GET /api/settings/:ns returns { values: { key: { value, source, cascadeChain } } }, but PUT /api/settings/:ns expects top-level { key: value } and rejects { values: {…} } with UNKNOWN_KEY. The error message is clear, but the asymmetry trips integrators — document the shapes, or accept both on write.

P3 — Default-language precedence unclear

localization.locale default is en-US, yet the console rendered in Chinese (driven by browser Accept-Language). Define/document precedence — tenant default vs. per-user preference vs. browser — and whether the tenant default should drive the console UI language.

Environment / repro

• Example: examples/app-showcase, booted via objectstack dev --seed-admin (admin@objectos.ai / admin123).
• Console at /_console/; Setup app at /_console/apps/com.objectstack.setup.
• Settings catalog: GET /api/settings. Merged nav: GET /api/v1/meta/app?id=com.objectstack.setup.

Key references

• packages/platform-objects/src/apps/setup.app.ts (nav shell) · setup-nav.contributions.ts (entries)
• packages/services/service-settings/src/manifests/*.manifest.ts (auth / company / localization / …)
• packages/plugins/plugin-auth/src/auth-manager.ts (applyConfigPatch) · auth-plugin.ts (bindAuthSettings)
• packages/plugins/plugin-security, packages/plugins/plugin-sharing (RBAC + sharing)

[os-zhuang]

Update — additional fixes applied (working tree, pending review)

Following a second pass, the smaller/bounded items from this issue are now fixed and browser-verified (showcase, objectstack dev, zh session). Builds + unit tests green (service-settings 128, rest 133 incl. 6 new gate tests).

Now fixed

• P2 — "Organizations" shown but unmanageable. Extended the ADR-0057 D10 server-side visibility gate to dashboard widgets: rest-server now strips widgets whose requiresService names an unregistered kernel service (mirrors the existing app-nav gate). Tagged widget_organizations with requiresService: 'org-scoping', so in single-tenant the KPI is gone (verified: absent from served metadata and the rendered overview). requiresObject widgets (e.g. Packages) stay client-gated, unchanged.
• P3 — i18n nav labels. "Cloud Connection" → 云连接, "Datasources" → 数据源, "Capabilities" → 能力 (added to platform-objects setup zh-CN.ts).
• P3 — Localization help text. Added zh help for number_format / currency / first_day_of_week / fiscal_year_start (service-settings zh-CN.ts); the "Grouping and decimal separators…" English leak is gone.
• P3 — Settings read/write asymmetry. PUT /api/settings/:ns now also accepts the { values: { … } } envelope that GET returns (flat or read-shape inner), so a client can write back what it read. Backward-compatible; covered by 2 new tests.

Still open (tracked here)

• P1 guided onboarding/setup checklist; P1 enterprise auth hardening (password complexity/expiry/lockout, MFA enforcement, SAML, IP allowlist, brute-force, session limits — must be enforcement-wired, not declaration-only); P2 bulk CSV / SCIM provisioning; P2 Roles/Capabilities/Permission-Sets conceptual overload.
• P3 KPI sublabels (Users/Organizations/Sessions/Events): not currently translatable — TranslationData (spec/system/translation.zod.ts) has no datasets/measure-label section. Needs a schema addition before the dataset measure labels can be localized.
• P3 "Recent" diagnostics nav label: the nav entry is translated (通知) but the console renders the bound view's label ("Recent") for viewName-carrying nav items — console-side (objectui) or make the view label translatable.
• P3 default-language precedence (tenant localization.locale vs per-user vs browser).

[os-zhuang]

Full Setup-menu sweep (all 38 items, browser-verified)

Drove every Setup menu route on a clean isolated server and checked each for render + errors. Result: 36 render fine; 2 were broken (now fixed).

Fixed → PR #2266

• Verifications (sys_verification) and Device Codes (sys_device_code) Advanced entries always rendered the "无法加载记录 / failed to load" error boundary. Root cause: both objects intentionally omit list from apiMethods (sensitive ephemeral secrets), so the generic list-view menu hit 405 OBJECT_API_METHOD_NOT_ALLOWED every time. Removed both nav entries (objects stay reachable by id).

Remaining minor i18n (folds into the i18n item already tracked here)

• List-page headings use the object's English label even though the nav label is translated: e.g. nav 能力 but heading "Capability"; nav 通知偏好/订阅/模板 but headings "Notification Preference/Subscription/Template"; also "Installed Apps", "Cloud Connection", "Datasources", "Settings". The object "kind" badges are English too (Identity / Admin config / System-managed / Read-only · Audit log).
• nav-label ↔ object-label mismatch: nav "审批申请" vs object heading "审批请求"; nav "审批历史" vs object heading "审批动作". Cosmetic, but worth aligning.

All settings pages (本地化/公司/品牌/认证/邮件/存储/AI/知识库/功能开关) and all listable object pages render correctly.