certflow.config.models 源代码

"""配置数据模型

使用 Pydantic 定义配置数据结构,提供类型验证和自动补全.
"""

from typing import Any

from pydantic import BaseModel, Field, field_validator


[文档] class AppConfig(BaseModel): """应用基础配置模型 定义应用程序的基本信息,包括名称、版本、组织等元数据. Attributes: name: 应用程序名称,默认为"CertFlow" version: 应用程序版本号,默认为"2.0.0" year: 版权年份,默认为2026 organization: 组织名称,默认为"CertFlow Team" debug: 是否启用调试模式,默认为False """ name: str = "CertFlow" version: str = "2.0.0" year: int = 2026 organization: str = "CertFlow Team" debug: bool = False
class DatabasePaths(BaseModel): """数据库路径配置模型 定义数据库文件的存储目录和文件名. Attributes: dir: 数据库文件所在目录,默认为"database" name: 数据库文件名,默认为"certflow.db" """ dir: str = "database" name: str = "certflow.db" class TempPaths(BaseModel): """临时目录配置模型 定义各类临时文件的存储子目录. Attributes: base: 临时文件根目录,默认为"temp" excel: Excel临时文件目录,默认为"excel" reports: 报告临时文件目录,默认为"reports" images: 图片临时文件目录,默认为"images" scans: 扫描件临时文件目录,默认为"scans" """ base: str = "temp" excel: str = "excel" reports: str = "reports" images: str = "images" scans: str = "scans" class TemplatePaths(BaseModel): """模板路径配置模型 定义各类模板文件的存储路径. Attributes: base: 模板文件根目录,默认为"data/templates/" certificate_chinese: 中文合格证模板路径 certificate_bilingual: 中英文合格证模板路径 """ base: str = "data/templates/" certificate_chinese: str = "data/templates/中文合格证模板.xlsx" certificate_bilingual: str = "data/templates/中英文合格证模板.xlsx"
[文档] class PathsConfig(BaseModel): """路径配置集合模型 聚合所有文件路径相关的配置,包括数据库、临时文件、日志等路径. Attributes: database: 数据库路径配置 temp: 临时文件路径配置 logs: 日志文件目录,默认为"logs" resources: 资源文件目录,默认为"resources" templates: 模板文件路径配置 sales_plan: 销售计划文件路径映射(V2) qualified_list: 合格清单文件路径映射(V2) nameplate_db: 铭牌数据库路径映射(V2) quality_cert: 质量证书路径映射(V2) transfer_docs: 交接文档路径映射(V2) backup: 备份文件路径映射(V2) output: 输出文件路径映射(V2) excel_layout: Excel布局配置(V2) images: 图片文件路径映射(V2) """ database: DatabasePaths = Field(default_factory=DatabasePaths) temp: TempPaths = Field(default_factory=TempPaths) logs: str = "logs" resources: str = "resources" templates: TemplatePaths = Field(default_factory=TemplatePaths) # V2 新增路径 sales_plan: dict[str, str] | None = None qualified_list: dict[str, str] | None = None nameplate_db: dict[str, str] | None = None quality_cert: dict[str, str] | None = None transfer_docs: dict[str, str] | None = None backup: dict[str, str] | None = None output: dict[str, str] | None = None excel_layout: dict[str, Any] | None = None images: dict[str, str] | None = None
class ColumnMappingConfig(BaseModel): """列映射配置模型 定义Excel列名到数据字段的映射关系,支持直接映射和别名映射. Attributes: direct: 直接列映射,键为数据字段名,值为Excel列名 aliases: 列别名映射,键为Excel列名,值为可能的别名列表 """ direct: dict[str, str] = Field(default_factory=dict) aliases: dict[str, list[str]] = Field(default_factory=dict) class ValidRowCheck(BaseModel): """有效行检查配置模型 定义用于判断Excel行是否为有效数据的检查规则. Attributes: enabled: 是否启用有效行检查,默认为True key_fields: 用于判断行有效性的关键字段列表 """ enabled: bool = True key_fields: list[str] = Field(default_factory=list)
[文档] class SalesPlanConfig(BaseModel): """销售计划配置模型 定义销售计划Excel文件的解析规则,包括列映射、表头位置等. Attributes: column_mapping: 列映射配置 header_row: 表头所在行号(从1开始),默认为2 data_start_row: 数据起始行号(从1开始),默认为3 required_fields: 必填字段列表 valid_row_check: 有效行检查配置 """ column_mapping: ColumnMappingConfig = Field(default_factory=ColumnMappingConfig) header_row: int = 2 data_start_row: int = 3 required_fields: list[str] = Field(default_factory=list) valid_row_check: ValidRowCheck = Field(default_factory=ValidRowCheck)
class SuffixRule(BaseModel): """合格证后缀规则模型 根据关键词匹配规则生成证书编号后缀. Attributes: keywords: 触发该后缀的关键词列表 suffix: 匹配成功时使用的后缀字符串 """ keywords: list[str] suffix: str
[文档] class CertificateConfig(BaseModel): """合格证配置模型 定义合格证编号的生成规则. Attributes: prefix: 证书编号前缀,默认为"CERT" date_format: 日期格式字符串,默认为"%Y%m%d" format_template: 编号格式模板,支持{prefix}、{date}、{seq}占位符 suffix_rules: 后缀匹配规则列表 defaults: 默认值字典 """ prefix: str = "CERT" date_format: str = "%Y%m%d" format_template: str = "{prefix}{date}{seq:04d}" suffix_rules: list[SuffixRule] = Field(default_factory=list) defaults: dict[str, Any] = Field(default_factory=dict)
[文档] class ImportDeduplicationConfig(BaseModel): """导入去重配置模型 定义数据导入时的重复检测和处理策略. Attributes: strategy: 去重策略,"skip"表示跳过重复项,"overwrite"表示覆盖 check_within_file: 是否检查文件内重复,默认为True check_against_db: 是否检查与数据库重复,默认为True unique_key_fields: 用于判断唯一性的字段列表 duplicate_handling: 重复处理扩展配置(V2) unique_key_generation: 唯一键生成配置(V2) field_normalization: 字段规范化配置(V2) """ strategy: str = "skip" check_within_file: bool = True check_against_db: bool = True unique_key_fields: list[str] = Field(default_factory=list) # V2 新增: 扩展去重配置 duplicate_handling: dict[str, Any] | None = None unique_key_generation: dict[str, Any] | None = None field_normalization: dict[str, Any] | None = None
[文档] class DatabaseConfig(BaseModel): """数据库配置模型 定义数据库连接参数和行为. Attributes: type: 数据库类型,默认为"sqlite" echo: 是否打印SQL语句日志,默认为False pool_size: 数据库连接池大小,默认为5 max_overflow: 连接池最大溢出连接数,默认为10 """ type: str = "sqlite" echo: bool = False pool_size: int = 5 max_overflow: int = 10
[文档] class LoggingConfig(BaseModel): """日志配置模型 定义日志输出格式、轮转策略等参数. Attributes: level: 日志级别,可选值为DEBUG、INFO、WARNING、ERROR、CRITICAL format: 日志格式字符串 rotation: 日志文件轮转条件,如"10 MB"表示10MB轮转 retention: 日志保留时间,如"30 days"表示保留30天 compression: 日志压缩格式,默认为"zip" """ level: str = "INFO" format: str = "{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}" rotation: str = "10 MB" retention: str = "30 days" compression: str = "zip"
class WindowConfig(BaseModel): """窗口配置模型 定义应用程序主窗口的外观和行为. Attributes: title: 窗口标题,默认为"CertFlow - 证书管理系统" min_width: 窗口最小宽度,默认为1000像素 min_height: 窗口最小高度,默认为618像素 default_width: 窗口默认宽度,默认为1200像素 default_height: 窗口默认高度,默认为800像素 """ title: str = "CertFlow - 证书管理系统" min_width: int = 1000 min_height: int = 618 default_width: int = 1200 default_height: int = 800 class TableConfig(BaseModel): """表格配置模型 定义数据表格的显示行为. Attributes: alternating_row_colors: 是否使用交替行颜色,默认为True sorting_enabled: 是否启用排序功能,默认为True stretch_last_section: 是否拉伸最后一列,默认为True """ alternating_row_colors: bool = True sorting_enabled: bool = True stretch_last_section: bool = True class StatusBarConfig(BaseModel): """状态栏配置模型 定义状态栏的显示内容. Attributes: ready_message: 就绪状态显示的消息,默认为"✅ 系统就绪" """ ready_message: str = "✅ 系统就绪"
[文档] class UIConfig(BaseModel): """UI配置集合模型 聚合所有用户界面相关的配置. Attributes: window: 窗口配置 table: 表格配置 status_bar: 状态栏配置 query_page: 查询页面配置(视图模板、操作符、字段映射等) """ window: WindowConfig = Field(default_factory=WindowConfig) table: TableConfig = Field(default_factory=TableConfig) status_bar: StatusBarConfig = Field(default_factory=StatusBarConfig) query_page: dict = Field(default_factory=dict)
[文档] class ColorMappingConfig(BaseModel): """颜色映射配置模型 定义状态和优先级到颜色的映射关系. Attributes: status_colors: 状态到颜色的映射字典 priority_colors: 优先级到颜色的映射字典 vba_colors: VBA颜色索引到颜色的映射(V2) font_color_to_shipping: 字体颜色到发货状态的映射(V2) bg_color_to_status: 背景颜色到状态的映射(V2) theme_font_colors: THEME 字体颜色到状态的映射(V3) font_colors: 字体颜色 hex 字符串映射 bg_colors: 背景颜色 hex 字符串映射 """ status_colors: dict[str, str] = Field(default_factory=dict) priority_colors: dict[str, str] = Field(default_factory=dict) # V2 新增: VBA 颜色映射 vba_colors: dict[int, str] | None = None font_color_to_shipping: dict[int, str] | None = None bg_color_to_status: dict[int, str] | None = None # V3 新增: THEME 颜色和 hex 颜色映射 theme_font_colors: dict[str, str] | None = None font_colors: dict[str, str] | None = None bg_colors: dict[str, str] | None = None
# ============================================================ # V2 新增配置模型 # ============================================================
[文档] class NumberingSuffixRule(BaseModel): """编号后缀规则模型(V2新增) 根据字段值或关键词匹配规则生成编号后缀. Attributes: field: 用于匹配的字段名 keywords: 触发该后缀的关键词列表 suffix: 匹配成功时使用的后缀字符串 exclude: 排除的关键词列表,匹配时不生成后缀 """ field: str | None = None keywords: list[str] = Field(default_factory=list) suffix: str = "" exclude: list[str] | None = None
[文档] class NumberingConfig(BaseModel): """编号规则配置模型(V2新增) 定义V2版本的自动编号生成规则. Attributes: prefix: 编号前缀,默认为"V" format: 编号格式模板 suffixes: 后缀映射字典 auto_number_mode: 自动编号模式配置 suffix_rules: 后缀规则列表 """ prefix: str = "V" format: str = "{prefix}{year}{month}{seq:03d}{suffix}" suffixes: dict[str, str] = Field(default_factory=dict) auto_number_mode: dict[str, Any] | None = None suffix_rules: list[NumberingSuffixRule] = Field(default_factory=list)
[文档] class DuplicateCheckConfig(BaseModel): """重复检查配置模型(V2新增) 定义数据重复检查的字段列表. Attributes: fields: 用于重复检查的字段名列表 """ fields: list[str] = Field(default_factory=list)
[文档] class UniqueKeyField(BaseModel): """唯一键字段模型(V2新增) 定义构成唯一键的字段及其约束. Attributes: name: 字段名称 required: 该字段是否为必填,默认为False """ name: str required: bool = False
[文档] class UniqueKeyConfig(BaseModel): """唯一标识规则配置模型(V2新增) 定义唯一键的生成规则. Attributes: separator: 字段值连接符,默认为"|" date_to_serial: 是否将日期转换为序列号,默认为True fields: 构成唯一键的字段列表 key_field_fallbacks: 唯一键字段的回退映射 """ separator: str = "|" date_to_serial: bool = True fields: list[UniqueKeyField] = Field(default_factory=list) key_field_fallbacks: dict[str, list[str]] | None = None
[文档] class GroupingNumberingConfig(BaseModel): """分组序号配置""" use_global_prefix: bool = True prefix_format: str = "G{:03d}" seq_format: str = "{:03d}" separator: str = "-" full_seq_field: str = "group_seq" group_index_field: str = "_group_index" group_key_field: str = "_group_key"
[文档] class GroupingConfig(BaseModel): """分组配置(V3新增) 第一层分组:按业务键分组,生成组内序号 """ group_keys: list[str] = Field(default_factory=list) group_keys_no_project: list[str] = Field(default_factory=list) numbering: GroupingNumberingConfig = Field(default_factory=GroupingNumberingConfig)
[文档] class SortingKey(BaseModel): """排序键配置(V3新增)""" field: str order: str = "asc"
[文档] class SortingConfig(BaseModel): """排序配置(V3新增) 第二层排序:组内按产品键排序 """ keys: list[SortingKey] = Field(default_factory=list)
[文档] class PriorityRulesConfig(BaseModel): """优先级规则配置模型(V2新增) 定义基于金额的优先级判定规则和颜色. Attributes: high_threshold: 高优先级阈值,金额大于此值为高优先级,默认为10000 medium_threshold: 中优先级阈值,金额大于此值为中优先级,默认为5000 high_label: 高优先级标签,默认为"高" medium_label: 中优先级标签,默认为"中" low_label: 低优先级标签,默认为"低" high_color: 高优先级颜色(十六进制),默认为"#e74c3c" medium_color: 中优先级颜色(十六进制),默认为"#f39c12" low_color: 低优先级颜色(十六进制),默认为"#27ae60" """ high_threshold: int = 10000 medium_threshold: int = 5000 high_label: str = "高" medium_label: str = "中" low_label: str = "低" high_color: str = "#e74c3c" medium_color: str = "#f39c12" low_color: str = "#27ae60"
[文档] class ExportConfig(BaseModel): """导出配置模型(V2新增) 定义数据导出的格式和行为. Attributes: hyperlink_column: 超链接所在列号(从1开始),默认为44 hyperlink_ref_prefix: 超链接引用前缀,默认为"AR" hyperlink_width: 超链接列宽度,默认为20字符 summary: 汇总导出配置 """ hyperlink_column: int = 44 hyperlink_ref_prefix: str = "AR" hyperlink_width: int = 20 summary: dict[str, Any] | None = None
class FieldFallbackConfig(BaseModel): """字段回退链配置模型(V2新增) 占位模型,实际使用Dict[str, List[str]]表示字段回退关系. """ pass class FieldFillRule(BaseModel): """字段填充规则模型(V2新增) 占位模型,实际使用复杂的嵌套字典结构表示填充规则. """ pass
[文档] class ImportMappingConfig(BaseModel): """数据导入列映射配置模型(V2新增) 定义Excel导入时的预处理、列映射和默认值. Attributes: preprocessor: 预处理器配置 column_mapping: 列映射规则列表 default_values: 默认值映射 """ preprocessor: dict[str, Any] | None = None column_mapping: list[dict[str, Any]] | None = None default_values: dict[str, str] | None = None
[文档] class SalesImporterConfig(BaseModel): """销售计划导入器配置模型(V2新增) 定义销售计划Excel导入的字段映射和颜色列配置. Attributes: field_mapping: 字段映射字典,键为Excel列名,值为数据字段名 color_columns: 颜色列配置 selection_info_columns: 选择信息列列表 """ field_mapping: dict[str, str] = Field(default_factory=dict) color_columns: dict[str, Any] | None = None selection_info_columns: list[str] | None = None
[文档] class VBAImportConfig(BaseModel): """VBA导入逻辑配置模型(V2新增) 定义VBA导入功能的文件路径、字段映射和重复检查规则. Attributes: sales_plan_files: 销售计划文件路径映射 qualified_list: 合格清单文件路径映射 field_mapping: 字段映射字典 color_mapping: 颜色映射配置 duplicate_check_fields: 重复检查字段列表 """ sales_plan_files: dict[str, str] | None = None qualified_list: dict[str, str] | None = None field_mapping: dict[str, str] = Field(default_factory=dict) color_mapping: dict[str, Any] | None = None duplicate_check_fields: list[str] | None = None
class CertificatePrintTemplate(BaseModel): """合格证打印模板字段模型(V2新增) 定义单个字段在打印模板中的位置映射. Attributes: excel_row: 在Excel中的行号 vba_col: 在VBA中的列索引 field_name: 字段名称 """ excel_row: int vba_col: int field_name: str
[文档] class CertificatePrintTemplateConfig(BaseModel): """合格证打印模板配置模型(V2新增) 定义完整打印模板的配置. Attributes: name: 模板名称 style_code: 样式代码,默认为1 picture_options: 图片选项列表 fields: 模板字段列表 """ name: str = "" style_code: int = 1 picture_options: list[str] | None = None fields: list[CertificatePrintTemplate] = Field(default_factory=list)
[文档] class CertificatePrintConfig(BaseModel): """合格证打印配置模型(V2新增) 定义合格证打印的打印机、打印区域、批处理等配置. Attributes: printer: 打印机配置 print_area: 打印区域配置 batch: 批处理配置 templates: 模板配置字典 numbering_modes: 编号模式映射 """ printer: dict[str, Any] | None = None print_area: dict[str, str] | None = None batch: dict[str, Any] | None = None templates: dict[str, CertificatePrintTemplateConfig] | None = None numbering_modes: dict[str, int] | None = None
[文档] class TestReportConfig(BaseModel): """试压报告配置模型(V2新增) 定义试压报告的相关配置. Attributes: company_name: 公司名称 form_code: 表单代码 """ company_name: str = "" form_code: str = ""
[文档] class PrinterConfig(BaseModel): """打印机配置模型(V2新增) 定义默认打印机设置. Attributes: default: 默认打印机名称 """ default: str = ""
[文档] class EnvironmentConfig(BaseModel): """环境信息配置模型(V2新增) 定义运行时环境信息,支持环境变量替换. Attributes: computer_name: 计算机名称,支持${COMPUTERNAME:Unknown}语法 username: 用户名,支持${USERNAME:Unknown}语法 """ computer_name: str = "${COMPUTERNAME:Unknown}" username: str = "${USERNAME:Unknown}"
[文档] class ColorsConfig(BaseModel): """颜色常量值配置模型(V2新增) 定义VBA中使用的颜色常量值. Attributes: yellow: 黄色的RGB整数值,默认为65535 blue: 蓝色的RGB整数值,默认为16711680 red: 红色的RGB整数值,默认为255 green: 绿色的RGB整数值,默认为65280 light_blue: 浅蓝色的RGB整数值,默认为15773696 """ yellow: int = 65535 blue: int = 16711680 red: int = 255 green: int = 65280 light_blue: int = 15773696
[文档] class ImageBackgroundsConfig(BaseModel): """图片背景配置模型(V2新增) 定义不同语言版本的证书背景图片路径. Attributes: chinese: 中文版背景图片路径 bilingual: 中英文双语版背景图片路径 russian: 俄文版背景图片路径 """ chinese: str = "" bilingual: str = "" russian: str = ""
[文档] class CompletedOrdersBackfillConfig(BaseModel): """已完成工单回填配置模型 定义从"已完成工单"Excel的月份工作表中读取"供货类型"字段并回填到数据库的规则。 核心设计: - 只处理月份工作表(2026-01~2026-12) - 按字段名称(列标题)匹配,不依赖列号/列字母 - 通过 production_order_no 匹配(同一生产令号所有记录回填相同值) """ file_path: str = "temp/excel/已完成工单【202601--202612】.xlsx" match_field: str = "生产令号" # Excel 中用于匹配的列名 source_field: str = "供货类型" # Excel 中要读取的源字段列名 db_match_field: str = "production_order_no" # DB 匹配字段 db_target_field: str = "supply_type" # DB 目标字段 overwrite_existing: bool = False backup_before_update: bool = True backup_suffix: str = "_before_supply_type_backfill"
[文档] class RootConfig(BaseModel): """根配置模型 所有配置的顶层容器,聚合所有子配置模块. Attributes: app: 应用基础配置 paths: 路径配置 sales_plan: 销售计划配置 sort_rules: 排序规则配置 certificate: 合格证配置 import_deduplication: 导入去重配置 database: 数据库配置 logging: 日志配置 ui: UI配置 color_mapping: 颜色映射配置 numbering: 编号规则配置(V2) duplicate_check: 重复检查配置(V2) unique_key: 唯一键配置(V2) priority_rules: 优先级规则配置(V2) group_by: 分组规则配置(V2) export: 导出配置(V2) sales_plan_fill: 销售计划填充配置(V2) field_fallbacks: 字段回退链配置(V2) field_fill_rules: 字段填充规则配置(V2) sales_importer: 销售计划导入器配置(V2) qualified_list: 合格清单配置(V2) import_mapping: 导入列映射配置(V2) export_debug: 导出调试配置(V2) test_report: 试压报告配置(V2) printer: 打印机配置(V2) environment: 环境信息配置(V2) colors: 颜色常量配置(V2) image_backgrounds: 图片背景配置(V2) templates: 顶层模板配置(V2) vba_import: VBA导入配置(V2) certificate_print: 合格证打印配置(V2) """ app: AppConfig = Field(default_factory=AppConfig) paths: PathsConfig = Field(default_factory=PathsConfig) sales_plan: SalesPlanConfig = Field(default_factory=SalesPlanConfig) certificate: CertificateConfig = Field(default_factory=CertificateConfig) import_deduplication: ImportDeduplicationConfig = Field( default_factory=ImportDeduplicationConfig ) database: DatabaseConfig = Field(default_factory=DatabaseConfig) logging: LoggingConfig = Field(default_factory=LoggingConfig) ui: UIConfig = Field(default_factory=UIConfig) color_mapping: ColorMappingConfig = Field(default_factory=ColorMappingConfig) # V2 新增顶层配置段(全部 Optional,保持向后兼容) numbering: NumberingConfig | None = None duplicate_check: DuplicateCheckConfig | None = None unique_key: UniqueKeyConfig | None = None priority_rules: PriorityRulesConfig | None = None export: ExportConfig | None = None sales_plan_fill: dict[str, Any] | None = None field_fallbacks: dict[str, list[str]] | None = None field_fill_rules: dict[str, Any] | None = None sales_importer: SalesImporterConfig | None = None qualified_list: dict[str, Any] | None = None import_mapping: ImportMappingConfig | None = None export_debug: dict[str, Any] | None = None test_report: TestReportConfig | None = None printer: PrinterConfig | None = None environment: EnvironmentConfig | None = None colors: ColorsConfig | None = None image_backgrounds: ImageBackgroundsConfig | None = None templates: dict[str, Any] | None = None # V2 顶层 templates vba_import: VBAImportConfig | None = None certificate_print: CertificatePrintConfig | None = None completed_orders_backfill: CompletedOrdersBackfillConfig | None = None query_page: dict[str, Any] = Field(default_factory=dict) # V3 新增分组排序配置 grouping: GroupingConfig | None = None sorting: SortingConfig | None = None
[文档] @field_validator("logging") @classmethod def validate_log_level(cls, v: LoggingConfig) -> LoggingConfig: """验证日志级别是否有效 Args: v: 待验证的日志配置对象 Returns: LoggingConfig: 验证通过的日志配置对象 Raises: ValueError: 当日志级别不在有效值范围内时抛出 """ valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"} if v.level.upper() not in valid_levels: raise ValueError(f"Invalid log level: {v.level}") return v
# 导出所有模型 __all__ = [ "RootConfig", "AppConfig", "PathsConfig", "SalesPlanConfig", "CertificateConfig", "ImportDeduplicationConfig", "DatabaseConfig", "LoggingConfig", "UIConfig", "ColorMappingConfig", # V2 新增 "NumberingConfig", "NumberingSuffixRule", "DuplicateCheckConfig", "UniqueKeyConfig", "UniqueKeyField", "PriorityRulesConfig", "ExportConfig", "SalesImporterConfig", "VBAImportConfig", "CertificatePrintConfig", "CertificatePrintTemplateConfig", "TestReportConfig", "PrinterConfig", "EnvironmentConfig", "ColorsConfig", "ImageBackgroundsConfig", "ImportMappingConfig", # V3 新增 "GroupingConfig", "GroupingNumberingConfig", "SortingConfig", "SortingKey", "CompletedOrdersBackfillConfig", ]