docs(02-03): complete search and detail endpoints plan

- SUMMARY.md for plan 02-03 (search, detail, tree reconstruction) - STATE.md updated: Phase 02 complete, 75% progress - ROADMAP.md phase 02 marked complete (3/3 plans) - REQUIREMENTS.md SRCH-06 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 16:34:37 +01:00
parent 079dce5daf
commit d73f265d41
3 changed files with 155 additions and 15 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -23,7 +23,7 @@ Requirements for initial release. Each maps to roadmap phases. Tracked as Gitea
 - [x] **SRCH-03**: User can search transactions by duration range (min/max milliseconds) (#9)
 - [x] **SRCH-04**: User can search transactions by correlationId to find all related executions across instances (#10)
 - [x] **SRCH-05**: User can full-text search across message bodies, headers, error messages, and stack traces (#11)
- [ ] **SRCH-06**: User can view transaction detail with nested processor execution tree (#12)
+- [x] **SRCH-06**: User can view transaction detail with nested processor execution tree (#12)

 ### Agent Management

--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,15 +3,15 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: in-progress
-stopped_at: Completed 02-01-PLAN.md
-last_updated: "2026-03-11T15:15:47Z"
-last_activity: 2026-03-11 -- Completed 02-01 (Schema extension, core domain types, ingestion updates)
+stopped_at: Completed 02-03-PLAN.md (Phase 02 complete)
+last_updated: "2026-03-11T15:32:00Z"
+last_activity: 2026-03-11 -- Completed 02-03 (Search endpoints, detail controller, 24 tests)
 progress:
  total_phases: 4
-  completed_phases: 1
+  completed_phases: 2
  total_plans: 3
-  completed_plans: 1
-  percent: 33
+  completed_plans: 3
+  percent: 75
 ---

 # Project State
@@ -25,12 +25,12 @@ See: .planning/PROJECT.md (updated 2026-03-11)

 ## Current Position

-Phase: 2 of 4 (Transaction Search + Diagrams)
-Plan: 2 of 3 in current phase
-Status: Plan 02-02 Complete
-Last activity: 2026-03-11 -- Completed 02-02 (ELK diagram rendering, SVG/JSON content negotiation, 15 tests)
+Phase: 2 of 4 (Transaction Search + Diagrams) -- COMPLETE
+Plan: 3 of 3 in current phase
+Status: Phase 02 Complete
+Last activity: 2026-03-11 -- Completed 02-03 (Search endpoints, detail controller, tree reconstruction, 24 tests)

-Progress: [██████----] 67%
+Progress: [████████--] 75%

 ## Performance Metrics

@@ -55,6 +55,7 @@ Progress: [██████----] 67%
 | Phase 01 P03 | 10min | 2 tasks | 12 files |
 | Phase 02 P01 | 13min | 2 tasks | 15 files |
 | Phase 02 P02 | 14min | 2 tasks | 10 files |
+| Phase 02 P03 | 12min | 2 tasks | 9 files |

 ## Accumulated Context

@@ -84,6 +85,9 @@ Recent decisions affecting current work:
 - [Phase 02]: Manual Accept header parsing -- JSON only when first preference, SVG as default
 - [Phase 02]: xtext xbase lib required at runtime by ELK 0.11.0 LayeredMetaDataProvider
 - [Phase 02]: Compound node children detected from RouteNode.getChildren() (matches agent graph model)
+- [Phase 02]: Search tests use correlationId scoping for shared ClickHouse isolation
+- [Phase 02]: findProcessorSnapshot uses ClickHouse 1-indexed array access
+- [Phase 02]: DetailController injects ClickHouseExecutionRepository directly for snapshot (not via interface)

 ### Pending Todos

@@ -98,6 +102,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-03-11T15:17:22Z
-Stopped at: Completed 02-02-PLAN.md
-Resume file: .planning/phases/02-transaction-search-diagrams/02-02-SUMMARY.md
+Last session: 2026-03-11T15:32:00Z
+Stopped at: Completed 02-03-PLAN.md (Phase 02 complete)
+Resume file: .planning/phases/02-transaction-search-diagrams/02-03-SUMMARY.md
--- a/.planning/phases/02-transaction-search-diagrams/02-03-SUMMARY.md
+++ b/.planning/phases/02-transaction-search-diagrams/02-03-SUMMARY.md
@@ -0,0 +1,136 @@
+---
+phase: 02-transaction-search-diagrams
+plan: 03
+subsystem: api, search, database
+tags: [clickhouse, search, dynamic-sql, rest, tree-reconstruction, pagination]
+
+requires:
+  - phase: 02-transaction-search-diagrams
+    provides: "SearchEngine interface, SearchRequest/SearchResult/ExecutionSummary types, DetailService, RawExecutionRow, schema with search columns"
+provides:
+  - "ClickHouseSearchEngine with dynamic WHERE building and LIKE escape"
+  - "SearchController GET+POST endpoints for transaction search"
+  - "DetailController with nested processor tree reconstruction"
+  - "Processor snapshot endpoint for per-processor exchange data"
+  - "SearchBeanConfig wiring search and detail layer beans"
+affects: []
+
+tech-stack:
+  added: []
+  patterns: [dynamic-sql-where-building, like-escape-injection-prevention, shared-clickhouse-test-isolation]
+
+key-files:
+  created:
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/search/ClickHouseSearchEngine.java
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/SearchController.java
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/DetailController.java
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/SearchBeanConfig.java
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/SearchControllerIT.java
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/DetailControllerIT.java
+    - cameleer3-server-core/src/test/java/com/cameleer3/server/core/detail/TreeReconstructionTest.java
+  modified:
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/storage/ClickHouseExecutionRepository.java
+    - cameleer3-server-core/pom.xml
+
+key-decisions:
+  - "Search tests use correlationId scoping and >= assertions for shared ClickHouse isolation"
+  - "findProcessorSnapshot uses ClickHouse 1-indexed array access for per-processor exchange retrieval"
+  - "DetailController takes ClickHouseExecutionRepository directly for snapshot access (not through interface)"
+
+patterns-established:
+  - "Dynamic WHERE building: ArrayList<String> conditions + ArrayList<Object> params with LIKE escape"
+  - "Test isolation: scope assertions with unique correlationIds when ClickHouse container is shared"
+
+requirements-completed: [SRCH-01, SRCH-02, SRCH-03, SRCH-04, SRCH-05, SRCH-06]
+
+duration: 12min
+completed: 2026-03-11
+---
+
+# Phase 2 Plan 03: Search Endpoints + Detail Endpoints Summary
+
+**ClickHouse search engine with dynamic SQL, GET/POST search endpoints, transaction detail with nested tree reconstruction, and per-processor exchange snapshot endpoint -- 24 tests**
+
+## Performance
+
+- **Duration:** 12 min
+- **Started:** 2026-03-11T15:19:59Z
+- **Completed:** 2026-03-11T15:32:00Z
+- **Tasks:** 2
+- **Files modified:** 9
+
+## Accomplishments
+- ClickHouseSearchEngine with dynamic WHERE clause building supporting 10 filter types (status, time range, duration range, correlationId, global text, body text, header text, error text) with proper LIKE escape
+- SearchController with GET (basic filters via query params) and POST (full JSON body) endpoints at /api/v1/search/executions
+- DetailController with GET /api/v1/executions/{id} returning nested processor tree and GET /api/v1/executions/{id}/processors/{index}/snapshot for exchange data
+- Implemented findRawById and findProcessorSnapshot in ClickHouseExecutionRepository with robust array type handling
+- 13 search integration tests covering all filter types, combinations, pagination, and empty results
+- 6 detail integration tests covering nested tree verification, snapshot retrieval, and 404 handling
+- 5 unit tests for tree reconstruction logic (linear chain, branching, multiple roots, empty, null)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: ClickHouseSearchEngine, SearchController, and search integration tests** - `82a190c` (feat)
+2. **Task 2: DetailController, tree reconstruction, processor snapshot endpoint** - `0615a98` (feat)
+3. **Task 2 fix: Test isolation for shared ClickHouse** - `079dce5` (fix)
+
+## Files Created/Modified
+- `cameleer3-server-app/.../search/ClickHouseSearchEngine.java` - Dynamic SQL search with LIKE escape, implements SearchEngine
+- `cameleer3-server-app/.../controller/SearchController.java` - GET + POST /api/v1/search/executions endpoints
+- `cameleer3-server-app/.../controller/DetailController.java` - GET /api/v1/executions/{id} and processor snapshot endpoints
+- `cameleer3-server-app/.../config/SearchBeanConfig.java` - Wires SearchEngine, SearchService, DetailService beans
+- `cameleer3-server-app/.../storage/ClickHouseExecutionRepository.java` - Added findRawById, findProcessorSnapshot, array extraction helpers
+- `cameleer3-server-app/.../controller/SearchControllerIT.java` - 13 integration tests for search
+- `cameleer3-server-app/.../controller/DetailControllerIT.java` - 6 integration tests for detail/snapshot
+- `cameleer3-server-core/.../detail/TreeReconstructionTest.java` - 5 unit tests for tree reconstruction
+- `cameleer3-server-core/pom.xml` - Added assertj and mockito test dependencies
+
+## Decisions Made
+- Search tests use correlationId scoping and >= assertions to remain stable when other test classes seed data in the shared ClickHouse container
+- findProcessorSnapshot accesses ClickHouse arrays with 1-based indexing (Java 0-based + 1)
+- DetailController injects ClickHouseExecutionRepository directly for snapshot access rather than adding a new interface method to ExecutionRepository (snapshot is ClickHouse-specific array indexing)
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Added assertj and mockito test dependencies to core module**
+- **Found during:** Task 2 (TreeReconstructionTest compilation)
+- **Issue:** Core module only had JUnit Jupiter as test dependency, TreeReconstructionTest needed assertj for assertions and mockito for mock(ExecutionRepository.class)
+- **Fix:** Added assertj-core and mockito-core test-scoped dependencies to cameleer3-server-core/pom.xml
+- **Files modified:** cameleer3-server-core/pom.xml
+- **Committed in:** 0615a98 (Task 2 commit)
+
+**2. [Rule 1 - Bug] Fixed search tests failing with shared ClickHouse data**
+- **Found during:** Task 2 (full test suite verification)
+- **Issue:** SearchControllerIT status and duration count assertions were exact (e.g., "total == 2 FAILED") but other test classes (DetailControllerIT, ExecutionControllerIT) seed additional data in the shared ClickHouse container, causing count mismatches
+- **Fix:** Changed broad count assertions to use >= for status tests, and scoped duration/time tests with unique correlationId filters
+- **Files modified:** SearchControllerIT.java
+- **Committed in:** 079dce5 (fix commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (1 blocking, 1 bug)
+**Impact on plan:** Both auto-fixes necessary for compilation and test stability. No scope creep.
+
+## Issues Encountered
+- Pre-existing IngestionSchemaIT flaky test (nullSnapshots_insertSucceedsWithEmptyDefaults) fails intermittently when run alongside other test classes due to Awaitility timeout on shared data. Not related to this plan's changes. Already documented in 02-01-SUMMARY.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 2 complete: all search, detail, and diagram endpoints implemented
+- All 6 SRCH requirements satisfied
+- Ready for Phase 3 (Agent Management) which has no dependency on Phase 2
+
+## Self-Check: PASSED
+
+All 7 created files verified present. All 3 task commits verified in git log.
+
+---
+*Phase: 02-transaction-search-diagrams*
+*Completed: 2026-03-11*