# ai-application-designer

**Repository Path**: yi-shui_a/ai-application-designer

## Basic Information

- **Project Name**: ai-application-designer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Application Designer (SiteGenie)

零代码 AI 网站生成平台 —— 从自然语言需求到可部署网页应用的全链路自动化。

> **完整项目规格文档**：[docs/PROJECT_SPEC.md](docs/PROJECT_SPEC.md) —— 涵盖架构设计、数据库 Schema、API 规范、AI 能力体系、配置说明等，是开发和 AI 协作的核心参考。

## 环境要求

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| Java | 21 | Spring Boot 3.5 要求 |
| Node.js | 18.17+ | Vite 7 要求，推荐 22+ |
| Docker | 20+ | 中间件部署 |
| Docker Compose | 2.0+ | 中间件编排 |

> Maven 不需要单独安装，项目使用 `./mvnw`（Maven Wrapper）。

## 项目概述

本项目是一个面向零代码建站的 AI 应用生成平台，基于 Spring Boot + LangChain4j 构建核心架构。通过 Function Calling、Agent Skills、Workflow 实现从需求输入到代码生成、构建、发布的全链路自动化。

### 核心能力

- **多模型统一接入**：支持 DashScope（通义千问）、小米 MiMo 等 OpenAI 兼容 API
- **三种代码生成模式**：HTML 单文件、多文件、Vue 工程项目
- **Agent Skills 体系**：可版本化的能力包（Prompt 模板 + 工具白名单 + 运行时策略）
- **Skill 组件市场**：独立 Market 微服务，Skill CRUD + 版本管理 + 应用绑定 + Redis L1 缓存
- **Metadata 评分选取**：零 LLM 调用的 Skill 选取策略，三层短路 + 加权评分，延迟 < 1ms
- **事件驱动分片**：Market 通过 RocketMQ 触发 AI 分片，消除 Dubbo 循环依赖
- **三层缓存体系**：Caffeine L0(AI) + Redis L1(Market) + MySQL L2
- **LangGraph4j 工作流编排**：18 节点 DAG，支持串行/并行分支
- **四层记忆系统**：MySQL 全量历史 + Redis 窗口记忆 + MinIO 压缩记忆 + Caffeine 实例缓存
- **三级限流治理**：USER/IP/API 维度，Redisson + AOP 实现
- **异步可靠架构**：Outbox + RocketMQ + 幂等消费 + DLQ 回放
- **多租户工作空间**：workspace + RBAC 四角色 + 邀请系统 + 配额追踪 + 套餐订阅 + 平台管理后台
- **SSE 租户透传**：AI 对话流式请求自动注入 X-Workspace-Id，WorkspaceFilter + TenantConfiguration 自动隔离
- **空间管理后台**：空间/套餐/订阅/数据概览 全平台管理，独立 AdminLayout 侧栏
- **完整发布链路**：版本快照 → 发布申请 → 审批 → 异步构建/部署 → 状态轮询
- **智能素材收集**：LLM 规划 → Pexels/Undraw/Mermaid 并行采集 → OSS 持久化 → Prompt 注入，全链路降级不阻塞

---

## 快速开始

### 方式一：Docker Compose 一键启动（推荐）

#### 第一步：拉取所有中间件镜像

```bash
docker pull mysql:8.0
docker pull redis:7-alpine
docker pull nacos/nacos-server:v2.2.3
docker pull apache/rocketmq:4.9.4
docker pull apacherocketmq/rocketmq-dashboard:2.0.0
docker pull minio/minio:latest
```

#### 第二步：启动中间件

```bash
cd docker-compose
docker compose up -d
```

启动后 MySQL 自动执行 `sql/init-all.sql`，完成建表和测试数据插入。

> **自定义端口**：`docker-compose/.env` 文件可配置所有中间件端口和凭据，修改后重新 `docker compose up -d` 即可生效。
>
> **RocketMQ 配置**：Broker 的注册 IP 已通过 `docker-compose/rocketmq/broker.conf` 固定为 `127.0.0.1`，宿主机 App 可直接访问。`docker compose up -d` 后自动生效，无需额外配置。
>
> **重新初始化数据库**：SQL 初始化仅在 MySQL 首次启动（数据卷为空）时执行。如需重新初始化，执行 `docker compose down -v` 后再 `docker compose up -d`。

#### 第三步：验证服务状态

```bash
docker compose ps
```

确认以下 9 个容器均为 healthy/running 状态：

