@umacloud/knowledge 1.0.1

package/seed-templates/auth-system.md

@@ -0,0 +1,59 @@
+---
+id: auth-system
+title: Seed Template: Authentication System
+domain: seed-templates
+category: auth-system.md
+difficulty: intermediate
+tags: [auth, component, gates, page, patterns, quality, seed-templates, structure]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: Authentication System
+
+> Use for login/signup/MFA/password-reset flows.
+> Recommended design direction: Modern Minimal.
+
+## Page structure
+
+```
+Auth flow pages (each a separate route):
+
+/login          — email + password + "Remember me" + "Forgot?" link + OAuth buttons
+/signup         — name + email + password + confirm + terms checkbox + OAuth
+/forgot         — email input + "Send reset link" button
+/reset/:token   — new password + confirm + "Reset" button
+/verify-email   — success message + "Resend" link
+/mfa            — 6-digit TOTP input + "Use backup code" link
+/mfa/setup      — QR code + manual key + verify input
+```
+
+## Component patterns
+
+### Auth card (centered on page)
+- max-width: 420px, centered vertically + horizontally
+- bg-surface, radius-lg, shadow-md, padding 32-40px
+- Logo at top, heading below, form fields, primary CTA full-width
+
+### OAuth buttons
+- Full-width, secondary style, icon left-aligned
+- "Continue with Google" / "Continue with GitHub"
+- Separated from email form by "or" divider
+
+### Password input
+- Show/hide toggle (eye icon from icon library)
+- Strength indicator bar below (4 segments: weak/fair/good/strong)
+
+## Quality gates
+
+### P0
+- [ ] Login form submits (even if to /api/auth/login stub)
+- [ ] Password visibility toggle works
+- [ ] OAuth buttons are styled (not unstyled links)
+- [ ] Mobile responsive (card shrinks, no horizontal scroll)
+- [ ] Error states shown inline (red border + message below field)
+
+### P1
+- [ ] MFA TOTP input auto-advances between 6 digit boxes
+- [ ] Password strength indicator animates on typing
+- [ ] "Remember me" checkbox styled with custom checkmark
+- [ ] Loading spinner on form submit

package/seed-templates/blog-content.md

@@ -0,0 +1,94 @@
+---
+id: blog-content
+title: Seed Template: Blog / Content Site
+domain: seed-templates
+category: blog-content.md
+difficulty: intermediate
+tags: [article, articles, blog, content, gates, page, quality, rules]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: Blog / Content Site
+
+> Use this structure when the product is a blog, documentation site, or content-heavy platform.
+> Recommended design direction: Editorial Clean.
+
+## Page structure
+
+```
+┌─────────────────────────────────────────────────┐
+│  Nav: logo · category links · search · theme btn │
+├─────────────────────────────────────────────────┤
+│  Featured: hero article with large image         │
+│  ┌────────────────────────────────────────────┐  │
+│  │  Category tag · Read time                  │  │
+│  │  Article Title (display font, large)       │  │
+│  │  Excerpt (body-lg)                         │  │
+│  │  Author avatar + name + date               │  │
+│  └────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────┤
+│  Article grid: 2-3 column cards                  │
+│  Each: thumbnail · category · title · excerpt    │
+├─────────────────────────────────────────────────┤
+│  Newsletter CTA: simple email capture            │
+├─────────────────────────────────────────────────┤
+│  Footer: about · categories · social · copyright │
+└─────────────────────────────────────────────────┘
+```
+
+## Article page structure
+
+```
+┌─────────────────────────────────────────────────┐
+│  Nav (same as index)                             │
+├─────────────────────────────────────────────────┤
+│  Article header:                                 │
+│    Category · Read time                          │
+│    Title (display, 36-48px)                      │
+│    Subtitle (body-lg)                            │
+│    Author + date + share buttons                 │
+├─────────────────────────────────────────────────┤
+│  ┌─────────┐                                     │
+│  │ Content │  max-width: 680px, centered          │
+│  │ column  │  Serif body text, 18-20px            │
+│  │         │  Line-height: 1.7                    │
+│  │ h2/h3   │  Serif headings                      │
+│  │ images  │  Full-width within column             │
+│  │ code    │  Monospace, bg-surface-sunken         │
+│  │ quotes  │  Left border + italic                 │
+│  └─────────┘                                     │
+├─────────────────────────────────────────────────┤
+│  Related articles: 3-column card grid            │
+├─────────────────────────────────────────────────┤
+│  Footer                                          │
+└─────────────────────────────────────────────────┘
+```
+
+## Typography rules for articles
+
+- Body text: serif, 18-20px, line-height 1.7 — optimized for reading
+- Headings: same serif family, weight 700
+- Code blocks: monospace, 14px, surface-sunken background
+- Links: underline on hover, primary color
+- Blockquote: left border 3px primary, italic
+- Max content width: 680px (optimal reading width)
+
+## Quality gates
+
+### P0
+- [ ] Articles are readable (correct font size, line-height, max-width)
+- [ ] Navigation works between index and article pages
+- [ ] Images have aspect ratios maintained
+- [ ] Mobile responsive (single column on mobile)
+
+### P1
+- [ ] Category filtering works on index page
+- [ ] Article metadata (date, read time, author) is formatted
+- [ ] Code blocks have syntax highlighting
+- [ ] Newsletter form validates email
+
+### P2
+- [ ] Dark mode support
+- [ ] Reading progress indicator
+- [ ] Smooth scroll to headings
+- [ ] Table of contents for long articles

