ui-prototype

name	ui-prototype
description	基于现有页面快速生成 UI 原型。当需要设计新页面、修改现有页面布局、新增 UI 功能模块，或需要向产品/设计对齐 UI 方案时使用。支持截图输入和文字描述输入。

UI 原型快速迭代

核心理念：代码即原型。不画 Figma，直接在现有页面基础上用代码迭代 UI 方案。 AI 生成可运行的 Vue 组件代码，浏览器中预览，快速迭代至满意。

触发条件

• 用户说"做个原型"、"页面长什么样"、"设计一下 UI"、"新增一个页面"
• 用户提供截图并要求基于此修改
• 用户描述一个新的 UI 功能模块或页面布局
• 需要在编码前确认 UI 方案

技术栈约束

本项目前端技术栈：

技术	版本	说明
Vue	2.7.14	Options API 为主
bk-magic-vue	2.5.8	蓝鲸 MagicBox 组件库，组件以 bk- 前缀使用
Element UI	2.15.13	辅助组件库，用于 bk-magic-vue 未覆盖的场景
Vue Router	2.x	路由
Vuex	2.x	状态管理
vue-i18n	7.x	国际化，使用 $t('中文') 包裹文案
AntV X6	2.x	画布/流程编排

组件使用优先级：bk-magic-vue > Element UI > 原生 HTML

---

工作流程

Step 1: 理解需求，确定原型范围

两种输入模式：

输入方式	AI 行为
截图 + 描述	分析截图中的现有布局，理解要在哪里改、改什么
纯文字描述	找到最相似的现有页面作为基线，在其基础上设计

AI 必须做的事：

1. 找到基线页面：在 frontend/src/views/ 下找到与需求最相关的现有页面
2. 读取基线代码：读取该页面的 .vue 文件，理解现有布局、组件使用、样式模式
3. 读取后端数据模型（如已有）：如果是改造已有功能，找到页面对应的后端 Model / Config / Serializer，提取字段元数据（详见 Step 1.5）；如果是全新功能、后端尚未开发，则跳过此步，基于用户提供的需求描述设计表单
4. 明确改动范围：向用户确认——是修改现有页面，还是新建页面？改多大范围？

输出格式：

📐 原型范围确认

**基线页面**：`frontend/src/views/admin/Space/Credential/index.vue`
**现有布局**：顶部操作栏 + 数据表格 + 侧滑面板
**改动范围**：[新增 / 修改 / 重新设计]
**具体内容**：
  - [改动点 1]
  - [改动点 2]

确认后我开始生成原型代码。

Step 1.5: 读取后端数据模型，映射表单控件（条件触发）

触发条件：后端代码已存在（改造已有功能、重构现有页面）。 跳过条件：全新功能、后端尚未开发——此时基于用户提供的需求描述或产品文档设计表单，在原型报告中注明"字段待后端确认"。

先读后端，再画前端。 当后端已有数据模型时，表单类页面的原型必须基于后端数据模型，而非凭截图猜测。

AI 必须做的事：

1. 在后端代码中找到页面对应的 Model / Config / Serializer / Constants
2. 提取每个字段的完整元数据：name、description、value_type、default_value、choices、校验规则
3. 按照「数据类型 → 控件映射表」为每个字段选择表单控件
4. 输出完整的字段-控件映射表，列出所有字段，无遗漏

数据类型 → 控件映射表：

后端数据类型	表单控件	bk-magic-vue 组件
boolean / choices=["true","false"]	开关 Switch	bk-switcher
string + choices（2 个选项）	分段按钮 Segmented Control	bk-radio-button-group
string + choices（3+ 个选项）	下拉选择 Select	bk-select + bk-option
string（短文本，无 choices）	文本输入 Input	bk-input
string（有格式要求，如时间）	文本输入 + 格式提示	bk-input + 下方灰色提示文字
JSON object	代码编辑器	FullCodeEditor（Monaco）
JSON array（用户列表等）	标签输入 Tag Input	bk-tag-input 或自定义 Tag 组件
is_mix_type=true（TEXT/JSON 可切换）	类型切换 + 对应控件	分段按钮 [TEXT]/[JSON] + 输入框或编辑器

输出格式：

📋 字段-控件映射（共 N 个字段）

| 字段 | 说明 | 类型 | 默认值 | 控件 | 分组 |
|------|------|------|--------|------|------|
| superusers | 空间管理员 | JSON array | [] | 标签输入 | 权限与用户 |
| flow_versioning | 流程版本控制 | choices[true/false] | "false" | Switch | 权限与用户 |
| ... | ... | ... | ... | ... | ... |

