AgentLab/backend/app/data/recipe_notes.py

"""按核对结果生成表说明和列说明（P2-SPEC 5.4），再写进要冻结的表结构（schema_cache）。

说明进模型可见文本：introspect.describe_table 把表和列的 comment 拼进 db_schema 的输出，摘要里也有。
所以这里守三条规矩：
- **说明跟着核对结果走，规则写死**：K / T 没通过，这张表的说明里不出现「一致」；一条核对有几种无法核对的
  原因，用最弱的「原因混合」说法；找不到对应模板就记 problems（不能保存），绝不退回到别的模板——
  宁可导不进去，也不让模型读到「已核对一致」而事实上没核对。核对本身是不可接受的结构类失败（试运行已经
  拒收）时，那一段不写、也不记 problems，免得用户被引去改配方（见 _blocking）。
- **不带数字和坐标**：模板里的列名、表名、单位一律写成 {列:名} {表:名} {单位:名} 引用，每张表、每列的模板都过
  契约的 prose_problems(known=…)（遮盖引用后不许抽出数字、不许有坐标，引用必须指向真实的名字）。
  原表头、坐标、区域外文字全文只进清单和界面，不进说明。
- **模板是常量，拼接只用 .format()**：模板放在 NOTE_TEXT / COLUMN_TEXT 里，{a} {b} 这类槽位由 _tok 填入引用；
  这样模板本身经得起文案检查，填进去的名字也不会被当成格式串再解析一次。
"""
from __future__ import annotations

import copy
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Any

from app.data.names import canon
from app.data.recipe_checks import date_columns, plan_checks, split_coord
from app.data.recipe_parsers import UNITS
from app.data.recipe_types import (
    Acceptance,
    CheckResult,
    ColumnOut,
    CrosstabBlock,
    DerivedSegment,
    DimensionSegment,
    Extraction,
    ListBlock,
    MeasuresSegment,
    NotComparable,
    Placeholder,
    Recipe,
    SchemaNotes,
    SheetRecipe,
    SumEq,
    TableNote,
    derive_tables,
    prose_problems,
    render_prose,
)

