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

docs: land automation macro execution plan

Browse Source
This commit is contained in:
rogee
2026-06-05 08:50:36 +08:00
parent 20941b9f2d
commit 04be5e4e4e
1 changed files with 39 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md
+39 -4
View File
@@ -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.