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

Python（FastAPI）服务端 + Ant Design Vue（Vue3 + Vite + TypeScript）客户端。
加载 `models/*.glb`，按部件单独选中与着色；故障列表、曲线、场景位置、故障↔部件对照等。

## 目录结构

```
3d/
├─ backend/            # FastAPI 服务端（扁平结构，无 app/ 层）
│  ├─ main.py          # 应用入口：鉴权、/api、/models、前端托管与 SPA 回退
│  ├─ config.py        # 路径、运行模式与账号配置
│  ├─ auth.py          # 登录鉴权（内存 token、require_auth 依赖）
│  ├─ routers/         # files / alarms / series / scenes / fault_map
│  ├─ services/        # model / alarm / series / scene / fault_map
│  ├─ run.py           # 启动脚本
│  ├─ run.sh           # 启动脚本（自动选当前 conda/venv 解释器）
│  ├─ run_prod.sh      # 生产启动（APP_MODE=prod）
│  └─ requirements.txt
├─ frontend/           # Ant Design Vue 客户端
│  └─ src/
│     ├─ api/          # 接口封装（axios + token）
│     ├─ stores/       # pinia：model / parts / viewer / alarms / scenes / charts / faultParts
│     ├─ three/        # 纯 three.js 逻辑（Viewer.ts 等）
│     ├─ composables/  # useThreeViewer（Vue 与 three 的桥接）
│     ├─ components/   # TopBar / ViewerCanvas / 登录页 / 各卡片 / 弹窗
│     ├─ types/        # 类型定义
│     └─ styles/
├─ tools/              # CAD/GLB 处理脚本（split_glb / remove_nodes / scale_part）
├─ models/             # *.glb 模型
├─ data/               # scene_positions.csv、fault_part_map.csv
└─ 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
bash 3d/backend/run_prod.sh --host 0.0.0.0 --port 5182   # 以 APP_MODE=prod 启动
```

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

## 登录与运行模式

- **默认 `APP_MODE=test`（测试模式）**：登录页会**自动填入**账号密码（来自 `/api/auth-config`），仍需点“登录”。
- **生产**：用 `run_prod.sh`（等价于设置 `APP_MODE=prod`），`/api/auth-config` 不再返回账号密码。
- 数据接口需登录（`Authorization: Bearer <token>`）；`/models/*` 模型文件为静态资源，**不鉴权**。
- token 存于进程内存，服务重启后失效，需重新登录。

环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `APP_MODE` | `test` | `test` 测试模式；`prod` 生产模式 |
| `AUTH_USER` | `aaabbb` | 登录账号 |
| `AUTH_PASSWORD` | `Aa*147258&cd` | 登录密码 |
| `AUTH_TOKEN_TTL_SECONDS` | `43200` | token 有效期（秒） |
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | 读根目录 `数据库.md` | 数据库连接 |

示例：

```bash
APP_MODE=prod AUTH_USER=admin AUTH_PASSWORD='***' bash 3d/backend/run_prod.sh --port 5182
```

## 接口

| 方法 | 路径 | 鉴权 | 说明 |
| --- | --- | --- | --- |
| POST | `/api/login` | 否 | 登录，返回 token |
| POST | `/api/logout` | 否 | 退出 |
| GET | `/api/auth-config` | 否 | 运行模式（测试模式含默认账号密码） |
| GET | `/api/models` | 是 | 可用模型名列表 |
| GET | `/models/<file>` | 否 | GLB / glTF 模型文件 |
| GET | `/api/alarms` | 是 | 故障列表（筛选/分页，倒序） |
| GET | `/api/alarm-filters` | 是 | 故障列表筛选项 |
| GET | `/api/pks-series` | 是 | 故障曲线原始序列（YSJ_5/10/11） |
| GET | `/api/scene-positions` | 是 | 场景位置列表 |
| POST/PUT/DELETE | `/api/scene-positions[/id]` | 是 | 场景位置增/改/删 |
| GET | `/api/fault-part-map` | 是 | 故障↔3D 部件对照表 |
| POST | `/api/fault-part-map/scene` | 是 | 记录故障场景位置（贴合故障） |

## 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
```