ui-prototype

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

UI 原型快速迭代

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

触发条件

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

技术栈约束

本项目前端技术栈：

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

工作流程

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

两种输入模式：

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. 输出完整的字段-控件映射表，列出所有字段，无遗漏

数据类型 → 控件映射表：

输出格式：

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

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

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

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

Step 2: 生成原型代码

核心原则：

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

生成模式选择：

代码结构要求：

<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 / 分组 / 步骤，就必须生成对应数量的原型图，每个都展示该状态下的所有字段和控件。

4b. 交互标注

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

标注内容必须覆盖：

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 常用组件速查

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

布局与容器

数据展示

表单

操作与反馈

导航

现有页面模式参考

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

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

强制规则

反模式

设计原则参考

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