@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/phases/deliver/rules.md

@@ -0,0 +1,61 @@
+# Deliver Rules (DLV-*) + Stack Rules (STK-*)
+
+## DLV-001: Unified Stack Preview Before Production
+**Severity:** MUST
+**Description:** Every release MUST deploy as unified stack preview with per-component e2e + cross-stack e2e passing before production.
+**Valid:** `deploy_stack --preview` → `pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL`.
+**Invalid:** Deploying only one component to preview.
+
+## DLV-002: Production Approval Gate
+**Severity:** MUST
+**Description:** Production deployment requires explicit human approval reviewing per-component e2e, cross-stack e2e, staging smoke, and contract-diff.md.
+**Valid:** Human reviews all reports and explicitly approves.
+**Invalid:** Automated production deployment triggered solely by test pass.
+
+## DLV-003: Stack BVT Validation
+**Severity:** MUST
+**Description:** After production deploy, BVT MUST run against the stack. Failure triggers automatic stack rollback.
+**Valid:** `bvt ${PRODUCTION_URL}` → fail → `deploy_stack --rollback`.
+**Invalid:** BVT skip or success with errors.
+
+## DLV-004: Per-Component Preview URL Isolation
+**Severity:** MUST
+**Description:** e2e tests run against dynamic preview URLs, never hardcoded production URLs.
+**Valid:** `pytest apps/web/tests/e2e/ --preview-url $WEB_URL`.
+**Invalid:** Hardcoded `https://prod.example.com` in tests.
+
+## STK-001: Component Scope Declaration
+**Severity:** MUST
+**Description:** Every spec delta, design doc, task list MUST declare `affects:`.
+**Valid:** `affects: [web, backend, contracts]`.
+**Invalid:** Missing `affects` declaration.
+
+## STK-002: Cross-Component Tasks Have Edges
+**Severity:** MUST
+**Description:** Tasks consuming a contract MUST have explicit `depends_on` edge to producing task.
+**Valid:** `depends_on: [int-contract-auth-login, be-login-endpoint]`.
+**Invalid:** Implicit dependency with no DAG edge.
+
+## STK-003: Cross-Stack E2E Mandatory for ≥2 Components
+**Severity:** MUST
+**Description:** Changes affecting ≥2 components MUST have cross-stack e2e testing real flow between components.
+**Valid:** Real web client against real backend preview.
+**Invalid:** Cross-stack test that mocks the other component.
+
+## STK-004: Unified Stack Deploy
+**Severity:** MUST
+**Description:** Shared environments MUST use `deploy_stack` orchestrator, not per-component ad-hoc deploys.
+**Valid:** `deploy_stack --preview` deploys all components.
+**Invalid:** Ad-hoc per-component deploy to shared preview.
+
+## STK-005: Cross-Component Build Config Injection
+**Severity:** MUST
+**Description:** All client builds receive `BACKEND_URL` as build-time env var, never hardcoded.
+**Valid:** `pnpm --filter web build --env BACKEND_URL=$BACKEND_URL`.
+**Invalid:** Hardcoded URLs in `.env.production`.
+
+## STK-006: Stack-Level Rollback
+**Severity:** MUST
+**Description:** Rollback is stack operation. Entire previous stable version reverts together.
+**Valid:** `deploy_stack --rollback v1.2.3` reverts all components.
+**Invalid:** Rolling back only backend while leaving clients on new version.

package/ai-dlc-skill/phases/plan/design_system/accessibility.md

