# aiaxure

**Repository Path**: wayleq/aiaxure

## Basic Information

- **Project Name**: aiaxure
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AiAxure 工程文档

> 文档版本：v1.0  
> 项目名称：AiAxure（企业级智能原型设计平台）  
> 技术栈：Node.js + Express + HTML5 Canvas 2D + Vanilla JS + Electron  

---

## 一、项目概述

### 1.1 业务定位

AiAxure 是一款面向产品、设计与研发团队的**在线原型设计工具**，参考 Figma 的文档模型与交互范式，提供：

- 无限画布上的可视化页面设计
- 矩形、椭圆、文本、图片、画板（Frame）等核心元素
- 图层管理、属性编辑、撤销重做、导入导出
- 基于大语言模型（LLM）的 **AI 设计生成助手**

### 1.2 核心价值

| 业务场景 | 价值体现 |
|---------|---------|
| 产品原型 | 快速将需求转化为可交互视觉稿 |
| 设计协作 | 统一的文件格式与导出能力（Figma/Penpot） |
| AI 辅助 | 自然语言生成页面，降低设计门槛 |
| 本地部署 | 数据私有化，支持离线使用与桌面客户端 |

### 1.3 界面预览

![AiAxure 主界面](images/ScreenShot_2026-07-16_053530_539.png)

> 上图展示了 AiAxure 的主界面：左侧为项目/图层面板，中间为无限画布（显示 AI 生成的"我的日程"页面），右侧为一枢设计助手面板。

---

## 二、业务架构

```mermaid
flowchart TB
    subgraph 用户层
        U1[产品经理]
        U2[UI/UX 设计师]
        U3[前端开发]
    end

    subgraph 应用层
        A1[浏览器访问]
        A2[Electron 桌面客户端]
        A3[AI 设计助手]
    end

    subgraph 服务层
        S1[Express 静态服务]
        S2[REST API]
        S3[AI 生成接口]
        S4[文件导入导出]
    end

    subgraph 数据层
        D1[SQLite 项目存储]
        D2[本地文件系统]
        D3[LLM API]
    end

    U1 --> A1
    U2 --> A1
    U3 --> A2
    U1 --> A3
    U2 --> A3

    A1 --> S1
    A1 --> S2
    A2 --> S1
    A2 --> S2
    A3 --> S3

    S2 --> D1
    S3 --> D3
    S4 --> D2
```

---

## 三、技术架构

### 3.1 整体分层

```mermaid
flowchart LR
    subgraph 表现层
        UI[UI Layer<br/>Toolbar / LayerPanel / PropertyPanel]
        AI[AI Chat Panel]
    end

    subgraph 交互层
        TM[ToolManager]
        ST[SelectTool]
        DT[DrawTools]
        DH[DragHandler]
    end

    subgraph 渲染层
        CA[Camera]
        RE[Renderer]
        HT[HitTest]
    end

    subgraph 模型层
        SC[Scene]
        NO[Node]
        CM[Command History]
    end

    subgraph 服务层
        EX[Express Server]
        DB[(SQLite)]
        API[LLM API Client]
    end

    UI --> TM
    AI --> EX
    TM --> DH
    DH --> SC
    TM --> RE
    RE --> CA
    RE --> SC
    HT --> SC
    SC --> NO
    SC --> CM
    EX --> DB
    EX --> API
```

### 3.2 技术选型

| 层级 | 技术 | 选型理由 |
|-----|------|---------|
| 服务端 | Node.js + Express | 轻量、前后端同构、生态成熟 |
| 实时通信 | WebSocket (ws) | 预留协同编辑数据通道 |
| 渲染引擎 | HTML5 Canvas 2D | 无需编译，开发效率高，满足原型工具规模 |
| 前端框架 | Vanilla JS | 避免框架开销，直接控制 Canvas 与 DOM |
| 状态管理 | Scene + Command | 参考 Figma 文档模型，天然支持撤销重做 |
| 数据持久化 | better-sqlite3 | 轻量本地数据库，项目快速读写 |
| 桌面端 | Electron | 打包为 Windows/macOS/Linux 客户端 |
| AI 能力 | Anthropic Claude / DeepSeek | 通过 OpenAI 兼容接口接入 |

---

## 四、核心数据流

### 4.1 设计生成流程（AI）

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端 App
    participant S as Express 服务
    participant L as LLM API
    participant M as Scene 模型

    U->>F: 输入自然语言指令
    F->>S: POST /api/design/generate
    Note over S: 组装 system prompt + user prompt
    S->>L: 请求 JSON 格式设计数据
    L-->>S: 返回原始文本
    Note over S: safeJsonParse 修复常见 JSON 错误
    Note over S: normalizeDesignResult 转换 pages/nodes
    S-->>F: 返回 nodes + description
    F->>M: createNode / updateNode
    F->>F: 触发 Renderer 重绘
```

### 4.2 文件保存与加载流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端 App
    participant S as Express 服务
    participant DB as SQLite

    U->>F: 点击保存
    F->>S: POST /api/projects/save
    Note over F: scene.toJSON()
    S->>DB: UPSERT projects
    DB-->>S: 成功
    S-->>F: { success: true }

    U->>F: 点击加载
    F->>S: GET /api/projects/:id
    S->>DB: SELECT project
    DB-->>S: project data
    S-->>F: JSON 数据
    F->>F: Scene.fromJSON + render
```

