cmwrun

Appearance

🏗 项目架构讟计文档 ​

IMPORTANT

历史園档诎明2026-03-11本文䞭的 Storybook、.storybook、pnpm storybook、*.stories.tsx 内容䞺历史阶段记圕。项目现已统䞀迁移䞺 VitePress 组件文档方案请䜿甚 pnpm dev并圚 front/components/**/index.md 䞭通过 <demo react="..."/> 查看组件挔瀺。

抂览 ​

本文档描述 cmwrun 前端知识站的敎䜓架构、栞心暡块、层级关系和数据流。

系统架构囟 ​

┌─────────────────────────────────────────────────────────────────┐
│                        甚户浏览噚                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▌
┌─────────────────────────────────────────────────────────────────┐
│                      VitePress 站点前端                       │
├──────────────────────────────────────────────────────────────────
│                                                                  │
│  ┌────────────────────────────────────────────────────────┐    │
│  │           应甚层页面、组件、垃局                    │    │
│  │  ┌──────────────────────────────────────────────────┐  │    │
│  │  │ Pages: 銖页、知识库、组件库、云端胜力、曎新记圕  │  │    │
│  │  │ Components: Button, Select, Form, ...            │  │    │
│  │  │ Layouts: Doc, Home, Sidebar Navigation           │  │    │
│  │  └──────────────────────────────────────────────────┘  │    │
│  └────────────────────────────────────────────────────────┘    │
│                              │                                   │
│  ┌────────────────────────────────────────────────────────┐    │
│  │           䞚务逻蟑层Hooks、工具凜数                │    │
│  │  ┌──────────────────────────────────────────────────┐  │    │
│  │  │ Hooks: useGuide (亀互富航)                        │  │    │
│  │  │ Utils: 防抖、节流、深拷莝、算法等                │  │    │
│  │  │ Services: API 调甚、数据获取                      │  │    │
│  │  └──────────────────────────────────────────────────┘  │    │
│  └────────────────────────────────────────────────────────┘    │
│                              │                                   │
│  ┌────────────────────────────────────────────────────────┐    │
│  │      监控和分析层性胜、错误、甚户行䞺            │    │
│  │  ┌──────────────────────────────────────────────────┐  │    │
│  │  │ Performance: Web Vitals 监控、性胜基准线         │  │    │
│  │  │ ErrorTracking: 党局错误捕获                      │  │    │
│  │  │ Sentry: 错误䞊报、性胜监控                       │  │    │
│  │  │ Analytics: 甚户行䞺远螪                          │  │    │
│  │  └──────────────────────────────────────────────────┘  │    │
│  └────────────────────────────────────────────────────────┘    │
│                              │                                   │
│  ┌────────────────────────────────────────────────────────┐    │
│  │           底层支持样匏、䞻题、配眮                │    │
│  │  ┌──────────────────────────────────────────────────┐  │    │
│  │  │ Theme: 亮色/深色䞻题、CSS 变量                  │  │    │
│  │  │ Styles: 党局样匏、组件样匏                      │  │    │
│  │  │ Config: VitePress 配眮、构建选项                │  │    │
│  │  └──────────────────────────────────────────────────┘  │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┌─────────────────────┐
        ▌                     ▌                     ▌
   ┌─────────┐           ┌─────────┐           ┌─────────┐
   │ Sentry  │           │ Analytics│           │ CDN     │
   │ 错误远螪 │           │ 数据收集 │           │ 内容分发 │
   └─────────┘           └─────────┘           └─────────┘

栞心暡块诊解 ​

1. 应甚层Application Layer ​

页面Pages ​

/: 銖页 (index)
  └─ Hero 区域、特性展瀺、快速铟接

/front/knowledge/: 知识库
  └─ KMP 算法、Event Loop、React Diff、枲染流氎线...

/front/components/: 组件库
  └─ Button、Select、Form 组件挔瀺和文档

/cloud-capabilities: 云端胜力
  └─ 云端功胜介绍

/updates: 曎新记圕
  └─ 版本历史和曎新日志

组件Components ​

Button (按钮)
  ├─ Props: variant, size, disabled, loading, block, onClick
  ├─ Stories: 11 䞪亀互匏故事
  └─ Test: 12 䞪单元测试

Select (䞋拉选择)
  ├─ Props: options, value, onChange, disabled, error, placeholder
  ├─ Stories: 7 䞪亀互匏故事
  └─ Test: 11 䞪单元测试

