AiDOPWarehouse/doc/generate_s3_req_docx.js

/**
 * Generate S3 供应协同业务需求描述.docx
 * 严格按照 S1 产销协同业务需求描述.docx 的格式：
 *   标题 → 文档信息 → 目录 → (一)模块功能说明+业务描述 → ...
 */
const fs = require('fs');
const {
  Document, Packer, Paragraph, TextRun, HeadingLevel,
  AlignmentType, PageBreak, TableOfContents, convertInchesToTwip,
} = require('docx');

const FONT = '微软雅黑';

// ── 辅助函数 ──
function empty() { return new Paragraph({ spacing: { after: 80 }, children: [] }); }
function pageBreak() { return new Paragraph({ children: [new PageBreak()] }); }

function normalPara(text, opts = {}) {
  return new Paragraph({
    children: [new TextRun({ text, size: 21, font: FONT, ...opts })],
    spacing: { after: 100, line: 360 },
    indent: opts.indent ? { left: convertInchesToTwip(opts.indent) } : undefined,
  });
}

// H2: (一) 物料需求计划
function sectionHeading(text) {
  return new Paragraph({
    children: [new TextRun({ text, bold: true, size: 28, font: FONT })],
    heading: HeadingLevel.HEADING_2,
    spacing: { before: 400, after: 200 },
  });
}

// H3: 功能说明 / 业务描述
function subHeading(text) {
  return new Paragraph({
    children: [new TextRun({ text, bold: true, size: 22, font: FONT })],
    heading: HeadingLevel.HEADING_3,
    spacing: { before: 200, after: 100 },
  });
}

// Title paragraph
function titlePara(text) {
  return new Paragraph({
    children: [new TextRun({ text, bold: true, size: 36, font: FONT, color: '1F4E79' })],
    alignment: AlignmentType.CENTER,
    spacing: { after: 300 },
  });
}

function docInfoPara(text) {
  return new Paragraph({
    children: [new TextRun({ text, size: 21, font: FONT })],
    spacing: { after: 40 },
    bullet: { level: 0 },
  });
}

// ═══════════════════════════════════════════════════
// 各模块业务需求描述数据
// ═══════════════════════════════════════════════════

const CN_NUM = ['', '一', '二', '三', '四', '五', '六', '七', '八', '九', '十', '十一', '十二', '十三'];

