AiDOPWarehouse/doc/_gen_agent_task_plan_docx.py

"""生成《Ai-DOP 智能体建设任务计划》Word 文档（V1.0）。

基于《Ai-DOP 本体驱动智能体建设方案》(7)(1) 的第七章分阶段实施计划（P0~P4）、
6.3 节各域现状判定与首要补齐项、5.5~5.9 试点与场景示例，
输出可执行的任务分解（WBS）、里程碑时间线、依赖关系与质量控制闸门。
"""

from __future__ import annotations

import os

from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
from docx.oxml.ns import qn
from docx.shared import Cm, Pt

BASE = os.path.dirname(os.path.abspath(__file__))
OUT = os.path.join(BASE, "plan", "Ai-DOP智能体建设任务计划.docx")

doc = Document()
sec = doc.sections[0]
sec.page_width = Cm(21.0)
sec.page_height = Cm(29.7)
sec.top_margin = Cm(2.54)
sec.bottom_margin = Cm(2.54)
sec.left_margin = Cm(2.4)
sec.right_margin = Cm(2.4)


def set_run_font(run, name_cn="宋体", name_en="Times New Roman", size=12, bold=False, color=None):
    run.font.name = name_en
    run._element.rPr.rFonts.set(qn("w:eastAsia"), name_cn)
    run.font.size = Pt(size)
    run.bold = bold
    if color is not None:
        run.font.color.rgb = color


def style_normal():
    style = doc.styles["Normal"]
    style.font.name = "Times New Roman"
    style.font.size = Pt(12)
    style._element.rPr.rFonts.set(qn("w:eastAsia"), "宋体")
    pf = style.paragraph_format
    pf.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE
    pf.space_after = Pt(6)


def add_title(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(12)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 18, True)


def add_subtitle(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(12)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 14, True)


def add_meta(text: str):
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    p.paragraph_format.space_after = Pt(4)
    run = p.add_run(text)
    set_run_font(run, "宋体", "Times New Roman", 10.5)


def add_h1(text: str):
    p = doc.add_paragraph()
    p.paragraph_format.space_before = Pt(14)
    p.paragraph_format.space_after = Pt(8)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 14, True)


def add_h2(text: str):
    p = doc.add_paragraph()
    p.paragraph_format.space_before = Pt(10)
    p.paragraph_format.space_after = Pt(6)
    run = p.add_run(text)
    set_run_font(run, "黑体", "SimHei", 12, True)


def add_body(text: str, indent=True):
    p = doc.add_paragraph()
    p.paragraph_format.first_line_indent = Pt(24) if indent else Pt(0)
    p.paragraph_format.space_after = Pt(6)
    run = p.add_run(text)
    set_run_font(run, "宋体", "Times New Roman", 12)


def add_bullet(text: str, ordered=False, index=None):
    p = doc.add_paragraph()
    p.paragraph_format.left_indent = Cm(0.74)
    p.paragraph_format.first_line_indent = Pt(0)
    p.paragraph_format.space_after = Pt(3)
    prefix = f"{index}." if ordered else "•"
    run = p.add_run(f"{prefix} {text}")
    set_run_font(run, "宋体", "Times New Roman", 12)


def add_table(headers, rows, col_widths=None):
    table = doc.add_table(rows=1 + len(rows), cols=len(headers))
    table.style = "Table Grid"
    table.autofit = True

    for i, h in enumerate(headers):
        cell = table.rows[0].cells[i]
        cell.text = ""
        p = cell.paragraphs[0]
        p.alignment = WD_ALIGN_PARAGRAPH.CENTER
        run = p.add_run(h)
        set_run_font(run, "宋体", "Times New Roman", 10.5, True)
        tc = cell._tc
        tcPr = tc.get_or_add_tcPr()
        shd = tcPr.makeelement(qn("w:shd"), {qn("w:val"): "clear", qn("w:fill"): "D9E2F3"})
        tcPr.append(shd)

    for ri, row in enumerate(rows):
        for ci, val in enumerate(row):
            cell = table.rows[ri + 1].cells[ci]
            cell.text = ""
            p = cell.paragraphs[0]
            run = p.add_run(str(val))
            set_run_font(run, "宋体", "Times New Roman", 10.5)

    if col_widths is not None:
        table.autofit = False
        for ci, w in enumerate(col_widths):
            for row in table.rows:
                row.cells[ci].width = Cm(w)
    return table


