Compressor/build_model_detail_report.py

#!/usr/bin/env python3
"""Generate the detailed pressure/vibration model report from current artifacts."""
from __future__ import annotations

import csv
import json
from datetime import date
from pathlib import Path
from typing import Any

import numpy as np
import pandas as pd
from docx import Document
from docx.enum.section import WD_ORIENT
from docx.enum.table import WD_ALIGN_VERTICAL, WD_TABLE_ALIGNMENT
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.shared import Cm, Pt, RGBColor

from models.common import modeling, paths
from models.generalized import features_pressure
from models.vibration import features_vibration

OUT = paths.MODELS.parent / "总结文档" / "润滑油压力和振动模型详细报告.docx"
BODY_FONT = "宋体"
HEAD_FONT = "黑体"
BODY_SIZE = 12.0
TABLE_SIZE = 12.0
SMALL_SIZE = 9.0
BLACK = RGBColor(0, 0, 0)

KINDS = {
    "pressure": {
        "label": "润滑油压力",
        "stage_col": "压力阶段",
        "label_file": paths.REFERENCE / "润滑油压力小时阶段段.csv",
        "features": features_pressure,
        "feature_count": 22,
    },
    "vibration": {
        "label": "振动",
        "stage_col": "振动阶段",
        "label_file": paths.REFERENCE / "振动异常段.csv",
        "features": features_vibration,
        "feature_count": 25,
    },
}


def set_run_font(run, name=BODY_FONT, size=BODY_SIZE, bold=False) -> None:
    run.font.name = name
    run.font.size = Pt(size)
    run.font.bold = bold
    run.font.color.rgb = BLACK
    run._element.get_or_add_rPr().rFonts.set(qn("w:eastAsia"), name)


def set_style_font(style, name: str, size: float, bold: bool) -> None:
    style.font.name = name
    style.font.size = Pt(size)
    style.font.bold = bold
    style.font.color.rgb = BLACK
    style.element.get_or_add_rPr().rFonts.set(qn("w:eastAsia"), name)


def configure_document(doc: Document) -> None:
    section = doc.sections[0]
    section.orientation = WD_ORIENT.PORTRAIT
    section.page_width = Cm(21.0)
    section.page_height = Cm(29.7)
    section.top_margin = Cm(2.2)
    section.bottom_margin = Cm(2.2)
    section.left_margin = Cm(2.2)
    section.right_margin = Cm(2.2)

    normal = doc.styles["Normal"]
    set_style_font(normal, BODY_FONT, BODY_SIZE, False)
    normal.paragraph_format.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE
    normal.paragraph_format.space_before = Pt(0)
    normal.paragraph_format.space_after = Pt(0)

    for name, size in (("Heading 1", 16), ("Heading 2", 14), ("Heading 3", 12)):
        style = doc.styles[name]
        set_style_font(style, HEAD_FONT, size, True)
        style.paragraph_format.space_before = Pt(14 if name == "Heading 1" else 10)
        style.paragraph_format.space_after = Pt(8)
        style.paragraph_format.line_spacing_rule = WD_LINE_SPACING.SINGLE
        style.paragraph_format.keep_with_next = True

    header = section.header.paragraphs[0]
    header.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = header.add_run("润滑油压力和振动模型详细报告")
    set_run_font(run, BODY_FONT, 9)

    footer = section.footer.paragraphs[0]
    footer.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = footer.add_run("第 ")
    set_run_font(run, BODY_FONT, 9)
    field = OxmlElement("w:fldSimple")
    field.set(qn("w:instr"), "PAGE")
    footer._p.append(field)
    run = footer.add_run(" 页")
    set_run_font(run, BODY_FONT, 9)


