xiaoxia-saas/docs/PHASE6-DESIGN.md

Phase 6: 前端完善 - 详细设计文档

版本：v1.0
创建时间：2026-06-17
负责人：小虾 🦐
预计时间：4-6 周

---

📋 目标

在 Phase 4 完成的后端 API 基础上，构建完整的前端用户界面，让用户可以通过图形化界面使用所有 SaaS 功能。

---

🎯 核心目标

1. 用户认证界面 - 注册/登录/密码管理
2. 工作空间管理 - 创建/管理工作空间和成员
3. 订阅管理界面 - 查看/升级/管理订阅
4. Admin 后台 - 系统管理和数据监控
5. 响应式设计 - 支持桌面/平板/移动端

---

🛠️ 技术栈选型

前端框架

选择：React 18 + TypeScript

理由：

• 生态成熟，组件丰富
• TypeScript 提供类型安全
• 与后端 API 配合良好
• 社区活跃，文档完善

替代方案：

• Vue 3 + TypeScript（更简单，但生态相对小）
• Next.js 14（支持 SSR，适合 SEO）

UI 组件库

选择：Ant Design 5.x

理由：

• 企业级 UI 组件
• 中文文档完善
• 开箱即用的表单/表格/布局
• 符合国内用户习惯

替代方案：

• Material-UI（更现代，但学习曲线陡）
• Chakra UI（轻量，但组件不够丰富）
• shadcn/ui（新兴，基于 Tailwind）

状态管理

选择：Zustand

理由：

• 轻量简单
• TypeScript 友好
• 无需 Provider 包裹
• 学习成本低

替代方案：

• Redux Toolkit（功能强大，但复杂）
• Jotai/Recoil（原子化状态，适合大型应用）

路由

选择：React Router v6

HTTP 客户端

选择：Axios + React Query

理由：

• Axios：成熟稳定，拦截器方便
• React Query：自动缓存、重试、分页支持

表单管理

选择：React Hook Form + Zod

理由：

• React Hook Form：性能优秀，API 简洁
• Zod：TypeScript 友好的 schema 验证

样式方案

选择：CSS Modules + Tailwind CSS

构建工具

选择：Vite

理由：

• 开发服务器极快
• 原生 ES 模块支持
• 完美支持 React + TypeScript

---

📐 项目结构

apps/web/
├── src/
│   ├── api/              # API 调用封装
│   │   ├── auth.ts       # 认证相关 API
│   │   ├── workspace.ts  # 工作空间 API
│   │   ├── subscription.ts
│   │   └── client.ts     # Axios 实例配置
│   ├── components/       # 可复用组件
│   │   ├── common/       # 通用组件
│   │   │   ├── Button/
│   │   │   ├── Modal/
│   │   │   └── Table/
│   │   ├── layout/       # 布局组件
│   │   │   ├── Header/
│   │   │   ├── Sidebar/
│   │   │   └── Footer/
│   │   └── business/     # 业务组件
│   │       ├── WorkspaceCard/
│   │       ├── MemberList/
│   │       └── SubscriptionPlan/
│   ├── pages/            # 页面组件
│   │   ├── auth/         # 认证页面
│   │   │   ├── Login.tsx
│   │   │   ├── Register.tsx
│   │   │   ├── ForgotPassword.tsx
│   │   │   └── ResetPassword.tsx
│   │   ├── workspace/    # 工作空间页面
│   │   │   ├── List.tsx
│   │   │   ├── Detail.tsx
│   │   │   └── Members.tsx
│   │   ├── subscription/ # 订阅页面
│   │   │   ├── Plans.tsx
│   │   │   ├── Upgrade.tsx
│   │   │   └── Billing.tsx
│   │   ├── admin/        # 管理后台
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Users.tsx
│   │   │   └── Analytics.tsx
│   │   └── profile/      # 个人中心
│   │       ├── Settings.tsx
│   │       └── Account.tsx
│   ├── hooks/            # 自定义 Hooks
│   │   ├── useAuth.ts
│   │   ├── useWorkspace.ts
│   │   └── useSubscription.ts
│   ├── store/            # 状态管理
│   │   ├── authStore.ts
│   │   ├── workspaceStore.ts
│   │   └── uiStore.ts
│   ├── types/            # TypeScript 类型定义
│   │   ├── auth.ts
│   │   ├── workspace.ts
│   │   └── api.ts
│   ├── utils/            # 工具函数
│   │   ├── request.ts    # HTTP 请求封装
│   │   ├── storage.ts    # LocalStorage 封装
│   │   ├── validator.ts  # 表单验证
│   │   └── format.ts     # 格式化函数
│   ├── router/           # 路由配置
│   │   └── index.tsx
│   ├── styles/           # 全局样式
│   │   ├── global.css
│   │   └── variables.css
│   ├── App.tsx
│   ├── main.tsx
│   └── vite-env.d.ts
├── public/
│   └── assets/
├── index.html
├── vite.config.ts
├── tsconfig.json
├── tailwind.config.js
└── package.json

