docs/diagrams/README.md

# 科研流程图与架构图（CS3319 推荐系统）

本目录存放本项目「方法 / 架构 / 依赖」的**可维护矢量图**。所有图都以源文件形式保存在
`src/`，由 `scripts/render_diagrams.sh` 一键渲染为 SVG / PDF 到 `svg/`、`pdf/`。
图只表达**关键模块**（不堆砌全部代码文件），可直接放入论文或课程报告。

> 设计原则：源文件即真相，SVG/PDF 是构建产物。改图就改 `src/` 里的源文件，再重渲染。
> 切勿手工编辑 `svg/`、`pdf/` 里的产物——下次渲染会被覆盖。

---

## 目录结构

```
docs/diagrams/
├── src/                         # 图的源文件（编辑这些）
│   ├── pipeline.mmd             # Mermaid：整体实验流程
│   ├── architecture.d2          # D2：系统分层架构
│   ├── dependencies.dot         # Graphviz：关键模块运行时依赖
│   ├── architecture_c4.puml     # C4-PlantUML：系统主架构图（论文主图）
│   └── architecture_c4_features.puml  # C4-PlantUML：259 维特征构成
├── svg/                         # 渲染产物（自动生成，勿手改）
├── pdf/                         # 渲染产物（自动生成，勿手改）
└── README.md                    # 本文件
scripts/render_diagrams.sh       # 一键渲染脚本
```

---

## 五张图分别表达什么

| 文件 | 工具 | 表达内容 | 论文用途 |
|---|---|---|---|
| `pipeline.mmd` | Mermaid | **端到端实验流程**：数据 → 确定性划分(seed=202) → 6 个 Stage-1 分数源 → 259 维特征 → LightGBM 二级堆叠 → rank-cutoff 决策 → 提交。用 `contrib` 类高亮高阶传播这一核心贡献。 | 方法流程图（Flow） |
| `architecture.d2` | D2 | **分层系统架构**：Data Layer / Deterministic Split / Stage-1 Suite / Stage-2 Meta-learner / Decision / Output 七层 + Shared Infrastructure（两个 `load_module` 共享库、特征缓存、无 utils 的代码复用约定）。 | 系统架构图 |
| `dependencies.dot` | Graphviz | **关键模块运行时依赖**：用 `importlib load_module()` 互相加载的真实关系。粗深色边 = 最终堆叠器加载各生产者；实线绿边 = 生产者间复用；点线灰边 = 扇入共享库。带图例。 | 工程/可复现性说明 |
| `architecture_c4.puml` | C4 Container | **系统主架构图（论文主图）**：外部（异构图 + 榜单）↔ 系统边界（Two-Stage Stacking Recommender）。Stage-1 用 Container_Boundary 收纳 6 个 Component（LightGCN / BPR-MF / Random Walk / Content / Explicit / **High-order（核心贡献）**），经 Feature Cache → Meta-Learner → Decision → 输出。标注公开 F1 = 0.96626、验证 F1 = 0.966874。 | 论文主图（Main Figure） |
| `architecture_c4_features.puml` | C4 Component | **259 维特征构成**：把主图里的「特征向量」放大，标注每组特征的维度（X_base 84-d = 4+18+8+3+43+4+4，再 +rich 18 +RW 77 +agg 11 +undir 24 +dir 45 = 259），汇入 LightGBM。 | 方法细节图 |

> **为什么用三种工具**：Mermaid 适合「方法流程」（GitHub/Typora 直接预览）；D2 适合「分层架构」；Graphviz 适合「依赖网络」；C4-PlantUML 适合「面向论文的专业架构主图」（有外系统边界、图例、规范的容器/组件抽象）。

---

## 如何重新渲染（一键）

```bash
# 渲染全部源文件 → SVG + PDF
bash scripts/render_diagrams.sh

# 只渲染 SVG（跳过 PDF，更快）
bash scripts/render_diagrams.sh --svg
```

