📊 项目重构与优化报告 (Phase 3)

IMPORTANT

历史归档说明（2026-03-11）：本文中涉及 Storybook 的目录与命令是当时阶段性记录。当前项目已统一迁移到 VitePress 组件文档链路。

日期：2026-03-06 工作：项目文件结构优化 + 业界标准化状态：✅ 完成

📋 本轮优化概览

目标

将 vitePress 项目从杂乱的根目录结构优化到业界标准的分层架构，提高项目可维护性和扩展性。

成果

✅ 完整的目录重构（从混乱到标准化）
✅ 路径别名配置（类似 Next.js / Vite 项目）
✅ 所有测试通过（34/34 ✅）
✅ 生产构建成功 ✅
✅ 向后兼容性保持完好

🏗️ 项目结构优化（Before → After）

优化前（混乱结构）

project-root/
├── GuideExample.tsx            ❌ React 源文件在根目录
├── GuideOverlay.tsx            ❌ 组件源文件在根目录
├── a.jsx, useGuide.ts          ❌ 源代码分散无序
├── front/
│   ├── components/             ✓ 有一定组织
│   └── knowledge/              ✓ 有一定组织
├── tests/
│   ├── *.spec.ts               ❌ E2E 和单元混合
│   └── useGuide.test.ts        ❌ 位置不清楚
├── .vitepress/                 ✓ 配置就位
└── 大量 .md 文件在根目录         ❌ 文档混乱无序

问题：

源代码分散，难以维护
测试组织不清
文档路径混乱
新开发者快速导航困难
不符合 TypeScript/Vite 项目规范

优化后（业界标准）

project-root/
├── src/                        ✅ 所有源代码
│   ├── components/             ✅ React 组件库
│   │   ├── Button/
│   │   ├── Select/
│   │   └── Form/
│   ├── hooks/                  ✅ 自定义 Hooks
│   │   └── useGuide.ts
│   ├── utils/                  ✅ 工具函数
│   ├── types/                  ✅ TypeScript 类型
│   └── ...
│
├── docs/                       ✅ VitePress 文档
│   ├── front/
│   │   ├── knowledge/          ✅ 知识库（向后兼容）
│   │   └── components/         ✅ 组件文档
│   ├── guide/                  ✅ 用户指南
│   ├── extra/                  ✅ 架构/优化文档
│   ├── PROJECT_STRUCTURE.md    ✅ 项目结构说明
│   └── index.md                ✅ 文档首页
│
├── tests/                      ✅ 测试组织
│   ├── unit/                   ✅ 单元测试
│   │   ├── useGuide.test.ts
│   │   ├── setup.ts
│   │   └── ...
│   ├── e2e/                    ✅ 端到端测试
│   │   ├── basic.spec.ts
│   │   ├── advanced-interactions.spec.ts
│   │   └── ...
│   └── fixtures/               ✅ 测试数据（可选）
│
├── public/                     ✅ 静态资源
├── .vitepress/                 ✅ VitePress 配置
├── .storybook/                 ✅ Storybook 配置
│
└── 配置文件（根目录）           ✅ 集中管理
    ├── tsconfig.json           ✅ 已更新
    ├── vitest.config.ts        ✅ 已更新
    ├── package.json
    └── ...

优势：

✅ 文件位置清晰，易于导航
✅ 遵循业界标准（Next.js / Vite 风格）
✅ 便于团队协作和新人上手
✅ 扩展性强，易于添加新功能
✅ 与现代工具链兼容

📝 具体改动清单

1. 源代码迁移 → src/

原路径	新路径	说明
`front/components/*`	`src/components/*`	React 组件库
`useGuide.ts`	`src/hooks/useGuide.ts`	自定义 Hook
`GuideExample.tsx`	`src/components/GuideExample.tsx`	示例组件
`GuideOverlay.tsx`	`src/components/GuideOverlay.tsx`	覆盖层组件

2. 文档迁移 → docs/

原路径	新路径	说明
`front/knowledge/`	`docs/front/knowledge/`	知识库（向后兼容）
`front/components/`	`docs/front/components/`	组件文档
`api-examples.md`	`docs/guide/api-examples.md`	API 示例
`ARCHITECTURE.md`	`docs/extra/ARCHITECTURE.md`	架构文档
`ROADMAP.md`	`docs/extra/ROADMAP.md`	路线图

