Breaking Changes

• Removed all v0.15.0 deprecated crate re-exports (open_lark::openlark_client,
  open_lark::openlark_core, open_lark::openlark_auth, etc.)
• Removed all v0.15.0 deprecated *Client type aliases from root crate
  (AuthClient, DocsClient, HrClient, etc.). Use client.auth, client.docs,
  client.hr field access instead.
• Cleaned root prelude — no longer exports deprecated *Client aliases
• Cleaned root and openlark-client preludes — no longer export deprecated
  openlark_client::Config; use CoreConfig or Client::builder() instead.
• Client.config() now returns &openlark_core::config::Config (was &openlark_client::Config).
  Access fields via methods: client.config().app_id(), client.config().base_url(), etc.
• Migration: Replace use open_lark::AuthClient → access via client.auth field
  or use open_lark::auth module namespace directly. Replace client.config().app_id
  → client.config().app_id() (method call, not field access)

Deprecated

• openlark_client::Config — planned for removal after the migration window.
  Use Client::builder() or openlark_core::config::Config directly.

Added

• SecurityClient struct in openlark-security — proper wrapper with Deref
  to SecurityServices (replaces Arc<SecurityServices> alias)
• XxxClient type aliases in all business crates for consistent naming:
  WorkflowClient, PlatformClient, ApplicationClient, HelpdeskClient,
  MailClient, AnalyticsClient, UserClient
• [package.metadata.docs.rs] configuration for complete documentation generation
• docs/CLIENT_NAMING_CONVENTION.md — naming convention documentation

Changed

• openlark-core no longer enables testing feature by default. Crates using
  openlark_core::testing in tests must add openlark-core = { features = ["testing"] }
  to their [dev-dependencies].
• All business crate XxxClient types now exported from source crates instead of
  defined as type aliases in openlark-client

Removed

• #![allow(async_fn_in_trait)] from openlark-client (MSRV 1.88 no longer needs it)

Compatibility

Typed APIs

Helpers & Convenience Methods

Breaking Changes

Deprecations

Migration Notes

Added

Changed

Fixed

Crate 级质量状态

质量状态维度:

• typed coverage:来自 reports/api_validation/summary.json 的 typed API 覆盖率
• contract tests:crate 内存在 request/response contract test
• snapshot tests:crate 内存在 helper/output snapshot test

Added

• feat(api): 同步 70 个新增飞书 API catalog 条目,并补齐 application v7、docs drive/minutes、HR corehr v2、IM reaction、mail v1、meeting v1、spark v1 等 typed SDK 模块。
• coverage(api): 将 application、communication、docs、hr、mail、meeting、platform 等相关 crate 的 strict API 覆盖率恢复到 0 missing APIs。

Changed

• build(deps): 放宽 uuid 与 serde_with 的精确版本锁定,降低下游依赖解析冲突风险。

Crate 级质量状态

质量状态维度:

• typed coverage:来自 reports/api_validation/summary.json 的 typed API 覆盖率
• contract tests:crate 内存在 request/response contract test
• snapshot tests:crate 内存在 helper/output snapshot test

🔄 变更

• style(fmt): 统一代码格式化,修复多个文件的格式问题
• docs(docPath): 为 260+ 个 API 文件补充 docPath 官方文档链接
• refactor(api): 删除 explorer/permission v2 的函数式 API,统一使用 Builder 模式
• refactor(api): 统一 platform/helpdesk 40 个文件的 execute() 委托模式,消除代码重复
• refactor(validate): 统一 44 个文件的必填字段校验,使用 validate_required! 宏替换手工校验
• refactor(types): 替换 calendar v4 的 serde_json::Value 为强类型结构体
• fix(exports): 补充 5 个 mod.rs 文件的模型显式导出
• fix(url): 修复 exchange_binding/get.rs 的 API 端点路径拼写错误
• ci: 修复 clippy 警告和文档注释缺失
• build(deps): 升级安全相关依赖(tokio-tungstenite、url、reqwest)
• build(rust): 对齐 Rust 2024 / MSRV 1.88

🐛 修复

• fix(ci): 修复 CI 持续失败问题(clippy 警告、格式问题)
• fix(security): 添加 max_response_size / ResponseTooLarge HTTP 与 WebSocket 响应大小限制
• fix(security): Token/PII 日志脱敏
• fix(security): path 参数 percent-encoding 安全修复
• fix(code): 生产代码与测试代码 unwrap() 清理
• fix(auth): AuthTokenProvider 多租户缓存 key 修复

Crate 级质量状态

质量状态维度:

• typed coverage:来自 reports/api_validation/summary.json 的 typed API 覆盖率
• contract tests:crate 内存在 request/response contract test
• snapshot tests:crate 内存在 helper/output snapshot test

