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