feat: prepare Zhinian desktop client for pilot release

2026-04-29 10:23:20 +08:00
parent f9361e686a
commit 47b83b79fc
149 changed files with 15341 additions and 3590 deletions
--- a/design-system/智念助手/MASTER.md
+++ b/design-system/智念助手/MASTER.md
@@ -0,0 +1,275 @@
+# Design System Master File
+
+> **LOGIC:** When building a specific page, first check `design-system/智念助手/pages/[page-name].md`.
+> If that file exists, its rules **override** this Master file.
+> If not, strictly follow the rules below.
+
+---
+
+**Project:** 智念助手
+**Generated:** 2026-04-26 16:21:54
+**Category:** Micro SaaS
+
+---
+
+## Global Rules
+
+### Color Palette
+
+| Role | Hex | CSS Variable |
+|------|-----|--------------|
+| Primary | `#1E3A8A` | `--color-primary` |
+| Secondary | `#3B82F6` | `--color-secondary` |
+| CTA/Accent | `#CA8A04` | `--color-cta` |
+| Background | `#F8FAFC` | `--color-background` |
+| Text | `#1E40AF` | `--color-text` |
+
+**Color Notes:** Luxury navy + gold service
+
+### Typography
+
+- **Preferred Implementation:** System font stack first for desktop reliability and China-network/offline friendliness.
+- **Heading Font:** `-apple-system`, `BlinkMacSystemFont`, `PingFang SC`, `Microsoft YaHei`, `Segoe UI`, sans-serif
+- **Body Font:** `-apple-system`, `BlinkMacSystemFont`, `PingFang SC`, `Microsoft YaHei`, `Segoe UI`, sans-serif
+- **Reference Pairing:** Rubik + Nunito Sans can inform proportions, but should not be required at runtime.
+- **Mood:** mature B-end operations, precise desktop tooling, calm AI assistant
+
+**Optional Reference Import:**
+```css
+@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap');
+```
+
+### Spacing Variables
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--space-xs` | `4px` / `0.25rem` | Tight gaps |
+| `--space-sm` | `8px` / `0.5rem` | Icon gaps, inline spacing |
+| `--space-md` | `16px` / `1rem` | Standard padding |
+| `--space-lg` | `24px` / `1.5rem` | Section padding |
+| `--space-xl` | `32px` / `2rem` | Large gaps |
+| `--space-2xl` | `48px` / `3rem` | Section margins |
+| `--space-3xl` | `64px` / `4rem` | Hero padding |
+
+### Shadow Depths
+
+| Level | Value | Usage |
+|-------|-------|-------|
+| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift |
+| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, buttons |
+| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns |
+| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Hero images, featured cards |
+
+---
+
+## Component Specs
+
+### Buttons
+
+```css
+/* Primary Button */
+.btn-primary {
+  background: #CA8A04;
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.btn-primary:hover {
+  opacity: 0.9;
+  transform: translateY(-1px);
+}
+
+/* Secondary Button */
+.btn-secondary {
+  background: transparent;
+  color: #1E3A8A;
+  border: 2px solid #1E3A8A;
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+```
+
+### Cards
+
+```css
+.card {
+  background: #F8FAFC;
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: var(--shadow-md);
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-lg);
+  transform: translateY(-2px);
+}
+```
+
+### Inputs
+
+```css
+.input {
+  padding: 12px 16px;
+  border: 1px solid #E2E8F0;
+  border-radius: 8px;
+  font-size: 16px;
+  transition: border-color 200ms ease;
+}
+
+.input:focus {
+  border-color: #1E3A8A;
+  outline: none;
+  box-shadow: 0 0 0 3px #1E3A8A20;
+}
+```
+
+### Modals
+
+```css
+.modal-overlay {
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(4px);
+}
+
+.modal {
+  background: white;
+  border-radius: 16px;
+  padding: 32px;
+  box-shadow: var(--shadow-xl);
+  max-width: 500px;
+  width: 90%;
+}
+```
+
+---
+
+## Style Guidelines
+
+**Style:** Flat Design
+
+**Keywords:** 2D, minimalist, bold colors, no shadows, clean lines, simple shapes, typography-focused, modern, icon-heavy
+
+**Best For:** Web apps, mobile apps, cross-platform, startup MVPs, user-friendly, SaaS, dashboards, corporate
+
+**Key Effects:** No gradients/shadows, simple hover (color/opacity shift), fast loading, clean transitions (150-200ms ease), minimal icons
+
+### Product Identity
+
+- **Product Name:** 智念助手
+- **Desktop App ID:** `app.zhinian.assistant`
+- **Primary Mark:** Rounded navy app tile with a blue conversation panel, white intelligence loop, and restrained gold service line.
+- **Brand Assets:**
+  - App icon source: `resources/icons/icon.svg`
+  - Plain app mark: `resources/icons/icon-plain.svg`
+  - Tray template source: `resources/icons/tray-icon-template.svg`
+  - Renderer wordmark: `src/assets/logo.svg`
+- **Generated Desktop Assets:**
+  - `resources/icons/icon.png`
+  - `resources/icons/icon.icns`
+  - `resources/icons/icon.ico`
+  - `resources/icons/16x16.png` through `512x512.png`
+  - `resources/icons/tray-icon-Template.png`
+
+### Product Shell Rules
+
+- Desktop shell must say `智念助手` in customer-facing places.
+- Product language should describe the selected tenant as a `工作空间` or `业务对象`, not as a hotel.
+- Keep `ClawX` and `OpenClaw` only in technical contexts, developer documentation, compatibility tests, or advanced implementation surfaces.
+- Login, Sidebar, Windows title bar, tray menu, installer metadata, and desktop shortcuts should all use the 智念助手 brand.
+- The design should feel like a mature operations product, not a marketing landing page.
+
+### Implemented UI Primitives
+
+The renderer design kit lives in `src/components/yinian/ui.tsx`.
+
+- `YinianPageShell`
+- `YinianPageHeader`
+- `YinianHeaderActions`
+- `YinianKicker`
+- `YinianPanel`
+- `YinianSectionPanel`
+- `YinianMetricCard`
+- `YinianListItem`
+- `YinianInfoRow`
+- `YinianNotice`
+- `YinianEmptyState`
+- `YinianStatusDot`
+
+Use these before adding page-local card/list/notice styling. New primitives should stay thin and composable over existing React/Tailwind/shadcn foundations.
+
+### Implemented Page Direction
+
+- **Login:** enterprise desktop entry with brand narrative, reliability cues, and a focused organization account form.
+- **Today:** operations cockpit using section panels, metric cards, task queue rows, and clear skill state labels.
+- **Skills Manager:** capability management surface with clear entitlement/local registry/version state separation.
+- **Sidebar Service Context:** one account maps to one B-end service for now; show the current service, region, role, and user inside the left sidebar instead of a top switcher. The service card is also the Dashboard/Today entry.
+- **Sidebar:** production navigation is intentionally narrow: `快速使用` for Skills/定时任务/知识库, `对话` for New Chat/History, and a footer Settings entry. Do not expose Models, Agents, Channels, or Dev Console in normal customer navigation.
+- **Chat History:** history should not be a permanently expanded side list. Use a compact `历史会话` row that opens a hover popover on pointer devices and clicks through to the latest session.
+- **Knowledge Base:** knowledge upload is a first-class quick-use tool. The v0 UI may be local-only, but it should present as a service-scoped document library that will later connect to indexing and permissions.
+- **Settings:** account actions, service config sync, logout, local preferences, and the "configuration is service-managed" explanation belong in Settings.
+- **Service-Managed Configuration:** model/provider strategy, Agent orchestration, notification channels, and low-level scheduling policy are issued by the service side for the current account/service. Local editing controls for these areas should stay disabled or hidden unless an explicit admin/developer mode is added.
+- **Inherited Chinese Surfaces:** customer-visible Chinese strings in Chat, Settings, and Setup should say 智念助手; keep ClawX/OpenClaw only where the user is explicitly in technical or compatibility context.
+- **Inherited Page Typography:** inherited dashboard pages should not use oversized serif page titles. Use system-font, semibold headings with compact desktop-dashboard scale.
+- **Customer-Visible Chinese Copy:** zh locale should avoid ClawX unless describing a technical compatibility or upstream/open-source context.
+
+### Visual QA Baselines
+
+The production 智念 flow has a repeatable screenshot smoke test in `tests/e2e/yinian-visual-smoke.spec.ts`.
+
+- Login baseline: `test-results/yinian-visual/01-login.png`
+- Today baseline: `test-results/yinian-visual/02-today.png`
+- Skills baseline: `test-results/yinian-visual/03-skills.png`
+- Knowledge baseline: `test-results/yinian-visual/04-knowledge.png`
+- Settings baseline: `test-results/yinian-visual/05-settings.png`
+
+Run `pnpm run build:vite` before `pnpm exec playwright test tests/e2e/yinian-visual-smoke.spec.ts` so Electron loads the latest built renderer.
+
+### Page Pattern
+
+**Pattern Name:** Product Demo + Features
+
+- **Conversion Strategy:** Embedded product demo increases engagement. Use interactive mockup if possible. Auto-play video muted.
+- **CTA Placement:** Video center + CTA right/bottom
+- **Section Order:** 1. Hero, 2. Product video/mockup (center), 3. Feature breakdown per section, 4. Comparison (optional), 5. CTA
+
+---
+
+## Anti-Patterns (Do NOT Use)
+
+- ❌ Complex onboarding flow
+- ❌ Cluttered layout
+
+### Additional Forbidden Patterns
+
+- ❌ **Emojis as icons** — Use SVG icons (Heroicons, Lucide, Simple Icons)
+- ❌ **Missing cursor:pointer** — All clickable elements must have cursor:pointer
+- ❌ **Layout-shifting hovers** — Avoid scale transforms that shift layout
+- ❌ **Low contrast text** — Maintain 4.5:1 minimum contrast ratio
+- ❌ **Instant state changes** — Always use transitions (150-300ms)
+- ❌ **Invisible focus states** — Focus states must be visible for a11y
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering any UI code, verify:
+
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] `cursor-pointer` on all clickable elements
+- [ ] Hover states with smooth transitions (150-300ms)
+- [ ] Light mode: text contrast 4.5:1 minimum
+- [ ] Focus states visible for keyboard navigation
+- [ ] `prefers-reduced-motion` respected
+- [ ] Responsive: 375px, 768px, 1024px, 1440px
+- [ ] No content hidden behind fixed navbars
+- [ ] No horizontal scroll on mobile