🔄 变更

• release(root): 将工作区版本与根 crate 文案切换到 0.15.0
• docs(release): 新增 0.15 迁移指南、public API 稳定性策略与正式版发布清障清单
• ci(examples): 为根 README 对齐示例与主推 examples 增加编译校验入口
• build(metadata): 修正 crates.io 元数据中的仓库与文档链接

🐛 修复

• fix(release): 修复 GitHub Release 对 RC tag 一律标为正式版的问题
• fix(docs): 修复多个 crate README 中错误的 crate 名、仓库链接和过期版本示例

🔄 变更

• refactor(root): 将 openlark 收敛为唯一官方入口 crate,直接导出 Client、ClientBuilder、Config、RequestOption、CoreError 等高频类型
• refactor(features): 重构根 crate feature 模型,移除面向用户的 client/protocol 心智,统一为业务 feature、技术 feature 与组合 feature
• refactor(client): 将 openlark-client 明确为高级入口,不再作为普通用户的默认接入方式
• docs(examples): 统一 README 和主 examples 到 openlark 根入口,修复 workflow 示例门槛与实际依赖不一致问题
• build(lints): 将 workspace.lints 真正落到各成员 crate,统一工作区 lint 配置

✨ 新增功能

• feat(webhook): 集成 openlark-webhook 模块到工作空间(8 个 API)
  • 自定义机器人、Webhook 事件处理
• feat(hr): 实现 462 个 API (Wave 1-5),涵盖招聘、CoreHR、考勤、薪酬等模块,总计 562 个 API
• feat(workflow): 完成 workflow 模块 100% API 覆盖(117 个 API)
  • TASK v1 剩余 28 个 API、TASK v2 剩余 24 个 API
  • APPROVAL v4 16 个 API
  • BOARD 模块命名规范修复
• feat(platform): 完成 openlark-platform Transport API 迁移(102 个 API)
• feat(ai): 完成 openlark-ai 模块 27 个 API 实现
• feat: 实现缺失的 bizTag API(100% 覆盖)
• feat(examples): 新增长连接 WebSocket Echo 示例并补充测试
• feat(core): 新增测试基础设施模块(testing)
  • test_runtime() - 安全的测试运行时
  • assert_res_ok!, assert_err_contains! 等断言宏
• feat(client): 新增 LazyService 延迟初始化工具
• docs: 添加 AGENTS.md 项目知识库

🔄 变更

• refactor(docs): 简化 API 入口设计,删除 Service 层,统一 Request 模式
• refactor(docs): 将 glob 重导出转换为显式导出(258 → 7 处)
• perf(docs): 优化 Config 传递,使用 Arc<Config> 替代 Config
• refactor(meeting): 统一 Request 模式,删除冗余 RequestBuilder
• refactor(hr): 统一架构并添加 feature gating 支持
• refactor(core): 为 testing 模块添加 feature gate
• refactor(core): 清理未使用的空 features,将测试依赖移动到 dev-dependencies
• refactor: 实现显式导出系统,消除 251+ 个通配符导出
• style(security): 修复命名规范异常,替换硬编码 URL,统一代码风格

🐛 修复

• fix(core): 统一 validate_required 语义,支持字符串 trim
• fix(docs): 修复 sheets_v2 数据读取 API 路径
• fix(docs): 修复 Arc 类型不匹配错误
• fix(docs): 修复 explorer v2 模块编译错误和导出问题
• fix(hr): 添加 CoreHR 缺失的 API 端点定义并修复语法错误
• fix: 修复 no-default-features 编译错误
• fix: 修复多个 crate 的代码风格和导出
• fix(examples): 修复 examples 编译错误
• fix(ci): 修复 Coverage 工作流覆盖率收集问题(多次迭代修复)

🧪 测试

• 大幅提升测试覆盖率至 ~47%
• 为所有主要模块添加测试:docs、workflow、platform、cardkit、hr、meeting、auth、core
• 为 workflow v1/v2 模块添加完整测试套件
• 迁移 44 个测试文件到新框架,消除 144 处 Runtime::new().unwrap()

Added - 🎉 全面事件系统实现与 WebSocket IM 事件增强

📡 完整飞书/Lark事件系统实现

