complete card height change and new page about RoRd overall and weight assignment

2025-10-05 20:40:16 +08:00
parent 8a0276c3ce
commit 76efb30b7f
15 changed files with 2734 additions and 1446 deletions
--- a/README.md
+++ b/README.md
@@ -1,217 +1,156 @@
-# Astro Jiao77 网站
+<!-- ...existing code... -->
+# astro-jiao77.cn

-一个基于 Astro 构建的现代化网站，采用玻璃质感设计和莫兰蒂配色方案。
+一个基于 Astro 5、TypeScript 与 Tailwind CSS 打造的现代静态网站，融合玻璃质感设计、莫兰蒂配色与定制动画系统，适合构建专题站点、数据报告与导航中心。

-## 🎨 设计特色
+## 项目简介

- **玻璃质感 (Glass Morphism)**: 半透明背景配合模糊效果
- **莫兰蒂配色**: 温和优雅的色彩搭配
- **圆角设计**: 现代化的UI界面
- **流畅动画**: 渐入渐出效果和悬浮动画
- **响应式布局**: 适配各种设备屏幕
+- 使用 Astro 的岛屿架构实现快速加载与细粒度交互。
+- Tailwind CSS 提供统一的设计令牌与主题扩展，支持深浅配色切换。
+- 组件库涵盖导航、报告、通用 UI 与动画包装器，降低页面搭建成本。
+- 内置部署脚本与检查流程，支持快速上线与质量验证。

-## 📁 项目结构
+## 环境要求

