Complete platform management workflows

2026-07-14 16:39:37 +08:00
parent 7e05d0a4e7
commit 4f33f761a3
106 changed files with 11313 additions and 460 deletions
@@ -40,10 +40,18 @@ This change should stay inside platform_web interaction and visual polish. It mu

   Lifecycle actions, destructive confirmations, logs, diffs, config review, operation results, warnings, and AI recommendations must remain text-readable, traceable, and not color-only. Decorative theme effects must stay behind operational surfaces and respect reduced motion.

-5. Use browser walkthroughs for acceptance, not screenshots alone.
+5. Demote low-value counters near management headers.
+
+   Tiny counts such as installed plugin count, user count, role count, pending review count, provider count, enabled count, and model count are useful as context but should not become primary framed KPI cards. Management pages should keep scarce vertical space for the actual work surface: search/filter bars, plugin catalog, user table, and provider table.
+
+6. Use browser walkthroughs for acceptance, not screenshots alone.

   Completion requires exercising the actual routes and workflows in a browser at representative desktop and mobile widths. Screenshots can help debugging, but accepted evidence should focus on route behavior, visible controls, responsive layout, and absence of overlap or sensitive/fallback content.

+7. Prefer human-operable flows over raw DTO forms.
+
+   Management pages should expose the same platform-backed actions, but the UI should bundle them into understandable operator flows: one status-change path per user, readable AI provider row actions, provider setup presets and secret-reference help, and maintenance triage entry points that connect failed jobs or stale endpoints to the next useful page. These additions remain presentation/workflow polish and do not add new authorization, run, plugin, or provider semantics.
+
 ## Risks / Trade-offs

 - Visual polish can drift into scope expansion -> Keep tasks limited to platform_web interaction and theme presentation; do not change platform/run/plugin semantics.
@@ -5,6 +5,7 @@ The console now has real API-backed coverage and automated browser acceptance, b
 ## What Changes

 - Define accepted interaction/design criteria for the required first-party areas: 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
+- Compress low-value management page summary counts into compact status context so primary list/table surfaces keep the scarce first-screen space.
 - Define server detail workflow polish for lifecycle controls, logs, config, plugin controls, AI assistant, and operation history.
 - Require responsive desktop/mobile walkthrough coverage and no visible overlap, clipped text, unreadable panels, or inaccessible control states.
 - Require the polish to preserve the existing black mecha default theme, magical-girl alternate theme, translucent game-operations surfaces, grouped navigation, and shared theme primitives.
@@ -23,6 +23,10 @@ The platform_web console SHALL provide polished, scannable, API-backed interacti
 - **WHEN** an operator opens AI 提供商管理
 - **THEN** the route MUST present provider identity, connection status, relay mode, model/default-model information, and redacted key references without exposing raw keys or making status dependent on color alone

+#### Scenario: Management page counters stay secondary
+- **WHEN** an operator opens 插件市场、用户管理, or AI 提供商管理
+- **THEN** small summary counts such as installed plugins, bridge actions, validation failures, users, roles, pending reviews, providers, enabled providers, and models MUST render as compact contextual status instead of large framed KPI cards that displace the primary list, grid, table, search, or filter work surface
+
 ### Requirement: Server detail workflows are polished without direct run access
 The platform_web server detail route SHALL provide polished workflow surfaces for lifecycle, logs, config, plugin controls, AI assistant, and operation history while preserving platform-mediated boundaries.

@@ -43,6 +43,21 @@
 - [x] 6.4 If structural theme rules or shared style contracts change, update `platform_web/theme/README.md` and any relevant tests in the same change.
 - [x] 6.5 Update `openspec/changes/architecture-delivery-stream/delivery-plan.md` and `openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md` after implementation evidence exists.

