AiDOPWarehouse/doc/_gen_delivery_sys_docs.py

# -*- coding: utf-8 -*-
"""生成系统总纲 4 份，并补齐诊断/改善/ChatBI/系统集成的详设与手册；重写已有需求/蓝图。"""
from __future__ import annotations

import shutil
import sys
from pathlib import Path

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.shared import Cm, RGBColor

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

from _gen_s9_diag_impr_int_delivery import (  # noqa: E402
    BASE,
    add_cover,
    add_para,
    heading1,
    heading2,
    heading3,
    set_cell_text,
    shade_cell,
    write_bbp,
    write_brd,
)
from _gen_s9_modules_data import MODULES  # noqa: E402

TMP = HERE / "_tmp_docx_out"
SYS_DIR_NAME = "00-系统总纲"

MODULE_INDEX = [
    ("S0 运营建模", "S0",
     "S0-运营建模-业务需求描述-V0.8.docx",
     "S0-运营建模-业务蓝图设计方案-V0.8.docx",
     "S0运营建模模块详细设计说明书-V1.2.docx",
     "S0-运营建模-用户操作手册-V1.2.docx"),
    ("S1 产销协同", "S1",
     "S1产销协同业务需求描述-V0.4.docx",
     "S1产销协同模块蓝图设计方案-V2.2.docx",
     "S1产销协同模块详细设计说明书-V1.2.docx",
     "S1产销协同模块用户操作手册-V1.2.docx"),
    ("S2 制造协同", "S2",
     "S2制造协同业务需求描述-V0.4.docx",
     "S2制造协同模块蓝图设计方案-V0.4.docx",
     "S2制造协同模块详细设计说明书-V1.2.docx",
     "S2制造协同模块用户操作手册-V1.2.docx"),
    ("S3 供应协同", "S3",
     "S3供应协同业务需求描述-V0.4.docx",
     "S3供应协同模块蓝图设计方案-V0.4.docx",
     "S3供应协同模块详细设计说明书-V1.2.docx",
     "S3供应协同模块用户操作手册-V1.2.docx"),
    ("S4 采购执行", "S4",
     "S4采购执行业务需求描述-V0.4.docx",
     "S4采购执行模块蓝图设计方案-V0.4.docx",
     "S4采购执行模块详细设计说明书-V1.2.docx",
     "S4采购执行模块用户操作手册-V1.2.docx"),
    ("S5 物料仓储", "S5",
     "S5-物料仓储-业务需求描述-V1.2.docx",
     "S5-物料仓储-业务蓝图设计方案-V0.3.docx",
     "S5物料仓储模块详细设计说明书-V1.2.docx",
     "S5-物料仓储-用户操作手册-V1.2.docx"),
    ("S6 生产执行", "S6",
     "S6-生产执行-业务需求描述-V1.2.docx",
     "S6-生产执行-业务蓝图设计方案-V0.3.docx",
     "S6生产执行模块详细设计说明书-V1.2.docx",
     "S6-生产执行-用户操作手册-V1.2.docx"),
    ("S7 成品仓储", "S7",
     "S7-成品仓储-业务需求描述-V1.2.docx",
     "S7-成品仓储-业务蓝图设计方案-V0.3.docx",
     "S7成品仓储模块详细设计说明书-V1.2.docx",
     "S7-成品仓储-用户操作手册-V1.2.docx"),
    ("S8 异常监控", "S8",
     "S8-异常监控-业务需求描述-V1.2.docx",
     "S8-异常监控-业务蓝图设计方案-V0.3.docx",
     "S8异常监控模块详细设计说明书-V1.2.docx",
     "S8-异常监控-用户操作手册-V1.2.docx"),
    ("九宫格智慧运营看板（含 S9 全场关键指标看板）", "S9",
     "九宫格智慧运营看板业务需求描述-V0.4.docx",
     "九宫格智慧运营看板模块蓝图设计方案-V0.4.docx",
     "九宫格智慧运营看板业务需求描述-V0.4.docx",
     "九宫格智慧运营看板模块蓝图设计方案-V0.4.docx"),
    ("运营诊断", "运营诊断",
     "运营诊断业务需求描述-V0.4.docx",
     "运营诊断模块蓝图设计方案-V0.4.docx",
     "运营诊断模块详细设计说明书-V0.4.docx",
     "运营诊断-用户操作手册-V0.4.docx"),
    ("运营改善", "运营改善",
     "运营改善业务需求描述-V0.4.docx",
     "运营改善模块蓝图设计方案-V0.4.docx",
     "运营改善模块详细设计说明书-V0.4.docx",
     "运营改善-用户操作手册-V0.4.docx"),
    ("ChatBI智能报表", "ChatBI",
     "ChatBI智能报表业务需求描述-V0.4.docx",
     "ChatBI智能报表模块蓝图设计方案-V0.4.docx",
     "ChatBI智能报表模块详细设计说明书-V0.4.docx",
     "ChatBI智能报表-用户操作手册-V0.4.docx"),
    ("系统集成（含数据对接服务）", "系统集成",
     "系统集成业务需求描述-V0.4.docx",
     "系统集成模块蓝图设计方案-V0.4.docx",
     "系统集成模块详细设计说明书-V0.4.docx",
     "系统集成-用户操作手册-V0.4.docx"),
]