#: 表说明的片段模板。槽位里填的是 {列:名} {表:名} 引用（_tok 生成），片段之间用「。」拼接
NOTE_TEXT = {
    "grain_1": "粒度：每个{a}",
    "grain_2": "粒度：每个{a}的每个{b}",
    "grain_n": "粒度：{a} 与 {b} 的每个组合",
    "sum_eq_passed": "{total} 等于 {parts} 之和（导入时已{per}核对）：求合计只用 {total}，不要把这几列相加",
    "sum_eq_mismatch_accepted": "{total} 与 {parts} 之和的关系在本期个别{unit}不成立，已由用户确认接受，详见导入清单："
                                "不要据此推算，也不要把这几列相加",
    # 试运行回执的预览按「全部未接受」生成（P2-SPEC 7.4），这时还不能写「已由用户确认接受」
    "sum_eq_mismatch_pending": "{total} 与 {parts} 之和的关系在本期个别{unit}不成立，尚未确认接受："
                               "不要据此推算，也不要把这几列相加",
    "sum_eq_nulls": "{total} 与 {parts} 之和的关系在本期部分{unit}因空值未能核对：不要据此推算，也不要把这几列相加",
    # 本期一行数据都没有（AU-1）：不能写「已核对」，也不是「因空值」
    "sum_eq_no_rows": "{total} 与 {parts} 之和的关系在本期没有数据行，未能核对：不要据此推算，也不要把这几列相加",
    "not_comparable_unequal": "与 {other} 口径不同：各{dims}之和不等于 {value}，不能互相推算或相加",
    # 基表除了分组列没有别的粒度列时，「各……之和」无从说起，改说按分组列汇总
    "not_comparable_unequal_flat": "与 {other} 口径不同：{a_value} 按 {by} 汇总不等于 {value}，不能互相推算或相加",
    "not_comparable_equal": "与 {other} 口径不同，不能互相推算或相加",
    "hour_range": "{dim} 按规范写法存储：{start}-{end}，不带单位",
    # 配方没派生起止小时列时，没有列可以引用
    "hour_range_plain": "{dim} 按规范写法存储：起始小时与结束小时用连字符相连，不带单位",
    "const": "{col} 取自原表的分段标题",
    "total_kept": "原表的合计在 {table}，不要与本表相加",
    "total_not_kept": "原表的合计行未导入本表",
    "total_k_passed": "原表写明的合计，已按明细重算核对一致",
    "total_k_passed_g_unverifiable": "原表写明的合计，合计值已按明细核对一致，公式引用的格子未能核对",
    "total_k_uncached": "原表写明的合计。本期原表未保存计算结果，合计值为空，未能核对",
    "total_k_blank": "原表写明的合计。本期原表合计格为空，未能核对",
    "total_k_null_detail": "原表写明的合计，按原表保存的值存储。本期明细含无数据占位符，未能核对",
    "total_k_tiling": "原表写明的合计，按原表保存的值存储。本期明细未能覆盖合计的全部范围，未能核对",
    "total_k_hidden": "原表写明的合计，按原表保存的值存储。本期存在隐藏行或使用了分类汇总函数，合计口径无法确定，未能核对",
    "total_k_mixed": "原表写明的合计，按原表保存的值存储。本期合计值未能核对",
    "total_overlap": "各{dim}覆盖的时段可能互相重叠：不要彼此相加，也不要与 {base} 相加",
    "list_total_passed": "原表合计行的值，已按各列明细求和核对一致：不要与 {base} 相加",
    # 合计行里空着的数字格不生成合计格（P2-SPEC 4.4），T 只核对了其余的列：不能说「各列」都一致
    "list_total_passed_partial": "原表合计行的值。本期原表 {cols} 的合计格为空，其余各列已按明细求和核对一致："
                                 "不要与 {base} 相加",
    "list_total_uncached": "原表合计行的值。本期原表未保存计算结果，合计值为空，未能核对：不要与 {base} 相加",
    # 合计格写的是占位符（转成空值）时走到这里，与交叉表的 total_k_blank 对应
    "list_total_blank": "原表合计行的值。本期原表合计格为空，未能核对：不要与 {base} 相加",
    "list_total_tiling": "原表合计行的值，按原表保存的值存储。本期合计行之上没有明细，未能核对：不要与 {base} 相加",
    "list_total_null_detail": "原表合计行的值，按原表保存的值存储。本期明细含空值，未能核对：不要与 {base} 相加",
    "list_total_hidden": "原表合计行的值，按原表保存的值存储。本期存在隐藏行或使用了分类汇总函数，合计口径无法确定，"
                         "未能核对：不要与 {base} 相加",
    "list_total_mixed": "原表合计行的值，按原表保存的值存储。本期未能核对：不要与 {base} 相加",
    "hidden_excluded": "本表不含原表中被隐藏的行",
    "hidden_included": "本表包含原表中被隐藏的行",
    "ignored_columns": "原表另有未导入的列",
    "rows_after_stop": "原表在空行之后另有未导入的文字行，内容见证据面板",
    # 不写「不一致」：K / T 没通过的表不许出现「一致」二字，按子串判断时「不一致」也会撞上
    "period_conflict_accepted": "本期统计期的写法在原表或文件名中有冲突，已由用户确认接受，详见导入清单",
    "period_conflict_pending": "本期统计期的写法在原表或文件名中有冲突，尚未确认接受",
    "period_human": "本期统计期为人工录入",
    "outside_digits": "本期原表附有说明文字（可能涉及口径），内容见证据面板",
}

#: 列说明的片段模板
COLUMN_TEXT = {
    "unit": "单位：{unit}",
    "null_placeholder": "空值表示原表为{meaning}占位符，不代表零；求和时请同时统计非空个数",
    "null_blank": "空值表示原表为空格，不代表零；求和时请同时统计非空个数",
    "null_both": "空值表示原表为{meaning}占位符或空格，不代表零；求和时请同时统计非空个数",
    "date": "格式 YYYY-MM-DD",
    "date_year_from_period": "格式 YYYY-MM-DD，年份按统计期补全",
}