def body(doc: Document, text: str, bold_prefix: str = "") -> None:
    paragraph = doc.add_paragraph()
    paragraph.paragraph_format.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE
    paragraph.paragraph_format.space_after = Pt(6)
    if bold_prefix and text.startswith(bold_prefix):
        run = paragraph.add_run(bold_prefix)
        set_run_font(run, BODY_FONT, BODY_SIZE, True)
        run = paragraph.add_run(text[len(bold_prefix):])
        set_run_font(run, BODY_FONT, BODY_SIZE)
    else:
        run = paragraph.add_run(text)
        set_run_font(run, BODY_FONT, BODY_SIZE)


def source(doc: Document, text: str) -> None:
    paragraph = doc.add_paragraph()
    paragraph.paragraph_format.space_after = Pt(8)
    run = paragraph.add_run("数据来源：" + text)
    set_run_font(run, BODY_FONT, SMALL_SIZE)


def fix_table(table, widths: list[float]) -> None:
    table.alignment = WD_TABLE_ALIGNMENT.CENTER
    table.autofit = False
    tbl_pr = table._tbl.tblPr
    layout = OxmlElement("w:tblLayout")
    layout.set(qn("w:type"), "fixed")
    tbl_pr.append(layout)
    tbl_w = tbl_pr.find(qn("w:tblW"))
    if tbl_w is None:
        tbl_w = OxmlElement("w:tblW")
        tbl_pr.append(tbl_w)
    tbl_w.set(qn("w:w"), str(int(sum(widths) * 567)))
    tbl_w.set(qn("w:type"), "dxa")
    for index, column in enumerate(table._tbl.tblGrid.gridCol_lst):
        column.set(qn("w:w"), str(int(widths[index] * 567)))


def cell_margins(cell) -> None:
    tc_pr = cell._tc.get_or_add_tcPr()
    mar = tc_pr.first_child_found_in("w:tcMar")
    if mar is None:
        mar = OxmlElement("w:tcMar")
        tc_pr.append(mar)
    for key, value in (("w:left", 60), ("w:right", 60), ("w:top", 30), ("w:bottom", 30)):
        node = mar.find(qn(key))
        if node is None:
            node = OxmlElement(key)
            mar.append(node)
        node.set(qn("w:w"), str(value))
        node.set(qn("w:type"), "dxa")


def add_table(doc: Document, headers: list[str], rows: list[list[Any]], widths: list[float], size=TABLE_SIZE, center=True) -> None:
    table = doc.add_table(rows=1, cols=len(headers))
    table.style = "Table Grid"
    fix_table(table, widths)
    header_row = table.rows[0]
    tr_pr = header_row._tr.get_or_add_trPr()
    tr_pr.append(OxmlElement("w:tblHeader"))
    for index, text in enumerate(headers):
        cell = header_row.cells[index]
        cell.width = Cm(widths[index])
        cell_margins(cell)
        cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER
        paragraph = cell.paragraphs[0]
        paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
        paragraph.paragraph_format.line_spacing_rule = WD_LINE_SPACING.SINGLE
        run = paragraph.add_run(str(text))
        set_run_font(run, BODY_FONT, size, True)
    for values in rows:
        row = table.add_row()
        row._tr.get_or_add_trPr().append(OxmlElement("w:cantSplit"))
        for index, text in enumerate(values):
            cell = row.cells[index]
            cell.width = Cm(widths[index])
            cell_margins(cell)
            cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER
            paragraph = cell.paragraphs[0]
            paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER if center else WD_ALIGN_PARAGRAPH.LEFT
            paragraph.paragraph_format.line_spacing_rule = WD_LINE_SPACING.SINGLE
            run = paragraph.add_run("" if text is None else str(text))
            set_run_font(run, BODY_FONT, size)
    doc.add_paragraph()


def pct(value: Any, digits: int = 2) -> str:
    if value is None:
        return "—"
    return f"{float(value) * 100:.{digits}f}%"


def num(value: Any, digits: int = 4) -> str:
    if value is None:
        return "—"
    return f"{float(value):.{digits}f}"


def load_json(path: Path) -> dict:
    return json.loads(Path(path).read_text(encoding="utf-8"))


