# Step1 数据聚合

## 目标

以 `data/templates/metadata` 中的模板为目标结构，依据模板内显式声明的 DMS
模型与字段映射，从对应模型的状态 0、1、2、3 取数并生成 Step2 可读取的生产 Excel。

## 当前资产

- `data/templates/metadata/*.xlsx`：节点模板及 DMS 字段映射；当前为人员信息、项目信息两份。
- `data/production/*.xlsx`：依据模板实时生成的实际数据（运行产物，不纳入版本控制）。
- `data/production/fetch_report.json`：每份模板的模型、字段数和记录数报告。
- `data/production/analysis/*.analysis.json`：确定性字段画像与结构化 LLM 评估。
- `data/production/analysis/*.analysis.md`：供人工阅读的数据质量报告。
- `data/production/analysis/qa_data_context.json`：供 QA Agent 加载的精简参考上下文。
- `output/模板_源数据_DMS字段关联.csv`：既有三方字段关联参考。
- `data/manual_fill/DMS补数字段清单.csv`：既有人工补填字段清单。

## 代码拆分

- `dms_client.py`：复用 Step0 鉴权，自动发现 DMS 代理路径，解析栏目/模型并按状态 0、1、2、3 串行分页读取数据。
- `template_mapping.py`：动态扫描模板，读取并校验“字段映射”工作表。
- `dms_pipeline.py`：校验 DMS 字段、按模板列顺序输出 Excel 和取数报告。
- `data_analysis.py`：逐文件统计字段质量、调用 LLM，并输出报告与 QA 上下文。
- `scripts/fetch_dms_production.py`：只负责命令行参数与结果摘要。
- `models.py`：既有聚合协议。

模板规则只存在于 Excel 中，不散落在 DMS 请求、Excel 写出或问答代码中。

## 模板驱动的 DMS 全生命周期数据导出

```powershell
uv run python scripts/fetch_dms_production.py
```

运行规则：

1. 扫描全部 `.xlsx` 模板，不维护模板白名单。
2. 每行映射必须提供 `模板字段`、`DMS模型`、`DMS字段` 和 `含义`。
3. 根据模型完整路径动态查找栏目和模型，不写死栏目 ID、模型 ID、模板名或字段名。
4. 按 `states=0、1、2、3` 依次串行请求内容接口并分别自动分页，再按状态顺序合并；不获取销毁和退回数据。
5. 输出列及顺序完全来自模板；DMS 字段缺失、模型歧义或重复映射时立即失败。
6. 对每个实际数据文件计算缺失率、唯一值、重复数、类型分布和范围，再调用 LLM 生成业务含义、质量问题及 QA 使用建议。
   同时检测完全重复行与最多三字段的最小唯一组合，供 LLM 判断数据粒度、记录唯一性依据
   （候选业务主键）以及 1:1、1:N、N:M 等基数关系；统计唯一不能直接视为业务主键。
7. LLM 输入不包含原始单元格值；统计事实与 LLM 建议在结果中分开保存。
8. DMS 取数保持串行；全部生产 Excel 生成后，逐文件画像与 LLM 调用使用有界并发，
   并发数由 `.env` 的 `STEP1_ANALYSIS_MAX_WORKERS` 控制（默认 3）。每份 Excel 独立生成
   `.analysis.json` 和 `.analysis.md`。

因此，按现有格式新增/删除模板或增删字段，不需要调整 Python 代码。当前每份模板只允许
映射一个 DMS 模型；若未来一份模板需要组合多个模型，必须先在模板规范中增加连接键和连接规则。

## 完成条件

真实 DMS 可稳定分页拉取；模板声明字段在目标模型中存在；输出列与模板完全一致；
报告列出模板、模型、字段数和记录数。后续跨来源合并仍需补充连接键、转换和缺失处理规则。

## QA Agent 接入

QA Agent 在构建 schema context 时自动读取 `qa_data_context.json`。该内容只用于字段理解、
查询规划和数据局限解释，不能替代知识图谱查询结果，也不能扩展可用工具。
分析上下文也向 QA Agent 提供“一行代表什么”、候选业务主键和基数关系，帮助其避免
把人员与证书等一对多数据误解为一人一条。

每份评估会生成动态路由词。QA Agent 按当前用户问题匹配数据集名、路由词和字段，只注入
匹配报告；跨数据集问题可注入多份，未匹配时不注入评估上下文，绝不默认加载全部报告。
当前数据模式不再生成旧月度派生文件，`monthly.py` 与 `scripts/build_monthly_data.py` 已删除。