# Web 端技术选型 PRD

## 背景

eryao 项目需要建设 Web 端。移动端已有 Flutter 应用（iOS/Android），后端为 Python FastAPI + Supabase。Pencil 设计稿已完成（`web/design/eryao.pen`），包含 19 个页面。

## 设计稿分析

### 页面分类

**营销/公开页面**（需要 SEO）：
- Landing Page — Hero + Showcase + Testimonials + CTA + Footer
- Features Page — 功能特性展示
- Pricing Page — 定价方案卡片
- About Page — 关于我们 + 法律声明
- Privacy Policy Page
- Terms of Service Page

**Dashboard/应用页面**（Auth 后 SPA）：
- Login Page — 登录表单卡片
- Dashboard — 侧边栏(260px) + 主区域(1180px) 布局
- NotificationPage — 通知列表
- 其余 9 个页面（待展开）

### 设计特征
- 宽度 1440px，桌面端为主
- 色系：紫色主色(#7C3AED)、深蓝底色(#0F172A/#020617)、白色/浅灰背景
- 渐变背景（linear-gradient）、圆角(16px)、阴影(blur 24px)
- 全部色值来自 Tailwind CSS 默认色板
- i18n 支持：zh / zh_Hant / en（与移动端一致）

## 技术选型

### 决策：Astro 5 + React + Tailwind CSS 4 + shadcn/ui

### 选型理由

#### 1. Astro 5 作为框架

| 考量 | 结论 |
|------|------|
| 营销页 SEO | Astro 默认零 JS 输出，SSG 开箱即用，SEO 最优 |
| Dashboard SPA | React islands 模式，客户端全功能渲染 |
| 安全性 | 静态生成，无服务端运行时，攻击面极小 |
| 无已知 CVE | 搜索未发现 Astro 框架本身的 CVE 记录 |

**为什么不用 Next.js：**
- CVE-2025-55182（CVSS 10.0 "React2Shell"）RCE，已被武器化
- CVE-2025-29927 中间件鉴权绕过
- CVE-2025-66478 Next.js 对应编号，766 台主机被入侵
- Server Components 攻击面大，对于本项目过度设计

**为什么不用 Vite + React SPA：**
- 营销页 SEO 差，需要额外 SSR 方案
- 两个场景（营销+应用）用一套框架更简洁

#### 2. React 作为交互层

- shadcn/ui 原生 React，组件覆盖度最高
- Astro islands 一等公民支持
- 生态最大，Dashboard 复杂交互组件丰富

**关于 CVE-2025-55182：**
该漏洞仅影响 React Server Components（RSC），即 Next.js App Router 服务端渲染场景。我们的架构使用 Astro SSG + React 客户端 islands，不使用 RSC，漏洞不适用。

#### 3. Tailwind CSS 4

- 设计稿色值全部来自 Tailwind 色板，零适配成本
- 渐变、flexbox、阴影、圆角全部原生支持
- 无已知直接漏洞（Snyk 确认）
- v4 已修复 v3 的 glob 传递依赖问题

#### 4. shadcn/ui

- 源码级复制，可完全自定义，无锁定
- Card / Button / Input / Form / Sidebar 等组件与设计稿高度吻合
- 无已知直接漏洞（Snyk 确认）
- 只使用官方 registry，避免第三方 registry 注入风险

### 架构概览

```
web/
├── src/
│   ├── components/        # 共享 UI 组件（shadcn/ui + 自定义）
│   │   ├── ui/            # shadcn/ui 组件
│   │   ├── Navbar.astro   # 营销页导航栏
│   │   ├── Footer.astro   # 营销页页脚
│   │   └── Sidebar.tsx    # Dashboard 侧边栏（React island）
│   ├── layouts/
│   │   ├── Marketing.astro    # 营销页布局（Navbar + Footer）
│   │   └── Dashboard.astro    # Dashboard 布局（Sidebar + Main）
│   ├── pages/
│   │   ├── index.astro        # Landing Page
│   │   ├── features.astro     # Features Page
│   │   ├── pricing.astro      # Pricing Page
│   │   ├── about.astro        # About Page
│   │   ├── privacy.astro      # Privacy Policy
│   │   ├── terms.astro        # Terms of Service
│   │   ├── login.astro        # Login Page（含 React island）
│   │   └── dashboard/
│   │       ├── index.astro    # Dashboard（含 React island）
│   │       └── notifications.astro
│   └── styles/
│       └── global.css         # Tailwind 入口
├── astro.config.mjs
├── tailwind.config.ts
├── tsconfig.json
└── package.json
```

### API 集成

- 后端：FastAPI（已有）
- Auth：Supabase Auth JS SDK（客户端）
- 数据：通过 FastAPI REST API + Supabase JS SDK

### i18n 方案

- 使用 `astro-i18next` 或 `@astrolicious/i18n` 处理 Astro 页面
- React islands 使用 `react-i18next`
- 翻译文件与移动端共享（zh / zh_Hant / en）

### 部署

- 营销页：SSG 静态部署（Vercel / Cloudflare Pages / 自托管）
- Dashboard SPA：同一构建产物，客户端渲染
- 无需 Node.js 服务端运行时

## 验收标准

- [ ] 所有设计稿页面可在浏览器中像素级还原
- [ ] 营销页 Lighthouse SEO 评分 >= 95
- [ ] Dashboard 侧边栏导航和主区域交互正常
- [ ] i18n 三语言切换正常
- [ ] 无安全漏洞（npm audit clean）
- [ ] 设计稿中所有渐变、阴影、圆角、布局精确匹配