| 容器 | 端口 | 验证方式 |
|------|------|---------|
| ai-designer-mysql | 3306 | `mysql -uroot -proot -e "SELECT 1"` |
| ai-designer-redis | 6379 | `redis-cli ping` |
| ai-designer-nacos | 8848 | http://localhost:8848/nacos |
| ai-designer-rocketmq-namesrv | 9876 | - |
| ai-designer-broker-a | 10911 | RocketMQ Dashboard |
| ai-designer-broker-a-slave | 10921 | RocketMQ Dashboard |
| ai-designer-broker-b | 10931 | RocketMQ Dashboard |
| ai-designer-rocketmq-dashboard | 18080 | http://localhost:18080 |
| ai-designer-minio | 9000/9001 | http://localhost:9001 (minioadmin/minioadmin) |

#### 第四步：配置 LLM API Key

在 AI 服务目录下创建 `application-local.yml`：

```bash
# 微服务模式
cp ai-application-designer-microservice/ai-application-designer-ai/src/main/resources/application.yml \
   ai-application-designer-microservice/ai-application-designer-ai/src/main/resources/application-local.yml

# 单体模式（如使用单体模式）
# application-local.yml 放在 src/main/resources/ 下
```

编辑 `application-local.yml`，填入你的 API Key：

```yaml
langchain4j:
  open-ai:
    chat-model:
      api-key: your-api-key-here
    streaming-chat-model:
      api-key: your-api-key-here
    reasoning-streaming-chat-model:
      api-key: your-api-key-here
    routing-chat-model:
      api-key: your-api-key-here
```

支持的模型服务：DashScope（通义千问）、小米 MiMo 等 OpenAI 兼容 API。详见 [tutorial/04-LLM-API-Key配置.md](tutorial/04-LLM-API-Key配置.md)。

#### 第五步：启动后端服务

```bash
# 微服务模式（按顺序启动）
./mvnw -f ai-application-designer-microservice/pom.xml clean install -DskipTests
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-user spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-oss spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-market spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-ai spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-execution spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-app spring-boot:run
```

#### 第六步：启动前端

```bash
cd ai-application-designer-frontend
npm install
npm run dev
```

访问 http://localhost:5173。

> **重要**：开发环境默认通过同源 `/api` 访问后端，由 `vite.config.ts` 代理转发。
> - **网关模式**：`/api` 代理到 `http://localhost:8080`
> - **微服务直连模式**：`/api/user` → 8124，`/api/skill` → 8129，其余 `/api` → 8125
> - **单体模式**：如需单体启动，请将代理目标改为 `http://localhost:8123`
>
> 不要把开发环境的 `VITE_GATEWAY_URL` 配成 `http://localhost:8080/api` 这类绝对地址，否则浏览器会直接跨域请求网关，登录和注册会触发 CORS 问题。

### 方式二：手动启动

详见 [tutorial/01-Docker镜像下载.md](tutorial/01-Docker镜像下载.md) 至 [tutorial/04-LLM-API-Key配置.md](tutorial/04-LLM-API-Key配置.md)。

---

## 项目结构

```
ai-application-designer/
├── ai-application-designer-frontend/      # Vue 3 前端
├── ai-application-designer-microservice/  # 微服务后端（9 个子模块）
│   ├── ai-application-designer-common/    # 公共常量、工具类
│   ├── ai-application-designer-model/     # 实体、DTO、VO、枚举
│   ├── ai-application-designer-client/    # Dubbo 服务契约
│   ├── ai-application-designer-user/      # 用户服务
│   ├── ai-application-designer-app/       # 应用服务（业务编排中枢）
│   ├── ai-application-designer-ai/        # AI 服务（模型调用、工具执行）
│   ├── ai-application-designer-execution/ # 执行服务（构建、部署、截图、记忆压缩）
│   ├── ai-application-designer-market/    # 组件市场服务（Skill CRUD、绑定管理、Redis L1 缓存）
│   └── ai-application-designer-oss/       # 对象存储服务
├── src/                                   # 单体模式源码
├── pom.xml                                # 单体模式 Maven 配置
├── mvnw / mvnw.cmd                        # Maven Wrapper
├── sql/                                   # 数据库脚本
├── docker-compose/                        # Docker 编排文件
├── nginx.conf                             # Nginx 配置（静态资源 + MinIO 代理）
├── tutorial/                              # 环境搭建教程
├── docs/                                  # 设计文档
├── grafana/                               # Grafana 面板配置
└── prometheus.yml                         # Prometheus 抓取配置
```

### 运行模式

项目支持两种运行模式：

| 模式 | 说明 | 端口 | 适用场景 |
|------|------|------|---------|
| 微服务模式 | 6 个独立服务，Dubbo + MQ 通信 | 8124-8129 | 推荐，与生产一致 |
| 单体模式 | 所有模块打包为一个 Spring Boot 应用 | 8123 | 快速验证，不依赖 Nacos/RocketMQ |

