#!/usr/bin/env python3
"""
基于统一索引生成最终可导入的合成知识库。

新原则：
- 培训文档是主事实层，完整保留
- Figma / 测试用例是补充层
- 模块仅作为辅助索引
- 主要组织轴：feature_scope + app_version + 来源优先级

输出目录：
  dist/final_kb/
"""

from __future__ import annotations

import json
import re
from collections import Counter, defaultdict
from pathlib import Path


BASE_DIR = Path(__file__).parent.parent
RAG_DIR = BASE_DIR / "dist" / "rag"
OUT_DIR = BASE_DIR / "dist" / "final_kb"
BACKEND_CODE_DIR = BASE_DIR / "dist" / "backend_code"

SOURCE_PRIORITY = {"doc_rule": 0, "definition": 0, "rule": 1, "case_rule": 2}
SOURCE_LABEL = {
    "doc_rule": "培训文档",
    "definition": "培训文档定义",
    "rule": "Figma",
    "case_rule": "测试用例",
}
MODULE_ORDER = [
    "AUTH",
    "INCOME",
    "INQUIRY",
    "CLINIC",
    "PATIENT",
    "NOTIFICATION",
    "BACKSTAGE",
    "GENERAL",
]
MODULE_NAMES = {
    "AUTH": "认证",
    "INCOME": "收入提现",
    "INQUIRY": "问诊",
    "CLINIC": "门诊",
    "PATIENT": "患者",
    "NOTIFICATION": "通知",
    "BACKSTAGE": "后台",
    "GENERAL": "通用",
}
GENERIC_RESULTS = {"满足预期", "搜索出结果", "成功", "失败", "显示成功", "显示失败", "表现正常"}
SCREENSHOT_MARKERS = ("[截图]", "[图]", "截图")
GENERIC_DOC_HEADINGS = {
    "APP端",
    "PC端",
    "小程序端",
    "后台",
    "数据定义",
    "关注流程",
    "关注对象",
    "咨询列表",
    "团队患者开方",
    "团队医生列表",
    "团队工作室医生列表",
}


def version_key(version: str) -> tuple[int, ...]:
    return tuple(int(part) for part in re.findall(r"\d+", version or ""))


def clean_text(text: str) -> str:
    text = str(text or "")
    return re.sub(r"\s+", " ", text).strip()


def load_jsonl(path: Path) -> list[dict]:
    rows = []
    with path.open("r", encoding="utf-8") as handle:
        for raw_line in handle:
            line = raw_line.strip()
            if line:
                rows.append(json.loads(line))
    return rows


def load_optional_jsonl(path: Path) -> list[dict]:
    if not path.exists():
        return []
    return load_jsonl(path)


def is_clean_supplement(atom: dict) -> bool:
    atom_type = atom.get("atom_type", "")
    if atom_type not in {"rule", "case_rule"}:
        return False
    a = clean_text(atom.get("A", ""))
    r = clean_text(atom.get("R", ""))
    canon = clean_text(atom.get("canon_text", ""))
    if not a or not r:
        return False
    if any(marker in a or marker in r or marker in canon for marker in SCREENSHOT_MARKERS):
        return False
    if r in GENERIC_RESULTS:
        return False
    if "？" in a or "？" in r or "???" in a or "???" in r:
        return False
    if atom_type == "case_rule" and re.search(r"^\d+[，、.]", a):
        return False
    return True


def atom_sort_key(atom: dict) -> tuple:
    return (
        version_key(atom.get("app_version", "")),
        SOURCE_PRIORITY.get(atom.get("atom_type", ""), 9),
        atom.get("merge_fingerprint", ""),
    )


def feature_sort_key(feature_scope: str) -> tuple:
    return (display_feature_scope(feature_scope).lower(),)


def display_feature_scope(feature_scope: str) -> str:
    scope = clean_text(feature_scope)
    scope = re.sub(r"^\d{1,2}\.\d+(?=\s|[^\d])\s*", "", scope)
    scope = re.sub(r"^(?:\d+(?:[.．]\d+)*[、.．)]\s*)+", "", scope)
    scope = re.sub(r"^\d(?=[\u4e00-\u9fff])", "", scope)
    scope = re.sub(r"^[：:、.．\s]+", "", scope)
    return scope or "未归类功能"


