Merged PR 2430: Add API grouping facade rollout checkpoint

Add API grouping facade rollout checkpoint Related work items: #23754
2026-06-25 09:05:59 +00:00
parent a266fa5428
commit f9f78548b0
3 changed files with 229 additions and 0 deletions
@@ -259,6 +259,65 @@ It means:
    - excluded adjacent search journeys remain unchanged
    - no route migration, deletion, or contract change has occurred

+#### API Grouping Façade Rollout Checkpoint
+
+- The first successful façade slices now establish a proven additive rollout pattern for:
+    - subscriptions / watched cases
+    - documents / published document metadata
+    - public search results
+- Proven runtime shape:
+
+```text
+UI journey
+→ existing service layer
+→ grouped façade route
+→ legacy canonical handler
+→ unchanged integration behaviour
+```
+
+- Proven implementation pattern:
+    - audit the active journey path first
+    - identify the existing owning/common service layer already used by that path
+    - add grouped façade routes only for the proven in-scope active calls
+    - implement each grouped route as a tiny wrapper that delegates directly to the existing legacy handler
+    - keep the legacy handler as the canonical implementation
+    - adopt the grouped route in the existing service layer only where the active journey path is proven and low-risk
+    - leave adjacent, inactive, support, or orchestration-heavy routes out of scope unless separately justified
+    - prove the slice with lightweight characterization tests covering delegation, service adoption, retained legacy handlers, and unchanged scope boundaries
+- Important interpretation:
+    - this checkpoint proves a safe rollout pattern for additive façade grouping
+    - it does not approve route removal
+    - it does not approve handler replacement
+    - it does not approve broad migration
+    - it does not approve grouping of more complex API families without another bounded audit
+
+#### Vertical façade slice completion criteria
+
+- A vertical façade slice should be treated as complete only when:
+    - active journey paths are audited
+    - grouped façade routes exist for the in-scope active routes only
+    - the service layer adopts the grouped routes where safe and proven
+    - legacy handlers remain present and canonical behind the façade
+    - inactive or support routes are explicitly left out of scope where they are not part of the active adopted path
+    - characterization tests prove façade delegation and service-layer adoption
+    - characterization tests do not imply that legacy handlers can be removed
+    - documentation records the exact scope, completion meaning, exclusions, and non-goals
+- A slice is not complete merely because grouped files exist.
+- Completion requires both bounded adoption evidence and explicit documentation of what remains outside scope.
+
+#### Do not group yet criteria
+
+- Grouping should be delayed when any of the following apply:
+    - no clear service layer exists
+    - active ownership is unclear
+    - the route is orchestration-heavy
+    - the route crosses storage + queue + CRM boundaries
+    - the route is auth/session critical
+    - the route is not proven active in a bounded current journey
+    - grouping would require frontend refactor rather than additive service-level adoption
+    - grouping would require contract change
+- In these cases, documentation may still classify the area conceptually, but additive façade rollout should wait for a safer bounded slice.
+
 ---

 ### Stage 3 — Documentation Maturity