style_normal()

# ============ 封面信息 ============
add_title("Ai-DOP 智能体建设任务计划")
add_subtitle("——基于《Ai-DOP 本体驱动智能体建设方案》的落地执行分解")
add_meta("文档版本：V1.0　　编制日期：2026 年 10 月")
add_meta("依据方案：《Ai-DOP 本体驱动智能体建设方案》(7)(1)（第七章分阶段实施计划、6.3 节需求就绪度判定、5.5~5.9 试点与场景示例）")

# ============ 一、任务计划总览 ============
add_h1("一、任务计划总览")
add_h2("1.1 建设总纲")
add_body(
    "本任务计划以方案「零旁路增量」为总纲：本体四要素以 4 张配置表承载，四类职能智能体（数据感知、关系推理、"
    "风险预警、执行调度）实现为插件 Job 目录下的独立巡检 Job 与一个 LLM 编排 Planner，写类动作一律经现有审批流"
    "（IFlowBizHandler）人工确认后落库；全部新能力缺省关闭、可评审、可回退，不阻塞现有业务发版。"
)
add_body(
    "按方案第七章，建设分 P0~P4 五阶段：P0~P3 合计约 11 周，P4 为持续扩展期；各阶段均可独立交付与回退。"
    "P4 业务域补齐顺序按「数据就绪度 × 规则确定性」排序（与模块重要性无关）：S4 采购执行 → S5 物料仓储 → "
    "S3 完善 → S7 成品仓储外物流 → S6 生产执行 → S1/S2 完善 → S8/S9 字典与 KPI 基线。"
)
add_h2("1.2 阶段里程碑总表")
add_table(
    ["阶段", "建设内容", "工期", "交付物", "验收闸门（通过后方可进入下一阶段）"],
    [
        ["P0 底座", "4 张本体登记表 + 工具注册闸门 + 前端登记页 + 价值基线锁定", "约 2 周",
         "① DDL 与实体 ② 登记维护页面 ③ 工具注册闸门服务 ④ 基线校准报告",
         "登记、启停、租户隔离生效；未启用租户行为不变；矩阵 A 对象/规则/工具起步值完成代码与业务基线校准；价值 KPI 以一个月历史数据锁定基线"],
        ["P1 自动预警", "四规则巡检引擎 + 数据感知/风险预警 Job + S8 对接", "约 3 周",
         "① 巡检 Job ② 规则配置页 ③ 预警通知链路",
         "规则命中即登记 S8 异常并通知责任人；预警结论可核对（附触发数据位置）"],
        ["P2 自动分析", "关系推理智能体 + Planner + 证据链 + ChatBI 增强 + 齐套四量问答试点", "约 3 周",
         "① Planner 服务 ② 证据链报告 ③ ChatBI 带证据回答 ④ 试点用例",
         "根因候选均带证据（表名/字段/记录号）；无证据不下结论；试点问答返回四量与欠料并附证据"],
        ["P3 自动优化", "执行调度智能体 + 建议审批 + 有效性验证闭环", "约 3 周",
         "① 建议起草服务 ② 闭环流程 ③ 场景示例落地",
         "建议经审批方可执行；执行结果经有效性验证回写规则库"],
        ["P4 扩展", "业务域补齐 + 更多场景规则沉淀 + 登记表扩展", "持续",
         "① 各域需求卡 ② 场景规则包 ③ 登记数据",
         "每场景均有可复盘证据与收益统计"],
    ],
    col_widths=[1.7, 5.0, 1.4, 3.4, 4.7],
)
add_h2("1.3 排期前置条件（三项硬闸门）")
add_bullet("需求卡闸门：各业务域按「一页需求卡」C0~C13 十四项标准写清（最多 3 页）；C1（业务目标与 KPI）、C5（规则与算法）、C11（验收与评测）任一缺失，评审直接判定「不具备开发条件」，不进入开发排期。", ordered=True, index=1)
add_bullet("就绪度销项：对照方案 6.3 节矩阵 B，9 个域六维中「缺失/部分」项逐项销项——当前仅 S2 验收评测、S7 KPI 为「缺失」，其余六维均「部分」以上；各域按 6.3 节「首要补齐项」补文档与评测后方可排期。", ordered=True, index=2)
add_bullet("基线闸门：价值量化目标（方案第九章）为示例值，P0 阶段以一个月历史数据锁定基线后方可进入验收；无基线的 KPI 不写入验收表。", ordered=True, index=3)

