xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases 7 Wiki Activity

docs: add Phase 6 frontend development design document

Browse Source 
Complete Phase 6 design specification:
- Technology stack: React 18 + TypeScript + Ant Design
- Project structure and file organization
- Design system (colors, typography, spacing)
- Authentication flow design
- Workspace management UI
- Subscription management interface
- Admin dashboard design
- Responsive design (mobile/tablet/desktop)
- 8-week development roadmap
- Testing strategy and performance optimization

Ready to start Phase 6 frontend development!
This commit is contained in:
Xiaoxia AI
2026-06-17 09:32:37 +08:00
parent 5269e80d4c
commit 8c0ad4bab5
1 changed files with 678 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PHASE6-DESIGN.md
+678
View File
@@ -0,0 +1,678 @@
# 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. 色彩系统
**主色调：**
```css
--primary: #1890ff; /* 品牌蓝 */
--primary-hover: #40a9ff;
--primary-active: #096dd9;
--success: #52c41a; /* 成功绿 */
--warning: #faad14; /* 警告黄 */
--error: #ff4d4f; /* 错误红 */
--info: #1890ff; /* 信息蓝 */
```
**中性色：**
```css
--text-primary: #262626;
--text-secondary: #595959;
--text-disabled: #bfbfbf;
--bg-primary: #ffffff;
--bg-secondary: #fafafa;
--bg-tertiary: #f5f5f5;
--border: #d9d9d9;
--divider: #f0f0f0;
```
### 2. 字体规范
**字体家族：**
```css
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI',
'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei',
sans-serif;
```
**字号：**
```css
--text-xs: 12px; /* 辅助文字 */
--text-sm: 14px; /* 正文 */
--text-base: 16px; /* 正文加重 */
--text-lg: 18px; /* 小标题 */
--text-xl: 20px; /* 标题 */
--text-2xl: 24px; /* 大标题 */
```
### 3. 间距系统
```css
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 24px;
--space-xl: 32px;
--space-2xl: 48px;
```
### 4. 圆角
```css
--radius-sm: 2px;
--radius-md: 4px;
--radius-lg: 8px;
--radius-xl: 12px;
--radius-full: 9999px;
```
### 5. 阴影
```css
--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. 自动登录 → 跳转到工作空间列表
**表单验证：**
```typescript
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 管理
**自动刷新：**
```typescript
// 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`
**标签页：**
- **概览** - 基本信息、配额使用情况
- **成员** - 成员列表、邀请、权限管理
- **订阅** - 当前计划、升级选项
- **设置** - 工作空间名称、删除
**概览页示例：**
```typescript
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 │
│ 邮件支持 │ 优先支持 │ 专属支持 │
│ │ │ 定制开发 │
│ [当前] │ [升级] │ [联系] │
└───────────┴───────────┴───────────┘
```
**对比表格：**
```typescript
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 连接状态
- 错误日志
- 慢查询日志
---
## 📱 响应式设计
### 断点定义
```css
/* 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. 代码分割
```typescript
// 路由懒加载
const Login = lazy(() => import('./pages/auth/Login'));
const Dashboard = lazy(() => import('./pages/admin/Dashboard'));
```
### 2. 图片优化
- 使用 WebP 格式
- 懒加载图片
- 响应式图片
### 3. 缓存策略
**React Query 配置：**
```typescript
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 的开发工作！** 🦐💪