docs(08-01): complete container list keyboard plan

Tasks completed: 3/3 - Task 1: Add Container List Inline Keyboard - Task 2: Add Container Submenu with Action Buttons - Task 3: Handle List Pagination Callbacks SUMMARY: .planning/phases/08-inline-keyboard-infrastructure/08-01-SUMMARY.md
2026-02-03 16:19:51 -05:00
parent 393d368dec
commit 1a3feecd91
2 changed files with 129 additions and 8 deletions
@@ -0,0 +1,116 @@
+---
+phase: 08-inline-keyboard-infrastructure
+plan: 01
+subsystem: ui
+tags: [telegram, inline-keyboard, n8n, callback-query, pagination]
+
+# Dependency graph
+requires:
+  - phase: 07-socket-security
+    provides: Docker socket proxy for container API access
+provides:
+  - Container list inline keyboard with pagination
+  - Container submenu with state-based action buttons
+  - Callback routing for select, list, action, noop
+  - Message editing for in-place UI updates
+affects: [08-02, 09-batch-operations]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [inline-keyboard-via-http-request, callback-data-colon-format, editMessageText-navigation]
+
+key-files:
+  created: []
+  modified: [n8n-workflow.json]
+
+key-decisions:
+  - "Callback data format: colon-separated (select:name, list:page, action:verb:name) for compact 64-byte compliance"
+  - "6 containers per page for mobile readability"
+  - "Running containers shown first with green circle icon"
+  - "All callback transitions use editMessageText (no new messages)"
+
+patterns-established:
+  - "Answer callback FIRST: Always call answerCallbackQuery before processing to prevent loading indicator"
+  - "Callback format: prefix:value with colon separator for new keyboard interactions"
+  - "State-based keyboard: Build action buttons dynamically based on container state"
+
+# Metrics
+duration: 5min
+completed: 2026-02-03
+---
+
+# Phase 8 Plan 1: Container List and Submenu Summary
+
+**Inline keyboard container list with pagination and state-based submenu via Telegram callback queries**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-02-03T21:14:10Z
+- **Completed:** 2026-02-03T21:18:59Z
+- **Tasks:** 3
+- **Files modified:** 1
+
+## Accomplishments
+
+- Container list inline keyboard with running/stopped grouping and pagination
+- Container submenu with dynamic action buttons based on state (Start vs Stop/Restart)
+- Callback routing infrastructure for select, list, action, and noop callbacks
+- Direct container access via `/status plex` shows submenu immediately
+- All transitions use editMessageText for clean in-place updates
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add Container List Inline Keyboard** - `f8d616e` (feat)
+2. **Task 2: Add Container Submenu with Action Buttons** - `0148282` (feat)
+3. **Task 3: Handle List Pagination Callbacks** - `393d368` (feat)
+
+## Files Created/Modified
+
+- `n8n-workflow.json` - Added 12 new nodes for keyboard infrastructure:
+  - Build Container List Keyboard (code)
+  - Send Container List (HTTP)
+  - Check Single Container (IF)
+  - Build Container Submenu Direct (code)
+  - Send Container Submenu Direct (HTTP)
+  - Answer Select Callback (HTTP)
+  - Prepare Container Fetch (code)
+  - Get Single Container (HTTP)
+  - Build Container Submenu (code)
+  - Send Container Submenu (HTTP)
+  - Answer List/Noop Callback (HTTP)
+  - Build Paginated List (code)
+  - Edit Container List (HTTP)
+
+## Decisions Made
+
+- **Callback data format:** Used colon-separated format (`select:name`, `list:0`, `action:stop:plex`) instead of JSON to stay within 64-byte limit while remaining human-readable
+- **Containers per page:** Set to 6 for optimal mobile display without scrolling
+- **Icon convention:** Green circle for running, white circle for stopped (matches common Docker UI conventions)
+- **Legacy callback support:** Preserved existing JSON callback format for backward compatibility with suggestion/batch flows
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None - all nodes created and wired successfully on first attempt.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Keyboard infrastructure complete
+- Ready for Plan 02: Action execution through keyboard buttons
+- `action:` callbacks routed but not yet handled (empty output in Route Callback)
+- Logs and Update actions in submenu will need special handling (logs modal, update confirmation)
+
+---
+*Phase: 08-inline-keyboard-infrastructure*
+*Completed: 2026-02-03*