def normalize_title_candidate(text: str) -> str:
    text = display_feature_scope(text)
    text = re.sub(r"^[•◦■\-]+\s*", "", text)
    text = re.sub(r"^[a-zA-ZivxIVX]+[.、)]\s*", "", text)
    text = re.sub(r"^\d+\s+", "", text)
    text = re.sub(r"^\d(?=\s|[\u4e00-\u9fff])", "", text)
    text = re.split(r"\s*(?:场景|功能设计|需求背景|背景|处理方式|设计说明|说明)[:：]", text, maxsplit=1)[0]
    text = re.split(r"\s{2,}", text, maxsplit=1)[0]
    if len(text) > 24:
        text = re.split(r"[，。,；;]", text, maxsplit=1)[0]
    text = re.sub(r"[，。,；;：:]\s*$", "", text)
    text = clean_text(text)
    return text


def is_good_title(text: str) -> bool:
    text = normalize_title_candidate(text)
    if not text or len(text) < 4 or len(text) > 32:
        return False
    if text == "未归类功能":
        return False
    if re.match(r"^\d", text):
        return False
    if re.match(r"^[•◦■\-]", text):
        return False
    if text in GENERIC_DOC_HEADINGS:
        return False
    if any(keyword in text for keyword in ["灰度", "预估时间", "仅供参考", "咨询萧峰"]):
        return False
    if " " in text and len(text) > 18:
        return False
    if any(keyword in text for keyword in ["场景", "功能设计", "需求背景", "背景"]):
        return False
    return True


def fallback_title_from_atoms(atoms: list[dict]) -> str:
    for atom in atoms:
        for raw in (atom.get("A", ""), atom.get("R", ""), atom.get("C", "")):
            text = normalize_rule_phrase(raw)
            if not text:
                continue
            candidates = [text]
            if "：" in text:
                candidates.append(text.split("：", 1)[0])
            candidates.extend(re.split(r"[，。,；;]", text, maxsplit=2))
            for candidate in candidates:
                candidate = normalize_title_candidate(candidate)
                if is_good_title(candidate):
                    return candidate
    return ""


def best_doc_title(atoms: list[dict], feature_scope: str) -> str:
    candidates = [normalize_title_candidate(feature_scope)]
    for atom in atoms:
        a = normalize_title_candidate(atom.get("A", ""))
        c = normalize_title_candidate(atom.get("C", "").replace("背景：", "", 1))
        if a:
            candidates.append(a)
        if c:
            candidates.append(c)

    def score(title: str) -> tuple[int, int, str]:
        good = 1 if is_good_title(title) else 0
        ideal_len = abs(len(title) - 10)
        return (good, -ideal_len, title)

    unique = []
    seen = set()
    for item in candidates:
        if item and item not in seen:
            seen.add(item)
            unique.append(item)
    fallback = fallback_title_from_atoms(atoms)
    if fallback and fallback not in seen:
        unique.append(fallback)
    if not unique:
        return "未归类功能"
    unique.sort(key=score, reverse=True)
    return unique[0]


def sample_texts(atoms: list[dict], limit: int = 2) -> list[str]:
    seen = set()
    result = []
    for atom in sorted(atoms, key=atom_sort_key):
        text = clean_text(atom.get("R") or atom.get("A") or atom.get("rule_text", ""))
        if not text or text in seen:
            continue
        seen.add(text)
        result.append(text)
        if len(result) >= limit:
            break
    return result


def group_by_feature(atoms: list[dict]) -> dict[str, list[dict]]:
    grouped: dict[str, list[dict]] = defaultdict(list)
    for atom in atoms:
        grouped[atom["feature_scope"]].append(atom)
    return grouped


def group_doc_facts(master_atoms: list[dict]) -> dict[str, list[dict]]:
    docs = [atom for atom in master_atoms if atom.get("atom_type") in {"doc_rule", "definition"}]
    grouped = group_by_feature(docs)
    return {feature: sorted(items, key=atom_sort_key) for feature, items in grouped.items()}