@@ -0,0 +1,268 @@
+# Accessibility — 可访问性规范
+
+所有 UI 组件必须符合 WCAG 2.1 AA 标准，确保残障人士可正常使用。
+
+## WCAG 2.1 核心标准
+
+| 原则 | 级别 | 要求 |
+|------|------|------|
+| **可感知** | A | 文本替代、媒体字幕、适应性内容 |
+| **可操作** | A | 键盘可访问、无陷阱、足够时间 |
+| **可理解** | A | 语言可读、可预测、输入帮助 |
+| **健壮** | A | 兼容性、状态可访问性 |
+
+### 对比度要求
+
+| 内容类型 | AA 标准 | AAA 标准 |
+|----------|---------|----------|
+| 正常文本 (<18px / <14px bold) | 4.5:1 | 7:1 |
+| 大文本 (≥18px / ≥14px bold) | 3:1 | 4.5:1 |
+| UI 组件/图形 | 3:1 | 3:1 |
+
+### 字体大小规范
+
+```css
+/* 最小可访问字体 */
+--font-size-min-accessible: 14px;  /* 正常文本 */
+--font-size-min-accessible-large: 18px;  /* 大文本 */
+```
+
+## 焦点管理 (Focus Management)
+
+### Focus Ring 规范
+
+```css
+/* 所有可交互元素的 focus ring */
+:focus-visible {
+  outline: 2px solid var(--color-border-focus);
+  outline-offset: 2px;
+}
+
+/* 移除默认 focus ring */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+### 焦点顺序
+
+```markdown
+### Tab 顺序规则
+1. 逻辑顺序: 从左到右，从上到下
+2. 焦点顺序必须与视觉顺序一致
+3. 模态弹窗必须捕获焦点 (focus trap)
+4. 关闭弹窗后焦点需返回触发元素
+5. 跳过链接 (#main-content) 必须是第一个可聚焦元素
+```
+
+### 焦点陷阱 (Focus Trap)
+
+```typescript
+// Modal / Dialog 必须实现焦点陷阱
+const focusTrap = (container: HTMLElement) => {
+  const focusable = container.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const first = focusable[0] as HTMLElement;
+  const last = focusable[focusable.length - 1] as HTMLElement;
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key !== 'Tab') return;
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  };
+
+  container.addEventListener('keydown', handleKeyDown);
+  first?.focus();
+};
+```
+
+## 键盘导航 (Keyboard Navigation)
+
+### 标准键盘交互
+
+| Key | 组件 | 行为 |
+|-----|------|------|
+| Tab | 全局 | 移动到下一个可聚焦元素 |
+| Shift+Tab | 全局 | 移动到上一个可聚焦元素 |
+| Enter | Button / Link | 激活 |
+| Space | Button / Checkbox | 激活 / 切换 |
+| Escape | Modal / Dropdown | 关闭 |
+| Arrow Up/Down | Menu / Select | 上下导航 |
+| Arrow Left/Right | Tab / Slider | 左右切换 |
+
+### 可交互元素最小集合
+
+```markdown
+必须可键盘操作:
+- [ ] 所有 Button
+- [ ] 所有 Link
+- [ ] 所有 Input / Textarea
+- [ ] 所有 Select
+- [ ] 所有 Checkbox / Radio / Switch
+- [ ] 所有 MenuItem
+- [ ] 所有 Modal / Dialog
+- [ ] 所有 Tooltip (可通过键盘触发)
+```
+
+## ARIA 规范
+
+### ARIA 属性速查
+
+| 属性 | 用途 | 示例 |
+|------|------|------|
+| aria-label | 为元素提供可访问名称 | `<button aria-label="关闭">X</button>` |
+| aria-describedby | 关联描述元素 | `<input aria-describedby="hint-email">` |
+| aria-required | 标记必填 | `<input aria-required="true">` |
+| aria-invalid | 标记错误 | `<input aria-invalid="true">` |
+| aria-disabled | 标记禁用 | `<button aria-disabled="true">` |
+| aria-expanded | 展开/收起状态 | `<button aria-expanded="false">` |
+| aria-hidden | 隐藏于屏幕阅读器 | `<span aria-hidden="true">icon</span>` |
+| aria-live | 动态区域 | `<div aria-live="polite">result</div>` |
+| aria-busy | 加载状态 | `<div aria-busy="true">` |
+| aria-current | 当前项 | `<a aria-current="page">Home</a>` |
+| role | 语义角色 | `<div role="dialog">` |
+
+### 常见 ARIA 模式
+
+```markdown
+### Button vs Link
+- Button: 执行操作 (onClick) → <button> 或 <div role="button">
+- Link: 导航 → <a href>
+
+### Form Field
+<input
+  id="email"
+  type="email"
+  aria-required="true"
+  aria-invalid="false"
+  aria-describedby="email-hint email-error"
+/>
+<span id="email-hint">用于接收验证码</span>
+<span id="email-error" aria-live="polite"></span>
+
+### Modal/Dialog
+<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">确认删除</h2>
+  <p>确定要删除此项吗？</p>
+  <button>取消</button>
+  <button>确定</button>
+</div>
+
+### Tabs
+<div role="tablist">
+  <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
+</div>
+<div role="tabpanel" id="panel-1">Content 1</div>
+<div role="tabpanel" id="panel-2" hidden>Content 2</div>
+```
+
+## 屏幕阅读器支持
+
+### 必需内容
+
+```markdown
+### 图片
+- 有意义图片: alt="描述内容"
+- 装饰图片: alt="" (空)
+
+### 图标
+- 纯装饰图标: aria-hidden="true"
+- 有意义图标: aria-label 或可见文字
+
+### 动态内容
+- 非紧急更新: aria-live="polite"
+- 紧急警告: aria-live="assertive"
+- Toast: role="status" 或 role="alert"
+
+### 表单错误
+- 错误提示必须关联到对应输入框 (aria-describedby)
+- 错误必须可被屏幕阅读器即时读取
+```
+
+### 辅助技术测试清单
+
+```markdown
+- [ ] NVDA + Chrome 测试
+- [ ] VoiceOver + Safari 测试
+- [ ] JAWS + Chrome 测试 (可选)
+```
+
+## 运动与动画
+
+### 减少运动 (Reduce Motion)
+
+```css
+/* 尊重用户减少动画偏好 */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### 动画规范
+
+| 类型 | 最大时长 | 缓动 |
+|------|----------|------|
+| 微交互 | 100-200ms | ease-out |
+| 状态切换 | 200-300ms | ease-in-out |
+| 展开/折叠 | 300-500ms | ease-in-out |
+| 页面过渡 | 300-500ms | ease-in-out |
+
+## 色彩相关
+
+### 不应仅依赖颜色传达信息
+
+```markdown
+❌ 错误: 红色边框表示错误
+✅ 正确: 红色边框 + 错误图标 + 错误文字 + aria-invalid
+
+❌ 错误: 灰色表示禁用
+✅ 正确: 灰色 + aria-disabled="true" + 鼠标事件禁用
+```
+
+## 移动端触摸
+
+```markdown
+### 触摸目标尺寸
+- 最小: 44x44 CSS pixels (Apple) / 48x48 dp (Material Design)
+- 推荐: 48x48 CSS pixels
+
+### 触摸间距
+- 相邻可触摸元素间距 ≥ 8px
+- 防止误触相邻元素
+```
+
+## 法规与标准
+
+| 标准 | 要求级别 |
+|------|----------|
+| WCAG 2.1 (A) | 强制 (MUST) |
+| WCAG 2.1 (AA) | 推荐 (SHOULD) |
+| WCAG 2.1 (AAA) | 可选 (MAY) |
+| EN 301 549 (欧盟) | 政府采购 |
+| Section 508 (美国) | 政府/公共机构 |
+
+## 评审清单
+
+- [ ] 所有文本对比度 ≥ 4.5:1 (AA)
+- [ ] 所有 UI 组件对比度 ≥ 3:1 (AA)
+- [ ] 所有交互元素可通过键盘操作
+- [ ] 所有图标按钮有 aria-label
+- [ ] 所有表单有错误提示和关联
+- [ ] 模态框实现焦点陷阱
+- [ ] 支持 prefers-reduced-motion
+- [ ] 触摸目标 ≥ 44x44px
+- [ ] 通过 axe-core 自动检测
+- [ ] 通过屏幕阅读器手动测试

