@xpert-ai/plugin-live-dashboard 0.3.1 → 0.4.0

package/skills/live-dashboard/examples/superstore/THIRD_PARTY_LICENSE.txt

@@ -0,0 +1,207 @@
+Apache License Version 2.0
+
+Copyright (c) 2026 Salesforce, Inc.
+All rights reserved.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/skills/live-dashboard/examples/superstore/build_data.py

@@ -0,0 +1,155 @@
+"""Rebuild the pinned Tableau teaching dataset (requires xlrd==2.0.2).
+
+Usage: python build_data.py --workbook /path/to/Sample-Superstore.xls
+The original workbook is not modified. Only files in this recipe are generated.
+"""
+import argparse
+import csv
+import hashlib
+import json
+from collections import defaultdict
+from datetime import datetime
+from decimal import Decimal
+from pathlib import Path
+
+SHA256 = 'add4e193479cae8e9f22bfa734dd8bb706355dce38353967668f4e2b6643d19c'
+ROOT = Path(__file__).resolve().parent
+FIELDS = [
+    'row_id', 'order_id', 'order_date', 'ship_date', 'ship_mode', 'customer_id',
+    'customer_name', 'segment', 'country', 'city', 'state', 'postal_code', 'region',
+    'product_id', 'category', 'sub_category', 'product_name', 'sales', 'quantity',
+    'discount', 'profit', 'order_year', 'order_month', 'regional_manager',
+    'returned', 'returned_order_id', 'returned_sales',
+]
+NUMERIC = {'sales', 'profit', 'discount', 'returned_sales'}
+INTEGER = {'row_id', 'quantity'}
+
+
+def money(value):
+    # Excel binary floating-point noise is normalized at six decimal places.
+    return Decimal(str(value)).quantize(Decimal('0.000001'))
+
+
+def read_workbook(path):
+    if hashlib.sha256(path.read_bytes()).hexdigest() != SHA256:
+        raise ValueError('Workbook SHA-256 differs from the pinned Tableau release')
+    import xlrd
+    book = xlrd.open_workbook(str(path))
+    orders, returns, people = [book.sheet_by_name(name) for name in ('Orders', 'Returns', 'People')]
+    if orders.nrows - 1 != 10194 or orders.ncols != 21:
+        raise ValueError('Unexpected Orders shape')
+    return_ids = {str(returns.cell_value(i, 1)) for i in range(1, returns.nrows)}
+    if len(return_ids) != 296 or returns.nrows - 1 != 800:
+        raise ValueError('Unexpected Returns shape')
+    managers = {}
+    for i in range(1, people.nrows):
+        name, region = people.row_values(i)
+        if region in managers:
+            raise ValueError('Duplicate region manager would multiply fact rows')
+        managers[region] = name
+    rows = []
+    for i in range(1, orders.nrows):
+        values = orders.row_values(i)
+        row = dict(zip(FIELDS[:21], values))
+        for key in ('order_date', 'ship_date'):
+            row[key] = xlrd.xldate_as_datetime(row[key], book.datemode).date().isoformat()
+        for key in NUMERIC - {'returned_sales'}:
+            row[key] = money(row[key])
+        for key in INTEGER:
+            if row[key] != int(row[key]):
+                raise ValueError('Non-integer identifier or quantity')
+            row[key] = int(row[key])
+        # Postal codes are labels, never numbers or measures.
+        row['postal_code'] = str(int(row['postal_code'])).zfill(5) if isinstance(row['postal_code'], (int, float)) else str(row['postal_code'])
+        row['order_year'], row['order_month'] = row['order_date'][:4], row['order_date'][:7]
+        row['regional_manager'] = managers[row['region']]
+        returned = row['order_id'] in return_ids
+        row['returned'] = 'Yes' if returned else 'No'
+        row['returned_order_id'] = row['order_id'] if returned else None
+        row['returned_sales'] = row['sales'] if returned else Decimal('0.000000')
+        rows.append(row)
+    if len({r['row_id'] for r in rows}) != len(rows):
+        raise ValueError('Duplicate order-line primary key')
+    if return_ids - {r['order_id'] for r in rows}:
+        raise ValueError('Unmatched return order')
+    return rows
+
+
+def aggregate(rows):
+    total = lambda field: str(sum((r[field] for r in rows), Decimal(0)).quantize(Decimal('0.000001')))
+    return {
+        'Sales': total('sales'), 'Profit': total('profit'),
+        'Quantity': sum(r['quantity'] for r in rows),
+        'Orders': len({r['order_id'] for r in rows}),
+        'Customers': len({r['customer_id'] for r in rows}),
+        'ReturnedOrders': len({r['returned_order_id'] for r in rows if r['returned_order_id']}),
+        'ReturnedSales': total('returned_sales'),
+    }
+
+
+def write_json(name, value):
+    (ROOT / name).write_text(json.dumps(value, ensure_ascii=False, indent=2) + '\n')
+
+
+def build(rows):
+    with (ROOT / 'orders.csv').open('w', newline='') as handle:
+        writer = csv.DictWriter(handle, fieldnames=FIELDS, lineterminator='\n')
+        writer.writeheader()
+        writer.writerows(rows)
+    dimensions = {
+        'OrderYear': ('order_year', '年份'), 'OrderMonth': ('order_month', '订单月份'),
+        'Region': ('region', '区域'), 'Category': ('category', '品类'),
+        'SubCategory': ('sub_category', '子品类'), 'Segment': ('segment', '客户分群'),
+        'Returned': ('returned', '退货标记'), 'RegionalManager': ('regional_manager', '区域经理'),
+    }
+    measures = [
+        ('Sales', 'sales', 'sum', '销售额（USD）'),
+        ('Profit', 'profit', 'sum', '利润（USD）'),
+        ('Quantity', 'quantity', 'sum', '商品件数'),
+        ('Orders', 'order_id', 'distinct-count', '订单数'),
+        ('Customers', 'customer_id', 'distinct-count', '客户数'),
+        ('ReturnedOrders', 'returned_order_id', 'distinct-count', '退货订单数'),
+        ('ReturnedSales', 'returned_sales', 'sum', '退货关联销售额（USD，非退款）'),
+    ]
+    write_json('semantic-model.json', {'cubes': [{
+        'name': 'SuperstoreOrders', 'caption': 'Superstore 订单分析（演示）',
+        'fact': {'type': 'table', 'table': {'name': 'superstore_orders_v1', 'schema': 'public'}},
+        'defaultMeasure': 'Sales',
+        'measures': [{'name': n, 'column': c, 'aggregator': a, 'caption': label,
+                      'datatype': 'Numeric', 'visible': True} for n, c, a, label in measures],
+        'dimensions': [{'name': name, 'caption': label, 'hierarchies': [{
+            'name': name, 'hasAll': True,
+            'levels': [{'name': name, 'column': column, 'type': 'String', 'uniqueMembers': True}],
+        }]} for name, (column, label) in dimensions.items()],
+    }]})
+    cases = {'all': {}, 'west': {'region': 'West'}, 'east': {'region': 'East'},
+             'year2024': {'order_year': '2024'}, 'furniture': {'category': 'Furniture'},
+             'west2024furniture': {'region': 'West', 'order_year': '2024', 'category': 'Furniture'},
+             'empty': {'order_year': '1999'}}
+    expected = {'sourceSha256': SHA256, 'orderLines': len(rows), 'cases': {}}
+    for key, filters in cases.items():
+        selected = [r for r in rows if all(r[k] == v for k, v in filters.items())]
+        item = {'filters': filters, 'rows': len(selected), 'totals': aggregate(selected), 'groups': {}}
+        for dim, (column, _) in dimensions.items():
+            groups = defaultdict(list)
+            for row in selected:
+                groups[row[column]].append(row)
+            item['groups'][dim] = [{dim: member, **aggregate(group)} for member, group in sorted(groups.items())]
+        expected['cases'][key] = item
+    write_json('expected.json', expected)
+    write_json('import.json', [{
+        'catalog': 'public', 'name': 'superstore_orders_v1', 'withHeader': 1,
+        'columns': [{'name': f, 'fieldName': f, 'isKey': f == 'row_id',
+                     'type': 'decimal' if f in NUMERIC else 'integer' if f in INTEGER else 'varchar',
+                     **({'precision': 20, 'fraction': 6} if f in NUMERIC else {'length': 512} if f not in INTEGER else {})}
+                    for f in FIELDS],
+    }])
+    print(json.dumps({'rows': len(rows), 'totals': aggregate(rows),
+                      'csvSha256': hashlib.sha256((ROOT / 'orders.csv').read_bytes()).hexdigest()}))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--workbook', type=Path, required=True)
+    args = parser.parse_args()
+    build(read_workbook(args.workbook))

