# Lurmix 网站重构架构文档

**项目名称**: Lurmix 品牌官网  
**版本**: 2.0  
**创建日期**: 2026-06-03  
**状态**: 架构设计阶段

---

## 一、项目定位

### 1.1 项目类型
- **静态品牌官网** - 主要用于品牌展示和产品介绍
- **纯前端项目** - 无后端依赖，内容写死在代码中
- **低维护成本** - 内容很少更新，适合静态生成

### 1.2 核心目标
- 高性能加载（首屏 < 1s）
- SEO 友好（静态 HTML + 元标签优化）
- 组件化复用（减少重复代码）
- 类型安全（Content Collections）
- 易于维护（模块化结构）

---

## 二、技术栈

### 2.1 核心技术
| 技术 | 版本 | 用途 |
|------|------|------|
| **Astro** | ^4.x | 静态站点生成器，组件化框架 |
| **Tailwind CSS** | ^3.x | 工具类优先的 CSS 框架 |
| **Alpine.js** | ^3.x | 轻量级交互式框架（2KB） |
| **JavaScript** | ES2022+ | 脚本语言（不使用 TypeScript） |

### 2.2 构建工具
- **Vite** - Astro 内置，极速构建
- **PostCSS** - Tailwind CSS 依赖
- **Sharp** - 图片优化（Astro 内置）

### 2.3 部署平台
- **Cloudflare Pages** - 静态托管 + CDN

---

## 三、项目架构

### 3.1 技术架构图
```
┌─────────────────────────────────────────────┐
│          Cloudflare Pages (CDN)             │
└─────────────────────────────────────────────┘
                    ▲
                    │ 部署
                    │
┌─────────────────────────────────────────────┐
│         Astro Build (Static HTML)           │
│  ┌─────────────────────────────────────┐   │
│  │  Pages (.astro)                     │   │
│  │  ├─ Home                            │   │
│  │  ├─ Products (AI Toys/Companion)    │   │
│  │  ├─ About / Contact                 │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Components (.astro)                │   │
│  │  ├─ Layout (Header/Footer)          │   │
│  │  ├─ UI (Button/Card/Section)        │   │
│  │  └─ Business (ProductCard/Form)     │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Content Collections                │   │
│  │  ├─ products.json                   │   │
│  │  ├─ features.json                   │   │
│  │  └─ testimonials.json               │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Styles                             │   │
│  │  ├─ Tailwind Config (Design System) │   │
│  │  └─ Custom CSS (动画/特效)          │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Scripts                            │   │
│  │  ├─ Alpine.js (交互)                │   │
│  │  └─ Utils (工具函数)                │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
```

### 3.2 目录结构
```
lurmix-web/
├── src/
│   ├── pages/                    # 页面路由
│   │   ├── index.astro          # 首页
│   │   ├── products/            # 产品模块
│   │   │   ├── ai-toys.astro
│   │   │   ├── ai-companion.astro
│   │   │   └── badges.astro
│   │   ├── about/               # 关于模块
│   │   │   └── index.astro
│   │   └── contact/             # 联系模块
│   │       └── index.astro
│   │
│   ├── layouts/                 # 布局组件
│   │   ├── BaseLayout.astro     # 基础布局（含 Head/SEO）
│   │   ├── Header.astro         # 顶部导航
│   │   └── Footer.astro         # 页脚
│   │
│   ├── components/              # 可复用组件
│   │   ├── ui/                  # 通用 UI 组件
│   │   │   ├── Button.astro
│   │   │   ├── Card.astro
│   │   │   ├── Section.astro
│   │   │   └── Badge.astro
│   │   ├── home/                # 首页专属组件
│   │   │   ├── Hero.astro
│   │   │   ├── TrustIndicators.astro
│   │   │   └── ProductSeries.astro
│   │   ├── products/            # 产品页组件
│   │   │   ├── ProductCard.astro
│   │   │   ├── ProductFeatures.astro
│   │   │   └── ProductSpecs.astro
│   │   ├── about/               # 关于页组件
│   │   │   ├── TeamSection.astro
│   │   │   └── TestimonialCard.astro
│   │   └── contact/             # 联系页组件
│   │       └── ContactForm.astro
│   │
│   ├── content/                 # 内容集合（类型安全）
│   │   ├── config.js            # Content Collections 配置
│   │   ├── products/            # 产品数据
│   │   │   ├── ai-toys.json
│   │   │   ├── ai-companion.json
│   │   │   └── badges.json
│   │   ├── features/            # 技术特性
│   │   │   └── tech-features.json
│   │   ├── testimonials/        # 用户评价
│   │   │   └── reviews.json
│   │   └── company/             # 公司信息
│   │       └── team.json
│   │
│   ├── styles/                  # 样式文件
│   │   ├── global.css           # 全局样式（Tailwind 导入）
│   │   └── animations.css       # 自定义动画
│   │
│   ├── scripts/                 # JavaScript 模块
│   │   ├── navigation.js        # 导航交互
│   │   ├── scroll.js            # 滚动效果
│   │   └── utils.js             # 工具函数
│   │
│   └── assets/                  # 静态资源
│       ├── images/              # 图片
│       └── icons/               # 图标/SVG
│
├── public/                      # 公共静态文件（直接复制）
│   ├── favicon.ico
│   └── robots.txt
│
├── astro.config.mjs             # Astro 配置
├── tailwind.config.mjs          # Tailwind 配置（设计系统）
├── package.json
└── ARCHITECTURE.md              # 本文档
```