package/seed-templates/dashboard.md

@@ -0,0 +1,89 @@
+---
+id: dashboard
+title: Seed Template: Dashboard
+domain: seed-templates
+category: dashboard.md
+difficulty: intermediate
+tags: [component, dashboard, gates, layout, page, patterns, quality, rules]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: Dashboard
+
+> Use this structure when the product is a data dashboard, admin panel, or monitoring tool.
+> Recommended design direction: Tech Utility or Modern Minimal.
+
+## Page structure
+
+```
+┌──────┬──────────────────────────────────────────┐
+│ Side │  Top bar: breadcrumb · search · avatar   │
+│ bar  ├──────────────────────────────────────────┤
+│      │  KPI row: 3-4 stat cards                  │
+│ Nav  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐    │
+│ 220px│  │ Stat │ │ Stat │ │ Stat │ │ Stat │    │
+│      │  └──────┘ └──────┘ └──────┘ └──────┘    │
+│      ├──────────────────────────────────────────┤
+│      │  Primary chart: full-width, 300px height  │
+│      ├───────────────────┬──────────────────────┤
+│      │  Data table       │  Secondary chart     │
+│      │  (sortable, paged)│  or activity feed    │
+│      │                   │                      │
+└──────┴───────────────────┴──────────────────────┘
+```
+
+## Layout rules
+
+- Sidebar: fixed 220px width, collapsible to 64px (icons only) on mobile
+- Content area: fluid, min-width 640px
+- KPI cards: equal width, flexbox row with 16px gap
+- Primary chart: full content width, 280-320px height
+- Bottom row: 60/40 or 50/50 split
+
+## Component patterns
+
+### Stat card
+```
+┌─────────────────────┐
+│  Label (caption)     │
+│  123,456 (num, 28px) │
+│  ↑ 12.3% (trend)    │
+└─────────────────────┘
+```
+- Number right-aligned or left-aligned with trend badge
+- Trend: green up-arrow for positive, red down-arrow for negative
+- Use monospace for numbers
+
+### Data table
+- Sticky header row
+- Alternating row colors (transparent / surface-sunken)
+- Sortable columns with chevron indicator
+- Pagination: "1-20 of 156" + prev/next
+- Row height: 44px for comfortable clicking
+- Monospace for IDs, timestamps, numeric columns
+
+### Sidebar nav
+- Active item: bg-primary-muted + text-primary + left border 3px
+- Hover: bg-surface-sunken
+- Section headers: caption weight, uppercase, 0.08em letter-spacing
+- Icons: 20px Lucide, stroke-width 1.5
+
+## Quality gates
+
+### P0
+- [ ] Sidebar navigation works (active state tracks route)
+- [ ] KPI cards show realistic numbers (not "123" or "N/A")
+- [ ] Table sorts on column click
+- [ ] Responsive: sidebar collapses on mobile
+
+### P1
+- [ ] Chart renders (even if placeholder SVG)
+- [ ] Loading skeletons for KPI cards and table
+- [ ] Empty state for table when no data
+- [ ] Keyboard navigable (Tab through nav items)
+
+### P2
+- [ ] Transition animations on stat card number changes
+- [ ] Table row hover highlight
+- [ ] Chart tooltip on hover
+- [ ] Dark mode via design tokens

package/seed-templates/docs-site.md