---

🎨 设计规范

1. 色彩系统

主色调：

--primary: #1890ff;     /* 品牌蓝 */
--primary-hover: #40a9ff;
--primary-active: #096dd9;

--success: #52c41a;     /* 成功绿 */
--warning: #faad14;     /* 警告黄 */
--error: #ff4d4f;       /* 错误红 */
--info: #1890ff;        /* 信息蓝 */

中性色：

--text-primary: #262626;
--text-secondary: #595959;
--text-disabled: #bfbfbf;

--bg-primary: #ffffff;
--bg-secondary: #fafafa;
--bg-tertiary: #f5f5f5;

--border: #d9d9d9;
--divider: #f0f0f0;

2. 字体规范

字体家族：

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 
             'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 
             sans-serif;

字号：

--text-xs: 12px;    /* 辅助文字 */
--text-sm: 14px;    /* 正文 */
--text-base: 16px;  /* 正文加重 */
--text-lg: 18px;    /* 小标题 */
--text-xl: 20px;    /* 标题 */
--text-2xl: 24px;   /* 大标题 */

3. 间距系统

--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 24px;
--space-xl: 32px;
--space-2xl: 48px;

4. 圆角

--radius-sm: 2px;
--radius-md: 4px;
--radius-lg: 8px;
--radius-xl: 12px;
--radius-full: 9999px;

5. 阴影

--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.08);
--shadow-md: 0 4px 8px rgba(0, 0, 0, 0.12);
--shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.16);

---

🔐 认证流程设计

1. 注册流程

页面： /register

步骤：

1. 用户填写邮箱、用户名、密码
2. 前端验证（密码强度、邮箱格式）
3. 调用 POST /api/v1/auth/register
4. 显示"验证邮件已发送"提示
5. 用户点击邮件链接 → 跳转到验证页面
6. 自动登录 → 跳转到工作空间列表

表单验证：

const registerSchema = z.object({
  email: z.string().email('请输入有效的邮箱地址'),
  username: z.string()
    .min(3, '用户名至少 3 个字符')
    .max(20, '用户名最多 20 个字符')
    .regex(/^[a-zA-Z0-9_]+$/, '用户名只能包含字母、数字和下划线'),
  password: z.string()
    .min(8, '密码至少 8 个字符')
    .regex(/[A-Z]/, '密码必须包含大写字母')
    .regex(/[a-z]/, '密码必须包含小写字母')
    .regex(/[0-9]/, '密码必须包含数字'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: '两次密码输入不一致',
  path: ['confirmPassword'],
});

2. 登录流程

页面： /login

步骤：

1. 用户输入邮箱和密码
2. 调用 POST /api/v1/auth/login
3. 保存 token 到 localStorage
4. 设置 Axios 默认 Authorization header
5. 跳转到工作空间列表或上次访问页面

Remember Me 功能：

• 勾选时：token 保存 30 天
• 不勾选：token 保存到 sessionStorage

3. Token 管理

自动刷新：

// axios 拦截器
axios.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      // Token 过期，尝试刷新
      const refreshToken = storage.get('refresh_token');
      if (refreshToken) {
        try {
          const { access_token } = await refreshAccessToken(refreshToken);
          storage.set('access_token', access_token);
          // 重试原请求
          return axios(error.config);
        } catch {
          // 刷新失败，跳转登录
          router.push('/login');
        }
      }
    }
    return Promise.reject(error);
  }
);

