@captain_z/zsk-skills 0.1.0

package/frontend/security-web/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: zsk:security-web
+description: Web frontend security — XSS (React default escape +
+  dangerouslySetInnerHTML red line + DOMPurify exception), URL protocol
+  whitelist, Storage red lines (no sensitive data in Local/SessionStorage), CSRF
+  token integration, console log scrubbing for production, CSP meta/header
+  consumption, SRI for third-party scripts, clickjacking (frame-ancestors
+  awareness), postMessage origin checks. Frontend UI is the convenience defense;
+  backend is final.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../i18n/SKILL.md
+  - ../../quality/security-owasp/SKILL.md
+triggers:
+  - dangerouslySetInnerHTML
+  - XSS React
+  - DOMPurify
+  - LocalStorage sensitive
+  - CSRF token
+  - console production
+  - CSP frontend
+  - SRI
+  - postMessage origin
+  - clickjacking frontend
+---
+
+# Security Web · Web 前端安全红线
+
+> **范围**：React / Web **前端专属**安全实现 — XSS / URL / Storage / CSRF / console / CSP / SRI / postMessage
+> **原则层**（OWASP Top 10、CVE 响应、供应链）→ [`quality/security-owasp`](../../quality/security-owasp/SKILL.md)
+> **核心认知**：**前端是便利性防线，后端是最终防线**。前端不能替代后端鉴权，但必须防止自身成为攻击入口。
+
+## 1. XSS 防护
+
+### React 默认已转义
+
+JSX 插值自动 HTML 转义，**正常使用不会产生 XSS**：
+
+```tsx
+<div>{userInput}</div>  // 安全：自动转义
+```
+
+### 红线：`dangerouslySetInnerHTML`
+
+**默认禁用**。需要时必须：
+
+1. **ADR 记录**：为什么不能用普通 JSX
+2. **内容白名单化**：`DOMPurify.sanitize(html)`
+3. **内容源可信**：来自受信后端（经过校验）而非用户输入
+
+```tsx
+import DOMPurify from 'dompurify';
+
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(richText) }} />
+```
+
+### 其他 XSS 入口
+
+- ❌ `element.innerHTML = userInput`
+- ❌ `document.write(userInput)`
+- ❌ `eval(...)` / `new Function(...)`（项目 lint 必须禁用 `no-eval` / `no-new-func`）
+
+### URL / 跳转协议白名单
+
+```tsx
+// ❌ 不校验
+<a href={userUrl}>link</a>
+
+// ✅ 校验
+function isSafeUrl(url: string): boolean {
+  try {
+    const u = new URL(url, window.location.origin);
+    return ['http:', 'https:', 'mailto:'].includes(u.protocol);
+  } catch {
+    return false;
+  }
+}
+
+<a href={isSafeUrl(userUrl) ? userUrl : '#'}>link</a>
+```
+
+**禁止 `javascript:` 协议**。`data:` URL 仅限预设的 MIME（如图片 base64）。
+
+### `window.location = userInput` 必须白名单
+
+```ts
+const ALLOWED_HOSTS = ['example.com', 'cdn.example.com'];
+function safeRedirect(url: string) {
+  const u = new URL(url, window.location.origin);
+  if (ALLOWED_HOSTS.includes(u.host)) window.location.href = u.toString();
+}
+```
+
+## 2. Storage 红线
+
+### 禁止写入的字段
+
+以下**绝对不进** `localStorage` / `sessionStorage`：
+
+- ❌ 密码 / PIN / 2FA 密钥
+- ❌ Access Token / Refresh Token（除非业务明确评估过 + ADR；**优先用 HttpOnly Cookie**）
+- ❌ 身份证号 / 银行卡号 / 手机号（明文）
+- ❌ 用户私密内容（IM 消息明文 / 草稿敏感内容）
+- ❌ 后端返回的 SSO session ID
+
+### 原因
+
+- Storage 可被任何同源脚本读取（含被注入的第三方脚本 / XSS payload）
+- 浏览器跨 tab 共享，存活周期长
+- 无 `HttpOnly` 保护
+
+### 合规用法
+
+- UI 偏好（主题 / 语言 / 侧栏折叠）
+- 非敏感草稿（若需加密存储，用 `IndexedDB` + Web Crypto）
+- **最多缓存 ID**（`userId` 级别），详情数据走后端
+
+### 离开登录态清理
+
+```ts
+// 登出时
+localStorage.removeItem('app:user-pref');
+sessionStorage.clear();
+// Cookie 由后端 Set-Cookie Max-Age=0 清理
+```
+
+## 3. CSRF 防护
+
+### 前端侧职责
+
+- 所有修改类请求（POST / PUT / DELETE / PATCH）自动注入 CSRF Token
+- 建议统一封装在 `{{config.paths.services_entry}}`，业务代码不手写
+
+```ts
+// services/request.ts
+request.interceptors.request.use((config) => {
+  if (['post', 'put', 'delete', 'patch'].includes(config.method ?? '')) {
+    config.headers['X-CSRF-Token'] = getCsrfToken(); // 从 Cookie / meta / 接口获取
+  }
+  return config;
+});
+```
+
+### Cookie 配合
+
+后端 Set-Cookie 时：`SameSite=Lax` 或 `Strict` + `Secure` + `HttpOnly`（登录态 Cookie）。
+
+前端不能写 `HttpOnly`，只能要求后端配置到位。
+
+## 4. console 脱敏
+
+### 生产环境红线
+
+- ❌ `console.log`（lint 禁用 `no-console`，允许 `warn` / `error`）
+- ❌ 在 warn/error 中打印明文：密码 / Token / PII
+
+### 脱敏工具
+
+```ts
+// utils/scrub.ts
+const SENSITIVE_KEYS = /^(password|token|pwd|secret|authorization|cookie|session)/i;
+export function scrub(obj: unknown): unknown {
+  if (typeof obj !== 'object' || !obj) return obj;
+  return Object.fromEntries(
+    Object.entries(obj).map(([k, v]) =>
+      SENSITIVE_KEYS.test(k) ? [k, '***'] : [k, scrub(v)]
+    )
+  );
+}
+
+// 使用
+console.error('Request failed', scrub(payload));
+```
+
+### 错误上报同样规则
+
+Sentry / 自研上报前必须经脱敏过滤器；`breadcrumbs` 里不能有原始请求体。
+
+## 5. CSP（Content Security Policy）
+
+CSP 主要由**后端 header** 或 `<meta>` 设置。前端责任：不写违反 CSP 的代码（内联 `<script>` / `<style>` / `eval` / 内联 `style="..."` 属性，除非 CSP 允许 nonce / hash）；第三方脚本（分析 / 地图 / 客服）需加入白名单并在 PR 描述声明域名。
+
+**推荐严格 CSP**：`default-src 'self'`；`script-src 'self' 'nonce-{random}'`；`style-src 'self' 'nonce-{random}'`；`img-src 'self' data: https:`；`connect-src 'self' https://api.example.com`；`frame-ancestors 'none'`；`object-src 'none'`；`base-uri 'self'`。
+
+## 6. SRI（Subresource Integrity）
+
+第三方 CDN 脚本 / 样式必须带 SRI：
+
+```html
+<script
+  src="https://cdn.example.com/lib.js"
+  integrity="sha384-abc..."
+  crossorigin="anonymous"
+></script>
+```
+
+构建工具链（Vite / Webpack）自带生成能力（`vite-plugin-sri` / `webpack-subresource-integrity`）。
+
+## 7. 点击劫持（前端可感知的部分）
+
+**主要防护在后端 header**：`X-Frame-Options: DENY` 或 CSP `frame-ancestors 'none'`。
+
+前端可做：
+
+```ts
+// 顶层脚本（如果被 iframe 嵌入则跳出）
+if (window.top !== window.self) {
+  window.top!.location = window.self.location;
+}
+```
+
+但不如 header 可靠。**主方案是后端 header**，前端这招是兜底。
+
+## 8. postMessage 跨域通信
+
+```ts
+// ❌ 接收方不校验来源
+window.addEventListener('message', (e) => {
+  handlePayload(e.data);  // 任何源都能发
+});
+
+// ✅ 校验 origin
+window.addEventListener('message', (e) => {
+  if (e.origin !== 'https://trusted.example.com') return;
+  if (typeof e.data !== 'object' || e.data === null) return;
+  handlePayload(e.data);
+});
+
+// 发送方
+target.postMessage(payload, 'https://trusted.example.com'); // 不用 '*'
+```
+
+## 9. 表单安全
+
+- **`autocomplete` 属性正确设置**：密码用 `new-password` / `current-password`，信用卡用 `cc-number` 等
+- **不在 URL 查询参数传敏感信息**（会进浏览器历史 / 日志）
+- **文件上传**：前端只做便利校验（`accept` 属性 / MIME 快检），**MIME / 大小 / 病毒扫描必须后端**
+
+## 10. 第三方依赖安全
+
+- Lint `no-restricted-imports` 禁用已知不安全库（项目 SYSTEM-SPEC 配置）
+- 引入前 `npm view {pkg}` 看维护 / 下载量 / 最近发布；**锁版本**（lock file 必须提交）
+- CI `npm audit --audit-level=high`；高危 CVE **24h 内响应**（升级 / 绕过 / 豁免 + ADR）。CVE 响应 SLA 见 [`quality/security-owasp`](../../quality/security-owasp/SKILL.md)
+
+## 11. 生产构建红线
+
+| 项 | 规则 |
+| --- | --- |
+| Source Map | 不上传到公网（仅上报平台私有） |
+| 调试工具 | React DevTools / Redux DevTools 仅 DEV 启用 |
+| 日志 | 生产无 `console.log` |
+| 内联脚本 | 无（除 CSP 允许的 nonce/hash） |
+| 环境变量 | 前端 `VITE_*` / `NEXT_PUBLIC_*` 只能放**非敏感**值 |
+
+### 环境变量误区
+
+```
+❌ VITE_API_SECRET=xxx    # 前端 env 会进 bundle，等于公开
+✅ 敏感值只放后端 env
+```
+
+## 反模式（禁止）
+
+- ❌ `dangerouslySetInnerHTML` 无 DOMPurify / 无 ADR
+- ❌ Token / 密码进 Local/SessionStorage（除非 ADR 评估）
+- ❌ `href={userUrl}` / `window.location = userInput` 不校验协议
+- ❌ 修改类请求不注入 CSRF Token
+- ❌ 生产 `console.log` / 明文打印敏感字段
+- ❌ `postMessage` 不校验 origin
+- ❌ 把 API Secret 放前端 env
+- ❌ 第三方 CDN 脚本无 SRI
+
+## 质量门禁
+
+- [ ] 无新增 `dangerouslySetInnerHTML`（或经 ADR + DOMPurify）
+- [ ] 无敏感字段进 Storage
+- [ ] URL / 跳转有协议白名单
+- [ ] CSRF Token 在 service 层统一注入
+- [ ] 生产 `console.log` 零出现
+- [ ] 日志 / 上报经脱敏
+- [ ] 第三方脚本带 SRI
+- [ ] `postMessage` 校验 origin
+- [ ] `npm audit` 无 high / critical
+- [ ] 环境变量无敏感值暴露前端

