Files
moyi-model-intelligence-hub/docs/02-interactive-prototype.md
T

7.1 KiB

阶段 2:可视化交互原型

文档信息

  • 产品:模亦灵枢 / MOYI Model Intelligence Hub
  • 阶段:阶段 2,可视化交互原型
  • 状态:第一版原型已完成,待产品评审
  • 实现目录:prototype/
  • 技术栈:Vue 3、Vite、TypeScript、Lucide Vue Next

一、阶段目标

本阶段不把页面当成一次性视觉稿,而是交付一个可以运行、可以点击、可以验证核心流程的前端原型。页面结构、交互状态、演示数据和视觉基础应尽量能够延续到后续真实前端开发,后续只替换数据访问层、权限状态和服务接口。

本阶段重点验证:

  1. C 端开发者控制台的信息架构是否清晰。
  2. 用户是否能从发现模型走到 Playground,再走到 API Key 和标准接口接入。
  3. 同步、流式、异步任务三类调用的状态是否容易理解。
  4. 邀请码内测、管理员额度发放、充值入口预留等第一版规则是否能被用户看懂。
  5. 视觉方向是否能支撑未来扩展为团队 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,并在列表中禁用/启用。
  • 用户可以筛选模型和任务,打开任务详情抽屉,看到排队/执行/完成/失败状态。
  • 充值入口、公开注册等未确定能力有明确的预留状态,不会让用户误以为已经可用。
  • 核心页面在桌面和窄屏布局下没有明显溢出或无法操作的关键控件。

七、评审后待调整项

  1. 确认品牌色、字体和 Logo 是否进入正式设计系统。
  2. 确认首批模型名称、供应商归属、模型能力字段和真实示例数据。
  3. 确认标准对话接口、任务接口、流式协议和错误码的最终契约。
  4. 确认邀请码、登录、公开注册、企业认证和管理员角色的真实状态流转。
  5. 确认额度、并发、队列和计费文案是否需要展示具体数值。
  6. 原型评审通过后进入阶段 3:总体、概要和详细系统架构设计。