# ============ 二、任务分解 ============
add_h1("二、任务分解（WBS）")
add_body(
    "以下按阶段列出全部任务。角色缩写：域Owner=各业务域负责人（登记口径、验收责任）；后端=平台研发后端；"
    "前端=平台研发前端；测试=质量与评测；数据=数据中台与 KPI 口径。任务编号规则：T{阶段序号}.{任务序号}。"
)
add_h2("2.1 P0 底座（约 2 周）")
add_table(
    ["编号", "任务", "工作内容", "交付物", "前置依赖", "工期", "角色", "验收口径"],
    [
        ["T0.1", "四张本体登记表落地", "aidop_agent_entity/relation/action_chain/tool_registry 四表 DDL 与实体，含 tenant_id、status_dict、attr_spec_json、自动化等级/幂等键/回滚方式字段，SqlSugar CodeFirst 挂入插件 Entity", "DDL + 实体 + 种子数据", "—", "4 天", "后端", "四表可在现有业务库创建；全部带 tenant_id；初始缺省关闭"],
        ["T0.2", "前端登记维护页", "实体/关联/动作链/工具四类登记页（增改查、启停、版本化），登记 FUNC 功能码后注入菜单（侧栏短标方案）", "登记维护页面", "T0.1", "4 天", "前端", "四类对象可登记、启停；菜单可访问；按租户隔离"],
        ["T0.3", "工具注册闸门服务", "工具显式注册（tool_code/语义描述/调用目标），Planner 调用前强制校验；未注册工具一律不可调用", "闸门服务 + 单元测试", "T0.1", "3 天", "后端", "未注册工具调用被拦截；注册表附业务语义描述"],
        ["T0.4", "租户级启用开关", "租户级灰度开关与规则启用配置（缺省关闭，逐租户开启）", "开关配置能力", "T0.1", "2 天", "后端", "未启用租户行为与当前版本完全一致"],
        ["T0.5", "矩阵 A 起步值基线校准", "按代码基线（各域服务/Job/规则）与业务基线校准矩阵 A 的对象/规则/工具起步值", "基线校准报告", "—", "3 天", "后端+域Owner", "9 个域起步值均经代码证据与业务确认"],
        ["T0.6", "价值 KPI 基线锁定", "以一个月历史数据锁定预警时效、分析时效、人工干预率、响应时间、交付准时率等基线", "KPI 基线表", "—", "与 P0 并行", "数据", "每个验收 KPI 均有基线值；无基线 KPI 不写入验收"],
    ],
    col_widths=[1.1, 2.3, 4.6, 2.1, 1.3, 1.2, 1.4, 2.4],
)
add_h2("2.2 P1 自动预警（约 3 周）")
add_table(
    ["编号", "任务", "工作内容", "交付物", "前置依赖", "工期", "角色", "验收口径"],
    [
        ["T1.1", "四规则巡检引擎", "时效性/一致性/完整性/阈值四类规则引擎，按租户、按对象配置，缺省关闭；规则暂以代码/JSON 承载", "巡检引擎 + 单元测试", "T0.3", "6 天", "后端", "四类规则均可配置、可启停；命中即产出预警候选"],
        ["T1.2", "数据感知 Job", "周期扫描数据新鲜度/一致性/完整性，产出异常事实写入动作日志与预警候选队列；错峰调度", "巡检 Job（挂 Job/ 目录）", "T1.1", "4 天", "后端", "与现有 22 个 Job 同范式挂入调度；错峰执行不影响在线业务"],
        ["T1.3", "风险预警 Job + S8 对接", "预警分级（轻微/一般/严重）后登记 ado_s8_exception 并通知责任人；预警结论附触发数据位置", "预警链路", "T1.1", "5 天", "后端", "规则命中即登记 S8 异常并通知；结论可核对、可追溯"],
        ["T1.4", "规则配置页", "四类规则的租户级配置界面（对象、阈值、启停、巡检窗口）", "配置页", "T1.1", "4 天", "前端", "配置即时生效；阈值可调"],
        ["T1.5", "预警分级字典与阈值基线", "确定轻微/一般/严重分级标准与各域阈值基线、责任人映射", "分级字典 + 基线配置", "—", "与 T1.1 并行", "域Owner+数据", "分级标准经业务确认；责任人可寻址"],
    ],
    col_widths=[1.1, 2.3, 4.6, 2.1, 1.3, 1.2, 1.4, 2.4],
)
add_h2("2.3 P2 自动分析（约 3 周）")
add_table(
    ["编号", "任务", "工作内容", "交付物", "前置依赖", "工期", "角色", "验收口径"],
    [
        ["T2.1", "关系推理智能体", "沿实体—关联—动作链定位候选根因（如工单延迟→车间资源冲突→运输卡点）", "推理服务 + 单元测试", "T0.1", "5 天", "后端", "推理路径沿登记链路展开；候选根因可枚举"],
        ["T2.2", "LLM 编排 Planner", "复用 DeepSeekChatClient（纯 JSON 补全）做语义整理与候选排序；推理骨架由登记表与证据校验代码决定", "Planner 服务", "T2.1", "6 天", "后端", "LLM 不产生无证据结论；输出结构化根因报告（结论+证据链+置信度）"],
        ["T2.3", "证据校验服务", "每个候选根因必须落到具体证据（表名、字段、记录号）；证据不足的候选剔除", "证据校验服务", "T2.1", "4 天", "后端", "无证据候选 100% 剔除；证据可反查"],
        ["T2.4", "ChatBI 增强", "问数答案附带证据链，可回答性校验", "ChatBI 带证据回答", "T2.2", "4 天", "后端+前端", "答案附证据位置；证据不足时明示"],
        ["T2.5", "齐套四量问答试点", "注册「齐套四量查询」聚合工具（LLM 不直连数据库）；占用单独取数 ic_item_stockoccupy/srm_po_occupy；欠料口径直接引用 lack_qty 权威列", "试点用例 + 评测报告", "T2.2", "5 天", "后端+测试", "问答返回在库/在检/在途/占用四量与欠料，附证据表名与记录号（方案 5.5）"],
    ],
    col_widths=[1.1, 2.3, 4.6, 2.1, 1.3, 1.2, 1.4, 2.4],
)
add_h2("2.4 P3 自动优化（约 3 周）")
add_table(
    ["编号", "任务", "工作内容", "交付物", "前置依赖", "工期", "角色", "验收口径"],
    [
        ["T3.1", "执行调度智能体", "依据分析结论与工具注册表起草改善建议（重跑 MRP、调整排产优先级、补充采购申请等）", "建议起草服务", "T2.2", "5 天", "后端", "建议含动作、目标对象与预期效果；只起草不落库"],
        ["T3.2", "建议审批对接", "建议进入现有审批流（IFlowBizHandler），审批人守卫校验（ImprovementApproverGuard 范式）；未审批不落库", "审批流对接", "T3.1", "5 天", "后端", "未经审批的建议无法执行；审批人解析复用现有守卫"],
        ["T3.3", "有效性验证回写", "执行结果经有效性验证（ImprovementEffectiveness 范式），验证通过回写规则库与登记表", "闭环验证服务", "T3.2", "4 天", "后端", "验证结果可复盘；通过后规则库生效"],
        ["T3.4", "场景示例落地（按序）", "依次落地方案 5.6 交期提前影响分析、5.7 理论/实际产能与建议人数、5.8 物料交期与自动选供、5.9 安全库存/补货建议", "4 个场景用例", "T3.2", "8 天（与 T3.3 并行）", "后端+域Owner", "每场景数据来源均对齐现有代码（见方案 5.6~5.9 数据表）"],
    ],
    col_widths=[1.1, 2.3, 4.6, 2.1, 1.3, 1.2, 1.4, 2.4],
)
add_h2("2.5 P4 扩展（持续）")
add_table(
    ["编号", "任务", "工作内容", "交付物", "前置依赖", "工期", "角色", "验收口径"],
    [
        ["T4.1", "业务域按序补齐", "按 S4→S5→S3→S7→S6→S1/S2→S8/S9 顺序补齐各域智能体；S6 依赖车间实时数据，宜在 S4/S5 跑通 L2 闭环后启动", "各域智能体能力", "该域需求卡评审通过", "每域约 3~4 周", "后端+域Owner", "该域需求卡 C0~C13 全项验收达标"],
        ["T4.2", "需求卡编写—评审循环", "每域「一页需求卡」编写→评审→开发→验收闭环；6.3 节矩阵 B 的「缺失/部分」逐项销项", "各域需求卡 + 评审记录", "—", "持续", "域Owner", "C1/C5/C11 全部达标；销项清单更新"],
        ["T4.3", "场景规则沉淀与登记表扩展", "新场景规则包沉淀；LLM 半自动抽取生成登记草稿，人工确认后生效并版本化留痕", "规则包 + 登记数据", "T4.1", "持续", "后端+域Owner", "每场景均有可复盘证据与收益统计"],
    ],
    col_widths=[1.1, 2.3, 4.6, 2.1, 1.3, 1.2, 1.4, 2.4],
)

