PPT 生成质量强制规范

核心原则：生成的每一页 PPT 都必须包含数据可视化图表 + 深度分析文本，严禁出现空页、纯图表页、纯文字页。质量检查不合格的页面必须自动修复或回退重建。

一、页面内容完整性强制标准

1.1 每页必须包含的元素（MINIMUM_REQUIRED）

页面类型	至少图表数	至少分析段数	每段最少字数
KPI概览页	6个KPI卡片	4段	150字/段
趋势分析页	1个趋势图	4段	150字/段
分布分析页	1个图表（环形/柱状）	3段	150字/段
排行分析页	1个条形图	4段	150字/段
总结/建议页	无硬性要求	4段	150字/段
封面/目录/尾页	无硬性要求	1段简介	30字/段

1.2 分析文本深度要求

分析文本必须包含具体数值引用和业务洞察建议，不得是泛泛概括：

分析维度	必须包含的内容
数据引用	引用具体数值（含单位），如"XXX 台"、"占比 XX%"、"增长 XX%"
对比分析	与同类/历史/目标进行对比，说明高低/好坏
原因解读	对数据背后的原因进行分析（至少 2 条可能原因）
业务建议	给出可执行的业务行动建议（不空泛说"加强"、"优化"）

1.3 页面为空判定（CRITICAL）

以下任一种情况判定为页面为空，严重级别 critical：

页面内所有文本框总字数 < 50 字
页面没有任何图表（shape_type 为 chart 的元素数为 0）
页面有图表但无分析文本（图表下方/右侧无 insight 文本块）
页面所有文本均为占位符替换后的默认文本（如标题"数据详情"无实质内容）
页面仅有一行文字（如仅有标题没有正文）

二、图表完整性强制标准

2.1 图表必须可读

图表标题不可为空
坐标轴标签必须显示完整（不被截断）
数据系列颜色必须与主题配色一致
图表尺寸必须占据合理区域（宽度 ≥ 页面宽度的 35%）

2.2 图表与分析文本的关联

图表中的关键数据必须在右侧/下方分析文本中被引用
分析文本中的数值必须与图表数据一致
图表和分析文本必须在视觉上属于同一页（不能有割裂感）

2.3 图表尺寸下限

图表类型	最小宽度	最小高度
趋势折线图	SLIDE_WIDTH × 0.40	SLIDE_HEIGHT × 0.35
分布环形图/饼图	SLIDE_WIDTH × 0.30	SLIDE_HEIGHT × 0.30
排行条形图	SLIDE_WIDTH × 0.45	SLIDE_HEIGHT × 0.45
KPI 卡片	SLIDE_WIDTH × 0.28（单张）	SLIDE_HEIGHT × 0.15（单张）

三、布局合理性强制标准

3.1 安全区域

所有元素必须位于以下安全区域内：

左边界 ≥ CONTENT_LEFT (Emu(762000) ≈ 2cm)
右边界 ≤ SLIDE_WIDTH - Emu(762000)
上边界 ≥ Emu(1524000)（避开页眉导航栏）
下边界 ≤ SLIDE_HEIGHT - Emu(700000)（避开页脚区域）

3.2 图文重叠检测

任意两个形状的重叠面积 > 任一形状面积的 10% 则判定为重叠
标题文字与导航标签的重叠豁免
必须检测 chart 与 textbox 的重叠

3.3 填充率

内容填充率 < 20% → critical（页面基本为空）
内容填充率 < 35% → major（留白严重）
内容填充率 < 50% → minor（留白偏多）
内容填充率 ≥ 65% → 合格

四、视觉一致性强制标准

4.1 字体规范

中文字体：微软雅黑
数字/英文字体：Arial
标题字号：24pt - 32pt
正文字号：11pt - 14pt
KPI 数值字号：28pt - 36pt
同一页面字体种类 ≤ 2 种

4.2 颜色规范

主色：主题 primary 色
强调色：主题 accent 色
图表系列色：主题 series 色板
正文色：#333333
次要文字色：#666666
背景色：#FFFFFF

五、六项用户确认的强制校验

5.1 报告周期与页数范围

校验项	说明
封面日期	必须与用户确认的周期一致
总页数	必须在用户确认的范围内（允许 ±1 页）
目录页	若页数 ≥ 5 则必须包含目录页

5.2 核心指标集

每个 KPI 指标必须在 KPI 概览页出现
每个 KPI 的值必须来自数据计算而非硬编码
KPI 卡片不得超过 6 个（超出则合并或精简）

5.3 受众与决策场景

