# Cross System Report Pipeline

> 从外部 API（MCP/钉钉云API）拉数据 → Python 处理计算 → Excel 输出 + 钉钉日志自动填报。 用于周/月报自动化、运营指标汇总、跨系统数据管道搭建。

- Skill: `crimsonblazezero/cross-system-report-pipeline` (Agent Skill)
- Install (CLI): `npx skillmds@latest add crimsonblazezero/cross-system-report-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crimsonblazezero/cross-system-report-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: crimsonblazezero (https://skillmd.com/u/crimsonblazezero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crimsonblazezero/cross-system-report-pipeline

---


# 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` 命令：

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

contents JSON 格式：
```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. **库销比分母**：用销量（件数），不是销售额（金额）