# 智绘构界（VisionForge）

**Repository Path**: recursiveSoup/VisionForge

## Basic Information

- **Project Name**: 智绘构界（VisionForge）
- **Description**: 智绘构界是一个基于 Spring AI Alibaba、多模态模型与 RAG 的前端原型智能生成和迭代平台。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智绘构界（VisionForge）

智绘构界是一个通过自然语言讨论、生成、预览和迭代前端页面的 AI 原型平台。当前仓库已完成 MVP 初始环境与项目脚手架，开发范围以 [`docs/智绘构界-3天MVP与后续优化路线图-v0.2.md`](docs/智绘构界-3天MVP与后续优化路线图-v0.2.md) 为准。

## 当前脚手架

```text
VisionForge/
├── backend/                 # Java 21 + Spring Boot 模块化单体
│   ├── src/main/java/       # API、配置和后续领域模块
│   ├── config/              # 不进入构建产物的本地 dev 配置
│   ├── src/main/resources/  # 公共配置与 Flyway 迁移
│   └── pom.xml              # IDEA 默认 Maven 直接导入
├── frontend/                # Vue 3 + TypeScript + Vite 工作台
├── runtime/                 # 版本文件和部署站点（内容不提交 Git）
├── scripts/                 # 环境初始化、开发启动和完整检查
├── compose.yaml             # MVP 仅启动 MySQL 8.4
└── docs/                    # 产品、架构和 MVP 路线文档
```

已建立的基础能力：

- Spring Boot 健康接口、演示用户模式、Spring Security 默认保护边界、MyBatis-Plus、Flyway 与 MySQL 配置。
- Spring AI 1.1.2、Spring AI Alibaba 1.1.2.3 与 DashScope Starter；没有 API Key 时默认禁用模型自动配置。
- MVP 核心业务表、持久生成任务、BCrypt 演示账号、会话创建与按 ID 恢复。
- `STATIC_PAGE` 纯静态单文档与 `INTERACTIVE_PAGE` 三文件交互页面两条生成策略。
- DashScope POST SSE、受控文件工具、结构与安全校验、Playwright Chromium 加载冒烟和原子目录发布。
- 静态与三文件产物校验失败后最多自动修复 2 次；全部通过后才创建正式版本。
- 稳定版本 URL 的 sandbox iframe 预览、文件树、懒加载 Monaco 只读查看和刷新恢复。
- qwen3.7-plus 多轮修改计划、确认后版本迭代、最近10个版本保留和破坏性线性回退。
- Vue Router、Pinia、Ant Design Vue、Vitest、ESLint、OxcLint、Prettier 和响应式工作台。
- Vite `/api`、`/sites` 代理以及适用于 POST SSE 的长超时配置。
- 可复现的 MySQL 容器、IDEA 内置 Maven 和 Java 21 自动发现脚本。

## 环境要求

- Windows PowerShell 5.1 或 PowerShell 7
- JDK 21
- IntelliJ IDEA 内置 Maven（当前为 Maven 3.9.11）
- Node.js `^22.18.0 || >=24.12.0`
- Docker Desktop（用于本地 MySQL）
- Playwright 托管 Chromium（通过项目脚本安装，不使用系统浏览器）

本机已发现的 JDK 21 位于 `C:\Users\Lenovo\.jdks\ms-21.0.12`。脚本会自动选择它，不会修改或删除现有 Java 17。

## 初始化

在仓库根目录执行：

```powershell
.\scripts\bootstrap.ps1
```

`bootstrap.ps1` 会自动查找 IDEA 内置 Maven、启动 MySQL、安装前端依赖并预下载后端 Maven 依赖。若本地配置不存在，它还会根据 `application-dev.example.yml` 创建：

```text
backend/config/application-dev.yml
```

首次运行真实代码生成前还需要安装发布前冒烟检查使用的 Chromium：

```powershell
.\scripts\install-playwright.ps1
```

Chromium 是正式版本发布的强制校验依赖。未安装或无法启动时，生成任务以
`BROWSER_VALIDATION_UNAVAILABLE` 失败，不会跳过检查或创建版本。

`application-dev.yml` 已加入 `.gitignore`，数据库密码和 API Key 可以直接写在其中，不会被 Git 跟踪，也不会被打包进 JAR。Spring Boot 默认启用 `dev` Profile，因此从 IDEA 直接运行 `VisionForgeApplication` 也会自动读取该文件。

当前机器已有 MySQL 占用 `3306`，所以项目 Docker MySQL 固定映射到 `3307`；后端本地配置已经与之对应。若只想安装代码依赖，可以执行：

```powershell
.\scripts\bootstrap.ps1 -SkipInfrastructure
```

## 本地开发

可以在 IDEA 中直接运行：

```text
backend/src/main/java/com/visionforge/VisionForgeApplication.java
```

也可以使用终端脚本启动后端：

```powershell
.\scripts\dev-backend.ps1
```

