数据同步API
**本文档引用的文件** - [[bi-plan-taoxi/openapi.yaml]](../api/file/bi-plan-taoxi/openapi.yaml) - [[bi-api-jushuitan/internal/data/client/streamload.go]](../api/file/bi-api-jushuitan/internal/data/client/streamload.go) - [[bi-common/database/starrocks/streamload/response.go]](../api/file/bi-common/database/starrocks/streamload/response.go) - [[ui-web/next.config.ts]](../api/file/ui-web/next.config.ts) - [[ui-crx/background.js]](../api/file/ui-crx/background.js) - [[bi-notify/internal/biz/platform_callback_retry.go]](../api/file/bi-notify/internal/biz/platform-callback-retry.go) - [[bi-notify/internal/biz/feishu_adapter.go]](../api/file/bi-notify/internal/biz/feishu-adapter.go) - [[bi-api-jushuitan/internal/data/client/streamload.go]](../api/file/bi-api-jushuitan/internal/data/client/streamload.go) - [[bi-common/database/starrocks/streamload/response.go]](../api/file/bi-common/database/starrocks/streamload/response.go)
目录
简介
本文件面向数据同步服务，聚焦于以下外部数据源的同步能力：
- 乐刻（Leke）：提供商品、订单、库存等业务数据的同步接口与映射规则
- 聚水潭（Jushuitan）：提供库存、出入库、采购等仓储数据的同步接口与入库策略
- 淘系计划（Taoxi Plan）：提供广告计划、关键词、报表等营销数据的查询与批量操作接口
文档覆盖同步策略（全量/增量）、数据映射与字段转换、数据验证、错误重试与断点续传、状态监控与故障处理、以及性能优化与批量处理策略。
项目结构
围绕数据同步的关键模块包括：
- 外部平台API网关与路由：前端Next.js通过反向代理将特定路径转发至后端服务
- 平台回调与重试：平台回调消息的持久化、重试调度与死信处理
- 数据落库：通过StarRocks StreamLoad进行高性能批量写入
- 前端扩展（CRX）：浏览器插件侧的采集、缓存与批量上传
图表来源
- [ui-web/next.config.ts]
- [bi-plan-taoxi/openapi.yaml]
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
章节来源
核心组件
- 淘系计划API：提供账户余额、计划列表、计划详情、关键词管理、报表查询等接口，支持批量更新出价/预算、批量增删改关键词等
- 聚水潭API：提供库存查询等数据的接收与入库，采用StreamLoad进行批量写入
- 通知与重试：对平台回调消息进行重试调度、死信处理与状态管理
- 前端CRX：本地采集指标，按批次与时间窗口触发上传，具备断点续传与状态反馈
章节来源
- [bi-plan-taoxi/openapi.yaml]
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
- [ui-crx/background.js]
架构总览
数据从各外部平台经API网关进入后端服务，完成数据映射与校验后，批量写入StarRocks；同时平台回调消息由通知服务负责重试与死信处理；前端CRX在本地聚合数据并按策略批量上传。
图表来源
- [ui-web/next.config.ts]
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-common/database/starrocks/streamload/response.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
详细组件分析
淘系计划API（Taoxi Plan）
- 接口范围：账户余额、计划列表/详情、关键词列表/增删改、关键词建议、账户/计划/关键词/实时报表查询
- 批量操作：批量更新计划出价/预算
- 数据模型：包含Campaign、Keyword、报表项等Schema定义，字段涵盖标识、状态、预算/出价、效果指标等
- 使用场景：广告投放策略调整、效果监控与报表分析
图表来源
章节来源
聚水潭API（Jushuitan）与数据落库
- 数据入口：库存查询等数据通过API接收
- 数据落库：使用StarRocks StreamLoad进行高性能批量写入，支持超时与重试配置
- 写入流程：序列化为JSON，设置外层数组剥离参数，提交后根据响应状态判断成功/失败
图表来源
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-common/database/starrocks/streamload/response.go]
章节来源
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-common/database/starrocks/streamload/response.go]
平台回调重试与死信处理
- 重试调度：基于定时器周期性拉取待重试消息，按批大小与最大重试次数控制
- 死信处理：达到最大重试次数后，将消息发送至死信主题
- 状态管理：根据发送结果更新记录状态（RETRY/FAILED/DEAD）
图表来源
章节来源
前端CRX数据采集与批量上传
- 采集循环：按权限通道轮询采集指标，本地缓存队列
- 批量上传：当队列长度或时间间隔达到阈值时触发上传；上传后更新已上传计数与最后上传时间
- 断点续传：通过状态存储与重试机制保障离线/失败后的恢复
- 错误处理：上传失败时记录状态，后续循环继续尝试
图表来源
章节来源
依赖关系分析
- 前端Next.js通过反向代理将特定路径转发至对应后端服务，确保跨域与统一入口
- 聚水潭API依赖StarRocks StreamLoad客户端进行批量写入，写入响应用于判定成功/失败
- 通知服务依赖Kafka/消息队列进行回调消息的持久化与重试调度
图表来源
- [ui-web/next.config.ts]
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
章节来源
- [ui-web/next.config.ts]
- [bi-api-jushuitan/internal/data/client/streamload.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
性能考虑
- 批量写入：通过StarRocks StreamLoad进行批量JSON写入，减少网络往返与事务开销
- 超时与重试：StreamLoad客户端配置超时与最大重试次数，提升稳定性
- 前端聚合：CRX侧按批次与时间窗口触发上传，避免频繁小包传输
- 并发控制：CRX内部通过队列与并发限制控制采集与上传的节奏
章节来源
故障排查指南
- 写入失败：检查StreamLoad响应状态与错误URL，确认数据库连接、表结构与数据格式
- 重试异常：查看重试服务日志，确认批大小、最大重试次数与间隔配置
- 死信处理：核对死信主题配置，定位无法处理的消息并修复
- 前端上传失败：检查CRX状态存储与鉴权信息，确认上传触发条件与网络状况
章节来源
- [bi-common/database/starrocks/streamload/response.go]
- [bi-notify/internal/biz/platform_callback_retry.go]
- [bi-notify/internal/biz/feishu_adapter.go]
- [ui-crx/background.js]
结论
本文档梳理了乐刻、聚水潭与淘系计划三类外部数据源的同步接口与实现要点，明确了全量/增量策略下的数据映射、字段转换与验证流程，给出了错误重试、断点续传与一致性保障方案，并总结了性能优化与批量处理策略。结合前端CRX的本地聚合与后端StreamLoad的高效写入，可构建稳定、可观测且高性能的数据同步体系。