DDS_UM_KEYS = {
    "运营诊断": ("OD-DDS-001", "OD-UM-001", "运营诊断模块详细设计说明书.docx", "运营诊断-用户操作手册.docx"),
    "运营改善": ("OI-DDS-001", "OI-UM-001", "运营改善模块详细设计说明书.docx", "运营改善-用户操作手册.docx"),
    "ChatBI": ("CBI-DDS-001", "CBI-UM-001", "ChatBI智能报表模块详细设计说明书.docx", "ChatBI智能报表-用户操作手册.docx"),
    "系统集成": ("INT-DDS-001", "INT-UM-001", "系统集成模块详细设计说明书.docx", "系统集成-用户操作手册.docx"),
}

# 详设：业务检查（可写技术词）；手册：同一逻辑的业务说法
LOGIC = {
    "运营诊断": {
        "dds": [
            "进入诊断必须带有模块编码；无模块编码时按默认模块打开，不得报错退出。",
            "诊断结论必须能追溯到指标编码或订单主线；页面展示红/黄/绿，无异常时给良好态或空问题列表。",
            "下钻受当前租户与数据权限约束；无明细时提示空结果，不弹出技术异常。",
            "从九宫格或 S9 全场关键指标看板进入时，保留指标与筛选上下文，避免用户重新选择后对不上。",
            "实时类识别时效以对接数据已刷新为前提；外部系统延迟不记为本模块缺陷。",
            "转改善时必须带上问题名称、模块、指标与目标/实际值，供改善建档使用。",
        ],
        "um": [
            "从九宫格或看板点未达标指标进入诊断，原来看的指标和日期会跟着带过来。",
            "各环节用红黄绿表示是否有问题；全绿或没有问题列表，说明这段时间没有识别到异常。",
            "点开一条问题，可以按订单、物料、供应商等再往下看依据；没有明细时提示暂无数据即可。",
            "确认是问题后，用「转改善」生成改善计划，不要在诊断页直接改业务单据。",
        ],
    },
    "运营改善": {
        "dds": [
            "建档：模块编码、问题名称必填；缺一不可保存。计划号按日生成且租户内唯一。",
            "责任人必须是当前租户有效用户，否则拒绝保存或分派。",
            "状态机：草稿可提交审批；审批中/已通过/执行中/待验证/已关闭不可再提交审批。",
            "开始执行：仅审批通过或已在执行中允许；未审批不得开工。",
            "提交验证：仅执行中或待验证允许；人工结论与自动评价不一致时必须填写理由。",
            "关闭：仅待验证允许；仍有未完成行动项不得关闭。",
            "行动项仅计划负责人、行动项负责人或创建人可改；他人提示无权修改。",
            "到期日前一日提醒、逾期提醒；未关闭且到期日早于今天计为逾期。",
        ],
        "um": [
            "建改善计划时至少要写清问题和所属模块，否则保不住。",
            "责任人必须是本企业里能登录的人，不能随便填一个外面的名字。",
            "写好后先送审批；没批过不能当已经在执行。",
            "执行中才能去做有效性验证；如果您的结论和系统自动评价不一样，必须写明理由。",
            "还有没做完的行动项，计划不能关闭。",
            "只有计划负责人或行动项负责人能改自己的任务进度。",
        ],
    },
    "ChatBI": {
        "dds": [
            "提问先走意图分类，再在当前模块已发布 KPI 中匹配焦点指标；匹配不到则降级为通用说明。",
            "问答基于已计算的运营指标日结果作答，不读取业务单据明细。",
            "大模型不可用或超时，回退本地模板答案，并标明为回退。",
            "回答可带跳转九宫格/模块看板/智慧诊断的动作；跳转须带当前模块上下文。",
            "问答必须带当前租户与数据权限，禁止跨租户取数。",
        ],
        "um": [
            "在九宫格或看板里打开问答窗口，用平常说话问指标即可，也可点建议问题。",
            "现在只能根据已算好的指标作答，不会替您去翻订单明细。",
            "问不到对应指标时，会给提示而不是报错。",
            "网络或智能服务暂时不可用时，仍会给一份基本说明，您可以再问一次或去看板查看。",
            "需要查原因时，按提示进入看板或诊断，不要把问答结果当成已改单。",
        ],
    },
    "系统集成": {
        "dds": [
            "入站：数据源地址/账号、同步对象映射未配齐不得启用任务。",
            "源系统不可达时任务记失败并写日志，不得把失败当成成功。",
            "清洗：字段标准化、空值过滤、异常值标记、编码统一；无法标准化的记录标记后跳过或进异常桶。",
            "出站：业务回写必须进回写队列，禁止无记录直连外写；失败可重试，避免重复入库或丢数。",
            "凭据不得在页面明文回显。",
        ],
        "um": [
            "数据对接服务用来配置从第三方系统取数和回写，一般由实施或运维操作。",
            "没配好地址和对照关系，任务不能启用。",
            "对面系统连不上时，任务会显示失败，可在日志里看原因，不会假装成功。",
            "业务上需要回写第三方系统的操作，会先进入回写队列；失败了可以重试，不要自己在库里改。",
            "打不开数据对接服务菜单时，请联系管理员核对权限。",
        ],
    },
}