def load_model(kind: str):
    bundle = __import__("joblib").load(paths.MODEL_ARTIFACTS / kind / f"{kind}_model.joblib")
    metadata = load_json(paths.MODEL_ARTIFACTS / kind / f"{kind}_metadata.json")
    return bundle, metadata


def predict(samples: list[dict], bundle: dict, kind: str) -> np.ndarray:
    feature_module = KINDS[kind]["features"]
    names = bundle["feature_names"]
    x = modeling.matrix(feature_module.feature_matrix(samples, bundle["unit_baselines"]), names)
    x = bundle["imputer"].transform(x)
    return bundle["model"].predict_proba(x)[:, 1]


def metrics_block(samples: list[dict], probabilities: np.ndarray, threshold: float) -> tuple[dict, dict]:
    labels = np.asarray([sample["label"] for sample in samples])
    predicted = (probabilities >= threshold).astype(int)
    return modeling.metrics(labels, predicted, probabilities), modeling.event_metrics(samples, predicted)


def class_rows(metrics: dict, threshold: float) -> list[list[str]]:
    normal = metrics["class_metrics"]["normal"]
    anomaly = metrics["class_metrics"]["anomaly"]
    return [
        ["正常", normal["support"], pct(normal["precision"]), pct(normal["recall"]), pct(normal["f1"]), pct(metrics["specificity"]), "—"],
        ["异常", anomaly["support"], pct(anomaly["precision"]), pct(anomaly["recall"]), pct(anomaly["f1"]), "—", pct(metrics["pr_auc"])],
    ]


def overall_rows(metrics: dict) -> list[list[str]]:
    c = metrics["confusion_matrix_counts"]
    return [[
        metrics["samples"], metrics["normal_samples"], metrics["anomaly_samples"],
        c["tp"], c["fp"], c["fn"], c["tn"], pct(metrics["accuracy"]), pct(metrics["balanced_accuracy"]),
        pct(metrics["macro_f1"]), pct(metrics["pr_auc"]),
    ]]


def event_rows(events: dict) -> list[list[str]]:
    return [[
        events["anomaly_events"], events["detected_anomaly_events"], events["missed_anomaly_events"],
        events["normal_events"], events["false_positive_normal_events"], pct(events["event_recall"]),
    ]]


def add_class_tables(doc: Document, metrics: dict, threshold: float, title: str, source_text: str) -> None:
    doc.add_heading(title, level=3)
    add_table(
        doc, ["类别", "样本数", "查准率", "召回率", "F1", "特异度", "PR-AUC"],
        class_rows(metrics, threshold), [2.2, 2.2, 2.4, 2.4, 2.2, 2.2, 2.4], size=12.0,
    )
    add_table(
        doc, ["样本数", "正常", "异常", "TP", "FP", "FN", "TN"],
        [overall_rows(metrics)[0][:7]], [2.4, 2.2, 2.2, 2.2, 2.2, 2.2, 2.2], size=12.0,
    )
    add_table(
        doc, ["准确率", "平衡准确率", "macro-F1", "PR-AUC"],
        [overall_rows(metrics)[0][7:]], [4.0, 4.0, 4.0, 4.0], size=12.0,
    )
    source(doc, source_text)


def add_event_table(doc: Document, events: dict, title: str, source_text: str) -> None:
    doc.add_heading(title, level=3)
    add_table(
        doc, ["异常事件", "检出", "漏报", "正常事件", "正常事件误报", "事件召回"],
        event_rows(events), [2.6, 2.2, 2.2, 2.6, 3.2, 2.6], size=12.0,
    )
    source(doc, source_text)