package/frontend/spec-frontend/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: zsk:spec-frontend
+description: Frontend component/page spec.md authoring — adds Component Public
+  Contract (Props / Events / TS types), UE state matrix with a11y attributes,
+  UE/MCP reference, and the 6-category Frontend NFR (performance / a11y /
+  security / i18n / compat / observability). Extends the generic zsk:spec
+  framework.
+category: stage
+domain: frontend
+tier: optional
+stage: 2
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../../sdlc/spec/SKILL.md
+  - ../../design-handoff/ue-mcp/SKILL.md
+  - ../design-frontend/SKILL.md
+  - ../a11y-web/SKILL.md
+  - ../i18n/SKILL.md
+  - ../nfr-web/SKILL.md
+  - ../api-contract-ts/SKILL.md
+triggers:
+  - frontend spec
+  - Component Public Contract
+  - Props Event Contract
+  - UE state matrix
+  - frontend NFR six categories
+---
+
+# Stage 2: Spec · Frontend 补丁
+
+> **用途**：当模块是**前端组件 / 页面**时，在 [`zsk:spec`](../../sdlc/spec/SKILL.md) 通用骨架上追加的条款
+> **范围**：Component Public Contract、UE 状态矩阵、UE/MCP 引用、Frontend NFR 六类
+
+## 追加章节（相对 `zsk:spec` 的通用 Feature 模板）
+
+在通用骨架之上追加下面这些章节，最终 `docs/{module}/spec.md` 同时包含两部分。
+
+### A. Component Public Contract
+
+#### A.1 Props
+
+- Props 名称、TS 类型、是否必填、默认值
+- 受控 / 非受控边界（value + onChange / defaultValue）
+- 明确不支持的输入
+
+```ts
+export interface {Module}Props {
+  data: {Module}Node[];
+  selectedId?: string;
+  onSelect?: (id: string, node: {Module}Node) => void;
+  // ...
+}
+```
+
+**禁止**把"Props 以后看实现再补"留到 Design 或 Coding。
+
+#### A.2 Event / Output
+
+- 事件回调签名（参数类型、返回值、副作用）
+- 命名 `on` 前缀（见 [`zsk:react-naming`](../react-naming/SKILL.md)）
+
+```ts
+export interface {Module}ChangeValue {
+  // ...
+}
+```
+
+#### A.3 受控 / 非受控声明
+
+明确组件属于：
+- **受控**（外部 value + onChange）
+- **非受控**（内部 state + defaultValue）
+- **混合**（必须有 `value === undefined ? 内部 : 外部` 兜底）
+
+### B. UI / UE Contract（状态矩阵）
+
+至少覆盖适用项：`loading / empty / error / hover / focus / focus-visible / selected / disabled`
+组件特有：`search-hit` / `search-empty` / `lazy-loading` 等
+
+矩阵列：
+
+| 状态 | 触发条件 | 用户可见表现 | 允许操作 | a11y 属性 |
+| --- | --- | --- | --- | --- |
+
+> a11y 属性参考 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md) 的 aria 表
+
+### C. UE / MCP Context
+
+- Figma 输入 → 引用 `docs/{module}/ue-mcp.md`（[`zsk:ue-mcp`](../../design-handoff/ue-mcp/SKILL.md)），本文件只摘要 URL + Node ID
+- 本节不重复 Figma 细节
+
+### D. API Contract（若涉及后端）
+
+- 引用 `docs/{module}/api-contract.md`（[`zsk:api-contract-ts`](../api-contract-ts/SKILL.md)）
+- 本文件只列用到的 endpoint 与类型名
+- **类型定义不在 spec 写**，由后端生成
+
+### E. Frontend NFR 六类
+
+继承 [`system/nfr-baseline`](../../system/nfr-baseline/SKILL.md)（7 类框架）+ [`frontend/nfr-web`](../nfr-web/SKILL.md)（Web 具体阈值），此处只列偏离项：
+
+| 编号 | 类别 | 要求 | 验证方式 |
+| --- | --- | --- | --- |
+| NFR-1 | 性能 | 首屏 < 500ms；交互响应 < 100ms | Lighthouse |
+| NFR-2 | 可访问性 | WCAG 2.1 AA；键盘导航；aria 完备 | axe |
+| NFR-3 | 安全 | 鉴权、越权校验、敏感字段脱敏 | 手工 + 自动扫描 |
+| NFR-4 | 国际化 | 三语 key 完备、文案长度弹性、RTL 声明 | 三语 diff |
+| NFR-5 | 兼容性 | 浏览器矩阵、响应式断点、最小分辨率 | 浏览器矩阵截图 |
+| NFR-6 | 可观测性 | 错误上报、关键交互埋点 | 埋点样本 |
+
+## Feature 型 frontend spec 完整结构（组合通用 + 本文件）
+
+1. 模块映射与事实源 _(zsk:spec)_
+2. 术语表 _(zsk:spec)_
+3. Why _(zsk:spec)_
+4. 用户故事 _(zsk:spec)_
+5. 功能需求 FR _(zsk:spec)_
+6. 非功能需求 NFR（**本文件 E 节 · 六类**）
+7. **Component Public Contract**（本文件 A 节）
+8. **UI / UE Contract 状态矩阵**（本文件 B 节）
+9. **UE / MCP Context**（本文件 C 节，引用 `ue-mcp.md`）
+10. **API Contract**（本文件 D 节，引用 `api-contract.md`）
+11. 数据模型 _(zsk:spec)_
+12. 行为场景 BDD _(zsk:spec)_
+13. Acceptance Criteria _(zsk:spec)_
+14. Edge Cases & Error Handling _(zsk:spec)_
+15. Impact _(zsk:spec)_
+
+## 质量门禁（前端补丁）
+
+- [ ] Component Public Contract 完整（Props / Event / 受控边界）
+- [ ] UE 状态矩阵已填（含 a11y 属性列）
+- [ ] 有 Figma 输入的模块已关联 `ue-mcp.md`
+- [ ] 有后端接口的模块已关联 `api-contract.md`
+- [ ] Frontend NFR 六类全覆盖（继承或偏离明确）
+- [ ] 禁止"Props 以后看实现再补"
+
+> 通用 spec 门禁（编号 / INVEST / BDD）见 [`zsk:spec`](../../sdlc/spec/SKILL.md)

