7.6 KiB
7.6 KiB
阶段 2:可视化交互原型
文档信息
- 产品:模亦灵枢 / MOYI Model Intelligence Hub
- 阶段:阶段 2,可视化交互原型
- 状态:第一版原型已完成,待产品评审
- 实现目录:
prototype/ - 技术栈:Vue 3、Vite、TypeScript、Lucide Vue Next
一、阶段目标
本阶段不把页面当成一次性视觉稿,而是交付一个可以运行、可以点击、可以验证核心流程的前端原型。页面结构、交互状态、演示数据和视觉基础应尽量能够延续到后续真实前端开发,后续只替换数据访问层、权限状态和服务接口。
本阶段重点验证:
- C 端开发者控制台的信息架构是否清晰。
- 用户是否能从发现模型走到 Playground,再走到 API Key 和标准接口接入。
- 同步、流式、异步任务三类调用的状态是否容易理解。
- 邀请码内测、管理员额度发放、充值入口预留等第一版规则是否能被用户看懂。
- 视觉方向是否能支撑未来扩展为团队 AI Gateway 和 MaaS 工作台。
二、技术方案
2.1 选型
| 项目 | 决策 | 原因 |
|---|---|---|
| 前端框架 | Vue 3 + <script setup> |
组件模型成熟,适合后续拆分真实页面和接入状态管理 |
| 构建工具 | Vite | 启动快、配置简单,适合原型快速迭代和后续生产构建 |
| 语言 | TypeScript | 先固定模型卡、Key、任务和页面状态的数据契约 |
| 图标 | Lucide Vue Next | 开源、风格统一、可按需引入,避免原型阶段引入沉重 UI 依赖 |
| 样式 | CSS Variables + 页面组件样式 | 保留品牌视觉控制力,未来可抽取为设计令牌和组件库 |
当前没有引入完整的重型 UI 组件库。表格、弹窗、筛选、状态标签等交互已经按轻量可复用模式实现,后续如果团队确定 Element Plus、Naive UI 或自研设计系统,再将这些基础样式替换为统一组件,不影响页面信息架构。
2.2 目录结构
prototype/
├── src/
│ ├── App.vue # 原型页面、演示状态和交互流程
│ ├── main.ts # Vue 入口
│ ├── styles.css # 设计令牌、响应式布局和视觉样式
│ └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
当前为了快速验证端到端体验,演示数据集中在 App.vue。进入真实开发时,建议拆为 layouts、views、components、composables、stores 和 types,并将页面数据替换为后端 API。
三、原型页面范围
| 页面 | 当前原型覆盖 | 后续真实接口方向 |
|---|---|---|
| 总览 | 调用趋势、额度、可用性、活动和精选模型 | 工作区概览、用量聚合、实时服务状态 |
| 模型广场 | 类型筛选、关键词搜索、模型卡、在线试用 | 模型目录、能力 schema、供应商和版本信息 |
| Playground | 模型选择、调用模式、提示词、调用中、成功和异步提交状态 | 真实模型请求、SSE、任务 API、请求 ID 和用量 |
| API Keys | Key 列表、权限范围、创建、一次性展示、复制、禁用 | Key CRUD、权限、轮换、审计和项目绑定 |
| 任务中心 | 排队、执行、完成、失败、进度条和详情抽屉 | 任务查询、取消、重试、结果文件和回调 |
| 用量与账单 | 调用趋势、额度卡片、流水、充值占位 | 用量明细、额度流水、计费规则、订单和支付 |
| 接入文档 | Base URL、Key、模型名、同步/流式/异步说明和代码示例 | 版本化 API 文档、SDK、错误码、模型能力文档 |
| 管理端 | 独立入口与导航;用户额度、模型供应商、渠道路由、并发队列、计费、审计和平台设置 | 用户、供应商、模型、策略、容量、计费和审计管理 |
四、核心交互流程
4.1 发现模型到第一次调用
总览 / 模型广场
↓ 点击模型卡或“在线试用”
Playground 自动带入模型
↓ 选择同步、流式或异步模式
提交调用
↓
响应预览 / 异步任务状态
↓
复制结果、查看任务或进入接入文档
4.2 API Key 创建
API Keys → 创建 API Key → 填写名称和权限范围
↓
生成 Key → 一次性完整展示 → 复制并确认已保存
↓
回到 Key 列表,可查看状态、范围和最近使用时间
4.3 异步任务
3D、视频、图像等任务型模型不强行套用对话页面。原型将其表现为“提交任务—进入队列—执行进度—结果/失败原因”,为后续任务 API、结果文件和取消/重试能力预留位置。
4.4 异常和未开放能力
- 空输入:调用前提示补充内容。
- 调用中:按钮禁用并展示模型处理状态。
- 异步调用:响应区展示任务已提交,跳转任务中心追踪。
- 无匹配模型:展示空状态和筛选建议。
- 充值/支付:保留位置并明确“暂未开放”,不伪造真实支付结果。
- 帮助中心、设置、部分后台操作:通过 Toast 说明将在后续阶段开放。
五、视觉与交互原则
- 使用深色导航 + 明亮工作区,形成“平台基础设施 + 开发者工具”的产品气质。
- 紫色表达平台和核心操作,青色表达连接与安全,橙色表达异步任务和容量状态,绿色表达成功与健康。
- 重要操作使用明确动词:探索模型、开始调用、创建 API Key、查看任务、复制 Base URL。
- 状态始终可见:服务健康、调用模式、任务进度、额度、Key 状态和操作结果均有视觉反馈。
- 桌面端优先,同时在 860px 和 560px 断点下压缩导航、卡片和表格,保证原型可用于移动端评审。
- 不绑定具体第三方客户端品牌;接入文档面向 AI 应用、业务系统、开发工具和 SDK/HTTP 的通用方式。
- 用户端和管理端使用独立导航与产品语境;第一阶段共享前端工程和设计系统,管理员可在两端切换。
六、阶段验收标准
pnpm install后可以启动pnpm dev,并访问http://localhost:4173。vue-tsc --noEmit通过,vite build通过。- 用户可以在总览、模型广场、Playground、Key、任务、用量和文档之间切换。
- 管理员可以从用户端进入独立管理端,并在管理总览、用户、模型、路由、队列、计费、审计和设置模块间切换。
- 管理端核心列表具备搜索、筛选、开关、抽屉、弹窗、额度发放、邀请创建和设置保存等可演示交互。
- 用户可以从模型卡进入 Playground,完成一次演示调用并看到成功反馈。
- 用户可以创建 Key、看到一次性展示弹窗、复制 Key,并在列表中禁用/启用。
- 用户可以筛选模型和任务,打开任务详情抽屉,看到排队/执行/完成/失败状态。
- 充值入口、公开注册等未确定能力有明确的预留状态,不会让用户误以为已经可用。
- 核心页面在桌面和窄屏布局下没有明显溢出或无法操作的关键控件。
七、评审后待调整项
- 确认品牌色、字体和 Logo 是否进入正式设计系统。
- 确认首批模型名称、供应商归属、模型能力字段和真实示例数据。
- 确认标准对话接口、任务接口、流式协议和错误码的最终契约。
- 确认邀请码、登录、公开注册、企业认证和管理员角色的真实状态流转。
- 确认额度、并发、队列和计费文案是否需要展示具体数值。
- 原型评审通过后进入阶段 3:总体、概要和详细系统架构设计。