Form (衚单)
  ├─ HighPerformanceForm (高性胜衚单)
  ├─ PubSubForm (事件驱劚衚单)
  └─ 挔瀺及文档

垃局Layouts ​

DefaultTheme (默讀䞻题)
  ├─ Navigation: 顶郚富航、䟧蟹栏
  ├─ Content: 文章内容区域
  ├─ Sidebar: 文章富航
  └─ Footer: 页脚、瀟亀铟接

Doc Layout: 文档䞓甚垃局
Home Layout: 銖页䞓甚垃局

2. 䞚务逻蟑层Business Logic Layer ​

Hooks自定义选项 ​

useGuide.ts (亀互富芜)
  ├─ 功胜: 创建分步骀指富
  ├─ 方法: start(), stop(), next(), prev()
  ├─ 特性: 自劚滚劚、元玠定䜍、重试机制
  └─ 测试: 11 䞪测试甚䟋94.59% 芆盖率

工具凜数Utils ​

防抖 / 节流: 防止频繁觊发
深浅拷莝: 对象倍制
算法: KMP、排序、递園等
字笊䞲倄理: 栌匏化、解析、验证
类型检查: 类型守卫、类型蜬换

服务Services ​

API 调甚: 获取数据、提亀衚单
数据蜬换: 规范化响应数据
猓存管理: 减少䞍必芁的请求
错误倄理: 统䞀的错误倄理策略

3. 监控和分析层Monitoring & Analytics Layer ​

性胜监控Performance Monitoring ​

performance.ts
  ├─ Web Vitals 集成
  │  ├─ CLS: Cumulative Layout Shift垃局皳定性
  │  ├─ FID: First Input Delay亀互响应
  │  ├─ FCP: First Contentful Paint銖字节
  │  ├─ LCP: Largest Contentful Paint䞻内容
  │  └─ TTFB: Time to First Byte服务噚响应
  │
  └─ 长任务监控
     └─ PerformanceObserver API

performance-baseline.ts
  ├─ 性胜指标基准线定义
  ├─ Good / Warning / Critical 阈倌
  ├─ 实时告譊机制
  └─ 性胜报告生成

错误远螪Error Tracking ​

error-tracking.ts
  ├─ 党局错误倄理
  │  ├─ window.onerror脚本错误
  │  ├─ unhandledrejectionPromise 拒绝
  │  └─ 资源加蜜倱莥IMG, SCRIPT, LINK
  │
  ├─ 错误分类和统计
  ├─ 错误历史记圕最倚 50 条
  └─ 错误报告生成

sentry-integration.ts
  ├─ Sentry SDK 集成
  ├─ 自劚䞊报生产环境
  ├─ 自定义事件远螪
  ├─ 甚户信息管理
  └─ 性胜和错误的统䞀平台

分析和远螪Analytics ​

甚户行䞺: 页面访问、点击、滚劚
性胜数据: 加蜜时闎、资源倧小、枲染时闎
错误信息: 错误类型、堆栈跟螪、甚户环境
自定义事件: 䞚务盞关的关键操䜜

4. 底层支持Infrastructure Layer ​

䞻题系统Theme System ​

.vitepress/theme/
  ├─ Vue 组件
  │  ├─ Avatar3D: 3D 虚拟角色
  │  ├─ BackToTop: 返回顶郚
  │  ├─ KeyboardShortcuts: 快捷键垮助
  │  ├─ ThemeSwitcher: 䞻题切换
  │  ├─ ReadingProgress: 阅读进床
  │  └─ others...
  │
  ├─ 样匏
  │  ├─ custom.css: 自定义样匏
  │  └─ print.css: 打印样匏
  │
  └─ index.ts: 䞻题入口讟眮所有组件和监控

VitePress 配眮Build Configuration ​

.vitepress/config.mts
  ├─ 站点基本信息
  ├─ 富航和䟧蟹栏配眮
  ├─ Markdown 插件配眮
  │  ├─ 时闎线插件
  │  ├─ Mermaid 囟衚
  │  ├─ Demo 挔瀺
  │  └─ 代码块分组
  │
  ├─ 构建䌘化
  │  ├─ 代码分割
  │  ├─ 䟛应商分组
  │  └─ Bundle 分析
  │
  └─ PWA 配眮
     ├─ Manifest
     ├─ Workbox 猓存策略
     └─ 犻线支持

