diff --git a/docs/superpowers/specs/2026-07-30-warm-operations-workbench-design.md b/docs/superpowers/specs/2026-07-30-warm-operations-workbench-design.md new file mode 100644 index 0000000..08551cb --- /dev/null +++ b/docs/superpowers/specs/2026-07-30-warm-operations-workbench-design.md @@ -0,0 +1,255 @@ +# SimAdmin Warm Operations Workbench Design + +**Date:** 2026-07-30 + +**Status:** Approved design + +**Primary goal:** Replace the conflicting glass-and-game UI with a coherent warm operations workbench, and turn the current read-only Jobs surface into a durable automation center for scheduled restarts and SMS delivery. + +## 1. Scope + +This design covers two connected changes: + +1. Rework the application shell and Fleet page into a compact, warm, information-dense operations interface. +2. Replace the current top-level Jobs and Audit destinations with an Automation center containing schedules, execution history, and lower-priority operation records. + +The existing instance routes, SSE refresh behavior, settings, safe operation catalog, Jobs history, Audit history, and SimAdmin feature modules remain in place unless this document explicitly changes their presentation or integration. + +## 2. Reference Direction + +The selected direction is **Warm Operations Workbench**. + +- Animal Island supplies the cream surfaces, warm brown text, mint accent, Nunito/Noto Sans SC typography, friendly geometry, and restrained tactile primary actions. +- Apple supplies hierarchy, immediate press feedback, restraint, sparse elevation, predictable control placement, and accessibility fallbacks. +- Notion supplies warm workspace organization, thin borders, compact content panels, and clear separation between primary work and supporting records. +- Linear supplies the scanning model for dense operational information, especially status rows, resource values, filters, and history views. + +Apple's cold white glass material is not used. Ribbon titles, dotted wallpaper, deep card shadows, decorative gradients, and permanently visible selection controls are excluded from operational surfaces. + +## 3. Information Architecture + +The top-level navigation becomes: + +- **Nodes** (`/fleet` and instance routes) +- **Automation** (`/automation`) +- **Settings** (`/settings/instances` and `/settings/system`) + +The existing Jobs and Audit routes remain compatible through redirects or route aliases, but are no longer separate primary navigation items. + +Automation contains three views: + +1. **Schedules**: create and manage Cron-based tasks. +2. **Runs**: present existing Jobs data and schedule-run aggregation. +3. **Operation records**: present existing Audit data for security and troubleshooting. This view is intentionally secondary and read-only. + +## 4. Visual System + +### 4.1 Global shell + +- Use a compact header of approximately 56px. +- Place product identity on the left, three primary navigation items in the main navigation area, and connection state on the right. +- Use solid warm surfaces. Translucency may be used only for a sticky overlay that visibly floats over scrolling content; it is not the default material. +- Remove oversized page headers and decorative English kickers. +- Use plain semantic headings rather than Animal Island ribbon titles on dense operational pages. +- Keep page gutters between 16px and 24px on ordinary desktop widths and lock very wide content to a practical maximum width. + +### 4.2 Tokens + +- Background: warm cream derived from Animal Island, not cool gray. +- Content surface: slightly lighter cream or white-cream. +- Primary text: warm brown; never pure black. +- Secondary text: muted warm brown with WCAG-compliant contrast. +- Primary action and selection: mint/teal. +- Warning: warm amber. +- Destructive and system reboot: semantic red, limited to labels, borders, icons, and confirmation surfaces. +- Card radius: 14px to 16px. +- Control radius: established Animal Island control grammar, including pills where appropriate. +- Default cards have no drop shadow. Hierarchy comes from solid surface changes and 1px warm hairlines. +- Selected cards use a stable 2px mint outline and a very light mint fill without changing layout dimensions. + +### 4.3 Motion and accessibility + +- Interaction transitions last 120ms to 200ms. +- Pointer-down and active states provide immediate scale or translation feedback. +- Motion communicates selection, expansion, state updates, and surface arrival only. +- All controls support keyboard navigation and visible focus. +- `prefers-reduced-motion`, `prefers-reduced-transparency`, and `prefers-contrast` are respected. +- Touch targets are at least 44px on touch layouts. + +## 5. Fleet Page + +### 5.1 Layout + +- Remove the persistent left summary/sidebar. +- Combine summary counts, search, filters, sorting, refresh, add-instance, and batch-mode entry into a compact page header and toolbar. +- Render nodes in three columns on wide desktop, two columns on medium layouts, and one column on mobile. +- Keep panel dimensions stable so status changes and progress updates do not shift the grid. + +### 5.2 Node panel + +Each node panel contains, in order: + +1. Identity: avatar, name, status, and detail link. +2. Endpoint and phone-number summary. +3. CPU, memory, and maximum temperature in one compact resource row. +4. Tags and recent SMS summary when available. +5. Service restart and system reboot actions. + +Cards use a cream solid surface, warm hairline border, 14px to 16px radius, and no floating shadow. Hover does not lift the whole panel. Action buttons may use subtle press feedback. + +Selection controls are hidden during normal browsing. A toolbar command enters batch-selection mode, after which checkboxes appear in a consistent leading position. Leaving selection mode removes them. This prevents selection chrome from permanently competing with node identity. + +## 6. Automation Center + +### 6.1 Schedule list + +Schedules use a dense list or table rather than repeated cards. Each row shows: + +- name; +- operation type; +- fixed-instance or tag-selector target summary; +- Cron expression; +- next execution time in Beijing time; +- latest result; +- enabled state; +- row menu for edit, run now, duplicate, pause/resume, and delete. + +Deleting a schedule stops future runs but never removes immutable execution or operation history. + +### 6.2 Schedule editor + +The editor opens in a right-side drawer and uses progressive sections: + +1. Name. +2. Operation: restart SimAdmin service, reboot device system, or send SMS. +3. Targets: multiple fixed instances or dynamic tag matching. +4. SMS configuration when applicable: one or more recipient numbers and message content. +5. Standard five-field Cron expression with future-five-run preview. +6. Optional effective start and end times. +7. Misfire behavior: skip or catch up once; default is skip. +8. Overlap behavior: skip or queue once; default is skip. +9. Bounded retry count and interval. System reboot defaults to no automatic retries. +10. Final target/risk summary and confirmation. + +The only supported timezone is `Asia/Shanghai`. The UI does not expose a timezone selector. Cron parsing, previews, misfire reconciliation, run timestamps, and operation-record timestamps are displayed as Beijing time (`UTC+8`). APIs reject alternate timezone input. + +Cron frequency is not restricted. High-frequency restart schedules display a prominent warning, future-run preview, and an additional confirmation, but the product does not block saving or execution. + +### 6.3 Target matching + +- Fixed mode stores a set of instance IDs. +- Dynamic mode stores a tag expression and resolves it at every trigger. +- Dynamic matching supports choosing whether all selected tags or any selected tag must match. +- The resolved target list is persisted as an immutable run snapshot. +- Instances added to a matching tag after schedule creation are included in later runs. +- A run with no matching targets receives the `no-targets` outcome and is not treated as an infrastructure failure. + +## 7. Persistence Model + +### 7.1 Scheduled tasks + +`scheduled_tasks` stores non-secret configuration: + +- identifier, name, operation type, enabled state, version; +- five-field Cron expression; +- fixed `Asia/Shanghai` timezone marker; +- target mode and target-selector JSON; +- effective start/end; +- misfire, overlap, and retry policy; +- next due time, last evaluated time; +- creator/updater identity and timestamps; +- a reference to secret SMS payload data when needed. + +### 7.2 Scheduled runs + +`scheduled_runs` stores: + +- schedule ID and immutable schedule version; +- due, claimed, started, and finished times; +- resolved target snapshot; +- aggregate outcome and skip/failure reason; +- correlated Job identifiers; +- manual or scheduled trigger source; +- attempt and retry metadata. + +SMS recipient numbers and message content reuse the existing secret-storage infrastructure. The SQLite schedule row stores only a reference. Audit and application logs never render message content and continue masking phone numbers. + +## 8. Scheduler and Execution + +- Use a maintained Cron parser with timezone support; do not implement Cron grammar manually. +- On API startup, load enabled schedules and reconcile due times. +- Apply each schedule's misfire policy: skip or execute one catch-up run. Never replay every missed occurrence. +- Claim a due occurrence transactionally using schedule ID, version, and due time so restarts or concurrent workers cannot execute it twice. +- Resolve targets at claim time and persist the target snapshot before dispatch. +- Validate that each instance is enabled, has the required capability, and has a current configuration revision. +- Execute each target independently. One target failure does not block other targets. +- Aggregate individual Jobs into one scheduled run. + +Schedule creation performs durable authorization for the exact schedule definition. Runtime execution validates the stored schedule version and operation constraints. Short-lived interactive confirmation tokens are never persisted or reused. Editing the operation, targets, Cron expression, or SMS payload creates a new version and requires confirmation again. + +Restart operations continue through the safe operation path. Scheduled SMS execution must gain equivalent Job correlation, request-body digesting, redaction, and Audit coverage rather than calling the existing direct message route without durable history. + +## 9. Outcomes and Error Handling + +Run outcomes are: + +- `succeeded`: every dispatch succeeded; +- `partially-succeeded`: at least one dispatch succeeded and at least one failed; +- `failed`: all attempted dispatches failed; +- `skipped`: missed window, overlap, disabled schedule, or an explicit scheduler skip; +- `no-targets`: the current selector matched no enabled instances; +- `needs-attention`: missing SMS secret, invalid schedule version, or removed capability. + +Offline or authentication-failed instances fail independently and follow the task's retry policy. System reboot has zero retries by default. Consecutive failures produce one persistent summary in the Automation page rather than repeated global notifications. + +Invalid Cron syntax blocks save. Backend validation remains authoritative even when the UI preview succeeds. Missing secret data disables execution and surfaces `needs-attention`; it never substitutes an empty SMS body. + +## 10. API Surface + +The Automation UI requires authenticated endpoints for: + +- list/get/create/update schedules; +- pause/resume and delete schedules; +- preview Cron occurrences in Beijing time; +- run a schedule immediately; +- list/get scheduled runs and their correlated Jobs. + +Requests and responses use strict contracts, bounded arrays/strings, exact-key validation where used elsewhere in the project, redacted problem details, and optimistic version checks for edits. + +## 11. Testing and Acceptance + +### 11.1 Automated tests + +- Cron parsing, Beijing-time boundaries, and future occurrence calculation. +- Startup reconciliation with skip and one-catch-up misfire policies. +- Transactional claim and duplicate prevention. +- Fixed multi-instance and dynamic any/all tag matching. +- Overlap skip and queue-once behavior. +- Bounded retries and no-retry system reboot default. +- Service restart, system reboot, and SMS execution. +- Per-target partial success and aggregate outcomes. +- Schedule version invalidation after sensitive edits. +- SMS secret persistence and complete log/Audit redaction. +- Schedule CRUD, pause/resume, duplicate, run-now, and immutable history. +- Existing Fleet, Jobs, Audit, settings, SSE, and instance-route regressions. + +### 11.2 Browser and visual acceptance + +- Real-browser flow for creating, editing, pausing, running, and deleting schedules. +- Keyboard-only completion of Fleet selection and schedule creation. +- Screenshots at 390px, 768px, 1024px, and 1440px. +- No horizontal overflow or overlapping text. +- Fleet renders one, two, or three columns at the intended widths. +- Selection controls appear only in batch mode. +- Reduced-motion and increased-contrast states remain usable. +- Existing instance actions and deep links remain functional. + +## 12. Non-Goals + +- User-selectable timezones. +- Second-level Cron expressions. +- Enforcing a minimum schedule interval. +- Replaying every occurrence missed during downtime. +- A general workflow builder with conditional branches. +- Removing immutable Audit data from the backend. +- Replacing Animal Island UI wholesale with another component library.