3. 测试重组 → tests/

原路径	新路径	说明
`tests/*.spec.ts`	`tests/e2e/*.spec.ts`	E2E 测试
`useGuide.test.ts`	`tests/unit/useGuide.test.ts`	单元测试
`tests/setup.ts`	`tests/unit/setup.ts`	Vitest 配置

4. 配置更新

tsconfig.json

typescript

// ✅ 新增路径别名（类似 Next.js）
"paths": {
  "@/*": ["src/*"],
  "@components/*": ["src/components/*"],
  "@hooks/*": ["src/hooks/*"],
  "@utils/*": ["src/utils/*"],
  "@types/*": ["src/types/*"]
}

// ✅ 更新 include
"include": [
  "src/**/*.ts",
  "src/**/*.tsx",
  "tests/**/*.ts",
  "tests/**/*.tsx"
]

vitest.config.ts

typescript

// ✅ 更新 setupFiles
setupFiles: ['./tests/unit/setup.ts'],

// ✅ 更新测试 glob
include: [
  'src/**/*.{test,spec}.{ts,tsx}',
  'tests/unit/**/*.{test,spec}.{ts,tsx}'
],

// ✅ 更新路径别名
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
    '@components': path.resolve(__dirname, './src/components'),
    '@hooks': path.resolve(__dirname, './src/hooks'),
  }
}

5. 代码更新

路径别名使用

typescript

// ❌ 旧的相对导入
import { useGuide } from '../../../useGuide';

// ✅ 新的别名导入
import { useGuide } from '@/hooks/useGuide';

修复 Web Vitals 导入

typescript

// ❌ onFID 已在 web-vitals v5 中废弃
import { onCLS, onFID, onFCP, onLCP, onTTFB } from 'web-vitals';

// ✅ 更新为 onINP（Interaction to Next Paint）
import { onCLS, onFCP, onLCP, onTTFB, onINP } from 'web-vitals';

✅ 验证和测试

单元测试

✓ Button component          12 tests ✅
✓ Select component          11 tests ✅
✓ useGuide hook             11 tests ✅
─────────────────────────────────
Total: 34/34 tests passed ✅
Duration: 2.34s
Coverage: 72%

构建验证

✓ building client + server bundles...
✓ rendering pages...
✓ generating sitemap...
✓ Build completed successfully!

路由验证