数据流和亀互 ​

1. 页面加蜜流皋 ​

甚户访问 → VitePress 路由匹配 → 加蜜页面组件
  ↓
䞻题初始化theme/index.ts
  ├─ 初始化性胜监控 (performance.ts)
  ├─ 初始化错误远螪 (error-tracking.ts)
  ├─ 初始化性胜基准 (performance-baseline.ts)
  ├─ 初始化 Sentry (sentry-integration.ts)
  └─ 挂蜜 Vue 组件 (Avatar3D, Navigation, etc.)
  ↓
内容枲染 → 性胜指标收集 → Web Vitals 回调觊发
  ↓
甚户亀互觊发 → 事件监听 → 错误/性胜数据䞊报

2. 组件䜿甚流皋 ​

富入组件 → Props 验证 → 组件枲染
  ↓
甚户亀互点击、蟓入、等
  ↓
事件倄理噚执行 → 䞚务逻蟑倄理Hooks、Utils
  ↓
DOM 曎新 → 重排/重绘 → 性胜数据收集
  ↓
性胜指标检查 → 是吊超过基准线
  ├─ 是 → 记圕譊告/错误 → 可选䞊报 Sentry
  └─ 吊 → 正垞继续

3. 错误倄理流皋 ​

应甚发生错误脚本、资源、Promise
  ↓
党局错误倄理噚捕获 (error-tracking.ts)
  ↓
错误分类和规范化
  ├─ 错误类型 (脚本/资源/Promise)
  ├─ 错误级别 (error/warning/info)
  └─ 错误䞊䞋文 (URL, UA, 时闎)
  ↓
保存到本地错误列衚
  ├─ 最倚星瀺最近 50 条
  └─ 添加时闎戳和 ID
  ↓
生产环境
  ├─ 是 → 发送到 Sentry (async)
  └─ 吊 → 匀发环境蟓出日志
  ↓
譊告是吊关键
  ├─ 是 → 生成告譊事件
  └─ 吊 → 静默记圕

文件目圕结构 ​

vitePress/
├── .github/
│   └── workflows/
│       └── ci.yml                    # GitHub Actions 工䜜流并行任务
│
├── .storybook/                        # Storybook 配眮
│   ├── main.ts
│   └── preview.ts
│
├── .vitepress/                        # VitePress 配眮和䞻题
│   ├── config.mts                     # 栞心配眮文件
│   ├── theme/
│   │   ├── index.ts                   # 䞻题入口
│   │   ├── performance.ts             # Web Vitals 监控
│   │   ├── error-tracking.ts          # 错误远螪
│   │   ├── performance-baseline.ts    # 性胜基准线
│   │   ├── sentry-integration.ts      # Sentry 集成
│   │   ├── custom.css                 # 自定义样匏
│   │   ├── print.css                  # 打印样匏
│   │   ├── components/                # Vue 䞻题组件
│   │   └── seo.ts                     # SEO 配眮
│   └── dist/                          # 构建蟓出
│       ├── bundle-analysis.html       # Bundle 分析报告
│       └── [眑站文件]
│
├── front/                             # 栞心内容和组件
│   ├── components/
│   │   ├── Button/
│   │   │   ├── button.tsx             # 组件源码
│   │   │   ├── button.test.tsx        # 单元测试
│   │   │   ├── button.stories.tsx     # Storybook 故事
│   │   │   └── index.md               # 文档
│   │   ├── Select/
│   │   │   ├── select.tsx
│   │   │   ├── select.test.tsx
│   │   │   ├── select.stories.tsx
│   │   │   └── index.md
│   │   └── Form/
│   │       ├── form.tsx
│   │       ├── pubsub-form.tsx
│   │       └── index.md
│   │
│   └── knowledge/                     # 知识文章
│       ├── 防抖䞎节流.md
│       ├── Event-Loop诊解.md
│       ├── React-Diff算法诊解.md
│       ├── 浏览噚枲染流氎线䞎重排重绘.md
│       └── ...
│
├── public/                            # 静态资源和挔瀺
│   ├── debounce-throttle-demo.html
│   ├── event-loop-demo.html
│   ├── react-diff-demo.html
│   └── [其他挔瀺页面]
│
├── tests/                             # E2E 测试
│   ├── basic.spec.ts
│   ├── advanced-interactions.spec.ts
│   ├── comprehensive.spec.ts
│   └── ...
│
├── vitest.config.ts                   # 单元测试配眮
├── playwright.config.ts               # E2E 测试配眮
├── tsconfig.json                      # TypeScript 配眮
├── eslint.config.js                   # ESLint 配眮
├── prettier.config.js                 # Prettier 配眮
│
├── CONTRIBUTING.md                    # 莡献指南
├── OPTIMIZATION-SUMMARY.md            # 䌘化总结
├── QUICK-REFERENCE.md                 # 快速参考
└── README.md                          # 项目文档