@@ -0,0 +1,73 @@
+---
+id: docs-site
+title: Seed Template: Documentation Site
+domain: seed-templates
+category: docs-site.md
+difficulty: intermediate
+tags: [component, docs, gates, page, patterns, quality, seed-templates, site]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: Documentation Site
+
+> Use for API docs, developer guides, knowledge bases.
+> Recommended design direction: Modern Minimal or Tech Utility.
+
+## Page structure
+
+```
+┌─────────────────────────────────────────────────┐
+│  Top nav: logo · search (cmd+K) · version · GitHub│
+├──────┬──────────────────────────────────────────┤
+│ Left │  Content area (max-width 780px)           │
+│ side │                                            │
+│ bar  │  # Page title                              │
+│ 240px│  > Callout box                             │
+│      │  Body text (16px, 1.6 line-height)         │
+│ tree │  ## Section heading                        │
+│ nav  │  Code block (syntax highlighted)           │
+│      │  ### Subsection                            │
+│      │  Table (API parameters)                    │
+│      │                                            │
+│      ├──────────────────────────────────────────┤
+│      │  Prev/Next navigation                      │
+│      │  "Was this helpful?" feedback               │
+└──────┴──────────────────────────────────────────┘
+```
+
+## Component patterns
+
+### Sidebar navigation
+- Collapsible tree with section > page > anchor structure
+- Active page highlighted, active section expanded
+- Mobile: hamburger menu slides from left
+
+### Code block
+- Syntax highlighting (language label top-right)
+- Copy button (click → "Copied!")
+- Tab group for multi-language examples (curl / JS / Python)
+
+### Callout boxes (4 types)
+- Info: blue-left-border + info icon
+- Warning: yellow-left-border + warning icon
+- Tip: green-left-border + lightbulb icon
+- Danger: red-left-border + alert icon
+
+### Search (Cmd+K)
+- Modal overlay with input + instant results
+- Keyboard navigable (↑↓ + Enter)
+- Results grouped by section
+
+## Quality gates
+
+### P0
+- [ ] Navigation tree works (expand/collapse, active state)
+- [ ] Code blocks have copy button
+- [ ] Mobile sidebar collapses to hamburger
+- [ ] Content area has appropriate max-width for reading
+
+### P1
+- [ ] Search modal opens on Cmd+K
+- [ ] Syntax highlighting renders correctly
+- [ ] Table of contents on right side (for long pages)
+- [ ] Prev/Next links navigate between pages

package/seed-templates/e-commerce.md

@@ -0,0 +1,50 @@
+---
+id: e-commerce
+title: Seed Template: E-Commerce Product Page
+domain: seed-templates
+category: e-commerce.md
+difficulty: intermediate
+tags: [commerce, gates, page, quality, seed-templates, structure]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: E-Commerce Product Page
+
+> Use for online shops, marketplaces, product catalogs.
+> Recommended design direction: Modern Minimal or Soft Warm.
+
+## Page structure
+
+```
+┌─────────────────────────────────────────────────┐
+│  Nav: logo · search · cart(badge) · account      │
+├─────────────────────────────────────────────────┤
+│  Breadcrumb: Home > Category > Product           │
+├──────────────────────┬──────────────────────────┤
+│  Image gallery       │  Product info             │
+│  (main + thumbnails) │  Title · Price · Rating   │
+│  zoom on hover       │  Variant selector          │
+│                      │  Add to Cart button        │
+│                      │  Shipping info             │
+├──────────────────────┴──────────────────────────┤
+│  Tabs: Description · Specs · Reviews              │
+├─────────────────────────────────────────────────┤
+│  Related products: 4-column card grid             │
+├─────────────────────────────────────────────────┤
+│  Footer: links · payment icons · copyright        │
+└─────────────────────────────────────────────────┘
+```
+
+## Quality gates
+
+### P0
+- [ ] Add to Cart button is prominent and always visible
+- [ ] Price displayed clearly with currency
+- [ ] Image gallery loads and thumbnails switch main image
+- [ ] Mobile: single column, sticky "Add to Cart" bottom bar
+
+### P1
+- [ ] Variant selector (size/color) updates price and image
+- [ ] Rating stars rendered as SVG (not emoji)
+- [ ] Related products section populated
+- [ ] Quantity selector with +/- buttons

package/seed-templates/saas-landing.md

