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