185 lines
6.7 KiB
Markdown
185 lines
6.7 KiB
Markdown
# 前端架构图 — 文生图提示词
|
||
|
||
你是一位前端架构可视化专家。请根据以下描述，生成一张 **gen2d 前端架构详图**，风格：**现代前端技术文档风格，深色主题，组件树 + 数据流 + 路由三重展示**。
|
||
|
||
## 标题
|
||
|
||
gen2d Frontend Architecture (Vite + React + TypeScript + zustand)
|
||
|
||
## 整体布局
|
||
|
||
分为三个主要区域，从左到右排列：
|
||
|
||
---
|
||
|
||
## 左区：路由与页面层 (Router & Pages)
|
||
|
||
### Router 入口
|
||
- **react-router-dom v6** (BrowserRouter, SPA 模式)
|
||
- **ProtectedRoute** 守卫组件 (检查 token，未登录重定向 /login)
|
||
|
||
### 页面路由表
|
||
|
||
用路由匹配图展示：
|
||
|
||
```
|
||
/ → HomePage (项目画廊)
|
||
/login → LoginPage (登录)
|
||
/register → RegisterPage (注册)
|
||
/projects/:projectId → ProjectDetailPage (三栏工作台)
|
||
/projects/:projectId/tasks/:taskId → ResultPage (素材预览)
|
||
```
|
||
|
||
### 页面层级关系
|
||
|
||
```
|
||
App
|
||
└─ Layout (Navbar + Outlet + ToastContainer)
|
||
├─ HomePage
|
||
│ ├─ ProjectCard (画廊卡片) × N
|
||
│ └─ CreateProjectModal (新建弹窗)
|
||
├─ ProjectDetailPage (三栏 CSS Grid)
|
||
│ ├─ [左栏 260px] ProjectConfigPanel
|
||
│ ├─ [中间 1fr] GenerateForm + ProgressBar
|
||
│ └─ [右栏 320px] TaskListPanel
|
||
└─ ResultPage
|
||
└─ AssetPreview
|
||
```
|
||
|
||
---
|
||
|
||
## 中区：状态管理 & 数据流 (State Management)
|
||
|
||
### zustand Stores (7 个)
|
||
|
||
用 7 个卡片网格展示，每个卡片包含 Store 名称、核心状态字段、主要 Action：
|
||
|
||
| Store | 核心 State | 主要 Actions | 消费组件 |
|
||
|-------|-----------|-------------|---------|
|
||
| **auth** | user, token, isAuthenticated | login, register, logout | Layout, ProtectedRoute, LoginPage |
|
||
| **projectList** | projects[], loading | loadProjects, createProject, deleteProject | HomePage |
|
||
| **project** | projectId, name, style, draftStyle, draftName, hasUnsavedChanges | loadProject, startEditing, updateDraft, commitDraft, discardDraft | ProjectConfigPanel, ProjectDetailPage |
|
||
| **task** | prompt, assetType, taskStyle, params, enableAI, optimizedPrompt | setters, runOptimize, reset | GenerateForm |
|
||
| **generation** | taskId, stage, progress, status, retryCount, assets[], error | submit, reset | ProgressBar, GenerateForm, ResultPage |
|
||
| **theme** | mode (light/dark) | toggle | Layout (全局主题切换) |
|
||
| **toast** | toasts[] | addToast, removeToast | ToastContainer |
|
||
|
||
### 数据流方向
|
||
|
||
在组件和 Store 之间画出单向数据流箭头：
|
||
- **组件 → Store**：dispatch action (用户交互)
|
||
- **Store → 组件**：useStore selector 订阅，自动重渲染
|
||
- **Store → API**：调用 api/ 封装层
|
||
- **API → Store**：响应数据写入 state
|
||
|
||
### 风格编辑流程 (Draft/Commit 模式)
|
||
|
||
用一个小流程图展示：
|
||
|
||
```
|
||
startEditing() → copy style → draftStyle
|
||
↓
|
||
updateDraft(key, value) → draftStyle 变更 → hasUnsavedChanges = true
|
||
↓
|
||
┌─ commitDraft() → PUT /api/v1/projects/:id/style → style = draftStyle → hasUnsavedChanges = false
|
||
└─ discardDraft() → draftStyle = style → hasUnsavedChanges = false
|
||
```
|
||
|
||
---
|
||
|
||
## 右区：组件树 & 交互流程 (Components & Interactions)
|
||
|
||
### 组件依赖树
|
||
|
||
```
|
||
Layout
|
||
├── Navbar (logo + 导航 + 用户菜单)
|
||
└── ToastContainer
|
||
└── ToastItem × N
|
||
|
||
HomePage
|
||
├── ProjectCard (缩略图 + 名称 + 任务数 + 最近活动)
|
||
└── CreateProjectModal
|
||
├── StyleSelector (预设风格 pill 按钮)
|
||
└── CustomTagsEditor (添加/删除自定义标签)
|
||
|
||
ProjectDetailPage (CSS Grid: 260px 1fr 320px)
|
||
├── [左栏] ProjectConfigPanel
|
||
│ ├── 工程名 (可编辑 input)
|
||
│ ├── StyleSelector (全量风格编辑)
|
||
│ ├── CustomTagsEditor
|
||
│ └── 保存/取消 按钮 (hasUnsavedChanges 控制)
|
||
├── [中间] 生成区域
|
||
│ ├── GenerateForm
|
||
│ │ ├── 素材类型选择 (sprite / background / ui / animation)
|
||
│ │ ├── StyleSelector (任务覆盖，仅记录差异)
|
||
│ │ ├── PromptEditor (文本输入)
|
||
│ │ ├── 技术参数 (分辨率 / 帧数 / 格式)
|
||
│ │ └── 提交按钮 + AI 优化按钮
|
||
│ └── ProgressBar (提交后显示)
|
||
│ └── 四阶段进度条 (prompt_builder → asset_generator → quality_supervisor → format_adapter)
|
||
└── [右栏] TaskListPanel
|
||
├── StatusBadge (状态标签: pending/running/completed/failed)
|
||
├── TaskItem × N (点击跳转 ResultPage)
|
||
└── 自动刷新 (15s 间隔)
|
||
|
||
ResultPage
|
||
└── AssetPreview
|
||
├── 图片预览 (带帧信息标注)
|
||
├── 元数据展示 (分辨率/帧数/方向数/格式)
|
||
└── 下载按钮 (GET /api/v1/assets/download?key=...)
|
||
```
|
||
|
||
### 生成任务交互流程 (时序简化)
|
||
|
||
```
|
||
User → GenerateForm (填写 prompt + 选择类型 + 参数) → [提交]
|
||
→ POST /api/v1/generate → taskId
|
||
→ generation store: status=running
|
||
→ ProgressBar 显示
|
||
→ 轮询 GET /api/v1/tasks/:taskId (每 1.5s)
|
||
→ 更新 stage + progress
|
||
→ status=completed
|
||
→ GET /api/v1/tasks/:taskId/assets
|
||
→ 显示 "查看结果" → 跳转 ResultPage
|
||
```
|
||
|
||
### API 封装层结构 (api/)
|
||
|
||
在底部用一个窄条展示：
|
||
|
||
```
|
||
api/
|
||
├── client.ts — fetch 封装 (统一错误处理, JSON 解包, Bearer Token 注入)
|
||
├── auth.ts — login(), register()
|
||
├── project.ts — listProjects(), createProject(), getProject(), updateProject(), deleteProject()
|
||
├── generate.ts — submitGenerate(), getTask(), getTaskAssets()
|
||
├── prompt.ts — optimizePrompt(), extractTags()
|
||
├── mock.ts — 多工程 Mock 数据 (开发用)
|
||
└── types.ts — Project, Task, Asset, User 等类型定义
|
||
```
|
||
|
||
---
|
||
|
||
## 色彩与排版指南
|
||
|
||
- **背景**：深色 (#1a1a2e 或 #0f172a)
|
||
- **左区 (Router)**：紫色调 (#8B5CF6 / #7C3AED)，紫色边框
|
||
- **中区 (State)**：青色调 (#06B6D4 / #0891B2)，青色边框
|
||
- **右区 (Components)**：绿色调 (#10B981 / #059669)，绿色边框
|
||
- **API 层**：橙色调 (#F59E0B)
|
||
- **组件框**：半透明背景 + 彩色左边框
|
||
- **箭头**：白色或浅灰 (#94A3B8)，实线 = 同步，虚线 = 异步
|
||
- **文字**：白色为主 (#F8FAFC)，次要文字浅灰 (#94A3B8)
|
||
- **Store 卡片**：微亮边框，内部字段用等宽字体
|
||
- **所有框使用圆角** (border-radius: 6px)
|
||
- **区域标题**用较大的加粗字体 + 左侧色条
|
||
|
||
## 附加约束
|
||
|
||
- 所有组件名、Store 名、文件名与代码库保持一致
|
||
- 中文用于辅助标注（括号内），英文为主要标注
|
||
- 避免拥挤，分区之间留白充分
|
||
- 画面比例 16:9 或更宽，适合横屏展示
|
||
- 不要使用 3D 效果
|