viewer：将 3d 模块重命名为 viewer，同步 README/文档/启动脚本/工具脚本路径与 npm 包名

.gitignore

@@ -5,8 +5,8 @@ __MACOSX/
 .venv/
 frontend/node_modules/
 frontend/dist/
-3d/frontend/node_modules/
-3d/frontend/dist/
+viewer/frontend/node_modules/
+viewer/frontend/dist/
 .env
 .env.*
 !.env.example

README.md

@@ -52,22 +52,22 @@ npm run build
 
 ## 3D 部件查看模块
 
-`3d/` 为独立的 3D 部件查看与配色模块（FastAPI 服务端 + Ant Design Vue 客户端）：
+`viewer/` 为独立的 3D 部件查看与配色模块（FastAPI 服务端 + Ant Design Vue 客户端）：
 
 ```bash
-python3 -m pip install -r 3d/backend/requirements.txt
-cd 3d/frontend && npm install
+python3 -m pip install -r viewer/backend/requirements.txt
+cd viewer/frontend && npm install
 
 # 开发：服务端 + 客户端（Vite 代理 /api、/models 到 5182）
-python3 3d/backend/run.py --reload       # http://127.0.0.1:5182
-cd 3d/frontend && npm run dev            # http://127.0.0.1:5183
+python3 viewer/backend/run.py --reload       # http://127.0.0.1:5182
+cd viewer/frontend && npm run dev            # http://127.0.0.1:5183
 
 # 生产：构建后由 FastAPI 单端口托管
-cd 3d/frontend && npm run build
-python3 3d/backend/run.py                # http://127.0.0.1:5182
+cd viewer/frontend && npm run build
+python3 viewer/backend/run.py                # http://127.0.0.1:5182
 ```
 
-详见 `3d/README.md`。
+详见 `viewer/README.md`。
 
 ## 主要接口
 

3d/README.md

@@ -6,7 +6,7 @@ Python（FastAPI）服务端 + Ant Design Vue（Vue3 + Vite + TypeScript）客
 ## 目录结构
 
 ```
-3d/
+viewer/
 ├─ backend/            # FastAPI 服务端（扁平结构，无 app/ 层）
 │  ├─ main.py          # 应用入口：鉴权、/api、/models、前端托管与 SPA 回退
 │  ├─ config.py        # 路径、运行模式与账号配置
@@ -35,20 +35,20 @@ Python（FastAPI）服务端 + Ant Design Vue（Vue3 + Vite + TypeScript）客
 ## 依赖
 
 ```bash
-python3 -m pip install -r 3d/backend/requirements.txt
-cd 3d/frontend && npm install
+python3 -m pip install -r viewer/backend/requirements.txt
+cd viewer/frontend && npm install
 ```
 
 ## 开发模式（前后端分离，热更新）
 
 ```bash
 # 终端 1：服务端
-python3 3d/backend/run.py --reload         # http://127.0.0.1:5182
+python3 viewer/backend/run.py --reload         # http://127.0.0.1:5182
 # 若 python3 被解析成系统解释器（zsh 命令缓存），改用：
-bash 3d/backend/run.sh --reload
+bash viewer/backend/run.sh --reload
 
 # 终端 2：客户端
-cd 3d/frontend
+cd viewer/frontend
 npm run dev                                # http://127.0.0.1:5183
 ```
 
@@ -60,8 +60,8 @@ Vite 已把 `/api`、`/models` 代理到 `http://127.0.0.1:5182`（见 `vite.con
 ## 生产模式（单端口）
 
 ```bash
-cd 3d/frontend && npm run build            # 产物：3d/frontend/dist
-bash 3d/backend/run_prod.sh --host 0.0.0.0 --port 5182   # 以 APP_MODE=prod 启动
+cd viewer/frontend && npm run build            # 产物：viewer/frontend/dist
+bash viewer/backend/run_prod.sh --host 0.0.0.0 --port 5182   # 以 APP_MODE=prod 启动
 ```
 
 FastAPI 托管 `frontend/dist`，非 `/api`、`/models` 的路径回退 `index.html`。
@@ -86,7 +86,7 @@ FastAPI 托管 `frontend/dist`，非 `/api`、`/models` 的路径回退 `index.h
 示例：
 
 ```bash