def add_unit_table(doc: Document, evaluation: dict, title: str, source_text: str) -> None:
    doc.add_heading(title, level=3)
    rows = []
    for unit, data in evaluation["by_unit"].items():
        normal = data["class_metrics"]["normal"]
        anomaly = data["class_metrics"]["anomaly"]
        rows.append([
            unit, data["normal_samples"], data["anomaly_samples"],
            pct(normal["precision"]), pct(normal["recall"]), pct(normal["f1"]),
            pct(anomaly["precision"]), pct(anomaly["recall"]), pct(anomaly["f1"]),
            pct(data["specificity"]), pct(data["pr_auc"]),
        ])
    add_table(
        doc, ["机组", "正常窗口", "正常查准", "正常召回", "正常F1", "特异度"],
        [[row[0], row[1], row[3], row[4], row[5], row[9]] for row in rows],
        [2.6, 2.6, 2.6, 2.6, 2.6, 2.6], size=12.0,
    )
    add_table(
        doc, ["机组", "异常窗口", "异常查准", "异常召回", "异常F1", "PR-AUC"],
        [[row[0], row[2], row[6], row[7], row[8], row[10]] for row in rows],
        [2.6, 2.6, 2.6, 2.6, 2.6, 2.6], size=12.0,
    )
    source(doc, source_text)


def add_stage_table(doc: Document, labels: pd.DataFrame, stage_col: str, title: str, source_text: str) -> None:
    doc.add_heading(title, level=3)
    rows = []
    for unit in ("7号机", "8号机", "9号机"):
        subset = labels[labels["机组"] == unit]
        counts = subset[stage_col].value_counts().to_dict()
        rows.append([
            unit, counts.get("轻微", 0), counts.get("异常", 0), counts.get("严重异常", 0), len(subset),
        ])
    counts = labels[stage_col].value_counts().to_dict()
    rows.append(["合计", counts.get("轻微", 0), counts.get("异常", 0), counts.get("严重异常", 0), len(labels)])
    add_table(doc, ["机组", "轻微", "异常", "严重异常", "合计"], rows, [4.0, 3.0, 3.0, 3.2, 3.0], size=12.0)
    source(doc, source_text)


def error_tables(doc: Document, kind: str, threshold: float, evaluation: dict) -> None:
    frame = pd.read_csv(paths.RESULTS / kind / f"{kind}_test_predictions.csv")
    frame = frame.rename(columns={"anomaly_probability": "probability", "true_label": "label", "predicted_label": "predicted"})
    fp = frame[(frame["label"] == 0) & (frame["predicted"] == 1)].sort_values("probability", ascending=False).head(5)
    fn = frame[(frame["label"] == 1) & (frame["predicted"] == 0)].sort_values("probability").head(5)
    c = evaluation["window_metrics"]["confusion_matrix_counts"]

    body(
        doc,
        f"测试集错判 {c['fp']} 个、漏判 {c['fn']} 个，真正例 {c['tp']} 个、真负例 {c['tn']} 个。"
        f"错判是正常窗口被判为异常，漏判是异常窗口被判为正常；同时给出事件级结果，避免只看窗口。",
    )
    add_table(
        doc, ["类型", "机组", "窗口开始", "窗口结束", "概率", "事件编号"],
        [["错判", r["unit"], r["start_hour"][:16], r["end_hour"][:16], num(r["probability"], 4), r["event_group_id"]]
         for _, r in fp.iterrows()] or [["错判", "无", "—", "—", "—", "—"]],
        [1.4, 1.6, 3.2, 3.2, 1.8, 4.8], size=12.0,
    )
    add_table(
        doc, ["类型", "机组", "窗口开始", "窗口结束", "概率", "事件编号"],
        [["漏判", r["unit"], r["start_hour"][:16], r["end_hour"][:16], num(r["probability"], 4), r["event_group_id"]]
         for _, r in fn.iterrows()] or [["漏判", "无", "—", "—", "—", "—"]],
        [1.4, 1.6, 3.2, 3.2, 1.8, 4.8], size=12.0,
    )
    source(doc, f"models/results/{kind}/{kind}_test_predictions.csv；按阈值 {threshold:.6f} 判定")


