# 压缩机 3D 部件查看与配色

Python（FastAPI）服务端 + Ant Design Vue（Vue3 + Vite + TypeScript）客户端。
加载 `models/*.glb`，按部件单独选中与着色，配色状态持久化到 `data/color_state.json`。

## 目录结构

```
3d/
├─ backend/            # FastAPI 服务端（扁平结构，无 app/ 层）
│  ├─ main.py          # 应用入口：/api、/models、前端托管与 SPA 回退
│  ├─ config.py        # 路径配置
│  ├─ routers/         # files.py（模型）、state.py（配色状态）
│  ├─ services/        # model_service、state_service
│  ├─ run.py           # 启动脚本
│  └─ requirements.txt
├─ frontend/           # Ant Design Vue 客户端
│  └─ src/
│     ├─ api/          # 接口封装（axios）
│     ├─ stores/       # pinia：model / parts / viewer
│     ├─ three/        # 纯 three.js 逻辑（Viewer.ts 等）
│     ├─ composables/  # useThreeViewer（Vue 与 three 的桥接）
│     ├─ components/   # TopBar / ViewerCanvas / DataPanel / 卡片 / 查询弹窗
│     ├─ types/        # 类型定义
│     └─ styles/
├─ tools/              # CAD/GLB 处理脚本（split_glb / remove_nodes / scale_part）
├─ models/             # *.glb 模型
├─ data/               # color_state.json
└─ docs/               # 建模与GLB转换指南.md
```

## 依赖

```bash
python3 -m pip install -r 3d/backend/requirements.txt
cd 3d/frontend && npm install
```

## 开发模式（前后端分离，热更新）

```bash
# 终端 1：服务端
python3 3d/backend/run.py --reload         # http://127.0.0.1:5182
# 若 python3 被解析成系统解释器（zsh 命令缓存），改用：
bash 3d/backend/run.sh --reload

# 终端 2：客户端
cd 3d/frontend
npm run dev                                # http://127.0.0.1:5183
```

> 排查：`which python3` 若显示 `/usr/bin/python3` 之类的系统解释器，执行 `hash -r`（zsh）或重开终端；
> `run.sh` 会优先使用当前 conda/venv 环境（`$CONDA_PREFIX/bin/python`），不受 PATH 缓存影响。

Vite 已把 `/api`、`/models` 代理到 `http://127.0.0.1:5182`（见 `vite.config.ts`）。

## 生产模式（单端口）

```bash
cd 3d/frontend && npm run build            # 产物：3d/frontend/dist
python3 3d/backend/run.py --host 0.0.0.0 --port 5182
```

FastAPI 托管 `frontend/dist`，非 `/api`、`/models` 的路径回退 `index.html`。

## 接口

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/models` | 可用模型名列表 |
| GET | `/api/state?model=x` | 读取某模型的配色状态 |
| POST | `/api/state?model=x` | 保存配色状态（body 为 `{部件id: {color, status}}`） |
| GET | `/models/<file>` | GLB / glTF 模型文件 |

## CAD 工具

```bash
# 按名字删除节点（世界变换烘焙，支持嵌套）
python3 3d/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 3d/tools/split_glb.py --input a.glb --outdir 3d/models --prefix a --axis y --planes 16 32
```