rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: land parity tracking handoff

Browse Source
This commit is contained in:
rogee
2026-06-07 10:27:56 +08:00
parent 168f12070e
commit f46bce7528
1 changed files with 10 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md
+10 -6
View File
@@ -49,12 +49,12 @@ Hermes task landing checklist:
## Current Baseline
- Current tracking checkpoint: 2026-06-07 P3.91 upload and macro attachment parity, prepared as `feat(macros): align attachment uploads`.
- Latest implementation checkpoint: this checkpoint, prepared as `feat(macros): align attachment uploads`.
- Latest documentation/tooling checkpoint: this tracker update records Chatwoot account upload and macro attachment parity. No route artifacts change.
- Current tracking checkpoint: 2026-06-07 P3.91 upload and macro attachment parity, committed as `168f120 feat(macros): align attachment uploads`.
- Latest implementation checkpoint: `168f120 feat(macros): align attachment uploads`.
- Latest documentation/tooling checkpoint: this tracker update records the committed baseline, the user-confirmed scope, and P3.92 automation-rule attachment parity as the next executable drift slice. No route artifacts change.
- Plan landing status: complete for the current known Hermes plans and user-confirmed scope. Future work should update this file directly instead of opening a parallel tracker.
- Worktree status at this implementation checkpoint: account upload now matches the reused Chatwoot helper by accepting multipart `attachment` and JSON `external_url`, returning raw `{ file_url, blob_id, blob_key }` without the local success/data envelope, and macro `send_attachment` actions now validate uploaded blob IDs, serialize `files`, and create outgoing attachment messages during macro execution. This retains P3.90 SearchAPI filter-surface parity, P3.89 fixed page size, P3.88 global result type scoping, P3.87 article payloads, P3.86 message payloads, P3.85 conversation payloads, P3.84 agent-sender filter parity, and prior checkpoints. Live API/browser/enterprise smoke still needs the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack.
- Next executable implementation checkpoint: continue Phase 2/3 drift audit for the next reused-frontend mismatch, or run B12 live smoke when the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack is available. Re-run Phase 6 placeholder audit after future route/smoke changes.
- Next executable implementation checkpoint: P3.92 automation-rule attachment parity, found by the Phase 2/3 drift audit after P3.91. The slice must align `AutomationRulesController` with Chatwoot `AttachmentConcern`: validate `send_attachment` upload blobs, normalize action params, serialize `files`, preserve actions when update omits them, and prove execution creates outgoing attachment messages. Run B12 live smoke when the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack is available. Re-run Phase 6 placeholder audit after future route/smoke changes.
- `go test ./...` passes when run outside the restricted socket sandbox for the latest implementation baseline; the latest docs/tooling checkpoint verified `scripts/parity_frontend_smoke.sh --check` with workspace-local temp/cache dirs after `/tmp` was full.
- Route dump succeeds with `967` registered routes after profile MFA route tracking.
- Route parity artifacts now exist under `docs/parity/` and are generated by `cmd/route_parity`.
@@ -96,7 +96,7 @@ Next ordered checkpoints:
| Order | Slice | Required outcome | Primary verification |
| --- | --- | --- | --- |
| 1 | Phase 2/3 audit pass | Route/controller/serializer drift found by B12 or new reference inspection is captured as named slices, not free-form TODOs. | Regenerated route parity artifacts and fixture-backed serializer tests. |
| 1 | P3.92 automation-rule attachment parity | Close the current drift between Chatwoot automation rules and GoChat for `send_attachment` uploads, serialized files, and update semantics. | Focused automation handler/service/action tests, full `go test ./...`, and `git diff --check`. |
| 2 | Phase 6 placeholder burn-down | Remaining account/contact/conversation/message/inbox placeholder handlers are either real Chatwoot-compatible flows or explicitly tracked as unsupported reference gaps. | `rg` placeholder audit, route smoke, and endpoint-family tests. |
| 3 | B12 optional live smoke | Run the checked smoke harness in a full PostgreSQL/Redis/Meilisearch/Vite/Chrome environment and turn failures into named slices. | `docs/parity/frontend_smoke_report.md` pass/fail entries linked to owners. |
@@ -104,7 +104,7 @@ Execution queue for the next agent turn:
| Order | Slice ID | Why now | Required commit contents |
| --- | --- | --- | --- |
| 1 | Phase 2/3 drift audit | Route parity is currently green for the tracked set, but only fresh reference/frontend inspection proves the next missing reused-frontend path. | Named drift rows with inspected reference files, fixture tests where behavior is known, regenerated route artifacts if the route set changes. |
| 1 | P3.92 automation-rule attachment parity | P3.91 closed the shared upload/macro side, and fresh reference inspection shows automation rules use the same `AttachmentConcern` contract. | Code/tests/docs for automation `send_attachment` upload validation, `files` serialization, omitted-action update preservation, and attachment-message execution. |
| 2 | B12 live smoke | The harness is checked in; live pass/fail still needs the full PostgreSQL/Redis/Meilisearch/Vite/Chrome stack. | Updated smoke report with command, environment, failures, and linked owner rows. |
| Guard | Phase 6 placeholder audit | Current audit is clean for reused-frontend critical handlers; re-run after future route/smoke changes so no frontend-critical stub becomes ownerless. | `rg` audit result, either a burn-down implementation or explicit non-frontend fallback classification, focused tests if code changes. |
@@ -156,6 +156,7 @@ This table is the shortest authoritative handoff view. If an older lower section
| Priority | Workstream | Current state | Next checkpoint | Commit close rule |
| --- | --- | --- | --- | --- |
| 0 | P3.92 automation-rule attachment parity | Todo from fresh Phase 2/3 drift audit. Chatwoot automation rules include `AttachmentConcern`, `has_many_attached :files`, `send_attachment` action validation, signed/upload blob normalization, and `files` serialization; GoChat currently has macro-side parity but automation rules still need the same contract. | Implement create/update attachment validation and action normalization, serialize automation `files`, preserve existing actions when update omits `actions`, reject invalid blobs with raw `422`, and prove rule execution creates outgoing attachment messages through the existing action service. | Focused AutomationRuleHandler, AutomationRuleService, and ActionService tests must pass; full `go test ./...` must pass outside the restricted socket sandbox; `git diff --check` must pass. No route artifacts change unless automation routes are touched. |
| 0 | P3.91 upload and macro attachment parity | Implemented for reused `uploadHelper` and macro settings flows: account upload accepts Chatwoot `attachment` multipart fields plus `external_url` JSON bodies, returns raw blob payloads consumed by the frontend, and macro `send_attachment` actions resolve those blob IDs into `files` payload entries and executable attachment messages. | Keep in Review; reopen from macro/automation attachment smoke, external fetch edge cases, or fresh reference evidence for ActiveStorage signed-id semantics not covered by the current direct-upload bridge. | Focused UploadHandler, MacroHandler, MacroService, and macro execution tests passed, including the external-url test outside the restricted socket sandbox; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
| 0 | P3.90 SearchAPI filter-surface parity | Implemented for reused SearchAPI endpoints: only Chatwoot-supported search filters are allowed through. `since/until` date filters remain available across result families when advanced search is enabled; `from` and `inbox_id` are preserved only for message search; unsupported local filters are stripped before DB fallback and Meilisearch execution. Global search applies message-only filters only to message results, so conversations/contacts/articles are not narrowed by message inbox or sender filters. | Keep in Review; reopen from B12 advanced-search smoke or fresh reference evidence for new upstream filter params, Searchkick advanced-search extensions, or endpoint-specific filter drift. | Focused SearchHandler, SearchService, and Meilisearch filter-surface tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
| 0 | P3.89 SearchAPI fixed page-size parity | Implemented for reused SearchAPI endpoints: GoChat now ignores local `per_page` query params and forces Chatwoot's fixed `.per(15)` page size for global, conversation, message, contact, and article search before DB fallback or Meilisearch execution. | Keep in Review; reopen from B12 search smoke or fresh reference evidence for endpoint-specific pagination changes, Kaminari default drift, or frontend callers adding explicit per-page support upstream. | Focused SearchHandler pagination tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
@@ -255,6 +256,7 @@ These rows are the executable development plan from this point forward. A checkp
| ID | Owner files | Reference files | Work to land | Exit gate |
| --- | --- | --- | --- | --- |
| P3.92 automation-rule attachment parity | `internal/handler/api/v1/automation_rule_handler.go`, `internal/automation/service.go`, `internal/automation/model.go`, `internal/automation/action_service.go`, automation rule handler/service/action tests | `reference/chatwoot/app/controllers/api/v1/accounts/automation_rules_controller.rb`, `reference/chatwoot/app/controllers/concerns/attachment_concern.rb`, `reference/chatwoot/app/models/automation_rule.rb`, `reference/chatwoot/app/views/api/v1/accounts/automation_rules/partials/_automation_rule.json.jbuilder`, `reference/chatwoot/app/javascript/dashboard/store/modules/automations.js`, `reference/chatwoot/app/javascript/dashboard/routes/dashboard/settings/automation/AutomationRuleForm.vue` | Automations must share the Chatwoot attachment contract already implemented for uploads/macros: create/update validate `send_attachment` blobs, normalize signed upload UUIDs or numeric blob IDs to stored upload IDs in `action_params`, serialize rule `files` with `id`, `automation_rule_id`, `file_type`, `account_id`, `file_url`, `blob_id`, and `filename`, preserve existing actions when update omits `actions`, and let execution create outgoing attachment messages with persisted attachment rows. | Close with focused tests for create normalization/files serialization, invalid blob `422`, omitted-action update preservation, and execution attachment side effects; full `go test ./...` must pass outside the restricted socket sandbox; `git diff --check` must pass. No route artifacts change unless automation routes are modified. |
| P3.91 upload and macro attachment parity | `internal/handler/api/v1/upload_handler.go`, `internal/service/upload_service.go`, `internal/handler/api/v1/macro_handler.go`, `internal/automation/macro_service.go`, `internal/automation/action_service.go`, upload/macro tests | `reference/chatwoot/app/controllers/api/v1/accounts/upload_controller.rb`, `reference/chatwoot/app/controllers/concerns/attachment_concern.rb`, `reference/chatwoot/app/controllers/api/v1/accounts/macros_controller.rb`, `reference/chatwoot/app/models/macro.rb`, `reference/chatwoot/app/services/macros/execution_service.rb`, `reference/chatwoot/app/javascript/dashboard/helper/uploadHelper.js`, macro settings helper/components | Account upload now follows Chatwoot's reused frontend helper contract: multipart field `attachment`, JSON `external_url`, raw `file_url/blob_id/blob_key` response. Macro create/update validates `send_attachment` blob IDs, normalizes signed upload UUIDs to stored blob IDs, serializes `files` with `blob_id`, `filename`, `file_url`, and macro execution creates outgoing messages with persisted attachment rows. | Review by `feat(macros): align attachment uploads`; focused tests prove upload helper payloads, invalid attachment rejection, macro file serialization, durable/synchronous macro execution, and attachment message creation; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
| P3.90 SearchAPI filter-surface parity | `internal/handler/api/v1/search_handler.go`, `internal/search/search_service.go`, `internal/search/engine_meili.go`, SearchHandler/SearchService/Meilisearch tests | `reference/chatwoot/app/services/search_service.rb`, `reference/chatwoot/app/controllers/api/v1/accounts/search_controller.rb`, `reference/chatwoot/app/javascript/dashboard/api/search.js`, `reference/chatwoot/app/javascript/dashboard/modules/search/components/SearchView.vue`, `reference/chatwoot/app/javascript/dashboard/modules/search/helpers/searchHelper.js` | SearchAPI filters now match the reused dashboard/reference surface: `since/until` are retained as advanced date filters; `from` and `inbox_id` are retained for message search only; local filters not present in Chatwoot `SearchService` (`status`, `priority`, `labels`, `assignee_id`, `team_id`, `message_type`, `content_type`, `private`, `contact_source`, `portal_id`, `article_status`, `locale`) are stripped by the handler. Global search applies message-only filters only to message results, including Meilisearch multi-type searches. | Review by `fix(search): align search filters`; focused tests prove conversation endpoints strip unsupported filters, message endpoints keep only `from/inbox_id`, global service filters per result type, and Meilisearch applies explicit inbox only to messages; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
| P3.89 SearchAPI fixed page-size parity | `internal/handler/api/v1/search_handler.go`, `internal/handler/api/v1/search_handler_test.go` | `reference/chatwoot/app/services/search_service.rb`, `reference/chatwoot/app/controllers/api/v1/accounts/search_controller.rb`, `reference/chatwoot/app/javascript/dashboard/api/search.js` | SearchAPI handlers now match Chatwoot `SearchService` pagination by forcing `PerPage = 15` for global, conversation, message, contact, and article search regardless of local `per_page` query params. This keeps DB fallback and Meilisearch searches on the same fixed page-size contract used by every `page(params[:page]).per(15)` branch in the reference. | Review by `fix(search): align search page size`; focused SearchHandler tests prove explicit `per_page` on global/message search is ignored and the backend filter remains `15`; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
@@ -370,6 +372,7 @@ This ledger records the committed parity checkpoints that future slices should b
| Commit | Scope | Verification summary | Follow-up state |
| --- | --- | --- | --- |
| `docs: land parity tracking handoff` | Documentation-only checkpoint after `168f120 feat(macros): align attachment uploads`. Records the committed baseline SHA, keeps user-confirmed scope and Hermes plan landing rules in this active tracker, and promotes P3.92 automation-rule attachment parity from audit evidence into the next executable slice. | `git diff --check`; no Go code or route artifacts changed. | Start P3.92 automation-rule attachment parity, then continue Phase 2/3 drift audit or B12 live smoke when the full stack is available. |
| `feat(macros): align attachment uploads` | Advances P3.91 with Chatwoot account upload and macro attachment parity. Account upload now accepts the frontend `attachment` form key and `external_url` JSON body, returns raw blob fields, and macro attachment actions validate/normalize those blob IDs, expose Chatwoot-style `files`, and create outgoing attachment messages during execution. | Focused UploadHandler/MacroHandler/MacroService tests passed, including the external-url upload test outside the restricted socket sandbox; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P3.91 to Review; continue Phase 2/3 drift audit, B9.4 automation attachment depth if fresh smoke exposes it, Phase 6 placeholder audit, or B12 live smoke. |
| `fix(search): align search filters` | Advances P3.90 with Chatwoot SearchAPI filter-surface parity. Search handlers now strip unsupported local filter params, retain only date filters plus message-only `from/inbox_id`, and global search applies those message-only filters only to message results in both DB fallback and Meilisearch paths. | `go test ./internal/handler/api/v1 ./internal/search -run 'TestSearchHandler_Search(Conversations_IgnoresUnsupportedSearchFilters\|Messages_KeepsOnlyReferenceAdvancedFilters)\|TestGlobalSearch_AppliesReferenceFiltersPerResultType\|TestMeiliSearchEngine_SearchAppliesExplicitInboxOnlyToMessages' -count=1` passed with workspace-local temp/cache dirs; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P3.90 to Review; continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke. |
| `fix(search): align search page size` | Advances P3.89 with Chatwoot SearchAPI pagination parity. Global/entity search handlers now force the backend filter to the reference fixed page size of `15` and ignore local `per_page` query params before DB fallback or Meilisearch execution, matching every `page(params[:page]).per(15)` branch in `SearchService`. | `go test ./internal/handler/api/v1 -run 'TestSearchHandler_(GlobalSearch_WithFilterParams\|SearchMessages_Success)' -count=1` passed with workspace-local temp/cache dirs; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P3.89 to Review; continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke. |
@@ -2744,3 +2747,4 @@ Verification milestone gates:
- 2026-06-07: P3.89 SearchAPI fixed page-size checkpoint prepared as `fix(search): align search page size`; audited Chatwoot `SearchService` pagination branches, `SearchController`, and reused dashboard `SearchAPI` callers. GoChat SearchAPI handlers now ignore local `per_page` query params and force the backend filter to Chatwoot's fixed `.per(15)` page size for global, conversation, message, contact, and article searches before DB fallback or Meilisearch execution. Focused SearchHandler pagination tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.
- 2026-06-07: P3.90 SearchAPI filter-surface checkpoint prepared as `fix(search): align search filters`; audited Chatwoot `SearchService`, `SearchController`, reused dashboard `SearchAPI`, `SearchView.vue`, and search helper URL param generation. GoChat SearchAPI handlers now strip unsupported local filter params, retain `since/until` date filters, keep `from/inbox_id` only for message search, and make global search apply message-only filters only to message results across DB fallback and Meilisearch execution. Focused SearchHandler/SearchService/Meilisearch tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.
- 2026-06-07: P3.91 upload and macro attachment checkpoint prepared as `feat(macros): align attachment uploads`; audited Chatwoot `UploadController`, `AttachmentConcern`, `MacrosController`, `Macro#file_base_data`, `Macros::ExecutionService#send_attachment`, and reused dashboard `uploadHelper` plus macro attachment helpers. GoChat account upload now accepts `attachment` multipart fields and `external_url` JSON, returns raw `file_url/blob_id/blob_key`, normalizes macro `send_attachment` actions from upload UUIDs to stored blob IDs, serializes macro `files`, rejects invalid blobs with raw `422`, and creates outgoing attachment messages from macro execution. Focused UploadHandler/MacroHandler/MacroService tests passed, including external-url upload outside the restricted socket sandbox; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.
- 2026-06-07: Documentation checkpoint prepared as `docs: land parity tracking handoff`; confirms `168f120 feat(macros): align attachment uploads` is committed, records the user-confirmed scope and Hermes plan landing rules in this active tracker, and opens P3.92 automation-rule attachment parity as the next executable slice from fresh Chatwoot `AutomationRulesController`, `AttachmentConcern`, automation model/Jbuilder, and reused automation frontend inspection. Verification for this docs-only checkpoint: `git diff --check`; no Go code or route artifacts changed.