def group_supplements(master_atoms: list[dict]) -> dict[str, list[dict]]:
    supplements = [atom for atom in master_atoms if is_clean_supplement(atom)]
    grouped = group_by_feature(supplements)
    return {feature: sorted(items, key=atom_sort_key) for feature, items in grouped.items()}


def module_counter_from_features(feature_atoms: dict[str, list[dict]]) -> Counter:
    counter = Counter()
    for atoms in feature_atoms.values():
        modules = {mod for atom in atoms for mod in atom.get("modules", [])}
        if not modules and atoms:
            modules = {atoms[0].get("primary_module", "GENERAL")}
        for module in modules:
            counter[module] += 1
    return counter


def split_doc_facts(doc_features: dict[str, list[dict]]) -> tuple[dict[str, list[dict]], dict[str, list[dict]]]:
    def is_readable(atom: dict) -> bool:
        scope = display_feature_scope(atom.get("feature_scope", ""))
        a = clean_text(atom.get("A", ""))
        r = clean_text(atom.get("R", ""))
        if len(scope) <= 2:
            return False
        if "背景：" in r or "功能：" in r or "目标：" in r:
            return False
        if len(r) > 180:
            return False
        if a == r and len(r) <= 4:
            return False
        return True

    primary: dict[str, list[dict]] = {}
    retained: dict[str, list[dict]] = {}
    for feature, atoms in doc_features.items():
        title = best_doc_title(atoms, feature)
        preferred = [atom for atom in atoms if atom.get("_source_file", "").endswith("doc_atoms_model.jsonl") and is_readable(atom)]
        readable_rules = summarize_doc_rules(preferred, limit=4) if preferred else []
        if preferred and is_good_title(title) and readable_rules:
            primary[feature] = preferred
            preferred_fp = {atom.get("merge_fingerprint") for atom in preferred}
            extra = [atom for atom in atoms if atom.get("merge_fingerprint") not in preferred_fp]
            if extra:
                retained[feature] = extra
        else:
            retained[feature] = atoms
    return primary, retained


def normalize_rule_phrase(text: str) -> str:
    text = clean_text(text)
    text = re.sub(r"^[a-zA-ZivxIVX]+[.、]\s*", "", text)
    text = re.sub(r"^[a-zA-ZivxIVX]+[)]\s*", "", text)
    text = re.sub(r"^\d+[.．、，)]\s*", "", text)
    text = re.sub(r"^\d+\s+", "", text)
    text = re.sub(r"^\d(?=[\u4e00-\u9fff])", "", text)
    text = re.split(r"\s*(?:场景|功能设计|需求背景|背景|说明)[:：]", text, maxsplit=1)[0]
    text = text.strip("：:;；")
    return text


def is_pretty_rule(line: str, title: str = "") -> bool:
    line = clean_text(line)
    if not line:
        return False
    if len(line) < 6 or len(line) > 88:
        return False
    if line == title:
        return False
    if line.startswith(("•", "◦", "-", "但是", "同时", "这样")):
        return False
    if any(marker in line for marker in ["•", "◦", "功能设计", "需求背景"]):
        return False
    if re.search(r"\b(?:i|ii|iii|iv|v|vi)\b[.．)]?", line, re.IGNORECASE):
        return False
    if any(keyword in line for keyword in ["灰度", "预估时间", "仅供参考", "咨询萧峰"]):
        return False
    return True


def summarize_doc_rules(atoms: list[dict], limit: int = 12) -> list[str]:
    rules = []
    seen = set()
    for atom in atoms:
        a = normalize_rule_phrase(atom.get("A", ""))
        r = normalize_rule_phrase(atom.get("R", ""))
        feature = display_feature_scope(atom.get("feature_scope", ""))
        if not r:
            continue
        if r == a or not a or a == feature:
            line = r
        elif len(r) <= 18 and len(a) <= 28:
            line = f"{a}：{r}"
        elif any(keyword in a for keyword in ["逻辑", "排序", "操作", "显示", "默认", "规则", "变化"]):
            line = f"{a}：{r}"
        else:
            line = r
        line = clean_text(line)
        if len(line) < 6:
            continue
        if line == feature:
            continue
        if line in GENERIC_DOC_HEADINGS:
            continue
        if re.match(r"^\d", line):
            continue
        if any(keyword in line for keyword in ["灰度", "预估时间", "仅供参考", "咨询萧峰"]):
            continue
        if "背景" in line and len(line) <= 18:
            continue
        if not is_pretty_rule(line, feature):
            continue
        if not line or line in seen:
            continue
        seen.add(line)
        rules.append(line)
        if len(rules) >= limit:
            break
    return rules