• 🏗️ 全面事件类型支持 - 系统化实现飞书开放平台所有事件类型
  • IM (即时消息) - 15个核心事件:消息接收、已读、撤回、反应、群聊生命周期等
  • Contact (通讯录) - 13个事件:用户、部门、范围、员工类型变更等
  • Drive (云文档) - 10个事件:权限变更、文档操作、订阅管理等
  • Calendar (日历) - 8个事件:日程变更、日历ACL、会议室操作等
  • Meeting Room (会议室) - 2个事件:状态变更
  • VC (视频会议) - 7个事件:会议状态、参会人变更、录制通知等
  • Approval (审批) - 2个事件:审批实例和任务状态变更
  • Application (应用) - 10个事件:应用状态、可见性、管理员变更等
  • 共计 67+ 事件类型, 完整覆盖飞书开放平台事件体系

🎯 WebSocket IM 事件增强

• ✅ 消息撤回事件 - 支持 p2_im_message_recalled_v1 事件监听和处理
• ✅ 群聊生命周期事件 - 支持群聊创建、更新、解散事件监听
  • p2_im_chat_created_v1 - 群聊创建事件
  • p2_im_chat_updated_v1 - 群聊更新事件
  • p2_im_chat_disbanded_v1 - 群聊解散事件
• ✅ 群成员管理事件 - 支持群成员变更事件监听
  • p2_im_chat_member_user_added_v1 - 群成员添加事件
  • p2_im_chat_member_user_deleted_v1 - 群成员移除事件
• 🎯 增强用户体验 - 中文日志输出、性能计时、结构化错误处理
• 📊 详细事件信息 - 显示事件ID、操作者、时间戳等完整上下文信息

📚 完整示例演示

• event_handler.rs - 300+ 行完整功能演示
  • 展示所有主要模块的事件注册和处理
  • 实时事件监听和响应逻辑
  • 企业级事件处理最佳实践

🏗️ 技术特性

• 类型安全 - 完整的事件数据结构定义和 Serde 支持
• 模块化设计 - 清晰的事件模块组织,易于维护和扩展
• 向后兼容 - 保持现有 API 稳定,新事件平滑集成
• 零编译警告 - 所有代码通过 clippy 检查和格式化

Added - ✨ Task v2 任务清单增强

• 任务清单支持: 支持在 CreateTaskRequest 中指定 tasklist_guid
• 帮助方法: 新增 TaskService::add_tasklist 方法,便于将既有任务加入指定清单
• 文档完善: 更新任务模块文档,补充任务加入清单的示例和能力说明

Fixed - 🐛 WebSocket 消息已读事件修复

修复消息已读事件数据结构不匹配问题

• ✅ message_read_v1 事件结构修正 - 修复关键的 WebSocket 事件反序列化错误
  • 修正 P2ImMessageMessageReadV1Data 数据结构定义与飞书 API 实际格式不符
  • 将 sender 和 message 字段替换为正确的 reader 和 message_id_list 字段
  • 新增 EventReader 结构体,包含 read_time, reader_id, tenant_key 字段
  • 彻底解决了 "missing field 'sender'" 反序列化错误

WebSocket Echo Server 示例完善

• 🤖 完整 Echo Server 实现 - 将 websocket_client.rs 转换为功能完整的 Echo 服务器
  • 实现消息接收和自动回显功能,回复格式为 "Echo: [原消息内容]"
  • 支持消息已读事件监听和显示
  • 增强错误处理和详细的调试日志输出
  • 自动设置 debug 日志级别以便问题诊断
• 📊 改进事件信息显示 - 优化控制台输出格式
  • 消息接收事件:显示消息ID、发送者、内容等详细信息
  • 消息已读事件:显示阅读者、阅读时间、已读消息列表等信息
  • 添加使用提示和功能说明

Added - 📚 全面文档完善与质量提升

Fixed - 🔧 CI/CD 流水线优化与构建修复

🚀 CI 构建流程完全修复

• ✅ 无默认特性构建支持 - 修复 --no-default-features 构建错误
  • 条件编译 Arc 导入,避免未使用警告
  • 40+ 示例文件添加 required-features 配置
  • 确保示例只在相应特性启用时编译
• 🎯 Clippy 警告清零 - 解决所有 clippy 警告和编译错误
  • 修复特性门控制的服务访问错误
  • 统一条件编译模式和导入规范
  • 代码格式标准化,提升可读性
• ⚡ CI 性能优化 - GitHub Actions 流水线稳定性提升
  • 双重构建验证:--no-default-features 和 --all-features
  • 示例编译错误完全消除
  • 测试覆盖率和文档生成流程优化

✨ 服务模块文档完整化 - 企业级文档标准

• 📝 43个服务模块完整文档 - 为所有主要服务模块添加详细中文文档
  • 核心通讯:im、mail、group等服务文档
  • 云文档协作:cloud_docs、drive、sheets、bitable等完整文档
  • 人力资源:hire、contact、corehr、ehr、payroll等HR服务文档
  • 办公自动化:approval、task、okr、calendar等办公服务文档
  • 企业管理:admin、tenant、directory、application等管理服务文档
  • 智能化服务:ai、search、lingo等AI服务文档
  • 安全合规:verification、security_and_compliance、acs等安全服务文档