#: 「逐日 / 逐行」「个别日期 / 个别行」：粒度只有一列日期时按日说，否则按行说
_PER = {True: ("逐日", "日期"), False: ("逐行", "行")}
_AND = " 与 "
_LIST = "、"
_MEANING_BOTH = "无数据或不适用"
#: 交叉表合计的单一原因 → 模板键；列表合计同理。列表的 blank：合计格写了占位符（非空格，转成空值，照样生成
#: 合计格）；tiling：合计行之上没有明细行。unrecognized 只出现在公式引用（G）上
_K_REASON = {r: f"total_k_{r}" for r in ("uncached", "blank", "null_detail", "tiling", "hidden")}
_T_REASON = {r: f"list_total_{r}" for r in ("uncached", "blank", "null_detail", "tiling", "hidden")}
#: 允许出现「一致」的模板：只在对应的 K / T 通过时才会选用
CONSISTENT_KEYS = frozenset({"total_k_passed", "total_k_passed_g_unverifiable", "list_total_passed",
                             "list_total_passed_partial"})


def _tok(kind: str, name: str) -> str:
    """结构化引用 {列:名} / {表:名} / {单位:名}。渲染时换成名字，检查时遮盖。"""
    return "{" + kind + ":" + name + "}"


def _col(name: str) -> str:
    return _tok("列", name)


def _tab(name: str) -> str:
    return _tok("表", name)


def _join_and(names: list[str]) -> str:
    """a、b 与 c。"""
    if len(names) <= 1:
        return "".join(names)
    return _LIST.join(names[:-1]) + _AND + names[-1]


# ---------------------------------------------------------------- 配方结构：每张表从哪来


@dataclass
class _Writers:
    """一张表在配方里的来历（哪些工作表、分段、块写进它、它是谁的合计另存表）。"""

    sheets: list[SheetRecipe] = field(default_factory=list)
    crosstabs: list[CrosstabBlock] = field(default_factory=list)
    dims: list[DimensionSegment] = field(default_factory=list)
    measures: list[MeasuresSegment] = field(default_factory=list)
    #: 以本表为基表核对的 derived 段（本表是明细表）
    verified_by: list[DerivedSegment] = field(default_factory=list)
    #: 把合计另存进本表的 derived 段（本表是交叉表的表内合计表）
    kept_from: list[DerivedSegment] = field(default_factory=list)
    lists: list[ListBlock] = field(default_factory=list)
    #: 把合计行另存进本表的列表块
    list_totals: list[ListBlock] = field(default_factory=list)

    def add_sheet(self, sheet: SheetRecipe) -> None:
        if all(s is not sheet for s in self.sheets):
            self.sheets.append(sheet)


def _writers(recipe: Recipe) -> dict[str, _Writers]:
    out: dict[str, _Writers] = {}

    def w(table: str, sheet: SheetRecipe) -> _Writers:
        entry = out.setdefault(table, _Writers())
        entry.add_sheet(sheet)
        return entry

    for sheet in recipe.sheets:
        for block in sheet.blocks:
            if isinstance(block, CrosstabBlock):
                for seg in block.segments:
                    if isinstance(seg, MeasuresSegment):
                        e = w(seg.table, sheet)
                        e.measures.append(seg)
                        if block not in e.crosstabs:
                            e.crosstabs.append(block)
                    elif isinstance(seg, DimensionSegment):
                        e = w(seg.table, sheet)
                        e.dims.append(seg)
                        if block not in e.crosstabs:
                            e.crosstabs.append(block)
                    elif isinstance(seg, DerivedSegment):
                        w(seg.verify.against_table, sheet).verified_by.append(seg)
                        if seg.keep_as is not None:
                            e = w(seg.keep_as.table, sheet)
                            e.kept_from.append(seg)
                            if block not in e.crosstabs:
                                e.crosstabs.append(block)
            else:
                w(block.table, sheet).lists.append(block)
                total = block.rows.total_row
                if total is not None and total.keep_as:
                    w(total.keep_as, sheet).list_totals.append(block)
    return out


def _actual_sheet(sheet: SheetRecipe, extraction: Extraction) -> str:
    return extraction.sheets.matched.get(sheet.id) or sheet.match.name


def _lineage_spans(extraction: Extraction, table: str, sheet: str) -> list[tuple[int, int]]:
    """本表的值在这张工作表上占的行区间（来自溯源段）。判断隐藏行、停止后的行属于哪张表用。"""
    spans: list[tuple[int, int]] = []
    for runs in (extraction.lineage.get(table) or {}).values():
        for run in runs:
            try:
                run_sheet, cell, count, direction = run[1], run[2], int(run[3]), run[4]
            except (IndexError, TypeError, ValueError):
                continue
            parsed = split_coord(cell)
            if run_sheet != sheet or parsed is None:
                continue
            row = parsed[2]
            spans.append((row, row + count - 1) if direction == "down" else (row, row))
    return spans


