@finebi/finebi-cli 1.2.1 → 1.4.0

package/skills/finebi-cli-agent/references/formula-parameters-analysis.md

@@ -0,0 +1,223 @@
+# DEF、LOD、窗口与引用函数参数详解
+
+本册解释参数本身及其组合规则。业务示例见 [分析模板](formula-recipes-analysis.md)，引擎与使用位置见 [使用边界](formula-help-boundaries.md)。数组 `[]` 是实际语法；签名文字中的“可省略”不代表用 NULL 占位。
+
+## 1. DEF 家族
+
+### DEF
+
+`DEF(metric, [dimension1, dimension2, ...], [filter1, filter2, ...])` · [原文](https://help.fanruan.com/finebi/doc-view-1986.html)
+
+| 位置 | 参数 | 必填与类型 | 详细规则 |
+|---|---|---|---|
+| 1 | `metric` 聚合指标 | 必填，只能有一个聚合指标表达式 | 支持嵌套，但最终必须满足聚合指标性质；直接使用明细计算指标会报“分析函数中不支持明细计算指标”。不是把多个指标以逗号逐个传入 |
+| 2 | `dimensions` 指定维度 | 可省略或 `[]`；维度字段/维度表达式组成的数组 | 仅按显式指定维度聚合，不自动继承分析区维度。空维度表示整表聚合。仅一个维度时允许不加数组括号；生成时统一数组形式 |
+| 3 | `filters` 过滤条件 | 可省略或为空；条件表达式数组 | 支持明细级过滤、DEF 输出指标的过滤；不支持直接把聚合函数表达式作为过滤条件。同层多个过滤以“且”连接，仅一个过滤时允许不加数组括号 |
+
+需要过滤但没有维度时，第二参必须占位：`DEF(SUM_AGG(${销售额}), [], [${年份}=2025])`。省略过滤指没有**函数内新增过滤**，并不自动清掉组件/仪表板过滤；要控制界面过滤需使用 CLEAN。
+
+逐参例：`DEF(SUM_AGG(${销售额}), [${省份},${产品}], [${年份}=2025])` 中，第一参指定“求和销售额”，第二参指定“每个省份和产品组合”，第三参指定“仅 2025 年”。`DEF(SUM_AGG(${销售额}))` 则不按维度拆分。
+
+仅自助分析主题。原文的“支持任意函数输出指标”仍受参数聚合性质和嵌套限制约束；例如 DEF 输出再参与上层指标时，需要形成合法聚合表达式。单一公式 DEF 嵌套上限由管理员设置，[使用须知](https://help.fanruan.com/finebi/doc-view-2549.html)说明默认 4 层，不应写成不可变硬上限。
+
+### DEF_ADD
+
+`DEF_ADD(metric, [dimension1, ...], [filter1, ...])` · [原文](https://help.fanruan.com/finebi/doc-view-1987.html)
+
+- `metric`：必需的一个聚合指标，可嵌套合法指标表达式；不能直接传明细计算指标。
+- `dimensions`：要**追加**到分析区维度中的维度数组；`[]` 表示不追加，保留分析区全部维度。单维度可裸写。原文明确空数组形式，生成时用 `[]` 表达“无追加维度”。
+- `filters`：可省略的过滤数组；明细条件或 DEF 输出指标条件，同层条件按“且”；不支持直接聚合函数条件。无追加维度而有过滤时用 `DEF_ADD(metric, [], [filters])`。
+- 维度参数不能嵌入 ADD_DIM/SUB_DIM 引用函数；仅自助主题，不支持自助数据集、明细表，也不能输出为维度字段。6.0.13 起自动合计使用当前合计视图维度。
+
+### DEF_SUB
+
+`DEF_SUB(metric, [dimension1, ...], [filter1, ...])` · [原文](https://help.fanruan.com/finebi/doc-view-1990.html)
+
+- `metric`：必需的一个聚合指标，支持合法嵌套；不能直接传明细计算指标。
+- `dimensions`：要从分析区维度中**排除**的维度数组；不是保留维度。`[]` 表示不排除，仍按分析区维度聚合；单维度可裸写。
+- `filters`：可省略的过滤数组；支持明细条件及 DEF 输出指标条件，同层按“且”；不直接接受聚合函数条件。无排除维度而有过滤时保留第二参 `[]`。
+- 不支持在维度参数中使用 ADD_DIM/SUB_DIM；仅自助主题，不支持自助数据集、明细表及输出为维度。6.0.13 起自动合计使用合计视图维度。
+
+### EARLIER
+
+`EARLIER(field)` · [原文](https://help.fanruan.com/finebi/doc-view-1991.html)
+
+- `field`：唯一且必需的字段列，读取外层当前行在该列的值；原文明确不支持常量。它不是“上一行”，也没有行偏移量第二参。
+- 只用于 DEF/DEF_ADD/DEF_SUB 中的行间过滤；例如 `${排名}+1=EARLIER(${排名})` 才通过条件定位上一名。
+- 官方 [SUB_DIM 应用](https://help.fanruan.com/finebi/doc-view-2624.html)另有 `EARLIER(SUB_DIM(...))`。本项目校验允许非聚合字段表达式（disAgg），不接受聚合或纯常量；该扩展与单字段入门签名分开理解。
+
+### CLEAN
+
+`CLEAN(field1, field2, ...)` 或 `CLEAN("ALL")` · [原文](https://help.fanruan.com/finebi/doc-view-2407.html)
+
+- `field1, field2, ...`：需要忽略过滤的字段引用，可为任意类型维度、指标、计算指标；逐个以逗号列出，至少一个。不是字段名字符串数组。
+- `"ALL"`：独立的特殊文本形式，表示当前分析函数涉及的所有字段；不省略参数，不将 `CLEAN()` 当 ALL，也不混写 ALL 与字段参数。
+- 必须作为 DEF 家族第三参中的**独立过滤项**，如 `[CLEAN(${月份}), ${月份}=7]`。它不是一个可任意嵌套的布尔比较函数。
+- 字段形式可忽略组件过滤器/钻取及部分仪表板过滤组件产生的字段过滤，不能清联动/跳转，也不覆盖树和复合过滤组件；ALL 范围更广。两者均不清权限、调度等组件/仪表板外过滤，同层显式条件及内外层 DEF 条件仍有效。完整范围见 [过滤边界](formula-help-boundaries.md#4-def-与过滤范围)。
+
+### CLEAN_WIDGET
+
+`CLEAN_WIDGET(field1, field2, ...)` 或 `CLEAN_WIDGET("ALL")` · [原文](https://help.fanruan.com/finebi/doc-view-2408.html)
+
+- `field1, field2, ...`：组件内要忽略过滤的字段，可为任意类型维度/指标，包括计算指标；至少一个，不可省略。
+- `"ALL"`：忽略当前分析函数中所有字段的**组件内**过滤；不能将其理解为忽略整个仪表板过滤。
+- 作为 DEF 家族独立过滤项使用；仪表板联动、跳转和过滤组件仍生效，嵌套/同层过滤规则与 CLEAN 一致。CLEAN 与 CLEAN_WIDGET 均自 6.1 提供，仅自助主题。
+
+## 2. LOD 表达式
+
+LOD 不是圆括号函数。外层用 `{}`，维度之间用英文逗号，维度与聚合表达式之间用 `:`，**没有 DEF 的第三个过滤参数**。仅标准分析主题；本项目其他性质和层数校验见 [合法性约束](formula-validation.md)。
+
+### FIXED
+
+`{FIXED dimension1, dimension2, ... : aggregate_expression}` · [原文](https://help.fanruan.com/finebi/doc-view-2770.html)
+
+- `dimensions`：可省略的指定维度列表；仅使用此列表，不继承视图维度。省略后写 `{FIXED : SUM_AGG(${金额})}`，表示整表聚合；无需写 `[]`。
+- `aggregate_expression`：必需的聚合指标计算，如 SUM_AGG、COUNTD_AGG；支持符合目标校验的 LOD 嵌套。不能把明细字段直接放在冒号后冒充聚合表达式。
+
+### INCLUDE
+
+`{INCLUDE dimension1, dimension2, ... : aggregate_expression}` · [原文](https://help.fanruan.com/finebi/doc-view-2772.html)
+
+- `dimensions`：可省略的**追加维度**列表，与当前分析区维度共同聚合；省略时保留当前视图维度，不是整表聚合。
+- `aggregate_expression`：必需的聚合指标表达式，支持合法 LOD 嵌套。
+- 原文参数表误写 EXCLUDE/“排除”，这里按正文与 INCLUDE 实例确定为“追加”；空参示例也明确仍按省份视图计算。不能复制错误表头生成语法。
+
+### EXCLUDE
+
+`{EXCLUDE dimension1, dimension2, ... : aggregate_expression}` · [原文](https://help.fanruan.com/finebi/doc-view-2771.html)
+
+- `dimensions`：可省略的**排除维度**列表；实际粒度为当前视图维度减去此列表。省略表示不排除任何维度，保留当前视图粒度。
+- `aggregate_expression`：必需的聚合指标表达式，支持合法 LOD 嵌套。
+- 原文参数表把空维度误写成整表聚合；本册按同页 `{EXCLUDE : ...}` 的明确示例解释为常规视图聚合。需要整体值时使用 FIXED 空维度。
+
+## 3. WINDOW 窗口函数
+
+### 共用的四个实参位置
+
+以下六个官方函数均为 **4 个位置参数**。原文将排序字段和排序方式分列成“参数3/4”，那是解释项目；它们实际同在第三个数组内，不能拆成两个实参。[官方总说明](https://help.fanruan.com/finebi/doc-view-2470.html)
+
+`WINDOW_XXX(metric, [group1, group2, ...], [sort1, "asc", sort2, "desc", ...], [upper, lower])`
+
+| 位置 | 内容 | 类型、可选性与默认值 |
+|---|---|---|
+| 1 | `metric` | 必需的聚合指标表达式，不可为空；在窗口内对各行的这个指标再次计算 |
+| 2 | `groups` | 可省略的分区字段数组；省略或 `[]` 不按任何字段分区，将整个当前视图作为一组 |
+| 3 | `sorts` | 可省略的排序数组；省略按默认顺序。显式写成 `[字段1,"asc",字段2,"desc"]`；排序方式仅 asc/desc。也可省略**全部**排序方式，例如 `[字段1,字段2]`，均按升序；不能只省略其中某一个方式 |
+| 4 | `bounds` | 可省略的两个边界数组；默认 `["first","last"]`，即整个分区。边界为数值常量或特殊文本 first/last |
+
+`upper` 是窗口开始行，`lower` 是窗口结束行；`"first"`/`"last"` 是分区第一/末行，`0` 当前行，`-n` 前 n 行，`n` 后 n 行。要写第四参而不分区、不自定义排序时，保留位置为 `metric, [], [], [upper,lower]`；实际生成按目标校验确认空数组处理。
+
+| 窗口 | 口径 |
+|---|---|
+| `[-2,0]` | 前两行至当前行；每月一行且月份连续才等同近三个月 |
+| `[-1,-1]` | 仅上一行 |
+| `[0,0]` | 仅当前行 |
+| `["first",0]` | 从分区起点累计至当前行 |
+| `[0,"last"]` | 当前行至分区末尾 |
+
+指标、分区、排序都基于当前分析视图，维度须来自该视图；嵌入 DEF 时对应 DEF 的独立视图。原文要求聚合性质，不等于给每个分组维度外包 SUM_AGG。窗口输出聚合字段，在数据集/明细表使用需经 DEF 输出明细结果。自 6.1.2 提供，直连还受数据库支持限制。
+
+### WINDOW_SUM
+
+`WINDOW_SUM(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2477.html)
+
+- `metric`：必需，窗口内要相加的聚合指标。
+- `groups`：可选分区数组，决定在哪些组内分别求和；默认整个视图。
+- `sorts`：可选排序数组，决定累计/前后行顺序；默认顺序及方式见共用契约。
+- `bounds`：可选窗口边界，默认整分区求和；累计必须显式写 `["first",0]`，不能将省略边界当作累计。
+
+### WINDOW_AVG
+
+`WINDOW_AVG(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2472.html)
+
+- `metric`：必需，在窗口行之间求平均的聚合指标。
+- `groups`：可选分区数组，默认整个视图。
+- `sorts`：可选排序数组，决定移动窗口行顺序，按共用契约提供字段/方式。
+- `bounds`：可选边界，默认整分区；移动三行平均用 `[-2,0]`。它平均的是各行聚合结果，不是自动按明细记录数加权。
+
+### WINDOW_MAX
+
+`WINDOW_MAX(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2473.html)
+
+- `metric`：必需，从窗口各行的聚合指标中取最大值。
+- `groups`：可选分区数组，默认整个视图。
+- `sorts`：可选排序数组，方式和省略规则同共用契约。
+- `bounds`：可选起止边界，默认整分区；`[-2,0]` 表示取当前及前两行指标的最大值。
+
+### WINDOW_MIN
+
+`WINDOW_MIN(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2474.html)
+
+- `metric`：必需，从窗口各行的聚合指标中取最小值。
+- `groups`：可选分区数组，默认整个视图。
+- `sorts`：可选排序数组，方式和省略规则同共用契约。
+- `bounds`：可选起止边界，默认整分区；`[-2,0]` 表示取当前及前两行指标的最小值。
+
+### WINDOW_STDEV
+
+`WINDOW_STDEV(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2475.html)
+
+- `metric`：必需，用窗口各行的聚合指标计算标准差。
+- `groups`：可选分区数组，默认整个视图。
+- `sorts`：可选排序数组，方式和省略规则同共用契约。
+- `bounds`：可选边界，默认整分区。原文没有样本/总体切换参数，不添加第五参，也不仅凭 STDEV_AGG 的说明推断本函数的统计分母。
+
+### WINDOW_VAR
+
+`WINDOW_VAR(metric, groups, sorts, bounds)` · [原文](https://help.fanruan.com/finebi/doc-view-2476.html)
+
+- `metric`：必需，用窗口各行的聚合指标计算方差。
+- `groups`：可选分区数组，默认整个视图。
+- `sorts`：可选排序数组，方式和省略规则同共用契约。
+- `bounds`：可选边界，默认整分区；原文未细述样本/总体分母，没有额外模式参数。
+
+### WINDOW_MEDIAN（实例补充）
+
+`WINDOW_MEDIAN(metric, groups, sorts, bounds)` 来自本项目既有 Spider 实例参考，官方专题的窗口总览仅列上面六种汇总函数。
+
+- `metric`：窗口中求中位数的聚合指标；`groups` 为分区数组、`sorts` 为排序数组、`bounds` 为窗口边界数组。
+- 这四个位置按既有实例契约理解；本次没有独立官方参数页可证明全部默认值或类型边界，使用前查目标面板和校验，不宣称所有 FineBI 环境通用。
+
+### RANK_AGG
+
+`RANK_AGG([group1, ...], [sort1, "asc", sort2, "desc", ...], "mode")` · [原文](https://help.fanruan.com/finebi/doc-view-2478.html)
+
+- 第 1 参 `groups`：可省略的**排名分区**字段数组，默认整个视图；不是“要相互比较的对象列表”。视图每地区一行且想比较各地区，传 `[]`，不能按地区自身分区。
+- 第 2 参 `sorts`：可省略的排名字段和排序方式数组，省略按默认顺序。方式为 asc/desc；省略方式时必须全部省略，默认为升序。本项目排序字段须为聚合结果，不能用 TOTAL 等表格计算结果；官方参数表称“明细级别”，须结合其 WINDOW 注意事项和 SUM_AGG 示例理解。
+- 第 3 参 `mode`：可省略文本，默认 `"COMMON"`；四种值见下表。排序方式在第二参内，mode 是第三参，不存在第四个窗口边界参数。
+
+| mode | 排序值 23、45、45、76 的升序排名 | 并列口径 |
+|---|---|---|
+| `"COMMON"` | 1、2、2、4 | 并列同名次，占后续位置 |
+| `"DENSE"` | 1、2、2、3 | 并列同名次，不跳号 |
+| `"UNIQUE"` | 1、2、3、4 | 每行唯一名次；业务要求稳定时显式补充可区分的排序字段 |
+| `"PERCENTILE"` | 0、约 0.33、约 0.33、1 | 返回相对排名比例，不是 PERCENTILE_AGG 的分位数值 |
+
+仅自助主题，三参均可省但实际任务宜明确排序字段；数据集不能直接输出此聚合结果，需 DEF 包装并明确排名对象粒度。
+
+## 4. 动态维度引用
+
+### ADD_DIM
+
+`ADD_DIM(dimension1, dimension2, ...)` 或 `ADD_DIM()` · [原文](https://help.fanruan.com/finebi/doc-view-2623.html)
+
+- `dimensions`：零个或多个维度表达式，以英文逗号分隔；将声明维度与指定视图的维度取并集。空参返回指定视图全部维度，不返回空集合。
+- 用在 DEF 的维度参数中时，“指定视图”是**外部视图**；其他位置是**当前视图**。外部视图可能是另一个 DEF，不一定始终是最终组件分析区。
+- 按字段 ID 匹配，即使字段有时间分组/自定义分组也可匹配。返回维度声明集合，不是数值，不单独作为普通计算值输出。
+- 自 7.0 提供，用于指标中心和组件（不含明细表），配合 DEF/WINDOW/FIELD_IN；不用于 DEF_ADD/DEF_SUB 的维度参数。
+
+### SUB_DIM
+
+`SUB_DIM(dimension1, dimension2, ...)` 或 `SUB_DIM()` · [原文](https://help.fanruan.com/finebi/doc-view-2624.html)
+
+- `dimensions`：零个或多个要从指定视图中排除的维度表达式；空参不排除任何维度，返回指定视图全部维度。
+- DEF 维度参数位置引用外部视图，其他位置引用当前视图。例如在 DEF 过滤中的 `EARLIER(SUB_DIM(${月份}))`，SUB_DIM 指当前 DEF 视图去除月份后的维度，而非一律引用外部视图。
+- 返回维度集合，配合 DEF/WINDOW/FIELD_IN；用于窗口分区时可排除排序日期，保留其他维度作为组内累计分区。7.0 引用机制的字段匹配与位置限制同 ADD_DIM。
+
+### FIELD_IN
+
+`FIELD_IN(fields1, fields2)` · [原文](https://help.fanruan.com/finebi/doc-view-2638.html)
+
+- `fields1`：必需的**参考字段声明数组**，例如 `[${省份},${城市}]` 或返回维度集合的 `ADD_DIM()`。
+- `fields2`：必需的**待检查字段声明数组**；判断 fields1 是否完全包含 fields2，忽略数组内部顺序。两参不可交换，不能传字段的普通值列表代替声明数组。
+- 按字段 ID 匹配，时间/自定义分组不改变该匹配原则。自 7.0 提供，应用于指标中心、非明细表组件。例：`FIELD_IN(ADD_DIM(),[${员工}])` 判断当前视图是否包含员工维度。

package/skills/finebi-cli-agent/references/formula-parameters-date.md

@@ -0,0 +1,236 @@
+# 日期函数参数详解
+
+按函数名查本册；日期格式、版本差异另见 [使用边界](formula-help-boundaries.md)。签名中的可选参数只能按对应重载省略；空参 `FN()` 不代表 `FN(NULL)`。日期字段优先传日期值，文本优先用明确格式解析；1900 年系列数与 1970 年起的毫秒时间戳是两套单位。
+
+## 1. 构造与转换
+
+### DATE
+
+`DATE(year, month, day)` · [原文](https://help.fanruan.com/finebi/doc-view-1414.html)
+
+- `year`：年，可为一到四位数；原文未细化两位年份映射，生成时使用四位年份。
+- `month`：月。抽取支持超过 12 时从该年一月累加，例如 13 对应次年一月；直连不承诺同样进位。
+- `day`：日，抽取按同样规则进位，例如 `DATE(2000,3,35)` 为 2000-04-04。
+- 三参均需提供；抽取可为数值或文本，实时/直连要求数值。未说明负月份、零日等边界，不推断。
+
+### TIME
+
+`TIME(hour, minute, second)` · [原文](https://help.fanruan.com/finebi/doc-view-1422.html)
+
+- `hour`：小时，0～23。
+- `minute`：分钟，0～59。
+- `second`：秒，0～59。
+- 三参均需提供；抽取允许数值或文本，直连要求数值。返回值的日期部分取系统当天，并非固定日期或纯时长。
+
+### TODAY
+
+`TODAY()` · [原文](https://help.fanruan.com/finebi/doc-view-1421.html)
+
+无参数，返回当前日期。不要附加格式、时区或偏移参数；偏移日期另用 DATEDELTA。
+
+### NOW
+
+`NOW()` · [原文](https://help.fanruan.com/finebi/doc-view-1415.html)
+
+无参数，返回当前日期时间。格式化由 FORMAT 负责，函数本身没有精度或格式参数。
+
+### TODATE
+
+[原文](https://help.fanruan.com/finebi/doc-view-1406.html)中的 `TODATE()` 是函数名示意，实际参数形式如下，不将其当作无参重载。
+
+| 重载 | 参数逐项说明 | 引擎 |
+|---|---|---|
+| `TODATE(date)` | 一个日期值，直接返回该日期 | 抽取、直连 |
+| `TODATE(milliseconds)` | 一个数值，表示从 1970-01-01 00:00:00 开始的**毫秒数**；秒级时间戳需先乘 1000 | 抽取、直连 |
+| `TODATE(text)` | 一个日期格式文本，按可识别的日期形式解析；紧凑格式优先显式给格式 | 抽取、直连 |
+| `TODATE(text, format)` | `text`：日期文本；`format`：解析该文本的格式串，二者均为文本，例如 `"20110830", "yyyyMMdd"` | 抽取、直连 |
+| `TODATE(text, format, language)` | 前两参同上；`language`：解析星期、月份等文字所用语言，文本 `"zh"`/`"en"`，也支持 `"ZH"`/`"EN"` | 抽取 |
+
+格式中年份用 `yy/yyyy`、月份 `MM`、日 `dd`。第三参用于文本解析语言，不是时区；原文未规定省略语言后的具体 locale。三参中星期与月日年不一致时，原文规定以月日年部分为主。
+
+### DATETONUMBER
+
+`DATETONUMBER(date)` · [原文](https://help.fanruan.com/finebi/doc-view-1412.html)
+
+- `date`：一个日期或日期文本参数；超过一个参数不合法。返回自 1970-01-01 00:00:00 GMT 起的**毫秒数**。
+- 抽取页同时写有“5.1.12 及以后仅文本/日期”和数值 35796 的示例，两者不一致；生成时按日期/文本类型传入，不把旧数值示例作为当前支持保证。直连明确只支持日期/文本。
+
+### LUNAR
+
+`LUNAR(year, month, day)` · [原文](https://help.fanruan.com/finebi/doc-view-1408.html)
+
+- `year`：待转换公历日期的年。
+- `month`：待转换公历日期的月。
+- `day`：待转换公历日期的日。
+- 三参允许数值或文本，返回该公历日期对应的农历表示；直连不支持。单函数页未声明完整年份范围，使用目标面板确认边界。
+
+## 2. 日期偏移与差值
+
+### DATEDELTA
+
+`DATEDELTA(date, deltadays)` · [原文](https://help.fanruan.com/finebi/doc-view-1403.html)
+
+- `date`：起始日期，支持日期或文本；抽取另有 1900 年系列数示例，直连不支持该数值输入。
+- `deltadays`：数值，偏移**天数**；正数往后、负数往前、0 不偏移。两个参数均需提供。
+
+### MONTHDELTA
+
+`MONTHDELTA(date, delta)` · [原文](https://help.fanruan.com/finebi/doc-view-1401.html)
+
+- `date`：起始日期，日期或文本；抽取另支持 1900 年系列数，直连仅日期/文本。
+- `delta`：数值，偏移的**月数**；不是天数。两参均需提供，月末溢出具体处理原文未说明，月末业务需验证。
+
+### YEARDELTA
+
+`YEARDELTA(date, delta)` · [原文](https://help.fanruan.com/finebi/doc-view-1417.html)
+
+- `date`：起始日期，日期或文本；抽取另支持 1900 年系列数，直连仅日期/文本。
+- `delta`：数值，偏移的**年数**。两参均需提供；闰日偏移到非闰年的具体日期原文未说明。
+
+### DATEDIF
+
+`DATEDIF(start_date, end_date, unit)` · [原文](https://help.fanruan.com/finebi/doc-view-1402.html)
+
+- `start_date`：初始日期，日期或文本。
+- `end_date`：终止日期，日期或文本。两字段类型保持一致；差值方向为 **end_date − start_date**，可以为负。抽取原文提到数值系列号，但与“只支持文本/日期”描述不一致，优先传日期类型。
+- `unit`：必需的文本，大小写不敏感，枚举见下表；不接受任意时间单位。
+
+| unit | 取差口径 |
+|---|---|
+| `"Y"` | 年份差；原文示例按年份相减，不按 Excel 完整周年逻辑推断 |
+| `"M"` | 年月差，跨年折算月数 |
+| `"D"` | 两日期的天数差 |
+| `"MD"` | 忽略年和月，只取日之差；28 日到 20 日为 -8 |
+| `"YM"` | 忽略年和日，取月份之差 |
+| `"YD"` | 忽略年，计算日期天数差 |
+
+抽取页明确日期为空时会用 NOW 计算；业务不希望空日期变为当前时间时应先判空。此规则不是“参数可省略”，三个位置仍需提供。
+
+### DATESUBDATE
+
+`DATESUBDATE(date1, date2, op)` · [原文](https://help.fanruan.com/finebi/doc-view-1411.html)
+
+- `date1`：被减日期；日期或文本，抽取还说明数值按 1900 年系列号处理。
+- `date2`：减去的日期；同样的类型规则。返回 **date1 − date2**，方向与 DATEDIF 的参数顺序相反；直连前两参仅日期/文本。
+- `op`：必需文本，`"s"` 秒、`"m"` 分钟、`"h"` 小时、`"d"` 天、`"w"` 周，大小写均可。这里 `M` 是**分钟**，不是月。
+
+### DAYS360
+
+`DAYS360(start_date, end_date[, method])` · [原文](https://help.fanruan.com/finebi/doc-view-1405.html)
+
+- `start_date`：计算期间的起始日期，日期或文本。
+- `end_date`：计算期间的终止日期，日期或文本。
+- `method`：可省略；`FALSE` 或省略使用美国 NASD 方法，`TRUE` 使用欧洲方法，后者将起止日期中的 31 日按 30 日处理。原文说明类型为文本或数值，但同时明确支持大小写布尔字面量；优先写 `TRUE/FALSE`，不推断任意数值的含义。
+- 按每月 30 天、每年 360 天计算，仅抽取支持。
+
+### DAYVALUE
+
+`DAYVALUE(date)` · [原文](https://help.fanruan.com/finebi/doc-view-1413.html)
+
+- `date`：一个日期或文本，抽取另有 1900 年系列数形式，直连仅日期/文本。返回 1900 年起经历的天数，不是毫秒。
+- 原文 `DAYVALUE(35796)=35795`，因此不能把 DAYVALUE 的结果和所有系列数表示直接视作恒等映射。直连日期文本优先 `yyyy-MM-dd`。
+
+## 3. 提取年月日与时分秒
+
+以下七个函数的抽取重载为 `FN()`、`FN(serial_number)`、`FN(serial_number, format)`；实时/直连按单函数页的明确签名使用 `FN()` 或 `FN(serial_number)`。省略全部参数时取**服务器当前时间**，不是传入字段的默认值；指定格式时同时提供日期/时间输入。
+
+### YEAR
+
+`YEAR([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1400.html)
+
+- `serial_number`：可省略，包含目标年份的日期/文本；抽取另支持 1900 年系列数。无参取当前服务器年份。
+- `format`：抽取可选文本解析格式，例如 `"yyyy-MM-dd"`。直连页虽有残留第二参描述，明确签名和示例均为 0/1 参，不据此推广两参。
+- 返回年份，原文给出 1900～9999。
+
+### MONTH
+
+`MONTH([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1398.html)
+
+- `serial_number`：可省略，包含目标月份的日期/文本；抽取另支持 1900 年系列数。无参取当前服务器月份。
+- `format`：抽取可选文本解析格式，如 `"yyyy-MM-dd"`。直连按明确 0/1 参签名使用。
+- 返回 1～12；不是从 0 开始的月份编号。
+
+### DAY
+
+`DAY([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1407.html)
+
+- `serial_number`：可省略，包含目标日的日期/文本；抽取另支持 1900 年系列数。无参取服务器当前日。
+- `format`：抽取可选文本解析格式，如 `"yyyy-MM-dd"`；直连按 0/1 参使用。
+- 返回月中的日，1～31，不是年内日序号；直连使用标准日期文本。
+
+### QUARTER
+
+`QUARTER([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1424.html)
+
+- `serial_number`：可省略，待提取季度的时间；抽取参数表允许任意类型，直连仅日期/文本。无参取服务器当前季度。
+- `format`：抽取可省略的文本解析格式；直连没有此重载。
+- 返回季度数值 1～4。
+
+### HOUR
+
+`HOUR([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1416.html)
+
+- `serial_number`：可省略，含所求小时的日期/时间或文本；无参取服务器当前小时。
+- `format`：抽取可选文本格式，例如 `"HH:mm:ss"`；直连仅 0/1 参。
+- 返回 0～23。
+
+### MINUTE
+
+`MINUTE([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1409.html)
+
+- `serial_number`：可省略，含所求分钟的日期/时间或文本；无参取服务器当前分钟。
+- `format`：抽取可选文本格式，例如 `"HH:mm:ss"`；直连仅 0/1 参。
+- 返回 0～59；格式中的小写 `mm` 表示分钟。
+
+### SECOND
+
+`SECOND([serial_number[, format]])` · [原文](https://help.fanruan.com/finebi/doc-view-1423.html)
+
+- `serial_number`：可省略，含所求秒的时间或日期文本；无参取服务器当前秒。
+- `format`：抽取可选文本格式，例如 `"HH:mm:ss"`；直连仅 0/1 参。
+- 返回 0～59。
+
+## 4. 周与周期天数
+
+### WEEK
+
+`WEEK([serial_number[, mode]])`（抽取）；`WEEK([serial_number])`（直连）· [原文](https://help.fanruan.com/finebi/doc-view-1419.html)
+
+- `serial_number`：可省略的日期/文本，抽取还支持 1900 年系列数；无参返回服务器当前日期的年内周序号。
+- `mode`：抽取可省略文本，**默认 `"F7"`**，只支持 F1/F7（大小写均可）。F1 把含 1 月 1 日的周计为第一周；F7 把当年第一个完整周计为第一周。
+- F1/F7 不决定一周从周几开始；周日起始或周一起始取决于平台设置。跨年周可能归入上年的第 52/53 周，原文示例的 52 不是固定值。直连页未给出第二参。
+
+### WEEKDAY
+
+`WEEKDAY(serial_number)` · [原文](https://help.fanruan.com/finebi/doc-view-1420.html)
+
+- `serial_number`：必需的日期或文本；抽取另支持 1900 年系列数，直连不支持该数值形式。
+- 返回 0～6，**0=周日、6=周六**。无 `return_type` 参数，不套用 Excel 重载。
+
+### WEEKDATE
+
+`WEEKDATE(year, month, weekOfMonth, dayOfWeek)` · [原文](https://help.fanruan.com/finebi/doc-view-1404.html)
+
+- `year`：目标年份。
+- `month`：目标月份。
+- `weekOfMonth`：该月内第几周，原文示例从 1 开始。
+- `dayOfWeek`：该周第几天。原文示例 `1` 为周日，`-1` 为该周最后一天（周六），并未完整枚举所有负值；不要套用 WEEKDAY 的 0～6 编号。
+- 四参均需提供；抽取允许数值/文本，直连要求数值。
+
+### DAYSOFMONTH
+
+`DAYSOFMONTH(date)` · [原文](https://help.fanruan.com/finebi/doc-view-1410.html)
+
+- `date`：一个包含目标年月的日期/文本；抽取另有 1900 年系列数形式，直连仅日期/文本。返回该月实际天数；原文范围描述从 1900 年 1 月以后。
+
+### DAYSOFQUARTER
+
+`DAYSOFQUARTER(date)` · [原文](https://help.fanruan.com/finebi/doc-view-1418.html)
+
+- `date`：一个包含目标季度的日期/文本；抽取另有 1900 年系列数形式，直连仅日期/文本。返回该年该季度实际天数，不是固定 90 天。
+
+### DAYSOFYEAR
+
+`DAYSOFYEAR(year)` · [原文](https://help.fanruan.com/finebi/doc-view-1399.html)
+
+- `year`：指定年份。抽取允许任意类型参数，示例 `2008` 等价于日期文本 `"2008-01-01"`；直连参数要求日期或文本，应传包含目标年的日期值。返回该年天数。