• 🎯 统一文档标准 - 建立标准化的文档格式和最佳实践
  • 模块级文档说明
  • 核心功能概览
  • 详细使用示例
  • API版本支持说明
  • 企业应用场景指导

🔧 文档测试质量保证

• ✅ 72个文档测试100%通过 - 修复所有doctest编译错误
  • Event模块:修复方法调用链和字段访问错误
  • Service模块:添加异步上下文和变量定义
  • Authentication模块:移除错误的字段访问
  • Card模块:修复类型错误和方法调用问题
• 🎨 代码示例优化 - 确保所有文档示例可编译运行
• 📊 零警告文档生成 - 消除所有rustdoc警告,提供清洁的文档体验

📝 核心API文档完善

• 🃏 Card模块完整文档 - 飞书卡片组件详细使用指南
• ⚡ Event模块文档 - 事件处理器使用说明和最佳实践
• 🛡️ Error模块文档 - 错误类型和处理机制详细说明
• 🏗️ 主要Enum类型文档 - 为核心枚举类型添加完整注释

🎯 开发者体验提升

• 🇨🇳 中文优先文档 - 面向中国开发者的本土化文档
• 📖 丰富使用示例 - 每个服务都包含详细的代码示例
• 💡 最佳实践指导 - 企业级应用开发建议和注意事项
• 🔍 层次化文档结构 - 从概览到详细API的清晰组织

Added - 🏗️ 现代化Builder模式与统一错误处理系统

✨ Builder模式完整实现 - 现代化API调用体验

• 🏗️ ExecutableBuilder特征系统 - 统一Builder接口,支持类型安全的链式调用
  • Contact v3用户服务完整Builder模式支持
  • IM v1消息、文件、图片服务Builder模式实现
  • Drive v1文件服务Builder模式支持
• ⚡ 现代化异步执行 - .execute()方法提供一致的异步调用体验
• 🔗 流畅链式调用 - 支持参数链式设置,提高代码可读性
• ✅ 完全向后兼容 - 新旧API并存,渐进式迁移

🛡️ 统一错误处理系统

• 📦 StandardResponse特征 - 统一的.into_result()错误处理机制
• 🎯 智能错误信息 - 详细错误分析和操作建议
• 🔄 一致性保证 - 所有服务使用统一的错误处理模式

🔧 API设计优化

• 📊 API一致性检查工具 - 自动化API设计质量监控
• 📚 完整设计规范 - API_DESIGN_GUIDELINES.md提供标准化开发指南
• 🧪 综合示例代码 - 展示传统vs现代API调用方式

📝 文档与示例完善

• 📋 综合示例 - unified_builder_pattern.rs展示完整功能
• 🎯 专项示例 - IM、Contact、Drive服务的Builder模式示例
• 📚 最佳实践 - 详细的使用指南和代码规范

Added - ✅ Contact v3 通讯录API 100%完成

🎯 Contact v3 API 最终补全 - 企业级通讯录管理达到完全覆盖

• ✨ 功能角色管理完整实现 - 补全最后3个缺失的API方法,现已实现98/98个方法
  • FunctionalRole.get() - 获取单个角色详细信息,支持角色ID查询
  • FunctionalRole.list() - 获取角色列表,支持分页查询和筛选
  • FunctionalRoleMember.create() - 添加角色成员,支持用户和部门类型
• 📝 完整数据结构支持 - 新增所有必需的请求/响应结构体
  • GetFunctionalRoleResponse, ListFunctionalRolesRequest/Response
  • CreateRoleMemberRequest/Response, RoleMemberInfo等完整数据模型
• 🎯 100%接口覆盖达成 - Contact v3现已完全实现文档中的所有接口
  • 14个模块全部完成:用户、部门、用户组、权限、自定义字段、人员类型、单位、职级、序列、职务、工作城市、用户组成员、功能角色、功能角色成员
  • 98个API方法全部实现,从96.9%提升到100%完成度
• 📚 综合示例代码 - 新增专门的角色管理示例演示
  • contact_v3_role_management.rs - 展示最新实现的角色管理功能
  • 更新 contact_v3_comprehensive.rs - 集成新功能到综合演示中

🔧 代码质量提升

• 🧹 修复编译警告 - 清理未使用的导入,优化代码结构
• ✅ 编译验证 - 所有新增代码通过编译检查和格式化
• 📖 完善文档 - 更新CHANGELOG记录完整实现历程