# ---------------------------------------------------------------- 表说明的各个片段


@dataclass
class _Ctx:
    recipe: Recipe
    extraction: Extraction
    checks: dict[str, CheckResult]
    accepted: set[str]
    tables: dict[str, list[ColumnOut]]
    grains: dict[str, list[str]]
    dates: dict[str, set[str]]
    writers: dict[str, _Writers]
    problems: list[str]
    plan: Any

    def check(self, table: str, cid: str | None, what: str) -> CheckResult | None:
        c = self.checks.get(cid or "")
        if c is None:
            self.problems.append(f"表「{table}」：找不到{what}的核对结果，无法生成说明")
        return c


def _blocking(c: CheckResult) -> bool:
    """不可接受的结构类失败（K / G / T 不一致、核对 SQL 出错、落库不对）：试运行已经因此拒收、也提交不了。

    这时不写这一段说明、也不记 problems：problems 会被当成「配方本身不合法 / 说明生成失败」显示，
    把用户引去改配方，而真正的问题是那条核对。problems 只留给真正缺模板的情况。
    不写比写错安全：缺了这一句，说明里就不会有「一致」。
    """
    return c.status == "mismatch" and c.category == "structure" and not c.acceptable


def _per_day(ctx: _Ctx, table: str) -> bool:
    grain = ctx.grains.get(table, [])
    return len(grain) == 1 and grain[0] in ctx.dates.get(table, set())


def _grain_fragment(grain: list[str]) -> str | None:
    cols = [_col(g) for g in grain]
    if not cols:
        return None
    if len(cols) == 1:
        return NOTE_TEXT["grain_1"].format(a=cols[0])
    if len(cols) == 2:
        return NOTE_TEXT["grain_2"].format(a=cols[0], b=cols[1])
    return NOTE_TEXT["grain_n"].format(a=_LIST.join(cols[:-1]), b=cols[-1])


def _sum_eq_fragment(ctx: _Ctx, table: str, rel: SumEq) -> str | None:
    c = ctx.check(table, rel.id, f"关系「{rel.id}」")
    if c is None or _blocking(c):
        # 核对 SQL 出错时 status 也是 mismatch：不能当成「关系不成立」去写
        return None
    per, unit = _PER[_per_day(ctx, table)]
    total = _col(rel.total)
    if c.status == "passed":
        return NOTE_TEXT["sum_eq_passed"].format(total=total, parts=_join_and([_col(p) for p in rel.parts]), per=per)
    parts = _LIST.join(_col(p) for p in rel.parts)
    if c.status == "mismatch":
        key = "sum_eq_mismatch_accepted" if rel.id in ctx.accepted else "sum_eq_mismatch_pending"
        return NOTE_TEXT[key].format(total=total, parts=parts, unit=unit)
    if c.status == "unverifiable":
        key = "sum_eq_no_rows" if not c.checked and not c.unverifiable else "sum_eq_nulls"
        return NOTE_TEXT[key].format(total=total, parts=parts, unit=unit)
    ctx.problems.append(f"表「{table}」：关系「{rel.id}」的核对状态「{c.status}」没有对应的说明")
    return None


def _not_comparable_fragment(ctx: _Ctx, table: str, rel: NotComparable) -> str | None:
    c = ctx.check(table, rel.id, f"关系「{rel.id}」")
    if c is None or _blocking(c):
        return None
    if c.status != "info":
        ctx.problems.append(f"表「{table}」：关系「{rel.id}」的核对没有完成，无法生成说明")
        return None
    other = rel.b.table if table == rel.a.table else rel.a.table
    if c.failed <= 0:
        # 本期全部相等（或没有可比的分组）：不写「不等于」
        return NOTE_TEXT["not_comparable_equal"].format(other=_tab(other))
    dims = [g for g in ctx.grains.get(rel.a.table, []) if g != rel.by]
    if dims:
        return NOTE_TEXT["not_comparable_unequal"].format(
            other=_tab(other), dims=_LIST.join(_col(d) for d in dims), value=_col(rel.b.value))
    return NOTE_TEXT["not_comparable_unequal_flat"].format(
        other=_tab(other), a_value=_col(rel.a.value), by=_col(rel.by), value=_col(rel.b.value))


