feat(sheets): refine chart data label controls

shortcuts/sheets/data/flag-defs.json

@@ -3553,14 +3553,14 @@
         "kind": "own",
         "type": "float64",
         "required": "optional",
-        "desc": "Lower display bound for the left Y-axis; must be less than --y-axis-max"
+        "desc": "Lower display bound for the left Y-axis; omit by default and pass only when the user explicitly requests fixed bounds; do not copy a raw source-column minimum, and keep it below --y-axis-max"
       },
       {
         "name": "y-axis-max",
         "kind": "own",
         "type": "float64",
         "required": "optional",
-        "desc": "Upper display bound for the left Y-axis; must be greater than --y-axis-min"
+        "desc": "Upper display bound for the left Y-axis; omit by default and pass only when the user explicitly requests fixed bounds; calculate it from rendered chart semantics, and keep it above --y-axis-min"
       },
       {
         "name": "dim1-index",
@@ -3588,7 +3588,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Combo charts only; comma-separated left or right Y-axis assignments aligned with --dim2-indexes; provide one value per selected series"
+        "desc": "Combo charts only; compare series units and magnitudes first and place a series that would be flattened on the right axis; pass left or right aligned with --dim2-indexes, one value per selected series"
       },
       {
         "name": "key-index",
@@ -3644,7 +3644,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Legend position; hidden removes the legend",
+        "desc": "Legend position; use bottom by default for pie and doughnut charts; hidden removes the legend",
         "enum": [
           "top",
           "bottom",
@@ -3707,7 +3707,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Data label content; combine value, category, and percentage in value_category_percentage order for any non-empty combination; series shows series names and none removes labels",
+        "desc": "Data label content; pass value by default for a basic chart, but omit it when many data points or series would make labels crowded; combine value, category, and percentage in value_category_percentage order for any non-empty combination; series shows series names and none removes labels",
         "enum": [
           "none",
           "value",
@@ -3737,6 +3737,13 @@
           "outside"
         ]
       },
+      {
+        "name": "series-data-labels",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Configure labels independently by 1-based value-series position; each item has series_position, scope (none/all/last), and optional content/position; mutually exclusive with global label flags"
+      },
       {
         "name": "stack",
         "kind": "own",
@@ -3804,7 +3811,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Optional chart width; must be paired with --height"
+        "desc": "Optional chart width; must be paired with --height; widen pie or doughnut charts and charts with long category labels to avoid truncation"
       },
       {
         "name": "height",
@@ -3956,14 +3963,14 @@
         "kind": "own",
         "type": "float64",
         "required": "optional",
-        "desc": "Lower display bound for the left Y-axis; must be less than --y-axis-max"
+        "desc": "Lower display bound for the left Y-axis; omit by default and pass only when the user explicitly requests fixed bounds; do not copy a raw source-column minimum, and keep it below --y-axis-max"
       },
       {
         "name": "y-axis-max",
         "kind": "own",
         "type": "float64",
         "required": "optional",
-        "desc": "Upper display bound for the left Y-axis; must be greater than --y-axis-min"
+        "desc": "Upper display bound for the left Y-axis; omit by default and pass only when the user explicitly requests fixed bounds; calculate it from rendered chart semantics, and keep it above --y-axis-min"
       },
       {
         "name": "data-labels",
@@ -4001,11 +4008,11 @@
         ]
       },
       {
-        "name": "last-point-label",
+        "name": "series-data-labels",
         "kind": "own",
-        "type": "bool",
+        "type": "string",
         "required": "optional",
-        "desc": "For line, area, radar, and linear combo series only; true shows a value label on the last data point of every series, while false removes those point labels"
+        "desc": "Configure labels independently by 1-based value-series position; each item has series_position, scope (none/all/last), and optional content/position; mutually exclusive with global label flags"
       },
       {
         "name": "stack",

shortcuts/sheets/data/flag-schemas.json

@@ -982,6 +982,66 @@
         }
       }
     },
+    "+chart-config-update": {
+      "series-data-labels": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 50,
+        "description": "按 1-based 数值系列顺序分别配置数据标签；与全局 data_labels/data_label_position 互斥。",
+        "items": {
+          "type": "object",
+          "required": [
+            "series_position",
+            "scope"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "series_position": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "数值系列在图表中的 1-based 顺序，与 dim2_indexes 的顺序一致"
+            },
+            "scope": {
+              "type": "string",
+              "enum": [
+                "none",
+                "all",
+                "last"
+              ],
+              "description": "none 隐藏该系列标签；all 显示全部数据点；last 仅显示最后一个数据点"
+            },
+            "content": {
+              "type": "string",
+              "enum": [
+                "value",
+                "category",
+                "percentage",
+                "value_category",
+                "value_percentage",
+                "category_percentage",
+                "value_category_percentage",
+                "series"
+              ],
+              "description": "标签内容，省略时为 value；scope=none 时不得设置"
+            },
+            "position": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "center",
+                "inside",
+                "outside"
+              ],
+              "description": "标签位置；scope=none 时不得设置"
+            }
+          }
+        }
+      }
+    },
     "+chart-create": {
       "properties": {
         "description": "创建/更新的图表属性。",
@@ -1040,9 +1100,63 @@
               "height"
             ]
           },