分析文本的语言风格必须匹配受众（管理层 → 结论优先，执行层 → 细节优先）
建议内容必须对应决策场景

5.4 视觉风格与配色方向

每页遵循相同的主题配色
不允许出现硬编码的颜色值（必须从 theme 获取）

5.5 页面结构与模板方案

实际生成的页面类型和顺序必须与用户确认的 pages 列表一致
不允许跳过任何用户选定的页面（除非数据不支持且已告警）

六、自检修复迭代标准

6.1 迭代退出条件

条件	说明
无任何 critical 级别问题	必须满足
无任何 major 级别问题	必须满足
minor 级别问题 ≤ 2 个	强烈推荐
质量评分 ≥ 85	必须满足

6.2 修复策略

问题类型	修复方式
页面为空	不允许简单添加提示文字"建议补充"，必须回退重建页面，调用 build 函数重新生成完整分析内容
图文重叠	重新计算位置，向下/右偏移；若空间不足则缩小图表
飞出页面	裁剪到安全区域内，必要时缩放
分析文本过短	扩写分析文本，补充数据引用和业务洞察
图表无数据	检查数据来源，使用备用数据列或降级为表格
占位符未替换	清空未替换的占位符文本

6.3 最大迭代次数

默认最大迭代 5 次
若第 5 次仍有 critical 问题，必须报错，不允许输出不合格 PPT

七、禁止事项（DO NOT）

禁止生成只有图表没有分析文本的页面
禁止生成只有分析文本没有图表的分析页（KPI/趋势/分布/排行页）
禁止分析文本中出现"暂无数据"、"数据不足"作为唯一内容（必须挖掘现有数据维度）
禁止在页面空白处简单添加"建议补充图表"的提示文字代替实际内容
禁止使用 placeholder 文本（如 {page_title} 未替换）
禁止任何元素飞出或紧贴页面边缘（安全边距≥2cm）
禁止在总结页仅列出不足 3 条建议
禁止分析文本使用模糊措辞如"要加强"、"进一步优化"（必须具体可执行）

八、理想 PPT 页面范例

KPI 概览页范例

┌──────────────────────────────────────────────────────┐
│  KPI1: 总需求 1,250 台   KPI2: 已下单 780 台         │
│  KPI3: 转化率 62.4%      KPI4: 覆盖客户 93 个          │
│  KPI5: 支持闭环率 78%    KPI6: 覆盖国家 96 个          │
├──────────────────────────────────────────────────────┤
│  需求总量与转化结构                                    │
│  本期客户意向项目总需求台数为 1,250 台，其中累计已下单    │
│  780 台（占比 62.4%），未下单 470 台（占比 37.6%），    │
│  下单转化率 62.4%...（≥150字深度分析）                  │
├──────────────────────────────────────────────────────┤
│  客户覆盖与服务广度                                    │
│  本期覆盖客户 93 个，涉及 96 个意向国家...              │
├──────────────────────────────────────────────────────┤
│  跨部门支持闭环效率                                    │
│  支持需求闭环率 78%，...                               │
├──────────────────────────────────────────────────────┤
│  未下单需求跟进策略                                    │
│  当前未下单 470 台，...                                │
└──────────────────────────────────────────────────────┘

分布分析页范例

┌───────────────────────┬──────────────────────────────┐
│                       │  意向级别分布概况              │
│    环形图              │  共有 6 个不同的意向级别...    │
│    (左 55%)           │                              │
│                       │  排名第一: A级                │
│                       │  A级以 450 台（占比 36%）...   │
│                       │                              │
│                       │  长尾分布特征                  │
│                       │  前三名累计占比 72%...         │
└───────────────────────┴──────────────────────────────┘

九、封面页质量专项规则

封面页是 PPT 的第一印象，且 python-pptx 在处理自定义模板时有多个已知陷阱。以下规则由 quality_inspector._check_cover_quality() 在生成后自动执行。

V006：封面文字颜色与背景冲突（critical，自动修复）

检测逻辑：

扫描封面页所有 is_placeholder=True 的 shape
检测页面顶部的彩色 banner（y≈0 的填充矩形）底部位置
如果 placeholder 在 banner 下方（白色区域）且文字颜色 RGB 三通道均 ≥ 0xCC（近白色）→ 报 V006

自动修复：将文字颜色改为 theme_colors['primary']（默认 #1E3A5F 深蓝）

典型场景：Wuling 模板，蓝色渐变矩形覆盖 0→3441700 EMU，title placeholder 在 y=3818251。开发者设了 C_WHITE → 白字在白色背景上完全隐形。

C012：封面占位符仍为模板默认文字（critical，不可自动修复）