---

## 四、组件架构

### 4.1 组件分层

#### L1 - 布局层（Layouts）
```
BaseLayout.astro
├─ 包含: <html>, <head>, SEO meta
├─ 插槽: <slot />
└─ 依赖: Header, Footer

Header.astro
├─ 功能: 导航栏、移动菜单
├─ 交互: Alpine.js (菜单切换)
└─ 样式: 固定定位、毛玻璃效果

Footer.astro
├─ 功能: 链接导航、社交媒体、版权
└─ 样式: 多栏布局
```

#### L2 - 通用组件层（UI Components）
```
Button.astro
├─ Props: variant (primary/secondary), size, href
└─ 样式: Tailwind classes

Card.astro
├─ Props: title, image, description
└─ 样式: 悬停动画、阴影

Section.astro
├─ Props: title, subtitle, background
└─ 功能: 统一的 section 容器

Badge.astro
├─ Props: text, color
└─ 样式: 小标签组件
```

#### L3 - 业务组件层（Business Components）
```
ProductCard.astro
├─ Props: product (from Content Collection)
├─ 显示: 图片、名称、价格、特性、CTA
└─ 复用: 3 个产品页

ContactForm.astro
├─ 功能: 表单验证（Alpine.js）
├─ 字段: 姓名、邮箱、电话、留言
└─ 样式: 响应式布局

TestimonialCard.astro
├─ Props: testimonial (from Content Collection)
└─ 显示: 头像、评价、用户信息

Hero.astro
├─ 功能: 首页大标题、CTA、视觉效果
└─ 样式: 全屏高度、渐变背景
```

### 4.2 组件通信
```
Pages (路由)
  ↓ 使用
Layouts (BaseLayout)
  ↓ 嵌入
Components (UI/Business)
  ↓ 读取
Content Collections (数据)
```

---

## 五、设计系统

### 5.1 Tailwind 配置结构
```javascript
// tailwind.config.mjs
export default {
  theme: {
    extend: {
      colors: {
        primary: {        // 品牌主色（智能蓝）
          50: '#e6f2ff',
          100: '#cce5ff',
          // ... 完整色阶
          900: '#001a33',
        },
        secondary: {      // 辅助色（温暖橙）
          // ...
        },
        accent: {         // 强调色（活力紫）
          // ...
        },
        neutral: {        // 中性灰
          // ...
        }
      },
      fontFamily: {
        display: ['Playfair Display', 'serif'],   // 标题
        body: ['Inter', 'sans-serif'],            // 正文
      },
      spacing: {
        // 基于 4px 网格
      },
      borderRadius: {
        // 统一圆角系统
      },
      boxShadow: {
        // 阴影层级
      },
      animation: {
        // 自定义动画
      }
    }
  }
}
```

### 5.2 设计 Token 映射
| 旧系统 (CSS 变量) | 新系统 (Tailwind) |
|-------------------|-------------------|
| `--color-primary-500` | `bg-primary-500` |
| `--font-display` | `font-display` |
| `--space-lg` | `p-8` |
| `--radius-xl` | `rounded-2xl` |
| `--shadow-md` | `shadow-md` |

---

