# Vue页面可视化设计器 - 项目上下文

> **用途**：用于在新环境快速恢复 AI 协作上下文  
> **更新时间**：2026-01-20  
> **项目路径**：`d:/workspace/fauto-design`

---

## 📋 项目概述

这是一个基于 **Vue3 + TypeScript + Vite + Element Plus** 的**可视化页面设计器**，通过拖拽操作直接编辑真实的Vue页面源文件。

### 核心特性

1. **直接解析Vue文件** - 动态扫描并渲染`src/views`下的页面
2. **拖拽式设计** - 将设计组件拖拽到页面，支持四个方向放置
3. **源码级修改** - 拖拽操作直接修改Vue源文件，支持热更新
4. **智能层级选择** - 键盘方向键切换嵌套元素层级
5. **实时视觉反馈** - 拖拽预览 + 拖放区域显示
6. **元数据编辑** - 点击组件可编辑属性（宽度、尺寸、颜色等）
7. **多种删除方式** - 右键菜单、Del键、删除图标

---

## 🏗️ 项目结构

```
fauto-design/
├── draggable-panels/              # 前端项目
│   ├── src/
│   │   ├── fauto/                 # 🔥 设计器核心代码
│   │   │   ├── Designer.vue       # 设计器主入口
│   │   │   │
│   │   │   ├── components/        # 基础UI组件
│   │   │   │   ├── Header.vue     # 顶部菜单栏
│   │   │   │   ├── Footer.vue     # 底部状态栏
│   │   │   │   ├── MainLayout.vue # 三栏布局容器
│   │   │   │   ├── Panel.vue      # 面板容器
│   │   │   │   └── Resizer.vue    # 面板分隔器
│   │   │   │
│   │   │   ├── materials/         # 🎁 物料组件系统
│   │   │   │   ├── PageManager/   # 页面管理（树形文件选择）
│   │   │   │   ├── DesignComponentList/ # 设计组件列表
│   │   │   │   ├── DesignCenter/  # 设计中心（动态渲染页面）
│   │   │   │   │   ├── index.vue
│   │   │   │   │   ├── InteractiveWrapper.vue  # 交互包装器
│   │   │   │   │   ├── DropZone.vue     # 拖放区域指示器
│   │   │   │   │   └── DragPreview.vue  # 拖拽预览
│   │   │   │   ├── TreeViewer/    # 结构树（页面结构展示）
│   │   │   │   └── DataTable/     # 元数据编辑器
│   │   │   │
│   │   │   ├── designComponents/  # 🎨 设计组件库
│   │   │   │   ├── TextInput/     # 输入框
│   │   │   │   │   ├── index.json    # 组件配置+元数据schema
│   │   │   │   │   └── template.html # 组件模板
│   │   │   │   ├── RadioSelect/   # 单选器
│   │   │   │   └── GridTable/     # 表格
│   │   │   │
│   │   │   ├── plugins/           # 🔌 插件系统
│   │   │   │   ├── index.ts       # 统一导出
│   │   │   │   ├── interactionStore.ts  # 交互事件钩子
│   │   │   │   ├── dragStore.ts   # 拖拽状态管理
│   │   │   │   └── pathUtils.ts   # 结构化路径工具
│   │   │   │
│   │   │   ├── stores/            # 🗄️ Pinia状态管理
│   │   │   │   ├── panelStore.ts  # 面板布局状态
│   │   │   │   ├── designStore.ts # 设计组件元数据
│   │   │   │   └── vueFileStore.ts# Vue文件选择状态
│   │   │   │
│   │   │   └── types/             # 📝 类型定义
│   │   │
│   │   └── views/                 # 📄 示例页面
│   │
│   └── vite.config.ts
│
└── vue-template-service/          # 🖥️ 后端服务
    └── src/
        ├── index.js               # Express服务入口
        └── services/
            └── templateService.js # Vue模板解析与修改服务
```

---

## 🔑 核心技术要点

### 1. **两阶段拖拽机制** ⭐

**第一阶段（源选择）**：鼠标按下开始，收集当前位置的层级节点  
**第二阶段（目标选择）**：移动到新位置，选择目标和方向

```typescript
// dragStore.ts
startDragFromCanvas(path, type, element) → 进入源选择阶段
enterTargetPhase(element) → 进入目标选择阶段
confirmDrop(pagePath) → 调用后端API执行移动
```

### 2. **结构化路径ID** ⭐

**格式**：`r{n}c{m}r{x}c{y}...`
- `r`: el-row
- `c`: el-col
- 数字：同级索引（从1开始）

**示例**：`r1c2r1c3` 表示：
- 第1个el-row → 第2个el-col → 第1个el-row → 第3个el-col

### 3. **设计组件标识** ⭐

设计组件使用 `data-component` 属性标识类型：

```html
<el-col :span="12">
  <div class="design-component" data-component="输入框">
    <el-form-item label="文本输入">
      <el-input v-model="inputValue" />
    </el-form-item>
  </div>
</el-col>
```

### 4. **元数据Schema定义** ⭐

设计组件的 index.json 定义可编辑属性：

```json
{
  "id": "TextInput",
  "name": "输入框",
  "metadata": {
    "span": { "label": "宽度", "type": "number", "min": 1, "max": 24, "target": "el-col", "attr": ":span" },
    "label": { "label": "标签", "type": "text", "target": "el-form-item", "attr": "label" },
    "placeholder": { "label": "占位符", "type": "text", "target": "el-input", "attr": "placeholder" }
  }
}
```

---

## 🔗 后端API

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/move-element` | POST | 移动元素（画布内拖拽） |
| `/api/insert-element` | POST | 插入新元素（设计组件拖入） |
| `/api/delete-element` | POST | 删除元素 |
| `/api/element-tree` | GET | 获取页面结构树 |
| `/api/component-props` | GET | 获取组件属性值 |
| `/api/update-props` | POST | 更新组件属性值 |

---

## 🎯 数据流图

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户操作                                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  页面管理器    │   │  设计组件列表  │   │   设计中心    │
│ (选择Vue文件)  │   │  (拖拽组件)   │   │  (编辑区域)   │
└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────────────────────────────────────────────────────┐
│                     Pinia 状态管理                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ vueFileStore │  │  dragStore   │  │ designStore  │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────┐
│                   vue-template-service                         │
│                    (Node.js后端服务)                           │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  templateService.js - Vue模板AST解析与修改               │  │
│  └─────────────────────────────────────────────────────────┘  │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ▼
┌───────────────────────────────────────────────────────────────┐
│                      Vue源文件                                 │
│                   (src/views/*.vue)                           │
└───────────────────────────────────────────────────────────────┘
```

---

## 🛠️ 快速开始

### 启动前端
```bash
cd draggable-panels
npm install
npm run dev
# 访问 http://localhost:5173/draggable
```

### 启动后端
```bash
cd vue-template-service
npm install
node src/index.js
# 服务运行在 http://localhost:3001
```

---

## 📝 Vue页面规范

**强制规则**：template的第一层级**有且仅有一个el-row**

```vue
<template>
  <el-row :gutter="20">
    <el-col :span="12">
      <div class="design-component" data-component="输入框">
        <!-- 内容 -->
      </div>
    </el-col>
  </el-row>
</template>
```

---

## 📚 相关文档

- **详细设计文档**：`项目设计文档.md`
- **开发者指南**：`DEVELOPMENT.md`
- **README**：`README.md`

---

**最后更新**：2026-01-20  
**AI协作建议**：优先阅读"核心技术要点"和"后端API"部分，理解系统的数据流和交互方式