-```
-src/
-├── components/           # 组件库
-│   ├── navigation/      # 导航页面组件
-│   │   ├── NavigationCard.astro    # 导航卡片
-│   │   └── NavigationGrid.astro    # 导航网格布局
-│   ├── report/          # 报告页面组件
-│   │   ├── ReportSection.astro     # 报告区块
-│   │   ├── MetricCard.astro        # 指标卡片
-│   │   └── MetricsGrid.astro       # 指标网格
-│   ├── Header.astro     # 可展开收缩的页眉
-│   ├── Footer.astro     # 页脚组件
-│   ├── Container.astro  # 通用容器组件
-│   └── AnimatedElement.astro  # 动画组件
-├── layouts/
-│   └── BaseLayout.astro # 基础布局
-├── pages/               # 页面
-│   ├── index.astro     # 首页 (导航类型)
-│   └── reports.astro   # 报告页面
-└── styles/
-    └── global.css      # 全局样式
+| 工具 | 建议版本 | 说明 |
+| --- | --- | --- |
+| Node.js | ≥ 18.17.0 | 可用 nvm 管理不同版本 |
+| npm / pnpm | npm ≥ 9 / pnpm ≥ 8 | 根据团队习惯选择包管理器 |
+| Git | 最新版本 | 代码管理与部署同步 |
+
+## 快速开始
+
+1. 安装依赖  
+   ```bash
+   npm install
+   ```
+2. 启动开发服务器（默认端口 4321）  
+   ```bash
+   npm run dev
+   ```
+3. 构建与预览产物  
+   ```bash
+   npm run build
+   npm run preview
+   ```
+4. 类型与模板检查  
+   ```bash
+   npm run astro check
+   ```
+
+## 目录结构
+
+```text
+.
+├─ src/
+│  ├─ components/
+│  │  ├─ common/                # 通用组件（按钮、动画包装、图像查看器等）
+│  │  ├─ navigation/            # 导航页面组件 (NavigationCard、NavigationGrid)
+│  │  └─ report/                # 报告组件 (ReportSection、MetricCard、MetricsGrid)
+│  ├─ layouts/                  # 布局组件 (BaseLayout 等)
+│  ├─ pages/                    # Astro 页面 (首页、报告模板、专题页)
+│  └─ scripts/                  # 浏览器交互脚本 (滚动、头部动画等)
+├─ docs/                        # 说明文档与部署指南
+├─ public/                      # 静态资源 (图片、图标、字体等)
+├─ tailwind.config.mjs          # 主题与配色扩展
+├─ deploy.sh / deploy-full.sh   # 部署脚本
+└─ astro.config.mjs             # Astro 全局配置
 ```

-## 🎯 页面类型
+## 常用命令
+
+| 命令 | 功能 |
+| --- | --- |
+| `npm run dev` | 本地开发，支持热更新 |
+| `npm run build` | 产出静态文件到 `dist/` |
+| `npm run preview` | 使用 Astro 内置服务器预览构建结果 |
+| `npm run astro check` | 运行 TypeScript + Astro 模板检查 |
+| `npm run lighthouse` | （如配置）执行性能与可访问性检测 |
+
+## 核心模块与文件
+
+- 报告模板：`src/pages/report/template/index.astro`，配合 `docs/REPORT_TEMPLATE_SUMMARY.md` 快速复用结构。
+- 导航模板：`src/pages/navigation-template.astro`，搭配 `docs/NAVIGATION_TEMPLATE_GUIDE.md` 定制导航入口。
+- 交互脚本：`src/scripts/scroll-progress.ts`、`src/scripts/header.ts` 管理滚动进度条与动态头部。
+- 通用组件：`src/components/common/AnimatedElement.astro`、`GlowButton.astro`、`ImageViewer.astro` 提供动画与图片交互。
+- 配色定义：`tailwind.config.mjs` 中的 `morandi` 调色盘，实现统一的莫兰蒂主题。
+
+## 页面与组件使用

 ### 导航页面
- 使用导航组件库 (`src/components/navigation/`)
- 浅色背景渐变
- 服务卡片式布局
- 适用于：首页、目录页、功能导航等
+
+- 组合 `NavigationGrid` 与 `NavigationCard` 构建入口矩阵。
+- 支持自定义列数、动画延迟与卡片主题，适用于首页、功能导航等场景。

 ### 报告页面
- 使用报告组件库 (`src/components/report/`)
- 深色背景渐变
- 数据展示布局
- 适用于：数据报告、统计分析、dashboard等

-## 🧩 组件介绍
-
-### 导航组件
-
-#### NavigationCard
-导航卡片组件，支持：
- 三种颜色主题 (primary, secondary, accent)
- 三种尺寸 (small, medium, large)
- 图标和描述文本
- 悬浮动画效果
-
-```astro
-<NavigationCard
-  title="项目展示"
-  description="查看我的最新项目"
-  href="/projects"
-  icon="fas fa-code"
-  color="primary"
-  size="large"
-/>
-```
-
-#### NavigationGrid
-导航网格布局：
- 自适应列数
- 交错动画效果
- 响应式设计
-
-```astro
-<NavigationGrid title="导航中心" columns={3}>
-  <!-- NavigationCard 组件 -->
-</NavigationGrid>
-```
-
-### 报告组件
-
-#### ReportSection
-报告区块组件：
- 可配置标题层级
- 自动分割线
- 深色主题优化
-
-```astro
-<ReportSection title="数据分析" subtitle="详细数据报告" level={2}>
-  <p>报告内容...</p>
-</ReportSection>
-```
-
-#### MetricCard
-指标卡片：
- 数值显示
- 变化趋势指示
- 多种颜色主题
-
-```astro
-<MetricCard
-  title="访问量"
-  value="125,847"
-  change="+12.5%"
-  changeType="positive"
-  icon="fas fa-users"
-/>
-```
+- 使用 `ReportSection` 划分章节，搭配 `MetricCard`、`MetricsGrid` 展示核心指标。
+- 支持深色渐变背景与滚动触发动画，适合数据报告、分析仪表盘。

 ### 通用组件

-#### Container
-万能容器组件：
- 多种视觉样式 (glass, glass-dark, solid, outline)
- 灵活尺寸配置
- 圆角和阴影选项
+- `Container`：多种视觉变体（glass、solid、outline）与尺寸可选。
+- `AnimatedElement`：封装 8 种滚动动画，支持延迟与持续时间配置。
+- `Header`：响应滚动的智能页眉，移动端自适应。

-```astro
-<Container variant="glass" size="large" padding="xl">
-  内容...
-</Container>
-```
+## 设计与交互

-#### AnimatedElement
-动画包装器：
- 8种动画效果
- 滚动触发
- 自定义延迟和时长
+- **玻璃质感**：半透明背景 + 模糊滤镜，营造层次感。
+- **莫兰蒂配色**：柔和雅致，适用于深浅背景。定义示例：
+  ```css
+  morandi: {
+    cream: '#F4F1E8',
+    beige: '#E8DCC0',
+    sage: '#C8D5B9',
+    dusty: '#D4B5A0',
+    mauve: '#B8A5A5',
+    clay: '#A68B7B',
+    mist: '#C7B8A1',
+    stone: '#9B8B7A',
+    deep: '#7A6B5D'
+  }
+  ```
+- **动画系统**：加载、滚动、悬浮多种动效，增强反馈与沉浸感。
+- **响应式布局**：针对桌面、平板、移动端优化栅格与交互。

-```astro
-<AnimatedElement animation="fadeInUp" delay={300} trigger="scroll">
-  需要动画的内容...
-</AnimatedElement>
-```
+## 开发流程

-#### Header
-智能页眉：
- 自动展开/收缩
- 滚动响应
- 移动端适配
+1. 基于模板创建页面：复制 `pages/report/template` 或现有导航页。
+2. 在 `src/components/` 中组合组件，必要时拓展新变体。
+3. Tailwind 实现局部样式，注意复用 `@apply` 与设计令牌。
+4. 若需脚本交互，将逻辑放入 `src/scripts/` 并在页面中按需引入。
+5. 执行 `npm run astro check` 与 `npm run build` 确保质量。

-## 🎨 配色方案
+## 部署流程

-项目采用莫兰蒂配色，定义在 `tailwind.config.mjs`:
+1. 本地构建：`npm run build`
+2. 根据上线需求选择：
+   - `./deploy.sh`：快速增量部署
+   - `./deploy-full.sh`：完整部署，包含权限校验、压缩检测
+3. 部署验证请参考 `docs/DEPLOYMENT.md` 与 `docs/DEPLOY_FULL_VERIFICATION.md`
+4. 上线后建议检查服务器日志与浏览器控制台，确保资源加载正常。

-```css
-morandi: {
-  cream: '#F4F1E8',   # 奶白色
-  beige: '#E8DCC0',   # 米色
-  sage: '#C8D5B9',    # 鼠尾草绿
-  dusty: '#D4B5A0',   # 尘土色
-  mauve: '#B8A5A5',   # 紫灰色
-  clay: '#A68B7B',    # 陶土色
-  mist: '#C7B8A1',    # 薄雾色
-  stone: '#9B8B7A',   # 石头色
-  deep: '#7A6B5D'     # 深褐色
-}
-```
+## 调试技巧

-## 🚀 开发命令
+- 利用浏览器 DevTools 观察 CSS 变量与动画帧率。
+- Astro CLI 支持 `--open`、`--host`，例如 `npm run dev -- --host` 供局域网调试。
+- 对滚动行为可在控制台监听 `scroll-progress` 脚本的状态输出。
+- 若遇到类型问题，运行 `npm run astro check -- --watch` 进行持续监控。

-```bash
-# 安装依赖
-npm install
+## 技术栈

