模板参考

ExcelFlow 计划文件必须包含五个基础工作表：抽取计划、数据对象、关联关系、字段映射、过滤条件。聚合任务使用可选的分组字段和聚合规则；新版模板会创建这两张空表。旧计划没有它们仍可执行。模板还包含不参与执行的“填写说明”。读取器按第一行表头取值，请保留模板列名。

所有配置行通过“任务ID”归属于某个任务。整行为空时会被忽略。

抽取计划

字段	必填	允许值或格式	说明
任务ID	是	非空文本，本表唯一；不得含路径分隔符、Windows 非法文件名字符或控制字符，也不能为 .、..	单任务模式下即 --task 参数值；多任务模式（省略 --task）下作为输出文件名 <任务ID>.<格式>。其他工作表通过它引用任务。
启用	是	是、否	只有“是”可通过 run 执行；validate 和 preview 不受此限制。
备注	否	任意文本	不参与执行。

数据对象

一行声明源 Excel 中的一个 Sheet。每个任务必须且只能有一个主表；任务声明的其他对象必须通过“关联关系”连接。

字段	必填	允许值或格式	说明
任务ID	是	已存在的任务ID	对象所属任务。
Sheet名称	是	源 Excel 中的 Sheet 名称	区分大小写并要求完全匹配。
对象别名	是	[A-Za-z_][A-Za-z0-9_$]*	在字段引用中使用的短名称；同一任务内不可重复。
表头行	否	从 1 开始的正整数	例如 1 表示第一行是列名；空值按 1 处理。非整数或小于 1 会校验失败。
是否主表	是	是、否	每个任务必须且只能有一行填写“是”。
备注	否	任意文本	不参与执行。

源 Sheet 的每个列名去除首尾空格后，也必须符合 [A-Za-z_][A-Za-z0-9_$]*，且不得重复。该项在 run 读取源 Excel 时检查，不是 validate 的检查范围。读取后字段的完整名称为 对象别名.列名，例如 o.order_id。

关联关系

每个关联顺序连接一个右侧对象。相同任务、相同关联顺序的多行组成复合关联键。

字段	必填	允许值或格式	说明
任务ID	是	已存在的任务ID	关联所属任务。
关联顺序	是	可转换为整数的值	按数值升序执行。建议填写从 1 开始的连续正整数；当前实现实际上也接受 0 和负整数。
关联类型	是	INNER JOIN、LEFT JOIN	同一关联顺序的各行必须一致。
左侧字段	是	别名.列名	别名必须是主表或此前已连接的对象。
右侧对象	是	对象别名	必须已在“数据对象”声明，且尚未连接。
右侧字段	是	别名.列名	字段别名必须等于“右侧对象”。
备注	否	任意文本	不参与执行。

示例复合键：

关联顺序	关联类型	左侧字段	右侧对象	右侧字段
1	LEFT JOIN	o.order_id	i	i.order_id
1	LEFT JOIN	o.tenant	i	i.tenant

这两行表示 o.order_id = i.order_id AND o.tenant = i.tenant。

计划校验只检查字段引用的格式和别名关系，不读取源 Excel，因此无法提前确认关联列是否真实存在，也无法确认左右关联列的数据类型是否兼容；这些问题会在 run 时由 Pandas 报告。

字段映射

一行定义一个输出列。存在字段映射时，只输出声明的目标字段；没有任何字段映射时，输出关联、过滤后的全部字段，列名保留 别名.列名。

字段	必填	允许值或格式	说明
任务ID	是	已存在的任务ID	映射所属任务。
源字段	条件必填	别名.列名	没有“转换表达式”时必填；有表达式时可留空。
目标字段	是	[A-Za-z_][A-Za-z0-9_$]*	输出列名。
目标类型	是	integer、decimal、string、datetime	输出前执行强制类型转换。
转换表达式	否	ExcelFlow 安全表达式	填写后以表达式结果为准，忽略“源字段”。
字段顺序	否	可转换为整数的值	按数值升序输出；空值按 999999 排序。校验器当前不检查该列，非法值会在 run 时失败。
备注	否	任意文本	不参与执行。

