From cded246736afe74607ed3047afd07e480c15426c Mon Sep 17 00:00:00 2001 From: lyf <2514544224@qq.com> Date: Thu, 12 Mar 2026 23:06:17 +0800 Subject: [PATCH] Add README and documentation files - Add project README.md with overview - Add GIT_TUTORIAL.md documentation Made-with: Cursor --- README.md | 170 ++++++++++++++++++++ docs/GIT_TUTORIAL.md | 364 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 534 insertions(+) create mode 100644 README.md create mode 100644 docs/GIT_TUTORIAL.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a05837f --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# 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)**: 云端存储 + +--- + +## 文档目录 + +| 文档 | 说明 | +|------|------| +| [GIT_TUTORIAL.md](../GIT_TUTORIAL.md) | Git 操作教程 | + +--- + +## 许可证 + +本项目基于 Apache 2.0 许可证开源，详细内容请参阅 [LICENSE](../Astral3D/LICENSE) 文件。 + +--- + +## 相关链接 + +- [在线演示](https://editor.astraljs.com) +- [文档中心](http://editor-doc.astraljs.com/) +- [后端仓库](https://github.com/yx8663/astral-service) +- [前端仓库](https://github.com/mlt131220/Astral3D) + +--- + +## 交流社区 + +- QQ 交流群：1040320579 +- 微信：联系开发者（仅限商务） diff --git a/docs/GIT_TUTORIAL.md b/docs/GIT_TUTORIAL.md new file mode 100644 index 0000000..5434d27 --- /dev/null +++ b/docs/GIT_TUTORIAL.md @@ -0,0 +1,364 @@ +# Git 提交操作教程 + +本教程适用于 Astral3D 项目，包含日常开发中常用的 Git 操作流程。 + +--- + +## 基础配置 + +首次使用需配置用户信息（已完成）： + +```bash +git config user.name "用户名" +git config user.email "邮箱" +``` + +查看配置： + +```bash +git config --list +``` + +--- + +## 远程仓库 + +项目远程仓库地址：`http://code-server:3000/lyf/Astral3D.git` + +查看远程仓库： + +```bash +git remote -v +``` + +--- + +## 常用操作流程 + +### 1. 拉取最新代码 + +```bash +# 拉取远程最新代码并合并到当前分支 +git pull origin master + +# 或者使用 fetch + rebase +git fetch origin +git rebase origin/master +``` + +### 2. 查看当前状态 + +```bash +# 查看工作区状态 +git status + +# 查看简略状态 +git status -s +``` + +### 3. 查看文件变更 + +```bash +# 查看未暂存的变更 +git diff + +# 查看已暂存的变更 +git diff --cached + +# 查看具体文件的变更 +git diff filename.java + +# 查看最近几次提交 +git log --oneline -5 +``` + +### 4. 暂存文件 + +```bash +# 暂存单个文件 +git add filename.java + +# 暂存多个文件 +git add file1.java file2.java + +# 暂存所有变更 +git add . + +# 暂存所有 .java 文件 +git add *.java + +# 暂存目录 +git add src/ +``` + +### 5. 取消暂存 + +```bash +# 取消所有暂存 +git reset + +# 取消单个文件暂存 +git reset filename.java +``` + +### 6. 撤销修改 + +```bash +# 撤销未暂存的修改（危险操作） +git checkout -- filename.java + +# 撤销所有未暂存的修改 +git checkout -- . + +# 撤销已暂存的修改 +git reset HEAD filename.java +git checkout -- filename.java +``` + +### 7. 提交变更 + +```bash +# 提交已暂存的变更 +git commit -m "提交说明" + +# 提交并添加说明（会打开编辑器） +git commit + +# 修改最后一次提交（还没推送到远程） +git commit --amend -m "新的提交说明" + +# 将暂存和提交合并为一步（适合小改动） +git commit -am "提交说明" +``` + +### 8. 推送到远程 + +```bash +# 推送到远程仓库 +git push origin master + +# 第一次推送并设置上游分支 +git push -u origin master + +# 简化写法（已设置上游分支后） +git push +``` + +### 9. 查看提交历史 + +```bash +# 查看详细提交历史 +git log + +# 查看简略历史 +git log --oneline + +# 查看最近5条 +git log --oneline -5 + +# 查看分支合并历史 +git log --graph --oneline --all +``` + +--- + +## 分支操作 + +### 1. 查看分支 + +```bash +# 查看本地分支 +git branch + +# 查看远程分支 +git branch -r + +# 查看所有分支 +git branch -a +``` + +### 2. 创建分支 + +```bash +# 基于当前分支创建新分支 +git branch feature-xxx + +# 基于 master 创建新分支 +git branch feature-xxx master +``` + +### 3. 切换分支 + +```bash +# 切换到分支 +git checkout feature-xxx + +# 创建并切换到新分支 +git checkout -b feature-xxx + +# 切换到上一个分支 +git checkout - +``` + +### 4. 合并分支 + +```bash +# 切换到 master 分支 +git checkout master + +# 合并 feature-xxx 分支到当前分支 +git merge feature-xxx + +# 使用 rebase 合并（保持线性历史） +git rebase feature-xxx +``` + +### 5. 删除分支 + +```bash +# 删除本地分支（已合并） +git branch -d feature-xxx + +# 强制删除本地分支 +git branch -D feature-xxx + +# 删除远程分支 +git push origin --delete feature-xxx +``` + +--- + +## 标签操作 + +### 1. 创建标签 + +```bash +# 创建轻量标签 +git tag v1.0.0 + +# 创建附注标签（带说明） +git tag -a v1.0.0 -m "版本说明" + +# 为历史提交打标签 +git tag -a v1.0.0 commitid -m "版本说明" +``` + +### 2. 查看和推送标签 + +```bash +# 查看标签 +git tag + +# 查看标签详情 +git show v1.0.0 + +# 推送标签到远程 +git push origin v1.0.0 + +# 推送所有标签 +git push origin --tags +``` + +--- + +## 解决冲突 + +### 1. 识别冲突 + +```bash +# 查看冲突文件 +git status +``` + +冲突文件会显示为 `both modified` + +### 2. 手动解决冲突 + +打开冲突文件，会看到类似以下标记： + +``` +<<<<<<< HEAD +当前分支的代码 +======= +合并进来的代码 +>>>>>>> branch-name +``` + +手动修改后： + +```bash +# 标记冲突已解决 +git add filename.java + +# 完成合并 +git commit +``` + +--- + +## 暂存操作（Stash） + +用于临时保存未提交的更改： + +```bash +# 暂存当前更改 +git stash + +# 暂存并添加说明 +git stash save "临时保存说明" + +# 查看暂存列表 +git stash list + +# 恢复暂存的更改 +git stash pop + +# 删除暂存 +git stash drop +``` + +--- + +## 常见问题 + +### 1. 代理问题 + +如果推送时遇到 503 错误，尝试设置代理排除： + +```bash +export no_proxy="code-server,192.168.1.72,localhost,127.0.0.1" +git push origin master +``` + +### 2. 每次推送都要输入密码 + +可以配置凭证缓存： + +```bash +# 缓存凭证 15 分钟 +git config --global credential.helper cache + +# 缓存更长时间（单位：秒） +git config --global credential.helper 'cache --timeout=3600' +``` + +### 3. 查看配置 + +```bash +# 查看所有配置 +git config --list + +# 查看特定配置 +git config user.name +git config remote.origin.url +``` + +--- + +## 最佳实践 + +1. **提交前先拉取**：每次提交前先 `git pull origin master` +2. **保持提交原子性**：一个提交只做一件事 +3. **提交说明清晰**：说明改了什么，为什么改 +4. **不要提交敏感信息**：不要提交密码、密钥等 +5. **使用 .gitignore**：排除不需要跟踪的文件（如 target/、.idea/）