const modules = [
  {
    title: '物料需求计划',
    funcDesc: [
      '物料需求计划模块实现物料需求的在线管理，通过MDP同步外部系统工单需求、库存和采购在途数据。',
      '利用MRP逻辑自动计算物料净需求（To-be-Scheduled Qty = MES Qty - Loc Qty - Scheduled Qty），生成可供发布的物料需求计划。',
      '支持勾选发布和全部发布两种模式，发布后数据驱动下游物料交货计划和物料采购申请。',
      '支持手动新增、编辑和删除物料需求记录，满足特殊场景下的灵活调整需求。',
      '数据通过MDP作业（S3_MDP_SYNC_TRANSFORM）从ERP定时同步，计算结果存入DWD宽表层供看板消费。',
    ],
    bizDesc: [
      '物料计划员登录DOP系统，进入"S3供应协同→物料需求计划"菜单，查看物料需求列表。',
      '系统自动展示MRP净需求计算结果：物料编码、物料名称、MES需求量、库存量、在途量和待排产净需求。',
      '通过物料编码、物料名称、需求日期等维度进行过滤查询，支持分页和列设置自定义显示字段。',
      '点击工具栏"勾选发布"按钮，将选中的物料需求计划行发布为"已发布"状态；也可点击"全部发布"一键发布所有未发布记录。',
      '已发布的计划可点击"取消发布"回退为未发布状态，重新参与后续计算和发布。',
      '对于特殊场景，可手动新增物料需求记录、编辑已有记录或删除记录（删除操作需二次确认）。',
    ],
  },
  {
    title: '物料交货计划',
    funcDesc: [
      '物料交货计划模块基于已发布的物料需求计划自动生成交货计划，并驱动供应商端交货计划同步。',
      '交货计划包含物料编码、供应商、计划交期等核心信息，作为供应商生产和交货的依据。',
      '供应商交货状态变更后自动回传至计划端，实现供应商与计划端的双向信息同步。',
      '每个交货计划行对应唯一的交货单号（dsnum），用于与供应商端交货单关联匹配。',
    ],
    bizDesc: [
      '物料计划员进入"S3供应协同→物料交货计划"菜单，查看基于已发布物料需求计划自动生成的交货计划列表。',
      '在列表中按物料编码、供应商、计划交期等条件筛选查询，查看各交货计划的执行情况。',
      '交货计划生成后自动同步至供应商端，驱动供应商按计划安排生产和交货。',
      '供应商交货状态变更时自动回传至计划端，交货计划列表实时反映最新的交货状态。',
      '物料计划员可根据交货状态跟踪结果，对未完成的交货计划进行催办和协调。',
    ],
  },
  {
    title: '交货单异常记录',
    funcDesc: [
      '交货单异常记录模块提供交货过程中产生的异常记录的只读查询视图，帮助物料计划员和质量管理人员快速掌握交货异常情况。',
      '系统自动比对交货计划与实际交货数据，逾期超过3个工作日或实收数量低于计划数量80%时自动标记为异常记录。',
      '异常数据来源于MDP同步的交货计划和实际交货数据自动比对结果，支持按交货单号、供应商、异常类型、日期范围等多维筛选。',
      '该页面为只读查询视图，不支持手动增删改操作，确保异常数据的客观性和可追溯性。',
    ],
    bizDesc: [
      '物料计划员进入"S3供应协同→交货单异常记录"菜单，查看系统自动识别的交货异常记录列表。',
      '通过交货单号、供应商名称、异常类型（逾期/短缺/质量）、计划日期范围等条件筛选查询。',
      '在列表中查看每条异常记录的基本信息：关联交货单、物料编码、计划数量、实际数量、异常原因。',
      '点击异常记录行查看明细信息，追溯异常来源和对生产计划的影响范围。',
      '支持将当前查询结果导出为CSV/Excel文件，用于离线分析和供应商绩效评估。',
      '质量管理员可通过该页面查看与质量相关的交货异常记录，进行质量追溯分析。',
    ],
  },
  {
    title: '要货令',
    funcDesc: [
      '要货令模块承接已批准物料采购申请驱动的要货指令（Demand Order）在线管理，作为采购执行的具体载体。',
      '业务流程为：物料采购申请驱动 → 要货令创建 → 供应选择 → 物料选择 → 订单保存。',
      '供应选择环节从货源清单动态加载下拉选择供应商和采购组，确保供应商资质合规。',
      '保存后生成DO类型采购订单记录（PurOrdMaster/DO），数据同步至ERP系统。',
    ],
    bizDesc: [
      '采购员进入"S3供应协同→要货令"菜单，接收已批准物料采购申请的驱动信号，启动要货令创建流程。',
      '在要货令表单中填写核心信息：单号、采购组、部门、日期、合同编号等。',
      '从货源清单动态加载下拉选择供应商和采购组，确保数据实时性和货源合规。',
      '选择要货物料，填写需求数量、交货日期等明细信息。',
      '确认无误后保存要货令，系统自动生成DO类型采购订单记录，数据同步至ERP。',
      '已保存的要货令可在列表中查看、编辑和删除；删除操作需二次确认。',
    ],
  },
  {
    title: '物料采购申请',
    funcDesc: [
      '物料采购申请模块承接物料交货计划和MRP检查输出的采购需求，通过规范的申请-审批流程确保采购需求的合理性和合规性。',
      '申请单提交后进入审批流，经指定审批人审核后状态更新为"已批准"，审批过程可追溯、可审计。',
      '批准后系统根据物料类型自动合并生成对应订单：DO物料→要货令，PO物料→采购订单，PW物料→委外加工订单。',
      '已批准申请单不可编辑或删除，仅可查看，保护审批结果严肃性。',
    ],
    bizDesc: [
      '采购员进入"S3供应协同→物料采购申请"菜单，查看采购申请列表，支持按申请单号、物料、供应商、状态多维度筛选。',
      '基于物料交货计划或MRP检查结果点击"新增"按钮，填写申请单号、物料编码、供应商、需求数量、需求日期等必填字段。',
      '申请单保存后可提交审批，提交后进入审批流，状态变为"审核中"。',
      '审批人在审批列表中查看待审申请，执行"批准"或"驳回"操作；批准后状态更新为"已批准"。',
      '已批准的申请单由系统自动按物料类型合并生成对应订单：DO物料→要货令，PO物料→采购订单，PW物料→委外加工订单。',
      '已批准的申请单不可编辑或删除，仅可查看；未提交的申请可编辑或删除。',
    ],
  },
  {
    title: '物料采购订单',
    funcDesc: [
      '物料采购订单模块管理已下达至供应商的正式采购订单，跟踪订单从下达到收货完成的全生命周期。',
      '业务流程为：采购订单生成 → 供应商确认/交期回复 → 发货关联 → 订单状态跟踪 → 收货完成/订单关闭。',
      '供应商在线确认订单并回复预计交期，发货关联展示发货数量、日期与订单的对应关系。',
      '收货数据累计达订单数量时状态自动更新为"已完成"，已完成订单可手动关闭。',
    ],
    bizDesc: [
      '采购员进入"S3供应协同→物料采购订单"菜单，查看采购订单列表，支持按订单号、供应商、物料、状态等条件筛选。',
      '基于已批准采购申请自动或手动生成采购订单，填写供应商、物料、数量、交期等核心信息。',
      '供应商在线确认订单并回复预计交期，确认信息回写至订单，采购员可在列表中查看交期回复状态。',
      '关联发货单数据，在发货关联视图中展示发货数量、日期与订单的对应关系。',
      '跟踪订单从"已下达→部分收货→已完成→已关闭"的完整生命周期状态。',
      '收货数据累计达订单数量时系统自动更新为"已完成"；已完成或已取消的订单可手动关闭，关闭后不可再收货。',
    ],
  },
  {
    title: '委外加工订单',
    funcDesc: [
      '委外加工订单模块管理委托外部供应商进行物料加工的采购订单（PurOrdMaster/PW类型）。',
      '业务流程为：委外加工订单创建 → 委外商选择 → 货源清单物料选择 → 明细行管理 → 订单保存。',
      '委外商和物料选择均需校验货源清单有效性，确保委外业务物料选择合规。',
      '每个委外加工订单至少需包含一个明细行，不允许空订单；明细行支持增删改查操作。',
    ],
    bizDesc: [
      '外协管理员进入"S3供应协同→委外加工订单"菜单，查看委外加工订单列表。',
      '点击"新增"按钮创建委外加工订单，填写订单基本信息（订单号、委外商等）。',
      '从货源清单选择委外加工供应商，系统校验供应商在货源清单中存在且状态有效。',
      '从货源清单选择委外加工物料，管理每个明细行的物料、数量、单价、交货日期等。',
      '确认无误后保存订单，生成PW类型采购订单记录，数据同步至ERP并与生产工单关联。',
      '已保存的订单可在列表中查看、编辑和删除；支持通过子页面管理明细行的增删改查。',
    ],
  },
  {
    title: '工序外协订单',
    funcDesc: [
      '工序外协订单模块管理生产过程中特定工序委托外部供应商完成的采购订单。',
      '业务流程为：选择生产工单 → 选择外协工序 → 创建外协订单 → 供应商/数量校验 → 订单保存/工单工序关联。',
      '支持工单-工序-外协订单三级关联，同一工单同一工序不可重复创建外协订单，防止重复委外。',
      '外协数量不可超过工单该工序的计划生产数量，外协商必须在货源清单中有效。',
    ],
    bizDesc: [
      '外协管理员进入"S3供应协同→工序外协订单"菜单，查看工序外协订单列表。',
      '从生产工单列表选择需要外协的生产工单，系统展示该工单的基本信息。',
      '通过组件从工单中选择需要外协的工序，系统校验工序属于有效工单（状态不为已关闭或已取消）。',
      '基于选中的工单和工序创建外协订单，填写供应商、数量、交期等信息。',
      '系统校验外协商在货源清单中有效、外协数量不超过工序计划生产数量，同一工单同一工序不可重复创建。',
      '保存订单后自动与生产工单工序建立关联，工单状态联动更新。',
    ],
  },
  {
    title: '供应协同看板',
    funcDesc: [
      '供应协同看板为管理层和业务人员提供S3模块的核心KPI可视化监控面板。',
      '通过4个KPI卡片展示核心指标：物料计划周期、物料计划满足率、物料计划人效、物料库存周转天数。',
      '采用DynamicModuleDashboard动态看板组件（module-code="S3"），支持多维筛选联动和分支看板视图切换。',
      '分支一为MRP维度（BOM需求满足趋势+统计表），分支二为MDP维度（交货执行进度+满足率）。',
      '支持策略模拟What-If分析和运营指标建模配置，KPI数据通过MDP定时或手动刷新。',
    ],
    bizDesc: [
      '供应链经理进入"S3供应协同→供应协同看板"菜单，系统自动加载4个KPI指标卡片，直观展示当前供应协同健康度。',
      '通过基础查询条件（日期、产品、订单号、产线、物料、供应商）筛选，看板所有指标数据自动联动刷新。',
      '查看趋势箭头（上升绿色/下降红色），基于同比/环比计算，辅助管理层快速识别改善或恶化趋势。',
      '切换至分支一MRP维度看板，查看BOM需求满足趋势和统计表；切换至分支二维MDP看板，查看交货执行进度和满足率。',
      '点击"策略模拟"按钮进行What-If分析，模拟调整参数查看对KPI的影响；点击"导出"生成分析报告。',
      '点击"运营指标建模"链接跳转至指标配置页面，自定义KPI口径和计算规则。',
    ],
  },
  {
    title: '工单物料齐套上线看板',
    funcDesc: [
      '工单物料齐套上线看板以工单为维度，展示每个工单所需物料的齐套状态（需求、发料、欠料、备料、在检、在途、承诺数量）。',
      '数据来源于WorkOrdDetailTotalKB宽表，通过MRP计算工单物料齐套情况，展示30+字段完整齐套信息。',
      '帮助生产计划和物料计划人员精准识别缺料工单和责任供应商（供应商编码/名称/采购组/采购员）。',
      '支持列设置自定义显示/隐藏列、多字段排序和分页（10/20/50条每页），优化大数据量页面性能。',
    ],
    bizDesc: [
      '物料计划员进入"S3供应协同→工单物料齐套上线看板"菜单，查看工单物料齐套数据列表。',
      '通过订单号、工单号、产品编码、物料编码、供应商名称等条件筛选查询。',
      '在列表中查看30+字段的齐套信息：序号、订单/工单号、BOM版本、物料描述、需求数量、发料数量、欠料数量、备料数量、在检数量、在途数量等。',
      '欠料数量>0的物料行自动标记为"未齐套"，通过供应商编码/名称/采购组/采购员快速定位责任供应商。',
      '点击"刷新"按钮调用refreshWorkOrderMaterialReadiness接口重新执行MRP齐套计算，获取最新数据。',
      '自定义显示/隐藏列配置和多字段升序/降序排序，满足不同角色的个性化视图需求。',
    ],
  },
  {
    title: 'MDP 运行监控',
    funcDesc: [
      'MDP运行监控模块提供S3相关MDP数据同步与转换任务的运行状态可视化。',
      '展示S3模块相关的MDP同步任务列表：任务名称、运行状态（成功/失败/运行中）、开始/结束时间、处理记录数和错误信息。',
      '失败任务红色高亮标识和告警提示，帮助IT运维人员及时发现和定位数据同步失败、转换异常等问题。',
      '与平台级MDP监控形成"总-分"监控体系：S3页面聚焦本模块任务实例，平台级监控覆盖所有模块。',
    ],
    bizDesc: [
      'IT运维人员进入"S3供应协同→MDP运行监控"菜单，查看S3模块相关的MDP同步任务列表。',
      '在列表中查看每个任务的运行状态：任务名称、最近一次执行状态（成功/失败/运行中）、开始时间、结束时间、处理记录数。',
      '按任务状态（全部/成功/失败/运行中）过滤查看，快速定位异常任务。',
      '失败任务以红色高亮标识，点击可查看错误信息详情，便于及时响应和修复。',
      '供应链经理和物料计划员也可通过该页面了解数据同步状态，确认数据时效性。',
    ],
  },
  {
    title: '数据中台架构',
    funcDesc: [
      'S3供应协同模块采用Ai-DOP统一数据中台分层架构（STG→STD→DWD→KPI），确保前端页面、看板展示和KPI考核的数据口径一致。',
      '贴源层(STG/mdp_stg_*)保留源系统原始数据；标准层(STD/mdp_std_*)统一字段口径并清洗脏数据；宽表层(DWD/dwd_*)构建面向页面和KPI的主题事实表；指标层(KPI/ado_s9_kpi_value_*)按天存储L1-L4指标值。',
      'MDP作业(S3_MDP_SYNC_TRANSFORM)负责全链路同步转换，支持手动触发和定时调度，作业日志可观测、异常可追溯。',
      '核心数据链路包括：物料需求/计划链路、采购订单/交货链路、齐套/看板链路。',
    ],
    bizDesc: [
      'S3模块的业务数据通过MDP作业自动同步至数据中台各层，各页面统一消费DWD/KPI层数据。',
      '物料需求/计划链路：work_order_demand/inventory_snapshot/srm_in_transit → mdp_stg_demand贴源 → mdp_std_demand标准 → dwd_demand_schedule宽表 → KPI计算。',
      '采购订单/交货链路：PurOrdMaster/srm_polist_ds/vscm_jhjh → mdp_stg_po贴源 → mdp_std_po标准 → dwd_po_delivery宽表 → KPI计算。',
      '齐套/看板链路：WorkOrdDetailTotalKB/homeS3 → DWD直接消费 → 前端看板和KPI卡片 → ado_s9_kpi_value_*。',
      '各页面刷新按钮和计划联动手动触发可即时获取最新同步数据；系统管理员通过MDP监控页面查看作业执行状态和处理日志。',
    ],
  },
  {
    title: '权限管理汇总',
    funcDesc: [
      'S3供应协同模块涉及以下核心角色和权限：',
      '物料计划员：查看和操作物料需求计划、交货计划；发布/取消发布；查看交货异常记录；刷新齐套看板。',
      '采购员：增删改查要货令、采购申请、采购订单；查看交货计划和交货异常记录。',
      '外协管理员：增删改查委外加工订单和工序外协订单。',
      '供应链经理：查看所有模块；查看供应协同看板和管理KPI；导出报表；策略模拟。',
      '审批人(采购经理)：审核采购申请的审批流。',
      'IT运维人员：查看MDP运行监控；监控同步任务状态。',
      '质量管理员：查看交货异常记录（质量追溯）。',
      '仓库管理员：查看采购订单和交货计划（安排收货）。',
    ],
  },
];