def feature_table(doc: Document, bundle: dict, metadata: dict, title: str, source_text: str) -> None:
    doc.add_heading(title, level=3)
    names = bundle["feature_names"]
    values = bundle["model"].feature_importances_
    items = sorted(zip(names, values), key=lambda item: item[1], reverse=True)
    top = items[:10]
    rest = sum(value for _, value in items[10:])
    rows = [[name, pct(value)] for name, value in top]
    rows.append(["其余特征合计", pct(rest)])
    add_table(doc, ["特征", "重要度"], rows, [12.5, 4.0], size=12.0, center=False)
    source(doc, source_text)


def add_model_section(doc: Document, kind: str, labels: pd.DataFrame, evaluation: dict, bundle: dict, metadata: dict, train: list[dict], validation: list[dict], test: list[dict]) -> None:
    info = KINDS[kind]
    title = info["label"]
    doc.add_heading(f"{'五' if kind == 'pressure' else '六'}、{title}模型详细", level=1)

    doc.add_heading("模型与训练", level=2)
    body(
        doc,
        f"模型为 XGBoost 二分类，输出窗口异常概率；特征版本为 {metadata.get('feature_version', '')}，"
        f"特征数 {info['feature_count']}。训练使用全部正常样本和异常样本，按验证集选择阈值。"
    )
    rows = [
        ["窗口长度", "3 小时"],
        ["训练轮数（请求/实际）", f"800 / {metadata.get('rounds_run', '—')}"],
        ["早停轮数", "50"],
        ["最佳轮次", str(metadata.get("best_iteration", "—"))],
        ["最佳验证 logloss", num(metadata.get("best_score"), 5)],
        ["正常/异常训练样本", f"{metadata.get('training_normal', '—')} / {metadata.get('training_anomaly', '—')}"],
        ["scale_pos_weight", num(metadata.get("scale_pos_weight"), 3)],
        ["分类阈值", num(metadata.get("threshold"), 6)],
        ["阈值选择", "验证集最大 F1"],
    ]
    add_table(doc, ["项目", "值"], rows, [6.0, 9.5], size=12.0, center=False)
    source(doc, f"models/datas/artifacts/{kind}/{kind}_metadata.json；models/common/modeling.py")

    # Training set (reference only)
    threshold = float(metadata["threshold"])
    train_p = predict(train, bundle, kind)
    train_metrics, train_events = metrics_block(train, train_p, threshold)
    add_class_tables(
        doc, train_metrics, threshold, "训练集（仅参考）",
        f"models/datas/{kind}/train；使用保存模型重新打分，训练集指标偏乐观，不作为泛化结论",
    )
    add_event_table(doc, train_events, "训练集事件级", f"models/datas/{kind}/train；保存模型重新打分")

    val_p = predict(validation, bundle, kind)
    val_metrics, val_events = metrics_block(validation, val_p, threshold)
    add_class_tables(
        doc, val_metrics, threshold, "验证集",
        f"models/datas/{kind}/validation；使用保存模型重新打分，阈值来自 metadata",
    )
    add_event_table(doc, val_events, "验证集事件级", f"models/datas/{kind}/validation；保存模型重新打分")

    add_class_tables(
        doc, evaluation["window_metrics"], threshold, "封存测试集",
        f"models/results/{kind}/{kind}_test_evaluation.json 的 window_metrics",
    )
    add_event_table(doc, evaluation["event_metrics"], "测试集事件级", f"models/results/{kind}/{kind}_test_evaluation.json 的 event_metrics")
    add_unit_table(doc, evaluation, "测试集分机组", f"models/results/{kind}/{kind}_test_evaluation.json 的 by_unit")
    add_stage_table(doc, labels, info["stage_col"], "标签阶段分布", f"models/datas/reference/{info['label_file'].name}")

    doc.add_heading("错判与漏判", level=2)
    error_tables(doc, kind, threshold, evaluation)
    if kind == "pressure":
        body(
            doc,
            "从测试结果看，错判主要是正常窗口概率接近阈值，漏判主要是轻微、单小时或边界窗口；"
            "7 号机测试异常窗口 10 个、9 号机没有异常窗口，因此分机组指标只能作为参考。事件级 10/10 检出。",
        )
    else:
        body(
            doc,
            "从测试结果看，错判和漏判都集中在短阶段和峰值型阶段附近，概率接近阈值；"
            "9 号机没有测试异常事件，7/8 号事件级 4/4 检出，但窗口级召回有限，需结合事件级结果看。",
        )

    feature_table(doc, bundle, metadata, "特征重要度（前 10）", f"{kind}_model.joblib 的 feature_importances_；特征名来自 metadata")


