From 04be5e4e4e8a381535ab4d0783b3f467b5e55017 Mon Sep 17 00:00:00 2001 From: Rogee Date: Fri, 5 Jun 2026 08:48:09 +0800 Subject: [PATCH] docs: land automation macro execution plan --- docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md | 43 +++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md index 9467958b..e3942a9c 100644 --- a/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md +++ b/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md @@ -17,8 +17,8 @@ Build GoChat as a Go backend that can directly reuse the frontend from `referenc ## Current Baseline - Latest implementation checkpoint: `b36cf07 feat(csat): align report download csv`. -- Latest documentation checkpoint before this update: `5c771d8 docs: record csat public send checkpoint`. -- Worktree status at this planning checkpoint: clean after `b36cf07`; next active slice is B9 automation and macro side-effect parity. +- Latest documentation checkpoint: this checkpoint, `docs: land automation macro execution plan`. +- Worktree status at this planning checkpoint: clean after `20941b9`; next active slice is B9.1a automation-rule CRUD payload and validation parity. - `go test ./...` passes. - Route dump succeeds with `TOTAL: 830` after adding the Chatwoot-compatible applied-SLA index route. - Route parity artifacts now exist under `docs/parity/` and are generated by `cmd/route_parity`. @@ -134,12 +134,14 @@ This ledger records the committed parity checkpoints that future slices should b | `ef3a909 feat(csat): send surveys on resolved conversations` | Advanced B8 public/send parity: public CSAT update now accepts the reused survey frontend's object-shaped `message.submitted_values`, keeps one message-linked CSAT response per `input_csat` message across repeated submissions, and still enforces the 14-day message-date lock. The resolve listener now loads the resolved conversation, checks inbox CSAT enablement and survey label rules, creates one Chatwoot-style `input_csat` template message with inbox CSAT content/display type, and no longer creates pending rating-0 responses before customer submission. Message-updated events also build CSAT responses from `submitted_values` when present. | `go test ./internal/automation -run 'CsatSurveyListener\|CsatSurveyService' -count=1`; `go test ./internal/handler/api/v1 -run CsatSurvey -count=1`; `go test ./internal/handler/widget -run 'CSAT\|Csat\|PublicInbox' -count=1`; `go test ./internal/service -run Widget -count=1`; `go test ./internal/automation -count=1`; `go test ./internal/handler/api/v1 -count=1`; `go test ./...`; `git diff --check`. No route changes; route dump remains `TOTAL: 830`. | Continue B8.4 CSAT download CSV parity and then review channel-specific WhatsApp/Twilio template send hooks as broader integration work. | | `5c771d8 docs: record csat public send checkpoint` | Recorded the B8.2/B8.3 public CSAT and resolve-send checkpoint, made B8.4 the next active task, and kept external WhatsApp/Twilio template delivery as a named Phase 5 integration follow-up. | Documentation-only checkpoint after `ef3a909`; `git diff --check` passed before commit. | Continue B8.4 CSAT download CSV parity. | | `b36cf07 feat(csat): align report download csv` | Completed B8.4 CSAT CSV download parity for the reused reports screen: `/csat_survey_responses/download` now writes real CSV via `encoding/csv`, uses Chatwoot's report headers, includes enterprise review notes, emits absolute conversation links using conversation display IDs, appends the reporting-period row, and applies the same account/date/agent/inbox/team/rating filters as list/metrics. | `go test ./internal/handler/api/v1 -run CsatSurvey -count=1`; `go test ./internal/handler/api/v1 -count=1`; `go test ./internal/automation -count=1`; `go test ./...`; `git diff --check`. No route changes; route dump remains `TOTAL: 830`. | B8 moves to Review. Continue B9 automation and macro side-effect parity. | +| `20941b9 docs: record csat download checkpoint` | Recorded the B8.4 CSAT download checkpoint and moved the active queue to B9 automation/macro side-effect parity. | Documentation-only checkpoint; no route changes. | Continue B9.1a automation-rule CRUD request/response and validation parity. | +| `docs: land automation macro execution plan` | Landed the B9 execution contract into this tracker before code changes: Chatwoot automation-rule controller/frontend contracts, current Go handler/service gaps, B9.1a implementation checklist, focused verification commands, and commit/documentation rules. | Documentation-only checkpoint; `git diff --check` passed before commit. | Start B9.1a implementation. | ## Next Slice Contract Completed implementation slice: B5.1-B5.5 now cover inbox serializer shape, Chatwoot frontend create/update binding, working-hours persistence, out-of-office behavior, inbox member assignment payload/mutation semantics, channel-specific config depth, AgentCapacityPolicy/InboxCapacityLimit API data contracts, and dedicated Email/Twilio/LINE channel route response shapes. B6 is now in Review after `a16c23c` and `f08c743`: Chatwoot search response envelopes, frontend query params, Meilisearch sender filters, mocked hit serialization, env-gated live Meilisearch validation, release-mode DB fallback rejection, and reindex Meilisearch-only guard are covered. B7 is now in Review after `a98dc2c`, `95224fa`, `a11bb96`, `213bf2b`, `4f85ef1`, and `d23f3f0`, enforcing per-inbox capacity limits, aligning SLA policy CRUD payloads, persisting applied SLA records, making core FRT/NRT/RT breach events idempotent, aligning the applied-SLA reports API, and creating SLA miss notifications. B3 and B4 remain in review for deeper side effects and browser validation. -Next implementation slice: start B9 automation and macro side-effect parity. +Next implementation slice: start B9.1a automation-rule CRUD request/response and validation parity; do not expand action side effects until CRUD contracts are frontend-compatible. | Step | Required result | Reference source | Verification | | --- | --- | --- | --- | @@ -152,7 +154,8 @@ Next implementation slice: start B9 automation and macro side-effect parity. | N7 | Keep applied-SLA report/list payload parity as the current SLA reports baseline. | `reference/chatwoot/enterprise/app/controllers/api/v1/accounts/applied_slas_controller.rb`, applied-SLA index/metrics/download views, dashboard SLA reports client. | Done by `4f85ef1`; account-side applied-SLA list/report filters return frontend-compatible payloads and metrics/download shapes. | | N8 | Keep B7.6 SLA notification and timing review as current SLA closeout baseline. | `Sla::EvaluateAppliedSlaService`, `SlaEvent#create_notifications`, SLA processing jobs. | Done by `d23f3f0`; SLA miss notifications fan out to participants/admins/assignee, repeated evaluation is idempotent, and current reference timing for `only_during_business_hours` is covered. | | N9 | Keep B8 CSAT account/public/send/download parity as the current CSAT baseline. | `CsatSurveyResponsesController`, public CSAT controller/views, `CsatSurveyService`, `CsatSurveyListener`, dashboard reports and survey frontend clients. | Done by `f441680`, `ef3a909`, and `b36cf07`; list/metrics/review-note payloads, public object-shaped submission, lock window, response idempotency, resolve-triggered message send, and CSV download are covered. | -| N10 | Update this tracker after every implementation checkpoint. | This document. | `git diff --check`; `go test ./...` for Go changes. | +| N10 | Land B9.1a automation-rule controller/frontend contracts before implementation. | Chatwoot automation controller, Jbuilder views, dashboard automation API/store/helper files, current Go handler/service/validator. | Done by `docs: land automation macro execution plan`; reference contracts, Go gaps, implementation checklist, and exit commands are tracked below. | +| N11 | Update this tracker after every implementation checkpoint. | This document. | `git diff --check`; `go test ./...` for Go changes. | Current B2 profile checkpoint: @@ -408,6 +411,37 @@ B9 automation and macro execution breakdown: | B9.2a | Align macro CRUD payloads, visibility rules, and validation. | Chatwoot macros controller/model and dashboard macro client. | Handler tests for raw macro payloads, ownership, account scoping, and delete status. | Todo | | B9.2b | Execute macro actions against real conversations: labels, status, priority, assignee, team, custom attributes, private notes, and attachments where supported. | Chatwoot macro execution service and conversation/message controllers. | Macro execute tests reload conversation/message rows and assert Chatwoot-shaped response payloads. | Todo | +B9.1a automation-rule landing contract: + +| Area | Reference contract | Current Go gap | Landing requirement | +| --- | --- | --- | --- | +| Reference files | `reference/chatwoot/app/controllers/api/v1/accounts/automation_rules_controller.rb`; automation rule Jbuilder views; `reference/chatwoot/app/javascript/dashboard/api/automation.js`; dashboard automation store and helpers. | Current Go code was built around local envelopes and local condition names. | Inspect these reference files before code changes and keep any new behavior tied to their request/response shapes. | +| List/show/create/update envelopes | Chatwoot `index` returns `{ payload: [...] }`; `show`, `update`, and `clone` return `{ payload: rule }`; `create` returns the raw rule object; `destroy` returns empty `200 OK`. | `automation_rule_handler.go` currently returns local `{ success, data }`, `{ automation_rules, meta }`, or delete JSON. | Add a Chatwoot serializer/binder boundary and update handler tests to assert the exact envelopes and empty delete body. | +| Rule serializer | Jbuilder emits `id`, `account_id`, `name`, `description`, `event_name`, `conditions`, `actions`, Unix `created_on`, `active`, and optional `files`. | Go currently exposes internal model JSON and timestamp names. | Serialize only Chatwoot fields for frontend routes; preserve internal structs behind the handler/service boundary. | +| Conditions | Frontend sends `conditions[].attribute_key`, `filter_operator`, `query_operator`, optional `custom_attribute_type`, and `values`; common operators include Chatwoot names such as `equal_to`. | Go `Condition` uses `attribute`; validator mainly expects local operator names such as `equal`. | Accept `attribute_key`, normalize aliases for execution, and respond with `attribute_key` plus Chatwoot operator names where the frontend expects them. | +| Actions | Frontend sends `actions[].action_name` and `action_params`, often as arrays. | Go `ActionParams` is map-oriented in several paths; direct binding can fail for array params. | Add request DTO/custom normalization that accepts Chatwoot array params without breaking existing map-based action execution. | +| Update scoping | Chatwoot updates an existing account-scoped rule through permitted fields. | Current update path can save a payload with zero `account_id` if the client omits it. | Load the existing account-scoped rule first, apply permitted fields, and keep `account_id`/ID ownership intact. | +| Clone/delete scoping | Chatwoot fetches rules within account context and clone response uses the clone view. | Go clone/delete need account-scope and not-found checks reviewed. | Enforce account scope for clone/delete and match clone response shape; delete returns empty `200 OK`. | + +B9.1a implementation checklist: + +- Add handler-level DTOs for Chatwoot automation-rule requests instead of binding frontend JSON directly into persistence models. +- Add serializer helpers for automation rules, conditions, and actions with Chatwoot field names and Unix `created_on`. +- Keep backward-compatible service/model normalization so existing automation tests that construct local `Condition{Attribute: ...}` and map action params still pass. +- Update or replace handler tests that currently assert local envelopes. +- Do not begin B9.1b side-effect expansion until B9.1a CRUD contracts pass focused tests and this document records the checkpoint. + +B9.1a exit commands: + +```bash +env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./internal/handler/api/v1 -run AutomationRule -count=1 +env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./internal/automation -run 'AutomationRule|Condition|Action' -count=1 +env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./internal/handler/api/v1 -count=1 +env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./internal/automation -count=1 +env GOCACHE=/tmp/gochat-gocache GOMODCACHE=/tmp/gochat-gomodcache go test ./... +git diff --check +``` + B10 admin and limits breakdown: | Step | Implementation target | Reference source | Required tests | Status | @@ -1050,3 +1084,4 @@ Verification milestone gates: - 2026-06-05: B8 account-side CSAT checkpoint committed as `f441680 feat(csat): align account report payloads`; CSAT report list now returns the raw Chatwoot response array with nested contact, assigned agent, reviewer, display conversation ID, Unix timestamps, and message ID. Filters now cover frontend `since/until`, `user_ids`, `inbox_id`, `team_id`, and `rating`; metrics returns `total_count`, `ratings_count`, and `total_sent_messages_count`; update/review-note actions return the Chatwoot CSAT serializer. Focused CSAT handler/service tests, handler and automation package tests, full `go test ./...`, and `git diff --check` passed. Next B8 checkpoint is public CSAT submit/update and resolve-triggered send parity. - 2026-06-05: B8 public/send CSAT checkpoint committed as `ef3a909 feat(csat): send surveys on resolved conversations`; public CSAT update now accepts object-shaped `message.submitted_values`, repeated submissions update the same message-linked response, and the 14-day lock still follows the survey message creation date. The resolve listener now creates one `input_csat` template message only when the resolved conversation's inbox has CSAT enabled and survey rules allow it, skips duplicates, and no longer creates pending rating-0 responses. Message-updated events build responses from submitted CSAT values. Focused CSAT listener/service/handler/widget tests, automation and API handler package tests, full `go test ./...`, and `git diff --check` passed. Next B8 checkpoint is CSAT download CSV parity. - 2026-06-05: B8 CSAT download checkpoint committed as `b36cf07 feat(csat): align report download csv`; CSAT report downloads now match Chatwoot CSV headers, filters, absolute conversation links by display ID, enterprise review notes, and the final reporting-period row. Focused CSAT handler tests, handler and automation package tests, full `go test ./...`, and `git diff --check` passed. B8 moves to Review; next slice is B9 automation and macro side-effect parity. +- 2026-06-05: B9 planning checkpoint committed as `docs: land automation macro execution plan`; B9.1a now has an explicit Chatwoot automation-rule controller/frontend contract, current Go gap table, implementation checklist, and focused exit commands before automation/macro code changes begin.