// ═══════════════════════════════════════════════════
// 生成文档
// ═══════════════════════════════════════════════════
function buildDocument() {
  const sections = [];

  // ── 封面/标题 ──
  sections.push(empty(), empty(), empty(), empty());
  sections.push(titlePara('供应协同业务需求描述'));
  sections.push(empty());

  // ── 文档信息 ──
  const infoItems = [
    '文档作者：彭熙玉',
    '创建日期：2026-06-10',
    '更新日期：2026-06-10',
    '文档编号：DOP-S3-REQ-001',
    '当前版本：V1.0',
  ];
  infoItems.forEach(item => sections.push(docInfoPara(item)));
  sections.push(empty(), empty());

  // ── 目录 ──
  sections.push(pageBreak());
  sections.push(new Paragraph({
    children: [new TextRun({ text: '目录', bold: true, size: 28, font: FONT })],
    heading: HeadingLevel.HEADING_2,
    spacing: { before: 200, after: 300 },
  }));
  sections.push(new TableOfContents('目录', {
    headingStyleRange: '2-3',
    hyperlink: true,
  }));
  sections.push(new Paragraph({
    children: [new TextRun({ text: '（如目录未显示，请在 Word 中右键此处 → 更新域）', size: 18, font: FONT, italics: true, color: '888888' })],
    spacing: { before: 40, after: 200 },
  }));

  // ── 各功能模块 ──
  for (let i = 0; i < modules.length; i++) {
    const mod = modules[i];
    sections.push(pageBreak());

    // 章节标题：(一) 物料需求计划
    sections.push(sectionHeading(`（${CN_NUM[i + 1]}）${mod.title}`));

    // 功能说明
    sections.push(subHeading('功能说明'));
    (mod.funcDesc || []).forEach(desc => sections.push(normalPara(desc)));

    // 业务描述
    if (mod.bizDesc && mod.bizDesc.length) {
      sections.push(subHeading('业务描述'));
      mod.bizDesc.forEach(desc => sections.push(normalPara(desc)));
    }
  }

  return sections;
}