def _dim_fragments(w: _Writers) -> list[str]:
    out: list[str] = []
    for seg in w.dims:
        if seg.dim.parser != "hour_range":
            continue
        roles = {role: name for name, role in seg.dim.derive.items()}
        if "start" in roles and "end" in roles:
            text = NOTE_TEXT["hour_range"].format(dim=_col(seg.dim.name), start=_col(roles["start"]),
                                                  end=_col(roles["end"]))
        else:
            text = NOTE_TEXT["hour_range_plain"].format(dim=_col(seg.dim.name))
        if text not in out:
            out.append(text)
    for seg in w.dims:
        for name in sorted(seg.const):
            text = NOTE_TEXT["const"].format(col=_col(name))
            if text not in out:
                out.append(text)
    return out


def _base_total_fragments(w: _Writers) -> list[str]:
    """明细表上的提示：原表合计另存在哪、或者没导入。"""
    out: list[str] = []
    kept = [s.keep_as.table for s in w.verified_by if s.keep_as is not None]
    kept += [b.rows.total_row.keep_as for b in w.lists if b.rows.total_row is not None and b.rows.total_row.keep_as]
    for t in kept:
        text = NOTE_TEXT["total_kept"].format(table=_tab(t))
        if text not in out:
            out.append(text)
    dropped = any(s.keep_as is None for s in w.verified_by) or any(
        b.rows.total_row is not None and not b.rows.total_row.keep_as for b in w.lists)
    if dropped:
        out.append(NOTE_TEXT["total_not_kept"])
    return out


def _total_key(checks: list[CheckResult], by_reason: dict[str, str], mixed: str, *,
               g_checks: list[CheckResult] | tuple[CheckResult, ...] = (), passed: str,
               passed_g: str | None = None) -> str | None:
    """表内合计表按「状态 × 原因」选模板。返回 None 表示没有对应模板（调用方记 problems）。"""
    statuses = {c.status for c in checks} | {c.status for c in g_checks}
    if not checks or "mismatch" in statuses or statuses - {"passed", "unverifiable"}:
        return None
    if all(c.status == "passed" for c in checks):
        if any(g.status == "unverifiable" for g in g_checks):
            return passed_g
        return passed
    reasons = {r for c in checks if c.status == "unverifiable" for r, n in c.reasons.items() if n}
    some_passed = any(c.status == "passed" for c in checks)
    if len(reasons) == 1 and not some_passed:
        return by_reason.get(next(iter(reasons)))
    # 几种原因，或者一部分核对通过、一部分没有：用最弱的说法，不挑其中一种来写
    return mixed if reasons else None


def _kept_total_fragments(ctx: _Ctx, table: str, w: _Writers) -> list[str]:
    out: list[str] = []
    if w.kept_from:
        # 一张合计表可以由几个 derived 段写入（日间、夜间各有合计行）：所有段的 K、G 一起选一条模板
        ks = [ctx.check(table, ctx.plan.k.get(s.id), f"分段「{s.id}」的合计") for s in w.kept_from]
        gs = [ctx.check(table, ctx.plan.g[s.id], f"分段「{s.id}」的公式引用") for s in w.kept_from if s.id in ctx.plan.g]
        if None in ks or None in gs:
            return out
        if not any(_blocking(c) for c in ks + gs):
            key = _total_key(ks, _K_REASON, "total_k_mixed", g_checks=gs, passed="total_k_passed",
                             passed_g="total_k_passed_g_unverifiable")
            if key is None:
                ctx.problems.append(f"表「{table}」：合计核对 {_ids(ks + gs)} 的结果没有对应的说明")
                return out
            out.append(NOTE_TEXT[key])
        for seg in w.kept_from:
            text = NOTE_TEXT["total_overlap"].format(dim=_col(seg.keep_as.dim), base=_tab(seg.verify.against_table))
            if text not in out:
                out.append(text)
    for block in w.list_totals:
        t = ctx.check(table, ctx.plan.t.get(block.id), f"块「{block.id}」的合计行")
        if t is None or _blocking(t):
            continue
        key = _total_key([t], _T_REASON, "list_total_mixed", passed="list_total_passed")
        if key is None:
            ctx.problems.append(f"表「{table}」：合计核对 {t.id} 的结果没有对应的说明")
            continue
        blank_cols = _uncovered_total_columns(ctx, block) if key == "list_total_passed" else []
        if blank_cols:
            text = NOTE_TEXT["list_total_passed_partial"].format(
                cols=_LIST.join(_col(c) for c in blank_cols), base=_tab(block.table))
        else:
            text = NOTE_TEXT[key].format(base=_tab(block.table))
        if text not in out:
            out.append(text)
    return out


