# 前端架构

**我是卡若。**

前端就是项目的脸。用户不管是通过朋友圈、抖音还是私域进来，第一眼看到的就是这个页面。如果加载慢、长得丑、滑动卡，人家转头就走，我的流量就浪费了。

所以，前端的核心目标只有一个：**极致的移动端阅读体验，像原生 App 一样丝滑。**

## 1. 技术底座

别跟我说什么技术先进，我要的是**稳**和**快**。

-   **框架**: Next.js 14 (App Router) - 必须用最新的 App Router，路由管理更清晰。
-   **语言**: TypeScript - 必须用 TS，类型安全，少出低级 Bug。
-   **样式**: Tailwind CSS - 写样式最快，没有之一。配合 `globals.css` 做全局控制。
-   **UI 组件库**: Shadcn UI (基于 Radix UI) + Vant UI (风格参考)。
    -   *注意*：我们要像素级复刻 iOS 风格，字体用 San Francisco，圆角、阴影都要对齐。

## 2. 目录结构（我的地盘）

前端代码主要集中在 `app/` 和 `components/`。

\`\`\`
app/
├── (routes)/               # 路由组，逻辑隔离
│   ├── page.tsx            # 首页：封面、简介、购买按钮
│   ├── chapters/           # 目录页：章节列表
│   ├── read/[id]/          # 阅读页：核心体验区
│   ├── my/                 # 个人中心：购买记录、分销
│   ├── admin/              # 管理后台：给自己用的
│   └── documentation/      # 文档生成：内部工具
├── layout.tsx              # 全局布局：导航栏、SEO Meta
├── globals.css             # 全局样式
└── error.tsx               # 错误处理页面

components/
├── ui/                     # 通用组件 (Button, Input, Skeleton)
├── modules/                # 业务模块组件 (新增)
│   ├── auth/               # 认证模块 (AuthModal)
│   ├── payment/            # 支付模块 (PaymentModal)
│   ├── marketing/          # 营销模块 (QRCodeModal)
│   └── referral/           # 分销模块 (ReferralShare)
├── book-cover.tsx          # 书籍封面展示
├── chapter-content.tsx     # 章节内容渲染器
├── bottom-nav.tsx          # 底部导航栏 (手机端核心)
└── theme-provider.tsx      # 主题管理 (深色/浅色模式)
\`\`\`

## 2.1 业务模块化 (Modularization)

为了支持“云阿米巴”模式的快速迭代，我们将核心业务逻辑封装为独立模块：

- **支付模块 (Payment)**: 统一管理微信、支付宝、USDT 等支付方式，支持整书/单章购买。
- **营销模块 (Marketing)**: 负责引流（如二维码弹窗、倒计时Banner），连接私域流量池。
- **分销模块 (Referral)**: 负责裂变传播（如分享按钮、返利计算），让用户帮我们卖书。
- **认证模块 (Auth)**: 统一的用户登录与权限校验。

这种设计允许我们在不修改页面核心逻辑的情况下，插拔不同的变现策略。

## 3. 核心交互设计

### 3.1 骨架屏 (Skeleton)
**规则**：凡是需要加载数据的地方，必须先展示骨架屏。
- 用户不能看白屏，哪怕等 0.5 秒，也要让他看到“东西正在来”的样子。
- 强制引入 `Skeleton` 组件。

### 3.2 路由动画 (Transition)
**规则**：页面切换不能生硬地跳。
- 使用 Framer Motion 或 CSS Transition。
- 模拟 iOS 的滑动切换或淡入淡出。

### 3.3 阅读体验
- **字体**：针对不同设备优化，保证字号适中，行间距舒服（建议 1.6-1.8）。
- **图片**：懒加载 (Lazy Load)，点击可放大预览。
- **代码块**：虽然是书，但如果有代码，要有高亮和复制按钮。

## 4. 数据获取 (Fetching)

- **服务端组件 (Server Components)**：
    - `page.tsx`, `read/[id]/page.tsx` 默认都是服务端组件。
    - 直接在组件内 `await` 获取数据（通过 `lib/book-data.ts`），SEO 极佳。
- **客户端组件 (Client Components)**：
    - 需要交互的（点击、弹窗、状态变化），头部加 `'use client'`。
    - 比如 `auth-modal.tsx`, `purchase-section.tsx`。

## 5. 待办事项 (Todo)

- [ ] 全局引入 Skeleton，替换掉所有的 `Loading...` 文字。
- [ ] 检查所有页面的 Mobile 适配，在 Chrome 开发者工具里用 iPhone SE 和 iPhone 14 Pro Max 两个尺寸测。
- [ ] 优化字体栈，确保在安卓上也不难看。

---
**总结**：
前端不仅是写代码，是**做产品**。每一个像素的偏移都影响用户的信任感。把细节抠好，转化率自然就高了。