def render_doc_atom(atom: dict) -> list[str]:
    lines = []
    if atom.get("atom_type") == "definition":
        term = clean_text(atom.get("term", ""))
        definition = clean_text(atom.get("definition", ""))
        lines.append(f"- 定义：{term}")
        lines.append(f"- 说明：{definition}")
    else:
        c = clean_text(atom.get("C", ""))
        a = clean_text(atom.get("A", ""))
        r = clean_text(atom.get("R", ""))
        if c:
            lines.append(f"- 前提：{c}")
        if a:
            lines.append(f"- 操作/场景：{a}")
        if r:
            lines.append(f"- 规则：{r}")
    lines.append(f"- 版本：{atom.get('app_version', '')}")
    return lines


def render_supplement_atom(atom: dict) -> list[str]:
    c = clean_text(atom.get("C", ""))
    a = clean_text(atom.get("A", ""))
    r = clean_text(atom.get("R", ""))
    lines = []
    if c:
        lines.append(f"- 前提：{c}")
    lines.append(f"- 操作：{a}")
    lines.append(f"- 结果：{r}")
    lines.append(f"- 来源：{SOURCE_LABEL.get(atom.get('atom_type', ''), atom.get('atom_type', ''))} · {atom.get('app_version', '')}")
    return lines


def render_manifest(doc_features: dict[str, list[dict]], supplement_features: dict[str, list[dict]]) -> str:
    module_stats = module_counter_from_features(doc_features)
    has_backend = (BACKEND_CODE_DIR / "code_atoms.jsonl").exists()
    lines = [
        "# 最终知识库导入说明",
        "",
        "推荐导入顺序：",
        "1. `00_导入说明.md`",
        "2. `01_知识库设计原则.md`",
        "3. `02_培训文档主事实库.md`",
        "4. `03_培训文档保留项.md`",
        "5. `04_Figma与测试补充库.md`",
        "6. `05_版本演进.md`",
        "7. `06_需求预评审.md`",
        "8. `07_模块辅助索引.md`",
        "",
        f"- 培训文档功能主题数：{len(doc_features)}",
        f"- 补充层功能主题数：{len(supplement_features)}",
        "",
        "## 模块辅助索引分布",
        "",
    ]
    for module in MODULE_ORDER:
        if module_stats.get(module):
            lines.append(f"- {module} / {MODULE_NAMES.get(module, module)}：{module_stats[module]}")
    lines.extend(
        [
            "",
            "## 使用原则",
            "",
            "- 培训文档是主事实层，完整保留。",
            "- Figma 和测试用例只做补充，不抢培训文档主定义权。",
            "- 后台代码仓库是实现补充层，用于补接口契约、枚举状态和实现约束。",
            "- 模块仅用于辅助过滤、路由和预评审提示，不作为知识主切分轴。",
        ]
    )
    if has_backend:
        lines.insert(11, "9. `08_后台代码实现补充库.md`")
    return "\n".join(lines) + "\n"


def render_design_principles() -> str:
    return "\n".join(
        [
            "# 知识库设计原则",
            "",
            "## 主轴",
            "",
            "- `feature_scope`：功能主题",
            "- `app_version`：版本演进",
            "- `事实源优先级`：培训文档 > Figma > 测试用例",
            "",
            "## 事实源定位",
            "",
            "- 培训文档：主事实源，必须完整保留。",
            "- Figma：交互细节补充源。",
            "- 测试用例：行为验证与边界补充源。",
            "- 后台代码：实现补充源，补接口、枚举、状态和实现边界。",
            "",
            "## 模块定位",
            "",
            "- 模块保留，但仅作为辅助索引。",
            "- 非预定义模块内容不因分类问题被删除。",
            "- `GENERAL` 只表示兜底归类，不表示低价值。",
        ]
    ) + "\n"