脚本特性：
- **优雅降级**：某个工具没装，会被跳过并提示，不会中断整体运行；装好后重跑即可补齐。
- **自动取工具**：
  - `plantuml.jar` 缺失时自动从 GitHub 下载到 `scripts/.cache/plantuml.jar`。
  - `d2` 缺失时（Windows）尝试 `scoop install d2`。
  - `mmdc` 缺失时回退到 `npx --yes @mermaid-js/mermaid-cli`。
- **逐图打勾/叉**：末尾打印 `SVG: N  PDF: M  failed: K` 汇总。

渲染产物：`docs/diagrams/svg/*.svg` 与 `docs/diagrams/pdf/*.pdf`。

### 单独渲染某一类（手工命令）

```bash
# Mermaid
mmdc -i docs/diagrams/src/pipeline.mmd -o docs/diagrams/svg/pipeline.svg
# D2
d2 docs/diagrams/src/architecture.d2 docs/diagrams/svg/architecture.svg
# Graphviz
dot -Tsvg docs/diagrams/src/dependencies.dot -o docs/diagrams/svg/dependencies.svg
# PlantUML / C4（注意：它在源文件旁输出，需手动移动）
cd docs/diagrams/src && \
  java -jar ../../scripts/.cache/plantuml.jar -tsvg architecture_c4.puml && \
  mv architecture_c4.svg ../svg/
```

---

## 如何更新一张图

1. 编辑 `docs/diagrams/src/` 下对应的源文件。
2. **核对事实**：图里的数字（如 259 维构成、136,484 验证对、F1）必须与代码 / 报告一致。
   - 259 维构成见 `reports/final_report.md` 与 `code/high_order_graph_stack.py`。
   - 依赖关系改了，先在 `code/` 里 `grep -n "load_module"` 确认，再改 `dependencies.dot`。
3. `bash scripts/render_diagrams.sh` 重渲染。
4. 打开 `svg/*.svg` 目视检查布局/文字是否溢出；必要时调源文件里的 `skinparam`/`classes`/`rankdir`。

### 改图时的常见注意点（踩过的坑）

- **C4-PlantUML 的 include**：`!include <C4/C4_Container>` **不**定义 `Component` 宏；要用 `Component(...)` 必须用 `!include <C4/C4_Component>`（它向下包含 Container→Context，定义全部宏）。`System_Boundary` 是带下划线的（不是 `SystemBoundary`）。
- **D2**：`stroke-dash` 只接受单个 0–10 的数字（不是 CSS 的 `4 3`）；没有 `note` shape，注释用 `shape: text`。
- **Graphviz**：依赖图刻意用三种边样式 + `constraint=false` 控制层级，避免「毛线球」；加边前想清楚属于哪一类。

---

## 工具安装（一次性）

| 工具 | 安装 | 用途 |
|---|---|---|
| Mermaid CLI | `npm i -g @mermaid-js/mermaid-cli` | `.mmd` → SVG（首次会拉 puppeteer chromium） |
| D2 | Windows: `scoop install d2` · macOS: `brew install d2` | `.d2` → SVG |
| Graphviz | Windows: `scoop install graphviz` · macOS: `brew install graphviz` | `.dot` → SVG |
| PlantUML | `scoop install temurin21-jdk`（或任意 JDK）；jar 由脚本自动下载 | `.puml` → SVG（C4 stdlib 已内置于 jar） |

> 本目录的图已在 Windows + bash 环境下验证全部可渲染（Graphviz 14.1.1、mmdc 11.15.0、d2 0.7.1、PlantUML 1.2026.6）。

---

## 与其它文档的关系

- 图里的方法叙事与 `reports/final_report.md`、`docs_first_principles/` 一致。
- 259 维特征构成与 `docs_first_principles/_fact_sheet.md`（数值唯一真相源）对齐。
- 若数值有出入，以 `_fact_sheet.md` 和代码为准，并回头修正这里的图。