weaver-e10-builder 1.6.10 → 1.6.12

package/skill-docs/references/report/financial-stats-report-guide.md

@@ -0,0 +1,89 @@
+# 同比环比等财务统计表 · 场景 K（SKILL A0.20）
+
+> 案例「同比环比等财务统计表」：年份/月份两级分组 + 销售额，配五类派生指标——
+> ①月环比 ②年同比 ③年内占比 ④年内排名+总排名 ⑤年内累计+总累计。
+
+---
+
+## 一、机制定案（源码级事实）
+
+| 事实 | 出处 |
+|---|---|
+| EDC 内置组合公式 `COMB_GROWTH_RATE / COMB_DYNAMIC_RATE / COMB_DIFF / COMB_GRAND_TOTAL`，后端仅生成 `IFERROR+原串` 公式串，**具体算术在 SpreadJS 前端逐实例执行** | knowledge-base §9.3 / report-building-guide §8.2 |
+| 合计/小计**不自动插入**；`SUM(扩展格)` = 对该扩展全部实例求和；公式父格上下文决定分组范围 | knowledge-base §9.3 / crosstab guide |
+| 公式格落库形态：`cellText` 与顶层 `formula` 均**不带前导 `=`**；公式格四件套（BUILD-49） | formula-cell-api-guide |
+
+**结论**：环比/同比/占比/排名/累计的「相对实例引用」靠 SpreadJS 前端逐实例求值 —— 报表侧可做，但
+**跨组引用（同比=上年同月）与排名/累计的层次语义是 FineReport 层次坐标的领地**，EDC 侧等价写法需验证。
+
+## 二、两条实现路径
+
+### 路径一：数据集侧预计算（★ 语义正解 · 推荐 · 与 MEMORY 铁律一致）
+
+比率/派生指标走**数据源侧预计算列**（数据加工 SQL 视图），报表**纯绑字段**——五行指标一次算全，
+格式/空值/排序全可控，不依赖前端公式语义：
+
+```sql
+SELECT
+  年份, 月份, 销售额,
+  销售额 / LAG(销售额) OVER (PARTITION BY 年份 ORDER BY 月份) - 1        AS 月环比,
+  销售额 / LAG(销售额, 12) OVER (ORDER BY 年份, 月份) - 1                AS 年同比,   -- 或按年月对齐
+  销售额 / SUM(销售额) OVER (PARTITION BY 年份)                          AS 年内占比,
+  RANK() OVER (PARTITION BY 年份 ORDER BY 销售额 DESC)                   AS 年内排名,
+  RANK() OVER (ORDER BY 销售额 DESC)                                     AS 总排名,
+  SUM(销售额) OVER (PARTITION BY 年份 ORDER BY 月份)                     AS 年内累计,
+  SUM(销售额) OVER (ORDER BY 年份, 月份)                                 AS 总累计
+FROM 销售明细
+```
+
+报表结构（build spec 直出，无需公式列）：
+
+```json
+{
+  "columns": [
+    { "title": "年份", "field": "年份" },
+    { "title": "月份", "field": "月份" },
+    { "title": "销售额", "field": "销售额", "format": "value" },
+    { "title": "月环比", "field": "月环比", "format": "percent" },
+    { "title": "年同比", "field": "年同比", "format": "percent" },
+    { "title": "占比", "field": "年内占比", "format": "percent" },
+    { "title": "年内排名", "field": "年内排名" },
+    { "title": "总排名", "field": "总排名" },
+    { "title": "年内累计", "field": "年内累计", "format": "value" },
+    { "title": "总累计", "field": "总累计", "format": "value" }
+  ],
+  "layout": { "title": "同比环比等财务统计表", "freezeRows": 1 }
+}
+```
+
+年份分组缩进（年份格纵跨）= 年份 Field Group 扩展 + 月份左父格→年份；纯列表版直接平铺。
+
+### 路径二：报表侧 SpreadJS 公式（能力边界 + 验证捕获法）
+
+| 指标 | 报表侧写法 | 状态 |
+|---|---|---|
+| 占比 | Formula `IFERROR(C3/SUM(C3),0)`（C3=销售额设计格；SUM 引扩展格=组内求和，父格上下文=年份） | 机制已验证方向，**分组作用域已验证** |
+| 环比 | Formula 相对上一实例 `IFERROR((C3-C2)/C2,"--")` 形态（SpreadJS 逐实例偏移） | ⚠️ 验证项（COMB_GROWTH_RATE 证明前端有此能力，**自写串的实例偏移规则待验证**） |
+| 同比 | 跨组相对引用（上年同月 = 偏移 N 实例） | ⚠️ 验证项（层次语义最弱的一环，优先路径一） |
+| 排名 | SpreadJS RANK 或数据集预计算 | ⚠️ 验证项 / 路径一 |
+| 累计 | 逐实例递推累计公式 | ⚠️ 验证项 / 路径一 |
+
+**捕获法（把内置组合公式固化进 CLI 的通道）**：设计器对某格配「环比/占比」内置组合公式 →
+`getReportDevInfo` 回读该格 `cellText`/`formula` 串 → 拿到 COMB_* 展开后的真实公式形态，
+回填本指南后即可在 rebuild 直构里复刻。
+
+## 三、搭建提示语句（路径一 · 推荐）
+
+> 按同比环比财务统计表搭一张报表：年份/月份两级分组，销售额按月汇总；
+> 指标列：月环比 / 年同比 / 年内占比 / 年内排名+总排名 / 年内累计+总累计；
+> **在数据加工 SQL 里用窗口函数预计算这五类指标**（LAG 环比、SUM OVER 占比累计、RANK OVER 排名），
+> 报表纯绑字段（`build spec` 直出，百分比列 format:percent）；
+> 数据源 `<sid 或 SQL 视图>`（appId `<appId>`）；年份格分组缩进、冻结表头；
+> 落库后回读验收：字段绑定与格式、无公式列依赖。
+
+## 四、验证清单
+
+1. 路径一：预计算列在数据集预览有值（空值=首月环比等，SQL 侧 NULL→"--" 或留空）
+2. build spec 回读：列绑定逐一命中、percent 格式 `0.00%`（禁 "common" 短码，BUILD-47）
+3. 路径二（如走）：公式格四件套（BUILD-49）+ `subordination=["",""]` + 渲染形态设计器确认
+4. 排名并列/方向（DESC）、累计首行初值——以 SQL 侧验收为准