---

## 五、文档模型

### 5.1 节点树结构

```mermaid
graph TD
    Root[Document Root]
    Root --> Frame1[Frame: 电商首页]
    Frame1 --> Nav[Rect: 顶部导航栏]
    Frame1 --> Logo[Text: Logo]
    Frame1 --> Banner[Rect: Banner 背景]
    Frame1 --> BannerText[Text: 活动标题]
    Frame1 --> Card1[Rect: 商品卡片 1]
    Card1 --> Img1[Image: 商品图]
    Card1 --> Price1[Text: ¥299]
```

### 5.2 Node 核心属性

```javascript
{
  id: "node_1234567890_abc",
  type: "rect" | "ellipse" | "text" | "frame" | "image" | "line",
  name: "按钮背景",
  x: 100, y: 200,
  width: 120, height: 40,
  rotation: 0,
  fill: "#06b6d4",
  stroke: "transparent",
  strokeWidth: 0,
  opacity: 1,
  cornerRadius: 8,
  parentId: "frame_xxx",
  children: []
}
```

---

## 六、项目结构

```
aiaxure/
├── electron/                 # Electron 桌面端入口
│   ├── main.js               # 主进程
│   ├── preload.js            # 预加载脚本
│   └── logger.js             # 主进程日志
├── public/                   # 前端静态资源
│   ├── index.html            # 应用主页面
│   ├── css/                  # 样式文件
│   └── js/                   # 前端源码
│       ├── app.js            # 应用入口与业务编排
│       ├── canvas/           # 渲染与相机
│       │   ├── camera.js
│       │   ├── renderer.js
│       │   └── hitTest.js
│       ├── model/            # 数据模型
│       │   ├── scene.js
│       │   ├── node.js
│       │   └── command.js
│       ├── interaction/      # 交互工具
│       │   ├── toolManager.js
│       │   ├── selectTool.js
│       │   ├── dragHandler.js
│       │   ├── rectTool.js
│       │   ├── ellipseTool.js
│       │   ├── textTool.js
│       │   ├── frameTool.js
│       │   └── ...
│       └── ui/               # UI 面板
│           ├── toolbar.js
│           ├── layerPanel.js
│           ├── propertyPanel.js
│           └── projectPanel.js
├── server.js                 # Express 服务端
├── data/                     # 本地数据
│   ├── aiaxure.db            # SQLite 数据库
│   └── uploads/              # 上传资源
├── kimi/                     # Kimi 配置
│   └── config.toml
├── package.json
└── start-aiaxure.ps1         # Windows 启动脚本
```

---

## 七、功能清单

### 7.1 已交付功能

![AiAxure 图层与属性面板](images/ScreenShot_2026-07-16_053640_229.png)

> 上图展示了选中画板后的编辑状态：左侧图层面板显示完整的节点树，右侧属性面板支持位置尺寸、外观、圆角等样式调整。

| 模块 | 功能点 | 状态 |
|-----|--------|------|
| 画布 | 无限画布、平移缩放、网格背景 | ✅ |
| 绘制 | 矩形、椭圆、文本、画板、图片、线条 | ✅ |
| 编辑 | 选中、移动、缩放、旋转、多选、框选 | ✅ |
| 图层 | 树形图层面板、重命名、显隐、排序 | ✅ |
| 属性 | 位置尺寸、颜色、描边、圆角、文本样式 | ✅ |
| 文件 | 新建、保存、加载、导出 JSON/Penpot/Figma | ✅ |
| AI | 自然语言生成页面、截图参考、上下文优化 | ✅ |
| 历史 | 撤销 / 重做（Command 模式） | ✅ |
| 桌面 | Electron 打包与安装程序 | ✅ |

### 7.2 已修复关键问题

| 问题 | 修复措施 |
|-----|---------|
| LLM 返回非 JSON | `safeJsonParse` 多策略修复（markdown、trailing comma、未转义换行、未加引号值、缺失逗号） |
| 颜色值未加引号 | `fixUnquotedStringValues` 自动补引号 |
| JSON 被截断 | `tryRepairTruncatedJson` 返回部分可用结果 + 提升 `max_tokens` |
| 页面未插入画布 | `normalizeDesignResult` 将 LLM 返回的 `pages` 转换为 frame |

---

## 八、部署与运行

### 8.1 环境要求

- Node.js >= 18
- npm / pnpm
- Windows（开发环境当前为 Windows）

### 8.2 启动服务

```bash
npm install
node server.js
```

服务默认监听 `http://localhost:3456`。

### 8.3 配置 AI

编辑 `kimi/config.toml`：

```toml
[providers.anthropic]
type = "anthropic"
base_url = "https://your-proxy-domain/v1"
api_key = "sk-xxxxxxxx"
```

### 8.4 桌面客户端

```bash
# 仅打包目录
npm run pack

# 构建 Windows 安装程序
npm run dist:win
```

---

## 九、结论

本项目已完成以下目标：

1. **业务可用性**：支持原型设计核心工作流，满足产品/设计/研发协作需求。
2. **技术完整性**：前后端分离、文档模型清晰、渲染与交互解耦。
3. **AI 集成**：自然语言生成设计并自动插入画布，具备容错修复能力。
4. **可扩展性**：模块化架构便于后续接入 WebGL、实时协同、组件库等高级能力。
5. **可交付性**：支持 Web 访问与 Electron 桌面客户端打包。