配置体系¶

1. 配置加载机制¶

关键文件：

加载顺序：

访问方式：

from certflow.config.settings import cfg
value = cfg("import.create_placeholder_dirs", False)

文件	用途	状态
`config.yaml`	索引文件，!include 拼接	✅
`paths.yaml`	路径配置（销售计划/输出/模板/日志）	✅
`paths.local.yaml.example`	本地覆盖模板（复制为 `.local.yaml` 生效）	✅
`ui.yaml`	UI 布局、action、导航按钮	✅
`dictionaries.yaml`	字典表	✅
`sales_plan.yaml`	销售计划字段定义	✅
`grouping.yaml`	订单分组规则	✅
`certificate.yaml`	合格证模板字段	✅
`numbering.yaml`	编号规则（`{prefix}{date}{seq}`）	✅
`import.yaml`	导入参数（含 `create_placeholder_dirs`）	✅
`database.yaml`	数据库连接	✅
`logging.yaml`	日志配置	✅
`colors.yaml`	UI 颜色主题	✅
`export.yaml`	导出参数	✅
`field_rules.yaml`	字段校验规则	✅
`sales_importer.yaml`	销售计划导入器详细参数	✅
`test_report.yaml`	试压报告配置	✅
`printer.yaml`	打印机配置	✅
`print.yaml`	打印参数	✅
`output.yaml`	输出目录与命名	✅
`vba_import.yaml`	VBA 字段映射	✅
`completed_orders_backfill.yaml`	已完成订单回填	✅
`production_status.yaml`	生产状态定义（驱动 `set_status_*`）	✅
`sync.yaml`	WebDAV 同步	✅
`quarantine.yaml`	校正队列规则	✅
`report.yaml`	报告模板与命名	✅
`grade_aliases.yaml`	材质牌号别名	✅
`imperial_rules.yaml`	英制单位规则	✅
`query_fields.yaml`	查询字段定义	✅
`settings_ui.yaml`	设置界面布局	✅
`userconfig.yaml`	用户配置（运行时持久化）	✅
`userconfig.state.yaml`	用户界面状态	✅
`columns.yaml`	表格列定义	✅

# 编号格式模板，支持占位符 {prefix}、{date}、{seq}
format_template: "{prefix}{date}{seq}"

影响代码：services/cert_numbering.py、cert_numbering_policy.py、models/auto_number.py

create_placeholder_dirs: false  # B0-4，默认 OFF
# True：导入期按订单组预建 VBA 风格占位项目文件夹

影响代码：config/models.py:ImportPlaceholderConfig（L1222-1239）

驱动 actions/registry.py 中的 set_status_* 动态 action。状态值在此文件定义后，UI 右键菜单自动生成对应选项。

# 文件名占位符见 ReportOutputService._build_filename

影响代码：services/report_output_service.py

支持 ${ENV_VAR} 与 ${ENV_VAR:default}：

sales_plan_path: "${VALVE_SALES_PLAN_PATH}"
output_dir: "${CERTFLOW_OUTPUT_DIR:./output}"

本地覆盖：复制 paths.local.yaml.example 为 paths.local.yaml，无需修改版本管理的 paths.yaml。

变量	用途	默认
`VALVE_SALES_PLAN_PATH`	销售计划 Excel 路径	无
`NUTSTORE_WEBDAV_USER`	坚果云 WebDAV 用户	无
`NUTSTORE_WEBDAV_TOKEN`	坚果云 WebDAV 密码	无
`VALVE_DEBUG`	调试模式	false
`VALVE_SEED_DEBUG`	播种明细日志	跟随 VALVE_DEBUG
`CERTFLOW_DB_PATH`	数据库路径覆盖	database/debug/certflow-debug.db
`CERTFLOW_RESET`	启动时重置调试库	0
`CERTFLOW_ENV`	环境标识（testing/production）	production