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

134 lines
7.1 KiB
Markdown
Raw Normal View History

2026-08-18 18:50:20 +08:00
# 阶段 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 目录结构
```text
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 发现模型到第一次调用
```text
总览 / 模型广场
↓ 点击模型卡或“在线试用”
Playground 自动带入模型
↓ 选择同步、流式或异步模式
提交调用
↓
响应预览 / 异步任务状态
↓
复制结果、查看任务或进入接入文档
```
### 4.2 API Key 创建
```text
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:总体、概要和详细系统架构设计。