def _uncovered_total_columns(ctx: _Ctx, block: ListBlock) -> list[str]:
    """列表合计行里没有生成合计格的数字列（原表合计格是空的，P2-SPEC 4.4），按配方列序。

    这些列在合计表里存的是空值、T 也没核对过。按合计格算而不按库里的空值数算：4 参数调用（不带 null_counts）
    时照样成立。
    """
    covered = {it.base_value for it in ctx.plan.items.get(block.id, [])}
    return [c.name for c in block.columns if c.type in ("INTEGER", "REAL") and c.name not in covered]


def _ids(checks: list[CheckResult]) -> str:
    return "、".join(c.id for c in checks)


def _hidden_fragments(ctx: _Ctx, table: str, w: _Writers) -> list[str]:
    excluded = included = False
    for sheet in w.sheets:
        actual = _actual_sheet(sheet, ctx.extraction)
        info = ctx.extraction.hidden.get(actual) or {}
        rows = [int(r) for r in info.get("rows") or []]
        if not rows:
            continue
        policy = info.get("policy_rows") or sheet.hidden.rows
        spans = _lineage_spans(ctx.extraction, table, actual)
        if policy == "exclude":
            # 排除的行不在溯源里：落在本表占的行范围之内就算本表排除了它们
            lo, hi = (min(a for a, _ in spans), max(b for _, b in spans)) if spans else (None, None)
            excluded |= not spans or any(lo <= r <= hi for r in rows)
        elif policy == "include":
            included |= not spans or any(a <= r <= b for a, b in spans for r in rows)
    out = []
    if excluded:
        out.append(NOTE_TEXT["hidden_excluded"])
    if included:
        out.append(NOTE_TEXT["hidden_included"])
    return out


def _rows_after_stop_tables(ctx: _Ctx) -> set[str]:
    """rows_after_stop 问题落在哪张表上：同一工作表上被空行停下的列表块；不止一个时取紧挨在这些行之上的那个。"""
    out: set[str] = set()
    for p in ctx.extraction.problems:
        if p.code != "rows_after_stop" or not p.cells:
            continue
        parsed = split_coord(p.cells[0])
        if parsed is None or parsed[0] is None:
            continue
        sheet_name, first_row = parsed[0], parsed[2]
        blocks = [b for s in ctx.recipe.sheets if _actual_sheet(s, ctx.extraction) == sheet_name
                  for b in s.blocks if isinstance(b, ListBlock) and b.rows.blank_rows == "stop"]
        if len(blocks) > 1:
            above = [(max(b for _, b in spans), blk) for blk in blocks
                     if (spans := _lineage_spans(ctx.extraction, blk.table, sheet_name))
                     and max(b for _, b in spans) < first_row]
            if above:
                blocks = [max(above, key=lambda x: x[0])[1]]
        out.update(b.table for b in blocks)
    return out


def _period_fragments(ctx: _Ctx, w: _Writers) -> list[str]:
    if not any(s.context for s in w.sheets):
        return []
    out: list[str] = []
    # 按传进来的核对结果判（run_checks 把 C1、C2 原样排在最前），与试运行、提交时存下的那份一致
    conflicts = [c for c in ctx.checks.values()
                 if c.kind in ("context_agree", "filename_period") and c.status == "mismatch"]
    if conflicts:
        accepted = all(c.id in ctx.accepted for c in conflicts)
        out.append(NOTE_TEXT["period_conflict_accepted" if accepted else "period_conflict_pending"])
    if ctx.extraction.period is not None and ctx.extraction.period.source == "human":
        out.append(NOTE_TEXT["period_human"])
    return out