# ============ 三、业务域需求卡补齐任务 ============
add_h1("三、各业务域需求卡补齐任务（排期输入）")
add_body(
    "以下任务与 P0~P2 并行推进，是 P4 各域开发排期的输入；依据方案 6.3 节「各域现状判定与首要补齐项」。"
    "S4 采购执行智能体需求卡（AGT-S4-001）为完整参照示例，其余各域按同一标准编写。"
)
add_table(
    ["业务域", "首要补齐内容（依据方案 6.3）", "责任人（域Owner）", "输出", "评审闸门"],
    [
        ["S1 产销协同", "预测粒度与准确率目标、库存计划对象、给 S2 的输入契约与冻结期", "销售运营+计划部", "S1 需求卡 v1.0", "C1/C5/C11 达标"],
        ["S2 制造协同", "约束清单（设备/模具/技能/换型）、冻结期、求解时限与结果可解释；验收评测资产空缺需补", "制造部+计划部", "S2 需求卡 v1.0", "C1/C5/C11 达标 + 测试资产"],
        ["S3 供应协同", "替代料规则、与 S4 的 PR/PO/ASN 边界、IQC 口径", "采购部+物控", "S3 需求卡 v1.0", "C1/C5/C11 达标"],
        ["S4 采购执行", "按 AGT-S4-001 补写全量需求卡（规则/动作均已取证，补目标与评测文档化）", "采购部", "S4 需求卡定稿", "参照示例卡验收底线"],
        ["S5 物料仓储", "作业对象（收货/上架/拣料/盘点）、批次与库位、盘点差异处理需求卡化", "仓储+物控", "S5 需求卡 v1.0", "C1/C5/C11 达标"],
        ["S6 生产执行", "报工与质量对象、停机原因树、工艺参数可调边界需求卡化", "车间+质量", "S6 需求卡 v1.0", "C1/C5/C11 达标"],
        ["S7 成品仓储外物流", "发运对象、承运与路线、签收 POD、退货需求卡化；KPI 缺失待补", "物流部", "S7 需求卡 v1.0 + KPI 注册", "C1/C5/C11 达标 + KPI 证据"],
        ["S8 异常管理", "体征字典与阈值基线、分级标准、S1~S7 责任人矩阵", "运营管理部", "S8 字典与基线配置", "分级标准经业务确认"],
        ["S9 绩效管理", "KPI 字典（公式/口径/数据源）、绩效树、回写白名单", "运营+财务", "S9 KPI 字典 v1.0", "口径经数据层取证确认"],
    ],
    col_widths=[1.7, 5.6, 2.1, 2.6, 3.2],
)