def render_primary_facts(doc_features: dict[str, list[dict]]) -> str:
    lines = [
        "# 培训文档主事实库",
        "",
        "这份文档优先采用增强后的培训文档原子组织主事实，不因为模块体系而过滤。",
        "如果某些历史培训文档原子未被增强原子覆盖，会在“培训文档保留项”中继续保留。",
        "",
    ]
    for feature in sorted(doc_features.keys(), key=feature_sort_key):
        atoms = doc_features[feature]
        versions = sorted({atom["app_version"] for atom in atoms}, key=version_key)
        modules = sorted({mod for atom in atoms for mod in atom.get("modules", []) if mod})
        display_scope = best_doc_title(atoms, feature)
        background = ""
        for atom in atoms:
            c = clean_text(atom.get("C", ""))
            if c.startswith("背景："):
                background = c.replace("背景：", "", 1).strip()
                break
        rules = summarize_doc_rules(atoms)
        lines.append(f"## {display_scope}")
        lines.append("")
        lines.append(f"- 涉及版本：{', '.join(versions)}")
        if modules:
            lines.append(f"- 模块辅助标签：{', '.join(modules)}")
        if background:
            lines.append(f"- 背景：{background}")
        lines.append("")
        lines.append("### 关键规则")
        lines.append("")
        for rule in rules:
            lines.append(f"- {rule}")
        if not rules:
            lines.append("- 当前仅保留原文事实，详见培训文档保留项。")
        lines.append("")
        lines.append("---")
        lines.append("")
    return "\n".join(lines)


def render_retained_doc_facts(retained_features: dict[str, list[dict]]) -> str:
    lines = [
        "# 培训文档保留项",
        "",
        "这份文档保留历史培训文档原子中未被增强原子覆盖的内容。",
        "它们不应被删除，因为培训文档是主事实源；这里只是把可读性较弱的遗留项单独存放。",
        "",
    ]
    if not retained_features:
        lines.append("- 当前无额外保留项。")
        lines.append("")
        return "\n".join(lines)
    for feature in sorted(retained_features.keys(), key=feature_sort_key):
        atoms = retained_features[feature]
        versions = sorted({atom["app_version"] for atom in atoms}, key=version_key)
        lines.append(f"## {best_doc_title(atoms, feature)}")
        lines.append("")
        lines.append(f"- 涉及版本：{', '.join(versions)}")
        lines.append("")
        for atom in atoms:
            lines.extend(render_doc_atom(atom))
            lines.append("")
        lines.append("---")
        lines.append("")
    return "\n".join(lines)


def render_supplement_facts(doc_features: dict[str, list[dict]], supplement_features: dict[str, list[dict]]) -> str:
    lines = [
        "# Figma 与测试补充库",
        "",
        "这份文档只保留较干净的 Figma / 测试用例补充信息，用于补交互细节、边界场景和培训文档缺失内容。",
        "",
    ]
    feature_names = sorted(set(doc_features.keys()) | set(supplement_features.keys()), key=feature_sort_key)
    for feature in feature_names:
        supp = supplement_features.get(feature, [])
        if not supp:
            continue
        has_doc = feature in doc_features
        versions = sorted({atom["app_version"] for atom in supp}, key=version_key)
        modules = sorted({mod for atom in supp for mod in atom.get("modules", []) if mod})
        lines.append(f"## {display_feature_scope(feature)}")
        lines.append("")
        lines.append(f"- 培训文档主事实：{'有' if has_doc else '无'}")
        lines.append(f"- 补充来源版本：{', '.join(versions)}")
        if modules:
            lines.append(f"- 模块辅助标签：{', '.join(modules)}")
        lines.append("")
        for atom in supp[:12]:
            lines.extend(render_supplement_atom(atom))
            lines.append("")
        lines.append("---")
        lines.append("")
    return "\n".join(lines)


