整理一下,分出前端后端public

This commit is contained in:
Jiao77
2025-10-22 18:54:50 +08:00
parent 4919bc6194
commit 3214b2fde8
34 changed files with 628 additions and 8128 deletions

156
README.md
View File

@@ -1,156 +0,0 @@
<!-- ...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... -->