- **微服务模式**代码在 `ai-application-designer-microservice/`，需要启动全部中间件
- **单体模式**代码在项目根目录（`pom.xml`），只需 MySQL + Redis + MinIO
- 两种模式共享 `common`、`model`、`client` 模块

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Java 21 + Spring Boot 3.5 + MyBatis-Flex |
| 微服务 | Dubbo 3.3 + Nacos 2.2 |
| AI 框架 | LangChain4j + OpenAI 兼容 API |
| 消息队列 | RocketMQ 5.2（事件驱动分片 + 缓存失效通知） |
| 缓存 | Redis 7 + Caffeine |
| 对象存储 | MinIO |
| 数据库 | MySQL 8.0 |
| 前端 | Vue 3 + TypeScript + Ant Design Vue + Vite |
| 可观测 | Prometheus + Grafana |

---

## 端口规划

### 微服务端口

| 服务 | HTTP | Dubbo | 说明 |
|------|------|-------|------|
| user | 8124 | 50051 | 用户与会话 |
| app | 8125 | 50053 | 应用编排中枢 |
| ai | 8126 | 50054 | AI 模型调用 |
| execution | 8127 | 50052 | 异步任务执行 |
| market | 8129 | 50056 | 组件市场（Skill CRUD、绑定、缓存） |
| oss | 8128 | 50055 | 对象存储 |

### 中间件端口

| 服务 | 端口 | 管理界面 |
|------|------|---------|
| MySQL | 3306 | - |
| Redis | 6379 | - |
| Nacos | 8848 | http://localhost:8848/nacos |
| RocketMQ NameServer | 9876 | - |
| RocketMQ Broker-A (Master) | 10911 | - |
| RocketMQ Broker-A (Slave) | 10921 | - |
| RocketMQ Broker-B (Master) | 10931 | - |
| RocketMQ Dashboard | 18080 | http://localhost:18080 |
| MinIO API | 9000 | - |
| MinIO Console | 9001 | http://localhost:9001 |
| 前端开发服务器 | 5173 | http://localhost:5173 |

---

## 测试账号

所有测试账号密码均为 `12345678`。

| 用户名 | userRole | 说明 |
|--------|---------|------|
| admin | admin | 管理员，拥有全部权限 |
| admin2 | admin | 运维管理员，负责部署和监控 |
| testuser | user | 测试用户，日常功能测试 |
| developer | user | 开发者，工作流和技能测试 |
| designer | user | UI 设计师，UI 设计和原型 |
| pm | user | 产品经理，需求定义和项目管理 |

---

## 快速体验

启动全部服务后，按以下步骤体验核心功能：

1. 访问 http://localhost:5173，使用 `testuser` / `12345678` 登录
2. 在首页点击"创建应用"，输入需求描述（如"做一个个人博客首页"）
3. 选择代码生成模式（HTML 最快，VUE_PROJECT 功能最全）
4. 等待 AI 生成完成，预览生成的网页
5. 点击"发布"将应用部署到本地，获得访问链接

测试数据中已包含示例应用和对话历史，可直接查看。

---

## 开发指南

### 前端开发

```bash
cd ai-application-designer-frontend
npm install
npm run dev
```

默认访问 http://localhost:5173。需根据后端模式修改 `vite.config.ts` 的 proxy target（单体模式为 8123，微服务模式为 8125）。

### 后端开发（单体模式）

```bash
# 初始化数据库
mysql -uroot -proot < sql/init-all.sql

# 启动单体服务
./mvnw spring-boot:run
```

访问 http://localhost:8123/api/doc.html 查看 API 文档。

### 后端开发（微服务模式）

```bash
# 构建
./mvnw -f ai-application-designer-microservice/pom.xml clean install -DskipTests

# 按顺序启动各服务（user → oss → market → ai → execution → app）
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-user spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-oss spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-market spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-ai spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-execution spring-boot:run
./mvnw -f ai-application-designer-microservice/pom.xml -pl ai-application-designer-app spring-boot:run
```

### 运行测试

```bash
# 单体模式测试
./mvnw test

# 微服务模式测试
./mvnw -f ai-application-designer-microservice/pom.xml test
```

> 注意：部分测试涉及 AI 服务调用，需要配置有效的 API Key 才能通过。

---

## API 文档

启动后端服务后访问 Knife4j 文档：