---

🏢 工作空间管理设计

1. 工作空间列表

页面： /workspaces

布局：

┌─────────────────────────────────────────┐
│  Header (用户头像、通知、设置)          │
├─────────────────────────────────────────┤
│  ┌─────────────────────────────────┐   │
│  │  我的工作空间          [+ 创建] │   │
│  ├─────────────────────────────────┤   │
│  │  ┌──────┐  ┌──────┐  ┌──────┐  │   │
│  │  │ WS 1 │  │ WS 2 │  │ WS 3 │  │   │
│  │  │ Free │  │ Pro  │  │ Free │  │   │
│  │  │ 3人  │  │ 12人 │  │ 1人  │  │   │
│  │  └──────┘  └──────┘  └──────┘  │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

功能：

• 显示所有工作空间
• 显示订阅计划（Free/Pro/Enterprise）
• 显示成员数量
• 快速切换工作空间
• 创建新工作空间

2. 工作空间详情

页面： /workspaces/:id

标签页：

• 概览 - 基本信息、配额使用情况
• 成员 - 成员列表、邀请、权限管理
• 订阅 - 当前计划、升级选项
• 设置 - 工作空间名称、删除

概览页示例：

interface WorkspaceOverview {
  name: string;
  plan: 'free' | 'pro' | 'enterprise';
  memberCount: number;
  projectCount: number;
  storageUsed: number;
  storageLimit: number;
  quotaStatus: 'normal' | 'warning' | 'critical' | 'exceeded';
}

3. 成员管理

功能：

• 邀请成员（输入邮箱 + 选择角色）
• 成员列表（头像、姓名、邮箱、角色、加入时间）
• 修改角色（Owner/Admin/Member/Viewer）
• 移除成员
• 待处理邀请列表

权限矩阵显示：

┌────────────┬──────┬───────┬────────┬────────┐
│ 操作       │ Owner│ Admin │ Member │ Viewer │
├────────────┼──────┼───────┼────────┼────────┤
│ 邀请成员   │  ✓   │  ✓    │   ✗    │   ✗    │
│ 移除成员   │  ✓   │  ✓    │   ✗    │   ✗    │
│ 创建项目   │  ✓   │  ✓    │   ✓    │   ✗    │
│ 删除项目   │  ✓   │  ✓    │  自己  │   ✗    │
└────────────┴──────┴───────┴────────┴────────┘

---

💳 订阅管理设计

1. 套餐选择页面

页面： /subscription/plans

布局：

┌───────────┬───────────┬───────────┐
│   Free    │    Pro    │ Enterprise│
├───────────┼───────────┼───────────┤
│ ¥0/月     │  ¥99/月   │  ¥999/月  │
│ 3 项目    │ 无限项目  │ 无限项目  │
│ 10GB      │ 100GB     │ 1TB       │
│ 邮件支持  │ 优先支持  │ 专属支持  │
│           │           │ 定制开发  │
│ [当前]    │ [升级]    │ [联系]    │
└───────────┴───────────┴───────────┘

对比表格：

interface PlanFeature {
  name: string;
  free: boolean | string;
  pro: boolean | string;
  enterprise: boolean | string;
}

const features: PlanFeature[] = [
  { name: '项目数量', free: '3', pro: '无限', enterprise: '无限' },
  { name: '存储空间', free: '10GB', pro: '100GB', enterprise: '1TB' },
  { name: '成员数量', free: '3', pro: '20', enterprise: '无限' },
  { name: 'API 调用', free: '1000/天', pro: '10000/天', enterprise: '无限' },
  { name: '技术支持', free: '邮件', pro: '邮件+工单', enterprise: '专属客服' },
];

2. 升级流程

步骤：

1. 选择套餐 → 确认升级
2. 显示订单信息（价格、有效期）
3. 选择支付方式（支付宝/微信/信用卡）
4. 跳转支付页面
5. 支付成功 → 自动升级 → 显示成功页面

3. 账单页面

页面： /subscription/billing

内容：

• 当前订阅信息
• 下次续费日期和金额
• 历史账单列表
• 发票申请入口

---

🎛️ Admin 后台设计

1. Dashboard