## 六、数据架构

### 6.1 Content Collections 结构

#### products/ai-toys.json
```json
[
  {
    "id": "dream-speaker-pro",
    "name": "梦语者 Pro",
    "category": "ai-toys",
    "price": 499,
    "image": "/images/products/dream-speaker.jpg",
    "description": "智能伴读台灯...",
    "features": [
      "AI 语音对话",
      "智能护眼",
      "海量童书资源"
    ],
    "specs": {
      "battery": "5000mAh",
      "connectivity": "WiFi + 蓝牙",
      "ageRange": "3-12岁"
    }
  }
]
```

#### features/tech-features.json
```json
[
  {
    "id": "nlp",
    "title": "自然语言处理",
    "icon": "brain",
    "description": "..."
  }
]
```

#### testimonials/reviews.json
```json
[
  {
    "id": "1",
    "author": "张女士",
    "role": "7岁家长",
    "avatar": "/images/avatars/zhang.jpg",
    "content": "...",
    "rating": 5
  }
]
```

### 6.2 数据访问方式
```javascript
// 在 .astro 文件中
import { getCollection } from 'astro:content';

const aiToys = await getCollection('products', ({ data }) => {
  return data.category === 'ai-toys';
});
```

---

## 七、交互设计

### 7.1 Alpine.js 使用场景

#### 移动端菜单
```html
<nav x-data="{ open: false }">
  <button @click="open = !open">Menu</button>
  <div x-show="open" x-transition>
    <!-- 菜单内容 -->
  </div>
</nav>
```

#### 表单验证
```html
<form x-data="{ 
  email: '', 
  isValid() { return this.email.includes('@') }
}">
  <input x-model="email" type="email">
  <span x-show="!isValid()" x-transition>
    请输入有效邮箱
  </span>
</form>
```

#### FAQ 手风琴
```html
<div x-data="{ active: null }">
  <div @click="active = active === 1 ? null : 1">
    <h3>问题 1</h3>
    <div x-show="active === 1" x-collapse>答案</div>
  </div>
</div>
```

### 7.2 滚动效果
```javascript
// src/scripts/scroll.js
// 导航栏背景变化
// 元素淡入动画（Intersection Observer）
// 平滑滚动锚点
```

---

## 八、性能优化

### 8.1 Astro 内置优化
- ✅ **零 JS 默认** - 组件默认无客户端 JS
- ✅ **自动代码分割** - 按路由拆分
- ✅ **图片优化** - `<Image>` 组件自动压缩
- ✅ **CSS 内联** - 关键 CSS 内联到 `<head>`

### 8.2 手动优化策略
- **字体优化**: Google Fonts + `display=swap`
- **图片格式**: WebP + 降级方案
- **懒加载**: `loading="lazy"` 属性
- **预加载**: 关键资源 `<link rel="preload">`

### 8.3 目标指标
| 指标 | 目标值 |
|------|--------|
| FCP (首次内容绘制) | < 1.0s |
| LCP (最大内容绘制) | < 2.5s |
| CLS (累积布局偏移) | < 0.1 |
| TTI (可交互时间) | < 3.0s |

---

## 九、SEO 策略

### 9.1 元标签配置
```astro
---
// BaseLayout.astro
const { title, description, image } = Astro.props;
---
<head>
  <title>{title} | Lurmix</title>
  <meta name="description" content={description}>
  <meta property="og:title" content={title}>
  <meta property="og:description" content={description}>
  <meta property="og:image" content={image}>
  <meta name="twitter:card" content="summary_large_image">
</head>
```

### 9.2 结构化数据
```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "梦语者 Pro",
  "brand": "Lurmix",
  "offers": {
    "@type": "Offer",
    "price": "499",
    "priceCurrency": "CNY"
  }
}
```

### 9.3 Sitemap & Robots
- Astro 自动生成 `sitemap.xml`
- `robots.txt` 配置抓取规则

---

## 十、构建与部署

### 10.1 开发流程
```bash
# 安装依赖
npm install

# 开发模式（热重载）
npm run dev          # http://localhost:4321

# 预览构建
npm run build        # 输出到 dist/
npm run preview      # 本地预览静态文件
```

### 10.2 部署流程（Cloudflare Pages）
```yaml
# 自动部署配置
Build command: npm run build
Build output directory: dist
Node version: 20

# 环境变量
PUBLIC_SITE_URL: https://lurmix.com
```

