zl-q
c12320cb79
Replace static HTML website with Astro SSG framework: - Astro 6 + React 19 (client islands) + Tailwind CSS 4 + shadcn/ui - i18n: zh/zh_Hant/en with URL prefix routing - Pages: Landing, Features, Pricing, About, Privacy, Terms (3 locales) - Responsive full-width layout with scroll reveal animations - Cyber gradient theme with particle effects inspired by Kimi - Features page: alternating layout with hexagram illustrations - Legal pages: markdown rendering with side info card - Language switcher preserves current page path - Assets shared via symlinks to web/design/assets/ (no duplication) Tech decisions documented in .trellis/spec/web/index.md Task: .trellis/tasks/05-08-web-astro-react-tailwind-shadcn-ui
138 lines
4.9 KiB
Markdown
138 lines
4.9 KiB
Markdown
# 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）
|
||
- [ ] 设计稿中所有渐变、阴影、圆角、布局精确匹配
|