/front/knowledge/* ✅ 保持向后兼容
/front/components/* ✅ 保持向后兼容
/guide/* ✅ 新的指南页面
/ ✅ 首页正常

📚 新增文档

docs/PROJECT_STRUCTURE.md

详细说明了新的项目结构：

目录说明和用途
导入路径规范
文件分类指南
最佳实践

使用：新团队成员应该首先阅读此文档了解项目组织。

🎯 为 Phase 4 做准备

已准备的基础设施

✅ 标准化的项目结构
✅ 路径别名配置完成
✅ 测试框架就位（可扩展）
✅ 构建系统验证无误
✅ 清晰的文档指引

下一步可立即开始的工作

短期（1-2 周）

□ Sentry 生产环境配置
  - 获取生产 DSN
  - 配置环境变量
  - 测试错误上报

□ 性能告警通知
  - 集成 Slack/Email
  - 设置告警钩子
  - 测试告警流程

□ 文档完善
  - 补充 src/ 中文件的说明
  - 更新团队 onboard 指南
  - 创建贡献者快速开始指南

中期（3-4 周）

□ 性能仪表板前端开发
  - 创建 Vue 组件展示 Web Vitals
  - 集成 Sentry API
  - 实现图表和告警面板

□ 自动化视觉测试
  - 选择工具（Percy / Chromatic）
  - 配置 Storybook 截图
  - CI 集成快照对比

□ 灰度发布系统
  - 实现分阶段发布脚本
  - 性能指标监控
  - 自动回滚机制

💡 关键改进对比

方面	优化前	优化后
文件定位	需要四处搜索	清晰的位置
代码组织	混乱分散	层级清晰
路径导入	复杂相对路径	简洁别名
测试分类	混合在一起	明确的 unit/e2e
文档查找	根目录混乱	结构化目录
新人上手	需要大量指引	自明的结构
IDE 导航	困难	直观快速
构建时间	无缓存影响	更优的缓存

🔄 向后兼容性

所有旧的 URL 路由保持不变：

/front/knowledge/* ✅ 继续工作
/front/components/* ✅ 继续工作
已发布的文章链接 ✅ 无需修改

新用户可以使用更直观的新路由（可在下一次优化中实现）。

🎓 对团队的好处

快速适应：新成员能快速理解项目结构
代码质量：更好的组织促进高质量代码
维护性：清晰的分层结构易于维护
扩展性：添加新功能时位置明确
协作效率：减少冲突和沟通成本
工具集成：与现代工具链无缝配合

📖 推荐阅读顺序

本文档（当前）- 了解重构内容
docs/PROJECT_STRUCTURE.md - 详细的目录说明
QUICK-REFERENCE.md - 日常命令速查
CONTRIBUTING.md - 代码贡献指南

📊 项目演进时间线

Phase 1 (完成): 测试和监控基础
  └─ 30 单元测试, 24+ E2E 测试, 错误追踪, Bundle 分析

Phase 2 (完成): 开发体验优化
  └─ Storybook 18+ 故事, 性能监控, CI/CD 优化

Phase 3 (完成): 项目结构和文件优化  ← YOU ARE HERE
  └─ src/, docs/, tests/ 标准化, 路径别名, 文档完善

Phase 4 (进行中): 开发工具和流程优化
  └─ 性能仪表板, 视觉回归测试, 灰度发布, A/B 测试

Phase 5-6: 数据智能和国际化

🚀 快速检查清单

在使用新结构时，确保：

[ ] 所有导入使用 @/ 别名而不是相对路径
[ ] src/ 中放置源代码
[ ] tests/ 中放置测试（分单元/E2E）
[ ] docs/ 中放置文档
[ ] public/ 中放置静态资源
[ ] 新组件遵循 src/components/ComponentName 结构
[ ] 新测试遵循相应的 tests/unit 或 tests/e2e 位置

版本：1.0 最后更新：2026-03-06 维护者：cmwrun 团队状态：✅ 生产就绪

📊 项目重构与优化报告 (Phase 3) ​

📋 本轮优化概览 ​

目标 ​

成果 ​

🏗️ 项目结构优化（Before → After） ​

优化前（混乱结构） ​

优化后（业界标准） ​

📝 具体改动清单 ​

1. 源代码迁移 → src/ ​

2. 文档迁移 → docs/ ​

3. 测试重组 → tests/ ​

4. 配置更新 ​

tsconfig.json ​

vitest.config.ts ​

5. 代码更新 ​

路径别名使用 ​

修复 Web Vitals 导入 ​

✅ 验证和测试 ​

单元测试 ​

构建验证 ​

路由验证 ​

📚 新增文档 ​

docs/PROJECT_STRUCTURE.md ​

🎯 为 Phase 4 做准备 ​

已准备的基础设施 ​

下一步可立即开始的工作 ​

短期（1-2 周） ​

中期（3-4 周） ​

💡 关键改进对比 ​

🔄 向后兼容性 ​

🎓 对团队的好处 ​

📖 推荐阅读顺序 ​

📊 项目演进时间线 ​

🚀 快速检查清单 ​

📊 项目重构与优化报告 (Phase 3)

📋 本轮优化概览

目标

成果

🏗️ 项目结构优化（Before → After）

优化前（混乱结构）

优化后（业界标准）

📝 具体改动清单

1. 源代码迁移 → src/

2. 文档迁移 → docs/

3. 测试重组 → tests/

4. 配置更新

tsconfig.json

vitest.config.ts

5. 代码更新

路径别名使用

修复 Web Vitals 导入

✅ 验证和测试

单元测试

构建验证

路由验证

📚 新增文档

docs/PROJECT_STRUCTURE.md

🎯 为 Phase 4 做准备

已准备的基础设施

下一步可立即开始的工作

短期（1-2 周）

中期（3-4 周）

💡 关键改进对比

🔄 向后兼容性

🎓 对团队的好处

📖 推荐阅读顺序

📊 项目演进时间线

🚀 快速检查清单