-          "last_point_label": {
-            "type": "boolean",
-            "description": "update 使用。true 为折线图、面积图、雷达图及组合图中的线性系列开启最后一个数据点的数值标签；false 关闭这些单点标签。"
+          "series_data_labels": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 50,
+            "description": "按 1-based 数值系列顺序分别配置数据标签；与全局 data_labels/data_label_position 互斥。",
+            "items": {
+              "type": "object",
+              "required": [
+                "series_position",
+                "scope"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "series_position": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "数值系列在图表中的 1-based 顺序，与 dim2_indexes 的顺序一致"
+                },
+                "scope": {
+                  "type": "string",
+                  "enum": [
+                    "none",
+                    "all",
+                    "last"
+                  ],
+                  "description": "none 隐藏该系列标签；all 显示全部数据点；last 仅显示最后一个数据点"
+                },
+                "content": {
+                  "type": "string",
+                  "enum": [
+                    "value",
+                    "category",
+                    "percentage",
+                    "value_category",
+                    "value_percentage",
+                    "category_percentage",
+                    "value_category_percentage",
+                    "series"
+                  ],
+                  "description": "标签内容，省略时为 value；scope=none 时不得设置"
+                },
+                "position": {
+                  "type": "string",
+                  "enum": [
+                    "auto",
+                    "top",
+                    "bottom",
+                    "left",
+                    "right",
+                    "center",
+                    "inside",
+                    "outside"
+                  ],
+                  "description": "标签位置；scope=none 时不得设置"
+                }
+              }
+            }
           },
           "snapshot": {
             "description": "图表快照配置。create 需要完整配置；update 可只提供需要变更的字段，对象字段递归合并，数组整段替换，未提供的字段保持现状。",
@@ -3282,6 +3396,66 @@
         }
       }
     },
+    "+chart-create-basic": {
+      "series-data-labels": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 50,
+        "description": "按 1-based 数值系列顺序分别配置数据标签；与全局 data_labels/data_label_position 互斥。",
+        "items": {
+          "type": "object",
+          "required": [
+            "series_position",
+            "scope"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "series_position": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "数值系列在图表中的 1-based 顺序，与 dim2_indexes 的顺序一致"
+            },
+            "scope": {
+              "type": "string",
+              "enum": [
+                "none",
+                "all",
+                "last"
+              ],
+              "description": "none 隐藏该系列标签；all 显示全部数据点；last 仅显示最后一个数据点"
+            },
+            "content": {
+              "type": "string",
+              "enum": [
+                "value",
+                "category",
+                "percentage",
+                "value_category",
+                "value_percentage",
+                "category_percentage",
+                "value_category_percentage",
+                "series"
+              ],
+              "description": "标签内容，省略时为 value；scope=none 时不得设置"
+            },
+            "position": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "center",
+                "inside",
+                "outside"
+              ],
+              "description": "标签位置；scope=none 时不得设置"
+            }
+          }
+        }
+      }
+    },
     "+chart-update": {
       "properties": {
         "description": "创建/更新的图表属性。",
@@ -3340,9 +3514,63 @@
               "height"
             ]
           },
-          "last_point_label": {
-            "type": "boolean",
-            "description": "update 使用。true 为折线图、面积图、雷达图及组合图中的线性系列开启最后一个数据点的数值标签；false 关闭这些单点标签。"
+          "series_data_labels": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 50,
+            "description": "按 1-based 数值系列顺序分别配置数据标签；与全局 data_labels/data_label_position 互斥。",
+            "items": {
+              "type": "object",
+              "required": [
+                "series_position",
+                "scope"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "series_position": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "数值系列在图表中的 1-based 顺序，与 dim2_indexes 的顺序一致"
+                },
+                "scope": {
+                  "type": "string",
+                  "enum": [
+                    "none",
+                    "all",
+                    "last"
+                  ],
+                  "description": "none 隐藏该系列标签；all 显示全部数据点；last 仅显示最后一个数据点"
+                },
+                "content": {
+                  "type": "string",
+                  "enum": [
+                    "value",
+                    "category",
+                    "percentage",
+                    "value_category",
+                    "value_percentage",
+                    "category_percentage",
+                    "value_category_percentage",
+                    "series"
+                  ],
+                  "description": "标签内容，省略时为 value；scope=none 时不得设置"
+                },
+                "position": {
+                  "type": "string",
+                  "enum": [
+                    "auto",
+                    "top",
+                    "bottom",
+                    "left",
+                    "right",
+                    "center",
+                    "inside",
+                    "outside"
+                  ],
+                  "description": "标签位置；scope=none 时不得设置"
+                }
+              }
+            }
           },
           "snapshot": {
             "description": "图表快照配置。create 需要完整配置；update 可只提供需要变更的字段，对象字段递归合并，数组整段替换，未提供的字段保持现状。",