package/skills/live-dashboard/examples/superstore/build_pages.py

@@ -0,0 +1,129 @@
+"""Generate self-contained, inspectable HTML recipes and query plans. No data rows are embedded."""
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+THEME = ROOT.parent.parent / 'themes' / 'trend-workspace'
+OPTIONS = {
+    'year': [['', '全部年份']] + [[str(y), str(y)] for y in range(2021, 2025)],
+    'region': [['', '全部区域']] + [[r, r] for r in ['Central', 'East', 'South', 'West']],
+    'category': [['', '全部品类']] + [[c, c] for c in ['Furniture', 'Office Supplies', 'Technology']],
+}
+CONTROLS = [{'controlId': key, 'label': label, 'type': 'string', 'defaultValue': '',
+             'allowedValues': [value for value, _ in OPTIONS[key]]}
+            for key, label in [('year', '年份'), ('region', '区域'), ('category', '品类')]]
+PAGES = [
+    {'key': 'overview', 'title': '零售经营总览', 'description': '从经营结果到区域与品类贡献',
+     'bindings': {'summary': [], 'trend': ['OrderMonth'], 'regions': ['Region'], 'categories': ['Category']},
+     'panels': ['月度销售与利润', '区域销售贡献'], 'notes': ['USD · 独立总计保留订单和客户去重口径', 'USD · 同一筛选范围'],
+     'dimension': '品类', 'table': '品类经营表现'},
+    {'key': 'profitability', 'title': '商品盈利分析', 'description': '找到贡献利润的商品，以及高销售背后的亏损',
+     'bindings': {'summary': [], 'subcategories': ['SubCategory']},
+     'panels': ['子品类利润排序', '销售额与利润关系'], 'notes': ['USD · 红色表示负利润', '每个点代表一个子品类，悬停查看金额'],
+     'dimension': '子品类', 'table': '子品类盈利明细'},
+    {'key': 'customers', 'title': '客户与退货分析', 'description': '客户结构、订单价值与退货订单关联表现',
+     'bindings': {'summary': [], 'segments': ['Segment'], 'regions': ['Region']},
+     'panels': ['客户分群销售贡献', '各区域退货订单数'], 'notes': ['USD · 客户数在当前范围内去重', '按 Order ID 去重；不代表退货商品件数'],
+     'dimension': '客户分群', 'table': '客户分群与退货明细'},
+]
+checks = []
+for name, case in json.loads((ROOT / 'expected.json').read_text())['cases'].items():
+    if name == 'empty':
+        continue  # 1999 is an SDK/data test, outside the page's allowed years.
+    checks.append({'case': name, 'controls': {
+        'year': case['filters'].get('order_year', ''),
+        'region': case['filters'].get('region', ''),
+        'category': case['filters'].get('category', '')},
+        'summary': {key: str(value) for key, value in case['totals'].items()}})
+(ROOT / 'checks.json').write_text(json.dumps(checks, ensure_ascii=False, indent=2) + '\n')
+CSS = '/* Theme CSS is supplied by the pinned trend-workspace document library. */'
+JS = (ROOT / 'page.js').read_text()
+for page in PAGES:
+    key = page['key']
+    measures = ['Sales', 'Orders', 'Customers', 'ReturnedOrders', 'ReturnedSales'] if key == 'customers' else ['Sales', 'Profit', 'Orders', 'Customers']
+    config = {**page, 'bindings': list(page['bindings']), 'options': OPTIONS, 'measures': measures}
+    metrics = [('销售额（USD）', '订单行销售额合计'), ('利润（USD）', '订单行利润合计'),
+               ('利润率', '利润 ÷ 销售额'), ('订单数', 'Order ID 去重'), ('客户数', 'Customer ID 去重')]
+    if key == 'customers':
+        metrics = [('客户数', 'Customer ID 去重'), ('订单数', 'Order ID 去重'),
+                   ('客单价（USD）', '销售额 ÷ 订单数'), ('退货订单数', '退货 Order ID 去重'), ('退货订单占比', '退货订单数 ÷ 订单数')]
+    filters = ''.join(f'<div class="filter-field"><label for="filter-{c["controlId"]}">{c["label"]}</label><select id="filter-{c["controlId"]}" data-dashboard-control="{c["controlId"]}" disabled></select></div>' for c in CONTROLS)
+    metric_blocks = [f'<div class="metric"><p>{label}</p><output id="metric-{i}">—</output><small>{note}</small></div>' for i, (label, note) in enumerate(metrics)]
+    cards = ''.join(metric_blocks)
+    panels = ''.join(f'<section class="panel"><h2>{page["panels"][i]}</h2><p class="note">{page["notes"][i]}</p><div id="chart-{name}" class="chart" role="img" aria-label="{page["panels"][i]}"></div></section>' for i, name in enumerate(['primary', 'secondary']))
+    headings = [page['dimension'], '销售额（USD）', '利润（USD）', '利润率']
+    if key == 'profitability':
+        headings += ['订单数', '客户数']
+    if key == 'customers':
+        headings = [page['dimension'], '销售额（USD）', '订单数', '客户数', '退货订单数', '退货订单占比', '退货关联销售额（USD）']
+    heads = ''.join(f'<th scope="col">{heading}</th>' for heading in headings)
+    table = f'<section class="details"><h2>{page["table"]}</h2><p class="note">USD · 同一筛选范围</p><div class="table-scroll" tabindex="0" role="region" aria-label="{page["table"]}"><table><thead><tr>{heads}</tr></thead><tbody id="details-rows"></tbody></table></div></section>'
+    if key == 'overview':
+        content = f'''<section class="hero"><h2>月度经营趋势</h2><p class="note">2021–2024 · USD · 销售额与利润分别使用独立刻度</p>
+<h3 class="chart-heading">销售额（USD）</h3><div id="chart-primary" class="chart" role="img" aria-label="月度销售额"></div>
+<h3 class="chart-heading profit">利润（USD）</h3><div id="chart-profit" class="chart chart-profit" role="img" aria-label="月度利润"></div></section>
+<div class="lower-grid"><section class="region-panel"><h2>区域销售贡献</h2><p class="note">USD · 按销售额从高到低</p><div id="chart-secondary" class="chart" role="img" aria-label="区域销售贡献"></div></section>{table}</div>'''
+    else:
+        content = f'<div class="plots">{panels}</div><div class="full-details">{table}</div>'
+    html = f'''<!doctype html>
+<html lang="zh-Hans"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Superstore · {page['title']}</title><style>{CSS}</style></head>
+<body data-page="{key}" data-dashboard-theme="trend-workspace@1"><main class="workspace">
+<aside class="metric-rail"><header><span class="demo">Superstore 演示数据</span><h1>{page['title']}</h1><p class="description">{page['description']}</p></header><section class="metrics" aria-label="当前筛选主要指标">{cards}</section></aside>
+<div class="analysis"><div class="filters" aria-label="分析筛选">{filters}</div>{content}
+<p id="status" class="status" role="status">正在加载…</p>
+<details class="methodology"><summary>数据与指标口径</summary><p>来源：Tableau Superstore 虚构教学工作簿，2021–2024 年，金额单位 USD。退货表先按订单去重，再关联订单行。退货关联销售额不等于退款或收入损失。利润率为合计利润除以合计销售额；订单数与客户数由后端在当前范围内去重，不能累加分组计数。各看板筛选状态独立。</p></details></div>
+<footer><span>2021–2024 · 演示数据 · Data Xpert</span><span id="freshness">尚无当前查询结果</span></footer></main>
+<script>const config={json.dumps(config, ensure_ascii=False, indent=2)};
+{JS}</script></body></html>
+'''
+    if key != 'overview':
+        theme = 'profit-atlas' if key == 'profitability' else 'customer-brief'
+        prefix = 'atlas' if key == 'profitability' else 'brief'
+        global_name = 'ProfitAtlas' if key == 'profitability' else 'CustomerBrief'
+        description = '看清销售与利润之间的差距' if key == 'profitability' else '理解客户结构，关注退货表现'
+        header = f'<header class="{prefix}-header"><div><h1>{page["title"]}</h1><p class="description">{description}</p><span class="demo">Superstore 演示数据 · 2021–2024</span></div><div class="filters" aria-label="分析筛选">{filters}</div></header>'
+        if key == 'profitability':
+            summary = f'<section class="atlas-metrics" aria-label="当前筛选主要指标">{cards}</section>'
+            panel_specs = [('secondary', '销售额与利润关系', '每个点代表一个子品类，悬停查看金额'), ('primary', '子品类利润排名', 'USD · 红色表示负利润')]
+            table = table.replace('USD · 同一筛选范围', '按利润升序 · 完整明细可滚动查看')
+        else:
+            summary = f'<section class="brief-metrics" aria-label="当前筛选主要指标"><div class="brief-primary-metrics">{"".join(metric_blocks[:3])}</div><div class="brief-return-metrics">{metric_blocks[4]}{metric_blocks[3]}</div></section>'
+            panel_specs = [('primary', '<span class="section-number" aria-hidden="true">01</span>客户分群销售贡献', 'USD · 客户数在当前范围内去重'), ('secondary', '<span class="section-number" aria-hidden="true">02</span>各区域退货订单数', '按 Order ID 去重；不代表退货商品件数')]
+        variant_panels = ''.join(f'<section class="panel"><h2>{title}</h2><p class="note">{note}</p><div id="chart-{name}" class="chart" role="img" aria-label="{page["panels"][0 if name == "primary" else 1]}"></div></section>' for name, title, note in panel_specs)
+        script = JS.replace('window.TrendWorkspace', f'window.{global_name}').replace('TrendWorkspaceCharts', 'DashboardCharts')
+        if key == 'customers':
+            script = script.replace("dimension:'Segment',measure:'Sales',label:'销售额（USD）'", "dimension:'Segment',measure:'Sales',label:'销售额（USD）',palette:['blue','segment-two','segment-three']")
+            script = script.replace("label:'退货订单数',decimals:0", "label:'退货订单数',decimals:0,palette:['returns']")
+        html = f'''<!doctype html>
+<html lang="zh-Hans"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Superstore · {page['title']}</title></head>
+<body data-page="{key}" data-dashboard-theme="{theme}@1"><main class="workspace">{header}{summary}
+<div class="analysis"><div class="{prefix}-plots">{variant_panels}</div><div class="full-details">{table}</div>
+<p id="status" class="status" role="status">正在加载…</p>
+<details class="methodology"><summary>数据与指标口径</summary><p>来源：Tableau Superstore 虚构教学工作簿，2021–2024 年，金额单位 USD。退货表先按订单去重，再关联订单行。退货关联销售额不等于退款或收入损失。利润率为合计利润除以合计销售额；订单数与客户数由后端在当前范围内去重，不能累加分组计数。各看板筛选状态独立。</p></details></div>
+<footer><span>2021–2024 · 演示数据 · Data Xpert</span><span id="freshness">尚无当前查询结果</span></footer></main>
+<script>const config={json.dumps(config, ensure_ascii=False, indent=2)};
+{script}</script></body></html>
+'''
+    # Sandbox readers bound individual lines: keep the complete recipe inspectable.
+    markup, scripts = html.split('<script>', 1)
+    html = markup.replace('><', '>\n<') + '<script>' + scripts
+    assert max(len(line.encode('utf-8')) for line in html.splitlines()) <= 500
+    (ROOT / (key + '.html')).write_text(html)
+    queries = []
+    for binding_id, dimensions in page['bindings'].items():
+        fields = [{'id': d, 'sourceField': d, 'label': d, 'logicalType': 'string', 'role': 'dimension', 'nullable': False} for d in dimensions]
+        fields += [{'id': m, 'sourceField': m, 'label': m, 'logicalType': 'decimal' if m in ['Sales', 'Profit', 'ReturnedSales'] else 'int64',
+                    'role': 'measure', 'nullable': m in ['Sales', 'Profit', 'ReturnedSales']} for m in measures]
+        queries.append({
+            'id': binding_id, 'providerId': 'data-xpert.ontology', 'operation': 'action', 'contractVersion': 1,
+            'payload': {'resourceId': '<discovered-resource-id>', 'actionTypeCode': 'sql.query_cube_slice',
+                        'target': {'entityTypeCode': 'semantic_cube', 'entityRef': '<published-model-id>::SuperstoreOrders'},
+                        'params': {'dimensions': dimensions, 'measures': measures,
+                                   'filters': [{'field': d, 'op': 'contains', 'value': ''} for d in ['OrderYear', 'Region', 'Category']], 'limit': 100},
+                        'parameterPaths': {c['controlId']: ['filters', str(i), 'value'] for i, c in enumerate(CONTROLS)}},
+            'parameters': [{'name': c['controlId'], 'controlId': c['controlId'], 'type': 'string', 'required': True,
+                            'defaultValue': '', 'allowedValues': c['allowedValues']} for c in CONTROLS],
+            'output': {'datasetId': binding_id, 'fields': fields, 'grain': dimensions},
+        })
+    (ROOT / (key + '.queries.json')).write_text(json.dumps({'controls': CONTROLS, 'bindings': queries}, ensure_ascii=False, indent=2)+'\n')
+print('Generated three HTML recipes and query plans (no embedded data).')