def _table_template(ctx: _Ctx, table: str, after_stop: set[str]) -> str:
    w = ctx.writers.get(table, _Writers())
    spec = next((t for t in ctx.recipe.tables if t.name == table), None)
    frags: list[str | None] = [_grain_fragment(ctx.grains.get(table, []))]
    for rel in ctx.recipe.relations:
        if isinstance(rel, SumEq) and rel.table == table:
            frags.append(_sum_eq_fragment(ctx, table, rel))
    for rel in ctx.recipe.relations:
        if isinstance(rel, NotComparable) and table in (rel.a.table, rel.b.table):
            frags.append(_not_comparable_fragment(ctx, table, rel))
    frags += _dim_fragments(w)
    frags += _base_total_fragments(w)
    frags += _kept_total_fragments(ctx, table, w)
    frags += _hidden_fragments(ctx, table, w)
    if any(b.extra_columns == "ignore" and ctx.extraction.ignored_columns.get(b.id) for b in w.lists):
        frags.append(NOTE_TEXT["ignored_columns"])
    if table in after_stop:
        frags.append(NOTE_TEXT["rows_after_stop"])
    frags += _period_fragments(ctx, w)
    sheets = {_actual_sheet(s, ctx.extraction) for s in w.sheets}
    if any(o.kind == "text_digits" and o.sheet in sheets for o in ctx.extraction.outside_text):
        frags.append(NOTE_TEXT["outside_digits"])
    if spec is not None and spec.note.strip():
        frags.append(spec.note.strip())
    return "。".join(f.strip().rstrip("。") for f in frags if f and f.strip().rstrip("。"))


# ---------------------------------------------------------------- 列说明


def _occurred(placeholders: list[Placeholder], extraction: Extraction) -> list[Placeholder]:
    """本期真的出现过的占位符（按 canon 比对原文）。"""
    seen = {canon(k) for k, n in extraction.placeholders.items() if n}
    return [p for p in placeholders if canon(p.text) in seen]


def _null_fragment(w: _Writers, extraction: Extraction) -> str | None:
    blocks: list[Any] = [*w.crosstabs, *w.lists]
    marks = [p for b in blocks for p in _occurred(list(b.values.placeholders), extraction)]
    blank = any(b.values.blank == "null" for b in blocks)
    meanings = {p.meaning for p in marks}
    meaning = next(iter(meanings)) if len(meanings) == 1 else _MEANING_BOTH
    if marks and blank:
        return COLUMN_TEXT["null_both"].format(meaning=meaning)
    if marks:
        return COLUMN_TEXT["null_placeholder"].format(meaning=meaning)
    if blank:
        return COLUMN_TEXT["null_blank"]
    return None


def _year_from_period(ctx: _Ctx, w: _Writers) -> bool:
    """轴的年份是不是从统计期补的：配了 year_from，而且本期表头不全是自带年份的日期格。"""
    for block in w.crosstabs:
        if block.axis.year_from is None:
            continue
        forms = [a.form for a in ctx.extraction.axes if a.block == block.id]
        if not forms or any(f != "date" for f in forms):
            return True
    return False


def _column_templates(ctx: _Ctx, table: str, null_counts: Mapping[str, Mapping[str, int]] | None) -> dict[str, str]:
    w = ctx.writers.get(table, _Writers())
    grain = set(ctx.grains.get(table, []))
    is_total = bool(w.kept_from or w.list_totals)
    list_dates = {c.name for b in w.lists for c in b.columns if c.type == "DATE"}
    counts = null_counts.get(table) if null_counts is not None else None
    out: dict[str, str] = {}
    for col in ctx.tables.get(table, []):
        frags: list[str] = []
        if col.role == "axis":
            frags.append(COLUMN_TEXT["date_year_from_period" if _year_from_period(ctx, w) else "date"])
        elif col.name in list_dates:
            frags.append(COLUMN_TEXT["date"])
        if col.unit:
            frags.append(COLUMN_TEXT["unit"].format(unit=_tok("单位", col.unit)))
        # 值列的空值说明：主键不会是空值；表内合计表的空值已由表说明（未能核对）交代
        value_col = (col.role in ("measure", "value") and col.type in ("INTEGER", "REAL"))
        has_nulls = counts is None or counts.get(col.name, 0) > 0
        if value_col and not is_total and col.name not in grain and has_nulls:
            if (text := _null_fragment(w, ctx.extraction)) is not None:
                frags.append(text)
        if frags:
            out[col.name] = "。".join(frags)
    return out


