# PBR 渲染初学者互动教程 (pbr)

日期：2026-11-11
状态：**功能实现并完成有头 Chromium 采集与聚焦 E2E；整体产品验收仍由用户执行**

## 交付内容

- 新应用内课程 `pbr`：`/?ui=web&tutorial=pbr`（落地页）/ `?ui=web&tutorial=pbr&start=1`（编辑器中）。
- 13 步中文教程：
  `intro` → `workspace-shading` → `load-studio` → `add-suzanne` → `add-cube` → `add-torus` →
  `assign-metal` → `assign-glass` → `assign-wood` → `assign-emission` → `render-setup` → `download-save` → `summary`。
- 教程演示动作走真实产品入口：工作区切换、按名选择、PBR 资产库追加模型/分配材质、打开课程摄影棚、
  Web PBR 渲染、PNG 下载、工程保存。
- React 接线：`TutorialContext` 增加 workspace/资产库/渲染结果；`TutorialApi` 增加工作区、选择、
  资产追加、材质分配、打开场景、渲染、下载；`PbrRenderPanel` 支持外部请求与 `onRendered` 回传。

## 资产与截图

- 课程摄影棚：`web/app/public/tutorial/pbr/studio.blend`
  - 相机 `PBR Studio Camera`、三点灯光 + Sun、深灰世界、地面；生成报告
    `tests/golden/PBR_TUTORIAL-001/studio-build.json`。
- 教程步骤截图（有头 Chromium 实际操作）：
  `web/app/public/tutorial/pbr/landing.jpg`、`steps/<stepId>.jpg`、`steps/<stepId>-view.jpg`、
  `steps/00-assembly.jpg`（13 步 × 2 + 2）。
- 12 张材质对比成片：`web/app/public/tutorial/pbr/renders/<model>-<material>.{png,jpg}`
  - 模型：Suzanne、Cube、Torus；材质：Metal Brushed、Glass、Wood、Emission Cyan。
  - 这 12 张由桌面 Blender EEVEE 使用同一摄影棚/材质库渲染（`renderer: DESKTOP_BLENDER_EEVEE`），
    因浏览器 WebGL2 路径当前对部分材质仍偏暗；教程步骤截图与交互操作仍是真实有头 Chromium。
  - 生成脚本：`tools/web/generate-pbr-tutorial-renders.py`。
- 采集报告：`tests/golden/PBR_TUTORIAL-001/headed-screenshots-latest.json`
  （steps=13、renders=12、status=PASS）。

## 脚本

```bash
# 生成课程摄影棚
build_blender_native/bin/blender --background --factory-startup \
  --python tools/web/generate-pbr-tutorial-studio.py -- \
  web/app/public/tutorial/pbr/studio.blend \
  tests/golden/PBR_TUTORIAL-001/studio-build.json

# 生成 12 张材质对比参考图
build_blender_native/bin/blender --background --factory-startup \
  --python tools/web/generate-pbr-tutorial-renders.py -- \
  web/app/public/tutorial/pbr/studio.blend \
  web/app/public/assets/pbr-library/pbr-library.blend \
  web/app/public/tutorial/pbr/renders

# 有头 Chromium 采集教程步骤截图
DISPLAY=:1 CHROME_PATH=/usr/bin/google-chrome \
  node tools/web/capture-parts-tutorial-screenshots.mjs --course pbr --dev --port 5176

# 校验采集产物
node tools/web/check-pbr-tutorial-captures.mjs
```

## 验证结果

- `node tools/web/check-pbr-tutorial-captures.mjs`：PASS（13 步截图齐全、12 张 PNG 1024×1024、
  报告 status=PASS、studio SHA 一致）。
- `web/tests/e2e/pbr-tutorial-accessibility.spec.ts`：通过（axe 无 critical/serious）。
- `web/tests/e2e/wbv2-pbr-tutorial-production.spec.ts`：通过（13 步演示、资产库 20 卡片、
  渲染结果、PNG/.blend 下载）。
- `npm run typecheck`：通过。

## 已知限制

- 浏览器 WebGL2 PBR 渲染对部分材质（尤其金属/木色）偏暗；12 张教程成片改用桌面 Blender EEVEE
  生成，标注为 `DESKTOP_BLENDER_EEVEE`。交互教程与步骤截图仍为真实有头 Chromium。
- `PBR Wood` 当前为暖色哑光材质（无贴图节点），教程文案已同步为“暖色木质”，避免把未生效的
  纹理链当作已验证功能。
- 14 类节点之外的任意节点、动态纹理/对象信息、EEVEE/Cycles 像素级一致性不在本教程范围。