郚眲架构 ​

Local Development
  ├─ pnpm dev (VitePress)
  └─ pnpm storybook

Build & Analyze
  ├─ pnpm build
  ├─ pnpm build:analyze
  └─ Security audit

GitHub Actions CI/CD
  ├─ Code Quality (并行)
  ├─ Unit Tests (并行)
  ├─ Build (并行)
  │  ├─ E2E Tests (depends on build)
  │  └─ Performance Analysis (depends on build)
  ├─ Security Audit (并行)
  └─ All Checks (绌合检查)

Production
  ├─ GitHub Pages (CDN)
  └─ Sentry (错误/性胜䞊报)

扩展和绎技指南 ​

添加新页面 ​

  1. 圚 front/knowledge/ 或盞应目圕创建 .md 文件
  2. 圚 .vitepress/config.mts 的 sidebar 配眮䞭添加
  3. 可选劂果需芁亀互圚 public/ 创建 HTML 挔瀺

添加新组件 ​

  1. 创建组件目圕 front/components/ComponentName/
  2. 猖写 component.tsx 文件
  3. 猖写 component.test.tsx 单元测试
  4. 猖写 component.stories.tsx Storybook 故事
  5. 猖写 index.md 文档
  6. 圚 .vitepress/config.mts 䞭添加富航

性胜䌘化 ​

  1. 监控 Web Vitals 通过 performance.ts
  2. 检查性胜基准线告譊performance-baseline.ts
  3. 分析 Bundle 倧小pnpm build:analyze
  4. 䌘化关键路埄枲染

错误调查 ​

  1. 查看浏览噚控制台匀发环境
  2. 检查错误远螪系统error-tracking.ts
  3. 圚 Sentry 仪衚板查看线䞊错误
  4. 䜿甚 Playwright 重现 E2E 问题

性胜目标和指标 ​

📊 性胜目标
├─ 銖屏加蜜: FCP < 1 秒 ✅
├─ 䞻内容: LCP < 2.5 秒 ✅
├─ 亀互响应: FID < 100ms ✅
├─ 垃局皳定: CLS < 0.1 ✅
└─ 服务噚: TTFB < 600ms ✅

🧪 测试芆盖
├─ 单元测试: 30+ 甚䟋72% 芆盖
├─ E2E 测试: 24+ 甚䟋党路埄芆盖
└─ 总䜓: 54+ 甚䟋高床测试

📊 Bundle 䌘化
├─ 代码分割: route-based 分割
├─ 䟛应商分组: 独立 shiki / mermaid chunks
├─ 囟像䌘化: CSS 析进匏加蜜
└─ 猓存策略: 类哈垌文件名

技术栈总结 ​

层级技术版本
框架Vue 3Latest
文档VitePress1.6.4
构建Vite7.x
语蚀TypeScript5.x
组件库React19.2.x
测试Vitest, PlaywrightLatest
组件文档Storybook10.2.15
代码莚量ESLint, PrettierLatest
监控Web Vitals, SentryLatest
郚眲GitHub Pages + ActionsNative

䞋䞀步升级计划 ​

Phase 1 (短期):
  ├─ Sentry 生产环境配眮
  ├─ 性胜仪衚板匀发
  └─ 自劚化郚眲脚本

Phase 2 (䞭期):
  ├─ 灰床发垃系统
  ├─ A/B 测试框架
  └─ 实时告譊系统

Phase 3 (长期):
  ├─ 甚户行䞺分析
  ├─ 智胜掚荐系统
  └─ 犻线应甚增区

最后曎新: 2026-03-06 绎技者: cmwrun 团队 文档版本: 1.0

内容仅䟛孊习参考劂有错误欢迎指正䞎 PR

Copyright © 2024-present cmwrun