表达式语法见 表达式参考，类型规则见 数据类型参考。当前校验器不解析表达式，也不检查表达式内部字段是否真实存在；语法、函数和字段错误会在运行时报告。当前也不检查重复的目标字段；重复名称会让后出现的映射覆盖先出现的映射，计划中应保持目标字段唯一。

过滤条件

同一“条件组”中的条件使用 AND 连接，不同条件组使用 OR 连接。没有过滤条件时保留所有关联结果。

字段	必填	允许值或格式	说明
任务ID	是	已存在的任务ID	条件所属任务。
条件组	是	可转换为整数的值	用于组织 AND/OR；按数值升序处理。校验器当前不检查该列，非法值会在 run 时失败。
条件序号	是	可转换为整数的值	同一组内按数值升序处理。校验器当前不检查该列，非法值会在 run 时失败。
字段	是	别名.列名	要判断的源字段。
运算符	是	受支持的过滤运算符	不区分大小写；模板提供下拉框。
值1	条件必填	文本、数字或日期值	除 IS NULL、IS NOT NULL 外必填。
值2	条件必填	文本、数字或日期值	仅 BETWEEN 必填。
备注	否	任意文本	不参与执行。

完整规则见 过滤运算符参考。

分组字段

分组字段决定汇总结果的粒度。例如按客户分组，结果中每个客户一行；不填写分组字段而填写聚合规则，会得到整个数据集的一行总计。空分组值会作为独立分组保留，分组保持关联及过滤后的首次出现顺序。

字段	必填	说明
任务ID	是	已存在的任务ID。
源字段	是	别名.列名。
目标字段	是	汇总结果中的列名。
目标类型	是	integer、decimal、string、datetime。
分组顺序	是	正整数，任务内不可重复；同时决定输出列顺序。
备注	否	不参与执行。

只有分组字段、没有聚合规则没有可汇总的指标，因此校验失败。

聚合规则

聚合发生在关联和过滤之后，并直接生成最终输出。聚合任务不能同时配置“字段映射”。第一版聚合源只能是真实源字段，不能填写表达式。

字段	必填	说明
任务ID	是	已存在的任务ID。
源字段	条件必填	除 count_all 外必须填写 别名.列名；count_all 必须留空。
聚合函数	是	从下表选择。
目标字段	是	汇总输出列名，不能与其他分组或聚合目标重名。
目标类型	是	integer、decimal、string、datetime。
分隔符	否	concat_agg 的连接符；空值默认英文逗号。
聚合顺序	是	正整数，任务内不可重复；决定指标列顺序。
备注	否	不参与执行。

聚合函数的最终类型由“目标类型”列决定，下表“结果”只说明语义。除 concat_agg 外，示例输入均假定 amount 为数值列。

函数	语义	结果示例
count	源字段的非空值数量。	[10, None, 7] → 2
count_all	组内总行数，包括字段为空的行；不读取源字段。	[10, None, 7] → 3
count_distinct	源字段的非空去重数量。	[10, 10, None, 7] → 2
sum	非空数值求和。	[10, None, 7] → 17
avg	跳过空值计算数值平均值。	[10, None, 7] → 8.5
min / max	跳过空值计算最小值 / 最大值。	[10, None, 7] → 7 / 10
first / last	当前输入顺序中第一个 / 最后一个非空值，不表示日期最早 / 最晚。	["x", None, "y"] → "x" / "y"
concat_agg	忽略空值，保持当前行顺序，不去重，按分隔符连接。	["x", None, "y"] → "x,y"（默认分隔符）

全空组行为：sum、avg、min、max、first、last 返回空值；concat_agg 返回空字符串；count 与 count_distinct 返回 0；count_all 返回行数。sum 与 avg 要求源字段可转为数值，否则任务失败。

一对多关联会先扩展行数，再执行聚合。统计业务对象数量时通常应对业务主键使用 count_distinct，而不是 count_all。

通用字段引用规则

字段引用固定写为：

对象别名.源Sheet列名

例如对象别名为 orders，源列为 amount：

orders.amount

对象别名和列名只能使用英文字母、数字、下划线和 $，且首字符必须是英文字母或下划线。当前不支持在字段引用中直接使用中文、空格、连字符或额外的点号。表达式还受 Python 属性语法约束，因此其中引用的别名和列名不能含 $，也不能使用会导致 Python 解析失败的关键字；详见 表达式参考。