// ═══════════════════════════════════════════════════
// 主流程
// ═══════════════════════════════════════════════════
async function main() {
  const sections = buildDocument();

  const doc = new Document({
    styles: { default: { document: { run: { font: FONT, size: 21 } } } },
    sections: [{
      properties: { page: { margin: { top: convertInchesToTwip(0.8), bottom: convertInchesToTwip(0.8), left: convertInchesToTwip(1.2), right: convertInchesToTwip(1.2) } } },
      children: sections,
    }],
  });

  const buffer = await Packer.toBuffer(doc);
  const outPath = 'd:\\DEMONET\\doc\\S3供应协同业务需求描述.docx';
  const fallbackPath = 'd:\\DEMONET\\doc\\S3供应协同业务需求描述_V2.docx';
  const tempPath = 'd:\\DEMONET\\doc\\S3_req_temp.docx';
  fs.writeFileSync(tempPath, buffer);

  try { fs.unlinkSync(outPath); } catch(e) {}
  try { fs.renameSync(tempPath, outPath); console.log(`Renamed to: ${outPath}`); }
    catch(e) {
      try { fs.unlinkSync(fallbackPath); } catch(_) {}
      try { fs.renameSync(tempPath, fallbackPath); console.log(`Fallback to: ${fallbackPath}`); }
        catch(e2) { console.log(`Generated: ${tempPath} (target locked)`); }
    }
  console.log(`Size: ${(buffer.length / 1024).toFixed(1)} KB`);
}

main().catch(err => { console.error('Error:', err); process.exit(1); });