Product Requirements Document

CS 产品质量月度分析报告

2026-05 · Serviceability Engineering

从 PostgreSQL 数据提取、LLM 二次分类、Vega-Lite 图表到 HTML 报告的全链路自动化生成系统设计。

LLM Pipeline PostgreSQL Vega-Lite Jinja2 Cross-Filter

概览

本系统设计的目标是自动化生成 CS 产品质量月度分析报告。从维修工单数据库提取数据，经过 LLM 二次分类与总结，渲染为带有交互图表的 HTML 报告。全流程无需人工介入——从原始数据到可阅读的月度分析报告，一次运行完成。

核心流程：PostgreSQL → Python Agent → LLM → Vega-Lite HTML Report。报告包含交互式图表（可展开条形图、环形图、趋势图）和 DataTables 明细表（支持 10k+ 行），并内置跨图表联动筛选（cross-filtering）。

数据源

两张核心表，结构为设计假设——部署前需与数据库管理员确认实际结构。

表名字段说明
repair_tickets ticket_id, created_at, fault_category, major_component, fault_symptom, solution, repair_type, summary 维修工单表
spare_parts ticket_id, part_name, part_code, quantity, replace_time 备件更换表

技术架构

4 级流水线设计，各阶段独立可执行，便于分步调试和增量运行：

Stage 1SQL 提取按月查询工单 + 备件 → 本地 JSON
↓
Stage 2LLM 二次分类故障子分类归一化 · 部件标准化 · 严重度评级
↓
Stage 3LLM 月度总结趋势分析 · 典型案例 · 改进建议
↓
Stage 4生成 HTMLJinja2 模板渲染 · 嵌入式数据与图表

技术选型：

LLM 处理

两个独立 LLM 任务，各有明确的输入输出规范：

任务一 · 二次分类

故障子分类归一化

硬件 → 6 子类（机械 / 电气 / 光学 / 传感器 / 连接 / 结构）
软件 → 5 子类（系统 / 界面 / 数据 / 通信 / 驱动）
其他 → 3 子类（操作 / 环境 / 未知）

部件名称标准化

将各工单中不一致的部件名映射到公司标准部件表。例：「液压阀」「液压控制阀」「HYD-VALVE-01」→ 统一

严重度评级

P0 — 停机 / 安全风险
P1 — 功能受损
P2 — 体验问题

输入 / 输出

输入：fault_symptom + major_component + summary（每条工单）
输出：结构化 JSON（子分类 / 标准部件 / 严重度）

任务二 · 月度总结

输入为聚合统计 JSON，输出结构化分析，包含：

报告页面结构

单页 HTML，从上到下依次为：

交叉筛选（Cross-Filter）

三种交互模式，实现图表之间的联动筛选：

🎯 Filter Bar

选择故障分类 → 所有图表和表格同步筛选
机制：Filter Bar change event → 全局状态 → View API refresh

📅 Trend Chart Brush

拖拽选中趋势图中某段时间范围 → 其他图表自动只显示该时间段数据
机制：Vega-Lite interval selection + resolve: filter

🔗 Component Ranking Click

点击部件排行柱状图中的某个部件 → 明细表只显示该部件的工单
机制：JS 监听 view change → DataTables API filter → table.draw()

代码架构

cs-quality-report/
├── generate_report.py   # 主入口
├── config.yaml            # 数据库 & LLM 配置
├── templates/
│   └── report.html.j2       # Jinja2 模板
├── prompts/
│   ├── classify.md          # 二次分类 prompt
│   └── summarize.md         # 月度总结 prompt
├── output/
│   └── CS_质量报告_2026-05.html
└── tests/
    └── test_extract.py

generate_report.py 主流程：

设计规范

报告页面的视觉约束，确保信息密度与可读性：

里程碑

总计约 7.5 个工作日，分 10 个里程碑：

风险与应对

风险 1
LLM 分类不一致
同类问题被分到不同子分类 → 置信度 < 0.7 标记待人工审查
风险 2
LLM 处理时间过长
10k 条记录约 30–60 分钟 → 批量并行；首次全量运行后增量
风险 3
单文件 HTML 过大
嵌入式数据 > 5MB → JSON gzip 压缩；明细表按需加载
风险 4
部件名称不一致
同名部件在不同工单中表达各异 → LLM 标准化 + 主数据映射
风险 5
数据库凭据安全
脚本需数据库密码 → config.yaml 不提交 Git

下一步

  1. 连接公司 PostgreSQL — 确认实际表结构和字段名
  2. 交付给 Copilot CLI / Hermes — 从 M1 开始实现
  3. 首月试运行 — 验证数据提取 → LLM 分类 → HTML 生成全链路