def new_doc():
    doc = Document()
    sec = doc.sections[0]
    sec.top_margin = Cm(2)
    sec.bottom_margin = Cm(2)
    sec.left_margin = Cm(2.5)
    sec.right_margin = Cm(2.5)
    return doc


def save_doc(doc: Document, dest: Path):
    from _delivery_docx_polish import force_all_text_black, rebuild_static_toc

    rebuild_static_toc(doc)
    force_all_text_black(doc)
    dest.parent.mkdir(parents=True, exist_ok=True)
    TMP.mkdir(exist_ok=True)
    tmp = TMP / "out.docx"
    doc.save(str(tmp))
    shutil.copy2(tmp, dest)
    print("WROTE", dest)


def add_index_table(doc):
    table = doc.add_table(rows=1 + len(MODULE_INDEX), cols=5)
    table.style = "Table Grid"
    headers = ["模块", "需求描述", "蓝图设计", "详细设计", "操作手册"]
    for c, h in enumerate(headers):
        set_cell_text(table.rows[0].cells[c], h, bold=True, color=RGBColor(0, 0, 0), center=True, size=9)
        shade_cell(table.rows[0].cells[c], "D6E3F0")
    for r, row in enumerate(MODULE_INDEX, 1):
        name, folder, brd, bbp, dds, um = row
        vals = [name, f"{folder}\\{brd}", f"{folder}\\{bbp}", f"{folder}\\{dds}" if not dds.startswith("（") else dds, f"{folder}\\{um}" if not um.startswith("（") else um]
        for c, v in enumerate(vals):
            set_cell_text(table.rows[r].cells[c], v, size=8)