+## 7. Management Header Density Correction
+
+- [x] 7.1 Replace large framed management summary KPI cards in 插件市场、用户管理, and AI 提供商管理 with compact contextual status chips.
+- [x] 7.2 Add regression tests proving those management headers render `page-summary-chip` instead of `metric-card`.
+- [x] 7.3 Run focused frontend tests, `scripts/check-structure.sh`, and `openspec validate polish-platform-interaction-design --strict`; record evidence.
+
+## 8. Human Workflow Polish Follow-up
+
+- [x] 8.1 Replace duplicate 用户管理 status/deactivation buttons with one status selector flow and explicit confirmation when disabling access.
+- [x] 8.2 Add user invitation, review, server-scope, and role-impact guidance without adding new backend authorization semantics.
+- [x] 8.3 Replace AI provider icon-only row actions with readable action labels and a compact "more" menu for lower-frequency enable/retire actions.
+- [x] 8.4 Add AI provider setup guidance: presets, secret-reference help, save-before validation, saved-configuration testing, and model discovery fill-in.
+- [x] 8.5 Add 系统维护 triage entry points for endpoint heartbeat/capacity, failed jobs, and related server/log navigation links.
+- [x] 8.6 Run focused frontend tests and typecheck; use the existing 5173 browser instance to spot-check the changed pages.
+
 ## Evidence

 - `platform_web/pages/UsersPage.tsx`: added explicit loading, API fallback error, empty-state, and accessible row action labels for 用户管理.
@@ -51,7 +66,14 @@
 - `platform_web/pages/PluginsPage.tsx`: polished plugin detail framing and action strip behavior.
 - `platform_web/theme/base.css`: hardened shared action strips, server toolbars, catalog cards, plugin detail panels, result strips, responsive grids, and table/workspace min-width behavior.
 - `platform_web/acceptance/browser-acceptance.mjs`: expanded browser acceptance to record desktop/mobile walkthroughs for black mecha and magical-girl themes, route marker checks, visible-layout checks, API-backed route proof, plugin controls, and operation-history proof.
+- Header density correction evidence: `platform_web/components/PageFrame.tsx` and `platform_web/pages/AiProvidersPage.tsx` now render management summary counts as `page-summary-chip`; `platform_web/pages/PluginsPage.test.tsx`, `platform_web/pages/UsersPage.test.tsx`, and `platform_web/pages/AiProvidersPage.test.tsx` assert those headers no longer render `metric-card`.
+- Focused frontend evidence: `cd platform_web && npm test -- PluginsPage.test.tsx UsersPage.test.tsx AiProvidersPage.test.tsx`, `cd platform_web && npm run typecheck`, and `cd platform_web && npm run build` passed for the header density correction.
 - Browser evidence: `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh` passed; evidence file `/private/tmp/browser-local-debug-acceptance/browser-acceptance/browser-acceptance-evidence.json` records 7 required routes plus 4 walkthrough scenarios: desktop/mobile black mecha and desktop/mobile magical-girl.
 - Frontend evidence: `cd platform_web && npm run typecheck`, `cd platform_web && npm test` (11 files / 49 tests), and `cd platform_web && npm run build` passed.
 - Structure evidence: `scripts/check-structure.sh` passed.
 - OpenSpec evidence: `openspec validate polish-platform-interaction-design --strict` passed.
+- Human workflow polish evidence: `platform_web/pages/UsersPage.tsx` now uses one status selector/apply path, keeps disable confirmation, renames create flow to 邀请用户, and shows invite/review/server-scope/role-impact guidance.
+- AI provider workflow evidence: `platform_web/pages/AiProvidersPage.tsx` now shows row actions as 测试 / 模型 / 编辑 / 更多, moves enable/retire into the more menu, adds provider presets, secret-reference help, 保存前检查, saved-configuration testing, and saved-model discovery fill-in.
+- Maintenance triage evidence: `platform_web/pages/MaintenancePage.tsx` now loads endpoints, jobs, servers, and audit events to show node heartbeat/capacity detail, recent failed jobs, retry dispatch, related server links, and log-chain entry copy.
+- Human workflow verification: `cd platform_web && npm test -- UsersPage.test.tsx AiProvidersPage.test.tsx ConsolePages.test.tsx`, `cd platform_web && npm run typecheck`, and `cd platform_web && npm run build` passed. `scripts/check-structure.sh` passed. `openspec validate polish-platform-interaction-design --strict` passed; only PostHog telemetry flushing failed due restricted network after validation succeeded.
+- Browser spot-check evidence: existing `http://127.0.0.1:5173` was opened and logged in with the local test operator. `#/aiProviders` showed readable row actions and edit dialog guidance with no clipped target buttons and no `api.example.test`; `#/users` showed 邀请用户, 审核申请, 绑定服务器范围, 角色影响, 应用状态, no duplicate “停用用户” label, and no clipped target buttons; `#/maintenance` showed 系统维护, 节点详情, 最近失败任务, heartbeat/status context, and the follow-up commit adds visible 维护排障入口 / 查看相关服务器 / 查看日志链路 copy for empty-data states.