bi-plan-taoxi 淘系计划服务
**本文引用的文件** - [[go.mod]](../file/bi-plan-taoxi/go.mod) - [[main.go]](../file/bi-plan-taoxi/cmd/bi-plan-taoxi/main.go) - [[wire.go]](../file/bi-plan-taoxi/cmd/bi-plan-taoxi/wire.go) - [[models.go]](../file/bi-plan-taoxi/internal/biz/models.go) - [[requests.go]](../file/bi-plan-taoxi/internal/biz/requests.go) - [[taobao_client.go]](../file/bi-plan-taoxi/internal/data/taobao-client.go) - [[data.go]](../file/bi-plan-taoxi/internal/data/data.go) - [[grpc.go]](../file/bi-plan-taoxi/internal/server/grpc.go) - [[http.go]](../file/bi-plan-taoxi/internal/server/http.go) - [[taoxi.go]](../file/bi-plan-taoxi/internal/service/taoxi.go) - [[openapi.yaml]](../file/bi-plan-taoxi/openapi.yaml) - [[application-dev.yaml]](../file/bi-plan-taoxi/configs/application-dev.yaml) - [[taoxi.proto]](../file/bi-plan-taoxi/api/taoxi/v1/taoxi.proto)
更新摘要
所做更改
- 更新了依赖关系分析，移除了对 bi-proto 模块的依赖
- 新增了本地 proto 文件生成和使用的说明
- 更新了项目结构图，反映新的依赖关系
- 补充了 proto 文件管理和代码生成的工作流程
目录
简介
本项目为"bi-plan-taoxi 淘系计划服务"，面向淘系广告计划（万相台无界）提供统一的数据获取、处理与分析能力。系统通过集成淘宝客开放平台（TOP）API，实现对广告计划、关键词、创意、人群等核心对象的查询与管理，并提供账户余额、实时与多维报表等数据能力。服务采用 Kratos 微服务框架，支持 gRPC 与 HTTP 双栈接入，具备完善的日志、追踪与中间件链路。
更新 本项目已移除对 bi-proto 模块的外部依赖，改为使用本地 proto 文件进行接口定义和代码生成，提高了项目的独立性和可维护性。
项目结构
- 应用入口与依赖注入
- 入口程序：cmd/bi-plan-taoxi/main.go
- 依赖注入：cmd/bi-plan-taoxi/wire.go
- 业务层（biz）
- 数据模型与请求参数：internal/biz/models.go、internal/biz/requests.go
- 数据层（data）
- TOP 客户端与仓库实现：internal/data/taobao_client.go、internal/data/data.go
- 服务层（service）
- gRPC 服务实现：internal/service/taoxi.go
- 传输层（server）
- gRPC/HTTP 服务器装配：internal/server/grpc.go、internal/server/http.go
- 接口定义与文档
- 本地 proto 文件：api/taoxi/v1/*.proto
- OpenAPI 文档：openapi.yaml
- Nacos 开发配置：configs/application-dev.yaml
- 模块依赖：bi-plan-taoxi/go.mod
图表来源
- [main.go]
- [wire.go]
- [taoxi.go]
- [data.go]
- [taobao_client.go]
- [grpc.go]
- [http.go]
- [application-dev.yaml]
- [openapi.yaml]
章节来源
核心组件
- 服务接口与协议
- TaoxiService：提供计划、关键词、创意、人群、报表等查询与管理接口
- 本地 proto 定义：覆盖账户余额、计划列表/详情、关键词、报表查询等
- 数据模型
- 报表指标：Charge、AdPv、Click、Ctr、Ecpc、Ecpm、Roi、Cvr、AlipayInshopAmt/Num、CartInshopNum、InshopPv/Uv、RhNum
- 计划/单元/关键词/人群/创意：包含 ID、名称、状态、时间、预算/出价、匹配类型、质量分等
- TOP 客户端
- 支持 HMAC-SHA1 签名、TOP 服务上下文透传、统一响应解析
- 仓库与服务
- 仓库负责对接 TOP API 并返回领域模型
- 服务负责协议转换与业务编排
章节来源
架构总览
系统采用分层架构：入口层负责配置加载与依赖注入；传输层提供 gRPC/HTTP 接口；服务层实现业务逻辑；数据层封装 TOP API 调用；配置层从 Nacos 加载运行时配置。
图表来源
详细组件分析
1) 服务接口与 OpenAPI 文档
- 接口范围
- 账户：获取账户余额
- 计划：列表查询、详情查询、批量更新出价/预算
- 关键词：列表查询、批量新增/修改/删除、建议
- 报表：账户、计划、单元、关键词、人群、创意、地域、实时
- OpenAPI 覆盖
- 路径与方法：见 openapi.yaml 的 paths
- 请求/响应模型：见 openapi.yaml 的 components/schemas
- 使用建议
- 前端或下游服务可通过 HTTP 网关访问；内部服务可走 gRPC 提升性能
章节来源
2) 业务模型与字段定义
- 报表指标
- 字段：花费、展现、点击、点击率、平均点击花费、千次展现花费、投入产出比、成交转化率、成交金额/笔数、加购数、引导访问量/人数、入会量
- 计划
- 字段：计划ID、名称、营销场景、状态、预算/类型、出价/类型、起止时间、创建/修改时间、计划组ID/名称
- 单元
- 字段：单元ID、名称、所属计划、状态、出价、推广信息、图片、创建/修改时间
- 关键词
- 字段：关键词ID、词、所属计划/单元、出价、匹配类型、状态、质量分、创建时间
- 人群
- 字段：人群ID、名称、所属计划/单元、出价、折扣、状态、人群类型、覆盖人数
- 创意
- 字段：创意ID、名称、所属计划/单元、状态、类型、图片/视频路径、尺寸、标题、创建/修改时间
- 账户
- 字段：余额、现金余额、券余额、营销场景、推广商品等
章节来源
3) 请求参数与批处理
- 报表查询
- 支持按时间范围、效果归因、维度拆分、统一类型、分页偏移、业务码过滤、计划/单元/关键词/创意筛选等
- 计划/单元/关键词/人群/创意
- 分页查询、批量更新出价/预算、新增/修改/删除、建议词、质量分查询等
- 批处理
- 批量更新出价/预算、批量新增/修改/删除关键词等
章节来源
4) TOP 客户端与数据同步
- 客户端能力
- 统一签名（HMAC-SHA1）、系统参数拼装、TOP 服务上下文透传、响应解析与错误提取
- 仓库实现
- 以领域模型为中心，调用 TOP API 并映射为 biz 层结构
- 当前已实现：实时报表查询
- 其他报表与管理接口预留（待实现）
图表来源
章节来源
5) 传输层与中间件
- gRPC/HTTP 中间件
- 链路追踪、请求ID、日志、恢复（panic）等
- 服务器装配
- 支持网络、地址、超时等配置项
- OpenAPI 网关
- 通过 HTTP 服务器注册 OpenAPI 路由
章节来源
6) 配置与部署
- 配置来源
- Nacos：开发环境配置文件 application-dev.yaml
- 配置项：Nacos 服务地址、命名空间、分组、超时、配置 data_id 列表
- 启动流程
- main.go 读取 -env 参数选择配置文件，加载 Nacos 配置，初始化日志与依赖注入，启动 gRPC/HTTP 服务
章节来源
依赖关系分析
- 模块依赖
- 使用 Kratos、Wire、gRPC-Gateway、OpenTelemetry、Prometheus 等生态组件
- 本地替换 bi-common 与 bi-server，便于本地联调
- 更新 移除了对 bi-proto 模块的依赖，改为使用本地 proto 文件
- 运行时依赖
- 日志、注册中心（Nacos）、配置中心（Nacos）、可观测性（Tracing/Metrics）
图表来源
章节来源
更新 依赖关系已更新，移除了对 bi-proto 模块的外部依赖，改为使用本地 proto 文件进行接口定义和代码生成。这提高了项目的独立性和可维护性，减少了对外部模块的依赖。
性能考虑
- 并发与资源
- 使用 automaxprocs 自动设置 GOMAXPROCS，提升并发效率
- 网络与超时
- HTTP 客户端默认 30 秒超时；gRPC/HTTP 服务器支持超时配置
- 中间件
- 开启追踪与恢复中间件，有助于定位性能瓶颈与异常
- 扩展建议
- 对高频报表接口增加缓存层
- 对批量操作进行分片与并发控制
- 对 TOP API 增加重试与熔断策略
章节来源
故障排查指南
- 常见问题
- TOP 签名失败：检查 app_key、app_secret、时间戳与排序规则
- 响应解析失败：确认 responseKey 与数据结构是否匹配
- API 返回错误：查看子代码与子消息，结合业务参数定位
- 日志与追踪
- 服务端中间件输出请求ID与日志，便于串联链路
- 建议流程
- 复现步骤 → 检查请求参数与签名 → 查看响应结构 → 对照 OpenAPI 文档 → 定位仓库/服务实现
章节来源
结论
bi-plan-taoxi 服务已完成基础架构搭建与 TOP 客户端封装，实现了 OpenAPI 规范与 gRPC/HTTP 双栈接入。当前重点在实时报表查询与计划/关键词/创意/人群等核心对象的仓库映射上，后续可按优先级扩展各类报表与管理接口，完善批处理、增量更新与错误重试机制，持续提升稳定性与性能。
更新 项目已成功移除对 bi-proto 模块的依赖，采用本地 proto 文件管理的方式，提高了项目的独立性和可维护性。这种调整使得项目更加轻量化，减少了外部依赖带来的复杂性。
附录
A. API 接口清单（节选）
- 账户
- GET /api/v1/taoxi/account/balance
- 计划
- GET /api/v1/taoxi/campaigns
- GET /api/v1/taoxi/campaigns/
- POST /api/v1/taoxi/campaigns/bid/batch
- POST /api/v1/taoxi/campaigns/budget/batch
- 关键词
- GET /api/v1/taoxi/keywords
- PUT /api/v1/taoxi/keywords/batch
- POST /api/v1/taoxi/keywords/batch
- POST /api/v1/taoxi/keywords/batch/delete
- POST /api/v1/taoxi/keywords/suggest
- 报表
- POST /api/v1/taoxi/report/account
- POST /api/v1/taoxi/report/campaign
- POST /api/v1/taoxi/report/keyword
- POST /api/v1/taoxi/report/realtime
章节来源
B. 数据模型字段参考（节选）
- 报表指标
- Charge、AdPv、Click、Ctr、Ecpc、Ecpm、Roi、Cvr、AlipayInshopAmt/Num、CartInshopNum、InshopPv/Uv、RhNum
- 计划
- CampaignID、CampaignName、BizCode、Status、Budget、BudgetType、Bid、BidType、PromotionModel、OptimizeTarget、StartTime、EndTime、CreateTime、ModifyTime、CampaignGroupID、CampaignGroupName
- 关键词
- BidwordID、Word、CampaignID、AdgroupID、Bid、MatchType、Status、Qscore、CreateTime
- 人群
- CrowdID、CrowdName、CampaignID、AdgroupID、Bid、Discount、Status、CrowdType、Coverage
- 创意
- CreativeID、CreativeName、CampaignID、AdgroupID、Status、CreativeType、ImagePath、VideoPath、CreativeSize、Title、CreateTime、ModifyTime
章节来源
C. Proto 文件管理与代码生成
- 本地 proto 管理
- 所有接口定义位于 api/taoxi/v1/ 目录下
- 包含 taoxi.proto 主文件和各功能模块的 proto 文件
- 使用本地 proto 文件替代外部 bi-proto 模块
- 代码生成流程
- 使用 protoc 工具生成 Go 代码
- 生成 pb.go 和 HTTP/gRPC 桩代码
- 支持 OpenAPI 文档生成
章节来源