@@ -0,0 +1,92 @@
+---
+id: saas-landing
+title: Seed Template: SaaS Landing Page
+domain: seed-templates
+category: saas-landing.md
+difficulty: intermediate
+tags: [bottom, gates, into, landing, page, paste, quality, root]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: SaaS Landing Page
+
+> Use this structure when the product is a SaaS landing / marketing page.
+> The worker should follow this section order and fill each slot.
+
+## Page structure (top → bottom)
+
+```
+┌─────────────────────────────────────────────────┐
+│  Nav: logo (left) · links (center) · CTA (right)│
+├─────────────────────────────────────────────────┤
+│  Hero: headline + subtitle + primary CTA         │
+│  Optional: product screenshot or animation       │
+├─────────────────────────────────────────────────┤
+│  Trust bar: 4-6 monochrome logos, single row     │
+├─────────────────────────────────────────────────┤
+│  Features: 3-column icon + title + description   │
+│  Use declared icon library, NOT emoji            │
+├─────────────────────────────────────────────────┤
+│  Product showcase: screenshot + feature callouts │
+│  Alternate left/right for visual rhythm          │
+├─────────────────────────────────────────────────┤
+│  Testimonials: 2-3 real quotes + avatar + name   │
+├─────────────────────────────────────────────────┤
+│  Pricing: 2-3 tier cards with toggle (if needed) │
+├─────────────────────────────────────────────────┤
+│  FAQ: accordion, 5-8 questions                   │
+├─────────────────────────────────────────────────┤
+│  CTA footer: headline + button + trust note      │
+├─────────────────────────────────────────────────┤
+│  Footer: links · social icons · copyright        │
+└─────────────────────────────────────────────────┘
+```
+
+## CSS skeleton (paste into :root)
+
+```css
+:root {
+  /* Bind these from the UIUX doc's design tokens */
+  --font-heading: /* from uiux */;
+  --font-body: /* from uiux */;
+  --max-width: 1200px;
+  --section-padding-y: 80px;
+  --section-padding-y-mobile: 48px;
+}
+
+.container {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 0 24px;
+}
+
+section {
+  padding: var(--section-padding-y) 0;
+}
+
+@media (max-width: 768px) {
+  section { padding: var(--section-padding-y-mobile) 0; }
+}
+```
+
+## Quality gates
+
+### P0 (must pass before preview gate)
+- [ ] Page loads without JS errors
+- [ ] Navigation links scroll to correct sections
+- [ ] CTA buttons have hover + focus states
+- [ ] Mobile responsive (test at 360px width)
+- [ ] No emoji as icons anywhere
+
+### P1 (should pass)
+- [ ] Trust bar logos are monochrome (not colorful)
+- [ ] Feature icons from declared library
+- [ ] Testimonial avatars are properly sized circles
+- [ ] Pricing cards have visual hierarchy (recommended plan highlighted)
+- [ ] FAQ accordion works (open/close)
+
+### P2 (polish)
+- [ ] Dark mode works via prefers-color-scheme
+- [ ] Scroll-triggered section reveal animation
+- [ ] Smooth scroll between sections
+- [ ] Loading skeleton for any async content

package/seed-templates/settings-page.md

@@ -0,0 +1,51 @@
+---
+id: settings-page
+title: Seed Template: Settings / Account Page
+domain: seed-templates
+category: settings-page.md
+difficulty: intermediate
+tags: [gates, page, quality, seed-templates, settings, structure]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Seed Template: Settings / Account Page
+
+> Use for user profile, preferences, billing, team management.
+> Recommended design direction: Modern Minimal.
+
+## Page structure
+
+```
+┌──────┬──────────────────────────────────────────┐
+│ Side │  Settings header: "Settings" + save btn   │
+│ nav  ├──────────────────────────────────────────┤
+│      │  Section: Profile                         │
+│ tabs │  ┌ Avatar upload ┐ Name ┐ Email ┐ Bio    │
+│      ├──────────────────────────────────────────┤
+│      │  Section: Preferences                     │
+│      │  Theme toggle · Language · Timezone        │
+│      ├──────────────────────────────────────────┤
+│      │  Section: Security                        │
+│      │  Change password · MFA toggle · Sessions   │
+│      ├──────────────────────────────────────────┤
+│      │  Section: Billing (if applicable)          │
+│      │  Current plan · Usage · Payment method     │
+│      ├──────────────────────────────────────────┤
+│      │  Danger zone: Delete account               │
+└──────┴──────────────────────────────────────────┘
+```
+
+## Quality gates
+
+### P0
+- [ ] Side navigation highlights active section
+- [ ] Form fields have labels and validation
+- [ ] Save button shows loading + success feedback
+- [ ] Danger zone is visually distinct (red border or background)
+- [ ] Mobile: side nav becomes top tabs or accordion
+
+### P1
+- [ ] Avatar upload with preview
+- [ ] Theme toggle instantly switches light/dark
+- [ ] Password change requires current password
+- [ ] Form dirty detection (unsaved changes warning)

package/testing/01-standards/test-strategy-and-layering.md

