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 全生命周期数据导出

uv run python scripts/fetch_dms_production.py

运行规则：

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

step1-data-aggregation.md 4.3 KB Historie Surový