更新

2026-01-28 17:22:31 +08:00
parent ee8cb9cfd2
commit 4a3dd2b225
46 changed files with 12739 additions and 287 deletions
--- a/Docs/FRONTEND_DEV.md
+++ b/Docs/FRONTEND_DEV.md
@@ -0,0 +1,182 @@
+# 前端开发规范
+
+## 目录结构
+
+```
+frontend/src/
+├── app/                # Next.js App Router 页面
+│   ├── page.tsx        # 首页（视频生成）
+│   ├── publish/        # 发布页面
+│   ├── admin/          # 管理员页面
+│   ├── login/          # 登录页面
+│   └── register/       # 注册页面
+├── lib/                # 公共工具函数
+│   ├── axios.ts        # Axios 实例（含 401/403 拦截器）
+│   └── auth.ts         # 认证相关函数
+└── proxy.ts            # 路由代理（原 middleware）
+```
+
+---
+
+## iOS Safari 安全区域兼容
+
+### 问题
+iPhone Safari 浏览器顶部（刘海/灵动岛）和底部（Home 指示条）有安全区域，默认情况下页面背景不会延伸到这些区域，导致白边。
+
+### 解决方案（三层配合）
+
+#### 1. Viewport 配置 (`layout.tsx`)
+```typescript
+import type { Viewport } from "next";
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  viewportFit: 'cover',    // 允许内容延伸到安全区域
+  themeColor: '#0f172a',   // 顶部状态栏颜色（与背景一致）
+};
+```
+
+#### 2. 全局背景统一到 body (`layout.tsx`)
+```tsx
+<html lang="en" style={{ backgroundColor: '#0f172a' }}>
+  <body
+    style={{
+      margin: 0,
+      minHeight: '100dvh',  // 使用 dvh 而非 vh
+      background: 'linear-gradient(to bottom, #0f172a 0%, #0f172a 5%, #581c87 50%, #0f172a 95%, #0f172a 100%)',
+    }}
+  >
+    {children}
+  </body>
+</html>
+```
+
+#### 3. CSS 安全区域支持 (`globals.css`)
+```css
+html {
+  background-color: #0f172a !important;
+  min-height: 100%;
+}
+
+body {
+  margin: 0 !important;
+  min-height: 100dvh;
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+### 关键要点
+- **渐变背景放 body，不放页面 div** - 安全区域在 div 之外
+- **使用 `100dvh` 而非 `100vh`** - dvh 是动态视口高度，适配移动端
+- **themeColor 与背景边缘色一致** - 避免状态栏色差
+- **页面 div 移除独立背景** - 使用透明，继承 body 渐变
+
+---
+
+## 移动端响应式规范
+
+### Header 按钮布局
+```tsx
+// 移动端紧凑，桌面端宽松
+<div className="flex items-center gap-1 sm:gap-4">
+  <button className="px-2 sm:px-4 py-1 sm:py-2 text-sm sm:text-base ...">
+    按钮
+  </button>
+</div>
+```
+
+### 常用响应式断点
+| 断点 | 宽度 | 用途 |
+|------|------|------|
+| 默认 | < 640px | 移动端 |
+| `sm:` | ≥ 640px | 平板/桌面 |
+| `lg:` | ≥ 1024px | 大屏桌面 |
+
+---
+
+## API 请求规范
+
+### 必须使用 `api` (axios 实例)
+
+所有需要认证的 API 请求**必须**使用 `@/lib/axios` 导出的 axios 实例。该实例已配置：
+- 自动携带 `credentials: include`
+- 遇到 401/403 时自动清除 cookie 并跳转登录页
+
+**使用方式：**
+
+```typescript
+import api from '@/lib/axios';
+
+// GET 请求
+const { data } = await api.get('/api/materials');
+
+// POST 请求
+const { data } = await api.post('/api/videos/generate', {
+    text: '...',
+    voice: '...',
+});
+
+// DELETE 请求
+await api.delete(`/api/materials/${id}`);
+
+// 带上传进度的文件上传
+await api.post('/api/materials', formData, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+    onUploadProgress: (e) => {
+        if (e.total) {
+            const progress = Math.round((e.loaded / e.total) * 100);
+            setProgress(progress);
+        }
+    },
+});
+```
+
+### SWR 配合使用
+
+```typescript
+import api from '@/lib/axios';
+
+// SWR fetcher 使用 axios
+const fetcher = (url: string) => api.get(url).then(res => res.data);
+
+const { data } = useSWR('/api/xxx', fetcher, { refreshInterval: 2000 });
+```
+
+---
+
+## 日期格式化规范
+
+### 禁止使用 `toLocaleString()`
+
+`toLocaleString()` 在服务端和客户端可能返回不同格式，导致 Hydration 错误。
+
+**错误示例：**
+```typescript
+// ❌ 会导致 Hydration 错误
+new Date(timestamp * 1000).toLocaleString('zh-CN')
+```
+
+**正确做法：**
+```typescript
+// ✅ 使用固定格式
+const formatDate = (timestamp: number) => {
+    const d = new Date(timestamp * 1000);
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    const hour = String(d.getHours()).padStart(2, '0');
+    const minute = String(d.getMinutes()).padStart(2, '0');
+    return `${year}/${month}/${day} ${hour}:${minute}`;
+};
+```
+
+---
+
+## 新增页面 Checklist
+
+1. [ ] 导入 `import api from '@/lib/axios'`
+2. [ ] 所有 API 请求使用 `api.get/post/delete()` 而非原生 `fetch`
+3. [ ] 日期格式化使用固定格式函数，不用 `toLocaleString()`
+4. [ ] 添加 `'use client'` 指令（如需客户端交互）