- 单体模式：http://localhost:8123/api/doc.html
- 微服务 user：http://localhost:8124/api/doc.html
- 微服务 app：http://localhost:8125/api/doc.html
- 微服务 ai：http://localhost:8126/doc.html（无 context-path）
- 微服务 execution：http://localhost:8127/api/doc.html
- 微服务 oss：http://localhost:8128/api/doc.html
- 微服务 market：http://localhost:8129/api/doc.html

---

## Nginx 配置（可选）

项目根目录的 `nginx.conf` 提供：
- 静态资源服务（端口 80）：访问已部署的应用
- MinIO S3 代理（`s3.localhost`）：OSS 服务的文件存储端点
- MinIO Console 代理（`minio.localhost`）

开发环境下 Nginx 非必须（部署目录直接由后端服务读取）。生产部署时需配置 Nginx。

---

## 可观测性

- **Prometheus**：抓取各服务 Actuator 指标，配置见 `prometheus.yml`
- **Grafana**：AI 模型调用面板，配置见 `grafana/ai_model_grafana_config.json`
- **自定义指标**：
  - AI 模型调用次数、Token 用量、响应时间
  - 记忆压缩成功/失败次数、耗时
  - 记忆读取命中/降级次数

---

## 文档索引

### 持续有效文档

| 文档 | 说明 |
|------|------|
| [docs/PROJECT_SPEC.md](docs/PROJECT_SPEC.md) | 项目完整规格说明（核心参考文档） |
| [docs/spec/微服务化与组件市场架构方案.md](docs/spec/微服务化与组件市场架构方案.md) | Skill 微服务化与组件市场架构设计 v2 |
| [docs/spec/skill-auto-slicing-design.md](docs/spec/skill-auto-slicing-design.md) | Skill 自动分片详细设计 |
| [docs/Timeout-And-Token-Configuration.md](docs/Timeout-And-Token-Configuration.md) | 工作流超时与Token配置指南 |
| [docs/AI-E2E-Test-Procedure.md](docs/AI-E2E-Test-Procedure.md) | AI端到端测试流程 |

### 归档文档

历史设计文档、分析报告和已完成的任务文档已归档至 [docs/archived/](docs/archived/)，按完成时间排序，详见该目录下的 `00-archived-README.md`。

### 教程文档

| 文档 | 说明 |
|------|------|
| [tutorial/01-Docker镜像下载.md](tutorial/01-Docker镜像下载.md) | Docker 镜像拉取指南 |
| [tutorial/02-DockerCompose环境搭建.md](tutorial/02-DockerCompose环境搭建.md) | Docker Compose 启动指南 |
| [tutorial/03-测试数据初始化.md](tutorial/03-测试数据初始化.md) | 测试数据说明 |
| [tutorial/04-LLM-API-Key配置.md](tutorial/04-LLM-API-Key配置.md) | LLM API Key 配置 |

---

## 常见问题

**前端启动后 API 请求失败（404 或连接拒绝）**
检查 `vite.config.ts` 的 proxy target 是否与后端端口一致。默认值 `http://localhost:8080` 不匹配任何服务，需改为 `http://localhost:8125`（微服务）或 `http://localhost:8123`（单体）。

**MySQL 容器启动后表不存在**
SQL 初始化仅在首次启动时执行。如需重新初始化：`docker compose down -v && docker compose up -d`。

**微服务启动报 Dubbo 连接失败**
确保 Nacos 已启动（http://localhost:8848/nacos），且服务按顺序启动：user → oss → market → ai → execution → app。

**Market 服务启动报 Redis 连接失败**
确保 Redis 已启动（端口 6379）。Market 服务依赖 Redis 作为 Skill 运行时数据的 L1 缓存。

**AI 生成报错 "API Key not configured"**
检查 `application-local.yml` 是否存在且包含有效的 API Key。该文件需手动创建，不会被 git 拉取。

**MinIO 连接失败**
确认 MinIO 已启动（http://localhost:9001），默认凭据 `minioadmin/minioadmin`。

**端口被占用**
执行 `netstat -ano | findstr :端口号`（Windows）或 `lsof -i :端口号`（Mac/Linux）查找占用进程。可在 `docker-compose/.env` 中修改端口映射。

**Docker 内存不足**
Nacos + RocketMQ + MySQL + Redis + MinIO 合计建议至少 4GB 内存。Docker Desktop 用户需在 Settings → Resources 中调整内存限制。

**Linux/Mac 下 mvnw 权限不足**
执行 `chmod +x mvnw` 后重试。

---

## 安全提示

- `application-local.yml` 已被 `.gitignore` 忽略，不要提交 API Key
- 测试密码仅用于开发环境，生产部署请修改
- MinIO 默认凭据 `minioadmin/minioadmin` 需在生产环境更换