def render_version_history(doc_features: dict[str, list[dict]], supplement_features: dict[str, list[dict]]) -> str:
    lines = [
        "# 版本演进",
        "",
        "按功能主题组织，先看培训文档主事实，再看补充层变化。",
        "",
    ]
    feature_names = sorted(set(doc_features.keys()) | set(supplement_features.keys()), key=feature_sort_key)
    for feature in feature_names:
        primary = doc_features.get(feature, [])
        supp = supplement_features.get(feature, [])
        versions = sorted({atom["app_version"] for atom in primary + supp}, key=version_key)
        lines.append(f"## {display_feature_scope(feature)}")
        lines.append("")
        lines.append(f"- 版本范围：{', '.join(versions)}")
        if primary:
            lines.append(f"- 培训文档版本：{', '.join(sorted({atom['app_version'] for atom in primary}, key=version_key))}")
            lines.append(f"- 培训文档样例：{'；'.join(sample_texts(primary, 2)) or '无'}")
        else:
            lines.append("- 培训文档版本：无")
        if supp:
            lines.append(f"- 补充层版本：{', '.join(sorted({atom['app_version'] for atom in supp}, key=version_key))}")
            lines.append(f"- 补充层样例：{'；'.join(sample_texts(supp, 2)) or '无'}")
        else:
            lines.append("- 补充层版本：无")
        lines.append("")
    return "\n".join(lines)

def module_code_summary(code_atoms: list[dict], modules: list[str]) -> dict[str, list[str] | int]:
    atoms = [atom for atom in code_atoms if atom.get("primary_module") in modules]
    api_atoms = [atom for atom in atoms if atom.get("atom_type") == "api_contract"]
    enum_atoms = [atom for atom in atoms if atom.get("atom_type") == "enum_definition"]
    constraint_atoms = [atom for atom in atoms if atom.get("atom_type") == "impl_constraint"]

    api_samples = []
    seen_api = set()
    for atom in sorted(api_atoms, key=lambda x: (x.get("route_path", ""), x.get("method_name", ""))):
        text = f"{atom.get('http_method', '')} {atom.get('route_path', '')}".strip()
        if text and text not in seen_api:
            seen_api.add(text)
            api_samples.append(text)
        if len(api_samples) >= 4:
            break

    enum_samples = []
    seen_enum = set()
    for atom in sorted(enum_atoms, key=lambda x: x.get("feature_scope", "")):
        text = atom.get("feature_scope", "")
        if text and text not in seen_enum:
            seen_enum.add(text)
            enum_samples.append(text)
        if len(enum_samples) >= 4:
            break

    constraint_samples = []
    seen_constraint = set()
    for atom in sorted(constraint_atoms, key=lambda x: (x.get("feature_scope", ""), x.get("rule_text", ""))):
        text = atom.get("rule_text", "")
        if text and text not in seen_constraint:
            seen_constraint.add(text)
            constraint_samples.append(text)
        if len(constraint_samples) >= 4:
            break

    return {
        "api_count": len(api_atoms),
        "enum_count": len(enum_atoms),
        "constraint_count": len(constraint_atoms),
        "api_samples": api_samples,
        "enum_samples": enum_samples,
        "constraint_samples": constraint_samples,
    }


def review_feature_rank(item: dict) -> tuple:
    has_primary = 1 if item["primary"] else 0
    has_supp = 1 if item["supp"] else 0
    touchpoints = len(item["touchpoints"])
    versions = len(item["versions"])
    title = clean_text(item["title"])
    return (-has_primary, -(has_primary + has_supp), -touchpoints, -versions, title.lower())