### 10.3 分支策略
- `main` - 生产环境（自动部署）
- `dev` - 开发分支
- `feature/*` - 功能分支

---

## 十一、迁移步骤

### 阶段 1: 项目初始化 (1天)
- [ ] 创建 Astro 项目
- [ ] 安装 Tailwind + Alpine.js
- [ ] 配置 Tailwind 设计系统
- [ ] 创建目录结构

### 阶段 2: 布局与通用组件 (1天)
- [ ] BaseLayout + Header + Footer
- [ ] Button, Card, Section 等 UI 组件
- [ ] 全局样式和动画

### 阶段 3: 首页开发 (1天)
- [ ] Hero 组件
- [ ] TrustIndicators 组件
- [ ] ProductSeries 组件
- [ ] CTA Section

### 阶段 4: 产品页开发 (2天)
- [ ] Content Collections 配置
- [ ] ProductCard 组件
- [ ] AI Toys 页面
- [ ] AI Companion 页面
- [ ] Badges 页面

### 阶段 5: 其他页面 (1天)
- [ ] About 页面
- [ ] Contact 页面
- [ ] ContactForm 组件

### 阶段 6: 交互与优化 (1天)
- [ ] Alpine.js 交互实现
- [ ] 滚动效果
- [ ] 图片优化
- [ ] SEO 配置

### 阶段 7: 测试与部署 (1天)
- [ ] 响应式测试（手机/平板/桌面）
- [ ] 浏览器兼容测试
- [ ] 性能测试（Lighthouse）
- [ ] 部署到 Cloudflare Pages

**总计**: 约 8 个工作日

---

## 十二、风险与挑战

### 12.1 技术风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Astro 学习曲线 | 中 | 官方文档完善，社区活跃 |
| Alpine.js 功能限制 | 低 | 需求简单，足够使用 |
| Tailwind 样式迁移工作量 | 中 | 有完整设计系统可参考 |

### 12.2 业务风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 内容不完整 | 低 | 已有完整的旧版内容 |
| 图片资源缺失 | 中 | 优先用占位符，逐步替换 |

---

## 十三、扩展性考虑

### 未来可能的扩展
1. **国际化（i18n）** - Astro 支持多语言路由
2. **CMS 集成** - 可接入 Strapi/Contentful
3. **动态评论** - 集成 Disqus/Giscus
4. **表单后端** - 集成 Formspree/Netlify Forms
5. **分析工具** - Google Analytics / Plausible

### 架构兼容性
- ✅ 支持平滑迁移到 CMS（Content Collections 易改）
- ✅ 支持添加 React/Vue 岛屿组件（Astro Islands）
- ✅ 支持 SSR（可切换到 Node/Deno/Cloudflare Workers）

---

## 十四、参考资源

### 官方文档
- [Astro 官方文档](https://docs.astro.build)
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
- [Alpine.js 文档](https://alpinejs.dev/)

### 设计灵感
- Apple 官网 - 简约美学
- Dyson 官网 - 高端品牌感
- Vercel 官网 - 现代 Web 设计

### 工具
- Figma - 设计稿（如需）
- Lighthouse - 性能测试
- WebPageTest - 详细性能分析

---

## 附录

### A. 技术决策记录

#### ADR-001: 选择 Astro 而非 Next.js
**背景**: 需要静态站点生成器  
**决策**: 使用 Astro  
**理由**: 
- 纯静态内容无需 React 运行时
- Astro 零 JS 默认，性能更好
- 模板语法更简洁
- 构建速度更快

#### ADR-002: 使用 Alpine.js 而非 Vue
**背景**: 需要轻量级交互  
**决策**: 使用 Alpine.js  
**理由**:
- 仅 2KB，性能最优
- 声明式语法，易学
- 无需构建步骤
- 与 Tailwind 配合默契

#### ADR-003: Tailwind 配置自定义 Token
**背景**: 需要保持设计系统一致性  
**决策**: 在 `tailwind.config.mjs` 定义品牌色  
**理由**:
- 避免散乱的颜色值
- 易于全局修改
- 语义化命名（bg-primary）
- 类型提示友好

---

**文档版本**: 1.0  
**最后更新**: 2026-06-03  
**负责人**: 开发团队  
**审批状态**: ✅ 已确认