package/frontend/testing-web/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: zsk:testing-web
+description: Frontend tests for React codebases — full toolchain (Jest/Vitest +
+  React Testing Library + renderHook + user-event + MSW + Playwright + Chromatic
+  + jest-axe), test structure (AAA/GWT), mock strategy (MSW for HTTP, manual for
+  modules), coverage thresholds (new code / global), and the component test
+  template. Implementation layer; cross-stack principles live in
+  quality/testing-pyramid.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-components/SKILL.md
+  - ../a11y-web/SKILL.md
+  - ../api-contract-ts/SKILL.md
+  - ../../quality/testing-pyramid/SKILL.md
+  - ../../sdlc/verify/SKILL.md
+triggers:
+  - Jest Vitest
+  - React Testing Library
+  - MSW mock service worker
+  - Playwright
+  - Chromatic visual regression
+  - jest-axe
+  - user-event
+  - renderHook
+  - coverage threshold
+  - component test template
+---
+
+# Testing Web · 前端测试工具链
+
+> **范围**：React / Web 测试工具链**实现层** — Jest/Vitest / RTL / MSW / Playwright / Chromatic / axe
+> **原则层**（金字塔比例 / AAA / 证据先于断言 / TDD / Bug 置信度）→ [`quality/testing-pyramid`](../../quality/testing-pyramid/SKILL.md)
+> **前置**：本文件假设你已读过原则层
+
+## 1. 工具栈总表
+
+| 层级 | 工具 | 职责 |
+| --- | --- | --- |
+| 测试运行器 | **Jest** 或 **Vitest**（项目选一） | 单元 + 集成 |
+| 组件渲染 | **`@testing-library/react`** | DOM query + render |
+| 用户交互 | **`@testing-library/user-event` v14** | 点击 / 键盘 / 输入（不要用 `fireEvent`） |
+| Hook 测试 | **`renderHook`**（RTL 14+ 已整合） | 独立测 hook |
+| HTTP Mock | **MSW**（Mock Service Worker） | 拦截 network 层，不拦截模块 |
+| E2E | **Playwright** | 真浏览器 / 跨浏览器 / trace |
+| 视觉回归 | **Chromatic**（Storybook）/ Playwright `toHaveScreenshot` | 截图 diff |
+| a11y 自动化 | **`jest-axe`** / `@axe-core/playwright` | axe-core 引擎 |
+| lint a11y | **`eslint-plugin-jsx-a11y`** | 静态规则 |
+
+## 2. 覆盖率目标
+
+| 维度 | 阈值 |
+| --- | --- |
+| 全量语句覆盖 | ≥ `{{config.quality.testing.unit_coverage_min}}`%（通常 70%） |
+| 新增 / 修改代码 | ≥ `{{config.quality.testing.new_code_coverage}}`%（通常 80%） |
+| 分支覆盖 | ≥ 70% |
+| Bugfix 回归测试 | **必须包含能失败的复现测试**（硬门禁） |
+
+**覆盖率不是目的**，AC 到测试的映射才是。覆盖率是最低地板。
+
+## 3. Jest / Vitest 基线配置
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./test/setup.ts'],
+    coverage: { provider: 'v8', reporter: ['text', 'html', 'lcov'],
+      thresholds: { lines: 70, branches: 70, functions: 70, statements: 70 } },
+  },
+});
+```
+
+```ts
+// test/setup.ts — 注入 jest-dom + axe + cleanup
+import '@testing-library/jest-dom/vitest';
+import { expect, afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+import { toHaveNoViolations } from 'jest-axe';
+expect.extend({ toHaveNoViolations });
+afterEach(() => cleanup());
+```
+
+## 4. 组件测试模板
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+
+describe('UserCard', () => {
+  const mockUser = { id: '1', name: 'Alice', email: 'a@x.com' };
+
+  it('renders user name and email', () => {
+    render(<UserCard user={mockUser} />);
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('a@x.com')).toBeInTheDocument();
+  });
+
+  it('calls onSelect when clicked', async () => {
+    const onSelect = vi.fn();
+    const user = userEvent.setup();
+    render(<UserCard user={mockUser} onSelect={onSelect} />);
+    await user.click(screen.getByRole('button', { name: /alice/i }));
+    expect(onSelect).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+**query 优先级**（RTL）：`getByRole` > `getByLabelText` > `getByPlaceholderText` > `getByText` > `getByDisplayValue` > `getByAltText` / `getByTitle` > `getByTestId`（兜底）。
+
+**user-event vs fireEvent**：默认 `user-event`（模拟真实 focus → mousedown → click 链路）；`fireEvent` 仅用于触发特定低级事件（`scroll` 等）。
+
+## 5. Hook 测试
+
+```tsx
+import { renderHook, act } from '@testing-library/react';
+
+it('increments counter', () => {
+  const { result } = renderHook(() => useCounter(0));
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+});
+```
+
+需 Provider 时，`renderHook(() => useX(), { wrapper })` 传 Context Provider 包裹。
+
+## 6. MSW (Mock Service Worker)
+
+**默认 HTTP mock 方案**，network 层拦截，比 mock 模块更接近真实：
+
+```ts
+// test/handlers.ts
+import { http, HttpResponse } from 'msw';
+export const handlers = [
+  http.get('/api/users', () => HttpResponse.json({ items: [], total: 0 })),
+  http.post('/api/users', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: '1', ...body }, { status: 201 });
+  }),
+];
+
+// test/setup.ts
+import { setupServer } from 'msw/node';
+export const server = setupServer(...handlers);
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+每 test 覆盖 handler：`server.use(http.get('/api/users', () => HttpResponse.json({ msg: 'boom' }, { status: 500 })))`。
+
+**禁止手写** `vi.mock('axios' / 'fetch')`（漂移风险 + 难维护）。
+
+## 7. 集成测试（组件 + service + 状态）
+
+```tsx
+it('loads and displays users', async () => {
+  render(
+    <QueryClientProvider client={queryClient}>
+      <UserList />
+    </QueryClientProvider>
+  );
+
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  expect(await screen.findByText('Alice')).toBeInTheDocument();
+  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+});
+```
+
+## 8. a11y 自动化
+
+```tsx
+import { axe } from 'jest-axe';
+
+it('is accessible', async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+**硬门禁**：每个组件测试文件至少一条 axe 断言。配合 [`a11y-web`](../a11y-web/SKILL.md) 的运行时扫描。
+
+## 9. E2E（Playwright）
+
+```ts
+// playwright.config.ts
+export default defineConfig({
+  testDir: './e2e',
+  use: { baseURL: 'http://localhost:5173', trace: 'retain-on-failure',
+         video: 'retain-on-failure', screenshot: 'only-on-failure' },
+  projects: [
+    { name: 'chromium', use: devices['Desktop Chrome'] },
+    { name: 'webkit', use: devices['Desktop Safari'] },
+    { name: 'mobile', use: devices['iPhone 13'] },
+  ],
+});
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('邮箱').fill('user@x.com');
+  await page.getByLabel('密码').fill('password');
+  await page.getByRole('button', { name: /登录/ }).click();
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+**a11y 扫描**：`AxeBuilder({ page }).analyze()` 过滤 `critical` / `serious` 后 `toEqual([])`。
+
+## 10. 视觉回归
+
+**方案一**：Chromatic（Storybook）— 每组件写 stories（各状态），Chromatic 自动截图 + diff。CI 脚本 `chromatic --exit-zero-on-changes`。
+
+**方案二**：Playwright `toHaveScreenshot('name.png', { maxDiffPixelRatio: 0.01 })`。
+
+**纪律**：Bugfix / Refactor 必须视觉回归零差异（见 [`review-frontend`](../review-frontend/SKILL.md) 硬门禁）；差异超阈值 → 修复或 ADR 说明保留。
+
+## 11. Mock 策略总表
+
+| 要 mock 的对象 | 工具 |
+| --- | --- |
+| HTTP 请求 | **MSW**（默认） |
+| 第三方 SDK 的行为 | `vi.mock('...')` + `vi.fn()` |
+| 浏览器 API（IntersectionObserver / matchMedia） | 在 `setup.ts` 提供 polyfill / stub |
+| 时间 | `vi.useFakeTimers()` |
+| `window.location` | `Object.defineProperty(window, 'location', ...)` 或用 `jest-location-mock` |
+| localStorage | 默认 jsdom 已提供；需清理 `beforeEach(() => localStorage.clear())` |
+
+## 12. 反模式（禁止）
+
+- ❌ 用 `getByTestId` 当默认选择器（优先 `getByRole`）
+- ❌ 用 `fireEvent` 代替 `user-event`
+- ❌ 测试实现细节（检查内部 state、私有函数）
+- ❌ 手写 `vi.mock('axios' / 'fetch')` 而不用 MSW
+- ❌ `beforeEach` 里 setState 让 test 互相依赖（测试必须可独立运行）
+- ❌ "修了 bug 不写回归测试"
+- ❌ E2E 覆盖已在单元测过的逻辑（慢 + 脆）
+
+## 13. 质量门禁
+
+- [ ] 新增 / 修改代码覆盖率 ≥ 80%
+- [ ] 每个 AC 至少 1 条测试
+- [ ] Bugfix 有能失败的复现测试
+- [ ] 至少 1 条 axe 断言（组件级）
+- [ ] Playwright 关键流程（登录 / 核心 CRUD）
+- [ ] Refactor 视觉回归零差异
+- [ ] MSW 作为 HTTP mock 默认方案
+- [ ] user-event 作为交互默认方案
+- [ ] 通用门禁见 [`quality/testing-pyramid`](../../quality/testing-pyramid/SKILL.md)