-# 启动开发服务器
-npm run dev
+- **Astro**：静态站点生成 + 部分组件岛屿渲染。
+- **Tailwind CSS**：实用类样式与主题扩展。
+- **TypeScript**：类型安全与更佳的开发体验。
+- **Font Awesome / 自定义图标**：图标资源。
+- **Vite**：开发服务器与构建工具。

-# 构建生产版本
-npm run build
+## 贡献指南

-# 预览生产构建
-npm run preview
-```
+欢迎提交 Issue 或 Pull Request 改进项目。建议遵循以下流程：

-## 📱 响应式设计
+1. Fork 仓库并创建新分支。
+2. 完成改动后运行 `npm run build` 与相关检查。
+3. 提交 PR 并在描述中说明变更内容及影响范围。

- **桌面端**: 完整功能和动画效果
- **平板端**: 优化布局和交互
- **移动端**: 简化界面，保持可用性
-
-## ✨ 动画效果
-
- **页面加载**: 渐入动画
- **滚动触发**: 元素逐步显现
- **悬浮效果**: 卡片提升和缩放
- **交错动画**: 网格元素依次出现
-
-## 🔧 自定义扩展
-
-### 添加新的导航卡片
-在 `src/pages/index.astro` 中添加新的 `NavigationCard` 组件
-
-### 创建新的报告页面
-1. 复制 `src/pages/reports.astro`
-2. 修改内容和数据
-3. 使用报告组件库构建布局
-
-### 扩展颜色主题
-在 `tailwind.config.mjs` 中添加新的颜色定义，然后在组件中使用
-
-## 📦 技术栈
-
- **Astro**: 现代化静态站点生成器
- **Tailwind CSS**: 实用优先的CSS框架
- **TypeScript**: 类型安全的JavaScript
- **Font Awesome**: 图标库
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request 来改进这个项目！
+<!-- ...existing code... -->