def render_review_playbook(
    doc_features: dict[str, list[dict]],
    supplement_features: dict[str, list[dict]],
    backend_code_atoms: list[dict],
) -> str:
    lines = [
        "# 需求预评审",
        "",
        "新增需求时，先检查培训文档主事实，再检查 Figma 与测试用例补充层，最后结合后台代码实现补充层判断接口、状态与改造边界。",
        "本页按模块聚合，只保留更适合做预评审入口的高信息密度主题。",
        "",
    ]
    module_groups: dict[str, list[dict]] = defaultdict(list)
    feature_names = set(doc_features.keys()) | set(supplement_features.keys())
    for feature in feature_names:
        primary = doc_features.get(feature, [])
        supp = supplement_features.get(feature, [])
        versions = sorted({atom["app_version"] for atom in primary + supp}, key=version_key)
        modules = sorted({mod for atom in primary + supp for mod in atom.get("modules", []) if mod})
        touchpoints = sorted({tp for atom in primary + supp for tp in atom.get("touchpoints", []) if tp})
        title = best_doc_title(primary, feature) if primary else display_feature_scope(feature)
        item = {
            "feature": feature,
            "title": title,
            "primary": primary,
            "supp": supp,
            "versions": versions,
            "modules": modules,
            "touchpoints": touchpoints,
        }
        target_modules = modules or ["GENERAL"]
        for module in target_modules:
            module_groups[module].append(item)

    for module in MODULE_ORDER:
        items = module_groups.get(module, [])
        if not items:
            continue
        unique_items = []
        seen = set()
        for item in sorted(items, key=review_feature_rank):
            if item["feature"] in seen:
                continue
            seen.add(item["feature"])
            unique_items.append(item)
        code_summary = module_code_summary(backend_code_atoms, [module]) if backend_code_atoms else None
        lines.append(f"## {module} / {MODULE_NAMES.get(module, module)}")
        lines.append("")
        lines.append(f"- 主题数：{len(unique_items)}")
        if code_summary:
            lines.append(
                f"- 后台实现范围：接口 {code_summary['api_count']} / 枚举 {code_summary['enum_count']} / 约束 {code_summary['constraint_count']}"
            )
            if code_summary["api_samples"]:
                lines.append(f"- 后台接口样例：{'；'.join(code_summary['api_samples'])}")
            if code_summary["enum_samples"]:
                lines.append(f"- 后台枚举样例：{'；'.join(code_summary['enum_samples'])}")
            if code_summary["constraint_samples"]:
                lines.append(f"- 后台约束样例：{'；'.join(code_summary['constraint_samples'])}")
        lines.append("")
        for item in unique_items[:18]:
            lines.append(f"### {item['title']}")
            lines.append("")
            if item["touchpoints"]:
                lines.append(f"- 触点：{', '.join(item['touchpoints'])}")
            if item["versions"]:
                lines.append(f"- 涉及版本：{', '.join(item['versions'])}")
            lines.append(f"- 主事实样例：{'；'.join(sample_texts(item['primary'], 2)) or '无'}")
            lines.append(f"- 补充样例：{'；'.join(sample_texts(item['supp'], 2)) or '无'}")
            lines.append("")
        lines.append("---")
        lines.append("")
    return "\n".join(lines)


def render_module_index(doc_features: dict[str, list[dict]], supplement_features: dict[str, list[dict]]) -> str:
    module_features: dict[str, list[str]] = defaultdict(list)
    for feature, atoms in {**doc_features, **supplement_features}.items():
        modules = sorted({mod for atom in atoms for mod in atom.get("modules", []) if mod})
        for module in modules or ["GENERAL"]:
            module_features[module].append(feature)

    lines = [
        "# 模块辅助索引",
        "",
        "模块仅用于辅助检索和路由，不作为知识主切分维度。",
        "",
    ]
    for module in MODULE_ORDER:
        features = sorted(set(module_features.get(module, [])), key=feature_sort_key)
        if not features:
            continue
        lines.append(f"## {module} / {MODULE_NAMES.get(module, module)}")
        lines.append("")
        for feature in features:
            primary = "有" if feature in doc_features else "无"
            supplement = "有" if feature in supplement_features else "无"
            lines.append(f"- {display_feature_scope(feature)} | 培训文档 {primary} | 补充层 {supplement}")
        lines.append("")
    return "\n".join(lines)