页面： /admin/dashboard

仪表盘指标：

┌──────────┬──────────┬──────────┬──────────┐
│ 总用户数 │ 付费用户 │ 月收入   │ 活跃用户 │
│  1,234   │   156    │ ¥15,444  │   892    │
└──────────┴──────────┴──────────┴──────────┘

┌─────────────────────────────────────────┐
│  用户增长趋势图                         │
│  ┌────────────────────────────────────┐ │
│  │         ╱╲                         │ │
│  │        ╱  ╲      ╱╲                │ │
│  │   ╱╲  ╱    ╲    ╱  ╲    ╱╲         │ │
│  │  ╱  ╲╱      ╲  ╱    ╲  ╱  ╲        │ │
│  │ ╱            ╲╱      ╲╱    ╲       │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘

2. 用户管理

页面： /admin/users

功能：

• 用户列表（搜索、筛选、分页）
• 用户详情（基本信息、工作空间、订阅状态）
• 封禁/解封用户
• 手动验证邮箱
• 重置密码

3. 系统监控

页面： /admin/monitoring

监控指标：

• API 响应时间
• 数据库连接池状态
• Redis 连接状态
• 错误日志
• 慢查询日志

---

📱 响应式设计

断点定义

/* Mobile */
@media (max-width: 640px) { }

/* Tablet */
@media (min-width: 641px) and (max-width: 1024px) { }

/* Desktop */
@media (min-width: 1025px) { }

移动端适配

导航：

• 桌面端：侧边栏 + 顶部栏
• 移动端：底部导航栏 + 汉堡菜单

表格：

• 桌面端：完整表格
• 移动端：卡片列表

表单：

• 全宽输入框
• 大号按钮（易于点击）

---

🧪 测试策略

1. 单元测试

工具： Vitest + Testing Library

覆盖范围：

• 工具函数（100%）
• Hooks（80%+）
• 组件（核心组件 80%+）

2. E2E 测试

工具： Playwright

关键流程：

• 用户注册 → 邮箱验证 → 登录
• 创建工作空间 → 邀请成员
• 升级订阅

3. 可访问性测试

• 键盘导航支持
• ARIA 标签
• 颜色对比度（WCAG AA）

---

🚀 性能优化

1. 代码分割

// 路由懒加载
const Login = lazy(() => import('./pages/auth/Login'));
const Dashboard = lazy(() => import('./pages/admin/Dashboard'));

2. 图片优化

• 使用 WebP 格式
• 懒加载图片
• 响应式图片

3. 缓存策略

React Query 配置：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,  // 5 分钟
      cacheTime: 10 * 60 * 1000,  // 10 分钟
      refetchOnWindowFocus: false,
    },
  },
});

---

📅 开发排期

Week 1-2: 基础搭建

• 项目初始化（Vite + React + TypeScript）
• 安装配置依赖（Ant Design, React Router, etc.）
• 搭建基础布局（Header, Sidebar, Footer）
• API 客户端封装
• 路由配置

Week 3: 认证页面

• 登录页面
• 注册页面
• 忘记密码页面
• 邮箱验证页面
• Token 管理

Week 4: 工作空间管理

• 工作空间列表页面
• 工作空间详情页面
• 成员管理页面
• 邀请成员功能

Week 5: 订阅管理

• 套餐选择页面
• 升级流程
• 账单页面
• 配额展示

Week 6: Admin 后台

• Dashboard 仪表盘
• 用户管理
• 系统监控

Week 7: 个人中心

• 个人设置页面
• 账号安全
• 通知设置

Week 8: 测试和优化

• E2E 测试
• 性能优化
• 可访问性优化
• Bug 修复

---

🎯 成功指标

• 所有页面加载时间 < 2s
• Lighthouse 性能分数 > 90
• 核心流程 E2E 测试覆盖率 100%
• 移动端体验良好（无横向滚动）
• 无 Console 错误和警告

---

📝 备注

• 优先保证桌面端体验，移动端作为补充
• UI 设计遵循 Ant Design 规范，保持一致性
• 所有文字支持国际化（i18n）准备
• 表单验证使用 Zod，前后端类型一致

---

老大确认后，我就开始 Phase 6 的开发工作！ 🦐💪