@@ -0,0 +1,83 @@
+---
+id: test-strategy-and-layering
+title: 测试策略与分层规范（商业级必读）
+domain: testing
+category: 01-standards
+difficulty: intermediate
+tags: [测试策略, 测试金字塔, 单元测试, 集成测试, e2e, 分层测试, test-double, coverage, aaa, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 测试策略与分层规范（商业级必读）
+
+> 商业级项目必须有自动化测试，且**按架构分层去测**——不同层测不同东西，比例呈金字塔。不写测试、或全堆在 e2e、或测实现细节，都是不合格。
+
+## 1. 测试金字塔（比例）
+
+```
+        /\        E2E（少量，关键业务流）         慢、脆、贵
+       /  \       Integration（适量，服务+仓储+真DB）
+      /____\      Unit（大量，领域逻辑/纯函数）    快、稳、便宜
+```
+
+- **大量单元测试**（毫秒级、无 IO）+ **适量集成测试** + **少量端到端**。倒金字塔（一堆 e2e、几乎没单测）是反模式：慢、脆、定位难。
+
+## 2. 各层测什么（对应分层架构）
+
+| 层 | 测什么 | 类型 |
+|---|---|---|
+| 领域层(entity/VO/纯函数) | 业务规则、不变量、状态机、计算 | 单元（无 mock，纯内存）|
+| 应用层(service/use-case) | 用例编排、事务、错误路径；mock 掉 repository/gateway 接口 | 单元/集成 |
+| 基础设施层(repository) | 真实读写、映射、查询正确性 | 集成（真实 DB，用 testcontainers/内存库）|
+| 接口层(controller/API) | 路由、校验、状态码、错误信封、鉴权 | 集成/契约 |
+| 关键业务流 | 注册→下单→支付 等端到端 happy + 关键失败 | E2E |
+
+## 3. 写法规范
+
+- **AAA / Given-When-Then**：准备(Arrange)→执行(Act)→断言(Assert)，结构清晰。
+- 一个测试只验**一个行为**；测试名说清"在什么条件下、做什么、期望什么"。
+- 测**行为/契约**，不测私有实现细节（否则重构就红）。
+- 覆盖**正常 + 边界 + 错误**路径，不只 happy path。
+- 测试相互独立、可任意顺序、可并行；不依赖执行顺序或共享可变状态。
+- 用测试替身（test double）替换外部依赖：mock 接口、stub 返回、fake 内存实现；不要在单测里打真网络/真第三方。
+
+## 4. 数据与环境
+
+- 集成测试用一次性真实依赖（testcontainers / 内存 Postgres / sqlite），每个用例自带数据、跑完清理，不污染。
+- 不依赖生产/共享测试库；不依赖"先跑某个测试"。
+- 时间、随机、UUID 等不确定源要可注入/可固定，避免 flaky。
+
+## 5. 覆盖率与质量门
+
+- 关注**关键路径覆盖**（业务核心、钱/权限相关）而非盲目追 100% 行覆盖。
+- 合理目标：领域/服务层高覆盖（如 ≥80%），整体设阈值并在 CI 卡住。
+- 覆盖率是下限不是目标；高覆盖 + 烂断言 = 假安全。
+
+## 6. CI 集成
+
+- 每次 PR/push 自动跑 lint + 单元 + 集成；e2e 在合并前或 nightly。
+- 测试失败必须**阻断合并**；flaky 测试要修或隔离，不允许"重跑就过"长期存在。
+- 测试要快（单测整套秒级），慢测试拆分/并行。
+
+## 7. 反模式（出现即不合格）
+
+- 没有自动化测试，或只有手测。
+- 倒金字塔：大量 e2e、几乎无单测。
+- 测私有实现细节，一重构全红。
+- 单测里打真网络/真数据库/真第三方。
+- 只测 happy path，不测错误与边界。
+- flaky 测试长期"重跑就过"；测试相互依赖、有顺序。
+- 为凑覆盖率写无断言/弱断言的"假测试"。
+
+## 8. 最低交付 checklist
+
+- [ ] 金字塔结构：单元为主、集成适量、e2e 少量覆盖关键流。
+- [ ] 领域逻辑有单测；服务层用例 mock 依赖后测编排与错误；repository 用真 DB 集成测。
+- [ ] API 层测状态码/校验/错误信封/鉴权。
+- [ ] AAA 结构、一测一行为、覆盖正常+边界+错误。
+- [ ] 测试独立、可并行、无 flaky；外部依赖用替身或一次性容器。
+- [ ] CI 自动跑且失败阻断合并；关键路径覆盖达阈值。
+
+---
+**参考**：测试金字塔（Mike Cohn / Martin Fowler）、Test Doubles（Fowler）、testcontainers、AAA/GWT。