def add_summary_section(doc: Document, data: dict[str, dict]) -> None:
    doc.add_heading("七、两模型汇总", level=1)
    rows = []
    for kind, item in data.items():
        for split_name, metrics in (("验证集", item["validation"]), ("测试集", item["test"])):
            normal = metrics["class_metrics"]["normal"]
            anomaly = metrics["class_metrics"]["anomaly"]
            rows.append([
                KINDS[kind]["label"], split_name, metrics["samples"],
                pct(normal["precision"]), pct(normal["recall"]), pct(normal["f1"]),
                pct(anomaly["precision"]), pct(anomaly["recall"]), pct(anomaly["f1"]),
                pct(metrics["pr_auc"]),
            ])
    add_table(
        doc, ["模型", "集合", "样本数", "正常查准", "正常召回", "正常F1"],
        [row[:6] for row in rows], [3.2, 2.8, 2.6, 2.6, 2.6, 2.6], size=12.0,
    )
    add_table(
        doc, ["模型", "集合", "样本数", "异常查准", "异常召回", "异常F1", "PR-AUC"],
        [[row[0], row[1], row[2], *row[6:]] for row in rows],
        [2.6, 2.4, 2.2, 2.4, 2.4, 2.4, 2.2], size=12.0,
    )
    source(doc, "压力/振动 validation 重新打分；test 来自各自 *_test_evaluation.json")
    rows = []
    for kind, item in data.items():
        for split_name, events in (("验证集", item["validation_events"]), ("测试集", item["test_events"])):
            rows.append([
                KINDS[kind]["label"], split_name, events["anomaly_events"], events["detected_anomaly_events"],
                events["missed_anomaly_events"], events["false_positive_normal_events"], pct(events["event_recall"]),
            ])
    add_table(doc, ["模型", "集合", "异常事件", "检出", "漏报", "正常事件误报", "事件召回"], rows, [2.2, 1.6, 2.0, 1.6, 1.6, 2.6, 2.2], size=12.0)
    source(doc, "validation 事件级重新打分；test 事件级来自 evaluation event_metrics")