package/ai-dlc-skill/phases/plan/design_system/atomic_design.md

@@ -0,0 +1,341 @@
+# Atomic Design — 原子化设计分层
+
+Atomic Design 是 UI 组件的分层方法论，将界面拆解为 5 个层级：Atom → Molecule → Organism → Template → Page。
+
+## 层级总览
+
+```
+Page
+  └── Template
+        └── Organism
+              └── Molecule
+                    └── Atom
+```
+
+| 层级 | 定义 | 复杂度 | 可复用性 |
+|------|------|--------|----------|
+| **Atom** | 最小单元，不可拆分 | 低 | 全局复用 |
+| **Molecule** | 2-3 个 Atom 简单组合 | 低 | 全局复用 |
+| **Organism** | 多个组件复杂组合 | 中 | 跨功能复用 |
+| **Template** | 页面骨架布局 | 中 | 同类型页面复用 |
+| **Page** | 具体页面实例 | 高 | 特定页面 |
+
+---
+
+## Atom — 原子
+
+**定义**: 最小 UI 单元，不可再拆分，拥有自己的 markup 和样式。
+
+### 类型
+
+| 类型 | 示例组件 |
+|------|----------|
+| **基础** | Button, Input, Textarea, Select, Checkbox, Radio, Switch |
+| **显示** | Badge, Tag, Avatar, Progress, Tooltip |
+| **导航** | Tab, Breadcrumb, Pagination |
+| **媒体** | Icon, Image, Video |
+| **反馈** | Spinner, Skeleton, Alert |
+
+### Atom 规范
+
+```markdown
+## Button
+
+### Variants
+- primary: 主操作按钮
+- secondary: 次级操作
+- ghost: 透明背景
+- danger: 危险操作
+
+### Sizes
+- sm: 高度 32px, font-size xs
+- md: 高度 40px, font-size sm (default)
+- lg: 高度 48px, font-size base
+
+### States
+- default: 默认
+- hover: 悬停
+- active: 按下
+- focus: 聚焦 (focus ring)
+- disabled: 禁用
+- loading: 加载中
+
+### Props (示例)
+- variant: 'primary' | 'secondary' | 'ghost' | 'danger'
+- size: 'sm' | 'md' | 'lg'
+- disabled: boolean
+- loading: boolean
+- leftIcon: ReactNode
+- rightIcon: ReactNode
+- fullWidth: boolean
+```
+
+### 设计要求
+
+- 必须可通过 CSS 变量覆盖外观
+- 必须支持键盘聚焦状态 (focus ring)
+- 尺寸需符合 spacing token
+- 文字颜色需满足 WCAG 对比度要求
+
+---
+
+## Molecule — 分子
+
+**定义**: 2-3 个 Atom 组合，形成具有单一功能职责的组件。
+
+### 类型
+
+| 类型 | 示例组件 |
+|------|----------|
+| **表单** | SearchBar (Input + Button), FormField (Label + Input + ErrorText), DatePicker |
+| **卡片** | CardHeader (Avatar + Title + Subtitle), CardFooter (Meta + Action) |
+| **数据** | DataRow (Label + Value), StatCard (Icon + Value + Label) |
+| **导航** | NavItem (Icon + Text + Badge), BreadcrumbItem |
+| **媒体** | ImageWithCaption (Image + Caption), VideoPlayer |
+
+### Molecule 规范
+
+```markdown
+## SearchBar
+
+### Composition
+- Input (Atom)
+- Button (Atom)
+- 可选: Dropdown for filter
+
+### States
+- default: 默认
+- focus: Input 聚焦
+- loading: 搜索中 (Button loading)
+- results: 显示结果
+- empty: 无结果
+
+### Props
+- placeholder: string
+- onSearch: (value: string) => void
+- isLoading: boolean
+- value: string
+
+### 行为
+- Enter 触发搜索
+- 搜索时显示 loading 状态
+- 清空按钮在有内容时显示
+```
+
+### 设计要求
+
+- Molecule 应有明确的单一职责
+- 内部 Atom 状态需联动（如 Input 禁用时 Button 也禁用）
+- 可接收外部样式覆盖 (className / style props)
+
+---
+
+## Organism — 有机体
+
+**定义**: 多个 Molecule/Atom 组合，形成独立的功能区块，可跨功能复用。
+
+### 类型
+
+| 类型 | 示例组件 |
+|------|----------|
+| **布局** | Header, Sidebar, Footer |
+| **数据** | DataTable, ListView, CardGrid |
+| **表单** | LoginForm, RegisterForm, FilterPanel |
+| **导航** | MainNav, TabPanel |
+| **反馈** | ToastContainer, Modal, ConfirmDialog |
+
+### Organism 规范
+
+```markdown
+## DataTable
+
+### Composition
+- TableHeader (Organism): 排序按钮 + 列选择
+- TableRow (Molecule): 多列数据
+- TableFooter (Organism): 分页信息
+- 内部状态: columns, sortConfig, selectedRows
+
+### States
+- loading: 骨架屏
+- empty: 空状态插画
+- error: 错误提示
+- populated: 正常数据
+
+### Props
+- columns: Column[]
+- data: T[]
+- sortable: boolean
+- selectable: boolean
+- pagination: PaginationConfig
+- onSort: (key: string, dir: 'asc' | 'desc') => void
+- onSelect: (rows: T[]) => void
+
+### 可复用部分
+- TableHeader 可单独作为 Organism
+- TableRow 可单独作为 Molecule
+```
+
+### 设计要求
+
+- Organism 应是独立功能块，不依赖父级数据
+- 内部状态需合理管理 (local state vs external state)
+- 必须处理空状态、加载状态、错误状态
+
+---
+
+## Template — 模板
+
+**定义**: 页面骨架布局，定义内容区域的结构和位置关系，不含具体业务数据。
+
+### 类型
+
+| 类型 | 用途 |
+|------|------|
+| **ListTemplate** | 列表页模板 (Header + Filter + Table + Pagination) |
+| **DetailTemplate** | 详情页模板 (Header + Content + Sidebar) |
+| **FormTemplate** | 表单页模板 (Header + Form + Actions) |
+| **DashboardTemplate** | 仪表盘模板 (Header + StatsGrid + Charts) |
+| **AuthTemplate** | 认证页模板 (CenterCard + Logo + Form) |
+
+### Template 规范
+
+```markdown
+## ListTemplate
+
+### Layout Structure
+┌─────────────────────────────────────┐
+│ Header: Title + Actions              │
+├─────────────────────────────────────┤
+│ FilterBar: Search + Filters + Sort  │
+├─────────────────────────────────────┤
+│ DataTable / ListView                │
+│ (内容区域，可滚动)                    │
+├─────────────────────────────────────┤
+│ Pagination                          │
+└─────────────────────────────────────┘
+
+### 占位区域
+- Header: 高度 64px, 固定
+- FilterBar: 高度 56px
+- Pagination: 高度 48px
+- 内容区: flex-1, 可滚动
+
+### Responsive
+- Desktop: 完整布局
+- Tablet: FilterBar 可折叠
+- Mobile: 单列列表
+```
+
+### 设计要求
+
+- Template 只定义布局结构，不含业务逻辑
+- 必须支持响应式断点
+- 主要内容区域需可滚动
+
+---
+
+## Page — 页面
+
+**定义**: Template 的具体实例，填充真实数据和业务逻辑。
+
+### 类型
+
+| 类型 | 示例 |
+|------|------|
+| **业务页面** | UserListPage, ProductDetailPage, OrderPage |
+| **认证页面** | LoginPage, RegisterPage, ForgotPasswordPage |
+| **设置页面** | AccountSettingsPage, NotificationSettingsPage |
+| **错误页面** | NotFoundPage, ErrorPage |
+
+### Page 规范
+
+```markdown
+## UserListPage
+
+### Uses Template
+- ListTemplate
+
+### Data Binding
+- Header: 动态标题 "用户管理"
+- FilterBar: 用户状态筛选 (全部/活跃/禁用)
+- DataTable: 用户列表数据
+- Pagination: 总页数 100
+
+### State Management
+- URL state: ?page=1&status=active&search=xxx
+- Local state: 选中行、弹窗可见性
+- Server state: 用户列表 (React Query / SWR)
+
+### Side Effects
+- 页面加载时获取数据
+- 筛选变化时重置页码并刷新
+- 删除用户后刷新列表
+
+### Routes
+- /users (列表)
+- /users/:id (详情)
+- /users/new (新建)
+```
+
+### 设计要求
+
+- Page 是路由级别的组件
+- Page 负责数据获取和业务逻辑，布局委托给 Template
+- Page 需处理 SEO (metadata)、权限控制
+
+---
+
+## 目录结构约定
+
+```
+src/
+├── components/
+│   ├── atoms/           # Atom 组件
+│   │   ├── Button/
+│   │   ├── Input/
+│   │   └── ...
+│   ├── molecules/       # Molecule 组件
+│   │   ├── SearchBar/
+│   │   ├── FormField/
+│   │   └── ...
+│   ├── organisms/       # Organism 组件
+│   │   ├── Header/
+│   │   ├── DataTable/
+│   │   └── ...
+│   └── templates/       # Template 组件
+│       ├── ListTemplate/
+│       ├── DetailTemplate/
+│       └── ...
+├── pages/               # Page 组件 (按路由组织)
+│   ├── UserListPage/
+│   └── ProductDetailPage/
+```
+
+---
+
+## 设计决策规则
+
+| 场景 | 决策 |
+|------|------|
+| 新组件是 Atom 还是 Molecule？ | 看是否需要多个 Atom 组合才能完成功能 |
+| 新组件是 Molecule 还是 Organism？ | 看是否有多个功能区块 / 是否独立存在 |
+| 是 Organism 还是 Template？ | Organism 是功能块，Template 是布局结构 |
+| 是 Template 还是 Page？ | Template 无业务数据，Page 是具体实例 |
+| 何时新建组件？ | 发现重复 UI 模式时抽取，而非预判 |
+| 组件复用边界？ | 同一功能类型内复用，跨类型不强行复用 |
+
+---
+
+## 评审清单
+
+新组件创建时检查：
+
+- [ ] 属于正确的原子层级
+- [ ] 有对应的 `ComponentName.stories.tsx` (Storybook)
+- [ ] 有对应的 `ComponentName.test.tsx` (Vitest)
+- [ ] 支持 Design Tokens (CSS 变量)
+- [ ] 支持深色模式
+- [ ] 有完整的 Props TypeScript 类型
+- [ ] 有必要的 ARIA 属性
+- [ ] 处理了 disabled / loading / error / empty 状态
+- [ ] 单元测试覆盖率 ≥ 80%