# Astral3D 项目说明

## 项目简介

Astral3D 是一个基于 Vue3 + Three.js 的现代 Web 3D 编辑器，同时包含配套的 Java 后端服务。项目旨在提供一站式 3D 场景创建、管理和展示解决方案。

**在线演示**: [Astral 3D Editor](https://editor.astraljs.com)

---

## 项目结构

```
Astral3D-Projects/
├── Astral3D/              # 前端编辑器项目 (Vue3 + Three.js)
│   ├── packages/          # 子包
│   ├── common/           # 公共模块
│   └── node_modules/     # 依赖
│
├── astral-service/        # 后端服务项目 (Java + SpringBoot)
│   ├── astral-common/    # 公共模块
│   ├── astral-core/      # 核心配置
│   ├── astral-business/  # 业务模块
│   ├── astral-system/    # 系统模块
│   ├── astral-web/       # Web 层
│   └── static/           # 静态资源
│
└── docs/                  # 文档目录
```

---

## 技术栈

### 前端 (Astral3D)

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.22 | 渐进式前端框架 |
| Three.js | r176 | 3D 渲染引擎 |
| Cesium | 1.107.0 | 地理信息系统 |
| Naive UI | 2.43.1 | UI 组件库 |
| UnoCSS | 0.46.5 | 原子化 CSS |

### 后端 (AstralService)

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 8 | 编程语言 |
| Spring Boot | 2.7.18 | Web 框架 |
| MyBatis Plus | - | ORM 框架 |
| MySQL | - | 数据库 |
| WebSocket | - | 实时通信 |

---

## 核心功能

### 前端功能

- **多格式模型支持**: 30+ 模型格式（GLTF/OBJ/FBX/GLB/RVT/IFC 等）
- **BIM 模型轻量化**: RVT/IFC 文件浏览器端展示
- **CAD 图纸解析**: DWG/DXF 文件解析和展示
- **场景管理**: 分包存储与动态加载
- **动画编辑器**: 内置动画制作工具
- **插件系统**: 扩展能力支持
- **脚本运行时**: 脚本化业务逻辑
- **粒子系统**: 视觉效果增强
- **天气系统**: 场景环境模拟
- **云存储集成**: 又拍云 USS 支持
- **资源中心**: 统一资源管理

### 后端功能

- **用户认证**: 用户注册登录
- **场景管理**: 场景 CRUD 操作
- **资产管理**: 资源上传、存储、加载
- **文件转换**: CAD DWG 转 DXF
- **WebSocket**: 实时通信支持

---

## 快速开始

### 前端开发

```bash
# 进入前端项目
cd Astral3D

# 使用 nvm 切换 Node 版本
nvm use 23.11.0

# 安装依赖
pnpm install

# 构建 SDK
pnpm run sdk:build

# 启动开发服务器
pnpm run editor:dev
```

### 后端服务

```bash
# 进入后端项目
cd astral-service

# 配置数据库
# 修改 astral-web/src/main/resources/application-dev.yml

# 方式一：IDEA 直接运行
# 运行 AstralWebApplication 类

# 方式二：Maven 运行
mvn spring-boot:run

# 方式三：打包运行
mvn clean package
cd astral-web/target
java -jar astral-web-exec.jar
```

---

## 数据库配置

1. 创建 MySQL 数据库
2. 导入表结构：`static/sql/astral_3d.sql`
3. 修改配置文件中的数据库连接信息

---

## 文件存储配置

支持两种存储方式：

- **本地存储 (local)**: 保存在项目 static 文件夹
- **又拍云存储 (upyun)**: 云端存储

---

## 文档目录

| 文档 | 说明 |
|------|------|
| [二开改造方案.md](docs/二开改造方案.md) | 二次开发视觉改造方案（新品牌 Logo、配色、UI 风格） |
| [digital-atelier-philosophy.md](docs/digital-atelier-philosophy.md) | 设计哲学：Digital Atelier 理念 |
| [ui-migration-todo.md](docs/ui-migration-todo.md) | UI 迁移待办：NaiveUI → Shadcn UI |
| [css-migration-spec.md](docs/css-migration-spec.md) | CSS 样式迁移规范 |
| [GIT_TUTORIAL.md](docs/GIT_TUTORIAL.md) | Git 操作教程 |

---

## 许可证

本项目基于 Apache 2.0 许可证开源，详细内容请参阅 [LICENSE](../Astral3D/LICENSE) 文件。

---

## 相关链接

- [在线演示](https://editor.astraljs.com)
- [文档中心](http://editor-doc.astraljs.com/)
- [代码仓库](http://code-server:3000/lyf/Astral3D.git)

---