docs: 添加项目说明文档以指导AI进行代码重构

2025-06-13 12:12:41 +08:00
parent c1bfb0915e
commit f134d69446
1 changed files with 119 additions and 0 deletions
--- a/.trae/rules/project_rules.md
+++ b/.trae/rules/project_rules.md
@@ -0,0 +1,119 @@
+# 项目说明文档
+
+本文档旨在提供对 `zhaoguiyang.site` 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。
+
+## 1. 项目概述
+
+`zhaoguiyang.site` 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能、项目、奖项和教育背景。
+
+## 2. 技术栈和框架
+
+- **主要框架**: [Astro](https://astro.build/) - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
+- **UI 框架**: [React](https://react.dev/) - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
+- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 `@tailwindcss/vite` 集成到 Astro 项目中。
+- **动画**: [Framer Motion](https://www.framer.com/motion/) (`framer-motion`) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 <mcsymbol name="HeroSection" path="src/components/HeroSection.tsx" filename="HeroSection.tsx" type="function" startline="5"></mcsymbol> 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 <mcfile path="src/components/MotionWrapper.tsx" name="MotionWrapper.tsx"></mcfile> 组件，它可能是一个统一处理动画逻辑的封装。
+- **图标**: [Lucide React](https://lucide.dev/) - 一个简单、美观的 SVG 图标库。
+- **包管理器**: [pnpm](https://pnpm.io/) - 一个快速、磁盘空间高效的包管理器。
+- **TypeScript**: 用于类型检查和提高代码质量。
+
+## 3. 组件库和 UI
+
+- **自定义组件**: 项目包含多个自定义 React 组件，位于 `src/components/` 目录下，用于展示不同的内容区域，例如：
+    - `HeroSection.tsx`: 个人简介区域。
+    - `ExperienceSection.tsx`: 工作经历区域。
+    - `SkillsSection.tsx`: 技能展示区域。
+    - `ProjectsSection.tsx`: 项目展示区域。
+    - `AwardsSection.tsx`: 奖项展示区域。
+    - `EducationSection.tsx`: 教育背景区域。
+    - `GlassHeader.tsx`: 玻璃拟态效果的导航栏。
+    - `Footer.tsx`: 页脚。
+- **UI 辅助库**:
+    - `class-variance-authority`: 用于创建可变样式的组件。
+    - `clsx`: 用于有条件地组合类名。
+    - `tailwind-merge`: 用于合并 Tailwind CSS 类名，避免冲突。
+    - `tw-animate-css`: 可能是用于集成 Animate.css 的 Tailwind CSS 插件（虽然 `package.json` 中列出，但具体用法需进一步查看代码）。
+- **Radix UI**: `@radix-ui/react-slot` 被用作依赖，这表明项目可能使用 Radix UI 的某些底层实用程序或组件，通常用于构建可访问和可组合的 UI 组件。
+
+## 4. 目录结构
+
+```
+├── .gitignore             # Git 忽略文件配置
+├── .trae/                 # Trae AI 相关配置目录
+│   └── rules/
+│       └── project_rules.md # 本项目说明文档
+├── .vscode/               # VS Code 编辑器配置
+│   ├── extensions.json
+│   └── launch.json
+├── LICENSE                # 项目许可证
+├── README.md              # 项目自述文件
+├── astro.config.mjs       # Astro 配置文件
+├── components.json        # 可能是 Shadcn UI 或类似组件库的配置文件
+├── package.json           # 项目依赖和脚本配置
+├── pnpm-lock.yaml         # pnpm 锁文件
+├── public/                # 静态资源目录 (如图片、favicon)
+│   ├── favicon.svg
+│   └── profile.jpg
+├── src/
+│   ├── components/        # React 组件目录
+│   │   ├── AwardsSection.tsx
+│   │   ├── EducationSection.tsx
+│   │   ├── ExperienceSection.tsx
+│   │   ├── Footer.tsx
+│   │   ├── GlassHeader.tsx
+│   │   ├── HeroSection.tsx
+│   │   ├── MotionWrapper.tsx  # Framer Motion 包装组件
+│   │   ├── ProjectsSection.tsx
+│   │   ├── SkillsSection.tsx
+│   │   ├── TimelineItem.tsx   # 时间轴条目组件
+│   │   └── ui/                # 可能包含更通用的 UI 组件 (当前为空)
+│   ├── layouts/             # Astro 布局组件
+│   │   └── Layout.astro       # 全局页面布局
+│   ├── lib/                 # 辅助函数和数据
+│   │   ├── data.ts            # 存储个人信息、经历、技能等静态数据
+│   │   └── utils.ts           # 通用工具函数 (当前可能为空或包含少量工具)
+│   ├── pages/               # Astro 页面组件
+│   │   └── index.astro        # 网站主页
+│   └── styles/              # 全局样式
+│       └── global.css
+└── tsconfig.json          # TypeScript 配置文件
+```
+
+## 5. 关键文件说明
+
+- **`astro.config.mjs`**: 配置 Astro 项目，包括 Vite 插件（如 Tailwind CSS）和 Astro 集成（如 React）。
+- **`package.json`**: 定义项目元数据、依赖项和 npm 脚本（如 `dev`, `build`, `preview`）。
+- **`tsconfig.json`**: 配置 TypeScript 编译器选项，包括路径别名（`@/*` 指向 `./src/*`）和 JSX 设置。
+- **`src/layouts/Layout.astro`**: 定义网站的全局 HTML 结构、头部信息（`<head>`）、全局样式和一些客户端脚本（如主题切换逻辑）。所有页面都将使用此布局。
+- **`src/pages/index.astro`**: 网站的入口页面，它导入并使用 `Layout.astro` 作为布局，并按顺序引入各个 React 内容区域组件。注意 `client:only="react"`指令，表示这些 React 组件仅在客户端渲染。
+- **`src/lib/data.ts`**: 存储网站展示的静态数据，如个人信息、工作经历、教育背景、技能列表、项目信息和奖项。这使得内容易于更新和管理，而无需直接修改组件代码。
+- **`src/components/*.tsx`**: 构成页面主要内容的 React 组件。它们从 `src/lib/data.ts` 获取数据并使用 Tailwind CSS 进行样式设置，使用 Framer Motion 实现动画效果。
+- **`public/`**: 存放可以直接通过 URL 访问的静态文件，如 `favicon.svg` 和 `profile.jpg`。
+
+## 6. 数据流和状态管理
+
+- **静态数据**: 大部分内容数据（如个人信息、工作经历等）都存储在 `src/lib/data.ts` 中，并直接导入到相应的 React 组件中进行渲染。这是一个静态网站，因此没有复杂的客户端状态管理（如 Redux 或 Zustand）。
+- **主题切换**: `src/layouts/Layout.astro` 中包含一个内联脚本，用于处理暗黑/明亮模式的主题切换，并将用户的偏好存储在 `localStorage` 中。
+
+## 7. 构建和部署
+
+- **开发**: 使用 `pnpm run dev` 命令启动 Astro 开发服务器。
+- **构建**: 使用 `pnpm run build` 命令将项目构建为静态文件，输出到 `dist/` 目录（默认情况下，可由 `astro.config.mjs` 配置）。
+- **预览**: 使用 `pnpm run preview` 命令在本地预览构建后的站点。
+
+## 8. AI 代码重构和功能开发指南
+
+- **遵循现有模式**: 在添加新组件或修改现有组件时，请参考 `src/components/` 和 `src/pages/` 中的现有代码风格和结构。
+- **数据驱动**: 如果添加新的内容区域，考虑是否可以将相关数据添加到 `src/lib/data.ts` 中，以保持内容与表示的分离。
+- **组件化**: 优先创建可复用的 React 组件。
+- **Astro 与 React 集成**: 理解 Astro 如何与 React 组件集成，特别是 `client:*` 指令的使用。
+- **Tailwind CSS**: 使用 Tailwind CSS 的实用工具类进行样式设置。
+- **TypeScript**: 确保新代码符合 TypeScript 的类型要求。
+- **动画**: 如果需要添加动画，应优先使用 Framer Motion。可以参考 <mcfile path="src/components/MotionWrapper.tsx" name="MotionWrapper.tsx"></mcfile> 的实现方式，或者直接在组件中使用 `motion` 组件和 `variants` 来定义动画。确保动画效果流畅且符合项目整体风格。查阅 <mcurl name="Framer Motion 文档" url="https://www.framer.com/motion/"></mcurl> 获取更详细的 API 和示例。
+- **可访问性**: 在开发新功能时，请注意可访问性最佳实践。
+
+## 9. 潜在的改进和扩展方向
+
+- **CMS 集成**: 对于更动态的内容管理，可以考虑集成一个 Headless CMS (如 Sanity, Contentful)。`package.json` 中提到了 `Sanity (CMS)`，这可能是一个未来的方向或之前的尝试。
+- **国际化 (i18n)**: 如果需要支持多语言，可以引入 Astro 或 React 的 i18n 库。
+- **更复杂的交互**: 对于需要更复杂客户端逻辑的功能，可能需要引入更全面的状态管理方案。
+- **API 路由**: Astro 支持 API 路由，可以用于处理表单提交、与后端服务交互等。