def write_sys_brd():
    doc = new_doc()
    add_cover(doc, "Ai-DOP智慧运营管理系统", "业务需求描述（总纲）", "SYS-BRD-001")
    heading1(doc, "1 文档目的与范围")
    add_para(doc, "本文是全系统业务需求总纲，只写跨模块共性要求，并列出各模块《业务需求描述》文件名。模块个性需求以各模块分册为准。")
    add_para(doc, "系统名称：Ai-DOP智慧运营管理系统。需求基准：项目合同里的技术规范「项目需求」详细实施内容。")

    heading1(doc, "2 建设目标")
    add_para(doc, "建设覆盖运营建模到异常监控的 OTD 全流程协同平台，并以九宫格智慧运营看板作为管理层总览入口。")
    add_para(doc, "S9 全场关键指标看板是九宫格中的全场关键指标页，不是九宫格的上级模块。")
    add_para(doc, "外部系统取数与回写统一走系统集成中的数据对接服务，保证一处配置、全流程共用。")

    heading1(doc, "3 模块与分册索引")
    add_index_table(doc)
    add_para(doc, "九宫格需求/蓝图现存放在交付目录 S9 文件夹，文件名已按「九宫格智慧运营看板」命名。")

    heading1(doc, "4 跨模块共性需求")
    heading2(doc, "4.1 组织与权限")
    add_para(doc, "用户只能看到本租户数据；无菜单权限不展示对应功能。管理层以只读总览为主，业务岗维护本职单据，实施/运维配置数据对接服务。")
    heading2(doc, "4.2 主数据引用")
    add_para(doc, "业务单据引用的物料、客户、供应商、产线等以 S0 运营建模为准。被下游占用的主数据不得删除；业务编码新增时手工录入，进入编辑后锁定。")
    heading2(doc, "4.3 审批与待办")
    add_para(doc, "需要审批的业务（如订单变更、改善计划）走统一审批中心；未通过不得进入下一业务状态。")
    heading2(doc, "4.4 指标口径")
    add_para(doc, "九宫格与 S9 全场关键指标看板、诊断、改善验证使用同一套指标定义；页面不得另写互相冲突的计算公式。")

    heading1(doc, "5 端到端主线")
    add_para(doc, "S0 建好主数据 → S1 评审与承诺交期 → S2 排产 → S3 算料 → S4 采购 → S5 来料与仓储 → S6 生产执行 → S7 成品与发运 → S8 监控异常。")
    add_para(doc, "九宫格汇总各环节是否达标；点 S9 格子看全场关键指标；未达标进入运营诊断；确认问题后进入运营改善闭环。")
    add_para(doc, "ChatBI 嵌在九宫格/看板中，用自然语言问已算好的指标，不替代各模块单据操作。")

    heading1(doc, "6 数据对接服务（系统集成）")
    add_para(doc, "数据对接服务负责与第三方系统的取数、清洗和回写。业务人员日常不在此配置，由实施或运维维护。")
    add_para(doc, "入站失败必须可见；回写必须留队列记录。具体页面与检查见《系统集成业务需求描述》。")

    heading1(doc, "7 编号与追溯")
    add_para(doc, "需求 REQ-Sn-nnn、功能 FUNC-Sn-nnn、测试 TC-Sn-nnn，通过各模块三联对照表串联。禁止改写已分配编号。")

    heading1(doc, "8 性能要求")
    add_para(doc, "以下性能要求依据委托开发合同相关条款，仅在本总纲列示，各模块分册不再重复。")
    add_para(doc, "• 常规页面加载、普通查询及常规操作响应不超过 30 秒；复杂查询、多表关联、大数据量列表、看板多图联动不超过 60 秒。")
    add_para(doc, "• 超大数据量导出、全量重算、智能问答按异步任务处理，任务状态可查询。")
    add_para(doc, "• 常规业务接口平均响应不超过 30 秒；复杂聚合接口平均响应不超过 60 秒。")
    add_para(doc, "• 最大支持约 1000 人同时在线、约 400 人并发操作。")
    add_para(doc, "• 主数据及业务单据状态同步目标延迟不超过 5 分钟；指标日批按日调度完成。")
    add_para(doc, "• 全年可用性不低于 99%；接口调用成功率不低于 99%（第三方拒绝与网络故障除外）。")
    save_doc(doc, BASE / SYS_DIR_NAME / "SYS-业务需求描述-总纲.docx")


def write_sys_bbp():
    doc = new_doc()
    add_cover(doc, "Ai-DOP智慧运营管理系统", "业务蓝图设计方案（总纲）", "SYS-BBP-001")
    heading1(doc, "1 目标和宗旨")
    add_para(doc, "把合同范围内的模块连成一条可运营的蓝图：主数据统一、单据可追溯、指标可看、问题可改。")
    add_para(doc, "九宫格是运营总览；S9 全场关键指标看板是九宫格里的全场指标页。")

    heading1(doc, "2 总体业务路径")
    add_para(doc, "数据对接服务采集/回写 → 各业务模块处理单据 → 指标日批计算 → 九宫格总览 →（可选）S9 全场关键指标看板 → 智慧诊断 → 改善计划审批与验证。")

    heading1(doc, "3 跨模块流程规则")
    add_para(doc, "• 下游引用上游主数据与单据状态，不得跳过必经节点（例如不合格按合格入库）。")
    add_para(doc, "• 指标只读展示日批结果；改数在业务模块或对接任务中完成，不在看板上改。")
    add_para(doc, "• 诊断不改单；改善改的是整改任务，不是直接改历史单据。")

    heading1(doc, "4 系统接口原则")
    add_para(doc, "外部系统一律经数据对接服务：直连库或 HTTP API。出站回写进队列。凭据不落页面明文。")

    heading1(doc, "5 各模块蓝图索引")
    add_index_table(doc)
    save_doc(doc, BASE / SYS_DIR_NAME / "SYS-业务蓝图设计方案-总纲.docx")