def render_backend_code_supplement(code_atoms: list[dict]) -> str:
    lines = [
        "# 后台代码实现补充库",
        "",
        "这份文档来自后台代码仓库，用于补接口契约、枚举状态和实现约束。",
        "它不覆盖培训文档主事实，只用于回答“系统实际上怎么实现、受什么条件限制”。",
        "",
    ]
    if not code_atoms:
        lines.append("- 当前未接入后台代码知识。")
        lines.append("")
        return "\n".join(lines)

    groups: dict[str, list[dict]] = defaultdict(list)
    for atom in code_atoms:
        groups[atom.get("primary_module", "GENERAL")].append(atom)

    for module in MODULE_ORDER:
        atoms = groups.get(module, [])
        if not atoms:
            continue
        lines.append(f"## {module} / {MODULE_NAMES.get(module, module)}")
        lines.append("")
        api_atoms = [a for a in atoms if a.get("atom_type") == "api_contract"][:12]
        enum_atoms = [a for a in atoms if a.get("atom_type") == "enum_definition"][:10]
        constraint_atoms = [a for a in atoms if a.get("atom_type") == "impl_constraint"][:12]
        lines.append(f"- 接口契约数：{len([a for a in atoms if a.get('atom_type') == 'api_contract'])}")
        lines.append(f"- 枚举定义数：{len([a for a in atoms if a.get('atom_type') == 'enum_definition'])}")
        lines.append(f"- 实现约束数：{len([a for a in atoms if a.get('atom_type') == 'impl_constraint'])}")
        lines.append("")
        if api_atoms:
            lines.append("### 接口契约样例")
            lines.append("")
            for atom in api_atoms:
                lines.append(f"- {atom.get('rule_text', '')} | {atom.get('repo_relative_path', '')}")
            lines.append("")
        if enum_atoms:
            lines.append("### 枚举样例")
            lines.append("")
            for atom in enum_atoms:
                lines.append(f"- {atom.get('rule_text', '')} | {atom.get('repo_relative_path', '')}")
            lines.append("")
        if constraint_atoms:
            lines.append("### 实现约束样例")
            lines.append("")
            for atom in constraint_atoms:
                lines.append(f"- {atom.get('rule_text', '')} | {atom.get('repo_relative_path', '')}")
            lines.append("")
        lines.append("---")
        lines.append("")
    return "\n".join(lines)


def main() -> None:
    master_atoms = load_jsonl(RAG_DIR / "master_atoms.jsonl")
    backend_code_atoms = load_optional_jsonl(BACKEND_CODE_DIR / "code_atoms.jsonl")
    all_doc_features = group_doc_facts(master_atoms)
    doc_features, retained_doc_features = split_doc_facts(all_doc_features)
    supplement_features = group_supplements(master_atoms)

    OUT_DIR.mkdir(parents=True, exist_ok=True)
    for old_file in OUT_DIR.glob("*"):
        if old_file.is_file():
            old_file.unlink()
    (OUT_DIR / "00_导入说明.md").write_text(render_manifest(doc_features, supplement_features), encoding="utf-8")
    (OUT_DIR / "01_知识库设计原则.md").write_text(render_design_principles(), encoding="utf-8")
    (OUT_DIR / "02_培训文档主事实库.md").write_text(render_primary_facts(doc_features), encoding="utf-8")
    (OUT_DIR / "03_培训文档保留项.md").write_text(render_retained_doc_facts(retained_doc_features), encoding="utf-8")
    (OUT_DIR / "04_Figma与测试补充库.md").write_text(render_supplement_facts(doc_features, supplement_features), encoding="utf-8")
    (OUT_DIR / "05_版本演进.md").write_text(render_version_history(doc_features, supplement_features), encoding="utf-8")
    (OUT_DIR / "06_需求预评审.md").write_text(
        render_review_playbook(doc_features, supplement_features, backend_code_atoms),
        encoding="utf-8",
    )
    (OUT_DIR / "07_模块辅助索引.md").write_text(render_module_index(doc_features, supplement_features), encoding="utf-8")
    if backend_code_atoms:
        (OUT_DIR / "08_后台代码实现补充库.md").write_text(render_backend_code_supplement(backend_code_atoms), encoding="utf-8")

    print(f"primary_features={len(doc_features)}")
    print(f"retained_doc_features={len(retained_doc_features)}")
    print(f"supplement_features={len(supplement_features)}")
    print(f"backend_code_atoms={len(backend_code_atoms)}")
    print(f"output={OUT_DIR.relative_to(BASE_DIR)}")


if __name__ == "__main__":
    main()