# ============ 四、里程碑与时间线 ============
add_h1("四、里程碑与时间线")
add_h2("4.1 关键里程碑")
add_table(
    ["里程碑", "时点", "内容", "通过标准"],
    [
        ["M0 底座验收", "P0 末（第 2 周末）", "四表 + 登记页 + 工具闸门 + 基线锁定", "P0 验收口径全项通过"],
        ["M1 预警试点验收", "P1 末（第 5 周末）", "四规则巡检 + S8 对接上线，选 1 域灰度", "规则命中即登记 S8 并通知"],
        ["M2 分析试点验收", "P2 末（第 8 周末）", "齐套四量问答试点验收", "试点问答返回四量与欠料并附证据"],
        ["M3 优化闭环验收", "P3 末（第 11 周末）", "建议—审批—执行—验证闭环 + 4 场景落地", "建议经审批方可执行；验证回写规则库"],
        ["M4 首个域全闭环", "P4 内（约第 15~16 周）", "S4 采购执行域 L2 全闭环首个案例", "AGT-S4-001 验收底线全项达标"],
    ],
    col_widths=[2.8, 2.6, 5.4, 4.4],
)
add_h2("4.2 阶段时间线（甘特）")
add_table(
    ["阶段", "W1", "W2", "W3", "W4", "W5", "W6", "W7", "W8", "W9", "W10", "W11", "W12+"],
    [
        ["P0 底座", "▓", "▓", "", "", "", "", "", "", "", "", "", ""],
        ["P1 自动预警", "", "", "▓", "▓", "▓", "", "", "", "", "", "", ""],
        ["P2 自动分析", "", "", "", "", "", "▓", "▓", "▓", "", "", "", ""],
        ["P3 自动优化", "", "", "", "", "", "", "", "", "▓", "▓", "▓", ""],
        ["P4 扩展（S4→S5→S3→S7→S6→S1/S2→S8/S9）", "", "", "", "", "", "", "", "", "", "", "", "▓"],
        ["需求卡补齐（并行）", "▓", "▓", "▓", "▓", "▓", "▓", "▓", "▓", "▓", "▓", "▓", "▓"],
    ],
    col_widths=[4.4, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.9],
)
add_body(
    "说明：P0~P3 合计约 11 周；各阶段末设评审会（闸门评审），通过后进入下一阶段；未通过按「独立回退」原则"
    "回退该阶段改动，不阻塞现有业务发版。"
)

