# 环庭参数化源码维护说明

先读包根目录 `README.md`，其中包含网页部署、环境安装和最短重建命令。本文件记录修改时容易破坏的约束。

## 当前交付边界

- 正式打印件为 A1、B1、O1、D1、L1；另有维护托架和试件。外购件 STL 只是装配包络。
- 完整 3MF 共 9 盘，A1 与 O1 分盘独立打印。不要恢复 A1+O1 组合对象或旧组合下载链接。
- `3mf/Huanting-H2C.3mf` 未切片。除非用户另行要求，不生成 G-code 或 sliced 3MF。
- B1 已打印并冻结。A1 已删除内圈高出的墙底锁止结构，B1 从上方直接放置，由 D1 外缘承托，不旋转锁紧。
- A1 外圈顶面 Z34.6 mm；背面 +Y 电源口向下贯通底沿；BAT/PWM 三边导向框及连接杆已删除。
- O1 是开放双灯槽，无中央六柱，原内圈过线孔按外圈同形扩大，平台上后加的两个孔已填回。
- D1 中央透光区厚 1.4 mm，无独立 O2；L1 保留底盖卡口，并同步背面电源缺口。

## 修改入口

`params.py` 保存共享尺寸；`build.py` 保存具体实体、网格导出、装配和试件构造。修改后先运行 `build.py`，不要直接拿旧 GLB 或旧 3MF 冒充新模型。

`FROZEN_SHA256` 当前只保护 B1。包内的 `parts/B1.stl` 不是可省略缓存，而是冻结实物的源输入。默认重建会读取并验证它，其余 STL 重新生成。若用户批准修改 B1，需同时取消对应冻结保护、重建所有相关试件并复核装配；不要只删除哈希断言后不重算配合。

`build.py` 输出的 `parts/` 使用毫米制装配坐标。`prepare_slicing.py` 另行生成 `print_oriented/`，负责旋转、居中与底面落零；这两套 STL 不应混用。

## 3MF 与预设

`prepare_slicing.py` 从 Bambu Studio 官方配置解析：

- `0.16mm Standard @BBL H2C`，不覆盖速度和加速度。
- 主体使用模型料，只有支撑界面使用 Support for PLA。
- A1、O1 分盘；B1 使用明确的支撑区域和阻挡体；D1 及指定试件关闭支撑。
- 不生成 A1+O1 组合项目。

通过环境变量指定工具位置：

```bash
export BAMBU_STUDIO_ROOT=/path/to/squashfs-root
python source/prepare_slicing.py
bash source/presets/export.sh
```

`export.sh` 由脚本按当前机器的实际绝对路径重建，只执行 `--export-3mf`，没有 `--slice`。移动目录后应先重新运行 `prepare_slicing.py`，不要沿用写死旧路径的导出脚本。

## 3D 与静态图

`build.py` 生成装配和维护 GLB；`normalize_glb_normals.py` 通过 Blender 按 25° 硬边拆分重新导出显式法线，解决预览过度圆滑问题。

`render.py` 总是先按当前 STL 重建并保存 `huanting.blend`。传入未识别的视图名（例如 `-- --no-static-renders`）可只更新场景而不渲染。无参数运行会重新渲染静态 PNG；模型改动后不要把旧图片称为新模型效果图。

## 网页和批注

网页依赖均在包内。`preview_server.py` 同时提供静态文件、批注 API 和上传图片读取。部署包根目录的 `start.sh` 将数据放在包内 `review-data/`，不使用原工作区的评论数据库。

预览器支持整件和零件表面定位、局部隔离、XYZ 正反向剖切、当前视图截图、Ctrl+V 粘贴图片及评论视角恢复。细部选区只是定位，不会把一体件拆成新零件，也不会改变制造模型。

批量修改网页后可用 `verify_delivery.py` 检查相对链接和 manifest 中的 STL；批注接口可用 `test_review_server.py` 做独立临时目录测试。正式域名不要用于自动写入测试评论。

## 非几何边界

数字封闭性、干涉和路径检查不等于实物强度、支撑可拆、透光、温升、电气安全或电池兼容已获验证。报告和证据目录保留历史检查结果；修改模型后应重新生成受影响项，不要沿用旧结论。