def main() -> None:
    doc = Document()
    configure_document(doc)

    # Cover
    for _ in range(5):
        doc.add_paragraph()
    paragraph = doc.add_paragraph()
    paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = paragraph.add_run("润滑油压力和振动模型详细报告")
    set_run_font(run, HEAD_FONT, 26, True)
    paragraph = doc.add_paragraph()
    paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = paragraph.add_run("备份版本：压力 72 条 / 振动 25 条")
    set_run_font(run, BODY_FONT, 14)
    for _ in range(6):
        doc.add_paragraph()
    paragraph = doc.add_paragraph()
    paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = paragraph.add_run(f"{date.today().year} 年 {date.today().month} 月")
    set_run_font(run, BODY_FONT, 12)
    doc.add_page_break()

    doc.add_heading("一、文档说明", level=1)
    body(doc, "本报告对应当前已恢复的备份版本：润滑油压力 72 条标签、振动 25 条标签。报告不包含后续 64 条压力标签或振动调参实验。")
    body(doc, "模型均为二分类“正常/异常”窗口模型，输出异常概率；标签中的轻微/异常/严重异常是样本来源阶段，不是模型的三分类输出。")
    body(doc, "所有指标均由当前模型文件、验证样本和封存测试结果重新计算或读取；每张表下方标注数据来源。")

    doc.add_heading("二、数据与标签来源", level=1)
    rows = [
        ["小时运行数据", "models/datas/hourly/pks_hourly_full.csv", "7/8/9 号机 5 秒数据按小时聚合"],
        ["压力标签", "models/datas/reference/润滑油压力小时阶段段.csv", "72 条"],
        ["振动标签", "models/datas/reference/振动异常段.csv", "25 条"],
        ["压力训练样本", "models/datas/pressure/", "manifest、train、validation、test"],
        ["振动训练样本", "models/datas/vibration/", "manifest、train、validation、test"],
        ["压力模型", "models/datas/artifacts/pressure/", "XGBoost + 相似度索引"],
        ["振动模型", "models/datas/artifacts/vibration/", "XGBoost + 相似度索引"],
    ]
    add_table(doc, ["类型", "路径", "说明"], rows, [3.2, 8.0, 5.0], size=12.0, center=False)
    source(doc, "项目内实际文件；标签时间范围和数量由 reference CSV 统计")

    pressure_labels = pd.read_csv(KINDS["pressure"]["label_file"])
    vibration_labels = pd.read_csv(KINDS["vibration"]["label_file"])
    rows = [
        ["润滑油压力", len(pressure_labels), pressure_labels["开始小时"].min()[:10], pressure_labels["结束小时"].max()[:10]],
        ["振动", len(vibration_labels), vibration_labels["开始小时"].min()[:10], vibration_labels["结束小时"].max()[:10]],
    ]
    add_table(doc, ["类型", "标签数", "最早开始", "最晚结束"], rows, [4.0, 3.0, 4.0, 4.0], size=12.0)
    source(doc, "models/datas/reference/润滑油压力小时阶段段.csv、振动异常段.csv")

    doc.add_heading("三、样本构建与划分", level=1)
    body(doc, "压力与振动均使用 3 小时滑动窗口。窗口与任一异常阶段重叠即标为异常；训练样本使用全部正常窗口。")
    body(doc, "切分比例为 6.5 / 2 / 1.5，随机种子 20260921，事件组不跨 train/validation/test。压力异常按样本分配，振动按事件组分配。")
    rows = []
    for kind in ("pressure", "vibration"):
        report = load_json(paths.DATAS / kind / "split_report.json")[kind]
        counts = report["sample_counts"]
        for split_name in ("train", "validation", "test"):
            item = counts[split_name]
            rows.append([KINDS[kind]["label"], split_name, item["samples_normal"], item["samples_anomaly"]])
    add_table(doc, ["模型", "划分", "正常", "异常"], rows, [4.0, 3.0, 4.0, 4.0], size=12.0)
    body(doc, "排除样本：压力 750、振动 519；不计入正常/异常训练或测试指标。")
    source(doc, "models/datas/pressure/split_report.json、models/datas/vibration/split_report.json")

    rows = []
    for kind in ("pressure", "vibration"):
        manifest = pd.read_csv(paths.DATAS / kind / "manifest.csv")
        for unit in ("7号机", "8号机", "9号机"):
            for split_name in ("train", "validation", "test"):
                subset = manifest[(manifest["unit"] == unit) & (manifest["split"] == split_name)]
                if subset.empty:
                    continue
                rows.append([
                    KINDS[kind]["label"], unit, split_name,
                    int((subset["label_name"] == "normal").sum()),
                    int((subset["label_name"] == "anomaly").sum()),
                ])
    add_table(doc, ["模型", "机组", "split", "正常", "异常"], rows, [3.0, 2.4, 2.6, 2.2, 2.2], size=12.0)
    source(doc, "models/datas/pressure/manifest.csv、models/datas/vibration/manifest.csv")

    doc.add_heading("四、指标定义与来源", level=1)
    body(doc, "TP：异常检出；FP：正常误报；FN：异常漏报；TN：正常正确排除。")
    body(doc, "查准率 = TP/(TP+FP)；异常召回 = TP/(TP+FN)；正常特异度 = TN/(TN+FP)；正常召回等于特异度。")
    body(doc, "F1 为查准率与召回率的调和平均；平衡准确率 =（正常召回 + 异常召回）/2；macro-F1 为两类 F1 的算术平均；PR-AUC 基于异常概率计算。")
    body(doc, "事件级指标按事件组聚合：事件内任一窗口检出，该事件算检出；正常事件内任一窗口报警，算正常事件误报。")
    rows = [
        ["验证集/训练集分类指标", "保存模型对对应样本重新打分", "models/datas/{kind}/train、validation；models/datas/artifacts/{kind}"],
        ["测试集分类指标", "封存测试评估 JSON", "models/results/{kind}/{kind}_test_evaluation.json"],
        ["分机组指标", "by_unit", "同上"],
        ["事件级指标", "event_metrics", "验证集重新计算；测试集读取 JSON"],
        ["错判/漏判明细", "测试预测 CSV", "models/results/{kind}/{kind}_test_predictions.csv"],
    ]
    add_table(doc, ["指标", "计算方式", "来源"], rows, [4.6, 5.8, 6.0], size=12.0, center=False)
    source(doc, "models/common/modeling.py 的 metrics / event_metrics / choose_threshold")

    data: dict[str, dict] = {}
    for kind in ("pressure", "vibration"):
        bundle, metadata = load_model(kind)
        train = modeling.load_samples(paths.DATAS / kind / "train")
        validation = modeling.load_samples(paths.DATAS / kind / "validation")
        test = modeling.load_samples(paths.DATAS / kind / "test")
        evaluation = load_json(paths.RESULTS / kind / f"{kind}_test_evaluation.json")
        labels = pd.read_csv(KINDS[kind]["label_file"])
        add_model_section(doc, kind, labels, evaluation, bundle, metadata, train, validation, test)
        threshold = float(metadata["threshold"])
        val_p = predict(validation, bundle, kind)
        val_metrics, val_events = metrics_block(validation, val_p, threshold)
        data[kind] = {
            "validation": val_metrics,
            "validation_events": val_events,
            "test": evaluation["window_metrics"],
            "test_events": evaluation["event_metrics"],
        }

    add_summary_section(doc, data)

    doc.add_heading("八、结论与限制", level=1)
    body(doc, "压力模型在测试集上正常类 F1 99.74%、异常类 F1 96.59%，事件级 10/10；但 7 号机只有 10 个测试异常窗口、9 号机没有测试异常窗口，分机组指标只能作参考。")
    body(doc, "振动模型在测试集上正常类 F1 99.72%、异常类 F1 71.43%，事件级 4/4；异常阶段短、测试事件少，窗口级指标波动较大。")
    body(doc, "两个模型的测试集均为封存集，没有参与训练或阈值选择；验证集用于阈值选择。标签来自规则扫描阶段，未经人工确认，指标代表对规则标签的泛化一致性，不等同于物理故障诊断。")
    body(doc, "错判和漏判主要出现在轻微、短阶段或边界窗口；实际使用时应结合事件级结果、连续窗口和现场维修记录复核。")

    doc.add_heading("附录：文件路径", level=1)
    rows = [
        ["压力标签", "models/datas/reference/润滑油压力小时阶段段.csv"],
        ["振动标签", "models/datas/reference/振动异常段.csv"],
        ["压力样本", "models/datas/pressure/"],
        ["振动样本", "models/datas/vibration/"],
        ["压力模型", "models/datas/artifacts/pressure/pressure_model.joblib"],
        ["振动模型", "models/datas/artifacts/vibration/vibration_model.joblib"],
        ["压力评估", "models/results/pressure/pressure_test_evaluation.json"],
        ["振动评估", "models/results/vibration/vibration_test_evaluation.json"],
        ["压力预测明细", "models/results/pressure/pressure_test_predictions.csv"],
        ["振动预测明细", "models/results/vibration/vibration_test_predictions.csv"],
    ]
    add_table(doc, ["对象", "路径"], rows, [4.0, 12.0], size=12.0, center=False)

    OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(OUT)
    print(f"已生成：{OUT}")


if __name__ == "__main__":
    main()