zgy/zhaoguiyang.site
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
720686751a3d8e21d0368aa84681a2584ac40bbe
zhaoguiyang.site/.trae/rules/project_rules.md

9.0 KiB
Raw Blame History

项目说明文档

本文档旨在提供对 zhaoguiyang.site 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。

1. 项目概述

zhaoguiyang.site 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能、项目、奖项和教育背景。

2. 技术栈和框架

  • 主要框架: Astro - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
  • UI 框架: React - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
  • 样式: Tailwind CSS - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 @tailwindcss/vite 集成到 Astro 项目中。
  • 动画: Framer Motion (framer-motion) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 组件，它可能是一个统一处理动画逻辑的封装。
  • 图标: Lucide React - 一个简单、美观的 SVG 图标库。
  • 包管理器: pnpm - 一个快速、磁盘空间高效的包管理器。
  • 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。可以参考 的实现方式，或者直接在组件中使用 motion 组件和 variants 来定义动画。确保动画效果流畅且符合项目整体风格。查阅 获取更详细的 API 和示例。
  • 可访问性: 在开发新功能时，请注意可访问性最佳实践。

9. 潜在的改进和扩展方向

  • CMS 集成: 对于更动态的内容管理，可以考虑集成一个 Headless CMS (如 Sanity, Contentful)。package.json 中提到了 Sanity (CMS)，这可能是一个未来的方向或之前的尝试。
  • 国际化 (i18n): 如果需要支持多语言，可以引入 Astro 或 React 的 i18n 库。
  • 更复杂的交互: 对于需要更复杂客户端逻辑的功能，可能需要引入更全面的状态管理方案。
  • API 路由: Astro 支持 API 路由，可以用于处理表单提交、与后端服务交互等。