# 配置体系

## 1. 配置加载机制

**关键文件**：

- `src/certflow/config/loader.py` — 加载器，支持 `!include` 指令
- `src/certflow/config/settings.py` — 全局配置访问入口
- `src/certflow/config/models.py` — pydantic 配置模型定义
- `src/certflow/config/paths_override.py` — 本地路径覆盖（`paths.local.yaml`）

**加载顺序**：

1. 读取 `config/config.yaml`（索引文件）
2. 解析 `!include` 拼接所有子配置
3. 展开环境变量占位符 `${ENV_VAR}` 或 `${ENV_VAR:default}`
4. 校验为 pydantic 模型实例
5. `paths.local.yaml`（若存在）覆盖 `paths.yaml`

**访问方式**：

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

## 2. 配置文件速查

| 文件 | 用途 | 状态 |
|------|------|------|
| `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` | 表格列定义 | ✅ |

## 3. 关键配置项详解

### 3.1 编号规则（numbering.yaml）

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

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

### 3.2 导入占位目录（import.yaml）

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

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

### 3.3 生产状态（production_status.yaml）

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

### 3.4 报告命名（report.yaml）

```yaml
# 文件名占位符见 ReportOutputService._build_filename
```

影响代码：`services/report_output_service.py`

### 3.5 路径配置（paths.yaml）

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

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

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

## 4. 环境变量（.env）

| 变量 | 用途 | 默认 |
|------|------|------|
| `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 |

## 5. 修改配置生效条件

| 修改类型 | 是否需重启 | 说明 |
|----------|-----------|------|
| `config/*.yaml` | 是 | 启动时加载一次 |
| `.env` | 是 | start.sh 阶段0.8 读取 |
| `paths.local.yaml` | 是 | 同 yaml |
| `userconfig.yaml` | 否（运行时持久化） | 设置界面修改即生效 |
| `templates/*` | 否（每次打印/报告读取） | 修改模板立即生效 |