# ============ 五、任务依赖与关键路径 ============
add_h1("五、任务依赖与关键路径")
add_h2("5.1 关键路径")
add_body(
    "T0.1（四表落地）→ T0.3（工具闸门）→ T1.1（巡检引擎）→ T1.3（S8 对接）→ T2.1（关系推理）→ "
    "T2.2（Planner）→ T3.1（执行调度）→ T3.2（建议审批）→ T3.4（场景落地）→ T4.1（S4 域补齐）。"
    "关键路径合计约 9 周 + S4 域补齐 3~4 周；关键路径上任何任务延期将直接推迟 M1~M4 里程碑。"
)
add_h2("5.2 并行任务与依赖要点")
add_bullet("T0.2（前端登记页）与 T0.1 并行，前端可先按表结构契约联调；", ordered=True, index=1)
add_bullet("T0.5/T0.6（基线校准与 KPI 锁定）与 P1 并行，由域Owner 与数据团队承担；", ordered=True, index=2)
add_bullet("第三部分九域需求卡补齐与 P0~P2 并行，域Owner 承担，不占用平台研发关键路径；", ordered=True, index=3)
add_bullet("T1.5（分级字典）与 T1.1 并行；T3.3（有效性验证）与 T3.4（场景落地）并行；", ordered=True, index=4)
add_bullet("P4 各域之间按「数据就绪度 × 规则确定性」串行推进；S6 依赖车间实时数据，须在 S4/S5 跑通 L2 闭环后启动；", ordered=True, index=5)
add_bullet("T2.5（齐套四量试点）依赖后端聚合工具先注册（LLM 不直连数据库），占用数据须单独汇总 ic_item_stockoccupy / srm_po_occupy 两表（列名不同：orderentry_id 与对应明细行 ID）。", ordered=True, index=6)