def write_sys_dds():
    doc = new_doc()
    add_cover(doc, "Ai-DOP智慧运营管理系统", "详细设计说明书（总纲）", "SYS-DDS-001")
    heading1(doc, "1 文档概述")
    heading2(doc, "1.1 编写目的")
    add_para(doc, "说明跨模块技术架构与必须统一遵守的业务检查。模块内表结构、页面与接口以各模块详细设计说明书为准。")
    heading2(doc, "1.2 设计范围")
    add_para(doc, "覆盖 S0～S8、九宫格（含 S9 全场关键指标看板）、运营诊断、运营改善、ChatBI、系统集成。")

    heading1(doc, "2 总体设计")
    heading2(doc, "2.1 技术栈")
    add_para(doc, "后端 .NET / Admin.NET；前端 Vue3 + Element Plus；数据库 MySQL 8.0（utf8mb4）；可选 Redis。运行环境见合同附件《项目运行环境及责任边界清单》。")
    heading2(doc, "2.2 总体架构")
    add_para(doc, "业务服务处理各模块单据；数据对接服务完成贴源采集、标准清洗、明细汇总、指标日批与出站回写队列；看板/诊断/ChatBI 只读消费指标与明细。")
    heading2(doc, "2.3 模块划分")
    add_para(doc, "S0 主数据；S1～S8 业务执行；九宫格与 S9 全场关键指标看板为展示；诊断与改善为闭环；系统集成承载数据对接服务。")

    heading1(doc, "3 跨模块业务检查（必须统一）")
    add_para(doc, "• 所有读写带租户条件；禁止把租户写成固定 0 或跨租户查询。")
    add_para(doc, "• 主数据删除前检查占用；编码编辑态锁定。")
    add_para(doc, "• 审批未通过不得进入下一状态。")
    add_para(doc, "• 指标口径以运营指标主数据为准，看板不得硬编码另一套公式。")
    add_para(doc, "• 出站必须进回写队列；入站失败必须落日志。")
    heading2(doc, "3.1 各业务模块主要检查（摘要）")
    bullets = [
        "S0：编码手填且编辑后不可改；被引用不可删。",
        "S1：交期评审看产能与齐套；交付变更需审批；发货需成品可发。",
        "S2：排程受工作日历与产能约束；冻结范围内已执行计划不随意作废。",
        "S3：净需求考虑库存与在途；齐套结论与库存口径一致。",
        "S4：采购数量来自需求；收货必须经过约定质检节点。",
        "S5：检验不合格不得按合格入库；现存查询以对接后的库存为准。",
        "S6：报工与工单未完数量相符；异常提报后按等级限时响应。",
        "S7：入库关联工单与检验；出库关联发货通知。",
        "S8：紧急异常限时响应；无处理结果不得闭环。",
        "九宫格 / S9：无数据给空态；未达标可下钻诊断。",
    ]
    for b in bullets:
        add_para(doc, "• " + b)

    heading1(doc, "4 数据对接服务设计")
    add_para(doc, "分层：贴源层保存外部原样；标准层统一编码与空值；明细层按订单/工单/物料汇总；指标层按日计算 KPI。")
    add_para(doc, "通道：数据库直连、HTTP API；定时或实时。新增一套外部系统以可视化配置为目标，避免大量改代码。")
    add_para(doc, "监控：任务日志、动作日志、出站队列状态（待发送/成功/失败/重试）。")
    add_para(doc, "数据对接服务操作页为 FUNC-S9-010～016，用于数据源、同步配置、任务与动作日志、出站回写队列。")

    heading1(doc, "5 安全与多租户")
    add_para(doc, "认证走平台登录。接口鉴权，ChatBI 问答必须带当前租户。")

    heading1(doc, "6 SaaS 部署与运维设计")
    heading2(doc, "6.1 部署模式和环境")
    add_para(doc, "Ai-DOP智慧运营管理系统采用统一 SaaS 多租户部署，不按模块单独建库；开发、预发、生产环境配置隔离。")
    add_para(doc, "系统部署于合同约定的服务器、数据库与网络环境；运行环境见合同附件《项目运行环境及责任边界清单》。客户端使用 Chrome 或 Edge 近两个正式版访问。")
    heading2(doc, "6.2 部署架构")
    add_para(doc, "采用容器化部署：反向代理 + 前端静态资源 + .NET API + MySQL + Redis。各业务模块随平台一同发布。")
    heading2(doc, "6.3 租户开通和初始化")
    add_para(doc, "新租户开通后初始化组织、角色与菜单权限；业务数据按租户隔离，禁止跨租户可见。")
    heading2(doc, "6.4 发布、升级和回滚")
    add_para(doc, "发版随平台版本号发布；升级失败按平台回滚策略回退至上一可用版本，保留业务数据。")
    heading2(doc, "6.5 监控、备份和恢复")
    add_para(doc, "按平台策略监控运行状态与任务失败；数据库按平台策略备份，恢复后核对关键业务数据。")
    add_para(doc, "部署与运维为跨模块共性内容，各模块分册不再单列。")

    heading1(doc, "7 各模块详设索引")
    add_index_table(doc)
    save_doc(doc, BASE / SYS_DIR_NAME / "SYS-详细设计说明书-总纲.docx")