-APP_MODE=prod AUTH_USER=admin AUTH_PASSWORD='***' bash 3d/backend/run_prod.sh --port 5182
+APP_MODE=prod AUTH_USER=admin AUTH_PASSWORD='***' bash viewer/backend/run_prod.sh --port 5182
 ```
 
 ## 接口
@@ -112,9 +112,9 @@ APP_MODE=prod AUTH_USER=admin AUTH_PASSWORD='***' bash 3d/backend/run_prod.sh --
 
 ```bash
 # 按名字删除节点（世界变换烘焙，支持嵌套）
-python3 3d/tools/remove_nodes.py --input a.glb --output b.glb --name 三维立体
+python3 viewer/tools/remove_nodes.py --input a.glb --output b.glb --name 三维立体
 # 按查看器标签缩放零件
-python3 3d/tools/scale_part.py --input a.glb --label 区域_143 --width 3 --inplace
+python3 viewer/tools/scale_part.py --input a.glb --label 区域_143 --width 3 --inplace
 # 按平面拆分模块
-python3 3d/tools/split_glb.py --input a.glb --outdir 3d/models --prefix a --axis y --planes 16 32
+python3 viewer/tools/split_glb.py --input a.glb --outdir viewer/models --prefix a --axis y --planes 16 32
 ```

3d/backend/config.py

@@ -3,8 +3,8 @@
 import os
 from pathlib import Path
 
-BASE_DIR = Path(__file__).resolve().parent          # 3d/backend
-MODULE_DIR = BASE_DIR.parent                        # 3d
+BASE_DIR = Path(__file__).resolve().parent          # viewer/backend
+MODULE_DIR = BASE_DIR.parent                        # viewer
 MODELS_DIR = MODULE_DIR / "models"
 DATA_DIR = MODULE_DIR / "data"
 SCENE_CSV = DATA_DIR / "scene_positions.csv"

3d/backend/main.py

@@ -81,4 +81,4 @@ def serve_frontend(full_path: str) -> FileResponse:
     index = FRONTEND_DIST / "index.html"
     if index.is_file():
         return FileResponse(index)
-    raise HTTPException(status_code=404, detail="前端未构建：请先 cd 3d/frontend && npm run build")
+    raise HTTPException(status_code=404, detail="前端未构建：请先 cd viewer/frontend && npm run build")

3d/backend/run.py

@@ -2,8 +2,8 @@
 """启动 3D 服务端。
 
 用法：
-    python3 3d/backend/run.py                 # 默认 127.0.0.1:5182
-    python3 3d/backend/run.py --port 9100 --reload
+    python3 viewer/backend/run.py                 # 默认 127.0.0.1:5182
+    python3 viewer/backend/run.py --port 9100 --reload
 """
 
 import argparse
@@ -26,7 +26,7 @@ def _require_dependencies() -> None:
         f"  安装依赖: {sys.executable} -m pip install -r {req}\n"
         "\n提示：如果 `python3` 指向系统解释器（如 /usr/bin/python3），\n"
         "请先激活项目环境（conda activate compressor-wave），\n"
-        "或用 conda run -n compressor-wave python3 3d/backend/run.py 运行。\n",
+        "或用 conda run -n compressor-wave python3 viewer/backend/run.py 运行。\n",
     )
     raise SystemExit(1)
 

3d/backend/run.sh

@@ -2,9 +2,9 @@
 # 启动 3D 服务端（自动选用当前 conda/venv 环境的解释器，避免 PATH 缓存到系统 python）。
 #
 # 用法：
-#   bash 3d/backend/run.sh                 # 默认 127.0.0.1:5182
-#   bash 3d/backend/run.sh --reload
-#   bash 3d/backend/run.sh --port 5182
+#   bash viewer/backend/run.sh                 # 默认 127.0.0.1:5182
+#   bash viewer/backend/run.sh --reload
+#   bash viewer/backend/run.sh --port 5182
 set -e
 
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

3d/backend/run_prod.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # 生产启动：关闭测试模式（APP_MODE=prod），登录页不再自动填入账号密码。
 # 账号密码等可用环境变量覆盖，例如：
-#   AUTH_USER=admin AUTH_PASSWORD='***' bash 3d/backend/run_prod.sh --host 0.0.0.0 --port 5182
+#   AUTH_USER=admin AUTH_PASSWORD='***' bash viewer/backend/run_prod.sh --host 0.0.0.0 --port 5182
 set -e
 export APP_MODE="${APP_MODE:-prod}"
 exec "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/run.sh" "$@"

3d/docs/建模与GLB转换指南.md

@@ -1,8 +1,8 @@
 # 3D 机械图建模与 GLB 转换注意事项
 
 > 面向本程序（网页 3D 查看 + 每部件独立着色）的建模与导出规范。
-> 演示程序：`3d/`（FastAPI 服务端 + Ant Design Vue 客户端），
-> 运行 `python3 3d/backend/run.py`，模型放 `3d/models/*.glb`。详见 `3d/README.md`。
+> 演示程序：`viewer/`（FastAPI 服务端 + Ant Design Vue 客户端），
+> 运行 `python3 viewer/backend/run.py`，模型放 `viewer/models/*.glb`。详见 `viewer/README.md`。
 
 ---
 
@@ -61,7 +61,7 @@
 
 ## 五、STEP → GLB 推荐转换管线
 
-> 目标产物：`xxx.glb`（每部件一个 node + 独立材质，node 名=CAD 部件名），放 `3d/models/` 即完成接入。
+> 目标产物：`xxx.glb`（每部件一个 node + 独立材质，node 名=CAD 部件名），放 `viewer/models/` 即完成接入。
 
 **管线 A（推荐，免费可脚本化）**
 ```
@@ -90,7 +90,7 @@ CAD Exchanger SDK / Datakit CrossManager：一条命令 STEP→GLB，保留部
 
 ## 六、交付自检清单
 
-打开网页（`python3 3d/backend/run.py`，默认 http://127.0.0.1:5182）后逐项确认：
+打开网页（`python3 viewer/backend/run.py`，默认 http://127.0.0.1:5182）后逐项确认：
 
 - [ ] 顶部下拉能选到你的模型
 - [ ] 部件列表数量、名称与你 CAD 里的零件对应

3d/frontend/package-lock.json

@@ -1,11 +1,11 @@
 {
-  "name": "compressor-3d-viewer",
+  "name": "compressor-viewer",
   "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "compressor-3d-viewer",
+      "name": "compressor-viewer",
       "version": "0.1.0",
       "dependencies": {
         "@ant-design/icons-vue": "^7.0.1",

3d/frontend/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "compressor-3d-viewer",
+  "name": "compressor-viewer",
   "private": true,
   "version": "0.1.0",
   "type": "module",

3d/tools/remove_nodes.py

@@ -8,8 +8,8 @@
   --name NAME    原始名称精确匹配，删除所有同名节点
 
 用法：
-  python3 3d/remove_nodes.py --input a.glb --inplace --label 三维立体
-  python3 3d/remove_nodes.py --input a.glb --output b.glb --index 0 12
+  python3 viewer/tools/remove_nodes.py --input a.glb --inplace --label 三维立体
+  python3 viewer/tools/remove_nodes.py --input a.glb --output b.glb --index 0 12
 """
 import argparse, os, sys
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

3d/tools/scale_part.py

@@ -5,7 +5,7 @@
 所以 width=3 表示两边各 +100%（总宽变 3 倍），length=1.5 表示两边各 +25%。
 
 用法：
-  python3 3d/scale_part.py --input a.glb --label 区域_143 --width 3 --length 1.5 --inplace
+  python3 viewer/tools/scale_part.py --input a.glb --label 区域_143 --width 3 --length 1.5 --inplace
 """
 import argparse, os, sys
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

3d/tools/split_glb.py

@@ -6,10 +6,10 @@
   - 跨越分割面的共享零件（如地板），在分割面处做几何裁剪，每个模块各留一段。
 
 用法示例：
-  python3 3d/split_glb.py \
-      --input 3d/压缩机2326-3000.glb \
+  python3 viewer/tools/split_glb.py \
+      --input viewer/压缩机2326-3000.glb \
       --axis y --planes 16 32 \
-      --outdir 3d/models --prefix 压缩机2326-3000
+      --outdir viewer/models --prefix 压缩机2326-3000
 """
 import argparse, json, os, struct
 import numpy as np