跳转至

更新日志

所有重要的项目变更都将记录在此文件中。

格式基于 Keep a Changelog， 并且本项目遵循 语义化版本。

[1.0.1] - 2025-09-14

新增

  • 响应类型化（对齐 Java DTO）：
  • 资金服务：open.funds.financial.settled.bill.detail → OrderBillDetailPageData（含 orders+cursor）。
  • 分销服务：
    • 快手币推广效果：趋势与明细返回类型化容器（KwaimoneyNewPromotionTrendData、KwaimoneyNewPromotionEffectDetailPageResult）。
    • 卖家活动推广效果：商品与汇总视图（DistributeCpsInvestItemView、DistributeCpsInvestBoardSummaryView）。
    • 品牌主题与推荐话题：品牌/商品/店铺与话题信息/商品/卖家列表类型化容器。

改进

  • 金额计算安全性：为资金领域返回的字符串金额字段提供 Decimal 助手（如 settlement_amount_decimal）。
  • 示例与文档：
  • 新增资金结算明细与 Decimal 聚合示例。
  • 新增分销趋势/明细、卖家活动效果、品牌主题与推荐话题的类型化用法示例。
  • 测试覆盖：补充响应类型化与 Decimal 助手的单元测试用例。
  • 文档交叉链接：为分销服务（CPS / Investment / Seller）类文档补充限流、授权、日志接入与错误处理参考链接，提升可发现性与一致性。

兼容性

  • 无破坏性变更；仅类型与文档增强，严格遵循 Java 参考与已公开 API。

[1.0.0] - 2024-01-XX

新增

🚀 核心功能

  • 完整的快手小店SDK实现 - 从Java SDK完全移植到Python
  • 异步优先设计 - 基于asyncio和httpx的高性能异步客户端
  • 类型安全 - 完整的类型注解和Pydantic数据验证
  • 现代化项目结构 - 使用PDM进行项目管理

🔐 认证系统

  • OAuth 2.0完整支持 - 授权码模式、客户端凭证模式、刷新令牌
  • 签名验证 - 支持MD5和HMAC-SHA256签名算法
  • 自动token刷新 - 内置token过期检测和自动刷新机制

📦 业务模块

  • 订单服务 (OrderService) - 订单查询、发货、备注管理
  • 商品服务 (ItemService) - 商品CRUD、库存管理、SKU支持
  • 售后服务 (RefundService) - 退款退货处理、协商流程
  • 25个业务域数据模型 - 涵盖电商全业务场景

🛡️ 可靠性保障

  • 智能重试机制 - 网络异常、限流、token过期自动重试
  • 连接池管理 - HTTP连接复用，提升性能
  • 详细错误处理 - 完整的异常体系和错误码映射
  • 请求日志 - 可配置的调试日志支持

📚 开发体验

  • 完整文档 - API参考、使用指南、最佳实践
  • 丰富示例 - 涵盖所有主要功能的代码示例
  • 单元测试 - 核心功能100%测试覆盖
  • 类型提示 - IDE友好的完整类型注解

技术实现

🏗️ 架构设计

  • 分层架构 - 客户端层、服务层、模型层、通信层清晰分离
  • 依赖注入 - 可配置的HTTP客户端、重试策略、认证管理
  • 插件化设计 - 易于扩展的业务服务架构

📊 性能优化

  • 并发支持 - 支持批量API调用和并发处理
  • 内存优化 - 流式数据处理，避免大对象常驻内存
  • 缓存策略 - 连接池、会话复用减少网络开销

🔧 开发工具

  • PDM项目管理 - 现代化的Python项目管理工具
  • 代码质量 - Black格式化、Ruff检查、MyPy类型检查
  • 自动化测试 - pytest + pytest-asyncio测试框架
  • 文档生成 - MkDocs + Material主题

API覆盖

✅ 已实现 (核心功能)

  • 订单管理 - 14个核心API
  • 订单查询 (open.seller.order.pcursor.list)
  • 订单详情 (open.order.get)
  • 订单发货 (open.order.ship)

  • 备注更新 (open.order.update.remark)

  • 商品管理 - 18个核心API

  • 商品列表 (open.item.list)
  • 商品详情 (open.item.get)
  • 商品创建 (open.item.create)
  • 商品更新 (open.item.update)
  • 库存管理 (open.item.update.stock)

  • 商品删除 (open.item.delete)

  • OAuth认证 - 完整OAuth2.0流程

  • 获取授权URL
  • 授权码换token (/oauth2/access_token)
  • 刷新token (/oauth2/refresh_token)
  • 撤销token (/oauth2/revoke)

🚧 计划实现 (后续版本)

  • 售后管理 - 退款退货相关API (v1.1.0)
  • 物流快递 - 发货跟踪相关API (v1.1.0)
  • 营销推广 - 优惠券、活动API (v1.2.0)
  • 资金管理 - 账单、提现API (v1.2.0)
  • 其他21个业务域 - 逐步完善 (v1.x系列)

兼容性

  • Python版本: 3.8+
  • 依赖库版本:
  • httpx >= 0.25.0
  • pydantic >= 2.0.0
  • orjson >= 3.8.0
  • cryptography >= 41.0.0
  • pendulum >= 3.0.0

破坏性变更

  • 这是首个版本，无破坏性变更

已知问题

  • 部分业务域模型尚未完全实现（将在后续版本中完善）
  • 文件上传功能需要进一步测试验证
  • WebSocket消息推送功能暂未实现

致谢

感谢快手开放平台提供的Java SDK作为参考，以及Python开源社区的优秀库支持。

[计划中的版本]

[1.1.0] - 计划 2024-02-XX

新增

  • 售后服务完整实现 - 退款退货、协商处理等API
  • 物流服务 - 快递查询、发货跟踪等功能
  • 消息推送 - WebSocket消息订阅支持
  • 批量操作优化 - 更高效的批量API调用

[1.2.0] - 计划 2024-03-XX

新增

  • 营销推广服务 - 优惠券、活动管理API
  • 资金管理服务 - 账单查询、提现等API
  • 数据统计服务 - 销售数据分析API
  • 高级功能 - 数据导出、报表生成等

[2.0.0] - 计划 2024-06-XX

新增

  • 完整896个API实现 - 覆盖所有快手开放平台API
  • GraphQL支持 - 更灵活的数据查询方式
  • 插件系统 - 第三方扩展支持
  • 性能优化 - 更高的并发能力和更低的内存占用

破坏性变更

  • 部分API接口可能会有调整以适应平台更新
  • 配置结构可能会有优化调整