package/skills/live-dashboard/examples/superstore/checks.json

@@ -0,0 +1,104 @@
+[
+  {
+    "case": "all",
+    "controls": {
+      "year": "",
+      "region": "",
+      "category": ""
+    },
+    "summary": {
+      "Sales": "2326534.354300",
+      "Profit": "292296.814600",
+      "Quantity": "38654",
+      "Orders": "5111",
+      "Customers": "804",
+      "ReturnedOrders": "296",
+      "ReturnedSales": "180504.277900"
+    }
+  },
+  {
+    "case": "west",
+    "controls": {
+      "year": "",
+      "region": "West",
+      "category": ""
+    },
+    "summary": {
+      "Sales": "739813.608500",
+      "Profit": "110798.817000",
+      "Quantity": "12466",
+      "Orders": "1635",
+      "Customers": "686",
+      "ReturnedOrders": "189",
+      "ReturnedSales": "107483.057500"
+    }
+  },
+  {
+    "case": "east",
+    "controls": {
+      "year": "",
+      "region": "East",
+      "category": ""
+    },
+    "summary": {
+      "Sales": "691828.168000",
+      "Profit": "94883.260300",
+      "Quantity": "11159",
+      "Orders": "1475",
+      "Customers": "685",
+      "ReturnedOrders": "44",
+      "ReturnedSales": "41705.144000"
+    }
+  },
+  {
+    "case": "year2024",
+    "controls": {
+      "year": "2024",
+      "region": "",
+      "category": ""
+    },
+    "summary": {
+      "Sales": "745567.531200",
+      "Profit": "95926.347600",
+      "Quantity": "12737",
+      "Orders": "1723",
+      "Customers": "704",
+      "ReturnedOrders": "105",
+      "ReturnedSales": "75502.063900"
+    }
+  },
+  {
+    "case": "furniture",
+    "controls": {
+      "year": "",
+      "region": "",
+      "category": "Furniture"
+    },
+    "summary": {
+      "Sales": "754747.761300",
+      "Profit": "19729.995600",
+      "Quantity": "8369",
+      "Orders": "1819",
+      "Customers": "714",
+      "ReturnedOrders": "136",
+      "ReturnedSales": "59219.174900"
+    }
+  },
+  {
+    "case": "west2024furniture",
+    "controls": {
+      "year": "2024",
+      "region": "West",
+      "category": "Furniture"
+    },
+    "summary": {
+      "Sales": "74155.119500",
+      "Profit": "2892.830000",
+      "Quantity": "909",
+      "Orders": "202",
+      "Customers": "184",
+      "ReturnedOrders": "36",
+      "ReturnedSales": "11587.636500"
+    }
+  }
+]