当后端已有代码时：映射表必须覆盖后端定义的所有字段，不可遗漏。用户确认映射后才能生成原型。

当后端尚未开发时：基于需求描述推断字段和类型，同样输出映射表，但在每个字段备注列标注"待确认"。此映射表可作为前后端对齐的沟通工具。

Step 2: 生成原型代码

核心原则：

1. 保持现有风格一致：从基线页面继承布局模式、间距、配色
2. 优先使用 bk-magic-vue 组件：不要引入项目未使用的 UI 库
3. 原型先行，细节后补：先把结构和交互做对，样式微调放后面
4. 所有文案用 $t() 包裹：保持国际化一致性

生成模式选择：

场景	生成方式
修改现有页面	直接修改现有 .vue 文件
新增子组件	在现有页面的 components/ 下新建 .vue 文件
全新页面	在 views/ 对应目录下创建新的 .vue + 注册路由

代码结构要求：

<template>
  <!-- 使用 bk-magic-vue 组件 -->
</template>

<script>
export default {
  name: 'ComponentName',
  components: {},
  props: {},
  data() {
    return {
      // 用 mock 数据填充，让原型看起来真实
    };
  },
  methods: {
    // 交互方法用空实现或 console.log 占位
  },
};
</script>

<style lang="scss" scoped>
/* 遵循项目现有样式模式 */
</style>

Step 3: 提供 Mock 数据

原型必须用真实感的 Mock 数据，不要用 "Lorem ipsum" 或 "测试1"。

// 好的 Mock 数据
tableData: [
  { id: 1, name: 'prod-api-key', type: 'bearer_token', creator: 'admin', create_at: '2026-02-15 14:30:00' },
  { id: 2, name: 'ci-deploy-token', type: 'app_secret', creator: 'devops', create_at: '2026-02-10 09:15:00' },
]

// 坏的 Mock 数据
tableData: [
  { id: 1, name: '测试', type: 'type1', creator: 'user1', create_at: '2020-01-01' },
]

Step 4: 生成原型图（强制全状态覆盖 + 交互标注）

原型图必须满足两个要求：覆盖所有页面状态 和 标注交互细节。

4a. 全状态覆盖

禁止只出一个 Tab / 一种状态的原型。 页面有多少个 Tab / 分组 / 步骤，就必须生成对应数量的原型图，每个都展示该状态下的所有字段和控件。

页面类型	需要覆盖的状态
Tab 切换页	每个 Tab 各一张原型图
多步骤表单	每个步骤各一张
列表 + 详情	列表页一张 + 详情/编辑态一张
弹窗/侧滑	主页面一张 + 弹窗打开态一张

4b. 交互标注

每张原型图必须包含红色编号标注（❶❷❸...），用红色引线指向具体 UI 元素，旁边附交互说明文字。

标注内容必须覆盖：

必须标注的交互	说明
保存时机	立即保存（onChange）还是失焦保存还是手动点击保存
校验规则	什么时候校验、校验失败的表现（红色边框、错误提示文字）
状态指示	如何区分已修改/默认值/未配置
危险操作	恢复默认值、删除等需二次确认的操作
特殊控件	代码编辑器的工具栏按钮、全屏模式、折叠/展开行为
导航行为	Tab 切换、URL 同步、搜索跨 Tab 跳转

4c. 输出原型报告

每次生成/修改后，输出以下报告：

---
## 🎨 原型 v[N]

### 原型图
[为每个状态/Tab 生成一张带交互标注的原型图]

### 改动文件
- `path/to/file.vue`: [做了什么]

### 页面结构
[用简洁的文字描述页面布局]

### 各状态下的字段与控件
[按 Tab/分组 列出每个字段使用的控件]

### 交互标注汇总
[按编号列出所有交互标注，每条包含：元素 + 交互行为]

| 编号 | 元素 | 交互说明 |
|------|------|----------|
| ❶ | 搜索框 | 实时搜索，跨 Tab 过滤... |
| ❷ | Switch 开关 | onChange 立即保存... |

---
⏸️ **请预览后反馈**

- **继续迭代** → 告诉我哪里需要调整
- **满意，开始实现** → 我将基于此原型编写完整的功能代码
- **推倒重来** → 描述新的方向

Step 5: 迭代

迭代原则：