# ============ 六、质量控制与评审闸门 ============
add_h1("六、质量控制与评审闸门")
add_h2("6.1 需求卡评审三硬闸门")
add_body(
    "每域需求卡按 C0~C13 十四项标准写清：C1（业务目标与 KPI）、C5（规则与算法）、C11（验收与评测）任一缺失，"
    "评审直接判定「不具备开发条件」。写卡三个易错点：① 把方案话术当需求——须写成可判定规则（如「以最小化换型"
    "次数为第一目标、交期满足为硬约束，求解上限 90 秒，输出前 3 个方案及目标值分解」）；② 只写正向路径——"
    "异常分支（无货源/无价格/超配额/供应商冻结）须各自挂起并转什么任务；③ 验收写形容词——须写数字（如"
    "「逾期预警提前 ≥2 天覆盖 ≥80%；证据完整率 100%；误报率 ≤10%（100 条标注样本）」）。"
)
add_h2("6.2 证据规范")
add_body(
    "每条结论 = 对象编码 + 记录号 + 字段 + 值 + 快照时间 + 口径版本；缺快照时间或口径版本的证据在跨日复核时"
    "视为无效。S4 采购执行智能体需求卡（AGT-S4-001）为完整参照示例：首批三个场景（PR 转 PO 自动起草含配额与"
    "框架价校验、交期答复与 T-3 逾期催交、供应商履约复盘与配额调整建议），首批规则 6 条、动作 6 个（全部 L2，"
    "催交通知可升 L3），试点范围 1 工厂 × 1 品类 × 30 家供应商运行一个完整采购月；验收底线为草稿字段准确率 "
    "≥98%、规则命中准确率 ≥90%、误报率 ≤10%、逾期预警提前 ≥2 天覆盖 ≥80%、证据完整率 100%。"
)
add_h2("6.3 代码评审红线（每任务合入前必查）")
add_bullet("租户隔离：所有读写强制注入 tenant_id 上下文，任何绕过租户字段的查询或写入均被禁止；", ordered=True, index=1)
add_bullet("审批流：智能体仅可「起草」或「建议」，所有落库操作必须经由现有审批流人工确认，不可绕过；", ordered=True, index=2)
add_bullet("工具注册闸门：所有可被智能体调用的 API 或服务必须显式注册并附带业务语义描述，未注册工具不可调用；", ordered=True, index=3)
add_bullet("缺省关闭：未启用租户的行为与当前版本完全一致，可评审、可回退；", ordered=True, index=4)
add_bullet("指标口径：智能体引用的指标定义、计算逻辑与数据源必须严格对齐已注册的蓝图文档与操作手册，不可自行推断。", ordered=True, index=5)

# ============ 七、风险任务化应对 ============
add_h1("七、风险任务化应对")
add_table(
    ["风险（方案第八章）", "对应任务", "应对措施"],
    [
        ["LLM 幻觉导致错误结论", "T2.2/T2.3", "推理骨架由登记表与证据校验代码决定；结论必须带证据；关键建议必经人工审批"],
        ["误报导致预警疲劳", "T1.1/T1.5", "规则阈值可配置、预警分级、置信度过滤；错峰巡检控制频率"],
        ["越权访问或跨租户泄漏", "T0.1/T0.3", "所有读写强制 tenant_id；工具注册闸门限定可调用面；复用 ResolveOrThrow 解析"],
        ["巡检影响在线业务", "T1.2", "巡检只读扫描、错峰调度、限流；重活复用现有调度能力"],
        ["登记表滞后于业务变化", "T4.3", "LLM 半自动抽取生成登记草稿（AI 辅助本体构建），人工确认生效；版本化留痕"],
    ],
    col_widths=[3.6, 2.2, 9.4],
)

# ============ 八、跟踪与汇报机制 ============
add_h1("八、跟踪与汇报机制")
add_bullet("周报：每周五输出任务周报（进展、风险、下周计划），按 WBS 任务编号逐条更新状态（未开始/进行中/阻塞/完成）；", ordered=True, index=1)
add_bullet("阶段评审会：每阶段末召开闸门评审会（域Owner、后端、前端、测试参加），对照验收口径逐项确认；未通过项进入整改清单，整改完成后复审；", ordered=True, index=2)
add_bullet("需求卡评审会：第三部分九域需求卡按完成情况滚动评审，C1/C5/C11 三硬闸门一票否决；", ordered=True, index=3)
add_bullet("任务完成标准：交付物 + 验收口径双达标方视为完成；代码合入前须通过 6.3 节代码评审红线；", ordered=True, index=4)
add_bullet("回退机制：每阶段独立交付与回退；回退不阻塞现有业务发版，回退内容记录于周报。", ordered=True, index=5)

doc.save(OUT)
print(OUT)