Openlark Naming

6.5) 事件/回调类（P2）命名与归属

事件（event）、回调（callback）、webhook 推送这类被动接收能力，命名与归属规则与主动调用的业务 API 不同：

• 独立 P2 crate，不进统一门面：webhook/event 类能力放在独立 crate（openlark-webhook），不注册进 openlark-client 的 ServiceRegistry 统一门面。
  • 现码核实：openlark-webhook 是独立 crate，其入口 WebhookClient 由 crates/openlark-webhook/src/lib.rs:60 re-export（pub use robot::v1::client::WebhookClient;）；在 crates/openlark-client/src/ 下搜索 webhook 无任何注册项。
• 命名：沿用 *Client 作为该 crate 的对外入口（如 WebhookClient），但不要求与 openlark-client::Client 形成 client.xxx 链式段，因为它不属于主动 API 调用链。
• 构造差异：webhook 类常不需要 Config/app_id，构造可能为 WebhookClient::new()（无参）或仅传 webhook URL/secret，与业务 *Client::new(config) 不同；命名上仍叫 *Client，但归属与生命周期独立。
• 判断要点：新增一个“接收推送/回调”的能力时，优先问“它是否被动触发？”——是，则归独立 P2 crate，不要塞进 openlark-client。

7) 已治理案例与现存反例

7.1 已治理：openlark-docs 的 DocsService 重名问题

历史问题：openlark-docs 曾出现多处 DocsService 同名但语义不同（ccm::docs 入口、ccm::docs::v1 版本层、ccm::doc 模块错配），是本技能最初触发的典型案例。

治理结论（已落地，作为同类问题的参考样板）：

• 全 crate 统一以 DocsClient 作为唯一对外入口，prelude 注释明确记载：
  • crates/openlark-docs/src/prelude.rs:16 — // 已移除 Service 的 prelude 导出，统一使用 DocsClient 作为唯一入口
• DocsClient 由分层调用链实现，定义于 crates/openlark-docs/src/common/chain.rs，经 crates/openlark-docs/src/lib.rs:125 re-export（pub use common::chain::DocsClient;）
• *Service 类型（CcmService/BaseService/BitableService 等）保留为内部执行层，不再进 prelude，仅在需要时通过完整路径访问
• 启示：当某 crate 的 *Service 泛名泛滥、re-export 冲突难收敛时，优先收敛为单一 *Client 门面 + 内部 Service 分层，而非逐个改名 *Service

现码核实：上述 prelude.rs:16 与 lib.rs:125 的 file:line 均有效；旧的 ccm/docs/mod.rs:8、ccm/docs/v1/mod.rs:25、ccm/doc/mod.rs:65 三处引用已全部失效，勿再引用。

7.2 现存反例：同一类型同时挂两个名字（Resource + Service）

现码中仍存在“同一结构体同时暴露 *Resource 与 *Service 两个名字”的兼容残留，是典型的待收敛反例：

• crates/openlark-cardkit/src/cardkit/cardkit/v1/card/element/mod.rs:47

  /// 兼容历史命名：card.element 服务
  pub type CardElementService = CardElementResource;

  • 真实结构体是 CardElementResource（mod.rs:42，资源节点语义），却又 pub type 出一个 CardElementService 别名。
  • 问题：违反 §0/§4 的职责-命名对应（资源节点不应叫 *Service），造成“读者不知道哪里能 execute”的同名泛滥；别名仅为兼容历史调用而存在。
  • 收敛方向：评估调用方迁移后移除 CardElementService 别名，统一只保留 CardElementResource。

排查方法：rg -n "pub type .*Service = .*Resource" crates/ 可一次性找出所有此类“同类型两名”残留。

8) 改名 review 清单（提交前逐条过一遍）

• 目录/模块路径是否能从类型名推断（至少到 bizTag/project/version/resource）
• prelude/re-export 是否引入同名冲突（尤其是 *Service 这种泛名；已治理的 DocsService 勿再复现）
• *Client / *Service / *Resource 的职责是否清晰，调用方式是否一致
• 版本层是否统一采用 *V{N}Service（或 *V{N}Client），避免重复 *Service；facade 侧 *V{N}Client 与执行侧 *V{N}Service 版本号是否成对一致
• 同一类型是否同时挂了 *Resource 与 *Service 两个名字（rg "pub type .*Service = .*Resource" 应无新增）
• 事件/回调类是否误被塞进 openlark-client 门面（webhook/event 应在独立 P2 crate）
• 改名后跑 just lint：等价于 cargo clippy --workspace --all-targets --all-features -- -Dwarnings -A missing_docs（justfile:14），务必带 --all-targets 以覆盖 examples/tests/benches，确保改名未漏掉非 lib 目标
• 移动/新建 example 时补 [[example]] required-features：根 Cargo.toml 每个 [[example]] 需声明所依赖的 feature（如 required-features = ["communication", "websocket"]，见 Cargo.toml:248+）；example 引用的类型若位于 feature-gated 模块，缺声明会导致 --all-features 之外编译失败
• 测试文件保持 //! 在 #![cfg(feature)] 之上：契约测试/集成测试文件开头顺序固定为「文件级文档注释 //! 在前、#![cfg(feature = "...")] 属性在后」，再 use（正例：crates/openlark-client/tests/docs_feature_contract.rs:1-6）；改名时勿颠倒顺序，否则 inner attribute 报错