# ---------------------------------------------------------------- 入口


def build_notes(recipe: Recipe, extraction: Extraction, checks: list[CheckResult],
                acceptances: list[Acceptance], *,
                null_counts: Mapping[str, Mapping[str, int]] | None = None) -> SchemaNotes:
    """按核对结果生成全部表说明、列说明。problems 非空就不能保存（试运行判 recipe 类问题，提交拒绝）。

    acceptances：写了理由接受的核对。试运行回执的预览传空列表（按「全部未接受」生成），提交时传实际的接受。
    null_counts（recipe_checks.column_null_counts 的结果）：给了就只对本期真有空值的值列写空值说明。
    不给时只能按配方推断——Extraction.placeholders 是整份文件的计数、不分列，于是配了占位符且本期出现过、
    或空格存空值的块里，每个值列都写（宁可多写一句「空值表示……」，不能漏写）。
    **试运行预览和提交都应传 null_counts**：参考配方（D00）的 全日客流 列说明要是「单位：人次」
    （P2-SPEC 7.4、9.7 第 2 步），不传就会多出空值那一句。
    """
    tables, shape_problems = derive_tables(recipe)
    problems = [f"配方推出的表结构有问题：{p.message}" for p in shape_problems]
    ctx = _Ctx(
        recipe=recipe, extraction=extraction, checks={c.id: c for c in checks},
        accepted={a.check_id for a in acceptances}, tables=tables,
        grains={t.name: list(t.grain) for t in recipe.tables}, dates=date_columns(recipe),
        writers=_writers(recipe), problems=problems, plan=plan_checks(recipe, extraction),
    )
    # 只给真正建出来的表写说明（derive_tables 推出的表）；声明了却没有分段写入的表不在库里，写了也落不了地
    names = list(tables)
    known = {"列": {c.name for cols in tables.values() for c in cols},
             "表": set(names) | {t.name for t in recipe.tables}, "单位": set(UNITS)}
    after_stop = _rows_after_stop_tables(ctx)
    notes = SchemaNotes(problems=problems)
    notes.kinds = {t.name: t.kind for t in recipe.tables if t.kind == "reported_total" and t.name in tables}
    for table in names:
        template = _table_template(ctx, table, after_stop)
        columns = _column_templates(ctx, table, null_counts)
        for p in prose_problems(template, known=known):
            problems.append(f"表「{table}」的说明：{p}")
        for col, tpl in columns.items():
            for p in prose_problems(tpl, known=known):
                problems.append(f"表「{table}」列「{col}」的说明：{p}")
        if template:
            notes.templates[table] = template
        notes.templates.update({f"{table}.{col}": tpl for col, tpl in columns.items()})
        notes.tables[table] = TableNote(comment=render_prose(template),
                                        columns={col: render_prose(tpl) for col, tpl in columns.items()})
    return notes


def apply_notes(schema_cache: dict[str, Any], notes: SchemaNotes) -> dict[str, Any]:
    """把说明写进表结构，返回新 dict（不改入参）：表 comment、列 comment，顶层加 import_mode=recipe。

    表或列在 schema_cache 里找不到（不该发生：说明和库出自同一份配方）时记进 notes.problems，不悄悄跳过。
    表说明为空时保留原来的 comment。
    """
    out = copy.deepcopy(schema_cache) if schema_cache else {}
    tables = out.get("tables")
    if not isinstance(tables, dict):
        tables = {}
    for name, kind in notes.kinds.items():
        # 表的种类记进表结构：说明（不要相加）只有 db_schema 查单表时看得到，工具描述和写作目录靠它点名（AU-5）
        if isinstance(tables.get(name), dict):
            tables[name]["kind"] = kind
    for name, note in notes.tables.items():
        meta = tables.get(name)
        if not isinstance(meta, dict):
            notes.problems.append(f"表「{name}」不在表结构中，说明没有写入")
            continue
        if note.comment:
            meta["comment"] = note.comment
        columns = {c.get("name"): c for c in meta.get("columns") or [] if isinstance(c, dict)}
        for col, text in note.columns.items():
            target = columns.get(col)
            if target is None:
                notes.problems.append(f"表「{name}」没有列「{col}」，说明没有写入")
                continue
            target["comment"] = text
    out["import_mode"] = "recipe"
    return out