docs(10.1-06): complete matching extraction plan
This commit is contained in:
Lucas Berger
@@ -0,0 +1,140 @@
|
||||
---
|
||||
phase: 10.1-aggressive-workflow-modularization
|
||||
plan: 06
|
||||
subsystem: workflow
|
||||
tags: [n8n, sub-workflow, matching, disambiguation, fuzzy-matching]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 10.1-01
|
||||
provides: Domain analysis identifying matching/disambiguation as 4th extractable domain
|
||||
- phase: 10.1-04
|
||||
provides: Main workflow at 168 nodes baseline
|
||||
provides:
|
||||
- n8n-matching.json sub-workflow (23 nodes)
|
||||
- Matching/disambiguation domain extracted from main workflow
|
||||
- All 4 viable domains now extracted
|
||||
affects: [10.1-07, deployment]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Action-based sub-workflow return pattern for matching results"
|
||||
- "Prepare Execution node to transform sub-workflow output to downstream format"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- n8n-matching.json
|
||||
- n8n-workflow.json.backup-matching
|
||||
modified:
|
||||
- n8n-workflow.json
|
||||
- DEPLOY-SUBWORKFLOWS.md
|
||||
|
||||
key-decisions:
|
||||
- "Matching sub-workflow returns action field but not the user's requested action (stop/start/etc) — downstream nodes read action from Parse Action Command or Detect Batch Command directly"
|
||||
- "Text-mode status needs keyboard stripped — added Strip Status Keyboard node"
|
||||
- "Batch text commands need data transformation — added Prepare Batch Execution node to map matchedContainers to allMatched"
|
||||
|
||||
patterns-established:
|
||||
- "When sub-workflow replaces inline logic, downstream nodes may need to reference original data sources (e.g., Parse Action Command) instead of sub-workflow output for fields not passed through"
|
||||
- "Text vs callback mode routing via messageId check (Has Status Message ID pattern)"
|
||||
|
||||
# Metrics
|
||||
duration: 16min
|
||||
completed: 2026-02-08
|
||||
---
|
||||
|
||||
# Phase 10.1 Plan 06: Matching/Disambiguation Sub-workflow Summary
|
||||
|
||||
**Extracted matching/disambiguation domain into n8n-matching.json sub-workflow (23 nodes), deployed via API, fixed 3 data flow issues found during runtime verification**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~16 min
|
||||
- **Started:** 2026-02-08T13:30:00Z
|
||||
- **Completed:** 2026-02-08T14:05:26Z
|
||||
- **Tasks:** 3 (2 auto + 1 checkpoint)
|
||||
- **Files modified:** 3
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Created n8n-matching.json sub-workflow with 23 nodes (12 logic + 1 trigger + 1 router + 9 format-return)
|
||||
- Three matching paths: action match, update match, batch match
|
||||
- Deployed via n8n API (ID: `kL4BoI8ITSP9Oxek`)
|
||||
- All 6 Telegram response nodes preserved in main workflow per locked decision
|
||||
- Fixed pre-existing text-mode status routing bug (editMessageText with messageId 0)
|
||||
- Main workflow: 168 nodes (net 0 change due to fix nodes added during verification)
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Create n8n-matching.json** - `e86941c` (feat)
|
||||
2. **Task 2: Update main workflow** - `de64d1b` (feat)
|
||||
3. **Task 3: Deploy and verify** - `fc955e6` (fix: deploy IDs), `22638fd` (fix: action passthrough + status routing), `11365b8` (fix: strip status keyboard), `cccf455` (fix: batch data flow)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `n8n-matching.json` - New sub-workflow: fuzzy container matching, disambiguation, suggestion building (23 nodes)
|
||||
- `n8n-workflow.json` - Main workflow with matching extracted and integration fixes (168 nodes)
|
||||
- `n8n-workflow.json.backup-matching` - Pre-extraction backup
|
||||
|
||||
## Decisions Made
|
||||
|
||||
1. **Action passthrough pattern:** The matching sub-workflow doesn't carry the user's requested action (stop/start/restart) through its return data. Downstream nodes reference the original parse node (`Parse Action Command` or `Detect Batch Command`) directly for the action type. This avoids expanding the sub-workflow's input/output contract.
|
||||
|
||||
2. **Text-mode status routing:** Added `Has Status Message ID` If node to route `status_direct` results — messageId > 0 goes to `Edit Container List` (callback), messageId == 0 goes to text send via `Strip Status Keyboard` → `Send Container Submenu Direct`.
|
||||
|
||||
3. **Batch data transformation:** Added `Prepare Batch Execution` Code node to map `matchedContainers` → `allMatched` and inject the real batch action from `Detect Batch Command`, since downstream nodes expect different field names than the sub-workflow returns.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Action type not passed through matching sub-workflow**
|
||||
- **Found during:** Task 3 (runtime verification)
|
||||
- **Issue:** `Prepare Text Action Input` read `data.actionType` which resolved to `"action"` (a routing label) instead of `"stop"`
|
||||
- **Fix:** Changed to read `$('Parse Action Command').item.json.action` directly
|
||||
- **Files modified:** n8n-workflow.json
|
||||
- **Verification:** "stop booklore" correctly executes stop
|
||||
- **Committed in:** `22638fd`
|
||||
|
||||
**2. [Rule 1 - Bug] Text-mode status sent to editMessageText with messageId 0**
|
||||
- **Found during:** Task 3 (runtime verification)
|
||||
- **Issue:** Pre-existing bug — "status book" routed to `Edit Container List` (editMessageText) which fails with messageId 0. Also showed inline keyboard buttons for text commands.
|
||||
- **Fix:** Added `Has Status Message ID` If node and `Strip Status Keyboard` Code node for text-mode routing
|
||||
- **Files modified:** n8n-workflow.json
|
||||
- **Verification:** "status book" sends plain text without buttons
|
||||
- **Committed in:** `22638fd`, `11365b8`
|
||||
|
||||
**3. [Rule 1 - Bug] Batch text commands: wrong field names and action**
|
||||
- **Found during:** Task 3 (runtime verification)
|
||||
- **Issue:** Downstream nodes expected `allMatched` but sub-workflow returned `matchedContainers`. `Route Batch Action` got `action: "batch_matched"` instead of `"stop"`.
|
||||
- **Fix:** Added `Prepare Batch Execution` Code node to transform data
|
||||
- **Files modified:** n8n-workflow.json
|
||||
- **Verification:** "stop plex dup" correctly executes batch stop
|
||||
- **Committed in:** `cccf455`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 3 auto-fixed (3 bugs)
|
||||
**Impact on plan:** All bugs were data flow mismatches caused by the sub-workflow returning different field names/values than what downstream nodes expected. The matching logic itself worked correctly. Node count is 168 instead of planned 165 due to 3 additional fix nodes (Has Status Message ID, Strip Status Keyboard, Prepare Batch Execution).
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None beyond the deviations above — all resolved during runtime verification.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None — deployed via n8n API during execution.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Matching sub-workflow created and deployed (7th sub-workflow)
|
||||
- All 4 viable extraction domains complete
|
||||
- Ready for plan 10.1-07: Code node classification and contract documentation
|
||||
|
||||
---
|
||||
*Phase: 10.1-aggressive-workflow-modularization*
|
||||
*Completed: 2026-02-08*
|
||||
Reference in New Issue
Block a user