终端二：

```powershell
npm --prefix frontend run dev
```

访问地址：

- 工作台：<http://localhost:5173>
- 后端健康接口：<http://localhost:8080/api/system/health>
- Actuator：<http://localhost:8080/actuator/health>
- 会话恢复地址：`http://localhost:5173/workspace/{conversationId}`
- 后续生成站点：`http://127.0.0.1:8080/sites/{deployKey}/`

Flyway 会创建本地演示账号：

```text
账号：demo@visionforge.local
密码：VisionForge@2026
```

当前阶段主动跳过真实登录，所有会话、项目和版本统一归属于预置演示用户。首次生成默认直接执行，也可选择先规划；已有项目的修改必须经过计划讨论和确认。部署仍在后续阶段接入。

## 启用 DashScope OpenAI 兼容模式

云端模型默认关闭，因此没有 API Key 也能启动和调试会话接口；生成请求会返回 `503 AI_NOT_CONFIGURED`。需要生成真实页面时，编辑不会提交到 Git 的 `backend/config/application-dev.yml`：

```yaml
spring:
  ai:
    model:
      chat: openai
    openai:
      api-key: your-api-key
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      chat:
        completions-path: /v1/chat/completions
        options:
          model: qwen3.7-plus
          temperature: 0.2
```

页面生成与修改计划讨论均使用 `qwen3.7-plus`，分别读取 `visionforge.models.code` 和 `visionforge.models.discussion`。模型请求走 OpenAI 兼容接口。不要把真实 Key 写入 `application-dev.example.yml`。

生成期间文件位于 `runtime/tasks/{taskId}/`，校验成功后原子发布到：

```text
runtime/versions/{projectId}/{versionNumber}/
├── index.html
├── style.css    # 仅交互模式
└── script.js    # 仅交互模式
```

静态模式禁止 JavaScript、按钮、表单和无效链接；交互模式只允许版本目录内的三文件和本地 DOM 交互。外部资源、网络、存储、页面跳转和动态执行能力会被后端拒绝。

每轮产物会先执行结构与安全校验，再由隔离的无头 Chromium 加载入口，检查本地资源失败、未捕获 JavaScript 异常和控制台错误。检查只验证页面能够无网络加载，不自动点击按钮或推断业务行为。可修复错误最多自动重试 2 次，浏览器不可用、模型连接、取消、发布和数据库错误不会重试。

生成与预览接口：

```text
POST /api/conversations/{conversationId}/generations
GET  /api/generation-tasks/{taskId}
GET  /api/generation-tasks/{taskId}/files
GET  /api/generation-tasks/{taskId}/files/{path}
GET  /api/versions/{versionId}/files
GET  /api/versions/{versionId}/files/{path}
GET  /api/versions/{versionId}/preview/
GET  /api/versions/{versionId}/download
POST /api/conversations/{conversationId}/change-plans
POST /api/change-plans/{planId}/revisions
POST /api/change-plans/{planId}/apply
GET  /api/projects/{projectId}/versions
POST /api/projects/{projectId}/versions/{versionId}/rollback
```

## 质量检查

```powershell
.\scripts\check.ps1
```

### 后端中文 Doc 规范

- 所有公开类、接口、枚举和 Record 必须具有中文 Javadoc。
- 公开 Controller、Service 和 SPI 方法必须说明参数、返回值及重要失败语义。
- Record 通过类型 Javadoc 的 `@param` 逐项说明组件；持久化实体字段直接说明关联、可空、JSON、路径和生命周期含义。
- 接口实现的普通 `@Override` 继承接口契约，不重复复制注释；复杂安全、状态迁移和文件补偿逻辑说明设计原因。
- 不为简单 getter、显而易见的私有单行方法和测试样板添加无信息量注释。

Maven Checkstyle Doc 门禁绑定到 `validate` 阶段，因此以下命令都会自动检查公开 Doc：

```powershell
cd backend
mvn validate
mvn test
```

规则文件位于 `backend/config/checkstyle-doc.xml`，测试源码和 Lombok 生成方法不在检查范围内。

该命令依次执行前端 lint、格式检查、类型检查、单元测试和构建，再执行后端测试。

## 版本基线

| 组件 | 锁定版本 |
|---|---:|
| Java | 21 |
| Maven | IDEA Bundled 3.9.11 |
| Spring Boot | 3.5.10 |
| Spring AI | 1.1.2 |
| Spring AI Alibaba | 1.1.2.3 |
| MyBatis-Plus | 3.5.17 |
| MySQL | 8.4 LTS |
| Vue / Vite | 由 `frontend/package-lock.json` 锁定 |

当前只引入 MVP 所需的 MySQL。Playwright 现阶段仅用于发布前无头加载冒烟，不负责截图或视觉评价；Redis、Elasticsearch、RabbitMQ、OSS、Playwright 截图和 Vue 工程生成均按路线图留到后续阶段，不创建空模块或无效基础设施。