def write_sys_um():
    doc = new_doc()
    add_cover(doc, "Ai-DOP智慧运营管理系统", "用户操作手册（总纲）", "SYS-UM-001")
    heading1(doc, "1 登录与工作台")
    add_para(doc, "在浏览器打开系统地址，输入账号密码后进入工作台。左侧是功能菜单，顶部是已打开的页签。")
    add_para(doc, "请使用 Chrome 或 Edge 近两个正式版。")
    heading1(doc, "2 通用操作")
    add_para(doc, "多数列表都是：上面筛选，中间表格，下面翻页。点查询看结果，点重置清空条件。")
    add_para(doc, "新增或编辑后点保存。删除前会再确认一次；如果这条已经被后面的业务用到，系统不会让您删。")
    add_para(doc, "需要审批的单据，提交后到「审批中心」处理；没通过之前，下一环节做不了。")
    heading1(doc, "3 从哪里看全局")
    add_para(doc, "日常先看九宫格：一屏看各模块是否达标。要看全场关键指标，点九宫格里的 S9。")
    add_para(doc, "某个指标不好，点进去做诊断；确认是问题再开改善计划。问数可以用看板上的问答窗口，它只解释已有指标，不会替您改单。")
    heading1(doc, "4 跨模块使用注意")
    add_para(doc, "先在运营建模里把物料、客户、产线等基础资料维护好，后面订单和排产才找得到。")
    add_para(doc, "各模块颜色和数字应能对上；对不上时先看筛选日期是不是一致，再找实施核对数据对接服务是否已跑完。")
    heading1(doc, "5 各模块操作手册")
    add_index_table(doc)
    add_para(doc, "具体按钮和字段以各模块手册为准。本总纲只讲共用习惯和先后顺序。")
    save_doc(doc, BASE / SYS_DIR_NAME / "SYS-用户操作手册-总纲.docx")


def write_module_dds(key: str, mod: dict):
    no, _um_no, dds_name, _um_name = DDS_UM_KEYS[key]
    doc = new_doc()
    add_cover(doc, mod["module_title"], "详细设计说明书", no)
    heading1(doc, "1 文档概述")
    heading2(doc, "1.1 编写目的")
    add_para(doc, f"说明「{mod['module_title']}」的功能处理与业务检查，供开发、测试与验收对照。")
    heading2(doc, "1.2 设计范围")
    add_para(doc, f"报价范围：{mod['quote_scope']}。共性架构见《SYS-详细设计说明书-总纲》。")
    if mod.get("intro"):
        add_para(doc, mod["intro"])

    heading1(doc, "2 总体设计")
    add_para(doc, "本模块前后端与权限模型同总纲。下列功能按实际菜单实现。")

    heading1(doc, "3 功能详细设计")
    heading2(doc, "3.1 模块级业务检查逻辑")
    add_para(doc, "下列检查对全模块生效，实施与测试按此拦截。")
    for t in LOGIC[key]["dds"]:
        add_para(doc, "• " + t)
    features = [f for f in mod["features"] if f.get("impl_status") != "未实现"]
    for i, feat in enumerate(features, 2):
        heading2(doc, f"3.{i} {feat['name']}（{feat['func']}）")
        heading3(doc, "业务流程")
        for t in feat["biz_desc"]:
            add_para(doc, t)
        heading3(doc, "功能处理")
        for t in feat["func_desc"]:
            add_para(doc, t)
        heading3(doc, "本功能规则")
        for t in feat.get("rules", []):
            add_para(doc, "• " + t)
        heading3(doc, "页面与验证")
        add_para(doc, f"路径：{feat['path']}。")

    heading1(doc, "4 接口设计")
    for feat in features:
        add_para(doc, f"{feat['name']}：{feat['interfaces']}")

    heading1(doc, "5 安全与多租户")
    add_para(doc, "查询与写操作必须带当前租户。改善、对接配置等写操作校验操作者权限。")
    save_doc(doc, BASE / mod["folder"] / dds_name)


