观远数据 BI 数据集下载

从观远数据 BI 平台下载完整数据集，自动处理登录、分页、按月切片。

凭据管理

首次使用时，脚本会自动弹出现代 Web 风格登录窗口：

需输入平台地址、工号和密码三个字段
密码输入框支持 👁 显示/隐藏切换
勾选"记住登录信息"后，凭据保存至 ~/.guandata-bi-credentials.json
密码使用 Windows DPAPI 加密存储（非 Windows 降级 Base64 编码）
不写入系统环境变量 / 注册表
后续使用无需再次输入，直接跳过登录界面

凭据读取优先级

当前会话环境变量（GUANBI_BASE_URL / GUANBI_LOGIN_ID / GUANBI_PASSWORD）
加密凭据文件 ~/.guandata-bi-credentials.json（密码字段 DPAPI 加密）
弹出登录窗口

安全机制

| 措施 | 说明 | |------|------| | 源码零密码 | Skill 所有文件不含任何密码、账号、平台地址 | | DPAPI 加密 | 凭据文件中密码字段使用 Windows DPAPI 加密，仅当前用户可解密 | | 内存隔离 | 凭据仅写入当前进程内存环境变量，不持久化到系统注册表 | | 兼容旧版 | 解密时自动识别 dpapi: / b64: / 明文格式，平滑迁移 |

安全保证: Skill 源码中不含任何密码、账号或平台地址。凭据加密保存到用户家目录下，仅本人可解密。

使用方式

当用户提供数据集 URL 或 ID 时，使用打包的脚本执行下载：

python scripts/fetch_bi.py <数据集URL或ID> [选项]

常见触发场景

"帮我下载这个数据集 https://bi.example.com/data-center/data-sets/xxx/yyy/details/overview"
"下载数据集 od1437c38086e44baa7a0aba"
"从BI导出这个报表数据"

参数说明

| 参数 | 必填 | 说明 | |------|------|------| | dataset | 是 | 数据集 ID 或完整 URL，自动提取 ID | | --output / -o | 否 | 输出 CSV 路径（默认 ./<id>.csv） | | --start | 否 | 起始日期 YYYY-MM-DD（默认自动检测） | | --end | 否 | 结束日期 YYYY-MM-DD（默认今天） | | --base-url | 否 | BI 平台地址（默认从 GUANBI_BASE_URL 读取） |

执行示例

# 从 URL 下载
python scripts/fetch_bi.py "https://bi.example.com/data-center/data-sets/xxx/yyy/details/overview" -o ./output.csv

# 指定日期范围
python scripts/fetch_bi.py od1437c38086e44baa7a0aba --start 2025-01-01 --end 2025-06-30

工作原理

环境检查: 启动时校验必要环境变量是否已配置
登录: 向 {base_url}/public-api/sign-in 发送 POST 请求，密码 Base64 编码后传输（凭据从加密文件/弹窗获取，非硬编码）
获取下载 token: GET {base_url}/api/data-source/{ds_id}/data-fetch-token
探测数据集结构: 调用一次 API 获取总行数、列名，自动检测日期字段名
自动检测日期字段: 按优先级尝试 访问时间、年月日期、日期、创建时间、更新时间，或匹配含"时间"/"日期"的列名
按月分批下载: 按月生成 GE/LT 日期过滤条件
自动省份分片: 若单月数据超过 5 万行，自动按省份分片；若省份仍超限，进一步按城市细分
补充 NULL 行: 下载日期字段为 NULL 的记录（仅全量下载时）
保存 CSV: UTF-8 BOM 编码

技术要点

API 限流: 单次 API 最多返回 50,000 行，按月切片确保不超限
API 不支持分页: page/pageSize/offset/limit 参数均被忽略，始终返回相同的前 5 万行。必须用过滤器分片。
日期字段自适应: 不同数据集的日期字段名不同，脚本自动检测
省份字段自适应: 支持"省"、"省份"、"省级行政区"等字段名，自动匹配并分片
密码安全: 凭据保存至 ~/.guandata-bi-credentials.json，密码字段使用 Windows DPAPI 加密存储。不写入系统环境变量。Skill 源码中不含任何密码或平台地址。
日期过滤: 使用 GE（>=）和 LT（<）避免边界重叠
省份分片: 大数据集（单月 > 5 万行）自动按 34 个省级行政区分片下载；若省份仍超限，按城市细分
性能: 55 个月批次约需 50 秒完成；33 万行按省份分片约需 30 秒

已知数据集类型

| 数据集 | 日期字段 | 省份字段 | 典型行数/月 | 说明 | |--------|----------|----------|-------------|------| | BI 访问日志 | 访问时间 | 无 | 2-3 万 | 管理层 BI 访问分析，按月分批即可 | | 终端零售 | 年月日期 | 省 | 30 万+ | 汽车终端零售数据，需按省份分片 | | 终端订单 | 下单日期 | 省份 | 5 万+ | 汽车终端订单数据，含车系/配置/颜色等维度 |

输出格式

CSV 文件为 UTF-8 BOM 编码。列名取决于数据集本身，例如：

BI 访问日志: 资源id, 资源名称, 用户名称, 访问用户一级部门, ...
终端零售: 品牌, 车系, 型号/车型名称, 大区, 省, 市, 年, 月, ...