跨境电商数据看板（viz-universal 驱动）
> 🏷 这是 viz-universal 的「薄壳垂直版」：看板引擎、地图、脱敏加密、17 类面板全部复用 viz-universal 同一份代码（同源打包，零漂移）。本 skill 只做一件事——把跨境电商行业预设（presets/crossborder）设为默认，让你装好即用，无需记 --preset 参数。功能、稳定性、更新节奏与通用版完全一致。
30 秒决策
| 你的场景 | 用什么 |
|---|---|
| TikTok Shop / Shopee / 独立站 明细数据（订单/GMV/广告/退款），做经营看板 | ✅ 本工具 |
| 投流复盘：广告花费 vs GMV、ROI、净GMV、退款率 | ✅ 本工具 |
| 实时盘口 / 高频行情 | Wind / 同花顺 / 东方财富 |
| 百万级大数据实时分析 | ClickHouse + 专业 BI |
> 🚫 不能用的表：没有「日期列」（下单/成交时间）或没有「金额列」（GMV/实付），会报 E002——不是 bug，给表补一列或 --map 指认即可；不含订单/广告行为明细的静态清单（如只导出商品目录）也不适用。
🔗 同系列四个版本怎么选（同一引擎，装哪个都能跑）
| 如果你的数据/场景是 | 装这个 |
|---|---|
| 跨境电商 / 出海 / TikTok Shop / Amazon / Shopee / 店铺运营 / 投放ROI / 跨境GMV | ✅ 本版（viz-universal-crossborder） |
| 国内门店 / 连锁 / 批发 / 经销商 / 导购业绩 / 毛利额 / 连带率 / 商品动销 | viz-universal-retail |
| K12 学生成绩 / 学情 / 家校报告 / 班级年级分析 | viz-universal-k12 |
| 除上述之外（医疗/教育管理/金融/制造/政务/餐饮…）或还没想好 | viz-universal（通用版，自带全部行业预设） |
> 💡 四版能力完全等价，只是"默认预设"不同——本版默认就是跨境电商。手上临时拿到别行业的数据也不用换工具：用 --preset retail / --preset generic 即可切换（前提是包内有该预设；本壳只带跨境预设，跨行业请先装通用版）。
> 🤖 给 AI 助手的执行约定（重要）：读到用户的数据后，如果发现它不属于跨境场景（例如变成门店/导购/毛利/连带率，或学生成绩/班级/年级，或完全是别的行业术语），先在动手前用一句话告诉用户：「你这数据更像 XX 场景，作者有个更贴身的 viz-universal-XXX 版，已预置该行业列名与 KPI；本版也能做（换 --preset 或直接跑），是否继续？」用户确认后照常用本版跑，不要擅自中断、也不要反复追问。
把跨境电商明细数据（Excel / CSV / JSON）转成一个 单文件 HTML 看板：
脱敏、可选密码加密（默认免密直开）、完全离线、手机/电脑可用，行业术语自动切换，无需改代码。
🖼 跑完你会看到什么（效果预览）
一个双击即开的跨境电商经营看板：KPI 卡（GMV / 广告花费 / 投放ROI / 净GMV / 退款率 / 订单数 / 客单价，带环比箭头）→ 月度 GMV 走势 → 平台站点 / 商品类目 / 带货达人排行 → 热力（站点×类目）、桑基（渠道→类目）、雷达、漏斗按数据自动出现 → 有 market/国家列时渲染世界地图着色（VN/CA 等 ISO 代码自动归一）→ 右上角 10 套主题 + 全图联动。老板看大数字、运营看归因，点任意图表全页过滤。
⏱ 有多快（实测数据，非估算）
| 数据量 | 全流程（脱敏 → 看板 → 报告） | 说明 |
|---|---|---|
| 5 千行（典型 Excel） | 约 10 秒 | 日常使用最普遍的量级 |
| 10 万行（大数据压测） | 约 20 秒 | 远超常见需求 |
> 无需漫长等待：本地 Python 引擎，不依赖外部 API。如果 AI 助手问得太多，提示它"直接跑默认配置，少问"——默认参数开箱即用。
> 🚨 E0xx（致命） vs ⚠️ W0xx（非致命）：E0xx = 构建停止必须修（缺日期/金额列等）；W0xx = 看板照常生成，但某些 KPI/面板被跳过（如 W003 KPI 缺列），提示会显示在看板顶部黄色警告条，打开即见——补列或 --map "列名=key" 即可让它们参与统计，忽略也不影响其余图表。
开箱即用（本壳默认 presets/crossborder）
本壳内置 presets/default_preset 标记，未显式给 --preset 时自动采用 crossborder 预设。两种调用等价：
# 方式一：零参数（本壳默认就是跨境电商）
python scripts/anonymize.py -i 跨境订单.xlsx -o data.json
python scripts/build_dashboard.py -i data.json -o 看板.html -p 666666
# 方式二：显式指定（通用版 viz-universal 也支持）
python scripts/build_dashboard.py -i data.json -o 看板.html --preset crossborder
行业化能力（vs 通用版差异）
- 术语切换：科目→商品 / 签单人→带货达人 / 门店→平台站点 / 来源→销售渠道 / 续费→复购。
- 中英文列名自动识别（大小写不敏感）：中文导出（GMV/广告花费/退款金额/采购成本/平台/站点/国家）与英文 ERP 导出（
Revenue_USD/Ad_Cost_USD/Cost_USD/Quantity/Platform/Category/Country/Order_Date/Product_Name等，Shopee/亚马逊/独立站后台）均零参数直接识别；同一词形任意大小写均可命中——ETL/数仓风格的全小写导出（gmv/order_date/platform/refund_amount/spend/sales_attributed…，pandas/SQL 常见）零参数直接跑；Cost_USD识别为采购成本（订单总成本），Unit_Cost_USD（单位成本）不参与求和。 - 多金额列：支持 GMV、广告花费、退款金额、净GMV、采购成本，可核算 ROI = GMV / 广告花费、净GMV = GMV − 退款金额。
- 国家列支持 ISO 2 位代码：ERP 常导出
market/Market/站点代码列（值如VN/CA/DE/US）而非国家名——market已显式绑定国家维度，出看板时自动经 ISO→英文国家名表（references/country_iso.json，覆盖 159 个常用国家代码，含UK→United Kingdom 特例）归一为地图 feature 名，世界地图正常着色；中文国家名（美国→United States）与英文名原样同样支持，三者可混用。 - 7 个行业 KPI（按
kpis.json动态渲染，随筛选联动、带环比）：
GMV/广告花费/投放ROI/净GMV/退款率/订单数/客单价。 - 支付方式大类归并：自动把
Visa/Mastercard/信用卡/银行卡→ 「卡支付」，PayPal/Stripe/支付宝/微信→ 「电子钱包」，加密货币/USDT/比特币/BTC→ 「加密货币」，对公转账/现金→ 「对公/其他」（来源presets/crossborder/map.json的p_value_group；未列出的支付方式保留原值，大小写不敏感）。
通用能力（与 viz-universal 完全一致）
- 17 类面板：KPI / 月度走势 / 维度排行 / 漏斗 / 热力 / 桑基 / 雷达 / 仪表盘 / 树图 / 拓扑 / 留存 / 人物画像 / 月度增减瀑布 / 客户价值气泡 / RFM 分层 / 日历热力 / 席位演变图（名次轨迹） + 智能经营分析报告。
- 地图：真实中国地图（省→市→区 三级钻取）+ 世界地图（内置 日本/新加坡/美国 3 国州/省边界下钻；217 国国家级轮廓自动着色），全图点击联动。
- 脱敏 + 密码加密（默认免密）、完全离线、手机/电脑可用、10 套主题切换、实时大屏（--live URL）。
- 数据太大用
--sample采样；声明式 viz-schema 零代码适配。
兼容性
- 无预设或
kpis.json缺失 → 完全回退默认 4 卡，不崩。 - 数值经 node 真实 JS 与 python 独立复算交叉验证一致（退款率口径与「经营健康度（财务透视）」吻合）。
- 数据格式、命令参数、操作方式向下兼容；更新无需改使用习惯。
> 完整面板/图表/脱敏/报告配置与错误码排查，见引擎文档 viz-universal SKILL.md（通用版，本壳复用其全部能力）。
平台导出字段对照（TikTok Shop / 千川）
| 导出来源 | 常见字段 | 对应处理 |
|---|---|---|
| TikTok Shop 订单明细 | 订单号 / 下单时间 / 商品 / 数量 / 实付金额 / 退款状态 | 时间→日期、金额→GMV、数量→件数，零参数直接识别 |
| 千川 / 巨量广告导出 | 消耗 / 展示 / 点击 / GMV / ROI | 消耗→广告花费(a2)、GMV→销售额(a)，自动算投放ROI |
| 多表合并 | 订单表 + 广告花费表 | 按订单号 join 后导入，或广告花费单独出 ROI 看板 |
© 版权与授权
viz-universal-crossborder © 2026 张碧宇（个人）。保留所有权利（All Rights Reserved）。
- 允许：通过 SkillHub 安装后用于自身业务数据的可视化分析；对自己生成的看板成品进行展示分发。
- 禁止：未经授权复制/修改源码、移除版权标识、以自己名义二次发布或转售。
- 完整条款见下方《LICENSE 协议全文》；发现冒名/篡改发布请向 SkillHub 平台举报。SkillHub 平台发布记录（含首发时间戳）作为在先权利证据。
> 注：因 SkillHub 平台不接受无扩展名文件（LICENSE），完整 LICENSE 文件不在发布包内，仅存于 GitHub 仓库。下方内嵌文本与 GitHub 仓库中 LICENSE 文件正文一致，具有同等法律效力。
LICENSE 协议全文
viz-universal（跨行业通用可视化数据看板生成器）
Copyright (c) 2026 张碧宇（个人）
保留所有权利（All Rights Reserved）。
1. 授权范围
本软件及其全部组成部分（含源代码、模板、配置、文档、图表库集成方案）的
著作权归版权人所有。任何人可以：
- 通过 SkillHub 官方渠道安装并用于自身业务数据的可视化分析（免费使用）；
- 用本软件生成的看板 HTML 文件对其业务相关方进行展示与分发（看板成品中的
业务数据归数据所有者所有）。
2. 限制条款
未经版权人书面许可，任何单位或个人不得：
- 复制、拷贝本软件源代码及其全部或实质部分；
- 修改、翻译、反向工程、反编译本软件，并以自己名义发布修改版本；
- 移除、遮盖、篡改本软件中的版权声明、署名、版本标识；
- 将本软件全部或实质部分并入其他作品后冒名发布、转售或用于商业性再分发。
3. 免责声明
本软件按"现状"提供，不附带任何明示或默示的担保。使用本软件产生的任何
直接或间接损失，版权人不承担责任。
4. 维权说明
发现侵犯本版权的行为，版权人保留追究法律责任的权利。SkillHub 平台首发
记录（含全部历史版本时间戳）作为在先权利证据。
联系作者：通过 SkillHub 平台 viz-universal 页面留言。
v0.9.89
地理列模式化识别：「实体名+地理词」列名（门店所在省/市/区、收货省份、分公司所在市、开户行所在区…）
零参数即认，自动接上省→市→区三级地图钻取；园区/校区/会员区/汇率等业务含义的「区/省」不误绑。