def write_module_um(key: str, mod: dict):
    _dds_no, no, _dds_name, um_name = DDS_UM_KEYS[key]
    doc = new_doc()
    add_cover(doc, mod["module_title"], "用户操作手册", no)
    heading1(doc, "1 写给谁看")
    add_para(doc, "给业务人员和管理层看。登录、筛选、保存等通用操作见《SYS-用户操作手册-总纲》，这里只写本模块怎么用。")
    if mod.get("intro"):
        add_para(doc, mod["intro"])

    heading1(doc, "2 先做什么")
    if key == "运营诊断":
        add_para(doc, "建议先在九宫格里看到未达标，再点进来。也可以从菜单直接打开智慧诊断。")
    elif key == "运营改善":
        add_para(doc, "建议从诊断页的问题生成改善计划，这样问题和指标会对得上。")
    elif key == "ChatBI":
        add_para(doc, "打开九宫格或任一模块看板，点问答窗口即可，没有单独菜单也不影响使用。")
    else:
        add_para(doc, "数据对接服务由实施或运维配置。业务人员一般只需知道：数没来、回写失败时找运维查日志。")

    heading1(doc, "3 主要操作")
    for i, feat in enumerate([f for f in mod["features"] if f.get("impl_status") != "未实现"], 1):
        heading2(doc, f"3.{i} {feat['name']}")
        for t in feat["biz_desc"]:
            add_para(doc, t)

    heading1(doc, "4 系统会拦下来的情况")
    add_para(doc, "下面这些是本模块最常见的检查，用业务话说明「什么时候做不成」。")
    for t in LOGIC[key]["um"]:
        add_para(doc, "• " + t)

    heading1(doc, "5 和别的模块怎么配合")
    if key == "运营诊断":
        add_para(doc, "上看九宫格和 S9 全场关键指标，下转改善计划。诊断本身不改订单、不改库存。")
    elif key == "运营改善":
        add_para(doc, "计划要挂在诊断问题上。关闭前先做完行动项并完成验证。")
    elif key == "ChatBI":
        add_para(doc, "问答只解释指标。要改业务，请回到对应的 S1～S8 功能。")
    else:
        add_para(doc, "对接跑完后，S0～S8 和九宫格才能看到数。回写队列处理的是本系统写回第三方系统的单据。")
    save_doc(doc, BASE / mod["folder"] / um_name)


def rewrite_existing_brd_bbp():
    for key in ("S9", "运营诊断", "运营改善", "ChatBI", "系统集成"):
        mod = MODULES[key]
        folder = BASE / mod["folder"]
        write_brd(mod, folder / mod["brd_name"])
        write_bbp(mod, folder / mod["bbp_name"])
    old_s9 = [
        BASE / "S9" / "S9运营指标与智慧看板业务需求描述.docx",
        BASE / "S9" / "S9运营指标与智慧看板模块蓝图设计方案.docx",
    ]
    for p in old_s9:
        if p.exists() and p.name != MODULES["S9"]["brd_name"] and p.name != MODULES["S9"]["bbp_name"]:
            p.unlink()
            print("REMOVED", p)


def main():
    BASE.mkdir(parents=True, exist_ok=True)
    rewrite_existing_brd_bbp()
    write_sys_brd()
    write_sys_bbp()
    write_sys_dds()
    write_sys_um()
    for key in ("运营诊断", "运营改善", "ChatBI", "系统集成"):
        write_module_dds(key, MODULES[key])
        write_module_um(key, MODULES[key])
    print("DONE")


if __name__ == "__main__":
    main()