架构设计¶

技术栈¶

GUI框架: PySide6 - 提供跨平台的桌面应用界面
ORM: SQLAlchemy - 数据库对象关系映射，支持SQLite等数据库
PDF生成: ReportLab - 生成试压报告、材质报告和质保书
Excel处理: pandas + openpyxl - 读取Excel文件，支持单元格格式和样式读取
日志: loguru - 统一日志管理，支持文件轮转和压缩
配置管理: PyYAML - YAML格式配置文件解析
包管理: uv - Python包管理和依赖管理

分层架构¶

Views → Controllers → Services → Handlers → Models

各层职责¶

层级	模块	职责
视图层	`views/`	UI界面组件，用户交互，信号发送
控制层	`controllers/`	业务协调，信号响应，调用服务层
服务层	`services/`	业务逻辑实现，事务管理
处理层	`handlers/`	基础功能处理，如Excel读写、PDF生成、排序等
数据层	`models/`	ORM模型定义，数据库表映射
工具层	`utils/`	通用工具类，如数据库管理、日志配置

目录结构¶

certflow/
├── __init__.py              # 包初始化，版本信息
├── main.py                  # 程序入口，主窗口
├── config/                  # 配置模块
│   ├── __init__.py          # 配置导出
│   ├── loader.py            # YAML配置加载器，支持环境变量和!include
│   ├── models.py            # Pydantic配置数据模型
│   ├── settings.py          # 配置常量读取，零硬编码
│   └── ui_config.py         # UI配置加载和样式构建
├── controllers/             # 控制层
│   ├── __init__.py          # 控制器导出
│   ├── base_controller.py   # 控制器基类，会话管理
│   ├── certificate_controller.py  # 合格证控制器
│   └── report_controller.py # 报告控制器
├── services/                # 业务层
│   ├── __init__.py          # 服务导出
│   ├── auto_number_service.py   # 自动编号服务
│   ├── certificate_service.py   # 合格证服务
│   ├── query_service.py         # 高级查询服务，级联筛选
│   ├── report_service.py        # 报告服务
│   └── sale_plan_service.py     # 销售计划服务，Excel导入
├── handlers/                # 处理层
│   ├── __init__.py          # 处理器导出
│   ├── data_cleaner.py      # 数据清洗器
│   ├── excel_handler.py     # Excel文件处理器
│   ├── excel_styler.py      # Excel样式读取(颜色/字体/批注)
│   ├── id_generator.py      # 编号生成器(合格证编号/唯一键)
│   ├── report_generator.py  # PDF报告生成器
│   └── sorter.py            # 多键排序器
├── models/                  # 数据层
│   ├── __init__.py          # 模型导出
│   ├── base.py              # SQLAlchemy基类
│   ├── auto_number.py       # 自动编号规则和计数器
│   ├── certificate.py       # 合格证模型
│   ├── print_log.py         # 打印日志模型
│   ├── report_template.py   # 报告模板模型
│   └── sale_plan.py         # 销售计划模型
├── views/                   # 视图层
│   ├── __init__.py          # 视图导出
│   ├── certificate_number_view.py  # 合格证编号生成视图
│   ├── certificate_view.py        # 合格证管理视图
│   ├── import_dialog.py           # 导入配置对话框
│   ├── query_view.py              # 销售计划查询视图
│   └── report_view.py             # 报告生成视图
└── utils/                   # 工具模块
    ├── __init__.py          # 工具导出
    ├── database.py          # 数据库管理器(引擎/会话/迁移)
    └── logger.py            # 日志管理器(单例/轮转/压缩)

核心数据流¶

销售计划导入流程¶

用户选择Excel文件
       ↓
ImportConfigDialog (配置参数: 工作表/表头行/数据起始行/列映射)
       ↓
SalePlanController / SalePlanService
       ↓
ExcelHandler.read_excel() → DataFrame
       ↓
DataCleaner.clean_sale_plan() (数据清洗)
       ↓
IDGenerator.generate_unique_key() (生成唯一键)
       ↓
Sorter.multi_key_sort() (多键排序)
       ↓
保存到 SalePlan 模型

合格证生成流程¶

用户选择销售计划 → 选择编号规则
       ↓
CertificateController.generate_certificates_for_sale_plans()
       ↓
AutoNumberService.generate_certificate_number()
       ↓
AutoNumberRule (获取规则配置) + AutoNumberCounter (流水号计数)
       ↓
生成合格证编号 → 创建 Certificate 记录

报告生成流程¶

用户选择数据 → 选择模板类型/语言/每页记录数
       ↓
ReportController.generate_xxx_report()
       ↓
ReportService → ReportGenerator
       ↓
ReportLab 构建 PDF (标题/表格/签名栏)
       ↓
保存到输出目录 → 记录报告历史

配置管理设计¶

配置文件结构¶

config/
├── config.yaml          # 主配置(应用/路径/数据库/日志等)
├── userconfig.yaml      # 用户配置(最近文件/导入历史/偏好)
└── ui.yaml              # UI配置(窗口/样式/页面布局)

配置优先级¶

环境变量 > YAML配置 > 代码默认值

配置加载特性¶

惰性加载: 配置只在首次访问时加载
缓存机制: 加载后缓存在内存中
环境变量替换: 支持 ${ENV_VAR:default} 语法
文件包含: 支持 !include 标签引用外部配置文件

数据库设计¶

核心表结构¶

表名	用途
sale_plans	销售计划原始数据
certificates	合格证信息
print_logs	打印日志
report_templates	报告模板配置
auto_number_rules	自动编号规则
auto_number_counters	自动编号计数器

自动编号特性¶

支持分组计数(按产品型号/订单号等)
支持按日/月/年重置流水号
支持自定义编号格式(前缀/日期/流水号/后缀)

日志设计¶

控制台输出: INFO级别，彩色格式
文件输出: DEBUG级别，每天轮转，保留30天，压缩为ZIP
单例模式: 全局唯一日志管理器

Excel导入特性¶

智能表头检测: 根据关键词自动识别表头行
格式保留: 支持读取单元格背景色、字体色、批注
列别名映射: 支持多种Excel列名变体
配置记忆: 按文件和工作表保存导入配置
空值规范化: 统一转换为 【空白字段名】 格式

扩展点¶

新增报告类型: 继承 ReportGenerator 并实现对应方法
新增编号规则: 在 auto_number_rules 表添加规则配置
新增数据模型: 继承 Base 定义新模型类
新增处理器: 在 handlers/ 添加独立的功能处理器
UI主题定制: 修改 ui.yaml 配置文件中的样式定义