@rezti/dsh-rez-suite 0.1.49 → 0.1.51

package/templates/shared/wecomcli-smartsheet/references/smart-sheet-chart-types.md

@@ -0,0 +1,95 @@
+# 图表类型（ChartType）完整参考
+
+## Chart（图表结构）
+
+图表属性信息，用于新增/修改/删除/查询图表。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | string | 图表 ID，唯一标识（新增时由服务端生成，更新/删除时必传） |
+| `title` | string | 图表名称 |
+| `type` | string | 图表类型枚举，见下表图表类型定义 |
+| `datasource` | string | 数据源，引用的工作表子表名称 |
+| `category` | ChartCategory | 类别字段配置 |
+| `series` | ChartSeries[] | 值字段配置。**`series` 不传时，纵轴默认使用「记录数」作为统计指标** |
+| `filter` | FilterSpec | 筛选条件，不传则不过滤；禁止传 `"filter": {}` 或空的 `conditions`。必须查看 `references/smart-sheet-view-types.md` 中的 FilterSpec 定义 |
+| `layout` | ChartLayout | 图表在仪表盘中的位置与尺寸 |
+
+> **图表筛选高频错误预警**：当用户要求生成带筛选条件的图表时，`filter.conditions[].string_value.value` **必须传选项 ID**（如 `"osvuEH"`），**不能传显示文本**（如 `"进行中"`）。传文本会导致筛选永远命中 0 条，图表会显示"数据不可用"或空白。
+>
+> **强制流程**：带筛选条件的图表创建前，**必须先调用 `smartsheet fields list` 获取字段的 `property_single_select.options[]` / `property_select.options[]`**，从中取 `id` 填入 `string_value.value`。完整的 FilterSpec / StringValue 定义见 `references/smart-sheet-view-types.md`。
+
+---
+
+## 图表类型
+
+> 当用户的请求中包含图表名称时（如"柱状图"、"条形图"、"组合图"），参考下表选择图表的 `type`。不要仅按英文字面意思猜测（例如"柱状图"应使用 `column`，"组合图"也不等于 `bar`）。
+
+| 用户中文叫法 | `type` 值 | 语义 / 典型使用场景 |
+| --- | --- | --- |
+| 条形图（横向） | `bar` | 横向矩形条，类别在 Y 轴 |
+| 堆积条形图 | `stackbar` | 横向，多系列堆叠 |
+| 百分比堆积条形图 | `percentbar` | 横向，多系列占比堆叠（总和 100%） |
+| 柱状图 / 柱形图（纵向） | `column` | 纵向矩形条，类别在 X 轴，**最常见的"柱状图"默认用它** |
+| 堆积柱状图 | `stackcolumn` | 纵向，多系列堆叠 |
+| 百分比堆积柱状图 | `percentcolumn` | 纵向，多系列占比堆叠（总和 100%） |
+| 折线图 | `line` | 折线 |
+| 平滑折线图 / 曲线图 | `smoothline` | 平滑曲线 |
+| 饼图 | `pie` | 圆饼 |
+| 环形图 / 圆环图 / 甜甜圈图 | `doughnut` | 中空圆环 |
+| 组合图 / 双轴图 / 柱线图 / 柱+线 | `combo` | **同一图上混用柱+线等多种图形，对比 2 个及以上数值系列，是"对比 A 和 B"、"同时看数量和均值"等意图的唯一正确选择** |
+| 表格图 / 数据表 | `table` | 二维表展示 |
+| 数字卡 / 指标卡 / KPI | `numberCard` | 单个大数字 |
+| 词云图 / 词云 | `wordCloud` | 词频展示 |
+| 文本块 / 文本说明 | `textBlock` | 纯文字注释块 |
+
+---
+
+## ChartCategory（类别字段配置）
+
+图表的类别字段配置。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `field_title` | string | 类别字段名称 |
+| `sub_field_title` | string | 二级类别字段名称（无二级分类时为空字符串） |
+
+---
+
+## ChartSeries（值字段配置）
+
+图表的值字段配置。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `field_title` | string | 值字段名称 |
+| `aggregation` | string | 数字字段支持的聚合方式枚举：`sum` (求和) / `avg` (平均值) / `max` (最大值) / `min` (最小值) |
+
+按照 **`count`（计数）** 方式聚合时，**禁止**传入 `series` 字段，保持默认按记录数统计即可。凡是“数量/总数/记录数/客户数/项目数/缺陷数/任务数/进行中数量/已完成数量”等计数语义，均不传 `series`，不能在 `series` 中填写 `"aggregation": "count"`。
+
+---
+
+## ChartLayout（图表布局）
+
+图表在仪表盘中的位置与尺寸。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `width_height` | uint32[] | 宽高，格式为 `[width, height]`，例如 `[3, 4]` |
+| `xy` | uint32[] | 起点坐标，格式为 `[x, y]`，例如 `[0, 0]` |
+
+### 网格规则与布局约束
+
+> **严禁触发自动调整**：以下两种情况会导致服务端静默修改坐标，造成布局混乱，**设计时必须主动规避**：
+>
+> 1. **x 坐标越界**：仪表盘网格总宽为 **12 格**，`x + width > 12` 时 x 坐标会被自动调整。**必须确保每行所有图表的 `x + width ≤ 12`**。
+> 2. **y 坐标悬空**：若某图表的 y 坐标与已有图表之间存在空行（无任何图表相邻），该图表会被自动上移。**必须确保图表在 y 轴方向紧密排列，不留空行**。
+
+### 布局设计规范
+
+- **紧凑原则**：同一行内的图表应填满 12 格宽度，不留横向空白。若一行内有多个图表宽度之和不足 12，需调整各图表宽度使其恰好填满。
+- **均衡原则**：避免"左重右轻"——即某行只有左侧有图表、右侧大片空白。除最后一行外，每一行都必须有图表填满整行 12 格，或将孤立图表拉伸至 12 格独占一行。
+- **推荐尺寸**：仅作参考，请按照具体需要设计尺寸。
+  - 普通图表（柱状图、条形图、折线图、饼图等）：`[6, 4]` 或 `[4, 4]`
+  - 宽图（需要展示较多类别）：`[8, 4]` 或 `[12, 4]`
+  - 数字卡（`numberCard`）：`[3, 2]` 或 `[2, 2]`