Problem Statement
OpenLark Docs 的端点目录已经集中拥有动态 path,但稳定的请求语义仍泄漏到大量叶子 module:每个叶子独立选择 HTTP method、token 要求、query/body 形态和响应提取。目录测试只证明 path,不证明 method/path 组合;因此目录测试可以全绿,而叶子仍可能以错误 method 调用正确 path。使用者看到的错误通常是运行时 404/405 或响应不匹配,维护者则需要在多个位置理解一个端点。
Solution
把 Docs 端点目录深化为拥有稳定请求语义的 domain module。端点身份、HTTP method、路径参数和稳定认证要求在同一 implementation 中保持 locality;叶子 builder 继续作为用户与测试的 interface,只提供领域数据和可变 request option。先以一个端点密集资源族作为 tracer bullet 验证,再按同一规则扩展。
User Stories
- As an OpenLark Docs user, I want each leaf builder to call the correct method and path, so that endpoint drift does not surface at runtime.
- As an OpenLark Docs user, I want authentication requirements attached to endpoint identity, so that token selection cannot diverge between sibling leaves.
- As an OpenLark Bitable user, I want dynamic identifiers encoded by one domain module, so that path construction remains type-safe.
- As an OpenLark SDK maintainer, I want method and path to change together, so that official endpoint updates require one edit.
- As an OpenLark SDK maintainer, I want request semantics to stay inside the Docs domain, so that core Transport remains domain-agnostic.
- As an OpenLark leaf-builder author, I want to supply domain data without re-declaring stable transport facts, so that a new leaf contains less repeated knowledge.
- As an OpenLark test author, I want leaf e2e tests to assert method and path together, so that the public builder interface is the test surface.
- As an OpenLark test author, I want endpoint-catalog tests to cover semantic completeness, so that missing method or auth metadata fails early.
- As an OpenLark reviewer, I want a small tracer-bullet rollout, so that the pattern is proven before broad migration.
- As an OpenLark downstream user, I want existing builder names and fluent calls preserved, so that internal deepening is non-breaking.
- As an OpenLark operator, I want request IDs and Transport error context unchanged, so that endpoint refactoring does not reduce observability.
- As an OpenLark maintainer, I want a repeatable migration rule for other Docs resources, so that follow-up work is mechanical and reviewable.
Implementation Decisions
- The Docs domain endpoint catalog owns endpoint identity, HTTP method, dynamic path parameters, and stable access-token requirements.
- Leaf request builders remain the external caller and test interface; their public construction and fluent methods do not change.
- Leaf implementation supplies domain query/body data and per-call request options, then delegates stable request semantics to the domain endpoint module.
- Core Transport remains generic and receives a fully described request; Docs-specific knowledge does not move into core.
- The first implementation is a tracer bullet in one endpoint-dense Docs resource family that includes at least read, create, update, and delete methods.
- Expansion beyond the tracer bullet requires the same observable behavior and no new seam per resource.
- Catalog semantics are compile-time data, not a runtime registry or stringly-typed map.
- Existing path bytes, serialization shapes, response models, and leaf builder interfaces remain unchanged unless the tracer bullet exposes a documented existing defect.
- This implements the leaf URL decoupling explicitly left for a separate issue by ADR-0001; it does not reopen navigation-shell design.
Testing Decisions
- The highest test seam is each migrated leaf builder executed against wiremock.
- E2e-style tests assert HTTP method, exact path, dynamic path encoding, query/body serialization, auth header behavior, request options, and typed response extraction.
- Endpoint-catalog tests assert semantic completeness and method/path/auth agreement but do not replace leaf execution tests.
- Before migration, tracer-bullet tests lock current correct behavior; any discovered mismatch is recorded as a bug rather than silently preserved.
- Tests assert outgoing requests and returned results only; they do not inspect catalog storage or internal helpers.
- Prior art is the repository's wiremock leaf tests and endpoint enum URL assertions, combined at the higher leaf-builder seam.
Out of Scope
- A workspace-wide endpoint migration in one change.
- Changes to navigation shells or DocsClient helpers covered by ADR-0001.
- Core Transport middleware or response-model redesign.
- New public leaf builder methods.
- Automatic synchronization with Feishu documentation.
Further Notes
- Earlier wrong-method/wrong-path defects show that path-only tests are insufficient.
- The deletion test already proves the catalog earns locality for paths; this work increases depth by absorbing stable request semantics that currently leak across the seam.
Problem Statement
OpenLark Docs 的端点目录已经集中拥有动态 path,但稳定的请求语义仍泄漏到大量叶子 module:每个叶子独立选择 HTTP method、token 要求、query/body 形态和响应提取。目录测试只证明 path,不证明 method/path 组合;因此目录测试可以全绿,而叶子仍可能以错误 method 调用正确 path。使用者看到的错误通常是运行时 404/405 或响应不匹配,维护者则需要在多个位置理解一个端点。
Solution
把 Docs 端点目录深化为拥有稳定请求语义的 domain module。端点身份、HTTP method、路径参数和稳定认证要求在同一 implementation 中保持 locality;叶子 builder 继续作为用户与测试的 interface,只提供领域数据和可变 request option。先以一个端点密集资源族作为 tracer bullet 验证,再按同一规则扩展。
User Stories
Implementation Decisions
Testing Decisions
Out of Scope
Further Notes