# 04b 查询与字段补充流程

> 状态：✅ 已实现 | ⚙️ 配置驱动

## 1. 操作入口

| 方式 | 入口 |
|------|------|
| GUI | 导航栏「查询与补充」→ `QueryView` |
| CLI | `certflow quick-query [options]` |

## 2. 涉及配置

| 配置文件 | 关键字段 | 说明 |
|----------|----------|------|
| `config/query_fields.yaml` | 字段定义 | 查询可用字段、标签、占位提示 |
| `config/production_status.yaml` | 状态枚举 | 驱动 `set_status_*` 右键菜单 |
| `config/sales_plan.yaml` | 字段映射 | 表格列定义 |
| `config/columns.yaml` | 列宽/可见性 | 表格显示 |
| `config/colors.yaml` | 状态颜色 | 行高亮 |

## 3. 涉及代码文件

| 层 | 文件 | 职责 |
|----|------|------|
| View | `views/query_view.py` | 主查询视图（表格 + 工具栏 + 右键菜单） |
| View | `views/query_hub_view.py` | 查询中心 |
| View | `views/sale_plan_query_view.py` | 销售计划查询 |
| Controller | `controllers/query_controller.py` | 查询编排、字段编辑 |
| Service | `services/query_service.py` | 查询执行 |
| Service | `services/query_builder.py` | 多条件查询构建器 |
| Service | `services/workflow_service.py` | 生产状态推断（`StatusInference`） |
| Widget | `widgets/filter_bar.py` | 过滤栏 |
| Widget | `widgets/filter_row.py` | 单行过滤条件 |
| Widget | `widgets/quick_search.py` | 快速搜索框 |
| Widget | `widgets/quick_search_preset.py` | 快查预设 |
| Model | `models/sale_plan.py` | 销售计划表 |

## 4. 逐步流程

### 4.1 查询

1. **进入查询页**：导航「查询与补充」
2. **设置过滤条件**（`FilterBar` + `FilterRow`）：
   - 选择字段（下拉，来自 `query_fields.yaml`）
   - 选择操作符（等于/包含/范围/...）
   - 输入值（支持占位提示）
3. **快速搜索**（`QuickSearch`）：在快查框输入关键字，按字段模糊匹配
4. **执行查询**：action `search` → `QueryService` → `QueryBuilder` 构建 SQL
5. **查看结果**：表格展示，支持排序、交替行色、列拉伸

### 4.2 字段补充（右键菜单 / 工具栏）

| 操作 | action | 说明 |
|------|--------|------|
| 批量填写计划号 | `fill_plan_no` | `_batch_fill_plan_no` |
| 设置年月前缀 | `set_year_month` | 弹窗输入 |
| 复制合同信息到合格证字段 | `copy_cert_info` | `_copy_cert_info` |
| 编辑合格证字段 | `edit_cert_fields` | `_edit_cert_fields` |
| 编辑合格证 | `edit_certificate` | `_edit_certificate` |
| 批量更新生产状态 | `batch_update_status` | `_batch_update_production_status` |
| 设置生产状态 | `set_status_<值>` | 配置驱动，前缀通用 action |
| 设置供货类型 | `set_supply_type_<值>` | 配置驱动（make/buy/repair） |
| 标记已检验 | `mark_inspected` | `_action_mark_inspected` |
| 标记已驳回 | `mark_rejected` | `_action_mark_rejected` |
| 切换需编号 | `toggle_needs_numbering` | `_action_toggle_needs_numbering` |
| 标记文档完成 | `mark_certificate_done` / `mark_nameplate_done` / `mark_test_report_done` / `mark_warranty_done` | `_action_mark_document_done` |

### 4.3 选择操作

| 操作 | action |
|------|--------|
| 全选 | `select_all` → `_action_select_all` |
| 反选 | `invert_selection` → `_invert_selection` |
| 隐藏选中 | `hide_selected` → `_action_hide_selected` |
| 隐藏行 | `hide_rows` → `_action_hide_rows` |
| 删除行 | `delete_rows` → `_delete_selected_records` |
| 返回首页 | `back_home` → `_go_back_home` |

### 4.4 导航跳转

从查询页可直接跳转到打印/报告：

- `goto_print` → `_goto_print`
- `print_certificates` → `_print_certificates`
- `preview_certificate` → `_preview_certificate`
- `export_selected` → `_export_selected`

## 5. 生产状态推断

`StatusInference`（`services/workflow_service.py`）在启动时从 `config.yaml` 加载规则，根据销售计划记录的字段组合自动推断生产状态。规则配置驱动，无需改代码即可调整推断逻辑。

## 6. CLI 查询

```bash
certflow quick-query --status 待生产 --month 202608
certflow stats --by status
certflow stats --by customer --month 202608
```

## 7. 批量更新

```bash
certflow batch-update --field supply_type --value make --filter "status=待生产"
```

对应 GUI 的 `batch_update` action。

## 8. 常见问题

- **查询慢**：确认 `sale_plan` 表有索引；大量数据时用 `--month` 缩小范围
- **字段不显示**：检查 `query_fields.yaml` 是否声明该字段
- **状态切换无效**：检查 `production_status.yaml` 是否定义该状态值