cross-system-report-pipeline

name	cross-system-report-pipeline
description	从外部 API（MCP/钉钉云API）拉数据 → Python 处理计算 → Excel 输出 + 钉钉日志自动填报。 用于周/月报自动化、运营指标汇总、跨系统数据管道搭建。
tags	["report","pipeline","excel","dingtalk","mcp","automation"]
metadata	{"author":"agnes","created":"2026-07-26T00:00:00.000Z","updated":"2026-07-26T00:00:00.000Z"}

Cross-System Report Pipeline

从多个数据源拉取业务数据，进行计算转换后写入 Excel 并自动提交到钉钉日志/报表的自动化管道。

适用场景

• 周报/月报自动填数据
• 从 ERP、CRM、财务系统拉取销售/库存/利润数据
• 多币种/多站点数据合并
• 钉钉日志模板填报
• Excel 指标计算与校验

核心流程

[数据源A] ──→ [脚本拉取/解析] ──┐
[数据源B] ──→ [脚本拉取/解析] ──┼──→ [Python 计算/转换] ──→ [Excel 输出]
[数据源C] ──→ [脚本拉取/解析] ──┘                              ↓
                                                            [钉钉日志/群投递]

Step 1：确认数据源与权限边界

在写代码前，先实测所有数据源的接口能力：

检查项	做法
是否只读？	调用 list/get/query 类接口确认；调用 create/update/delete 验证是否返回权限错误
QPS 限制	测试并发调用是否会触发限流；记录实际可用 QPS
分页方式	确认是 page/offset 还是 cursor 模式；每页条数限制
字段命名	记录实际字段名（而非 API 文档名），特别是日期格式、货币符号、状态码

示例：领星 MCP 实测结论

• get_profit_report_msku 返回 4453 条记录但一页只 50 条 → 需要分页
• 广告报表并发时触发"服务器繁忙" → 需串行或降速
• 自定义指标接口返回无权限 → 标记为不可用

Step 2：数据拉取与解析

关键原则：不要假设数据结构，先用示例数据打印完整结构再编写解析逻辑。

常见陷阱：

• MCP 返回值可能是嵌套 JSON：{result: "{\"code\":0,...,"data":{"records":[...]}}} → 需要二次 json.loads
• 字段可能为 null、空字符串 ""、或者数字 0 → 统一做 float(val or 0)
• 日期范围：用户说的"本周"可能指"上周日到今天"，而非自然周

Step 3：业务规则计算

每个业务场景都有特定计算规则，必须单独验证：

业务规则	示例
毛利修正系数	领星 predict_gross_profit × 0.6 ÷ 6.8109（部分成本未扣减，周报/周会纪要统一口径）
ACoS	优先直接从广告报表取，不手动算 ads/sales
目标设定	周目标 = 月目标 / 4；下期目标可累加未完成部分
库存清货效率	90-180天目标 = 当前 × 0.8；181-270天目标 = 当前 × 0.5；271-365天目标 = 当前 × 0.3；366天以上目标 = 当前 × 0.1
库销比	FBA 总库存件数 ÷ 日均销售件数（不是日均销售额）

Step 4：Excel 写入策略

两种模式可选：

A. 更新现有模板（适合"运营周会数据收集"类固定表）

• 读取现有 xlsx 文件
• 定位目标行/列（通常按姓名/负责人标识）
• 覆盖写入数值
• 保持原有格式和公式

B. 生成新汇总文件（适合需要独立交付的场景）

• 新建 Workbook
• 按业务维度分 Sheet
• 输出摘要 + 明细

Step 5：钉钉日志自动填报

使用 dws report entry submit 命令：

dws report entry submit \
  --template-id <模板ID> \
  --contents-file <JSON文件路径> \
  --format json

contents JSON 格式：

[
  {
    "key": "字段名",
    "sort": "排序号",
    "type": "字段类型(1文本/2数字/9附件/13富文本)",
    "content": "值",
    "contentType": "markdown"
  }
]

Step 6：调度与重试机制

防重复执行：

• 用 lock file 记录上次成功时间戳
• 同一天内：首次失败后每 2 小时允许重试一次
• 不同天：自动恢复运行

通知控制：

• 用户明确说"成功投递信息后，现在不在群里通知"
• 默认静默；仅失败时需要告警

参考文件

见 references/ 目录下的具体场景笔记：

• lingxing-mcp-notes.md：领星 MCP 实测数据、字段映射、已知坑

Pitfalls

1. MCP 结果嵌套：很多 MCP 返回的是 JSON 字符串，需要 json.loads 二次解析
2. QPS 限流：并发调用 MCP 接口容易触发"服务器繁忙"，串行或加间隔
3. 字段为空：null、""、0 都要安全处理
4. 日期口径：用户说"上周到本周六"≠自然周，需确认具体范围
5. A科AS别手算：优先用广告报表原始 ACoS；利润报表里的广告费只做备用
6. 库销比分母：用销量（件数），不是销售额（金额）