<!-- ...existing code... -->
# astro-jiao77.cn

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

## 项目简介

- 使用 Astro 的岛屿架构实现快速加载与细粒度交互。
- Tailwind CSS 提供统一的设计令牌与主题扩展，支持深浅配色切换。
- 组件库涵盖导航、报告、通用 UI 与动画包装器，降低页面搭建成本。
- 内置部署脚本与检查流程，支持快速上线与质量验证。

## 环境要求

| 工具 | 建议版本 | 说明 |
| --- | --- | --- |
| 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` 调色盘，实现统一的莫兰蒂主题。

## 页面与组件使用

### 导航页面

- 组合 `NavigationGrid` 与 `NavigationCard` 构建入口矩阵。
- 支持自定义列数、动画延迟与卡片主题，适用于首页、功能导航等场景。

### 报告页面

- 使用 `ReportSection` 划分章节，搭配 `MetricCard`、`MetricsGrid` 展示核心指标。
- 支持深色渐变背景与滚动触发动画，适合数据报告、分析仪表盘。

### 通用组件

- `Container`：多种视觉变体（glass、solid、outline）与尺寸可选。
- `AnimatedElement`：封装 8 种滚动动画，支持延迟与持续时间配置。
- `Header`：响应滚动的智能页眉，移动端自适应。

## 设计与交互

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

## 开发流程

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

## 部署流程

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

## 调试技巧

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

## 技术栈

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

## 贡献指南

欢迎提交 Issue 或 Pull Request 改进项目。建议遵循以下流程：

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

<!-- ...existing code... -->