• 每次迭代只改用户提到的部分，不要大范围重写
• 记录版本号（v1, v2, v3...），方便回溯
• 3 轮迭代后如果方向不明确，主动提议暂停，先对齐需求

从原型到正式代码：

当用户说"满意"或"开始实现"时：

1. 清理 Mock 数据，接入真实 API
2. 补全表单校验、错误处理、Loading 状态
3. 补全国际化文案（cn.js / en.js）
4. 触发 test-driven-development skill 编写测试

---

bk-magic-vue 常用组件速查

生成原型时优先使用以下组件：

布局与容器

组件	用途
bk-sideslider	侧滑面板（编辑/新建表单）
bk-dialog	弹窗（确认/警告/表单）
bk-tab / bk-tab-panel	标签页切换
bk-collapse / bk-collapse-item	折叠面板

数据展示

组件	用途
bk-table / bk-table-column	数据表格
bk-pagination	分页
bk-tag	标签/状态标记
bk-badge	徽标/计数
bk-progress	进度条
bk-tree	树形控件

表单

组件	用途
bk-form / bk-form-item	表单容器（支持校验）
bk-input	文本输入
bk-select / bk-option	下拉选择
bk-checkbox / bk-checkbox-group	多选
bk-radio / bk-radio-group	单选
bk-switcher	开关
bk-date-picker	日期选择
bk-time-picker	时间选择
bk-upload	文件上传

操作与反馈

组件	用途
bk-button	按钮（primary / default / text）
bk-dropdown-menu / bk-dropdown-item	下拉菜单
bk-popover	气泡提示
bk-popconfirm	气泡确认
bk-loading	加载状态（指令：v-bkloading）
bk-notify / bk-message	通知消息（JS 调用）

导航

组件	用途
bk-navigation	顶部导航
bk-breadcrumb / bk-breadcrumb-item	面包屑
bk-steps	步骤条

---

现有页面模式参考

在生成原型前，读取以下路径了解项目现有的 UI 模式：

模式	参考文件
列表页（搜索+表格+分页）	views/admin/Space/Credential/index.vue
侧滑表单	views/admin/Space/Credential/components/CredentialSlider.vue
Tab 切换页	views/admin/Space/SpaceConfig/
任务/流程页	views/admin/Space/Task/
模板管理页	views/admin/Space/Template/

读取现有页面的目的：继承其布局模式、间距、组件用法、样式写法，确保原型与现有页面风格统一。

---

强制规则

规则	说明
先读后端（如已有）	后端已有代码时，表单类页面必须先读取数据模型再设计控件；全新功能则基于需求描述推断
先找基线	生成任何原型前，必须先找到并读取最相关的现有页面
控件映射	严格按照「数据类型→控件映射表」选择控件，不凭直觉猜测
全状态覆盖	页面有多少个 Tab / 步骤 / 状态，就必须生成对应数量的原型图
交互标注	每张原型图必须带红色编号标注，标在图上而非仅文字描述
字段无遗漏	后端已定义的字段必须全部体现；新功能需列出所有推断字段并标注"待确认"
用项目组件	优先 bk-magic-vue，禁止引入 Ant Design、Vuetify 等未使用的库
真实 Mock	用接近真实业务的数据，不用占位符
保持一致	与现有页面的风格、间距、配色保持一致
国际化	所有可见文案用 $t() 包裹
每轮报告	每次生成/修改后输出原型报告
不过度设计	原型阶段只做结构和交互，不纠结像素级细节

反模式

错误做法	正确做法
后端已有代码却不读，凭截图猜字段类型	先读后端 Config/Model/Serializer，提取完整字段元数据
只出一个 Tab 的原型，让用户脑补其他 Tab	每个 Tab/状态都出原型图，全部展示
交互说明只写文字表格，不标注在图上	用红色编号❶❷❸直接标注在原型图上，附引线和说明
遗漏已有字段，或新功能不列推断字段	输出字段-控件映射表，逐一对照确保无遗漏；新功能标注"待确认"
不看现有页面，凭空设计	先读取最相关的现有页面作为基线
使用 Tailwind / 外部 CSS 框架	用 SCSS + 项目现有的样式模式
引入项目未使用的组件库	严格使用 bk-magic-vue + Element UI
Mock 数据用"测试1" "aaa"	用接近真实业务的数据
一次大改，不给用户预览机会	小步迭代，每次改完等用户反馈
原型阶段写完整的后端对接逻辑	原型用 Mock 数据，确认后再对接

---

设计原则参考

通用 UI 设计原则详见 reference/design-principles.md。